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?

Feature	AudioStreamPlayer	AudioStreamPlayer2D	AudioStreamPlayer3D
Spatial	Global	2D panning	3D positioning
Doppler	No	No	Yes
Attenuation	No	Distance-based	3D falloff
Reverb send	No	No	Yes
Use for	Music, UI, VO	2D games	3D games
Performance	Fastest	Medium	Slowest

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.

Need	Script
One-shot SFX spam / voice steal	MANDATORY audio_voice_pool_manager.gd
Cap identical SFX (ear-bleed)	MANDATORY audio_voice_limiter_manager.gd
Dialogue over music	MANDATORY audio_bus_ducker_logic.gd
Bus layout / runtime mute	audio_bus_manager.gd
Linear UI slider → dB	audio_linear_volume_interpolator.gd
Wall muffling	MANDATORY audio_occlusion_raycast.gd
Room reverb zones	audio_environmental_reverb_zone.gd
Vertical intensity stems	MANDATORY audio_interactive_music_manager.gd
Horizontal clip graph	interactive_music_graph.gd + references/interactive-music-deep-dive.md
Bus / pool WHY	references/audio-pooling-and-buses.md
Crossfade / BPM / duck	references/music-transitions.md
Adaptive music player wrapper	audio_adaptive_music_player.gd
Autoload SFX entry	audio_manager.gd
Footstep surface banks	audio_footstep_surface_selector.gd
Procedural hum / engine	audio_procedural_generator_synth.gd
Spectrum → gameplay / VFX	audio_reactive_visualizer_component.gd, audio_visualizer.gd
Dialogue subtitle sync	subtitle_sync_system.gd

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.
• Audio buses — Decibel scale, Master/sub-bus routing, and why linear slider values break mixing.
• Audio streams — AudioStreamPlayer / 2D / 3D roles, randomizers, and how streams reach buses.
• Audio effects — Bus FX chain (EQ, filters, reverb, compressor, limiter) for ducking and environment zones.
• Sync the gameplay with audio and music — Playback-position helpers (get_time_since_last_mix, latency) for BPM and subtitle sync.
• Importing audio samples — WAV/Ogg/MP3 tradeoffs that decide pool size and CPU cost for SFX spam.
• AudioServer — Runtime bus volume, mute, effect add/remove, and spectrum analyzer instances.
• AudioStreamPlayer — Non-positional music/UI/voice player API used by pools and crossfade managers.
• AudioStreamPlayer3D — Attenuation models, Doppler, and filter cutoff for spatial SFX and occlusion.
• AudioStreamInteractive — Clip graph / switch modes for horizontal combat↔explore music transitions.
• AudioStreamSynchronized — Stem layering API (set_sync_stream_volume) for vertical intensity mixes.

Related Skills

Prerequisites

• godot-project-foundations — Bus names, import defaults, and project audio latency settings must exist before runtime mix code.
• godot-autoload-architecture — Music/SFX pools and bus managers are almost always Autoloads; use this for singleton ownership and boot order.
• godot-gdscript-mastery — Typed Resources, signals, and await/Tween patterns underpin pooling, ducking, and interactive music graphs.

Complements

• godot-tweening — Crossfades, sidechain duck ramps, and occlusion cutoff sweeps should be Tween-driven, not per-frame lerps.
• godot-animation-player — Audio Playback + Call Method tracks keep dialogue VO and subtitles frame-locked across locales.
• godot-dialogue-system — Routes spoken lines to a Voice/Dialog bus and should trigger Music ducking from this skill’s bus helpers.
• godot-raycasting-queries — Occlusion muffling needs correct PhysicsRayQueryParameters3D masks from source to listener.
• godot-shaders-basics — Spectrum analyzer magnitudes commonly drive shader uniforms or light energy for audio-reactive VFX.
• godot-ui-containers — Volume menus need linear→dB mapping (linear_to_db) wired to bus indices, not raw slider values.
• godot-save-load-systems — Persist per-bus volume/mute so mixer choices survive relaunch without rewriting bus layout.

Downstream / consumers

• godot-performance-optimization — Escalate here when voice pools, polyphony, or mix-callback cost still show up in profilers after pooling.
• godot-monte-carlo-balancer — Use when SFX concurrency caps, “loudness budget,” or spam-vs-clarity tradeoffs need simulated balance passes (pairs with voice limiters).
• godot-genre-rhythm — Consumes sync-with-audio timing helpers for note windows and BPM-aligned transitions.
• godot-combat-system — Hit/explosion layers must share SFX bus routing plus voice stealing so combat never clips the mix.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting audio concern.