suggest-sfx

suggest-sfx — 音效设计流程

为已渲染并配好旁白的短视频添加恰到好处的音效，使其与视觉节拍和旁白同步，并从共享且不断扩充的音效库中选取素材。以协作方式逐拍进行；用户会审核方案并提出意见。

流程：以声明式方案（sfx-plan.json）为准 → 由工具读取并处理（tools/mix_sfx.py）→ 音效库不断扩充（media/library/sfx/）→ 混音前必须经过严格的 USER-AUDIT 审核关卡。

声音品味是品牌规范的一部分——每次都要阅读 brand.md §7。品牌风格沉稳、高级（Linear / Anthropic / Vercel），让人感受到而非刻意听到，始终低于人声。不要做成 MrBeast 式的吵闹风格。

输入（每次会话都要先阅读）

• brand.md §7（声音设计）——音效品味规范：克制、密度、音色、音量、同步、标志性主题和素材来源政策。不可妥协。
• shorts/short-N-<niche>/beats.json——节拍及真实的逐词人声时间（由 gen_voice.py 写回）。音效提示要与这些词同步（比如在“boom”处加一声爆破音，在“free”处加一声铃音）。
• 镜头源文件 remotion/src/shots/short-N/*.tsx——真正的视觉节拍位于镜头内部的动画帧中（元素落位、数字弹出、徽章盖章）。阅读镜头代码，并将本地帧转换为全局时间：at_s = (local_frame + sequence_from) / fps。不要猜测——提示必须落在事件发生的确切帧上。
• media/library/sfx/catalog.json + palette.json——你要从中选取素材并加以扩充的音效库。

音效库（media/library/sfx/）——长期资产

• palette.json——生成配方：通用、可复用的声音 ID + 提示词 + 时长 + 标签。它是音效库应当包含内容的事实来源。
• catalog.json——记录现有素材的清单：每段音效都包含 {id, file, category, tags, duration_s, peak_dbfs, loudness_lufs, source, model, license, prompt, used_in}。由 gen_sfx.py 写入。
• clips/*.mp3——响度已标准化的音效（约 −20 LUFS，峰值上限 −1.5 dBFS），因此方案中每条提示的 gain_db 都具有实际听感意义。
• **始终优先使用音效库。**生成新素材之前，先复用已有音效。使用通用名称和标签为音效命名（ui-toggle-on、whoosh-soft、pop-reveal），方便未来的视频复用——音效库是长期资产，每条视频只是从中选取素材。只有确实缺少的声音才加入 palette.json 并生成。

工作流

1. 阅读品牌指南 §7 + beats.json + 镜头源文件 + 目录。提取准确提示时间：对于每个候选节拍，找到镜头中视觉时刻的局部帧和／或旁白中的对应词，并换算为全局秒数。
2. 如果用户尚未确定，就先确认其偏好（临场感、密度、音效类型、来源），然后应用品牌指南 §7。已确定的决定不要重复询问。
3. 以功能为先，提出提示音列表。 对每个节拍，先询问它需要什么（品牌指南 §7）：运动感（呼啸声）· 紧张感（渐强音）· 强调（撞击声／弹出音）· 利落感（点击声）。为关键转场、揭示和恰到好处的点击序列打分；3–4 个镜头组成的点击序列算作一个动作。将确实可有可无的质感标记为 "optional": true。为最重要的 2–3 个时刻叠加音效（渐强后骤停）：在脚本中的揭示点用渐强音→撞击声；用呼啸声→弹出音突出剪辑点——计划中，叠加指两个位于相同或相邻 at_s、组合使用的事件。将每个提示音与视觉节拍同步，并尽可能与准确词语同步。
4. 优先使用音效库。 对计划所需的每种不同音效，若目录中有合适片段，就重复使用。若找不到合适片段，就在 palette.json 中添加通用配方并生成：python tools/gen_sfx.py（ElevenLabs Sound Effects API → 标准化片段 → 目录）。只有在生成效果不佳时，才使用精选的免版税音效；无论采用哪种方式，都要记录 source + license。
5. 编写 shorts/short-N-<niche>/sfx-plan.json——每个提示音对应一个事件，at_s 使用全局秒数。 （架构如下。）
6. 用户审核关卡（强制）。 展示解析后的提示音清单（python tools/mix_sfx.py <plan> --print），并在混音前获得用户批准或备注。
7. 批准后混合试听预览：python tools/mix_sfx.py shorts/short-N-<niche>/sfx-plan.json → 生成计划中的 render.out。在人声下方轻微应用侧链闪避，并使用安全限幅器。根据用户的备注迭代（增益、时间、添加／删除提示音）——重新打印并混音。
   • 用数据验证可听度，不能靠猜。 混音后，在每个提示音的时间窗口内，计算混音音频与仅人声预览的 RMS 差值：对剧情关键提示音，差值应至少为 +4 dB；质感音效应为 +1–3 dB。提示音在清单中看似存在，实际可能听不见——未确认确实出现的提示音不要交付。
   • 瞬态音效的增益陷阱。 短促的打击类片段（敲击声／印章声／钥匙声／弹响声）会在达到 −20 LUFS 响度目标前先触及 −1.5 dBFS 峰值上限，因此它们在目录中的音量比持续音效低约 3–5 dB。它们的计划 gain_db 必须比品牌表指示值高约 3–5 dB。上述可听度检查会揭示这个问题。
   • SHORTS 校准。 在旁白几乎连续（约 2.7 个词／秒、间隔很少）的短视频中，保守的增益表会整体低 4–8 dB——侧链闪避和人声掩蔽会吞掉所有音效。经验证的合适范围：转场／呼啸声 −3，剧情弹出音／撞击声 0..+3，印章声／弹响声 0..+7，叠加的主打渐强音 0..+2。短视频的计划从这些范围开始。
   • 完全落在连续语音下方的提示音测不出来——要么接受它只能被感受到而非听见，要么删掉。 人声发声期间，侧链闪避会一直压低安静的片段（点击序列在任何增益下都可能测出 +0 dB）。将这类提示音设为合理的 +6 左右，让它们出现在词语间隙中，或者删除；不要靠提高增益来补救（遇到停顿时会突然过响）。
   • 使用紧凑窗口测量瞬态音效。 在 0.6s 内计算 RMS，会把 50 ms 的点击声稀释到几乎听不见；相邻的大声提示音还可能渗入，造成虚假的合格结果。弹响声／弹出音／电子脉冲声／印章声使用约 0.3s 的窗口；渐强音则测量其最后三分之一（能量集中在末尾）。
   • 噪声音效不能靠增益修复。 在语音下方，静电声／故障杂音／嗡鸣片段即使降低到 −4 dB，听起来仍像噪声；再降低只会让噪声变小。若用户说“有杂音”，就替换为另一种音色（干净的机械弹响声），或使用静音——参见品牌指南 §7“旁白下方不要使用静电声／故障杂音质感”。
8. 保存回库。 新片段继续保存在音效库和目录中（可供下一条视频使用）。更新 used_in。

sfx-plan.json（事实来源）

{
  "master": "remotion/out/ShortNName-voiced.mp4", "master_fps": 30,
  "catalog": "media/library/sfx/catalog.json",
  "render": {
    "preview": "remotion/out/ShortNName-voiced.mp4",   // the voiced render to mix over
    "out": "shorts/short-N-<niche>/output/short-N-sfx.mp4",
    "end_s": 42, "duck": true
  },
  "events": [
    { "at_s": 4.9, "sfx_id": "chess-piece-thock", "gain_db": -8, "shot": "MainScene",
      "cue": "e4 pawn lands (local f51)", "note": "diegetic board foley" },
    { "at_s": 13.03, "sfx_id": "ui-click-soft", "gain_db": -18, "optional": true, "cue": "card locks" }
  ]
}

• at_s — 全局时间线上的秒数（与 beats.json 使用同一时钟）。
• gain_db — 相对于片段归一化电平的 dB（数值越低，声音越轻）。起始值请参阅上文的 SHORTS 校准。
• optional: true — 可舍弃的纹理；mix_sfx.py --no-optional 会将其移除。请尽量多使用，以便审核聚焦于核心集合。
• cue / note — 人类可读的锚点（确切的帧／词），让审核清晰易懂。

工具快速参考

• 扩充素材库：python tools/gen_sfx.py [--dry-run] [--only id1,id2] [--force] [--renorm]。 --renorm 会将现有片段重新平衡到目标响度（不调用 API／不计费）。需要在 .env 中设置 ELEVENLABS_API_KEY。
• 打印提示表（审核材料）：python tools/mix_sfx.py <plan> --print [--no-optional]。
• 混音：python tools/mix_sfx.py <plan> [--no-optional] [--no-duck] [--end S] [--out path]。

原则（本项目的风格——请遵守）

• 始终压在人声之下。 音效只是调味；人声才是主角。对音效进行闪避，保持音量轻柔，绝不让任何音效的峰值高于旁白。静默也是混音的一部分。
• 只用于关键转场和揭示——以及属于合成短片内容的实景动作声（棋子落下声、数字弹出声）。除此之外都标记为 optional。
• 与画面节拍和词语同步。 点击声要与开关翻转完全同步；弹出声要与揭示完全同步。偏差 100ms 就会显得粗糙——使用真实的帧／词时间点。
• 优先复用。 使用通用名称和标签，让素材库在不同视频间不断积累。生成前先复用。素材库是比这支视频更长久的交付物。
• 功能优先于氛围。 根据声音的作用来选择——动感／张力／强调／利落感（品牌规范 §7）——而不是在目录中挑选听起来“感觉合适”的声音。少数几种基础声音就能承担主要任务；更多并不代表更好。保持标志性主题音效的一致性。
• 重要时刻分层，其余保持单层。 营造再落下（上升音→冲击声、呼啸声→弹出声）是音效发挥价值的时机——但只用于 2–3 个主打节拍。
• 采用结构，不要戏剧化。 保持沉稳、高级感：不用制造钹片紧迫感的上升音，不用预告片式重击，也不要每个动作都配呼啸声。
• 混音前先审核。 用户必须先阅读并批准 sfx-plan.json。这是不可妥协的要求。

完成标准 = 素材库中包含所需片段（已记录目录、来源和许可），sfx-plan.json 已编写并经用户审核，已渲染并通过听觉抽查 SFX 混音预览，所有新片段及其 used_in 信息均已保存回素材库。