音频方案与首版实现(2026-10-27)
目标:给《拾剑录》补上完整音频(BGM + 战斗/UI/掉落音效),并接入音量设置与总线。 现状:全项目 0 个音频文件、0 行音频代码;配置表 tb_sound 有 350 行 / 144 条唯一音轨(17 BGM + 127 UI/技能/怪物/物品),被引用 283 个 id / 142 条音轨。 本轮:本地 AI 生成首批 40 条(5 BGM + 35 SFX)+ 完整音频引擎 + 设置页音量滑块 + 事件接线。
1. 三条路线对比与建议
| 路线 | 成本 | 优点 | 缺点 |
|---|---|---|---|
| A. 本地 AI 全量生成(ACE-Step 1.5 + Stable Audio 3 small,已验证可用) | ¥0 + 电费/时间 | 零授权费、可无限重跑、风格可按提示词微调 | 长曲结构/情绪起伏不稳定;SFX 需要筛选;需 Steam AI 披露 |
| B. 采购授权音源包(Humble/Unity Asset Store/Artlist 等) | ¥200–3000/包,商用授权 | 质量稳定、可商用、无 AI 披露问题 | 风格未必贴武侠;可能撞声 |
| C. 委托作曲/音效师 | ¥5000–30000 | 最贴主题、独占 | 贵、周期 2–6 周 |
| D. 混合(建议) | 低–中 | AI 出 90% 铺量 + 关键 3–5 首 BGM 采购/委托 | 需要一次筛选与统一响度 |
建议 D:先用本地 AI 把全套跑出来(可玩、零成本、随时替换),标题/首领/主题这 2–3 首在意向确定后再考虑委托或买包;AI 生成部分在 Steam 内容问卷里如实披露(pre-generated audio)。
合规提醒:AI 生成音频同样属于 Steam「AI Generated Content」披露范围(生成工具、用途、是否人工审核);不要用带版权样本的模型/参考音频。
2. 生成管线(已落地)
ComfyUI(127.0.0.1:8188) ├─ ACE-Step 1.5(9.3GB aio checkpoint)→ BGM:tags + bpm + duration + keyscale,instrumental └─ Stable Audio 3 small sfx(2.3GB)→ 单发音效:文本描述 + 时长(≥1s,TrimAudioDuration 裁到目标) 产物 tools/audio/out/<key>.mp3 → tools/audio/install_audio.py:去首尾静音、峰值归一化到 -1 dBFS、MP3 → client/public/assets/audio/<key>.mp3
命令:
python tools/audio/gen_batch.py # 全量首批(已生成 40 条) python tools/audio/gen_batch.py --only sfx # 只跑音效 python tools/audio/install_audio.py --apply # 规范化并装入 assets
单条调试:
python tools/audio/audio_gen.py sfx --name hit_light --prompt "..." --dur 0.3 python tools/audio/audio_gen.py bgm --name bgm_battle --prompt "..." --dur 60 --bpm 96
3. 客户端架构(client/src/audio/audio.js)
- 总线:master → music / sfx / ui(4 个 GainNode),设置页只调这四档
- 解锁:首次 pointerdown/keydown 时 unlock()(Autoplay 策略)
- 懒加载 + 缓存:首次播放才 fetch + decodeAudioData;失败只 warn 一次
- BGM:交叉淡入淡出、循环;同 key 忽略重复调用
- 事件接线:
- 施法:按技能名关键词(火/冰/雷/毒/圣/暗)选池 cast_*,怪物施法音量降低
- 命中:暴击 crit / 碾压 hit_heavy / 普通 hit_light|hit_heavy 随机
- 未命中 miss、僵直 stun
- UI:全局事件委托 → ui_click;TAB 切换加 ui_open
- 升级:快照里队伍等级上升 → level_up
- BGM:标题 bgm_title,战斗 bgm_battle,首领出场切 bgm_boss(1s 节流)
- 音量设置:设置页四档滑块 + 静音,存 localStorage(shijianlu.audio.v1),即时生效
4. 首批 40 条清单
| 类 | key |
|---|---|
| BGM ×5 | bgm_title / bgm_battle / bgm_boss / bgm_village / bgm_victory |
| UI ×9 | ui_click / ui_hover / ui_open / ui_close / ui_confirm / ui_cancel / ui_error / level_up / coin |
| 战斗 ×9 | hit_light / hit_heavy / crit / miss / stun / death / heal / buff / debuff |
| 施法 ×9 | cast_physical / cast_fire / cast_ice / cast_lightning / cast_poison / cast_holy / cast_shadow / arrow / slash |
| 怪物 ×4 | monster_born / monster_dead / boss_roar / elite_roar |
| 物品 ×4 | drop_common / drop_rare / drop_legendary / put_item |
5. 还没做的(下一批)
- 127 条 UI/技能/怪物/物品音轨:默认用「事件池」覆盖(同一类共 2–4 个变体随机播放),不必 1:1 生成;
- BGM 的无缝循环:现在整曲循环,接缝处有轻微断点;可做 2–4 秒交叉淡化或手工剪成 loop;
- 响度统一(现在只做峰值归一化;正式版建议 -16 LUFS 近似);
- 可加一个总线压缩器避免爆音;
- 音频设置里加「试听」按钮与静音快捷(M 键);
- Steam AI 披露文案与生成记录台账(tools/audio/out 保留 seed/prompt)。
6. 验收(tools/check-audio.mjs)
- 进战斗、点 TAB(解锁 AudioContext)
- 校验 /assets/audio/* 请求全部 200、无 4xx
- 校验 AudioContext state=running、buffers 加载数、BGM key 正确
- 截图设置页音量滑块
7. 首版落地结果(2026-10-27 深夜)
| 项 | 结果 |
|---|---|
| 生成 | 40 条(ACE-Step 5 条 BGM + Stable Audio 35 条 SFX),本地 ComfyUI,0 成本 |
| 规范化安装 | client/public/assets/audio/*.mp3,40 个文件 / 3.5MB |
| 引擎 | client/src/audio/audio.js(四总线、懒加载、BGM 交叉淡入、音量持久化) |
| 接线 | main.js(标题/战斗/首领 BGM、升级音)、battleview(施法/命中/暴击/未命中/僵直)、ui.js(点击/开页 + 四档滑块 + 静音) |
| 验证 | tools/check-audio.mjs:AudioContext running、8 个 buffer、8/8 请求 200、0 JS 异常;截图 tools/out/audio-settings.png |
| 单一音频 | bgm_battle 52.1s / peak 0.95;ui_click 0.18s;crit 0.5s;峰值归一化到约 -1 dBFS |
已知问题 / 下一步:
- BGM 现在整曲 loop,接缝处有轻微断点 → 需要 2–4 秒交叉淡化或手工剪 loop;
- 响度只做峰值归一化,正式版建议整体对齐约 -16 LUFS;
- 目前 40/167 条,剩 127 条按事件池映射(同类 2–4 变体随机播放,不必一条 id 一个文件);
- 可加总线压缩器、试听按钮、M 键静音;
- 生成记录(prompt/seed)保留在 tools/audio/out + tools/audio/batch.log,作为 Steam AI 披露依据。
8. 2026-10-27 反馈修正:SFX 太大声 / 太单一,BGM 默认 60%
- 默认音量:master 0.85 / music 0.60 / sfx 0.42 / ui 0.50(localStorage key 升级到 shijianlu.audio.v2,旧值自动作废)
- 总线加 DynamicsCompressor(threshold -14dB / ratio 3.5 / release 0.25s),压住连续命中与多单位同帧出手的峰值
- SFX 不再每个事件一条录音:新增 21 条变体(hit_light ×3、cast_* ×2、ui_click ×3、monster_born/dead ×2、drop_common/rare ×2 等),播放时随机选 + ±6% 变调 + ±0.16 声像
- 感知音量统一挪进引擎 VOL_SCALE 表(调用点只传语义音量),以后调平衡只改一张表
- 生成脚本:tools/audio/gen_variants.py(可重跑,已生成的会 skip)
9. 2026-10-28 关键修正:SFX 全是噪音
- 根因:Stable Audio 3 是 LCM 蒸馏模型,官方模板是 sampler=lcm / steps=8 / cfg=1;
首版误用了 euler / 30 步 / cfg=5,出图全部退化成噪音(旧 ui_click 甚至是纯直流)。
- 修法:tools/audio/audio_gen.py 的 sfx() 改为 lcm + 8 步 + cfg 1(去掉 ConditioningStableAudio,与模板一致);
56 条 SFX 全部重生成并重装(tools/audio/regen_sfx.log)。
- 验证:旧 hit_light 波形是等高块状、频谱是横条噪音;新的是瞬态起音 + 衰减。ZCR/峰值检查通过;check-audio 0 异常。
- BGM 未受影响:ACE-Step 本来就用官方模板(8 步 / cfg 1 / euler / shift 3)。
- 缓存:audio.js 增加 ASSET_VER 查询参数,避免浏览器继续使用旧噪音文件。
10. 2026-10-28 音频设置文案中英适配
- 音频设置块原先直接写死中文,英文模式下不翻译:已进 i18n 词典
(Volume / Master / Music / SFX / UI / Mute all / Drag to adjust · saved automatically)。
- 顺带补了舞台条里漏掉的「循环」→ Loop(PHRASES 短语表)。
- 验证:check-audio.mjs 在 lang=en 下读取 .audio-block.innerText = 全英文,
整页残留中文 token = [已隐藏] tools/out/audio-settings-en.png)。
11. 2026-10-28 音频收尾:事件池覆盖 / BGM 无缝循环 / 响度统一
- 事件池覆盖:新增 tools/audio/build_sound_map.mjs → client/public/data/sound-map.json,
把 198 个在用 sound id 映射到 9 类事件池(ui_click/open/confirm/cancel、level_up、 cast_physical/fire/ice/lightning/poison/holy/shadow、monster_born/dead、drop_common/rare/legendary、coin)。 客户端新增快照差分触发:怪物登场(普通/精英/首领)、怪物死亡、掉落与铜钱;施法按技能名元素选池。
- BGM 无缝循环:audio.js 改为双源交叠——每条 BGM 在结束前 2.5s 起下一条并交叉淡化,
不再用单源 loop(mp3 解码后的边界静音会「咔」一下)。
- 响度统一:install_audio.py 接入 ITU-R BS.1770(pyloudnorm):
SFX 积分响度 -16 LUFS(<400ms 的短音效用 -18 dBFS RMS 近似),BGM 按 -18 dBFS RMS 对齐; 全部峰值限制 -1 dBFS(BGM 0.95)。重装 61 条:BGM RMS 基本落在 -18 dBFS,SFX 峰值 ≤0.89。
- 总线压缩器:master → DynamicsCompressor(-14dB/3.5:1) → destination,压住连击与同帧多单位峰值。
12. 技能音效按元素细分(2026-10-28)
- 根因:tb_skill.NameKey 是 { Values: [key] } 而不是字符串,zh 查表恒空 → 55 条技能音效全落 cast_physical。
- 修正 build_sound_map.mjs 后:physical 30 / ice 6 / fire 5 / lightning 5 / poison 4 / shadow 3 / holy 2。
- 剩余 30 条 physical 多为确实不带元素词的招式名;要再细分需人工补「技能→元素」表。