real-sound

real-sound

你是一个无法听见影片的声音总监。配乐仅由真实、专业录制或制作的音频构成（一首已获许可的音乐曲目、真实的拟音和音效、真实的环境音），由确定性混音器放置在画面的提示帧上，通过测量而非聆听进行评估，由五个视角进行评议，由一个 Agent 修正，完成母带处理、署名并封装。代码负责选择、裁剪、放置、调整音量、声像、均衡、通过重采样改变音高、对音乐进行时间拉伸以及制作母带；代码绝不生成声音。

专业发布影片的标准：每个声音都由画面中的事物引发，采用统一的材质音色，音乐在主角亮相时达到高潮，其余部分保持克制，标志音效有完整收尾，并以静默结束。规则见： references/sound-design.md（以及 earshot 仓库中的 docs/launch-video-sound.md，其中包含捆绑的参考配置：7 部专业发布影片）。

下文中的 <skill> 指此文件夹。Python： 下文（以及每个提示词模板）中的 {{PY}} 指一个包含 numpy、scipy、soundfile 和 earshot 包的 Python 解释器：可以是 earshot 仓库的 venv（Windows 上为 <earshot repo>/.venv/Scripts/python.exe，其他系统上为 <earshot repo>/.venv/bin/python），也可以是任何运行 <python> -c "import earshot" 成功的 Python。Windows 上单独使用 python 往往会调用 Microsoft Store 占位程序，导致失败。运行命令或向子 Agent 提交提示词时，请将 {{PY}} 替换为完整路径（其他占位符见 references/process.md）。运行脚本时加上 -I（隔离模式：下载的文件绝不会覆盖模块）；除 scripts/licences.py（由 audit.py 和 credits.py 导入的许可政策模块）外，每个脚本都会输出 --help。

流程

步骤	负责人	输出	关卡
0. 提示列表	主负责人	out/cues.json	根据画面代码计算同步帧
1. 简报	主负责人	audio/SOUND_BRIEF.md	每条提示都有声音需求（或“无”）
2. 素材搜集（按类别并行）	素材搜集 Agent	audio/assets/<cat>/、清单	每个文件都经过测量；所用裁剪片段的 earshot realness 判定为“真实或专业制作”（只有在附有证据，并在清单中记录裁剪片段级别的重新检查时，才可标为“不确定”）
3. 许可审核	审核员	audit.json	影片所用素材通过 audit.py，退出码为 0
4. 音乐剪辑	音乐总监	audio/design/music.json	验证节拍网格，高潮落在亮相处，拼接干净
5. 设计片段（按类别并行）	设计师	audio/design/<cat>.json	单独渲染 + QA 通过
6. 整合	主负责人	音轨、分轨、报告、轨迹	母带关卡（+-0.5 LU，<= -1.5 dBTP）
7. QA + 聆听	主负责人	out/qa/qa.json、earshot 时间线 / 表格 / 评议	QA 无失败项
8. 评议（5 个视角，并行，只读）	评论员	按优先级排列的问题 + 已测试的操作
9. 修正	一位修正者	设计	QA：无回归问题
10. 母带、署名、封装	主负责人	CREDITS.md、描述文本、影片	署名检查退出码为 0，延迟为 0

每个步骤的详细说明、角色及每位评论员的测量内容见 references/process.md。每个子 Agent 的提示词都是 templates/prompts/ 中可直接填写的简报。

0. 根据画面生成提示列表

每个声音都对应画面代码计算出的帧：接触帧、弹出动画的 50 % 帧、移动的速度峰值、渐强音的击中帧、字标变得可读的帧。Cinetic 影片已经有 out/cues.json（export-cues.ts）；其他影片则根据时间线常量，按相同格式编写（templates/cues.json）。稳定 ID（act:thing:n）可让规则通过正则表达式匹配各类动作。

1. 简报

将 templates/SOUND_BRIEF.md 复制到 audio/SOUND_BRIEF.md：包含概念（音色、音乐走向、位置）、画面映射（每条提示：画面内容、声音需求）、环境音区域、允许的许可类型、质量标准和文件布局。这是每个子 Agent 都会原样收到的约定。选择品牌个性表格中的一行（见 references/sound-design.md §3）。

2. 按类别搜集素材（templates/prompts/sourcing.md）

常见的发布影片类别：ui（点击、轻触、切换、弹出）、keyboard、motion（呼啸声、渐强音）、impacts（揭晓重击、Logo）、ambience、music；角色影片还会增加 foley、角色所处世界的声音及物件声。 Freesound（CC0 / CC BY；HQ 预览文件 cdn.freesound.org/previews/<id//1000>/<id>_<user>-hq.ogg）、Mixkit（WAV 文件 assets.mixkit.co/active_storage/sfx/<id>/<id>.wav）、音乐作曲库；在每个素材自己的页面查看许可信息（references/licences.md）；礼貌、按顺序下载；测量每个文件：

{{PY}} -I <skill>/scripts/analyze.py audio/assets/ui/* --png out/audio-review/ui --out out/audio-review/ui.json
{{PY}} -m earshot realness audio/assets/ui/                  # gate: "real or pro-produced" (re-check trims: --start --end)
{{PY}} -m earshot rank "a single crisp trackpad click" audio/assets/ui/ --top 5
{{PY}} -m earshot match <file> "a soft cork pop" --alts "a gunshot" "a balloon burst"
{{PY}} -m earshot find <long take> "a single mechanical key press" --top 8   # trims; skip any marked head cut / tail cut

3. 许可审计（templates/prompts/licence_audit.md）

审计器会将每个页面显示的信息（licence_seen、licence_confirmed）记录到 audio/assets/manifests/audit.json；脚本会检查其余内容（分类、ID 与 URL 是否对应、文件能否解码、时长、 署名文本）：

{{PY}} -I <skill>/scripts/audit.py --root . --report out/qa/mix_report.json [--fetch]

允许：CC0、公共领域、CC BY 2.0-4.0、Mixkit 免费许可、Pixabay。禁止：NC、ND、SA、Sampling+、个人许可、自定义许可、有争议的许可。未经核实的素材会被屏蔽。

4. 音乐（templates/prompts/music_supervisor.md）

选择一首结构适合影片的已授权曲目。按影片小节编写乐曲弧线（templates/arc.json），然后：

{{PY}} -I <skill>/scripts/arrange.py audio/assets/music/<track> --film-bpm 120 --arc audio/arc.json --out out/audio-review/music/arrange.json

它会匹配节奏，将网格对齐到测得的起音位置（节拍跟踪器会滞后 20-50 毫秒），提出强拍相位，在最有力的候选落点处将落点锚定到影片小节，并在小节线上起草片段（可直接粘贴的 music 区块）。强拍位置是薄弱环节：如果输出的置信度为 LOW（在测试过的两首曲目中，有一首偏差了半个小节），请根据第一个音符、段落进入位置以及小节表中的和弦变化，在输出的两组网格中做出选择，然后使用 --phase N 重新运行。之后凭判断进行编辑：每个剪接处的和声要延续，落点的强拍要落在主视觉画面上，最终和弦要落在 Logo 上，并使用 tail_fade 渐弱至结尾。

5. 设计片段，按类别划分（templates/prompts/designer.md）

audio/design/<category>.json，包含采样（裁剪）、切片（将包含多个重击的录音切成单个重击）、素材池、提示事件规则、自由放置、环境音底层以及音乐区块。每个键和实际示例的说明见： references/design-format.md；完整的发布影片示例见：templates/design_fragment.json（其中的文件名是占位符，例如 mk-0000_mouse-click.wav：只有将每个占位符替换为清单中的真实录音后才能渲染；在此之前，mix.py 会停止运行并列出缺失的文件）。 单独验证：

{{PY}} -I <skill>/scripts/mix.py --only ui --dump out/audio-review/ui/dump        # every trim as WAV + numbers
{{PY}} -I <skill>/scripts/mix.py --only ui --trace out/audio-review/ui/adds.json --out out/audio-review/ui/solo.wav
{{PY}} -I <skill>/scripts/qa.py --only ui --report out/audio-review/ui/solo_report.json --stems out/audio-review/ui/solo_stems --trace out/audio-review/ui/adds.json --out out/audio-review/ui/qa.json
{{PY}} -m earshot timeline out/audio-review/ui/solo.wav --cues out/cues.json

6-7. 整合、QA、试听

{{PY}} -I <skill>/scripts/mix.py --root . --design audio/sounddesign.json --cues out/cues.json --trace out/qa/adds.json
{{PY}} -I <skill>/scripts/qa.py --layers                      # clicks, edges, audibility, harshness, loudness, coverage, sync, density
{{PY}} -I <skill>/scripts/qa.py --listen --realness --video out/film.mp4   # + earshot timeline, sheet, critique, realness
{{PY}} -m earshot critique out/audio/soundtrack.wav --video out/film.mp4    # scorecard vs professional launch films
{{PY}} -m earshot sheet out/audio/soundtrack.wav -o out/qa/sheet.png --video out/film.mp4 --cues out/qa/cues_sounded.json

qa.py 会将每项发现关联到导致该问题的规则和样本（即追踪信息）。无需模型即可使用；添加 --listen 后，还会加入 earshot 的转录文本（out/qa/qa_timeline.txt）、带注释的表格和评分卡。

8-9. 评审并修复

五个只读评审器并行运行，各自使用对应的提示词：critic_sync.md、critic_edges.md、critic_masking.md、 critic_tonal.md、critic_director.md。每个评审器都会在自己的文件夹中将修复作为变体进行测试：

{{PY}} -I <skill>/scripts/variant.py --ops out/audio-review/critic_tonal/ops_v1.json --out out/audio-review/critic_tonal/v1 --render --qa

并返回按优先级排序的问题，其中包含精确操作和前后数值。然后由一个修复器（fixer.md）合并这些操作、解决冲突、根据上一个 qa.json 检查合并后的变体，并应用变体（variant.py --apply，原始文件会备份）。对于确认有意保留的例外，使用 "qa_ok": "<reason>" 加以说明。 至少进行一轮；如果音量电平或音乐剪辑发生变化，则再进行第二轮。

10. 母带处理、署名、复用

mix.py 使用 master.py 进行母带处理（-14 LUFS、真峰值限制器、上限 0.77 线性；门限 +-0.5 LU 且 <= -1.5 dBTP）。

{{PY}} -I <skill>/scripts/audit.py --root . --report out/qa/mix_report.json            # exit 0
{{PY}} -I <skill>/scripts/credits.py --root . --design audio/sounddesign.json --audit audio/assets/manifests/audit.json
node <skill>/scripts/mux.mjs --video out/film.mp4 --audio out/audio/soundtrack.wav --out out/film_sound.mp4
{{PY}} -m earshot timeline out/film_sound.mp4 --cues out/qa/cues_sounded.json          # the finished file, heard

CREDITS.md + out/CREDITS_description.txt（粘贴到视频描述中：必须在此处署名 CC BY 素材）。 mux.mjs 会以流复制方式处理画面，并将 AAC 音频剪切至与画面时长一致。

发布视频：声音布局

画面	声音	对齐位置
光标移动、悬停、滚动、进度、流式文本	无（由音乐承载）
点击 / 轻触	全片只用一个真实点击声，按下后约 85 ms 再松开，每次音量相同	按下帧
打字	使用一个真实键盘声，切片处理；每秒不超过约 12 个按键；速度超过每秒约 25 个字符时，每个词用一个按键声；音乐降低 6-10 dB	每个发出声音的字符
卡片 / 芯片 / 徽章出现	柔和的真实弹出声或滴答声，在一组音效中逐渐升高	动画行程的 50 % 处
开关切换、锁定、计数器最终值	真实的卡扣声 / 点击声 / 清脆的滴答声	接触 / 锁定帧
镜头缩放移动、快速摇镜、变焦（每部影片约 2 次）	真实的掠过声，在速度峰值处达到顶点	速度峰值
硬切	无
揭晓前的紧张感	音乐渐强，或真实的上升音效，在重击前 30-250 ms 结束	重击
主视觉揭晓	音乐的骤降（剪辑曲目，使其强拍落在此处）+ 可选的一个真实冲击声	该帧
Logo / 标识组合	音乐在小节线处停止或经滤波渐弱，近乎静音 0.2-0.7 秒，再加入一个调内的柔和音符，尾音渐至无声	字标清晰可见的帧

电平：-14 LUFS，经过 AAC 编码后真峰值 <= -1 dBTP，LRA 5-9 LU；最响处位于骤降处（影片进行到 30-60 % 时），Logo 比它低 8-20 dB；每 10 秒设计约 5 个音效，音效保持干声并居中。测量规范和容易露馅的廉价效果： references/sound-design.md。

工具

需求	工具
测量录音（格式、底噪、带宽、起音、尖峰、速度 / 调性）+ 频谱图 PNG	scripts/analyze.py
收听录音：真实还是合成、听起来如何、最佳匹配、长文件中的最佳片段	{{PY}} -m earshot realness / describe / match / rank / find / compare / ab
测量单个文件或其某段（--start --end）的电平 / 明亮度 / 起音	{{PY}} -m earshot measure（Python：from earshot import api; api.measure(...)，api.find、api.realness 等也类似）
许可证 + 文件审计	scripts/audit.py（策略见 scripts/licences.py）
音乐节拍网格、强拍、小节线剪辑草稿	scripts/arrange.py
渲染设计（+ 使用 --only 单独渲染、使用 --dump 导出修剪片段、使用 --trace 进行 QA）	scripts/mix.py
母带处理和响度测量	scripts/master.py（--measure）
与音效位置关联的客观 QA	scripts/qa.py（--layers、--listen、--realness）
批判者生成的变体、修复器的应用	scripts/variant.py
为 CREDITS.md 和视频描述生成署名信息	scripts/credits.py
将配乐合入画面	scripts/mux.mjs
收听完整混音 / 影片；带注释的画面；发布影片评分卡	{{PY}} -m earshot timeline / sheet / critique

文件

audio/SOUND_BRIEF.md                 the contract              (templates/SOUND_BRIEF.md)
audio/assets/<category>/             downloaded recordings     (<source>-<id>_<slug>.<ext>; never commit or publish them)
audio/assets/manifests/<cat>.json    one entry per recording   (templates/manifest_entry.json)
audio/assets/manifests/audit.json    licence audit             (templates/audit_entry.json)
audio/sounddesign.json               top level: includes, buses, master   (templates/sounddesign.json)
audio/design/<category>.json         one fragment per designer             (templates/design_fragment.json)
out/cues.json                        the picture's cue events              (templates/cues.json)
out/audio/soundtrack.wav, stems/     the master and its stems
out/qa/                              mix_report.json, adds.json, cues_sounded.json, master.json, qa.json
out/audio-review/                    per-category and per-critic work, variants, dumps (the audit trail)
CREDITS.md, out/CREDITS_description.txt

参考资料

• references/process.md：角色、步骤、各批判者的测量内容、阈值及其来源、变体、轮次。
• references/design-format.md：每个设计键、默认值、处理顺序、输出、真实示例。
• references/sound-design.md：发布视频和影片的声音规则、电平、同步、变化、调校、选择、容易露馅的廉价效果。
• references/licences.md：允许 / 禁止事项、各网站的验证方式、署名、Content ID。
• references/troubleshooting.md：错误和修复方法。
• Cinetic 影片：earshot 仓库中的 docs/INTEGRATION.md（介绍提示音文件、时间线和评审循环如何衔接）。