Audio server

Purpose

AudioServer (servers/audio_server.cpp, ~77 KB) owns the audio bus graph and the mixing pipeline. It accepts AudioStreamPlayback instances from AudioStreamPlayer* nodes, mixes them into a tree of buses (each with optional effects), and hands the result to the active audio driver.

Directory layout

servers/audio/
├── audio_server.{cpp,h}         Mixer, bus graph, AudioStream registry (~77 KB cpp)
├── audio_stream.{cpp,h}         AudioStream / AudioStreamPlayback abstract types
├── audio_driver_dummy.{cpp,h}   No-op driver for headless / disabled audio
├── audio_filter_sw.{cpp,h}      Software filter primitives (low-pass, high-pass, band-pass, notch)
├── audio_rb_resampler.{cpp,h}   Ring-buffer resampler used by streams
├── audio_effect.{cpp,h}         AudioEffect / AudioEffectInstance abstract types
└── effects/                     Built-in effects: reverb, chorus, distortion, eq6/eq10/eq21,
                                 limiter, hard-limiter, panner, phaser, pitch-shift, compressor,
                                 record, capture, spectrum-analyzer, delay, …

drivers/                          Concrete audio drivers
├── alsa/, pulseaudio/            Linux/BSD
├── coreaudio/, coremidi/         macOS, iOS
├── wasapi/, winmidi/             Windows
├── xaudio2/                      Windows fallback / GDK
├── alsamidi/                     Linux MIDI
└── (web platform supplies its own driver in platform/web/)

Bus graph

Audio in Godot is mixed through a tree of buses (default config: a single "Master" bus). Each bus has:

• A volume / mute / solo state.
• A list of AudioEffect instances.
• An optional send to a parent bus (so effects can stack).
• A configurable channel count (mono, stereo, 5.1, 7.1) inherited from the project setting audio/driver/output_channels.

The bus graph is loaded from an AudioBusLayout resource (saved as default_bus_layout.tres in the project root, or per-platform overrides). The editor's Audio dock (under editor/) is the main UI for editing it.

graph LR
    Player1[AudioStreamPlayer] -->|sample frames| Voice[AudioStreamPlaybackVoice]
    Voice --> Bus1[Bus: SFX]
    Player2[AudioStreamPlayer3D] --> Voice
    Bus1 -->|send| Master[Bus: Master]
    Bus1 --> Eff1[AudioEffectReverb]
    Eff1 --> Master
    Master --> Eff2[AudioEffectLimiter]
    Eff2 --> Driver[AudioDriver<br/>WASAPI/CoreAudio/PulseAudio/…]
    Driver --> Speakers

How a frame mixes

The audio driver thread (e.g., AudioDriverWASAPI::audio_thread_func) drives the cadence. On each callback:

1. The driver requests mix_buffer_size frames from AudioServer::_driver_process.
2. AudioServer gathers active AudioStreamPlaybacks (AudioStreamPlayer*::play-attached voices), resamples them via AudioRBResampler, and writes mono/stereo frames into per-bus accumulator buffers.
3. Each bus's effects are applied to its accumulator (effects are stateful per bus channel via AudioEffectInstance).
4. The resulting frames flow up the bus graph (via send) and reach the Master bus.
5. The Master bus's frames are written to the output buffer the driver consumed.

AudioStreamPlayer2D and AudioStreamPlayer3D add positional audio: panning and attenuation curves are computed each mix tick from the listener and emitter transforms, plus optional Area2D/Area3D audio bus reverb/effects overrides.

AudioStream types

scene/resources/audio_stream*.h plus modules contribute many stream types:

Stream	Source	Notes
AudioStreamWAV	scene/resources/audio_stream_wav.cpp	PCM / IMA-ADPCM / QOA samples, used for short SFX
AudioStreamOggVorbis	modules/vorbis/	Ogg Vorbis container
AudioStreamMP3	modules/mp3/	MP3 via minimp3 (vendored)
AudioStreamPlaylist	scene/resources/audio_stream_playlist.cpp	Sequenced playlist
AudioStreamRandomizer	scene/resources/audio_stream_randomizer.cpp	Picks a child stream randomly
AudioStreamPolyphonic	scene/resources/audio_stream_polyphonic.cpp	Manual voice management for layered SFX
AudioStreamGenerator	scene/resources/audio_stream_generator.cpp	User-supplied buffer generator (for procedural audio)
AudioStreamMicrophone	scene/resources/audio_stream_microphone.cpp	Live microphone input via AudioServer::input_*
AudioStreamSynchronized	scene/resources/audio_stream_synchronized.cpp	Multiple streams sharing a clock
Interactive music streams	modules/interactive_music/	Layered + transitioning streams

Each stream subclass implements instantiate_playback() to return an AudioStreamPlayback (the per-voice runtime state).

Effects

servers/audio/effects/ ships a library of effect implementations. Each is a Resource (AudioEffectReverb, AudioEffectChorus, …) plus an AudioEffectInstance subclass that holds per-channel state. Effects can also be authored externally via GDExtension.

Notable effects: Reverb (Schroeder + comb filter), EQ (6/10/21-band), Limiter/HardLimiter (the master bus typically ends in a HardLimiter), Compressor, Distortion, Chorus, Delay, PitchShift, Capture/Record (for procedural audio + recording), SpectrumAnalyzer (used by the editor's profiler).

Drivers

Driver	File	Platforms
AudioDriverALSA	drivers/alsa/audio_driver_alsa.cpp	Linux/BSD (low latency)
AudioDriverPulseAudio	drivers/pulseaudio/audio_driver_pulseaudio.cpp	Linux/BSD (default)
AudioDriverWASAPI	drivers/wasapi/audio_driver_wasapi.cpp	Windows (default)
AudioDriverCoreAudio	drivers/coreaudio/audio_driver_coreaudio.cpp	macOS, iOS
AudioDriverXAudio2	drivers/xaudio2/audio_driver_xaudio2.cpp	Windows fallback / GDK consoles
AudioDriverDummy	servers/audio/audio_driver_dummy.cpp	Headless / --audio-driver Dummy
Web	platform/web/audio_driver_web.cpp	Uses Web Audio API via Emscripten
Android	platform/android/audio_driver_opensl.cpp	OpenSL ES

A driver implements init, start, lock, unlock, finish, plus an audio_thread_func that pulls frames from AudioServer::_driver_process.

Key abstractions

Abstraction	File	Role
AudioServer	servers/audio_server.h	Mixer + bus graph + driver orchestration
AudioDriver	core/os/audio_driver.h	Abstract driver interface
AudioStream	servers/audio/audio_stream.h	Sample-data resource type
AudioStreamPlayback	servers/audio/audio_stream.h	Per-voice runtime state
AudioEffect / AudioEffectInstance	servers/audio/audio_effect.h	Bus effect abstraction
AudioBusLayout	scene/resources/audio_bus_layout.cpp	Persisted bus graph
AudioRBResampler	servers/audio/audio_rb_resampler.h	Sample-rate conversion

Integration points

• AudioStreamPlayer, AudioStreamPlayer2D, AudioStreamPlayer3D instantiate playbacks and attach them to a bus.
• Positional audio uses listener nodes (AudioListener2D, AudioListener3D) and the active Camera2D/Camera3D as the listener.
• The Capture effect feeds back into AudioStreamGenerator for procedural audio.
• The editor's audio profiler (under editor/debugger/) consumes AudioServer::get_bus_peak_volume_*_db to draw the level meters.

Entry points for modification

• Adding a new effect → subclass AudioEffect + AudioEffectInstance in servers/audio/effects/ and register it in register_server_types.cpp. Or ship one via GDExtension.
• Writing a new audio driver → subclass AudioDriver, register in register_driver_types.cpp for the relevant platform, and add the platform-specific code under drivers/<your_driver>/.
• Adding an audio stream format → subclass AudioStream/AudioStreamPlayback, plus a ResourceFormatLoader for the file extension. Examples in modules/mp3, modules/vorbis, modules/theora.