音乐生成器 是做什么的？
一个程序化音乐生成系统，通过严格、可衡量的流水线创作原创音乐。所有决策由代理做出；脚本负责执行。该流水线使用客观测量和质量门，而非主观猜测。
使用时机
在以下情况使用此技能：
- 为视频、游戏、广告、播客或旁白创作原创音乐
- 根据情绪描述生成配乐（例如，“紧张的电影铺垫”、“平静的lo-fi”）
- 从录音中克隆乐器
- 混音或母带处理现有分轨
- 为带有剪辑/对话的视频配乐
- 修复机械、平淡或不平衡的音乐
- 处理特定文化风格（卡纳提克、阿拉伯、非洲、东亚等）
快速开始
从技能目录使用其虚拟环境运行：
- Windows：
.venv/Scripts/python.exe - Unix：
.venv/bin/python
首次设置：参见 references/setup.md。
工作流程
按顺序执行以下步骤。切勿跳过步骤。
| 步骤 | 操作 | 输出 | 检查 |
|---|---|---|---|
| 1 | 创建项目 | python scripts/setup_project.py --new-project <dir> --title "<Title>"（仅在要求时添加 --ambience） | 包含 direction/、presets/、scores/、out/、reports/、STATUS.md 的项目结构 |
| 2 | 研究 | python scripts/research_kb.py <dir> --topic "<topic>" --tags <tags>。通过 TinyFish 添加网络来源。对于氛围/音效，使用 --sounds 并记录带有许可证/测量的真实参考。 | reports/research_<topic>.md，包含 KB 引用和来源 |
| 3 | 方向表 | 将 templates/direction_sheet.json 复制到 <dir>/direction/direction_<title>.json。根据 references/music-direction.md 填写所有字段。对于视频，先运行 scripts/video_score.py。 | 包含工作、感觉、段落、动机、重音、混音意图、空间布局的完整方向表 |
| 4 | 创建预设 | python scripts/presets.py scaffold instruments/vocals/environments/sfx <name> --project <dir>。每个预设需要独特的空间位置。 | 项目中的预设，包含特征、空间方位角/距离 |
| 5 | 编写乐谱 | 创建 <dir>/scores/<title>_score.json（声明式，引用预设）。使用 templates/custom_score_template.py 进行精确控制。 | 有效的JSON，包含引用预设的音轨 |
| 6 | 渲染与门控 | python scripts/pipeline.py <dir>/scores/<title>_score.json --project <dir> | out/master.wav（最新版本的副本）、out/master_vNN.wav、out/versions.json、<master>.json 标签、stems/、midi/、reports/ci_report.json（0 FAIL） |
| 7 | 修订 | 一次只更改一个杠杆（references/music-direction.md §6）。重新运行步骤6直到通过（最多尝试5次）。 | 所有门测试通过 |
| 8 | 听取与交付 | python scripts/listen.py out/master.wav --direction direction/<sheet>.json | 验证并报告结果 |
交付元数据与版本
认证在音乐门通过后自动写入三样内容：
out/master_vNN.wav— 每个认证渲染都获得自己的版本文件。早期版本会保留；重新渲染从不会覆盖。out/master.wav— 最新版本的副本，供期望单一主文件的工具使用。out/versions.json— 每个版本附带其时间戳、测量结果以及使其通过的更改（它清除的门失败，或“首次认证渲染”）。out/master.json— 写在主文件旁边的标准标签。
标签来源：默认值来自 presets/metatdats/metadata.json（艺术家、专辑、版权、许可证、出版商、ISRC、语言），然后是根据乐谱派生的值（标题、来自 piece_type 的类型、年份、事实性的 key · BPM · piece_type 注释），然后项目的 metadata.json 覆盖。将真实值写入 <project>/metadata.json，而不是脚本中。
代理规则：
- 切勿删除或覆盖
master_vNN.wav或versions.json记录。如果交付需要干净版本，它将成为新版本。 - 渲染后检查记录：
python scripts/helpers/version_manager.py list --project <dir>。 - MP3 压缩是手动的，绝不属于流水线：
python scripts/helpers/compress_mp3.py out/master_vNN.wav -o <file>.mp3 -b 320k。它将侧车标签带入 MP3。 - 门行
meta.tags和meta.version仅跟踪此记录。它们会警告，但不会失败，并且在作品首次渲染时为INFO。
关键原则
- 模块化：声音/空间在
presets/中，音符在scores/中，意图在direction/中。没有单一脚本。 - 研究驱动：每个自定义乐器/人声/文化都需要知识库研究引用。
- 数据优先于代码：新声音使用场景数据（
"scene"/"scene_layers"），而非 Python 生成器。 - 一次只改一项：修复门失败时，恰好更改一个参数并重新测量。
- 衡量，而非猜测：使用流水线指标和诊断。品味无法衡量。
- 每个作品都有一个混音预设：控制增益分级、动态、侧链、母带处理。
按任务分类的路线
| 任务 | 关键参考 |
|---|---|
| 视频配乐/剪辑 | references/video-scoring.md、scripts/video_score.py |
| 人声/合唱/哼唱 | references/vocals-and-choirs.md、references/vocal-engine.md |
| 文化风格/融合 | knowledgebase/README.md、references/cultural-soul.md、references/genre-fusion.md |
| 音效/氛围/拟音 | references/sound-effects.md、references/physical-scene.md、references/environments-as-presets.md |
| SFZ 管弦乐 | references/sfz-libraries.md、scripts/sfz_libs.py |
| 乐器克隆/提取 | references/instrument-cloning.md、references/extraction.md |
| 混音/母带处理 | references/mixing-and-mastering.md、scripts/mixer.py、scripts/mix_diagnostics.py |
| 门失败 | references/quality-gate.md、scripts/gate_profiles.py |
输出模板
完成：out/master.wav (Xs, -X.X LUFS, -X.X dBTP), midi/<title>_score.mid, stems/ (N), reports/ci_report.json。
内容：<感觉、调性、BPM、乐器、预设>。
门：<N 通过，0 失败，经过 K 次尝试>；听取：<读数>。
未检查：品味、真实乐器真实感、在最终视频中的匹配度。
下一步：<一个建议的更改>。
注意事项与限制
- 默认使用 GM SoundFont；SFZ 库可选。标准合成中不会唱出词语（合唱/哼唱是纹理）。
listen.py需要 earshot 模型（运行python scripts/setup_project.py --ears安装）。- 仅对具有
spatial.binaural: true的预设进行耳机空间化。 - 混音诊断会报告，但不会阻止门测试（阻止的门测试在质量门中）。
- 参见
AGENTS.md了解完整规则，references/troubleshooting-and-limits.md了解全部限制。