音樂產生器 是做什麼的？
一個程序化音樂生成系統，透過嚴格、可衡量的管線創作原創音樂。所有決策由代理做出；腳本負責執行。管線使用客觀測量與品質閘門，而非主觀猜測。
使用時機
在以下情況使用此技能：
- 為影片、遊戲、廣告、Podcast 或旁白創作原創音樂
- 根據情緒描述產生配樂（例如「緊張的電影鋪陳」、「平靜的低傳真」）
- 從錄音中複製樂器音色
- 對現有分軌進行混音或母帶處理
- 為含有剪輯/對話的影片配樂
- 修正聽起來機械化、平淡或不平衡的音樂
- 處理特定文化風格（卡納提克、阿拉伯、非洲、東亞等）
快速開始
從技能目錄執行，並使用其虛擬環境：
- 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，包含知識庫引用與來源 |
| 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— 最新版本的副本，供預期單一 master 的工具使用。out/versions.json— 每個版本包含其時間戳記、測量結果，以及促成該版本的變更（它所通過的閘門失敗項目，或first certified render）。out/master.json— 寫在 master 旁邊的標準標籤。
標籤的來源：預設值來自 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時，才啟用耳機空間化。 - 混音診斷會報告但不會阻擋閘門（阻擋閘門定義在 quality gate 中）。
- 完整規則請見
AGENTS.md，完整限制請見references/troubleshooting-and-limits.md。