godot-audio-systems

音频系统

面向 Godot 音频引擎的专家级混音、空间音效、对象池和互动音乐模式。

绝对不要做的事（专家音频规则）

混音与总线

• 绝对不要使用线性值设置总线音量——set_bus_volume_db() 使用对数值。滑块应使用 linear_to_db()，否则在最后 5% 之前，所有声音都会太响。
• 绝对不要跳过“总线路由”——在“SFX”总线上播放音乐会让音量菜单失去作用。务必将每个播放器严格路由到专用子总线（Music、SFX、UI、Voice）。
• 绝对不要将“Master”用于游戏音效——Master 应专用于最终限幅。将所有游戏音频路由到子组，以便静音或压低各类音效的音量。

定位与空间音效

• 绝对不要在没有衰减模型的情况下使用 3D 播放器——默认值为 NONE。如果不将其设为 Inverse Distance，地图另一端的耳语也会以全局音量播放。
• 绝对不要在听者正上方播放 3D 音效——这会导致“声像抖动”，让声音在左右扬声器之间跳变。将位置偏移 0.1 个单位。
• 高速物体绝对不要忘记多普勒效应——没有 DOPPLER_TRACKING_PHYSICS_STEP 的飞驰汽车听起来会平淡而静止。

性能与润色

• 绝对不要在同一帧内密集播放相同音效——一次播放 50 个爆炸声会产生相长干涉（削波/失真）。请使用 Limiter（audio_voice_limiter_manager.gd）。
• 绝对不要为单次播放实例化节点——创建节点、播放 0.5 秒的拍手声，再调用 queue_free() 会导致帧时间峰值。请使用对象池。
• 绝对不要跳过交叉淡化/转场——突然切断音乐会破坏沉浸感。始终使用 0.5 秒至 1.0 秒的 Tween 衔接曲目。

---

决策矩阵：该使用哪种 AudioStreamPlayer？

功能	AudioStreamPlayer	AudioStreamPlayer2D	AudioStreamPlayer3D
空间定位	全局	2D 声像	3D 定位
多普勒效应	否	否	是
衰减	否	基于距离	3D 衰减
混响发送	否	否	是
适用场景	音乐、UI、语音	2D 游戏	3D 游戏
性能	最快	中等	最慢

黄金路径 → 脚本

强制要求 — 只能打开与表格行对应的脚本。不要凭记忆重新设计音源池、闪避器或交互式图表。

不要加载下面的所有脚本来完成一项混音任务。

需求	脚本
一次性音效刷屏 / 语音抢占	强制要求 audio_voice_pool_manager.gd
限制相同音效数量（刺耳轰鸣）	强制要求 audio_voice_limiter_manager.gd
音乐上的对白	强制要求 audio_bus_ducker_logic.gd
总线布局 / 运行时静音	audio_bus_manager.gd
线性 UI 滑块 → dB	audio_linear_volume_interpolator.gd
墙体闷音	强制要求 audio_occlusion_raycast.gd
房间混响区域	audio_environmental_reverb_zone.gd
纵向强度音轨	强制要求 audio_interactive_music_manager.gd
横向片段图表	interactive_music_graph.gd + references/interactive-music-deep-dive.md
总线 / 音源池原理	references/audio-pooling-and-buses.md
交叉淡化 / BPM / 闪避	references/music-transitions.md
自适应音乐播放器封装	audio_adaptive_music_player.gd
自动加载音效入口	audio_manager.gd
脚步声表面音效库	audio_footstep_surface_selector.gd
程序化嗡鸣 / 引擎音	audio_procedural_generator_synth.gd
频谱 → 游戏玩法 / 视觉特效	audio_reactive_visualizer_component.gd, audio_visualizer.gd
对白字幕同步	subtitle_sync_system.gd

可用脚本（目录）

audio_voice_pool_manager.gd

优先级语音池，可抢占优先级最低且最早播放的语音（英雄语音受保护）。

audio_voice_limiter_manager.gd

限制相同音效实例的并发数量。

audio_bus_ducker_logic.gd

侧链式对白压低音乐音量。

audio_bus_manager.gd

用于运行时调整音乐、音效、UI 和语音组的总线音量与静音状态。

audio_manager.gd

自动加载入口，用于将单次播放路由到音源池。

audio_linear_volume_interpolator.gd

符合音乐听感的线性音量 ↔ dB UI 滑块映射。

audio_occlusion_raycast.gd

通过衰减滤波器截止频率实现射线检测闷音。

audio_environmental_reverb_zone.gd

由 Area3D 驱动的混响 / 总线覆盖区域。

audio_interactive_music_manager.gd

AudioStreamSynchronized 纵向音轨强度控制。

interactive_music_graph.gd

AudioStreamInteractive 横向片段图表。

audio_adaptive_music_player.gd

由强度驱动音轨的自适应音乐播放器封装。

audio_footstep_surface_selector.gd

由物理属性驱动的表面 → 音效库选择。

audio_procedural_generator_synth.gd

用于嗡鸣、引擎和信号的实时程序化音调。

audio_reactive_visualizer_component.gd

FFT 频谱 → 游戏玩法 / 视觉驱动器。

audio_visualizer.gd

频谱分析器可视化辅助工具。

subtitle_sync_system.gd

与播放位置精准同步的字幕（已补偿延迟）。

专业音频模式

池化（原因）

每次播放脚步声都创建一个 AudioStreamPlayer.new()，在 60 FPS 下约等于每分钟 3600 个节点，还会造成帧率骤降。必须使用 audio_voice_pool_manager.gd。使用 audio_voice_limiter_manager.gd 限制重复的音效——同一帧播放 50 个爆炸声会导致混音削波。

深入了解 → audio-pooling-and-buses.md。

总线架构

Master 仅用于最终限幅。游戏音频 → Music / SFX / UI / Voice。set_bus_volume_db(0.5) 是错误用法——滑块应使用 linear_to_db()。

音乐过渡

切勿硬切曲目——使用 0.5–2.0s 的 Tween 交叉淡化，或与 BPM 对齐的衔接。纵向／横向自适应配乐 → interactive-music-deep-dive.md、music-transitions.md。

遮挡闷音

从声源向监听者发射射线；若被阻挡，则通过 Tween 调低 attenuation_filter_cutoff_hz——audio_occlusion_raycast.gd。

字幕同步（无计时器漂移）

pos = get_playback_position() + AudioServer.get_time_since_last_mix() - AudioServer.get_output_latency()——subtitle_sync_system.gd。

参考资料

渐进式展开：仅在研究特定 API 时打开官方文档链接；需要切换到关联领域时再加载相关技能——不要预加载整个技能网络。

官方文档

• 音频（教程索引） — 在深入查看类页面前，了解总线、流、效果、同步、麦克风和 TTS 的入口。
• 音频总线 — 分贝刻度、Master／子总线路由，以及线性滑块值为何会破坏混音。
• 音频流 — AudioStreamPlayer / 2D / 3D 的用途、随机化器，以及音频流如何传至总线。
• 音频效果 — 用于闪避和环境区域的总线 FX 链（均衡器、滤波器、混响、压缩器、限幅器）。
• 将游戏与音频和音乐同步 — 用于 BPM 和字幕同步的播放位置辅助方法（get_time_since_last_mix、延迟）。
• 导入音频采样 — WAV/Ogg/MP3 的取舍会影响音效连发时的池大小和 CPU 开销。
• AudioServer — 运行时总线音量、静音、添加／移除效果，以及频谱分析器实例。
• AudioStreamPlayer — 供池和交叉淡化管理器使用的非位置音乐／UI／语音播放器 API。
• AudioStreamPlayer3D — 空间音效和遮挡所用的衰减模型、多普勒效应及滤波器截止频率。
• AudioStreamInteractive — 用于横向战斗↔探索音乐过渡的片段图／切换模式。
• AudioStreamSynchronized — 用于纵向强度混音的分轨叠加 API（set_sync_stream_volume）。

相关技能

前置条件

• godot-project-foundations — 在编写运行时混音代码前，必须先设置总线名称、导入默认值和项目音频延迟设置。
• godot-autoload-architecture — 音乐／SFX 池和总线管理器几乎总是 Autoload；使用此技能管理单例所有权和启动顺序。
• godot-gdscript-mastery — 类型化 Resource、信号以及 await/Tween 模式是池化、闪避和交互式音乐图的基础。

补充技能

• godot-tweening — 交叉淡化、侧链闪避渐变和遮挡截止频率扫描应由 Tween 驱动，而不是逐帧 lerp。
• godot-animation-player — Audio Playback + Call Method 轨道可让不同语言区域的对白 VO 和字幕保持帧同步。
• godot-dialogue-system — 将语音台词路由到 Voice/Dialog 总线，并应使用此技能的总线辅助工具触发音乐闪避。
• godot-raycasting-queries — 遮挡闷音需要使用从声源到接收者的正确 PhysicsRayQueryParameters3D 遮罩。
• godot-shaders-basics — 频谱分析器的幅值通常用于驱动着色器 uniform 或光照能量，以实现音频响应型 VFX。
• godot-ui-containers — 音量菜单需要将线性值映射为 dB（linear_to_db），并连接到总线索引，而不是直接使用滑块值。
• godot-save-load-systems — 持久化每条总线的音量／静音状态，让混音器设置在重新启动后仍然保留，而无需重写总线布局。

下游／使用方

• godot-performance-optimization — 池化后，如果语音池、多音并发或混音回调开销仍出现在性能分析器中，请转而使用此技能。
• godot-monte-carlo-balancer — 当 SFX 并发上限、“响度预算”或刷屏与清晰度之间的取舍需要通过模拟平衡测试时使用（搭配语音限制器）。
• godot-genre-rhythm — 使用音频同步计时辅助工具来处理音符判定窗口和 BPM 对齐的转场。
• godot-combat-system — 命中／爆炸音层必须共享 SFX 总线路由和语音抢占机制，避免战斗音效导致混音削波。

主技能

• godot-master — 库路由器和镜像模块入口；需要了解哪个领域技能负责跨领域音频问题时，请打开此技能。