用途
该技能用于给用 Claude Code 相关工具（HyperFrames、Remotion、GSAP、Claude Motion 或 motion-broll 技能）制作的动态图形视频添加一套可量化的音效。其核心理念是：Claude 听不到声音，因此不凭感觉判断音效好坏，而是对每一步进行测量，并交给用户 5 个时间点用耳机核对。技能不会声称“听起来不错”。该方法来自 Vox 的音效处理提示词（@Voxyz_ai）。
主要能力
- 默认音效套件：sfx/manifest.json 中的 default_kit 为每个核心类别提供一个音效，均由作者按听觉挑选。whoosh、click、pop、riser、impact、tick 为内置 OGG 文件（CC0）；typing 使用 Mixkit 的“Fast laptop keyboard typing”（#1392），在运行时下载到输出目录的 sound-effects-cache/ 中，不随技能分发。清单中其余条目为可替代选项，alt_categories 列出了可互相替代的类别。
- 音效提示类型到类别的映射：movement/scene_cut → whoosh（提前 2 帧），appear/success → pop，click → click，typing → typing（循环/裁剪到指定时长、音量较低），build_up → riser（在下一个重音处结束），reveal → impact（最响的音效），error_or_tech → glitch，hover_or_small_ui → tick（很轻），bed → ambience（可选铺底）。每个提示只用一个音效，同类别内变换素材以免重复显得机械。
- 节拍网格校准：运行 librosa.beat.beat_track，对 120 Hz 以下做低通，绘制前 4 小节与节拍线对比；若底鼓不在线上，按中位偏移整体平移网格并重新绘制，输出 beatgrid.png 给用户。
- 大动作对齐节拍：硬切与揭示应落在节拍上；能改动画时序就改，不能改就移动音乐起点（搜索偏移，取切点误差最小者），并逐切点报告毫秒级误差。
- 混音与响度：优先级为人声 > 音效 > 音乐；音乐铺底约低于音效 12 dB，并在人声下衰减 8–12 dB；目标整体约 -16 LUFS，真峰值低于 -4 dBFS，导出后用 ffmpeg ebur128 分别做立体声与单声道测量，按需调增益或加限制器后再次导出测量。
- 验证：对每个提示从导出的 MP4 抓取前后各一帧并绘制波形（checks/cue-XX.png），再挑出 5 个风险最高的时间点（节拍误差最大、长音效如打字与 riser、reveal）供用户戴耳机核对。
- 替换报告：sound_pass.py 生成 report.html，列出每个提示的时间、类别、所用音效（含试听按钮）、来源页、许可与署名，以及同类替代项（含试听和“让模型决定”选项）。用户选择后下载 swaps.json，再用 --swaps 重新运行；两次运行间保持提示索引稳定。
使用方式
环境准备：需要 ffmpeg 与 Python 3.10+，安装到可删除的目录：
python3 -m venv .sound-effects
.sound-effects/bin/pip install librosa soundfile numpy scipy matplotlib
建立提示列表：用 ffprobe 读取视频时长与帧率，从合成源（HyperFrames/Remotion 时间线、GSAP 标签、motion-broll 的 plan.json）获取需要音效的时刻；否则用以下命令检测场景切点：
ffmpeg -i in.mp4 -vf "select='gt(scene,0.3)',showinfo" -f null -
写入 cues.json，格式如 [{"t": 2.0, "type": "scene_cut", "desc": "cut to card"}, {"t": 4.2, "type": "typing", "dur": 1.3, "desc": "..."}]。
运行脚本（steps 3–6 端到端）：
.sound-effects/bin/python scripts/sound_pass.py --video silent.mp4 --cues cues.json \
--music track.mp3 --manifest sfx/manifest.json --out out/
可加 --use-case "..."，确认后加 --music-source/--music-license。输出 after.mp4、report.html、SOUND.md、CREDITS.txt、beatgrid.png 与 checks/。若改过动画时序，需先重新渲染。
许可与来源规则
- 禁止用代码合成音乐或音效（不用振荡器或正弦提示音），必须使用真实录音文件。
- 内置库优先；内置无合适项时使用清单中的运行时条目（Mixkit），下载到用户项目而非技能目录，且不得提交。Mixkit 允许用于视频，但不允许独立再分发（包括放在工具或模板中）。
- 音乐：使用用户提供的曲目或 MUSIC.md 中的建议曲目（运行时下载、不提交），并把来源与许可写入 SOUND.md；用户无曲目时，从 MUSIC.md 建议 2–3 首贴合视频的让其挑选。
- 许可：只有 CC0 与 Mixkit Free License 视为免费且安全，脚本会检查每个放入的音效；若报告未知许可，须点名该音效、其许可与来源链接，并告知用户核验或替换前不要发布，不得把未知许可描述为“大概没问题”。缺少音乐来源与许可参数时，本次运行标记为 LICENCE NOT CONFIRMED 并如实告知。
- 每次运行写 CREDITS.txt，列出实际使用的音效与音乐，可粘贴到 YouTube、Instagram 或 TikTok 描述中；CC0 无需署名，但该列表可作为来源凭证。
- 发布前做许可检查：询问发布场景（YouTube、Instagram、TikTok、其他社交、在线广告、播客、客户项目、电视/广播、电子游戏、CD/DVD、供他人使用的模板或工具），作为 --use-case 传入；逐个来源打开当前许可页确认条款未变且允许该场景，必要时替换。
高质量原件
内置音效是压缩的 OGG Vorbis 预览（裁剪、归一化、常为单声道），多数视频够用；若音质不足，可按 manifest 中 source_url 获取原件：Freesound 页面需免费账号（可请用户下载或提供 API key）；Kenney 可下载整包 zip，按清单 original_file 定位具体文件。原件存入用户项目（如 sound-effects-cache/originals/），不得放入技能目录，可通过 --swaps 或编辑清单副本传入脚本，并施加与内置文件相同的裁剪与电平处理。
寻找更多音效
需要更多或不同音效时，可从 Freesound（使用 CC0 筛选）、Kenney（全部 CC0）、Mixkit、Pixabay、Sonniss GDC 包、YouTube Audio Library 中搜索，建议 3–5 个候选并附链接、作者与许可，由用户挑选；使用前须打开页面确认当日许可并核对适用场景，加入 CREDITS.txt。仅 CC0 音效可加入本仓库 sfx/ 目录，并附清单条目与 LICENSES.md 记录。
适用场景与限制
适用于已有动态图形视频需要添加音效和音乐的后期处理，尤其是希望用节拍对齐与响度测量保证质量的场景。限制包括：无法主观判断音效好坏，需用户试听；Mixkit 与 Pixabay 等素材不得再分发；需要 ffmpeg 与 Python 环境；最终响度与切点误差可测量，但音乐选择与音效取舍仍需人工决定。