音效库
834 个文件 / 63 个分类 / 约 1 GB。 唯一入口：脚本 sfx 位于与此 SKILL.md 文件相同的目录。脚本会自动确定自身路径，因此可以从任何位置通过完整路径调用——以下示例均简写为 sfx。
步骤 0 — 检查数据是否已存在
仓库仅包含代码和目录；音频文件位于 data/（未提交）。
sfx status
如果提示“未找到数据”，则下载数据——一次性操作，约 1 GB，下载前请告知用户：
sfx setup
setup 会按正确的优先级顺序自动执行，请勿打乱：
- 优先使用 Google Drive — 下载一个
.zip文件（约 880 MB，约 1 分钟），校验 sha256 后解压。 - 目录中已有的 URL 作为备用 — 仅在 Drive 失败时使用（404、文件未公开共享、下载配额超限、sha256 不匹配）。此时
setup会自动切换到从catalog/source/*.json中的 URL 逐个下载文件（按顺序，约 18 分钟），并校验 sha256 与catalog/meta.json。
只需要 python3（≥ 3.8），无需额外安装。如果中途中断，重新运行 sfx setup — 它会继续下载，不会从头开始。备用步骤较慢：建议后台运行并告知用户预计等待时间。
仅当用户明确要求时，才直接调用 sfx setup --source（跳过 Drive）。
如果 setup 提示“两个源都失败”，则运行 sfx doctor 并告知用户——不要自行寻找替代音频源。
搜索 SFX — 只需记住这一个命令
sfx find "<关键词>"
输入带调、不带调的越南语或英语，结果相同 —— 搜索前会去除音调，且每个分类都预制了双语关键词。
sfx find "转场" # 按意图
sfx find "通知" --max-dur 2
sfx find whoosh --group transition
sfx find --group impact --max-dur 1.5
sfx find riser --min-dur 3 --max-dur 5
结果会显示时长（秒）—— 这是匹配 SFX 到时间轴时最重要的信息。
| 选项 | 使用场景 |
|---|---|
--max-dur N / --min-dur N | 根据时间轴上的时段限制时长 |
--group <组名> | 浏览整个意图组（见下方分组表） |
--category <slug> | 已知确切的分类 |
--ext wav | 仅获取 wav（或 mp3）格式 |
--paths | 仅输出文件路径，每行一个——可直接导入其他命令 |
--json | 机器可读的输出，包含 duration、sha256、score |
--abs | 绝对路径——当从其他目录调用 sfx 时使用 |
-n N / --all | 结果数量（默认为 20） |
多词查询默认使用 AND 逻辑；如果没有文件匹配所有词，则自动放宽为 OR 并在 stderr 中明确说明。
不确定用什么 → sfx list 可打印所有分类及其适用场景和关键词。
10 个意图分组
先选择分组，再筛选——比猜测分类名称更快。
| 分组 | 用途 | 典型分类 |
|---|---|---|
transition | 连接两个场景 | fast-whoosh swoosh-swish whip zoom reverse |
impact | 强化观点、展示数据 | hit boom impacts slam bass |
ui | 文字出现、按钮点击、键盘打字 | pop click typing ui-mini tick shine |
alert | 通知、提醒 | notification ding bell alarm |
tension | 高潮前的铺垫 | riser builder braam tension trailer |
ambience | 场景背景音 | ambience environment |
foley | 真实物体声 | paper doors footsteps liquid draw camera-shutter |
comedy | 幽默效果 | comedy-cartoon memes |
scifi | 科技、奇幻效果 | technology glitch laser magic data |
horror | 恐怖效果 | horror jumpscare |
选择前先试听
仅凭 slug 名称不足以判断音频的实际听感。 whoosh-fast-05 和 whoosh-fast-06 的音色可能截然不同。
afplay "$(sfx find whoosh --paths --abs -n 1)" # macOS；Linux：ffplay -nodisp -autoexit
如果无法播放（如在无头服务器上运行），则提供 2–3 个选项及其时长供用户选择，不要自行决定并断言合适。
将 SFX 混入视频
sfx mix video.mp4 -o 带音效.mp4 \
2.4:fast-whoosh/whoosh-fast-05.wav \
5.0:ding/[email protected]
每个 cue 的格式为 <秒数>:<路径>[@音量]。路径相对于 data/sfx/ 或直接写文件名（不会冲突时）。默认音量为 0.6。需要 ffmpeg。
- 视频中已有的音频会被保留并混音，不会被覆盖——在添加配音之后运行
sfx mix是安全的。 - 使用
amix=normalize=0+alimiter：添加 cue 不会降低原始音量，且多个源叠加时不会失真。 --dry-run可输出 ffmpeg 命令，方便集成到其他脚本中。
从 HTML 生成的视频（使用 Playwright/Puppeteer/Remotion 录屏）：页面中的 <audio> 标签或 new Audio().play() 仅在浏览器中播放时有效——它们不会被录制到 MP4 文件中。应通过 sfx mix 在 ffmpeg 阶段混入 SFX，时间点从动画时间轴中获取。
决定视频听感是否专业的三个要点：
- SFX 必须比时间轴上的时段短——从一开始就用
--max-dur筛选，而不是之后裁剪。 - 将 SFX 放在动作发生的具体帧上，而不是场景开头——whoosh 必须在物体开始移动的瞬间响起。
- 不要让 SFX 覆盖对白。 如果有配音，请将音量降至
@0.3或使用ui-mini分类。
三个容易出错的地方
- 不要提交
data/— 约 1 GB，已加入 gitignore，通过sfx setup重新获取。 - 不要修改
data/sfx/中的文件。 那些是原始文件；裁剪或标准化音量应输出到其他位置。 - 首次获取数据时不要直接调用
sfx download。 它会逐个下载 834 个文件，速度慢，且只是备用方案。始终使用sfx setup，以便优先尝试 Google Drive。
当怀疑存在问题时，运行以下命令检查：sfx doctor（工具 + 数据源检查）、sfx verify --hash（重新计算每个文件的 sha256）。
库维护（添加分类、重新打包、更改 Drive 链接）：请参阅 README.md。