Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท UI, Audio and Animation

Audio, Buses and Sound

Add sound to a Godot 4 game: AudioStreamPlayer, 2D and 3D positional audio, the AudioServer bus layout, effects, volume in decibels, music crossfades and sound pooling, with Python stand-ins.

Sound makes a game feel alive, and Godot's audio system is built around buses: sound sources send audio to named channels, and each bus can have volume, mute, solo and effects. A settings menu with Music and Sound sliders is just a way to change bus volumes.

The Godot audio engine cannot run on this site, so scripts are read-only and the runnable blocks are Python stand-ins for the maths (decibels, panning, falloff). Before this lesson read animation and tweens.

Players and streams

A stream is an audio resource: AudioStreamWAV, AudioStreamOggVorbis and AudioStreamMP3. A player node plays it:

Node Use
AudioStreamPlayer Non-positional sound: music, UI clicks
AudioStreamPlayer2D Sound positioned in 2D, louder and panned by distance to the listener
AudioStreamPlayer3D Positioned in 3D, with attenuation and optional Doppler effect

Use WAV for short effects (low CPU, no decoding), and Ogg Vorbis for music and long ambience (small files). Set an Ogg stream's loop in the import settings for music.

GDSCRIPT
extends Node

@onready var click: AudioStreamPlayer = $Click
@onready var music: AudioStreamPlayer = $Music

func _ready() -> void:
	music.stream = preload("res://audio/theme.ogg")
	music.bus = "Music"
	music.play()

func on_button_pressed() -> void:
	click.pitch_scale = randf_range(0.95, 1.05)   # tiny variation avoids repetition
	click.play()

Browsers (the Web export) do not allow audio until the player interacts with the page; Godot unlocks it automatically on the first click or key press.

The bus layout

Open the Audio panel at the bottom of the editor. A project starts with one Master bus. Add buses such as Music, SFX and UI, and set each player's bus property. Buses can send to another bus (usually Master), so lowering Master lowers everything. Add effects to a bus: Reverb for caves, LowPassFilter for a muffled underwater sound, Compressor to keep dialogue above music, Limiter on Master to stop clipping. Save the layout as default_bus_layout.tres.

flowchart LR
    M["Music player"] --> MB["Music bus"]
    S["Player footsteps"] --> SB["SFX bus<br/>Reverb"]
    U["Button click"] --> UB["UI bus"]
    MB --> MA["Master bus<br/>Limiter"]
    SB --> MA
    UB --> MA
    MA --> O["Speakers"]

Sources feed buses; buses feed Master; Master feeds the speakers.

Volume is measured in decibels

Godot sets volume in decibels (dB): 0 dB is the original level, negative values are quieter, and about -80 dB is silence. A linear slider (0 to 1) does not match how we hear, so convert with linear_to_db():

GDSCRIPT
func set_music_volume(value: float) -> void:   # value from a 0..1 slider
	var bus := AudioServer.get_bus_index("Music")
	AudioServer.set_bus_volume_db(bus, linear_to_db(value))
	AudioServer.set_bus_mute(bus, value <= 0.001)
Python Stand-in (Python, not Godot): linear to dB and back

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Every -6 dB halves the amplitude. A slider mapped straight to dB would make most of its travel feel loud, while the log mapping feels even.

Positional sound

AudioStreamPlayer2D and AudioStreamPlayer3D compute volume from the distance to the listener: by default the current Camera2D or Camera3D (or an AudioListener2D/3D node you add). 2D players have max_distance and attenuation; 3D players have unit_size, max_distance and an attenuation model (inverse distance, inverse square, logarithmic). Panning follows the left-right position of the source.

Python Stand-in (Python, not Godot): distance attenuation and stereo pan

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Music, crossfades and pooling

Fade between tracks with a tween on volume_db:

GDSCRIPT
func crossfade(next_stream: AudioStream) -> void:
	var incoming: AudioStreamPlayer = $MusicB if $MusicA.playing else $MusicA
	var outgoing: AudioStreamPlayer = $MusicA if incoming == $MusicB else $MusicB
	incoming.stream = next_stream
	incoming.volume_db = -40.0
	incoming.play()
	var t := create_tween().set_parallel(true)
	t.tween_property(incoming, "volume_db", 0.0, 1.5)
	t.tween_property(outgoing, "volume_db", -40.0, 1.5)
	t.chain().tween_callback(outgoing.stop)

An AudioStreamPlayer plays one sound at a time unless you raise max_polyphony. Rapid effects (gunshots, coins) should use a pool of players, or max_polyphony, rather than creating a new node per shot. For random variation use an AudioStreamRandomizer resource that picks from several clips and varies pitch.

Python Stand-in (Python, not Godot): a round-robin pool of sound players

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a volume of 0 dB mean?

    0 dB is unity gain. Negative values are quieter; about -80 dB is silent.
  2. 2. How should you connect a 0..1 volume slider to a bus?

    Loudness perception is logarithmic, so a linear slider must be converted to decibels.
  3. 3. Which format suits a short, frequently played sound effect?

    WAV needs no decoding, so many instances are cheap; Ogg suits music.
  4. 4. Where do you add a Reverb effect for only the sound effects?

    Effects live on buses; route the effect players to that bus.

Summary

  • Use AudioStreamPlayer, ...2D and ...3D for non-positional and positional sound.
  • Route sounds through buses (Music, SFX, UI) and put effects on buses; Master is the final mix.
  • Volume is in dB: convert sliders with linear_to_db(); every -6 dB halves the amplitude.
  • Use pools, max_polyphony and randomizers for rapid effects; crossfade music with a tween.

Next: Themes and Responsive UI