real-sound 是做什么的？
你是一部无法直接聆听的电影的音效总监。音轨完全由真实的、专业录制或制作的音频（一条授权音乐轨、真实的拟音和音效、真实的环境音）构成，通过确定性混音器放置在画面的提示帧上，通过测量而非聆听来评估，经过五个透镜的审视，由一个代理修复，再母带、添加鸣谢并复用。代码负责选择、修剪、放置、调整电平、声相、均衡、通过重采样变速、对音乐进行时间伸缩和母带处理；代码永远不会生成声音。
标准为专业发布级电影：屏幕上的每个动作都有对应的声音，使用单一材质调色板，音乐高潮落在主角揭示时刻，其他位置保持克制，Logo 最终呈现，尾部渐入静默。规则请参阅 references/sound-design.md（以及 earhot 仓库中的 docs/launch-video-sound.md，其中包含了捆绑的参考配置文件：7 部专业发布级电影）。
以下 <skill> 指此文件夹。Python：{{PY}}（及以下所有提示模板中）指一个安装了 numpy、scipy、soundfile 和 earhot 包的解析器：即 earhot 仓库的虚拟环境（Windows 上为 <earshot repo>/.venv/Scripts/python.exe，其他系统上为 <earshot repo>/.venv/bin/python），或任何可以通过 <python> -c "import earshot" 命令的 Python。在 Windows 上，裸 python 通常是 Microsoft Store 存根程序，会失败。在执行命令或向子代理传递提示时，请用完整路径替换 {{PY}}（其他占位符列在 references/process.md 中）。使用 -I 参数运行脚本（隔离模式：确保下载的文件不会遮蔽任何模块）；除 scripts/licences.py（audit.py 和 credits.py 导入的许可证策略模块）外，每个脚本都支持 --help。
流程
| 步骤 | 负责人 | 输出 | 关卡 |
|---|---|---|---|
| 0. 提示列表 | 主管 | out/cues.json | 从画面代码计算出的同步帧 |
| 1. 概要 | 主管 | audio/SOUND_BRIEF.md | 每个提示都有声音需求（或“无”） |
| 2. 资源获取（按类别并行） | 资源获取代理 | audio/assets/<cat>/，清单清单 | 每个文件都经过测量 + earhot 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，音画同步无延迟 |
每一步的细节、角色以及每个评论员的衡量标准：references/process.md。每个子代理的提示都是 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：概念（调色板、音乐弧线、位置）、画面映射（每个提示：屏幕上是什么、声音需求）、环境音区域、允许的许可证、质量标准、文件布局。它是每个子代理都会逐字收到的合同。请选择品牌的个性行（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/ # 关卡：“真实或专业制作”（重新检查修剪片段：--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 # 修剪片段；跳过任何标记为头部剪切/尾部剪切的片段
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 块）。下拍是薄弱点：当脚本输出低置信度时（在其测试过的一个音轨上，它曾偏差了半小节），请根据第一个音符、段落入口和弦变化表（在 --phase N 参数帮助下）从两个打印的网格中做出决定，并使用 --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 # 每个修剪片段输出为 WAV + 数值
{{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 # 点击、边缘、可听度、刺耳度、响度、覆盖率、同步、密度
{{PY}} -I <skill>/scripts/qa.py --listen --realness --video out/film.mp4 # + earshot 时间线、波形图、评价、realness
{{PY}} -m earshot critique out/audio/soundtrack.wav --video out/film.mp4 # 与专业发布级影片的评分卡
{{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 # 退出码 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 # 最终文件，已监听
CREDITS.md + out/CREDITS_description.txt（粘贴到视频描述中：CC BY 鸣谢是必须的）。mux.mjs 将画面流式复制，并将 AAC 音频裁剪至画面的时长。
发布级视频：声音映射
| 画面 | 声音 | 位于 |
|---|---|---|
| 光标移动、悬停、滚动、进度、流式文本 | 无（音乐承载） | |
| 点击/轻触 | 影片的一个真实点击音色，按下 + 释放大约 85 毫秒后，每个电平相同 | 按下帧 |
| 打字 | 一个真实的键盘，已切片；速度 <= ~12 键/秒，超过 ~25 字符/秒的词每个词一个音；音乐降低 6-10 dB | 每个发声的字符 |
| 卡片/芯片/徽章出现 | 一个柔软的真实弹出或滴答声，在一系列中音高上升 | 其移动的 50% |
| 切换、锁定、计数器的最终值 | 一个真实的锁存/点击/清脆的滴答声 | 接触/锁定帧 |
| 相机缩放移动、鞭打、缩放（每影片约 2 个） | 一个真实的嗖嗖声，顶点在速度峰值 | 速度峰值 |
| 硬切 | 无 | |
| 紧张到揭示 | 音乐的铺垫，或一个真实的上升音，在冲击前 30-250 毫秒结束 | 冲击点 |
| 主角揭示 | 音乐的高潮（剪辑音轨使其下拍落在此处）+ 可选一个真实的冲击 | 帧 |
| 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 |
| 收听录音：真实 vs 合成、听起来像什么、最佳匹配、长文件中的最佳片段 | {{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 修剪片段、用于 QA 的 --trace） | scripts/mix.py |
| 母带处理和响度测量 | scripts/master.py（--measure） |
| 客观 QA，与放置位置关联 | scripts/qa.py（--layers、--listen、--realness） |
| 评论员变体、修复员的 apply | scripts/variant.py |
| 用于 CREDITS.md 和视频描述的鸣谢 | scripts/credits.py |
| 将音轨放到画面上 | scripts/mux.mjs |
| 收听整个混音/影片；带注释的画面；发布级影片评分卡 | {{PY}} -m earshot timeline / sheet / critique |
文件
audio/SOUND_BRIEF.md 合同 (templates/SOUND_BRIEF.md)
audio/assets/<category>/ 下载的录音 (<source>-<id>_<slug>.<ext>；切勿提交或发布它们)
audio/assets/manifests/<cat>.json 每个录音一条记录 (templates/manifest_entry.json)
audio/assets/manifests/audit.json 许可证审计 (templates/audit_entry.json)
audio/sounddesign.json 顶级：包含、总线、母带 (templates/sounddesign.json)
audio/design/<category>.json 每个设计师一个片段 (templates/design_fragment.json)
out/cues.json 画面的提示事件 (templates/cues.json)
out/audio/soundtrack.wav, stems/ 母带及其分轨
out/qa/ mix_report.json, adds.json, cues_sounded.json, master.json, qa.json
out/audio-review/ 按类别和评论员分类的工作、变体、转储（审计跟踪）
CREDITS.md, out/CREDITS_description.txt
参考
references/process.md：角色、步骤、每个评论员衡量的内容、阈值及其来源
…[翻译截断]