Godot Audio (4.x)
Play SFX and music, route them through buses, control volume in decibels, and time
gameplay to the beat. Targets Godot 4.7.
When to use
- Use when playing sound effects or music, routing audio to buses (Master/Music/SFX),
adjusting volume/mute from code, adding bus effects (reverb, compressor), positional 3D
audio, or syncing events to music.
When not to use: engine-agnostic audio design (adaptive music structure, mixing
philosophy, ducking patterns) → audio-design; importing/encoding assets outside Godot.
Core workflow
- Pick the player node:
AudioStreamPlayer — non-positional (music, UI, global SFX).
AudioStreamPlayer2D / AudioStreamPlayer3D — positional; volume/pan from distance.
- Assign an
AudioStream to stream (.ogg for music/loops, .wav for short SFX)
and play(). Set autoplay for music that starts with the scene.
- Route to a bus. Set the player's
bus to a named bus (e.g. "Music", "SFX").
Define buses in the Audio panel (bottom dock); each can have volume, mute, solo, and
effects.
- Control volume in dB, not linear (audio is logarithmic).
0 dB = unchanged,
-80 dB ≈ silent. Convert with linear_to_db/db_to_linear, or use the linear helpers
(volume_linear on players, AudioServer.set_bus_volume_linear()), which convert for you.
- Drive volume/mute from code with
AudioServer by bus index.
- For rhythm, compute precise playback time using output latency compensation.
Patterns
1. One-shot SFX (fire-and-forget)
@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 overlapping copies, raise sfx.max_polyphony (default 1), use an
# AudioStreamPolyphonic stream, or spawn short-lived players and free on `finished`.
2. Set a bus's volume and mute via 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. Crossfade between two music tracks
@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. Beat-accurate timing (compensate for output latency)
@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()
Pitfalls
- Treating volume as linear.
volume_db/set_bus_volume_db are decibels. Setting
volume_db = 0.5 is nearly full volume, not half. Map sliders with linear_to_db.
linear_to_db(0.0) is -inf. It is silent, but tweening or doing math from -inf
produces NaN. Clamp the linear value to a small minimum (e.g. 0.0001) before converting,
or special-case 0 → mute. set_bus_volume_linear(bus, 0.0) stores -inf too.
- Bus name typos fail quietly.
get_bus_index("Muisc") returns -1; calls then error
or no-op. Match the exact bus name from the Audio panel.
- Short SFX cut off when the same player is retriggered →
max_polyphony defaults to 1.
Raise it (e.g. 4) so play() overlaps copies, or use an AudioStreamPolyphonic /
separate players freed on finished.
- Music doesn't loop unless the import/stream loop is enabled (
.ogg import has a
Loop option; AudioStreamWAV has loop_mode).
- Syncing to
get_playback_position() alone is jittery — it updates per audio mix,
not per frame; add get_time_since_last_mix() and subtract get_output_latency().
- 3D audio inaudible → no
AudioListener3D/Camera3D to hear it, or max_distance/
attenuation too tight, or wrong bus muted.
References
- For the bus layout (
.tres), adding effects (reverb/compressor/EQ) and side-chain
ducking, AudioStreamPolyphonic/AudioStreamInteractive, microphone capture, and
procedural audio with AudioStreamGenerator, read references/buses-and-effects.md.
Related skills
audio-design — engine-agnostic adaptive music, mixing, and ducking practice.
godot-animation — syncing animation/Tween to get_playback_position().
godot-ui-control — volume sliders wired to AudioServer.
1---2name: godot-audio3description: >4 Play and mix audio in Godot 4.7: AudioStreamPlayer (2D/3D variants), audio buses5 with volume/mute and effects, music vs SFX routing, db/linear volume, and precise6 sync-to-beat playback timing. Use when playing sounds or music in a Godot project,7 routing AudioStreamPlayer nodes to buses, adjusting bus volume via AudioServer, or8 syncing gameplay to the beat.9metadata:10 source: https://skillmd.com/skills/junmystery/godot-audio11---1213# Godot Audio (4.x)1415Play SFX and music, route them through buses, control volume in decibels, and time16gameplay to the beat. Targets **Godot 4.7**.1718## When to use1920- Use when playing sound effects or music, routing audio to buses (Master/Music/SFX),21 adjusting volume/mute from code, adding bus effects (reverb, compressor), positional 3D22 audio, or syncing events to music.2324**When *not* to use:** engine-agnostic audio *design* (adaptive music structure, mixing25philosophy, ducking patterns) → `audio-design`; importing/encoding assets outside Godot.2627## Core workflow28291. **Pick the player node:**30 - `AudioStreamPlayer` — non-positional (music, UI, global SFX).31 - `AudioStreamPlayer2D` / `AudioStreamPlayer3D` — positional; volume/pan from distance.322. **Assign an `AudioStream`** to `stream` (`.ogg` for music/loops, `.wav` for short SFX)33 and `play()`. Set `autoplay` for music that starts with the scene.343. **Route to a bus.** Set the player's `bus` to a named bus (e.g. `"Music"`, `"SFX"`).35 Define buses in the Audio panel (bottom dock); each can have volume, mute, solo, and36 effects.374. **Control volume in dB**, not linear (audio is logarithmic). `0 dB` = unchanged,38 `-80 dB` ≈ silent. Convert with `linear_to_db`/`db_to_linear`, or use the linear helpers39 (`volume_linear` on players, `AudioServer.set_bus_volume_linear()`), which convert for you.405. **Drive volume/mute from code** with `AudioServer` by bus index.416. **For rhythm**, compute precise playback time using output latency compensation.4243## Patterns4445### 1. One-shot SFX (fire-and-forget)4647```gdscript48@onready var sfx: AudioStreamPlayer = $Sfx # stream assigned in the editor4950func play_jump() -> void:51 sfx.pitch_scale = randf_range(0.95, 1.05) # slight variation avoids fatigue52 sfx.play()5354# For overlapping copies, raise sfx.max_polyphony (default 1), use an55# AudioStreamPolyphonic stream, or spawn short-lived players and free on `finished`.56```5758### 2. Set a bus's volume and mute via AudioServer5960```gdscript61func set_music_volume(linear_0_to_1: float) -> void:62 var bus := AudioServer.get_bus_index("Music")63 # Convert a 0..1 slider to decibels; clamp avoids -inf at 0.64 AudioServer.set_bus_volume_db(bus, linear_to_db(maxf(linear_0_to_1, 0.0001)))6566func toggle_sfx(muted: bool) -> void:67 AudioServer.set_bus_mute(AudioServer.get_bus_index("SFX"), muted)68```6970### 3. Crossfade between two music tracks7172```gdscript73@onready var a: AudioStreamPlayer = $MusicA74@onready var b: AudioStreamPlayer = $MusicB7576func crossfade_to(stream: AudioStream, secs := 1.5) -> void:77 b.stream = stream78 b.volume_db = -40.079 b.play()80 var tw := create_tween().set_parallel(true)81 tw.tween_property(a, "volume_db", -40.0, secs) # fade out current82 tw.tween_property(b, "volume_db", 0.0, secs) # fade in next83 tw.chain().tween_callback(a.stop)84 var tmp := a; a = b; b = tmp # swap roles85```8687### 4. Beat-accurate timing (compensate for output latency)8889```gdscript90@onready var music: AudioStreamPlayer = $Music9192func get_playback_time() -> float:93 # Add time since the last audio mix, subtract output latency, for sub-frame accuracy.94 var t := music.get_playback_position() + AudioServer.get_time_since_last_mix()95 return t - AudioServer.get_output_latency()96```9798## Pitfalls99100- **Treating volume as linear.** `volume_db`/`set_bus_volume_db` are decibels. Setting101 `volume_db = 0.5` is nearly full volume, not half. Map sliders with `linear_to_db`.102- **`linear_to_db(0.0)` is `-inf`.** It is silent, but tweening or doing math from `-inf`103 produces NaN. Clamp the linear value to a small minimum (e.g. `0.0001`) before converting,104 or special-case 0 → mute. `set_bus_volume_linear(bus, 0.0)` stores `-inf` too.105- **Bus name typos fail quietly.** `get_bus_index("Muisc")` returns `-1`; calls then error106 or no-op. Match the exact bus name from the Audio panel.107- **Short SFX cut off** when the same player is retriggered → `max_polyphony` defaults to 1.108 Raise it (e.g. 4) so `play()` overlaps copies, or use an `AudioStreamPolyphonic` /109 separate players freed on `finished`.110- **Music doesn't loop** unless the import/stream loop is enabled (`.ogg` import has a111 Loop option; `AudioStreamWAV` has `loop_mode`).112- **Syncing to `get_playback_position()` alone is jittery** — it updates per audio mix,113 not per frame; add `get_time_since_last_mix()` and subtract `get_output_latency()`.114- **3D audio inaudible** → no `AudioListener3D`/`Camera3D` to hear it, or `max_distance`/115 attenuation too tight, or wrong bus muted.116117## References118119- For the bus layout (`.tres`), adding effects (reverb/compressor/EQ) and side-chain120 ducking, `AudioStreamPolyphonic`/`AudioStreamInteractive`, microphone capture, and121 procedural audio with `AudioStreamGenerator`, read `references/buses-and-effects.md`.122123## Related skills124125- `audio-design` — engine-agnostic adaptive music, mixing, and ducking practice.126- `godot-animation` — syncing animation/Tween to `get_playback_position()`.127- `godot-ui-control` — volume sliders wired to `AudioServer`.