游戏配乐审计：18个播放槽位为何只对应17个音频文件

当"18首曲目"变成一笔糊涂账

游戏音频制作中，候选曲目、选定作品、存储文件和实际播放分配会逐渐脱节。替换地图音乐时，旧文件可能仍留在存储中；两个场景也可能共用同一段录音。当制作笔记写着"18首曲目"时，这个数字究竟在数什么，往往无人能说清。

以 VOLT NOMAD 为例，将其制作笔记与代码交叉比对后发现：18个BGM播放槽位实际只引用17个不同的音频文件；加上胜利音效后，被引用的文件数为18；而音频目录中存放着19个文件。四个数字各不相同，每个都有存在的理由。

这项审计的源头是 game-jam-lab 仓库的 f074703 提交，检查时间为2026年9月11日。需要说明的是，调查没有进行听感对比，也没有重新生成任何音乐——所有结论都来自代码和文件的静态分析。

游戏配乐审计源文件截图

区分选择记录与实际分配

制作简报记录了什么

项目的音乐制作简报（SUNO_MUSIC_BRIEF.md）记录了每首曲目的用途、标题、Suno歌曲ID、选定的A/B候选版本以及对应的游戏文件。这是一份制作阶段的"意图记录"。

敌方专属音乐的扩展笔记透露了一个细节：部分初始候选曲目因时长过短而被淘汰。团队随后按指定时长重新生成曲目，对仍然提前结束的候选版本进行了再次尝试。记录显示，最初的 Relay Hydra A 版本时长为1分54秒，Grid Leech A 为2分34秒。

这些时长是历史制作记录，本次调查并未重新检索并测量每一个Suno候选版本。它们只能支持一个较窄的结论：在制作阶段，时长确实是一项选择标准。

从候选到实现的演进

版本历史从 5ab837b 的候选记录推进到 290d302 的敌方专属音乐，这条线索帮助区分"存储的候选"和"真正进入实现"的音乐。两者之间的差距，正是审计需要弥合的部分。

追踪名称到播放键的映射链

两个字典，两种职责

游戏的音乐代码包含两个角色不同的字典。EncounterBGMKeys 将遭遇战或形态ID映射到BGM键；BGMStreams 再将这些键映射到音频文件。只有走完这两步，才能避免把一个换了名字的键误认为未使用的作品。

几个典型的映射关系：

遭遇ID	BGM键	引用文件
gearmaw	hunt	piston_hunt_loop.ogg
vaultback	vaultback	blue_vault_pulse.ogg
phase_mantis	phase_mantis	critical_parallax.ogg
prime_current_form_1	prime_current_form_1	prime_current_crownless_protocol.mp3

Gearmaw 的专属曲目使用了一个通用的键名 hunt——如果只看键名而不追踪映射链，很容易得出错误结论。

选择逻辑决定实际播放

desired_bgm_key() 函数才是实际选择的执行者。标题画面或画廊、普通战斗或Boss战、最终Boss形态，都会影响它的返回值。字典中存在某个条目，并不等于目标场景真的能触发它。选择分支同样经过了检查，但本次调查并未逐一通关所有场景。

18个槽位、17个BGM文件、含音效18个

自动化统计结果

对字典和Git追踪音频的自动统计得出四个不同计数：

统计对象	数量
`BGMStreams` 中的键	18
这些键引用的不同音频文件	17
加上独立胜利音效后的被引用文件	18
目标音频目录中的存储文件	19

差异的来源可以逐一解释。singularity 和 ending_world 共用 arch_singularity.ogg——两个独立的场景槽位并不产生两首作品。此前的地图曲目 subterranean_hunt.ogg 仍存储在目录中，但已不在被检查的BGM字典引用范围内；当前地图键指向的是 six_core_descent.mp3。这正是"替换后保留旧文件"的典型案例，调查并未删除这个未被引用的文件。

制作简报中"18首曲目"的说法，对应的是不同BGM文件加上胜利音效。将键、文件和存储材料的计数分开维护，能在清理或移植时发现重复和遗漏。

为什么每个计数都有意义

四个数字各自回答了不同的问题：18个槽位回答"游戏需要多少个播放位置"，17个文件回答"实际有多少段不同的BGM"，18个含音效的文件回答"总共有多少段被引用的音频"，19个存储文件回答"磁盘上有多少东西"。混淆它们，就会在移植或清理时做出错误决策。

实测文件时长与制作笔记的差异

ffprobe的精确测量

对从Git提取的19个音频文件运行 ffprobe 后，所有音频流均为48 kHz、2声道。部分选中文件的时长：

文件	ffprobe时长（秒）
blue_vault_pulse.ogg	180.040000
cascade_trinity.ogg	179.880000
critical_parallax.ogg	179.800000
nomad_victory_signal.mp3	12.973500

制作表中"3:00"和"0:13"是四舍五入的描述，不是精确的循环点或停止时间。上述数值也只是 ffprobe 报告的文件时长，并非对首尾可听声音的听感测量。

响度处理的未解之谜

简报记录了初始曲目被母带处理至约 -18 LUFS，但原始WAV文件并不在此仓库中。本次调查既未复现该母带处理过程，也无法确认当前每首曲目是否具有相同响度。后期加入的MP3文件是否经过了同等处理，同样不能假设。

LUFS（Loudness Units Full Scale）是国际电信联盟ITU-R BS.1770标准中定义的响度计量单位，用于统一衡量音频节目在感知上的响度，而非简单的峰值电平。它与传统的dBFS（分贝满刻度）不同：dBFS描述的是信号振幅相对于数字满刻度的位置，而LUFS综合了人耳对不同频率的敏感度（通过K加权滤波）和声道能量，更接近人实际听到的响度感受。流媒体平台通常将-14 LUFS左右作为参考响度，游戏音频则常将BGM母带处理至-18 LUFS上下，以留出足够的动态余量给音效和对白。LUFS测量值还包含短期、瞬时和积分（Integrated）等不同时间窗口，其中Integrated LUFS最常用于描述整首曲目的平均响度。要复现或验证母带处理结果，需要原始未压缩文件，因为MP3等有损格式在编码过程中可能已经改变了响度特性。

循环配置与听感审批是两回事

代码层面的循环启用

切换BGM时，实现层会为Ogg和MP3启用循环：

if next_stream is AudioStreamOggVorbis:
    (next_stream as AudioStreamOggVorbis).loop = true
elif next_stream is AudioStreamMP3:
    (next_stream as AudioStreamMP3).loop = true

Godot的 AudioStreamMP3 文档确实记录了 loop 属性。但代码请求重复播放，与音乐在首尾衔接处是否连贯，是完全不同的问题。本次调查没有试听接缝噪声、静音或节拍错位。

Ogg Vorbis和MP3是两种常见的音频压缩格式，但它们在游戏引擎中的循环支持方式有所不同。Ogg Vorbis格式原生支持在文件元数据中写入循环点（Loop Point）信息，Godot引擎可以读取这些元数据并据此在指定采样位置无缝跳回循环起点。相比之下，MP3格式的规范中并不包含标准的循环点元数据字段，因此Godot的AudioStreamMP3类通过loop属性和可选的loop_offset属性来实现循环：开启后将整个文件从头到尾反复播放。这意味着MP3的循环点固定在文件开头，无法像Ogg那样在文件中间设置精细的循环区间。对于BGM这类需要精确循环衔接的音乐，Ogg通常是更合适的选择；MP3更多用于一次性播放的音效或对循环精度要求不高的场景。文件时长本身也会受编码器填充（Encoder Delay/Padding）影响，ffprobe报告的长度与实际可听内容可能存在数十毫秒的差异。

交叉淡入淡出的参数

两个 AudioStreamPlayer 实例负责场景切换，配置的交叉淡入淡出时长为0.85秒。短促的胜利音效使用独立的播放器，不进入完整BGM循环。这些观察描述的是播放代码，而非实测的听感舒适度或混音质量。

为下一次替换保留足够证据

验证脚本的产出

验证脚本从固定提交中读取字典和音频，记录引用存在性、计数、SHA-256哈希以及 ffprobe 数据。保存的结果使用 ffprobe 9.0.1 生成。整个过程没有进行音频转换或上传。

下一次替换需要什么记录

理想情况下，下一次替换时应保留：候选ID、选择原因、游戏键、目标文件，以及听感验证的完成程度。这样的记录既能标识播放目的地，又能标明哪些检查仍然待办。

这套方法的价值不限于单个项目。任何有一定规模游戏音频库的项目，都可以用"选择记录→播放键→实际文件"三段式审计来发现隐藏的重复、遗漏和僵尸文件。"18首曲目"之所以说不清，是因为它把四个不同层面的计数混在了一起——拆开来看，每个数字都变得清晰可解释。