kajisho5/sound-design-skill

sound-design-skill 是做什麼的？

執行 sound-design <command> ... --json（透過 pip install -e . 安裝，需 Python >= 3.9，僅使用標準函式庫）。搭配 --json 參數時，標準輸出的內容僅為單一 JSON 文件，且僅限 ASCII 字元。音訊的探測、剪輯、拼接與響度處理均透過 ffmpeg-skill 完成，其路徑可經由 --ffmpeg-skill DIR、$SOUND_DESIGN_FFMPEG_SKILL_DIR、$VIDEO_AGENT_FFMPEG_SKILL_DIR、~/.claude/skills/ffmpeg-skill、./vendor/ffmpeg-skill 或 ../ffmpeg-skill 指定。sound-design doctor --json 會報告各引擎的狀態為 OK、MISSING 或 INCOMPATIBLE，以及運算裝置與 GPU 記憶體資訊，並說明安裝方式；此指令絕不會自動下載任何檔案。

任務	指令
一段 60 秒的背景音樂	sound-design generate-bgm --prompt "calm piano bed" --tags "ambient,70 bpm" --duration 60 -o bed.wav --seed 42 --json（範圍 10-600 秒）
一段 120 BPM、用於 15 秒歌詞影片的背景音樂，包含節拍網格	sound-design generate-bgm --prompt "upbeat pop" --duration 15 --bpm 120 --time-signature 4 -o pv.wav --json（長度變為 16 秒 = 8 小節；同時產生 pv.beats.json）
同上，但加入歌詞 / 使用 CPU	加入 --lyrics lyrics.txt / --device cpu（預設為純器樂、--device auto）
使用更大的 4B XL 模型（需自行選擇，GPU 需 >= 20 GB）	sound-design generate-bgm --prompt "cinematic strings" --duration 60 -o bed.wav --model acestep-v15-xl-turbo --json（詳見「選擇 BGM 模型」）
一個音效（需使用者同意，詳見下方說明）	sound-design generate-sfx --prompt "a wooden door closes" --tags "indoor" --duration 3 -o door.wav --seed 7 --acknowledge-ezaudio-training-data --json（長度為整數秒，範圍 1-10）
將使用者自己的檔案加入音效庫	sound-design library-import track.wav --library ./sounds --licence CC-BY-4.0 --credit "Music: name" --kind bgm --tags piano --mood calm --loopable --json
匯入已下載的版權音軌及其授權記錄	sound-design library-import track.mp3 --library ./sounds --licence CC-BY-4.0 --title "Morning Light" --author "Aiko Tanaka" --licence-url https://creativecommons.org/licenses/by/4.0/ --licence-file LICENSE.txt --provider Freesound --kind bgm --json（若來源有提供來源資訊，可加上 --attribution "<line>"；僅當來源明確標示時才使用 --content-id registered）
檢視音效庫內容，包含授權與長度	sound-design library-index ./sounds --loudness --json
將音效庫中的曲目調整為 60 秒	sound-design library-pick ./sounds --kind bgm --tags piano --duration 60 -o bed.wav --json（可加上 --file <path> 指定曲目名稱，--crossfade 0.5 用於循環）
將背景音樂循環為無縫的 8 秒片段（用於編輯中的循環）	sound-design loop-bed bed.wav -o loop.wav --duration 8 --search 1 --json（來源音檔長度至少需大於 duration + crossfade；循環點會在 --search 秒內搜尋）
一段 1 秒的「咻」聲，其峰值精準落在 0.5 秒處（即畫面的剪接點）	sound-design stinger whoosh.wav -o stinger.wav --duration 1 --peak-at 0.5 --type whoosh --json
檢查循環音檔的接縫是否順暢	sound-design seam-check loop-x10.wav --period 8 --json（或 --seams 8,16；若接縫失敗則回傳 exit code 1）
根據剪接點與強調字幕產生音效提示表（供 MIX 使用的提示表）	sound-design sfx-cues --cuts 1.0,2.5,4.75 --emphasis 3.2 --library ./sounds --min-spacing 0.25 -o cues.json --json（剪接點預設使用 whoosh 音效；強調點預設使用 pop 音效，除非使用 --effect cut=<name>；可使用 --file ding=ding.wav 指定產生音效的檔案）
同上，但同一檔案在 30 秒內不重複，且強調音效改為明亮的 pop 音	sound-design sfx-cues --cuts 1.0,12.0,25.0 --emphasis 3.2 --library ./sounds --min-reuse-spacing 30 --character pop=bright -o cues.json --json（兩者皆為選擇性功能；詳見下方說明）
查看已安裝的項目	sound-design doctor --json、sound-design engines --json
查看此技能宣告的內容	sound-design contract --json（別名 skill --json）

每個操作都接受 --timeout S 和 --ffmpeg-skill DIR 參數；會寫入檔案的操作接受 --overwrite 參數（若無此參數，則會拒絕覆蓋已存在的輸出檔案）；產生器也接受 --seed 參數（若省略則會自動產生並記錄）和 --offline 參數。輸出結果會是一個全新的 .wav 檔案；輸入檔案絕對不會被修改，且輸出檔案會在 ffmpeg-skill 的 probe 確認無誤後，才會完整寫入，否則不會寫入。

何時使用

• 當使用者擁有已知授權的音樂或音效時（例如購買的音效包、委託製作的曲目、CC0 / CC BY 授權的素材）：優先使用音效庫模式。先使用 library-import 將每個檔案及其授權資訊匯入，然後再為每個場景使用 library-pick 選取。此過程不會執行任何 AI 引擎，也不會產生任何 AI 生成的內容（ai_generated: false）。
• 當音效庫中沒有適合的素材時：使用 generate-bgm（ACE-Step）或 generate-sfx（EzAudio），但前提是 doctor 指令顯示該引擎狀態為 OK。
• 然後，務必將生成的 WAV 檔案及其 provenance（來源資訊）交給 audio-production-skill MIX，由其負責放置音檔、在人聲下方進行閃避（ducking）處理，並設定響度。此 skill 本身不會進行混音、閃避或正規化。

循環片段與過場音效

• loop-bed 與 stinger 不需要執行任何 AI 引擎。它們直接使用你已有的一個 WAV 檔案（可以來自 generate-bgm、generate-sfx、library-pick 或使用者的檔案），僅透過 ffmpeg-skill 進行編輯，並測量編輯結果；該檔案的授權與引擎資訊會保留在原始來源的 provenance 中，因此請一併傳遞這些資訊。
• 循環片段的尾部會與其頭部相接，過程中不能有爆音（click）：將其頭尾相連重複播放，不需任何交疊淡入淡出（crossfade）。輸出結果會報告它找到的循環長度（loop.length，會在 --duration 的 --search 範圍內搜尋）、交疊淡入淡出素材的相似度（loop.similarity；低於 0.5 時會顯示警告）以及測量到的接縫狀況（seam）。整數小節數的循環效果最佳。
• 過場音效的長度會完全符合 --duration 的設定，且其最大音量的 10 毫秒區段，必須位於 --peak-at 時間點的前後 10 毫秒內（且距離音檔的頭尾至少 20 毫秒），否則不會輸出任何檔案。請告訴 MIX 要在剪接點前 --peak-at 秒處開始播放此音效。
• seam-check 是此技能專屬的循環檢查工具：它會檢查音檔接縫處前後 1 秒的點擊聲（±1 毫秒）、音量以及八度頻譜。qc-skill 目前還沒有循環接縫檢查的功能。

音效提示表

• sfx-cues 不會自行決定音效的擺放位置：所有時間點都由呼叫端提供（來自剪輯的剪接點清單和強調字幕），每個時間點對應一個提示。若某個時間點距離上一個保留的提示小於 --min-spacing 的設定，則該提示會被丟棄（會在 dropped 中列出，並附上原因），且絕不會被移動。請勿為此工具自行發明強調時間點。
• 每個提示會指出所使用的檔案（file、from：來自音效庫或指定的 WAV 檔案，source：其在 sources 下的條目，包含授權資訊）、音效開始播放的時間（start；若 file_offset 會讓音效在時間 0 之前開始，則會顯示此資訊）、為了達到 --level dBFS 所需的增益值（gain_db），以及該音效的峰值（如 whoosh、rise 等）或起始點（如 pop、ding 等）是否位於該時間點上。從音效庫選取音效時，需要有明確的授權宣告，其選擇方式類似 library-pick，會將音效名稱作為標籤進行比對。請將此提示表連同所有來源檔案的授權資訊，一併交給 audio-production-skill MIX。
• 避免短時間內重複使用同一個檔案（選擇性功能，預設關閉）。 --min-reuse-spacing S：若某個事件的音效，其使用的檔案（基於 SHA-256 雜湊值）與 S 秒內已保留的某個提示相同，則該事件會從音效庫中選取該音效的下一個排名檔案（第一個可用的檔案；絕不隨機選取）。若無其他符合條件的檔案，或該音效是透過 --file 指定的，則該事件會被丟棄（dropped[].by: min_reuse_spacing），絕不會被移動，也不會被賦予其他音效。substitutions 和每個提示中的 substituted 會顯示哪個檔案被哪個檔案取代。--min-spacing 的檢查會優先執行；被丟棄的事件對上述兩項規則都不會產生影響。建議設定：對於談話性頭像的編輯，建議 30 秒；對於快速剪輯的編輯，建議設定更短的時間，因為如果音效庫中有 N 個檔案，那麼在任何 S 秒的時間窗口內，一個音效最多只會出現 N 次提示；若希望使用一個特定的標誌性聲音，則建議關閉此功能。當有提示被丟棄時，請告知使用者。
• 音效特色（選擇性功能）。 --character pop=bright（或事件中的 "character": ["bright"]，後者會覆蓋前者）會讓提示表只選取音效庫中，其標籤或情緒設定包含了所有指定詞彙的檔案。此功能僅會根據音效庫中已有的資訊進行比對；它絕不會自行推斷或新增標籤，如果沒有符合的檔案，則會顯示 INPUT_NOT_FOUND：請使用者先匯入或標記該檔案，切勿自行猜測。library-import --tags / --mood 以及此處可使用的詞彙包括：bright（明亮）、dark（黑暗）、warm（溫暖）、metallic（金屬）、soft（柔和）、hard（堅硬）、punchy（有力）、subtle（細微）、short（短促）、long（持續）、high（高音）、low（低音）、rising（漸強）、falling（漸弱）、airy（輕柔）、playful（俏皮）（其他詞彙同樣適用）。

使用 EzAudio 前需先詢問使用者

EzAudio（generate-sfx 使用的引擎）是使用 YouTube 音訊（來自 AudioSet、VGGSound、AudioCaps 資料集）進行訓練的，而這些資料的所有者並未授權將其用於模型訓練。根據其所有者的決定，在執行此模型前，必須先告知使用者這項資訊。若未加上 --acknowledge-ezaudio-training-data 參數，generate-sfx 會在執行任何操作前，以 CONFIRMATION_REQUIRED（exit code 8）狀態停止；其訊息會以英文和日文說明此限制。請向使用者顯示該訊息，並僅在使用者同意後才加上此參數；切勿自行添加。contract --json（即 generate-sfx 工具）和 doctor --json（checks.operations.sfx）中會包含 confirmation_required: true 標記，以便協調器可以預先詢問使用者。此同意記錄會被寫入 provenance（來源資訊）中，且每個 SFX 輸出結果都會重複顯示訓練資料的警告訊息：請務必傳遞此資訊。

音效庫模式中的授權

• library-import 會拒絕匯入缺少、空白或使用佔位符（如 unknown、n/a 等）的授權資訊，並以 LICENCE_REQUIRED（exit code 2）狀態退出。請向使用者詢問正確的授權資訊；切勿自行填寫。
• 授權會完全依照使用者宣告的內容進行記錄，並標記為 verified: false。此技能不會檢查或清除授權資訊：請說「宣告為 CC-BY-4.0」，而不是「已清除授權疑慮」。
• library-index 會將未宣告授權的檔案回報為 licence: "unknown"，而 library-pick 絕不會使用這些檔案（它們會被列在 excluded 中，並附上原因）。
• 請務必傳遞以下警告資訊：非商業用途條款、禁止改作條款（若檔案已被修剪或循環處理）、CC BY 授權但未提供來源資訊、以及匯入後檔案已被修改的情況。任何公開發布的作品都必須保留來源資訊。
• 版權音軌。 匯入使用者下載的音軌時，請一併記錄來源所提供的所有資訊：--licence、--licence-url 及/或 --licence-file（會複製到 licences/ 目錄下）、--title、--author、--provider、--attribution、--content-id。此技能不會自動下載任何檔案；doctor 指令會列出支援的版權音軌來源（若未提供 API 金鑰則顯示 MISSING，若完全沒有 API 則顯示 MANUAL），但永遠不會呼叫它們。接收憑證（library-pick 結果和 provenance 中的 licence.attribution，以及 handoff.credit_line）會包含來源資訊行：優先使用使用者宣告的內容，否則使用 --credit 參數的內容，若以上皆無且為 CC BY 授權，則會根據使用者宣告的資訊組合而成（會發出警告要求檢查）。請將此資訊放入影片的描述或致謝名單中。若音軌被宣告為 --content-id registered，則會發出警告：上傳後可能觸發內容比對，請在發布前告知使用者。
• 配對邏輯：若目標時長與檔案長度差異在 max(0.1 秒, 1%) 範圍內，則直接使用完整檔案；若目標時長較短，則修剪檔案（不做淡入淡出：MIX 會處理）；若目標時長較長，則僅當檔案在匯入時使用了 --loopable 參數，才會進行循環並加入交疊淡入淡出；否則該檔案會被排除。相同的查詢條件和音效庫，一定會傳回相同的檔案。

需告知使用者的限制

• 實驗性功能。 audio.bgm_generate、audio.sfx_generate 與 audio.library_import 的生命週期標記為 EXPERIMENTAL。真實的 ACE-Step 和 EzAudio 在種子隨機性的確定性以及時長準確度方面，尚未經過測量（測試是使用具有相同 API 的模擬引擎進行的）。請說明結果是由 AI 生成的，並建議聆聽確認。
• 生成的音樂不會進行相似度檢查，以確認是否與現有錄音相似；音樂辨識與版權檢查並非此技能的功能。ACE-Step 的商業使用聲明僅為其供應商的說法。
• 節拍。 當使用 --bpm 參數時，生成的音樂長度會調整為最接近的整數小節數（會有警告提示），確保背景音樂在強拍處結束；同時，節拍網格（每個拍點、重拍、小節線）會寫入 <name>.beats.json 檔案中，並作為 tempo_map 回傳。此網格是根據請求設定的，第一個拍點在 0 秒處（measured: false）：雖然已要求 ACE-Step 依照指定節拍生成，但並未實際測量其節拍準確度。請傳遞此網格，但不要稱其為測量結果。
• ACE-Step 僅執行 DiT（其語言模型在 Qwen3 基礎版權確認前保持關閉），因此提示詞僅能引導風格，而非結構。
• 請務必閱讀並傳遞 warnings 中的每一項內容。

引擎（可選安裝）

操作	引擎	安裝方式
generate-bgm	ACE-Step 1.5（程式碼與權重皆為 MIT 授權；預設使用 2B turbo 模型，可透過 --model 選擇 4B XL turbo 模型），需在其獨立的目錄與 .venv 虛擬環境中運行，Python 版本為 3.11-3.12	doctor 指令會印出確切的安裝指令；可設定環境變數 SOUND_DESIGN_ACESTEP_PYTHON（以及 SOUND_DESIGN_ACESTEP_CHECKPOINTS，否則會使用 Hugging Face 的快取目錄）
generate-sfx	EzAudio-XL（程式碼與權重為 MIT 授權，Flan-T5-XL 為 Apache-2.0 授權），需在其獨立的目錄與 .venv 虛擬環境中運行	doctor 指令會印出確切的安裝指令；需設定環境變數 SOUND_DESIGN_EZAUDIO_PYTHON 和 SOUND_DESIGN_EZAUDIO_DIR（包含 ckpts/ 目錄的 checkout 路徑）；Flan-T5-XL 模型會存放在 Hugging Face 的快取目錄中
音效庫模式	無	除了 ffmpeg-skill 外，無需安裝任何東西

選擇 BGM 模型

generate-bgm 預設使用 ACE-Step 的 2B turbo 模型 acestep-v15-turbo，除非使用 --model 參數指定其他模型（請求金鑰為 model）。此模型需要少於 4 GB 的 GPU 記憶體，也可以在 CPU 上運行（但速度很慢）。--model acestep-v15-xl-turbo 參數會選擇 XL turbo 模型：一個 4B 參數的 DiT 模型，授權方式與預設模型相同（MIT），且其模型卡上會說明其輸出的商業使用政策。請從 doctor --json 的 checks.operations.bgm.models 中選擇模型，其中每個模型都有 ready 狀態、所需檔案、vram 需求和 install 安裝資訊：

• GPU 記憶體。 XL 模型需要至少 20 GB 的 GPU 記憶體，因為此技能在運行時不會啟用 CPU offload 或量化。其模型卡標示的記憶體需求分別為 12 GB（啟用 offload 和 INT8）、16 GB（啟用 offload）、20 GB（無 offload）和 24 GB（含 4B 語言模型）。若 GPU 記憶體不足 20 GB，或沒有 GPU，則 generate-bgm --model acestep-v15-xl-turbo 會在執行任何操作前，以 INSUFFICIENT_VRAM（exit code 3）狀態停止。請告知使用者，並提供預設模型作為替代方案（error.details.default_model）：移除 --model 參數即可。Apple Silicon 晶片會將其統一記憶體算入，此記憶體會與 CPU 共享。當無法測量 GPU 記憶體時（例如 ROCm、Intel XPU），仍會生成背景音樂，但會發出警告，表示未檢查記憶體是否足夠。只有透過 xpu-smi 才能偵測到 Intel GPU；若 Intel GPU 未安裝 xpu-smi，請傳遞 --device xpu 參數。
• 下載。 XL 模型需要額外約 20 GB 的硬碟空間，需下載到與主要模型相同的檢查點目錄中（SOUND_DESIGN_ACESTEP_CHECKPOINTS；Hugging Face 的快取快照不適用於 XL 模型）。若未下載，指令會以 MODEL_NOT_FOUND 狀態停止，並在 error.details.install 中提供安裝指令，例如 uv run acestep-download --model acestep-v15-xl-turbo --di。

...（已截斷）