godot-audio

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

1. Pick the player node:
   • AudioStreamPlayer — non-positional (music, UI, global SFX).
   • AudioStreamPlayer2D / AudioStreamPlayer3D — positional; volume/pan from distance.
2. Assign an AudioStream to stream (.ogg for music/loops, .wav for short SFX) and play(). Set autoplay for music that starts with the scene.
3. 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.
4. Control volume in dB, not linear (audio is logarithmic). 0 dB = unchanged, -80 dB ≈ silent. Convert with linear_to_db/db_to_linear.
5. Drive volume/mute from code with AudioServer by bus index.
6. 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 many overlapping copies, use an AudioStreamPlayer with 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)