procedural-sfx

程序化音效

使用噪声、正弦波、滤波器和包络合成所有音效，然后将每个音效放在它发生的准确帧上。这样生成的声音无需第三方采样许可，每次渲染结果都完全一致，并且会自动与画面保持同步。

这种方式最适合风格化作品：动画、解说视频、UI、动态图形、游戏原型。对于写实电影拟音（例如特定的真实枪支、真实碎石路上的脚步声），录制的采样仍然更好。混音器也接受音频文件（"type": "file"），因此混合使用也没问题。

设置

pip install -r scripts/requirements.txt   # numpy, scipy, soundfile
python scripts/check_env.py               # verifies them; ffmpeg >= 4.2 is optional (only for master.sh / mux.sh)

所有脚本都位于 scripts/，可从任何位置运行。以下路径均相对于此技能目录。发生错误时，脚本会以状态码 1 退出，并显示 error: … 和 fix: … 行；按照修复提示操作后重新运行。

工作流

1. 找出音效。 列出每个需要音效的时刻：时间、发生的事情、涉及的材质（塑料、木头、金属、空气、电流）。材质决定制作方案，而不是动作名称：“硬币落地”和“钥匙掉落”都属于小型金属撞击。也要规划静音段。在重击前留出一拍安静，比单纯增大音量更能强化冲击感。

2. 选择或设计每个音效。 运行 python scripts/render_sfx.py --list 查看内置配方。如果有合适的配方，使用参数渲染并试听。如果没有合适的配方，就根据 assets/recipe_template.py 在项目文件中编写新配方。

   • 编写新配方前，请阅读 references/design-method.md。其中说明了起音、主体、尾音的分层方式，以及哪些数值会改变听感。
   • 阅读 references/recipes.md，了解每个内置配方的效果、参数，以及枪械类型、表面和距离等变化形式。

3. 用数据检查每个音效。 你无法听到输出，因此要测量它：python scripts/analyze.py sound.wav --bands。将起音、余响时间、频谱质心和频段平衡与预期效果进行比较。references/design-method.md 提供了大致目标。对于重复播放的音效，render_sfx.py <recipe> --variants 4 会输出每个版本的指标，并标记完全相同或差异极小的版本。

4. 编写事件列表。 events.json 中每个音效对应一条记录，包含时间、类型、参数、增益和声像。assets/events.example.json 是可运行示例；语音台词和录制的音频以 "type": "file" 事件加入。时间应取自驱动动画的同一组常量，而不要重新手动输入。请参阅 references/event-sync.md，了解架构、从不同动画技术栈导出事件，以及预备偏移等内容，例如在撞击前开始的呼啸声。

5. 混音。 运行 python scripts/mix.py events.json -o mix.wav [--recipes my_recipes.py] [--music score.wav] [--bed rumble] [--stems stems/] [--audition audition/]。该脚本会先验证整个事件文件，然后输出每条总线的电平、标记被更响声音掩盖的事件的掩蔽报告，以及限幅器前后的真实峰值（上限为 −1 dBTP）。检查每一行 CHECK：修复问题，或在充分知情的情况下接受，并说明原因。请参阅 references/mixing.md，了解增益分级、闪避以及解决掩蔽问题的方法。

6. 完成母带处理以便交付。 两个脚本都会测量混音，将单一线性增益应用于混音以达到响度目标（网络／社交媒体为 −14 LUFS；其他目标见 references/mixing.md §5），并打印重新测量的结果。它们绝不会进行压缩；如果达到目标会导致真峰值超出限制，脚本就会停止并指出可达到的最高目标响度。

   • 带视频：sh scripts/mux.sh video.mp4 mix.wav out.mp4 [LUFS=-14] [dBTP=-1]。混音会替换视频自身的音频。如果视频已有必须保留的音乐或对白，请先提取音频（ffmpeg -i video.mp4 -vn -c:a pcm_s24le original.wav），并在封装前将其传给 mix.py --music original.wav；视频含有音频时，mux.sh 会发出警告。所有视频帧都会保留，并且会先将混音调整至视频时长，再进行母带处理（将 "dur" 设为视频时长，就无需调整）。输出格式为 .mp4、.m4v、.mov 或 .mkv。
   • 仅音频：sh scripts/master.sh mix.wav final.wav [LUFS=-14] [dBTP=-1]。

7. 交由他人试听。 数值能发现有故障的声音，却无法判断声音是否难听。混音报告末尾有一张“尚未经过听感调校”表：每个已放置的声音，只要其配方状态为 starting point 或 new，就会按配方和参数组各占一行。运行 mix.py 并传入 --audition DIR，即可单独渲染这些声音（使用与混音中相同的参数和采样），并填入文件列；为事件设置 "name"（例如 "angry cat"），即可填入声音列。将该表原样粘贴到交接内容中：声音 · 配方 · 参数 · 状态 · 时间 · 试听文件。请用户试听每一行状态不是 tuned 的声音。如果有问题，references/troubleshooting.md 会将“太薄”“结尾有咔嗒声”或“听起来像机器人”等反馈对应到修复方法，并提供最终 QA 检查清单。

脚本

脚本	用途
scripts/sfxkit.py	库：噪声、包络、滤波器、扫频、饱和、回声、无线电效果、真峰值测量和限制器、用于放置声音的 add()、wav 读写
scripts/recipes.py	18 种内置配方，以及可合并项目配方文件的 load()
scripts/render_sfx.py	渲染单个配方、多个变体或所有配方为 wav，以供试听
scripts/analyze.py	每个文件的指标：峰值、RMS、起音、衰减时间、频谱质心、频带能量
scripts/mix.py	将 events.json 转换为带总线、闪避、限制器、分轨和掩蔽报告的立体声混音
scripts/master.sh	仅音频交付：测量、应用一次线性增益以达到 LUFS 目标，并检查真峰值（ffmpeg）
scripts/mux.sh	运行 master.sh，然后以 AAC 封装到视频中（ffmpeg）
scripts/check_env.py	检查依赖项

内置配方

撞击声：click、clack、crash、thump、step（硬地／木地板／软地面）、creak · 动态效果：whoosh · UI：ding、pop、beep · 武器与科幻：gunshot（手枪／步枪／霰弹枪）、burst、explosion、laser · 氛围与戏剧效果：rumble、ignite、roar、heartbeat。每种配方都有状态，可通过 render_sfx.py --list 查看：tuned（已在成品中进行听感调校）或 starting point（已测量，但从未进行听感调校：gunshot、burst、explosion、laser，以及木地板／软地面的 step）。来自你自己的 --recipes 文件的配方状态为 new。详情见 references/recipes.md。

原则

• 一个配方 = 一种归一化的声音；增益由事件列表控制。 配方以 norm(x) * v 结尾，响度只通过 events.json 中的 gain 设置。之后只需编辑一张表即可完成混音。
• 随机性只能通过 noise()、rand()、uniform() 实现。 mix.py 会根据事件类型、时间和参数为每个事件设置随机种子，因此添加事件不会改变其他事件的声音，而且每次渲染生成的字节都完全相同。
• 让重复声音有所变化。 完全相同的重复声音（脚步声、枪声、打字声）会显得不真实。将音高随机调整 ±5–10%、音量调整 ±20%，并稍微调整声像。
• 时间应以动画为准，而不是凭耳朵判断。 同步不准时，问题几乎总是出在事件时间的生成方式上，而不是混音需要微调。