サウンドデザインスキル

sound-design-skill

sound-design <command> ... --json を実行（pip install -e . でインストール、Python >= 3.9、標準ライブラリのみ）。--json を付けると、stdoutは正確に1つの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秒の音楽BGMの生成	sound-design generate-bgm --prompt "calm piano bed" --tags "ambient,70 bpm" --duration 60 -o bed.wav --seed 42 --json (10〜600秒)
15秒のリリックビデオ用120BPMのBGM、ビートグリッド付き	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モデルを使用 (オプトイン、20GB以上のGPUが必要)	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を追加)
BGMのシームレスな8秒ループの作成（編集内のループ用）	sound-design loop-bed bed.wav -o loop.wav --duration 8 --search 1 --json (ソースは少なくとも duration + crossfade の長さが必要。ループポイントは--search秒以内で検索されます)
0.5秒のカットにピークが合う1秒のウーッシュ音	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。継ぎ目不合格時に終了コード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 (カット=ウーッシュ音、強調=ポップ音。--effect cut=<name>で変更可能、--file ding=ding.wavで生成済み効果音を指定)
同条件、30秒以内に同じファイルを再使用せず、明るいポップ音を使用	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_generated: false）。
• ライブラリに適切なものが見つからない場合： generate-bgm（ACE-Step）またはgenerate-sfx（EzAudio）を使用します。ただし、doctorが該当エンジンをOKと表示している場合に限ります。
• その後、常に WAVファイルとそのprovenance（来歴情報）を audio-production-skill MIX に引き渡します。MIXがファイルの配置、発話下でのダッキング、ラウドネス設定を行います。このスキルはミキシング、ダッキング、ノーマライゼーションを行いません。

ループとスティンガー

• loop-bedとstingerはエンジンを実行しません。既に持っているWAVファイル（generate-bgm、generate-sfx、library-pickの結果、またはユーザーのファイル）を入力として、ffmpeg-skillのみを使って編集し、結果を測定します。そのライセンスとエンジン情報は元のソースの来歴情報に残るため、両方とも引き継いで渡してください。
• ループの終端は始端にクリックノイズなく接続されます。ファイルを終端から始端に繰り返し、クロスフェードは行いません。結果は、見つかったループ長（loop.length、--durationから--search以内）、クロスフェードされた素材の類似度（loop.similarity、0.5未満は警告）、測定されたラップ（seam）を報告します。ループは整数小節数が最適です。
• スティンガーは正確に--durationの長さで、その最も音量の大きい10msが--peak-atの10ms以内に位置します（両端から少なくとも20ms以上離れている必要があります）。条件を満たさない場合、何も書き込まれません。MIXには、カットの--peak-at秒前にスティンガーを開始するように指示してください。
• seam-checkはこのスキル独自のループチェックです。クリック（±1ms）、レベル、各1秒間のオクターブバンドスペクトルをチェックします。qc-skillはまだループシームチェックを持っていません。

効果音キューシート

• sfx-cuesは何も配置せず、何も決定しません。時間は呼び出し元（編集のカットリストと強調キャプションから）が指定し、各時間に1つのキューが作成されます。--min-spacingよりも直近の保持キューとの間隔が短い時間はドロップされ（理由と共にdroppedにリストされます）、移動されることはありません。強調時間をこの機能のために新たに考案してはいけません。
• 各キューは、使用するファイル（file、from：ライブラリまたは指定されたWAVファイル、source：ライセンスを含むsources内のエントリ）、開始位置（start、file_offsetは0より前の開始を示す場合があります）、--level dBFSに到達するためのゲイン（gain_db）、そしてそのピーク（ウーッシュ音、上昇音など）またはオンセット（ポップ音、ディン音など）がその時間に位置するかどうかを示します。ライブラリの効果音は、宣言されたライセンスが必要であり、効果音名をタグとしてlibrary-pickと同様に選択されます。キューシートは、ソースのライセンスと共に audio-production-skill MIX に渡してください。
• 同じファイルの再使用（オプトイン、デフォルトではオフ）。 --min-reuse-spacing S：あるイベントが、S秒未満前に保持されたキューと同じファイル（同じSHA-256）を再生する場合、その効果音に対してランク順で次のライブラリファイルが使用されます（利用可能な場合は常に最初のランクのファイル、ランダムではありません）。他に適格なファイルがない場合、または--fileで指定された効果音の場合、そのイベントはドロップされ（dropped[].by: min_reuse_spacing）、移動されたり別の効果音に置き換えられたりすることはありません。substitutionsと各キューのsubstitutedは、どのファイルがどのファイルを置き換えたかを示します。--min-spacingチェックが先に行われます。ドロップされたイベントはどちらのルールにもカウントされません。推奨値：トークヘッド編集では30秒。速いカット編集では短め（N個のファイルがある場合、任意のS秒間に効果音は最大N個のキューしか持てないため）。特定の単一のサウンドシグネチャが必要な場合はオフにしてください。キューがドロップされた場合はユーザーに伝えてください。
• キャラクター（オプトイン）。 --character pop=bright（またはイベントの"character": ["bright"]。こちらは--characterの指定を上書きします）は、その効果音に対して、タグまたはムードに指定されたすべての単語が含まれるライブラリファイルのみを保持します。ライブラリが既に言っていることと一致させるものであり、タグを推測したり追加したりしてはいけません。一致するファイルがない場合は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（終了コード8）で停止します。メッセージには英語と日本語で注意事項が表示されます。ユーザーにそのメッセージを表示し、ユーザーが同意した場合にのみフラグを渡してください。自分でフラグを追加してはいけません。contract --json（generate-sfxツール）とdoctor --json（checks.operations.sfx）はconfirmation_required: trueを保持するため、オーケストレーターは事前に確認を求めることができます。同意は来歴情報に記録され、すべてのSFX結果はトレーニングデータに関する警告を繰り返します。これを引き継いで渡してください。

ライブラリモードでのライセンス

• library-importは、ライセンスが欠落している、空である、またはプレースホルダー（unknown、n/aなど）である場合、LICENCE_REQUIRED（終了コード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の結果と来歴情報内のlicence.attribution、handoff.credit_line）はクレジット行を保持します：宣言されたもの、次いでクレジット、CC BYの場合は宣言された部分のみから構成されたもの（警告：確認してください）。これを動画の説明またはクレジットに記載してください。--content-id registeredと宣言されたトラックについては警告が表示されます：アップロード時にクレームが発生する可能性があるため、公開前にユーザーに伝えてください。
• フィット：差が最大(0.1秒、1%)以内であればファイルはそのまま使用されます。より長いファイルはトリミングされます（フェードは行いません。MIXがフェードを担当します）。より短いファイルは、--loopableと共にインポートされた場合のみクロスフェードでループされ、そうでない場合は除外されます。同じライブラリとクエリは常に同じファイルを返します。

ユーザーに伝えるべき制限事項

• EXPERIMENTAL（実験的）。 audio.bgm_generate、audio.sfx_generate、audio.library_importのライフサイクルはEXPERIMENTALです。実際のACE-StepおよびEzAudioのシード決定性と継続時間精度はまだ測定されていません（テストでは同じAPIを持つフェイクエンジンを使用しています）。結果は生成されたものであり、聴取確認が必要であると伝えてください。
• 生成された音楽は既存の録音との類似性をチェックしていません。 音楽認識と著作権チェックはこのスキルの役割ではありません。ACE-Stepの商用利用に関する声明はベンダーの主張であり、このスキルはそれを伝達するのみです。
• テンポ。 --bpmを指定すると、長さは最も近い整数の小節数になります（その旨の警告が表示されます）。これによりBGMは小節線で終了し、ビートグリッド（すべてのビート、強拍、小節線）は<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）、Python 3.11-3.12、専用のcheckoutディレクトリと.venv	doctorが正確なコマンドを表示。SOUND_DESIGN_ACESTEP_PYTHON（およびSOUND_DESIGN_ACESTEP_CHECKPOINTS、設定されていない場合はHugging Faceキャッシュ）を設定
generate-sfx	EzAudio-XL（MITコードおよびウェイト、Flan-T5-XL Apache-2.0）、専用のcheckoutディレクトリと.venv	doctorが正確なコマンドを表示。SOUND_DESIGN_EZAUDIO_PYTHONとSOUND_DESIGN_EZAUDIO_DIR（ckpts/を含むcheckout）を設定。Flan-T5-XLはHugging Faceキャッシュ
ライブラリモード	なし	ffmpeg-skill以外にインストールするものはなし

BGMモデルの選択

generate-bgmは、--modelで別の指定がない限り、ACE-Stepの2B turboモデルacestep-v15-turboを実行します（リクエストキーmodel）。必要なGPUメモリは4GB未満で、CPUでも動作します（低速）。--model acestep-v15-xl-turboはXL turboモデルを選択します。4B DiTで、デフォルトと同じMITライセンスであり、出力の商用利用は独自のモデルカードに記載されています。doctor --jsonのchecks.operations.bgm.modelsから選択します。各モデルにはready、ファイル、vram、installが含まれます。

• GPUメモリ。 XLには少なくとも20GBのGPUメモリが必要です。このスキルはCPUオフロードや量子化なしで実行するため、モデルカードでは12GB（オフロードおよびINT8）、16GB（オフロード）、20GB（オフロードなし）、24GB（4B LMあり）とリストされています。20GB未満の場合、またはGPUがない場合、generate-bgm --model acestep-v15-xl-turboは何かを実行する前にINSUFFICIENT_VRAM（終了コード3）で停止します。ユーザーに伝え、デフォルトモデルを提案してください（error.details.default_model）。--modelを削除します。Apple SiliconはCPUと共有するユニファイドメモリとしてカウントされます。GPUメモリが測定できない場合（ROCm、Intel XPU）、BGMは作成されますが、チェックされなかったという警告が表示されます。Intel GPUはxpu-smiを通じてのみ認識されます。これがないIntel GPU上では、--device xpuを渡してください。
• ダウンロード。 ディスク上に約20GB追加され、メインモデルと同じチェックポイントディレクトリ（SOUND_DESIGN_ACESTEP_CHECKPOINTS、Hugging FaceキャッシュスナップショットはXLでは機能しません）に保存されます。ダウンロードがない場合、呼び出しはMODEL_NOT_FOUNDで停止し、error.details.installにインストールコマンドが表示されます。例：uv run acestep-download --model acestep-v15-xl-turbo --di（以下、truncated）