Godot Audio Systems

Audio Systems

Expert mixing, spatial, pooling, and interactive-music patterns for Godot's audio engine.

NEVER Do (Expert Audio Rules)

Mixing & Buses

• NEVER set bus volume with linear values — set_bus_volume_db() is logarithmic. Use linear_to_db() for sliders OR everything will sound too loud until the last 5%.
• NEVER skip 'Bus Routing' — Playing music on the 'SFX' bus makes volume menus useless. Strictly route every player to its dedicated sub-bus (Music, SFX, UI, Voice).
• NEVER use 'Master' for gameplay sounds — Dedicate Master to final limiting. Route all gameplay to sub-groups so you can mute/duck categories.

Positional & Spatial

• NEVER use 3D players without an Attenuation Model — Default is NONE. If you don't set it to Inverse Distance, a whisper on the other side of the map will be global volume.
• NEVER play 3D sounds exactly on top of the listener — Causes "Panning Jitter" where the sound snaps between Left/Right speakers. Offset by 0.1 units.
• NEVER forget Doppler for high-speed objects — A car flying by without DOPPLER_TRACKING_PHYSICS_STEP feels flat and static.

Performance & Polish

• NEVER spam same-frame sounds — Playing 50 explosions at once causes constructive interference (clipping/distortion). Use a Limiter (audio_voice_limiter_manager.gd).
• NEVER instantiate nodes for one-shots — Creating a node, playing a 0.5s clap, and queue_free()ing causes frame-time spikes. Use a Pool.
• NEVER skip Crossfades/Transitions — Abrupt music cuts break immersion. Always use a 0.5s-1.0s Tween to bridge tracks.

Decision Matrix: Which AudioStreamPlayer?

Golden Path → Scripts

MANDATORY — open only the script that matches the row. Do not reinvent pools, duckers, or interactive graphs from memory. Do NOT Load every script below for one mix task.

Available Scripts (catalog)

audio_voice_pool_manager.gd

Priority voice pool with steal of lowest-priority oldest voice (hero voices protected).

audio_voice_limiter_manager.gd

Concurrency cap for identical SFX instances.

audio_bus_ducker_logic.gd

Sidechain-style dialogue-over-music ducking.

audio_bus_manager.gd

Runtime bus volume/mute helpers for Music/SFX/UI/Voice groups.

audio_manager.gd

Autoload entry for play-one-shot routing onto the pool.

audio_linear_volume_interpolator.gd

Musically-correct linear↔dB UI slider mapping.

audio_occlusion_raycast.gd

Raycast muffling via attenuation filter cutoff.

audio_environmental_reverb_zone.gd

Area3D-driven reverb/bus override zones.

audio_interactive_music_manager.gd

AudioStreamSynchronized vertical stem intensity.

interactive_music_graph.gd

AudioStreamInteractive horizontal clip graph.

audio_adaptive_music_player.gd

Adaptive music player wrapper for intensity-driven stems.

audio_footstep_surface_selector.gd

Physics-driven surface → sound-bank selection.

audio_procedural_generator_synth.gd

Realtime procedural tones for hums/engines/signals.

audio_reactive_visualizer_component.gd

FFT spectrum → gameplay/visual driver.

audio_visualizer.gd

Spectrum analyzer visualization helper.

subtitle_sync_system.gd

Playback-position-accurate subtitle sync (latency-compensated).

Expert Audio Patterns

Pooling (WHY)

Spawning AudioStreamPlayer.new() per footstep at 60 FPS ≈ 3600 nodes/minute and frame spikes. MANDATORY audio_voice_pool_manager.gd. Cap duplicate SFX with audio_voice_limiter_manager.gd — 50 same-frame explosions clip the mix.

Deep dive → audio-pooling-and-buses.md.

Bus architecture

Master = final limiter only. Gameplay → Music / SFX / UI / Voice. set_bus_volume_db(0.5) is wrong — use linear_to_db() for sliders.

Music transitions

Never hard-cut tracks — 0.5–2.0s Tween crossfade or BPM-aligned handoff. Vertical/horizontal adaptive scores → interactive-music-deep-dive.md, music-transitions.md.

Occlusion muffling

Ray source→listener; blocked → Tween attenuation_filter_cutoff_hz down — audio_occlusion_raycast.gd.

Subtitle sync (no timer drift)

pos = get_playback_position() + AudioServer.get_time_since_last_mix() - AudioServer.get_output_latency() — subtitle_sync_system.gd.

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Audio (tutorial index) — Entry point for buses, streams, effects, sync, mic, and TTS before diving into class pages.