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；当接缝检查失败时，退出码为 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，在 --search 参数相对于 --duration 的范围内）、交叉淡入淡出材料的相似度（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；当开始时间会在 0 秒之前时，包含 file_offset）、达到 --level dBFS 所需的 gain_db，以及是该效果的峰值（呼啸声、上升音等）还是起始部分（爆裂声、叮当声等）落在时间点上。库中的效果需要有声明的许可证，其选择方式类似于 library-pick，以效果名称作为标签。将提示表及其来源的许可证传递给 audio-production-skill 的 MIX 组件。
• 同一文件的重复使用（可选，默认关闭）。 --min-reuse-spacing S：如果一个事件的效果将播放与某个保留提示点相同的文件（相同的 SHA-256），且该保留提示点发生在少于 S 秒之前，那么该事件将按排名顺序选取该效果的下一个库文件（只要可用，就始终使用排名第一的文件；绝不随机选择）。如果没有其他符合条件的文件，或者对于 --file 指定的效果，该事件将被丢弃（dropped[].by: min_reuse_spacing），绝不会被移动，也绝不会被赋予其他效果。substitutions 字段和每个提示的 substituted 字段说明了哪个文件替换了哪个。--min-spacing 检查优先执行；被丢弃的事件对这两条规则均不计入。建议：对于对话式镜头编辑，使用 30 秒；对于快速切换的编辑，使用更短的时间，因为在一个 S 秒的窗口内，使用 N 个文件的效果最多有 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（退出码 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）包含署名行：优先使用已声明的署名行，否则使用 --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 的假引擎）。请说明结果是生成的，应进行试听。
• 生成的音乐不会检查与现有录音的相似性；音乐识别和版权检查不是本技能的职责。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），Python 3.11-3.12，在其自己的检出目录和 .venv 虚拟环境中	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/ 的检出目录）；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 卸载或量化。其模型卡列出了 12 GB（带卸载和 INT8）、16 GB（带卸载）、20 GB（无卸载）和 24 GB（带 4B LM）。低于 20 GB，或没有 GPU 时，generate-bgm --model acestep-v15-xl-turbo 会在任何操作运行前以 INSUFFICIENT_VRAM（退出码 3）停止运行。告知用户，并提供默认模型（error.details.default_model）：去掉 --model 参数。Apple Silicon 计算的是其统一内存，该内存由 CPU 共享。当无法测量 GPU 内存时（ROCm、Intel XPU），会生成背景音乐并发出警告，说明未检查内存。Intel GPU 仅通过 xpu-smi 检测到；在未安装 xpu-smi 的 Intel GPU 上，请传递 --device xpu。
• 下载。 磁盘上还需要大约 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。