Yakui Studio 是做什麼的？
把實際音頻分析、候選轉譜、人工修整和可編輯工程連接起來。沿用用戶指定參考與已認可音樂；音樂製作本身不授權修改遊戲或發布套件。
啟動與資源
已安裝 npm 套件提供 yakui-studio 本地工作台；yakui-studio --no-open 只啟動服務。yakui-studio setup --agent codex|claude|opencode|all 安裝本技能及同級的 procedural-chiptune；預設 codex。目標分別為 $CODEX_HOME/skills（預設 ~/.codex/skills）、~/.claude/skills、~/.config/opencode/skills（遵守 XDG_CONFIG_HOME）。--skills-dir PATH 指定單一目錄，--replace 備份既有版本後安裝。技能被複製到其他目的地時，兩者應仍是相鄰資料夾。
yakui-studio music setup --profile basic：建立分析／程式化合成所需 Python 環境。yakui-studio music setup --profile transcribe：按需安裝真實分軌與轉譜依賴；首次分軌可能需要模型下載。music analyze/separate/transcribe/review/init/render呼叫隨套件 Python 工具；music import將候選轉成工作台工程。執行對應子命令--help確認當前參數，尤其轉譜模式、輸入輸出路徑和 BPM。
若只安裝了技能，仍可直接執行 procedural-chiptune/scripts 中工具；以該技能目錄解析腳本和範本路徑。Python 3.10+ 與 NumPy 支援基礎合成；音訊解碼和 MP3 需要 FFmpeg。模型依賴見 真實分軌與轉譜。
若 shell 找不到 yakui-studio，用 npx --yes --package [email protected] yakui-studio --help；後續命令同樣在該前綴後追加參數。安裝技能本身不會安裝代理 CLI、登入帳號或下載音樂模型。Codex 和 OpenCode 使用各自既有登入和模型配置；Claude Code 的內建候選介面預留為後續功能。工作台內候選模式關閉工具，外部代理透過下述 CLI 操作工程。
外部代理操作當前工作台
先執行 yakui-studio project --help 和 yakui-studio project read，讀取當前工程、revision、軌道片段和瀏覽器選區。服務預設 http://127.0.0.1:5240；用 YAKUI_STUDIO_URL 指向用戶實際開啟的實例，不要另建一個空白實例取代它。
yakui-studio project selection讀取選區，project selection --file selection.json更新選區。yakui-studio project apply --file operations.json應用編輯。檔案必須使用剛讀到的projectId、baseRevision，新的operationId和operations；操作類型、欄位和完整範例見 工程 CLI 協定。版本衝突後重新讀取並重新評估編輯，不能只換 revision 強行覆蓋用戶修改。yakui-studio project import input.json或input.mid導入；project export output.json或output.mid導出。導入前先導出當前工程，保持用戶已認可素材可復原。yakui-studio project undo --revision N --project ID和redo --revision N --project ID操作同一服務的復原歷史。
編輯後再次 project read 核對實際 revision 和音符，並告知用戶改變的軌道／片段。工作台可立即看見同一工程的修改。僅寫磁碟 JSON 不會自動改變已開啟工程。
從參考到工程
- 取得實際可解碼音訊後，依 參考分析 檢查多個樂句的速度、半速／倍速與拍點。只有曲名或連結時不能聲稱已經聽過或扒譜。
- 需要真實分軌時使用 Demucs，並保留模型實際 sources；drums/bass/other/vocals 不是主旋律／回應的保證。對分離後的複調樂器用 Basic Pitch ONNX，對明確單聲部片段用 pYIN 對照。先驗證短選段再擴展全曲。
- 保存原始候選、來源、秒時刻、信賴／激活值、彎音與人工理由。用
music review或review_notes.py應用角色視窗和顯式 edits，保留 before。衝突角色仍為 unassigned，量化欄位作為衍伸資料。 - 用
music import轉成工作台工程，再在介面開啟 JSON。保留原始候選檔案，導入會把音符對應到可編輯的拍單位；若目標格式無法承載彎音等資訊，應說明限制，不能把工程導出當成全部原始證據。 - 在軌道編排中選片段，進入鋼琴卷簾，核對八度、起拍、時值、重複同音、裝飾音和同時聲部。用獨奏、片段循環和數值屬性逐段修整。儲存工程 JSON 作為可繼續編輯的交付。
手工與 AI 協作
片段起點為全曲拍數，音符起點相對片段；時間單位都是四分音符拍。注意片段邊界與跨段延音。工程編輯、復原與重做會改變 revision。
AI 修改使用明確的音符／時間選區，先產生候選、對照試聽，再應用或丟棄；工程變更後重新產生過期候選。AI 編曲建議不構成參考音訊的準確轉譜證據。未配置可用代理時仍可手工編輯、試聽和導出；不可用或認證失敗必須如實報告。
原創程式化音樂走 procedural-chiptune 的 init/render 路線；改寫範本動機，避免僅改 BPM。事件譜格式見 score-format。瀏覽器合成與 Python 渲染不是逐取樣相同的母帶。
交付標準
「已提取候選」「已人工校訂部分樂句」「已按參考驗證完整範圍」分別表述。模型輸出、導入成功、AI 修改成功都不能單獨稱為準確扒譜。註明已核對範圍、未分配聲部與不確定音符；原創回應明確標記。
交付可編輯工程、必要的原始候選與校訂記錄，以及可播放試聽。工程 JSON 保留軌道和片段，事件譜用於程式渲染，MIDI 用於外部編輯，WAV 用於試聽。參考錄音不自動混入合成音軌或 npm 套件。實際聽音能力不可用時如實說明，提供音訊供使用者試聽。