godot-audio

Godot Audio (4.x)

播放音效和音乐，将它们路由到总线，以分贝为单位控制音量，并让游戏玩法与节拍同步。目标版本为 Godot 4.7。

适用场景

• 播放音效或音乐、将音频路由到总线（Master/Music/SFX）、通过代码调整音量或静音、添加总线效果（混响、压缩器）、处理 3D 定位音频，或将事件与音乐同步时使用。

不适用场景： 与引擎无关的音频设计（自适应音乐结构、混音理念、闪避模式）→ audio-design；在 Godot 之外导入/编码资源。

核心工作流

1. 选择播放器节点：
   • AudioStreamPlayer — 非定位音频（音乐、UI、全局音效）。
   • AudioStreamPlayer2D / AudioStreamPlayer3D — 定位音频；音量/声像随距离变化。
2. 为 stream 指定 AudioStream（音乐/循环使用 .ogg，短音效使用 .wav）， 然后调用 play()。对于随场景启动的音乐，设置 autoplay。
3. 路由到总线。 将播放器的 bus 设置为已命名的总线（例如 "Music"、"SFX"）。 在 Audio 面板（底部停靠栏）中定义总线；每条总线都可以设置音量、静音、独奏和效果。
4. 以 dB 为单位控制音量，而不是线性值（音频是对数的）。0 dB = 不变， -80 dB ≈ 静音。使用 linear_to_db/db_to_linear 进行转换。
5. 通过代码使用 AudioServer 控制音量/静音，并通过总线索引操作。
6. **对于节奏同步，**使用输出延迟补偿计算精确的播放时间。

模式

1. 单次播放音效（触发后即不再管理）

@onready var sfx: AudioStreamPlayer = $Sfx   # stream assigned in the editor

func play_jump() -> void:
    sfx.pitch_scale = randf_range(0.95, 1.05)   # slight variation avoids fatigue
    sfx.play()

# For many overlapping copies, use an AudioStreamPlayer with an
# AudioStreamPolyphonic stream, or spawn short-lived players and free on `finished`.

2. 通过 AudioServer 设置总线音量和静音

func set_music_volume(linear_0_to_1: float) -> void:
    var bus := AudioServer.get_bus_index("Music")
    # Convert a 0..1 slider to decibels; clamp avoids -inf at 0.
    AudioServer.set_bus_volume_db(bus, linear_to_db(maxf(linear_0_to_1, 0.0001)))

func toggle_sfx(muted: bool) -> void:
    AudioServer.set_bus_mute(AudioServer.get_bus_index("SFX"), muted)

3. 在两首音乐曲目之间交叉淡化

@onready var a: AudioStreamPlayer = $MusicA
@onready var b: AudioStreamPlayer = $MusicB

func crossfade_to(stream: AudioStream, secs := 1.5) -> void:
    b.stream = stream
    b.volume_db = -40.0
    b.play()
    var tw := create_tween().set_parallel(true)
    tw.tween_property(a, "volume_db", -40.0, secs)   # fade out current
    tw.tween_property(b, "volume_db", 0.0, secs)     # fade in next
    tw.chain().tween_callback(a.stop)
    var tmp := a; a = b; b = tmp                      # swap roles

4. 精确同步节拍（补偿输出延迟）

@onready var music: AudioStreamPlayer = $Music

func get_playback_time() -> float:
    # Add time since the last audio mix, subtract output latency, for sub-frame accuracy.
    var t := music.get_playback_position() + AudioServer.get_time_since_last_mix()
    return t - AudioServer.get_output_latency()

注意事项

• 将音量误当作线性值。 volume_db/set_bus_volume_db 使用分贝。设置 volume_db = 0.5 时，音量接近最大，而不是一半。使用 linear_to_db 映射滑块值。
• linear_to_db(0.0) 的结果是 -inf。 转换前将线性值限制在一个较小的最小值（例如 0.0001），或对 0 进行特殊处理并将其设为静音。
• 总线名称拼写错误不会明显报错。 get_bus_index("Muisc") 会返回 -1；后续调用会报错 或不执行任何操作。请与 Audio 面板中的总线名称完全一致。
• 重复触发同一个播放器会截断较短的音效。 使用多个播放器、AudioStreamPolyphonic，或为每次播放创建一个 AudioStreamPlayer，并在 finished 后释放。
• 除非启用了导入/流循环，否则音乐不会循环（.ogg 导入设置中有 Loop 选项； AudioStreamWAV 提供 loop_mode）。
• 只使用 get_playback_position() 进行同步会产生抖动——它按音频混合周期更新， 而不是按帧更新；请加上 get_time_since_last_mix() 并减去 get_output_latency()。
• 3D 音频听不到 → 没有 AudioListener3D/Camera3D 监听，或 max_distance/ 衰减范围过小，或错误的总线处于静音状态。

参考资料

• 关于总线布局（.tres）、添加效果（混响/压缩器/EQ）和侧链闪避、 AudioStreamPolyphonic/AudioStreamInteractive、麦克风采集，以及使用 AudioStreamGenerator 生成程序化音频，请阅读 references/buses-and-effects.md。

相关技能

• audio-design — 与引擎无关的自适应音乐、混音和闪避实践。
• godot-animation — 将动画/Tween 与 get_playback_position() 同步。
• godot-ui-control — 将音量滑块连接到 AudioServer。