/minara-music — 從腳本生成音樂與音效
將影片的逐秒腳本轉換為音樂提示清單 cues.json，然後在本地端合成 BGM 與畫面同步的音效。合成過程完全使用本機 numpy，輸出結果是確定性的（相同的提示與種子總是產生相同的音訊）。它不呼叫任何外部服務，且完全免費。
來源：Minara V2 宣傳影片的配樂方法，泛化為可重複使用的腳本；examples/v2-launch.json 即為該影片的提示清單。
工作流程（依序）
- 讀取腳本：從 minara-video（或故事板/配音時間表）取得逐秒腳本。如果腳本中有「聲音氛圍」或「音樂」欄位，請遵循它們；如果沒有，則根據畫面情緒自行判斷。
- 撰寫提示清單：在專案的
audio-src/cues.json中寫入：duration（= 最終影片長度）、bpm（預設 120）、key（預設A minor；明亮/慶祝的樂曲可使用C major）、seed。sections：將腳本切割成音樂段落，每個段落選取一個energy，並使用note描述對應的畫面（便於交叉參考）。sfx：腳本中的每個可見動作（點擊、打字、訂單完成、通知彈出、轉場、鎖定落地）都對應一個音效，時間點對齊腳本中指定的秒數。
- 先向操作者顯示提示清單；不要立即渲染：以 markdown 表格列出「時間範圍 / 能量 / 對應畫面」以及「音效時間 / 類型 / 對應動作」，並等待操作者說「好」再進行渲染。操作者編輯的是提示清單，而非程式碼。
- 渲染：
python3 ~/.claude/skills/minara-music/scripts/make_music.py <project>/audio-src/cues.json -o <project>/assets [--vo <project>/assets/vo.wav] - 自我檢查：腳本會印出每個段落；然後測量每個段落的音量，確認高潮部分最大聲，轉折/結尾段落明顯降低，且閃避功能正常運作。如果聽覺上有問題（太雜亂、某個音效搶走焦點），請調整
level/gain並重新渲染；每次渲染只需數秒。 - 交付：提供
bgm.wav（或bgm-duck.wav）的路徑，並使用open -R反白顯示preview-mix.wav以便操作者聆聽。在 HyperFrames 中，將其作為音軌加入，配音則放在另一條獨立音軌。
輸出
| 檔案 | 內容 |
|---|---|
bgm.wav | 音樂 + 音效，48 kHz 立體聲，峰值 -1 dBFS，開頭淡入 0.4 秒，結尾淡出 3.2 秒 |
bgm-duck.wav | 當有配音時產生：人聲出現時音樂降低 duck_db（預設 -8 dB）；音效不會被閃避 |
preview-mix.wav | 當有配音時產生：音樂 + 配音混合，僅供聆聽預覽，非最終影片使用 |
能量段落類型
| 能量 | 聲音 | 用途 |
|---|---|---|
silent | 無音樂 | 需要完全靜音的暫停 |
intro | 低沉 drone + 軟 pad | 開場、logo、資料匯聚 |
light | Pad + 輕柔琶音 + 稀疏節拍 | 手機互動、輕量級功能展示 |
build | 加入貝斯與每拍大鼓，段落結尾自動加入 riser | 逐漸堆疊，引導至關鍵時刻 |
full | 完整鼓組 + 拍手 + 貝斯 + 琶音 | 連續展示核心功能（回測、上線、自動化） |
breakdown | 移除鼓與貝斯，僅留 pad 與柔和琶音；最後一小節大鼓回歸 | 場景轉換、關於安全性/隱私的章節，需要「呼吸空間」 |
climax | 最飽滿：完整鼓組 + 主旋律 + 段落開頭的 crash；若前一段落非 build 則自動加入 riser | 產品名稱/上市宣言出現 |
outro | 在主和弦上解決 + 品牌鈴聲，與整個混音一起淡出 | 結尾卡、行動呼籲 |
每個段落可設定 "level": 0.5–1.3 來微調音量。和弦遵循全域小節（小調 i–VI–III–VII，大調 I–V–vi–IV），因此不會跨段落中斷。
音效類型（sfx）
| 類型 | 聲音 | 典型動作 | 可選參數 |
|---|---|---|---|
tap | 短促點擊 | 按鈕點擊、選取 | gain |
typing | 連續打字聲 | 在輸入欄位中打字 | chars、cps（字元/秒，對應畫面上的打字速度） |
success | 兩個上升的鈴聲 | 訂單成交、策略執行中 | gain |
notify | 三個音符的提示音 | 通知或提醒彈出 | gain |
bell | 單一鈴聲 | 頭像/logo 出現 | note（MIDI，預設 81） |
blips | 逐步上升的短音 | 回測進度、資料載入 | count、step（秒）、note |
sparkle | 閃爍顆粒 + 氣息聲 | 粒子匯聚、開場 | dur |
riser | 上升噪聲 | 手動加入的轉場堆疊 | dur |
whoosh | 反向掃掠 | 視窗收合、推/拉轉場 | dur |
thud | 低沉的鎖定聲 | 鎖定、確認、重落地 | gain |
crash | 鈸 | 額外重音 | gain |
每個音效都可設定 gain 來調整音量。
規則
- 音效僅跟隨可見動作：如果畫面上沒有對應的動作，就不要加入音效，等同於「不要隨便加入文字」。
- 從腳本複製時間點；不要自行估計：音效的
t使用逐秒腳本/動畫時間軸中的實際秒數；打字的cps使用動畫中的打字速度。 - 如果腳本的長度或順序改變，請先更新 cues.json 再重新渲染；不要手動拉伸音訊。
- 不要使用外部 AI 音樂服務或從網路下載的音樂；當需要商業授權的音樂時，由操作者提供檔案。