The Godot audio system is a multi-threaded architecture designed to handle low-level audio device communication, complex bus routing, real-time effect processing, and spatialized 3D/2D audio playback. The system is anchored by the AudioServer, which manages the audio graph and communicates with platform-specific AudioDriver implementations.
The audio system operates on a dedicated thread to ensure playback continuity regardless of the main loop's performance. Data flows from AudioStreamPlayer nodes through the AudioServer buses and finally to the hardware via an AudioDriver.
The following diagram illustrates the path from a resource on disk to the speaker output.
Audio Pipeline Overview
Sources: scene/audio/audio_stream_player.cpp110-127 scene/audio/audio_stream_player_internal.cpp1-50 doc/classes/AudioServer.xml7-8
AudioServer is the central hub for all audio operations. It manages the lifecycle of audio buses and orchestrates the mixing process.
AudioEffect resources and their corresponding AudioEffectInstance objects that perform the actual DSP on the audio thread doc/classes/AudioServer.xml60-68AudioStreamPlayback instances and ensures they are mixed into the correct buses scene/audio/audio_stream_player.cpp110-116The server uses a "Mix" callback from the AudioDriver to trigger the processing of the entire audio graph.
get_mix_count(): Returns the number of times the server has mixed audio, used by players to synchronize panning updates scene/2d/audio_stream_player_2d.cpp64 scene/3d/audio_stream_player_3d.h84start_playback_stream(): The primary entry point for nodes to begin audio playback scene/audio/audio_stream_player.cpp115 scene/2d/audio_stream_player_2d.cpp71Sources: doc/classes/AudioServer.xml1-160 scene/audio/audio_stream_player.cpp110-116 scene/3d/audio_stream_player_3d.h84
Platform-specific drivers bridge Godot's internal floating-point audio buffers with the OS-level audio APIs.
| Driver | Platform | Implementation File |
|---|---|---|
| WASAPI | Windows | drivers/wasapi/audio_driver_wasapi.cpp |
| PulseAudio | Linux | drivers/pulseaudio/audio_driver_pulseaudio.cpp |
| Web Audio | Web/WASM | platform/web/audio_driver_web.cpp |
| Dummy | Headless | servers/audio/audio_driver_dummy.cpp |
IAudioClient3 for shared mode engine periods drivers/wasapi/audio_driver_wasapi.cpp57-89 It utilizes a CMMNotificationClient to listen for OS-level device changes, specifically OnDefaultDeviceChanged drivers/wasapi/audio_driver_wasapi.cpp131-193pa_state_cb to monitor context readiness drivers/pulseaudio/audio_driver_pulseaudio.cpp49-71 and pa_server_info_cb to identify default input/output devices drivers/pulseaudio/audio_driver_pulseaudio.cpp111-118Sources: drivers/wasapi/audio_driver_wasapi.cpp131-193 drivers/pulseaudio/audio_driver_pulseaudio.cpp49-118
Godot provides three primary nodes for audio playback, each serving a different spatial context. These nodes typically wrap an AudioStreamPlayerInternal instance to handle shared logic.
Used for background music or UI sounds where 2D/3D positioning is not required. It mixes directly into a bus with optional stereo panning scene/audio/audio_stream_player.cpp184-195
max_polyphony scene/audio/audio_stream_player.cpp103-108Provides 2D spatialization. It calculates attenuation and panning based on the distance between the node and the AudioListener2D scene/2d/audio_stream_player_2d.cpp126-170
Math::pow(1.0f - dist / max_distance, attenuation) scene/2d/audio_stream_player_2d.cpp173Area2D intersections by querying the PhysicsDirectSpaceState2D scene/2d/audio_stream_player_2d.cpp85-123Provides 3D spatialization using Speaker-Placement Correction Amplitude Panning (SPCAP) scene/3d/audio_stream_player_3d.cpp50-52
AudioServer::SpeakerMode (Stereo, 3.1, 5.1, 7.1) to normalize gains scene/3d/audio_stream_player_3d.cpp63-76 scene/3d/audio_stream_player_3d.cpp112-127VelocityTracker3D to shift the actual_pitch_scale in real-time scene/3d/audio_stream_player_3d.h82-121ATTENUATION_INVERSE_DISTANCE, ATTENUATION_INVERSE_SQUARE_DISTANCE, and ATTENUATION_LOGARITHMIC scene/3d/audio_stream_player_3d.h51-56Sources: scene/audio/audio_stream_player.cpp31-150 scene/2d/audio_stream_player_2d.cpp126-173 scene/3d/audio_stream_player_3d.cpp50-127 scene/3d/audio_stream_player_3d.h51-56
AudioStream is the base resource for audio data. When played, it creates an AudioStreamPlayback object to maintain playback state (offset, loops, etc.) doc/classes/AudioStreamPlayer.xml28-33
| Format | Resource Class | Importer | Characteristics |
|---|---|---|---|
| WAV | AudioStreamWAV | ResourceImporterWAV | Supports PCM8, PCM16, IMA-ADPCM, and QOA doc/classes/ResourceImporterWAV.xml1-20 |
| Ogg Vorbis | AudioStreamOggVorbis | ResourceImporterOggVorbis | Compressed, supports seeking and looping modules/vorbis/audio_stream_ogg_vorbis.cpp39-145 |
AudioStreamWAV supports several compression modes. Notably, it includes the Quite OK Audio (QOA) format for high-quality, fast-decoding compressed audio editor/import/resource_importer_wav.cpp88-90
ResourceImporterWAV handles options for 8-bit forcing, mono conversion, and max rate clamping during import editor/import/resource_importer_wav.cpp78-90The AudioStreamPlaybackOggVorbis class handles real-time synthesis using the vorbis library.
_mix_internal function processes Vorbis packets into AudioFrame buffers modules/vorbis/audio_stream_ogg_vorbis.cpp39-145beat_length_frames is used to determine loop points modules/vorbis/audio_stream_ogg_vorbis.cpp51-53Sources: editor/import/resource_importer_wav.cpp36-101 modules/vorbis/audio_stream_ogg_vorbis.cpp39-191
This diagram bridges the conceptual "Audio System" to specific classes and functions in the codebase.
System to Code Mapping
Sources: scene/3d/audio_stream_player_3d.cpp52 modules/vorbis/audio_stream_ogg_vorbis.cpp39 doc/classes/AudioServer.xml1-100
On the Web platform, Godot uses a JavaScript-based bridge to the Web Audio API.
Sample class in JavaScript represents an AudioBuffer and its associated metadata like loopMode platform/web/js/libs/library_godot_audio.js53-120SampleNodeBus handles the routing of samples to Web Audio GainNode and ChannelSplitterNode objects platform/web/js/libs/library_godot_audio.js178-213Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.