音效需求清单 · OCC: Planet Civilization

状态：规划稿（项目当前音频接入度为 0） 本文是「要做什么声音」的单一清单，按代码事件点倒推，每一条都有落点。 与本文配套的工程方案见 docs/系统架构.md；资产生产/瘦身见 docs/美术资产管线.md。

---

0. 现状：从零开始

两处"等着接"的地方：

• public/src/main.js:1266 —— 机甲撞树/撞石："碰撞只给'重'的反馈 —— 火星 + 镜头震动 + 撞击音效（如果有）"
• docs/玩法方案-Planet Civilization-v1.md:513 —— 无人机物流："保证起降有实体、有音效、有货箱视觉变化"

结论：没有任何历史包袱，可以从架构开始一次做对。

---

1. 硬约束（先看这节，否则素材做好了也接不上）

---

2. 音频总线设计（建议）

                       ┌─────────────┐
  ui    ──► gain ──┐   │             │
  sfx   ──► gain ──┼──►│  master     │──► DynamicsCompressor ──► destination
  amb   ──► gain ──┤   │  (总音量)   │        (防削顶)
  bgm   ──► gain ──┘   └─────────────┘

默认建议值：master 0.7 / sfx 0.9 / ui 0.6 / amb 0.5 / bgm 0.45

2.1 三条必须有的"防炸"机制

1. 同名限流：同一音效最小间隔 minGap（机甲脚步 0.28s、命中 0.05s、拾取 0.06s）。

没有这条，50 台 NPC + Boss 齐射会瞬间叠 60 个voice → 爆音。

1. 最大并发 MAX_VOICES（建议 24）：超出时按优先级挤掉最低优先级（BGM/Ambient 永不挤）。
2. 距离降级：>120 弧长只发 P0 音效；>260 弧长直接不发声（与 renderDist 1100 无关，听觉距离要短得多）。

2.2 3D 声源坐标换算（球面专用）

// 听者 = 玩家：位置取 player 方向 × 半径，朝向取 +Z（车头），上取 +Y（法线）
// 声源 = 事件点 direction：单位向量 → 乘半径得到球面位置
// 衰减距离直接用三点间的**弧长**，不要欧氏直线距离（远距离差异很明显）

---

3. 音效清单

优先级：P0 = 一进作品就能感知、缺了明显"哑"；P1 = 玩法闭环必需；P2 = 氛围与打磨。 "落点"= 建议挂接的代码位置。

3.1 UI / 系统（总线 ui，无空间）

3.2 机甲本体（总线 sfx，1:1 跟随玩家 —— 最"响"的一组）

3.3 纸飞机 · 武器与命中（总线 sfx）

攻击是四态 orbit → climb → dive → return，音效必须贴着这个状态机做，否则节奏对不上。

3.4 采矿 · 采集（总线 sfx）

3.5 建造 · 生产 · 科技（总线 sfx）

3.6 物品 · 背包 · 仓库（总线 ui / sfx 混用）

3.7 NPC / 精英坦克 / Boss

3.8 无人机 · 物流（总线 sfx，3D）

docs/玩法方案-Planet Civilization-v1.md:513 明确要求"起降有实体、有音效"。

3.9 多人 · 世界 · 氛围

3.10 条目合计

最小可用集（先做 39 条 P0） 就能让整局作品"不再哑火"。

---

4. 素材规格与命名

4.1 格式与体量

🔴 本机没有 libvorbis（PyAV 只带 libmp3lame / aac / opus / flac）⇒ 原计划的 ogg 方案落不了地，改用 MP3 为主 + m4a 兜底。两者在现代浏览器全通吃， 判不判定 canPlayType 都无所谓了。真要 ogg：装 ffmpeg 后改 postprocess.py --format。 104 条实测总体积 7.6MB（mp3+m4a 双份；只留 mp3 是 3.51MB，平均 34KB/条）， 其中两条 30s 环境音各占 470KB —— 它们本来就是大头。

4.2 目录结构

public/assets/audio/
├─ ui/        ui_click.ogg / ui_panel_open.ogg / ...
├─ sfx/
│  ├─ mecha/  sfx_mecha_step_l.ogg / sfx_mecha_land.ogg / ...
│  ├─ weapon/ sfx_plane_launch.ogg / sfx_plane_hit_npc.ogg / ...
│  ├─ mine/   sfx_mine_beam_loop.ogg / sfx_depleted.ogg / ...
│  ├─ build/  sfx_build_place.ogg / sfx_tech_unlock.ogg / ...
│  ├─ npc/    sfx_npc_fire.ogg / sfx_npc_die.ogg / ...
│  └─ boss/   sfx_boss_phase.ogg / sfx_boss_mortar_warn.ogg / ...
├─ amb/       amb_home.ogg / amb_battle.ogg / ...
└─ bgm/       bgm_home.ogg / bgm_battle.ogg / bgm_boss.ogg

命名规范：<总线>_<系统>_<事件>[_<变体>].<ext>，全小写下划线，不允许中文文件名（部署 tar/scp 链路对非 ASCII 路径不友好 —— 见 deploy/prod/push.sh）。

4.3 一次性总量估算

BGM 是唯一需要认真权衡的部分：如果坚持"首屏 2.2MB"的精神，BGM 应该按世界懒加载（进苗圃只拉 bgm_home，切焦土再拉 bgm_battle），绝不全量预载。

---

5. 实施路径（分三期）

一期 · 骨架 + P0（核心体验）

1. 新增 public/src/audio.js：AudioContext 单例、4 总线、限流、MAX_VOICES、球面 3D 衰减、safe() 包裹。
2. 解锁时机：auth-ui.js 登录点击里 ctx.resume()。
3. 接入 41 条 P0 音效的落点（本文档已给全）。
4. 验收：safe('audio', …) 无抛错；50 NPC + Boss 齐射不爆音；切世界不残留上一世界的 amb/bgm。

二期 · 全量 + 设置面板

1. 补 P1/P2 共 67 条。
2. 新增设置面板：master / sfx / ui / amb / bgm 五滑杆 + 静音开关，落 localStorage（与现有 I 键反转 Y 轴同级别设置项，支持 H 操作说明面板里能看到）。
3. 音频懒加载：进世界后按世界拉取 amb/bgm，其余按需。

三期 · 动态混音

1. Boss 战 BGM 交叉淡入（bgm_battle → bgm_boss）。
2. 战斗强度驱动 amb 层（远处炮火密度）。
3. 低血量危机层。

---

6. 验收清单（做完必须过）

• [ ] 断网/无音频文件时，作品完全正常运行（静默降级，不抛错）
• [ ] 帧率不因音频下降（对比 node tools/e2e/perf.cjs 基线：draw call 51 / 三角形 50.8 万）
• [ ] 首屏体积不增加（音频全部懒加载）
• [ ] 50 台 NPC + Boss 全开火时无爆音、无 voice 溢出
• [ ] 切世界后旧世界 amb/bgm 完全停止
• [ ] 音量设置刷新页面后保留
• [ ] 生产环境（阿里云 nginx 8090）音频能正常加载 —— 确认 deploy/prod/push.sh 排除清单没有漏掉 public/assets/audio
• [ ] 主循环里所有音频调用都在 safe() 内

---

7. 素材来源（三条路，可混用）

🔴 版权红线：本项目是要上生产、要对外演示的产品，所有素材必须有可追溯授权记录，建议在 docs/美术资产管线.md 里补一节"音频素材来源与授权"。

---

8. 生产状态（2026-10-16）

104 条已全部生成并落地（108 − 4 条 BGM，BGM 走 ACE-Step），整条链路跑通。 生成侧的具体内容（每条提示词）见 docs/音效提示词库.md。

python tools/audio/gen.py --prio P0            # 生成（单条 1.5~4.5s @ 3070 Ti）
python tools/audio/postprocess.py --also-m4a   # 出成品 + 写索引

实测：RTX 3070 Ti / 8GB 上 small-sfx 单条 1.5~4.5 秒（8 步 lcm、cfg 1.0）。 104 条从零到成品约 15 分钟（含下载模型）。

其中 12 条需要无缝循环（含两条 30s 环境音），已全部做等功率交叉淡入。

三条实测踩坑（已写进脚本注释）

1. EmptyLatentAudio.seconds 下限是 1.0 —— ComfyUI 提交 0.4s 会直接报

value_smaller_than_min。所以 0.3~0.9s 的音效一律按 1s 生成再裁， 且裁剪必须按能量包络峰值定位起点（从 0 秒硬切会把瞬态切掉）。

1. 🔴 PyAV 解 FLAC 出来是 packed s16，to_ndarray() 给的是 (1, samples×channels)，

不是 (ch, samples)。当单声道处理会让时长翻倍、左右声道被串联 （听感上整体慢一倍 + 变调）。planar 格式（s16p/fltp）才是 (ch, samples)。

1. 🔴 写 MP3 时 AudioFrame.from_ndarray 要求 s16 的 shape 是 (1, n×ch)，

传 (n, ch) 会报 Expected packed array.shape[0] to equal 1。

已接入作品（2026-10-16）

public/src/audio.js 已落地并全量挂点 —— 作品里能听到声音了。

挂点清单（改某条音效去哪个文件找）：

两颗星球的声音（"背景音必须不同"）

🔴 整体基调是「空旷幽深的太空宏大感」，不是地球田园（老大 2026-10-16 晚）。 第一版写进了 faint birdsong texture / soft bird-like calls / 毛毡钢琴 / 木管 / 太鼓 —— 出来是"田园牧歌"，和太空题材拧着。现在：

• 全部 no nature sounds / no birds / no piano / no woodwind / no acoustic drums
• 换成 deep cosmic drone / cavernous reverb / infinite distance / weightless / vast
• 环境音 + 三条 BGM 都加了条目级 neg（birds, nature sounds, piano, woodwind, taiko, acoustic drums…）

频谱实测（同一套算法跑新旧两版，旧版从 git 取）：

环境音那条变化最大 —— 老大听到的"鸟叫"主要就是它。

🔴 BGM 是「状态驱动」而不是「事件驱动」：主循环每帧由 desiredBgm() 问一句"现在该放哪条"。 一开始写成"Boss 上线切曲 / 进世界按世界选"三处事件，翻过车 —— 那条按世界补发的 NPC/Boss 消息 可能比 boot 末尾的 loopStart 更早到，于是 deferredLoops 的重放顺序颠倒， 实测 bossAlive=true 却放着 bgm_battle。改成状态驱动后与事件到达顺序彻底解耦。

BGM 由哪个模型生成：正式版用 Stable Audio 3 Small-Music（同模型族、同工作流， 为音乐/循环训练）；同时用 ACE-Step 1.5 Turbo（10GB 大模型，歌曲架构）出了一套对照版， 放在同目录下以 .ace.mp3 结尾，在试听台里标着「（ACE-Step 对照）」—— 听感偏好由人来定， 代码里默认走 Small-Music 那套。

python tools/audio/gen.py --music                    # 正式版（Small-Music）
python tools/audio/gen.py --ace                      # 对照版（ACE-Step，输出到 <日期>/ace/）
python tools/audio/postprocess.py --src _logs/audio/<日期>/ace --suffix .ace --also-m4a

验收 _logs/bgm_world_check.cjs：10/10 通过（两个世界各验环境音 + BGM，并断言"两套必须不同"）。

还没做

• 音量面板没接进「H 操作说明」 —— 目前是独立的 dock 按钮。
• ACE-Step 版未接入作品 —— 只作为试听对照；要切过去改 desiredBgm() 的返回值即可。
• 对照版会一起发布（bgm/.ace.，约 12MB）—— 不想发就删掉这些文件并把 _index.json 里

对应条目去掉（重跑一次 postprocess.py 会自动剔除索引）。

• 没有"音效开关"的独立面板 —— 五条总线滑杆已够用，但没做"一键关所有音效"。