Godot 音频

先建总线布局，播放器用 bus 属性选总线，音量只在总线上调。

范围

先查内置

做法

总线布局

编辑器底部 Audio 面板建 Music SFX Voice，发送到 Master，存为项目设置 audio/buses/default_bus_layout 的默认路径 res://default_bus_layout.tres：

[gd_resource type="AudioBusLayout" format=3]

[sub_resource type="AudioEffectHardLimiter" id="AudioEffectHardLimiter_1"]
ceiling_db = -1.0

[resource]
bus/0/effect/0/effect = SubResource("AudioEffectHardLimiter_1")
bus/0/effect/0/enabled = true
bus/1/name = &"Music"
bus/1/volume_db = 0.0
bus/1/send = &"Master"
bus/2/name = &"SFX"
bus/2/volume_db = 0.0
bus/2/send = &"Master"

• 播放器 bus 填总线名，总线不存在时回退 Master，拼错不报错
• 限幅放 Master 上用 AudioEffectHardLimiter，AudioEffectLimiter 已弃用
• 区域换总线：Area2D Area3D 的 audio_bus_override 加 audio_bus_name，做洞穴混响
• 区域换总线只对 2D 3D 播放器生效，播放器 area_mask 默认 0，要勾上区域的层

音量设置

extends HSlider

@export var bus_name: StringName = &"Music"

func _ready() -> void:
	min_value = 0.0
	max_value = 1.0
	step = 0.01
	value = AudioServer.get_bus_volume_linear(AudioServer.get_bus_index(bus_name))
	value_changed.connect(_on_value_changed)

func _on_value_changed(linear: float) -> void:
	var bus := AudioServer.get_bus_index(bus_name)
	AudioServer.set_bus_volume_linear(bus, linear)
	AudioServer.set_bus_mute(bus, linear <= 0.0)

• 滑块用线性 0 到 1，直接当 volume_db 听感不均匀
• AudioServer.set_bus_volume_linear 与 get_bus_volume_linear 4.4+，内部做 linear_to_db
• 0 对应负无穷 dB，同时 set_bus_mute

混音

枪声、怪物出招、命中、UI 会同时响的游戏：

用压缩器侧链压低，参数要自己给：

func _ready() -> void:
	var duck := AudioEffectCompressor.new()
	duck.sidechain = &"Voice"
	duck.threshold = -18.0
	duck.ratio = 1.5
	duck.release_ms = 400.0
	AudioServer.add_bus_effect(AudioServer.get_bus_index(&"Music"), duck)

• threshold 默认 0 dB，触发声峰值不到 0 dBFS 就完全不压
• 压低量约为 2.08 × 峰值超出 threshold 的 dB × (1 − 1/ratio)，是常见公式的两倍
• 压低量随触发声响度变化

• 写死 -4 dB 这种固定量，或一个触发同时压多条总线，用电平加 AudioEffectAmplify，见 references/mixing.md

随机音效

编辑器里新建 AudioStreamRandomizer 拖入音效，或代码构造：

extends AudioStreamPlayer

@export var hits: Array[AudioStream] = []

func _ready() -> void:
	var random := AudioStreamRandomizer.new()
	random.playback_mode = AudioStreamRandomizer.PLAYBACK_RANDOM_NO_REPEATS
	random.random_pitch = 1.1
	random.random_volume_offset_db = 2.0
	for hit in hits:
		random.add_stream(-1, hit)
	stream = random

• random_pitch 是倍率，1.1 表示在 1/1.1 到 1.1 之间随机
• 按半音设用 random_pitch_semitones 4.6+
• random_volume_offset_db 2.0 表示正负 2 dB
• add_stream 第一参数小于 0 追加到末尾，第三参数是权重，默认 1.0

同时多声

extends AudioStreamPlayer

var _poly: AudioStreamPlaybackPolyphonic

func _ready() -> void:
	var poly := AudioStreamPolyphonic.new()
	poly.polyphony = 16
	bus = &"SFX"
	stream = poly
	play()
	_poly = get_stream_playback()

func play_sfx(sound: AudioStream, gain_db: float = 0.0) -> int:
	return _poly.play_stream(sound, 0.0, gain_db)

• 声音走播放器的 bus，4.7.2 实测 Stream 播放类型下 play_stream 的 bus 参数无效
• 要分总线就按总线各挂一个播放器
• 返回播放 ID，给 stop_stream set_stream_volume is_stream_playing 用
• 并发满了返回 AudioStreamPlaybackPolyphonic.INVALID_ID

动态音乐

4.3+。

• 切换片段：set(&"parameters/switch_to_clip", &"Combat")
• 转场表、拍点对齐、分层音量见 references/dynamic-music.md

导入格式

• 游戏里比原文件闷，先查播放器和总线，WAV 转 Ogg 只多一层有损压缩
• 96 kHz 素材按混音率重采样，开 force/max_rate 设 force/max_rate_hz 48000
• 立体声素材在 3D 播放器里保留声像宽度，定位不如单声道准

循环

• WAV 的 loop_mode 默认 Detect From WAV，跟随文件元数据
• 改完点 Reimport
• 运行时改共享 stream 的 loop 影响所有引用者，要不同行为就导入两份或 duplicate()
• 循环音频的播放器不发 finished

歌曲时间

get_playback_position() 按混音块更新，同一块内返回同一值，要加 AudioServer.get_time_since_last_mix() 再减输出延迟：

extends AudioStreamPlayer

var _latency: float = AudioServer.get_output_latency()

func song_time() -> float:
	return get_playback_position() + AudioServer.get_time_since_last_mix() - _latency

• get_output_latency() 开销大，取一次存起来
• 结果有抖动，丢弃比上一帧小的值
• stream 是 AudioStreamInteractive 时 get_playback_position() 恒为 0.0
• 另一种：play() 前记 Time.get_ticks_usec()，延迟取 AudioServer.get_time_to_next_mix() 加输出延迟
• 系统时钟法不抖，但长时间播放与声卡时钟漂移，长曲用上面的写法

空间音频

• 两者都有 max_distance panning_strength area_mask
• 听者放别处用 AudioListener2D 或 AudioListener3D 的 make_current()
• 全局声像强度见项目设置 audio/general/2d_panning_strength audio/general/3d_panning_strength
• 3D 滤波强度按衰减后的音量算，volume_db 也计入，低于 0 dB 越多压得越狠
• 不需要空气吸收的游戏，attenuation_filter_cutoff_hz 设 20500 关掉

@onready var _gun: AudioStreamPlayer3D = $Gun

func _ready() -> void:
	_gun.unit_size = 15.0
	_gun.volume_db = -8.0
	_gun.attenuation_filter_cutoff_hz = 20500.0

• 保留远处发闷又想调小某音效，改素材增益或给它单独总线，总线音量不参与滤波

陷阱

参考

• references/csharp.md：C# 项目先读，本文各节示例的 C# 写法
• references/mixing.md：分类总线布局、响度测量与目标、并发规则、固定量压低、混音自查
• references/dynamic-music.md：Interactive 转场、Synchronized 分层、Playlist
• https://docs.godotengine.org/en/stable/tutorials/audio/audio_buses.html