程式化晶片配樂
把作曲資訊和音色引擎分開：參考音訊 → 按需真實分軌 → 轉譜候選與校訂 → 編曲事件譜 → 波形合成 → 試聽／循環母版。支援無參考的原創音樂；這時跳過扒譜。
先確定音樂目標
優先沿用使用者已確定的參考、時長、風格和已認可音軌。缺少非關鍵細節時選擇合理初稿，不重複詢問已回答的偏好。儲存新版到獨立曲目目錄，保留已認可原稿。創作本身不代表授權接入網站、遊戲或發佈 npm。
參考改編先讀取 參考分析與取捨。需要保留混音中的主線／回應細節時，再讀 真實分軌與轉譜，使用 Demucs + Basic Pitch ONNX／pYIN；基礎 NumPy 模式不自動拉這些重依賴。使用 Yakui Studio 工作台校訂和匯入時，讀取同級安裝的 Yakui Studio。若只是瞭解方法來源，讀取 Yakui 案例；案例中的速度、和弦和段落長度不是新曲預設規則。
參考音訊分析
拿到實際可解碼的音訊再報告分析結果。使用者文字中的 BPM 或音符表需要核對；網頁描述、曲名和線上影片連結本身不是聽過音訊的證據。只有 URL 時使用當前可用的正常媒體獲取途徑；獲取受阻則說明缺少什麼，不編造扒譜結果。參考錄音不自動混入音軌或原始碼包。
基礎工具：
python scripts/analyze_reference.py reference.wav --start 0 --seconds 30 --out analysis-intro.json
路徑相對本 skill；可使用其絕對路徑。依賴 Python 3.10+、NumPy，參考解碼和 MP3 匯出還需 FFmpeg（PATH 或 FFMPEG）。
- 至少比較開頭和主要段落的節拍候選，注意半速／倍速；確認後才傳
--bpm對齊音符候選。 half_beat_candidates是混音中的諧波顯著度，不是自動識別的獨立旋律。最大的峰可能屬於貝斯泛音、鼓或另一個聲部。- 標註觀測、低置信度候選和編曲選擇；高音回應無法可靠提取時保留歧義，原創回應明確標記。
- 細節優先的改編先真實分軌，模型標籤按實際
sources儲存；再用複調轉譜保留同時音符，用單聲部 F0 對照明確旋律段。主旋律／回應屬於音樂角色，不能把頻段篩選或 Demucs 的other自動改稱獨立角色聲軌。 - 原始秒時刻、音高彎曲、置信度/啟用值和校訂理由留在分析檔案；量化只增加派生欄位。用譜面和有代表性的實際樂句核對八度、短裝飾音、重複同音與同時奏響，不把模型輸出直接稱為原曲準確樂譜。
建立可編輯曲目
python scripts/init_track.py /absolute/new-track --title "Track title" --bpm 95 --bars 24
它複製獨立的編曲範本、合成器與構建入口，不覆蓋已有目錄。輸出包括 track.json、arrange.py、render_score.py、build.py、依賴清單。範本動機只是原創範例，須按本次音樂目標修改；不要把每首曲子都渲染成範本換 BPM。
在曲目目錄執行：
python -m pip install -r requirements.txt
python build.py --mp3 --three-pass
先做有代表性的樂句／段落，再擴展到目標長度；使用者已批准詳細編排時直接按編排製作，不另設審批門檻。
- 四分音符拍為事件時間單位，時長由 BPM、小節數與拍號計算；接近指定秒數時說明節拍約束，不透過加快整條音訊硬湊長度。
- 主旋律、回應、貝斯、和聲、琶音和鼓分別編排。高潮增強音域、節奏和和聲密度，給主旋律留出聲像與電平空間。
- 合成器沿用已驗證的 PolyBLEP 脈衝波、有限諧波三角波、LFSR 雜訊鼓、短包絡和節拍延遲。按曲目調音色；擴展晶片聲部不等於嚴格模擬 FC/NES 通道限制。
- 參考分析與轉譜可服務其他風格；使用者指定後搖等風格時保留已核對的旋律，另選實際合適的樂器／渲染器。晶片範本不會自動變成真實吉他或後搖音色，不用範本換標籤冒充新風格。
8-bit預設指音色／編曲；輸出保留 44.1 kHz、16-bit 立體聲品質，除非使用者明確要求位元深度降質。
需要直接編輯譜或調音色時讀 事件譜格式。render_score.py score.json --out audio --mp3 --three-pass 可跳過編曲器，渲染任意相容譜。
試聽與交付
audio/ 輸出 preview.wav、loop.wav、可選 MP3、高潮片段與 render-report.json。預覽可淡出；循環母版不加整曲淡出，延遲尾音環繞到開頭。--three-pass 生成三輪接縫試聽。
核對時長、有限數值、削波、段落電平及循環附近的突變；數字檢查不能替代聽感。實際聽音能力不可用時交付可播放檔案讓使用者試聽，不聲稱自己已經聽過。重點聽主題、回應、高潮密度、主奏清晰度與循環接縫；不因為音樂檔案存在就宣稱風格匹配。
用絕對路徑音訊嵌入提供完整試聽和有代表性的高潮片段；附編曲／合成原始碼、樂譜和簡短段落說明。使用者要求輕量終端播放時，再按相同事件譜和音色參數移植本機合成器，避免把整段 PCM 內嵌或要求使用者安裝 Python；不要為了製作試聽自動改觀看器或發佈流程。