N0zoM1z0/vocaloid-mcp

VOCALOID MCP

一个面向智能体的制作桥接工具，用于创作、调校、渲染、混音和审计原生 VOCALOID3/4 项目——纯粹为了好玩而构建。

一段 48 小节的冷启动作曲：工程验收通过，但人耳试听仍发现了音乐上的差距

本仓库让编程智能体能够从空时间轴或创意简报出发，逐步完成：

意图
→ 乐理 / 曲式 / 和声 / 旋律
→ 日文音符分配
→ 原生 IA 交付
→ 编曲
→ 原始 VOCALOID3 Editor 渲染
→ 分离分轨 / 混音 / 母带 / QC
→ VSQX + 哈希绑定的创作记录

它不是 MIDI 转 VSQX 的转换器，也不是一键生成热门歌曲的工具。音符、歌词、音素、音符表情、颤音和 VOCALOID 控制曲线都会编译为原生 VSQ3/VSQ4 结构。获得授权的原版 Editor 仍然是合成权威。

该项目已经证明，智能体可以成为有用的作曲助手、制作工程师和实验伙伴。但它尚未工程化出品味或“完美歌曲”。我们最新的技术上有效的 190 BPM IA_ROCKS 测试仍然收到了诚实的人类评价：人声被伴奏掩盖，结果并不真的像摇滚。

这种区分本身就是一种特性。

实际已被证明的能力

- 从零创建原生 VSQ3/VSQ4 项目，无需复制源项目。
- 使用 Yamaha 的 schema 以及哈希固定的原生 Vsq3.dll 加载器探针进行验证。
- 通过原版 VOCALOID3 Editor 渲染所选的本地授权歌手。
- 在歌手替换和可疑的跨组件探针冲突时故障关闭。
- 编写日文歌词，包含明确的假名读音、手册支持的音素、摩拉分配、休止、拖腔和小 っ 的时值选择。
- 将高层发音、动态、音色、颤音和音高手势编译为原生音符样式和控制曲线。
- 维护带修订的规范歌曲清单，具有稳定 ID、试运行、有界编辑、历史记录，以及独立的内容/作曲/混音哈希。
- 渲染多乐器伴奏、分离的人声/乐器分轨、确定性效果链、段落自动化、混音、预览、A/B 对照和母带。
- 测量 LUFS、LRA、采样/真峰值、削波、声道平衡、乐谱/渲染音高、时值、释放和颤音证据。
- 运行确定性的乐理和编曲诊断，同时不让规则或语料数据去创作下一个音符。
- 在以下环节中保留简洁、哈希链式的创作决策：

意图 → 乐理 → 音符分配 → IA 交付 → 编曲

- 使用一个固定提示词加一个严格的每首歌意图文件，将工作流迁移到全新的 Codex 会话。

当前自动化结果：

发现 102 项测试
100 项通过
2 项因环境原因有意跳过
0 项失败

重要的非声明

通过每一项工程验收关口，并不意味着歌曲在音乐上成功。
| 工程可以确立 | 工程无法决定 |
| --- | --- |
| VSQX 在结构上有效 | 旋律是否令人难忘 |
| 所请求的歌手渲染出非静音音频 | 演唱是否充满生命力 |
| 原生控件已被实体化 | 调校是否有品味 |
| 交付内容是最新的且未削波 | IA 在混音中的位置是否正确 |
| 一个乐句避开了具体的理论风险 | 这个乐句是否说出了听众需要听到的内容 |
| 190 BPM 的编曲是稳定的 | 它是否真的感觉像摇滚 |

阅读故事

每一篇长文都提供繁体中文和英文版本。繁体中文版是主要的、更具个人色彩的叙述；英文版则为更广泛的受众保留相同的技术主张。

| 文章 | 繁體中文 | English |
| --- | --- | --- |
| 原生工程深度解析 | 從空白 Timeline 到一首完成的 VOCALOID 歌曲 | From a Blank Timeline to a Finished VOCALOID Song |
| 意图、理论与全新智能体作曲 | 從「它能唱」到「我希望 IA 在這一句唱出什麼？」 | From “Can It Sing?” to “What Should IA Sing in This Line?” |
| 有趣的整项目故事 | 我們叫一個 Coding Agent 去做 VOCALOID，然後事情失控了 | We Told a Coding Agent to Make VOCALOID Songs |

架构

CREATIVE / CONTROL PLANE

strict intent file + fixed agent workflow + listening question
│
▼
22-tool production MCP profile + 14 core resources
+ 1 optional local lyric resource
typed schemas │ dry-run │ preflight │ bounded proposals
│
▼
canonical *.song.json
intent │ timeline │ harmony │ vocals │ arrangement │ mix │ review
│
┌──────────────┴──────────────┐
▼                             ▼
NATIVE VOCAL PLANE            INSTRUMENT PLANE
VSQ3/VSQ4 compiler               pattern expansion
XSD + native loader probe          FluidSynth / SF2
VOCALOID3 Editor                 per-track stems
└──────────────┬──────────────┘
▼
AUDIO PRODUCTION PLANE
alignment → effects → automation → sum → master
│
▼
EVIDENCE / DELIVERY
hashes │ dependencies │ history │ journal │ previews │ QC
VSQX 是原生 Editor 的产物，而非唯一的数据库。规范清单保留了 VSQX 本身并不天然拥有的信息：渲染器选择、混音链、产物依赖、评审、意图以及变更历史。

创作边界

意图先于乐谱

规范的 vocaloid-composition-intent/v1 契约可以在任何音符存在之前就声明歌曲、段落和锚点乐句的用途。一个乐句方向承载一个聆听问题，之后可以绑定到稳定的乐谱、调音、和声与编曲对象。

理论是护栏

确定性的 core/v1 分析器区分结构性错误、音乐风险和风格观察。它可以发现时间线矛盾、呼吸压力、未解决音、声部碰撞、音区拥挤以及编曲冗余。它不会推断某个乐句是动人的、“像 IA 的”或是好的。

乐句语法不是旋律模板

可选的 DSL 提供带版本的 role、entry、contour、rhythm、motion、cadence、development、allocation、articulation 和 space 词汇。Bundle 是无序的选项池，带有 melody_material=absent。它们从不编译音高序列，也不提供下一个音符。

本地 IA 库位于生产运行时之外

生产 agent 不能查询本地歌曲路径、标题、逐轨特征、最近邻、参考旋律、续写或创作后的百分位拟合。离线库工作只能为经过人工评审的、非重构性的乐句语法词汇提供动机。

冷启动作品

这些受跟踪的包包含规范清单快照、仅追加的创作日志、可读报告以及摘要绑定的索引。最终 WAV 文件仅保留在本地。

| 作品 | 声库 | 音阶 | 记录 |
| --- | --- | ---: | --- |
| 朝がほどく前に | IA_ROCKS | 28 秒意图优先演示，11 项决策 | 记录 |
| 遠い灯、青い夜 | IA_ROCKS | 2:10 冷启动歌曲，13 项决策 | 记录 |
| 風は名を呼ばない | original IA | 3:10 全新 agent 歌曲，23 项决策 | 记录 |
| 雨と蝉のあいだ | IA_ROCKS | 190 BPM 下的 64 秒，24 项决策 | 记录 |

无需本地音频工作区即可安全发布的原生项目位于 artifacts/vsqxs/。

快速开始

要求

- Node.js 20 或更高版本。
- 通过 npm 安装的 TypeScript 工具链。
- 用于 schema 校验的 xmllint。
- 用于分析/混音/母带处理的 FFmpeg。
- FluidSynth 以及兼容的 SoundFont，用于确定性的草稿伴奏后端。
- 如需实际演唱：你自己合法拥有的 Windows 版 VOCALOID3 Editor 安装，以及正确安装/授权的声库。

本仓库不包含 VOCALOID 二进制文件、声库、激活数据或最终歌曲 WAV 文件。
构建与测试

npm install
npm run build
npm test

启动 MCP 服务器

VOCALOID_MCP_PROFILE=production npm start

通用本地 MCP 客户端配置：

{
"mcpServers": {
"vocaloid": {
"command": "node",
"args": ["/absolute/path/to/vocaloid/dist/src/index.js"],
"env": {
"VOCALOID_MCP_PROFILE": "production"
}
}
}
}

该服务器通过 stdio 使用 MCP。它被设计为本地单用户桌面桥接，而非远程暴露的多租户服务。

渲染可复用的作曲代理提示词

复制模板并编写一份有边界的创作简报：

cp intents/template.intent.json intents/my-song.intent.json
npm run --silent compose:prompt -- --intent=intents/my-song.intent.json

该简报要求一个 BPM 范围，并支持在该范围内指定一个可选的偏好 BPM：

{
"tempo_bpm": {
"min": 180,
"max": 200,
"preferred": 190
}
}

它还声明了确切的声部组件身份、时长、场景、戏剧性运动、听众问题、必须避免的约束，以及语料库/参考边界。

证据阶梯

绝不要将这些层级混为一谈：

declared     规范状态中存在某个手势或意图
materialized 原生 VSQX 音符 / 样式 / 控制中包含它
rendered     原始 Editor 生成了非静音的有界音频
heard        一位具名听众回答了一个明确的问题

有效的 VSQX 并不能证明歌手完成了渲染。非静音 WAV 并不能证明歌手身份。原生 PIT/DYN/vibrato 数据并不能证明演绎有品味。技术 QC 永远不会自行签署人类的 keep 决定。

仓库产物策略

公共仓库有意跟踪持久的、Git 安全的证据，并排除数 GB 的本地生产工作区。

| 路径 | 策略 | 内容 |
| --- | --- | --- |
| artifacts/songs/ | 忽略 | 最终本地试听 WAV 文件 |
| artifacts/evals/ | 忽略 | 分轨、预览、A/B 音频、调试工程、追踪 |
| build/ | 忽略 | 规范工作状态、缓存、临时渲染 |
| artifacts/creative-records/ | 跟踪 | 清单快照、日志链、报告、摘要索引 |
| artifacts/vsqxs/ | 跟踪 | 原生 VSQX 交付工程 |
| notes/ | 跟踪 | 契约、评估、失败证据 |
| blogs/ | 跟踪 | 长篇工程与创作回顾 |

VSQX 通过路径引用后备音频；它并不嵌入该 WAV。创作记录索引保留最终产物摘要，而不会将媒体复制到 Git 中。

仓库地图

src/
index.ts                 MCP profiles, tools, resources, prompt
song-manifest.ts         canonical state, revisions, stable IDs, hashes
theory/                  deterministic symbolic analysis and proposals
intent/                  composition-intent schema and realization evidence
phrase-grammar.ts        non-generative phrase vocabulary and diagnostics
creative-journal.ts      仅追加的决策与可发布记录
vocal-phrase.ts          日语节奏单元 / 摩拉编译
render.ts                原始编辑器导出边界
accompaniment.ts         确定性草稿伴奏
stems.ts                 孤立人声/乐器渲染
stem-mix.ts              效果、自动化、对齐、求和
audio-quality.ts         响度、峰值、削波、透明度
vocal-analysis.ts        乐谱与渲染对比观察

native/
vsq_probe.c              哈希固定的 Yamaha 原生加载器检查
vocaloid_export.c        有界 Win32 导出辅助程序

prompts/                   可复用智能体工作流
intents/                   严格的逐曲简报
scripts/                   评估、渲染、提示词与 MCP 辅助工具
tests/                     确定性与集成回归覆盖
notes/                     详细技术契约与问题日志
blogs/                     完整项目故事
artifacts/creative-records 持久化创作证据
artifacts/vsqxs/           可发布原生项目

精选技术笔记

- 乐理政策
- 作曲意图契约
- 乐句语法 DSL
- 创作决策日志
- 日语歌词与手势
- 规范歌曲清单设计
- 分轨混音工作流
- 乐谱与渲染分析
- 合成逆向工程
- 稳定问题/解决方案日志

安全与法律边界

- 文件系统写入仅限于配置的根目录；覆盖操作是显式的且绑定修订版本。
- 编辑器操作使用主机级租约，并且仅终止由活动渲染事务拥有的进程。
- 歌手可用性需要实际的原始编辑器探测；仅 VVD 发现只是元数据证据。
- 本项目不修补激活检查、不复制许可标记、不再分发语音数据，也不替换已授权的合成引擎。
- 二进制逆向工程发现与确切的本地哈希绑定，并作为观察结果记录，而非稳定的供应商 API。
- 捆绑/通用 GM SoundFont 路径是可复现的草稿渲染器，并非真实声学或摇滚演奏的证明。

项目状态

端到端本地研究原型在此阶段已完成。不声称其已可面向任意主机、所有声库或自主音乐发布投入生产。

最有用的结论刻意保持谦逊：

智能体已经可以成为强大的作曲助手、制作工程师和实验伙伴。热门歌曲仍然不是一项工程原语。
这没什么问题。这个仓库之所以存在，是因为用智能体打造一个真正的Vocaloid制作系统很有趣——而且因为那些失败最终和歌曲一样有意思。

许可证

源代码和仓库文档在MIT许可证下提供。VOCALOID、声库、Yamaha软件、提供的歌词、本地语料库材料以及其他第三方资源仍受其各自所有者和许可证的约束；本仓库不会对它们重新许可或分发。