添加mcp功能 - #2296
Open
toarujs wants to merge 7 commits into
Open
Conversation
Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com> Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com> Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
AnAndroNerd
reviewed
Aug 7, 2026
Comment on lines
+1
to
+329
| # 音频理解驱动的工程编辑工作流 | ||
|
|
||
| ## 1. 目标 | ||
|
|
||
| 构建一个独立的音频理解工作流，使 AI 基于可追溯的音频分析证据编辑歌声工程文件。 | ||
|
|
||
| 工作流面向已有工程文件和对应人声录音。用户提供或校对歌词，系统输出音符、音素、音高、响度和时间边界的结构化分析结果。AI 根据分析结果与工程状态生成可审核的修改计划，再通过工程编辑工具应用变更。 | ||
|
|
||
| ## 2. 核心原则 | ||
|
|
||
| - 音频分析器、AI 决策器与工程编辑器保持独立。 | ||
| - 用户校对的歌词作为强制对齐的权威文本。 | ||
| - 每条建议携带时间范围、置信度、分析来源与原始证据。 | ||
| - AI 生成修改计划，编辑工具执行明确的工程变更。 | ||
| - 低置信度区域保留给用户确认，避免自动覆盖已有精细调校。 | ||
| - 所有编辑操作可预览、可确认、可回退。 | ||
|
|
||
| ## 3. 系统边界 | ||
|
|
||
| ```text | ||
| 用户歌词 + 人声录音 + 工程文件 | ||
| | | ||
| v | ||
| 外部音频分析服务 | ||
| | | ||
| v | ||
| 结构化音频证据 JSON | ||
| | | ||
| v | ||
| AI 编辑代理 | ||
| | | ||
| v | ||
| 工程修改计划 | ||
| | | ||
| v | ||
| 工程编辑工具 | ||
| ``` | ||
|
|
||
| 音频分析服务不依赖目标编辑器的内部实现。工程编辑工具仅负责读取状态、生成修改计划和应用经确认的变更。 | ||
|
|
||
| ## 4. 输入 | ||
|
|
||
| ### 4.1 必需输入 | ||
|
|
||
| - 人声录音，优先使用 WAV、44.1 kHz 或 48 kHz、单声道或可分离人声的立体声。 | ||
| - 工程文件或工程状态快照。 | ||
| - 用户确认的歌词及语言标签。 | ||
|
|
||
| ### 4.2 可选输入 | ||
|
|
||
| - 每句歌词的预期顺序或预期音符范围。 | ||
| - 演唱速度、节拍、调性和参考音高。 | ||
| - 目标歌手、音源或发音词典。 | ||
| - 用户手动标注的句首、换气点和特殊读音。 | ||
|
|
||
| ### 4.3 歌词输入格式 | ||
|
|
||
| 歌词按演唱顺序拆分为可对齐单元。单元粒度应与目标语言和工程编辑粒度一致。 | ||
|
|
||
| ```json | ||
| { | ||
| "language": "ja", | ||
| "units": [ | ||
| { "id": "l001", "text": "ka" }, | ||
| { "id": "l002", "text": "na" }, | ||
| { "id": "l003", "text": "shi" }, | ||
| { "id": "l004", "text": "mi" } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| 中文建议输入分词和拼音候选；日语建议输入假名或明确的罗马音；英语建议输入词语及必要的发音词典覆写。 | ||
|
|
||
| ## 5. 分析管线 | ||
|
|
||
| ### 5.1 音频预处理 | ||
|
|
||
| 1. 统一采样率、声道数和响度参考。 | ||
| 2. 检测削波、长静音、异常噪声和多段录音。 | ||
| 3. 存储原始音频及标准化音频的校验值。 | ||
|
|
||
| ### 5.2 人声分离 | ||
|
|
||
| 使用 Demucs 从包含伴奏的混音中获得人声 stem。独立人声录音可跳过此步骤。 | ||
|
|
||
| 输出应包含分离质量和可能残留伴奏的标记，供后续模型降低置信度。 | ||
|
|
||
| ### 5.3 用户歌词的音素化 | ||
|
|
||
| 依据语言、发音词典与用户覆写，将歌词单元转换为音素序列。 | ||
|
|
||
| ```json | ||
| { | ||
| "lyric_id": "l001", | ||
| "text": "ka", | ||
| "phonemes": ["k", "a"], | ||
| "source": "user-confirmed" | ||
| } | ||
| ``` | ||
|
|
||
| ### 5.4 强制对齐 | ||
|
|
||
| 使用 Montreal Forced Aligner 或基于 wav2vec2 的 CTC 强制对齐器，将已确认的音素序列定位到录音时间轴。 | ||
|
|
||
| 每个音素输出起止时间、置信度和对齐状态。对齐失败或置信度过低时生成待确认项。 | ||
|
|
||
| ### 5.5 连续音高提取 | ||
|
|
||
| 使用 RMVPE 作为高质量离线 F0 提取器，使用 torchcrepe 或 CREPE 作为可选实时分析器。 | ||
|
|
||
| 输出内容包括： | ||
|
|
||
| - 每帧 F0 和置信度。 | ||
| - 有声与无声状态。 | ||
| - 片段中位音高和音高范围。 | ||
| - 颤音候选、滑音候选和突变候选。 | ||
| - 与十二平均律音高中心的 cents 偏差。 | ||
|
|
||
| ### 5.6 节奏、起音与音质特征 | ||
|
|
||
| 使用 Essentia、librosa 或 aubio 提取： | ||
|
|
||
| - 起音和释音时间。 | ||
| - RMS 响度和响度变化。 | ||
| - 静音、呼吸和噪声候选。 | ||
| - 频谱质心、共振峰和音色变化。 | ||
|
|
||
| Praat 或 Parselmouth 可用于需要元音共振峰和发声质量分析的高级模式。 | ||
|
|
||
| ### 5.7 音符候选生成 | ||
|
|
||
| 使用 Basic Pitch 或等价自动转录器生成音符候选。候选音符用于辅助判断，最终修改建议由连续 F0、音素边界和工程上下文共同确定。 | ||
|
|
||
| ## 6. 组件选型 | ||
|
|
||
| | 能力 | 首选组件 | 备选组件 | 输出 | | ||
| | --- | --- | --- | --- | | ||
| | 人声分离 | Demucs | Open-Unmix | 人声 stem、质量标记 | | ||
| | 用户文本对齐 | Montreal Forced Aligner | wav2vec2 CTC aligner | 音素边界、置信度 | | ||
| | 离线音高 | RMVPE | torchcrepe、CREPE | F0、voicing、置信度 | | ||
| | 音符候选 | Basic Pitch | MT3 | MIDI 音符候选 | | ||
| | 音频特征 | Essentia | librosa、aubio | 起音、响度、频谱与事件 | | ||
| | 发声特征 | Praat、Parselmouth | WORLD | 共振峰、音质与声学参数 | | ||
|
|
||
| 组件选择应在项目启动时核对许可证、模型权重许可、目标语言支持、运行平台和硬件要求。 | ||
|
|
||
| ## 7. 统一证据格式 | ||
|
|
||
| 分析器应只输出结构化数据，避免让 AI 依赖不可复核的自然语言描述。 | ||
|
|
||
| ```json | ||
| { | ||
| "schema_version": "1.0", | ||
| "audio": { | ||
| "path": "vocal.wav", | ||
| "duration_seconds": 42.31, | ||
| "sample_rate": 44100, | ||
| "channel_mode": "mono" | ||
| }, | ||
| "segments": [ | ||
| { | ||
| "id": "l001", | ||
| "text": "ka", | ||
| "phonemes": [ | ||
| { "value": "k", "start": 1.242, "end": 1.318, "confidence": 0.88 }, | ||
| { "value": "a", "start": 1.318, "end": 1.968, "confidence": 0.96 } | ||
| ], | ||
| "pitch": { | ||
| "median_hz": 440.2, | ||
| "range_hz": [431.8, 468.4], | ||
| "confidence": 0.95, | ||
| "points": [[1.318, 438.6], [1.500, 440.1], [1.968, 445.7]] | ||
| }, | ||
| "energy": { | ||
| "rms_db": -18.4, | ||
| "onset_seconds": 1.278 | ||
| }, | ||
| "events": ["slur_up"], | ||
| "evidence": ["rmvpe", "mfa", "essentia"] | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| ## 8. AI 编辑决策 | ||
|
|
||
| AI 同时读取工程状态和音频证据，输出修改计划。AI 不直接依赖单一模型结果。 | ||
|
|
||
| ### 8.1 可识别的编辑问题 | ||
|
|
||
| - 工程歌词单元与音频对齐单元的顺序或数量差异。 | ||
| - 音符起止时间与真实元音起止时间的偏差。 | ||
| - 音高中心与录音 F0 的持续偏差。 | ||
| - 滑音、颤音和自然音高漂移与现有曲线的差异。 | ||
| - 辅音长度、元音长度和音素切换位置的差异。 | ||
| - 换气、噪声和静音区对音符布局的影响。 | ||
|
|
||
| ### 8.2 修改计划格式 | ||
|
|
||
| ```json | ||
| { | ||
| "project_id": "project-001", | ||
| "analysis_id": "analysis-001", | ||
| "changes": [ | ||
| { | ||
| "target": "note-12", | ||
| "operation": "set_pitch_center", | ||
| "from": "A4", | ||
| "to": "G#4", | ||
| "reason": "F0 median is 94 cents below the current note", | ||
| "confidence": 0.93, | ||
| "evidence_segment_ids": ["l001"], | ||
| "requires_confirmation": true | ||
| }, | ||
| { | ||
| "target": "note-13", | ||
| "operation": "set_start_time", | ||
| "offset_ms": 86, | ||
| "reason": "Aligned vowel onset occurs later than the note start", | ||
| "confidence": 0.89, | ||
| "evidence_segment_ids": ["l002"], | ||
| "requires_confirmation": true | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| ### 8.3 自动应用策略 | ||
|
|
||
| - 置信度阈值、影响范围和可写字段由项目配置定义。 | ||
| - 影响音高、歌词、时值或音素边界的修改默认需要确认。 | ||
| - 仅调整辅助标记或生成预览的数据可采用较低阈值。 | ||
| - 每次应用前保存工程快照，并记录分析版本与计划版本。 | ||
|
|
||
| ## 9. 面向 AI 的工具接口 | ||
|
|
||
| AI 应通过工具读取有限范围的数据，避免在长音频和大型工程中丢失上下文。 | ||
|
|
||
| | 工具 | 用途 | | ||
| | --- | --- | | ||
| | `analyze_audio` | 创建或读取音频分析任务 | | ||
| | `get_audio_region` | 获取指定时间段的音素、F0、响度与事件 | | ||
| | `get_alignment_report` | 获取歌词单元和音素边界 | | ||
| | `get_project_region` | 获取对应时间段的工程音符和参数 | | ||
| | `compare_audio_project` | 生成证据驱动的差异报告 | | ||
| | `create_edit_plan` | 将建议固化为可审核计划 | | ||
| | `apply_edit_plan` | 应用经确认的计划 | | ||
| | `rollback_edit_plan` | 回退指定计划 | | ||
|
|
||
| ## 10. 置信度与人工校对 | ||
|
|
||
| ### 高置信度 | ||
|
|
||
| 典型条件：清晰独唱、人声分离质量高、用户歌词完整、音素对齐稳定、F0 连续。 | ||
|
|
||
| 适合生成较明确的修改建议。 | ||
|
|
||
| ### 中置信度 | ||
|
|
||
| 典型条件：存在滑音、气声、快速咬字、轻度混响或局部伴奏干扰。 | ||
|
|
||
| 适合生成候选修改和可视化证据。 | ||
|
|
||
| ### 低置信度 | ||
|
|
||
| 典型条件：歌词与录音不一致、发音词典缺失、强混响、多人声、极端唱法或长无声段。 | ||
|
|
||
| 系统应标记原因并请求用户确认歌词、发音或时间范围。 | ||
|
|
||
| ## 11. 分阶段实施 | ||
|
|
||
| ### 阶段 1：可验证的音频证据 | ||
|
|
||
| 1. 接收 WAV 和用户校对歌词。 | ||
| 2. 集成 RMVPE，导出 F0 与置信度。 | ||
| 3. 集成一种强制对齐器，导出音素边界。 | ||
| 4. 定义并持久化统一 JSON schema。 | ||
| 5. 提供指定时间段的查询接口。 | ||
|
|
||
| 验收标准：每个歌词单元均可显示音素边界、F0 曲线和置信度。 | ||
|
|
||
| ### 阶段 2：工程差异与计划 | ||
|
|
||
| 1. 接入工程状态读取工具。 | ||
| 2. 实现音频与工程的时间轴匹配。 | ||
| 3. 输出音高、起止时间和音素边界差异。 | ||
| 4. 生成可审核修改计划。 | ||
|
|
||
| 验收标准：AI 的每条修改建议都关联至少一段结构化音频证据。 | ||
|
|
||
| ### 阶段 3：受控编辑与回退 | ||
|
|
||
| 1. 接入工程编辑工具。 | ||
| 2. 实现确认、应用、快照和回退。 | ||
| 3. 加入置信度阈值、批量范围和操作审计。 | ||
|
|
||
| 验收标准：用户可查看计划、选择变更、应用变更并回退到应用前状态。 | ||
|
|
||
| ### 阶段 4：高级分析 | ||
|
|
||
| 1. 加入 Demucs 人声分离。 | ||
| 2. 加入 Basic Pitch 音符候选。 | ||
| 3. 加入 Essentia 音质、响度和呼吸检测。 | ||
| 4. 加入多语言发音词典和用户覆写。 | ||
|
|
||
| 验收标准：系统能对混音录音、多个语言和复杂唱法生成可解释的候选结果。 | ||
|
|
||
| ## 12. 评估方法 | ||
|
|
||
| - 音素边界：使用人工标注样本计算边界误差。 | ||
| - 音高：使用参考 F0 或人工标注曲线计算 cents 误差。 | ||
| - 音符：计算候选音符与人工工程的 onset、offset 和音高准确率。 | ||
| - 工程编辑：统计用户接受、修改和回退每类建议的比例。 | ||
| - 稳定性：统计分析失败率、低置信度比例和单首歌曲处理时间。 | ||
|
|
||
| ## 13. 风险与缓解 | ||
|
|
||
| | 风险 | 缓解方式 | | ||
| | --- | --- | | ||
| | 伴奏干扰音高和对齐 | 启用人声分离，并将分离质量纳入置信度 | | ||
| | 多语言发音差异 | 语言标签、发音词典、用户覆写和按语言选择对齐模型 | | ||
| | 歌词与演唱不一致 | 允许用户调整歌词单元和对齐锚点后重新分析 | | ||
| | AI 过度修改细节 | 使用修改计划、确认阈值、工程快照和回退 | | ||
| | 长音频上下文过大 | 通过时间窗、分段索引和区域查询提供数据 | | ||
| | 组件许可证差异 | 项目初始化时建立组件、代码和模型权重的许可证清单 | | ||
|
|
||
| ## 14. 第一版建议 | ||
|
|
||
| 第一版使用用户校对歌词、RMVPE、一个强制对齐器和统一 JSON 证据格式。它能够让 AI 基于可验证的音素时间和连续音高编辑工程，形成清晰、可控且可逐步扩展的基础。 |
Author
There was a problem hiding this comment.
很抱歉，在提交时我忘记将整个“.monkeeycode”文件夹排除了，这个文件夹是用来让编辑器识别优化的包含一部分备忘录
Contributor
|
I will say, I think this is better off as a Batch Plugin. They are much more powerful than you would think. |
AnAndroNerd
reviewed
Aug 8, 2026
| "; | ||
| public string RecoveryPath = string.Empty; | ||
| public bool DetachPianoRoll = false; | ||
| public bool DetachPianoRoll = true; |
Author
There was a problem hiding this comment.
这是在调试mcp时为了更好观察编辑器的变化做出的更改，看来是因为我提交的分支有问题，导致这些调试代码和备忘录出现在这里，我正在重新编辑分支，稍后推送
Author
这是因为我尝试过作为独立插件接入openutau，无论是原生插件还是dll注入的方式，都无法解决插件加载异常的问题，所以才通过修改openutau的方式实现mcp功能，尽管改为嵌入的方式，不过mcp功能的框架还是基于之前的插件版本 |
Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
AnAndroNerd
reviewed
Aug 9, 2026
Comment on lines
+2
to
+53
| # OpenUtau MCP | ||
|
|
||
| 此分支将原生 HTTP MCP 集成到 OpenUtau 桌面应用。MCP 服务与应用进程一同运行，面向本机 OpenUtau 实例和本地 MCP 客户端。 | ||
|
|
||
| ## 原生 HTTP MCP | ||
|
|
||
| 实现位于 `OpenUtau.Core/AgentBridge/`，使用 Streamable HTTP、JSON-RPC 2.0 和 Bearer Token。服务仅绑定回环地址，默认端点为 `http://127.0.0.1:43102/mcp`。 | ||
|
|
||
| ### 启动与连接 | ||
|
|
||
| 1. 在 OpenUtau 菜单中打开 `MCP`。 | ||
| 2. 选择 `启动 MCP 服务`。 | ||
| 3. 选择 `复制 MCP 连接配置`，将剪贴板中的 JSON 粘贴到 MCP 客户端配置中。 | ||
|
|
||
| 复制出的配置形如以下示例。Token 由应用生成，示例中的值仅为占位符： | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "openutau": { | ||
| "url": "http://127.0.0.1:43102/mcp", | ||
| "headers": { | ||
| "Authorization": "Bearer <MCP_TOKEN>" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 服务提供 `openutau_read`、`openutau_plan`、`openutau_apply` 和 `openutau_diagnostics`。写入操作先通过 `openutau_plan` 创建短期计划，再由 `openutau_apply` 以 `planId` 确认执行。 | ||
|
|
||
| MCP 菜单还提供状态查看、停止服务、复制 Token 与刷新 Token。Token 在应用重启后保持有效；选择 `刷新 MCP Token` 并确认后，客户端需要粘贴新的连接配置。Token 属于本机凭据，请避免记录到日志、版本库或共享渠道。 | ||
|
|
||
| ### 构建与验证 | ||
|
|
||
| ```bash | ||
| /workspace/.dotnet/dotnet build OpenUtau/OpenUtau.csproj -p:BaseOutputPath=/workspace/openutau-build/ | ||
|
|
||
| /workspace/.dotnet/dotnet test OpenUtau.Test/OpenUtau.Test.csproj --filter "FullyQualifiedName~BridgeProtocolTest" -p:BaseOutputPath=/workspace/openutau-build/ | ||
| ``` | ||
|
|
||
| ### 音频理解工作流 | ||
|
|
||
| 面向 AI 辅助工程编辑的外部音频理解工作流位于 [`.monkeycode/docs/AUDIO_UNDERSTANDING_WORKFLOW.md`](.monkeycode/docs/AUDIO_UNDERSTANDING_WORKFLOW.md)。该设计稿涵盖用户校对歌词、音素强制对齐、连续音高提取、结构化音频证据和可审核的工程修改计划。 | ||
|
|
||
| ### 相关 Bridge 分支 | ||
|
|
||
| `origin/Insert` 分支保留 stdio Bridge 协调器和文件 IPC 方案。此分支专注于应用内原生 HTTP MCP。 | ||
|
|
||
| 原版 OpenUtau 与 MCP 修改版适合采用独立安装目录和独立用户数据目录并行部署。发布脚本应明确配置安装器目录、应用标识与用户数据重定向。 | ||
|
|
||
| ## OpenUtau |
Contributor
There was a problem hiding this comment.
Please remove these changes
Comment on lines
+1
to
+46
| #define AppName "OpenUtau MCP" | ||
| #ifndef AppVersion | ||
| #define AppVersion "0.0.0" | ||
| #endif | ||
| #define AppPublisher "OpenUtau MCP Contributors" | ||
| #define AppExeName "OpenUtau.exe" | ||
|
|
||
| #ifndef SourceDir | ||
| #define SourceDir "..\publish\win-x64" | ||
| #endif | ||
|
|
||
| [Setup] | ||
| AppId={{C1A4602B-0F36-4D8A-B7D8-4733DB0B2638} | ||
| AppName={#AppName} | ||
| AppVersion={#AppVersion} | ||
| AppPublisher={#AppPublisher} | ||
| DefaultDirName={localappdata}\Programs\OpenUtau MCP | ||
| DefaultGroupName={#AppName} | ||
| DisableProgramGroupPage=yes | ||
| OutputBaseFilename=OpenUtau-MCP-Setup | ||
| Compression=lzma2 | ||
| SolidCompression=yes | ||
| ArchitecturesInstallIn64BitMode=x64 | ||
| PrivilegesRequired=lowest | ||
| UninstallDisplayName={#AppName} | ||
|
|
||
| [Files] | ||
| Source: "{#SourceDir}\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs | ||
|
|
||
| [Icons] | ||
| Name: "{autoprograms}\{#AppName}"; Filename: "{app}\{#AppExeName}" | ||
| Name: "{autodesktop}\{#AppName}"; Filename: "{app}\{#AppExeName}"; Tasks: desktopicon | ||
|
|
||
| [Tasks] | ||
| Name: "desktopicon"; Description: "Create a desktop shortcut"; GroupDescription: "Additional shortcuts:" | ||
|
|
||
| [Run] | ||
| Filename: "{app}\{#AppExeName}"; Description: "Launch {#AppName}"; Flags: nowait postinstall skipifsilent | ||
|
|
||
| [Code] | ||
| procedure CurStepChanged(CurStep: TSetupStep); | ||
| begin | ||
| if CurStep = ssPostInstall then begin | ||
| SaveStringToFile(ExpandConstant('{app}\installed-mcp.txt'), 'OpenUtau MCP installation marker' + #13#10, False); | ||
| end; | ||
| end; |
Contributor
|
In my testing, this doesn't seem to work well. Though I'm using only local models, it does seem that you are vibe coding this. I wouldn't recommend that as this requires a lot of care and effort. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
添加mcp功能