Expert patterns for Godot audio including AudioStreamPlayer variants (2D positional, 3D spatial), AudioBus mixing architecture, dynamic effects (reverb, EQ,compression), audio pooling for performance, music transitions (crossfade, bpm-sync), and procedural audio generation. Use for music systems, sound effects, spatial audio, or audio-reactive gameplay. Trigger keywords: AudioStreamPlayer, AudioStreamPlayer2D, AudioStreamPlayer3D, AudioBus, AudioServer, AudioEffect, music_crossfade, audio_pool, positional_audio, reverb, bus_volume.
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
— Playing 50 explosions at once causes constructive interference (clipping/distortion). Use a ().
NEVER spam same-frame sounds
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.
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.
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.
