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?

| 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](scripts/audio_voice_pool_manager.gd) |

| Cap identical SFX (ear-bleed) | MANDATORY [audio_voice_limiter_manager.gd](scripts/audio_voice_limiter_manager.gd) |

| Dialogue over music | MANDATORY [audio_bus_ducker_logic.gd](scripts/audio_bus_ducker_logic.gd) |

| Bus layout / runtime mute | [audio_bus_manager.gd](scripts/audio_bus_manager.gd) |

| Linear UI slider → dB | [audio_linear_volume_interpolator.gd](scripts/audio_linear_volume_interpolator.gd) |

| Wall muffling | MANDATORY [audio_occlusion_raycast.gd](scripts/audio_occlusion_raycast.gd) |

| Room reverb zones | [audio_environmental_reverb_zone.gd](scripts/audio_environmental_reverb_zone.gd) |

| Vertical intensity stems | MANDATORY [audio_interactive_music_manager.gd](scripts/audio_interactive_music_manager.gd) |

| Horizontal clip graph | [interactive_music_graph.gd](scripts/interactive_music_graph.gd) + [references/interactive-music-deep-dive.md](references/interactive-music-deep-dive.md) |

| Bus / pool WHY | [references/audio-pooling-and-buses.md](references/audio-pooling-and-buses.md) |

| Crossfade / BPM / duck | [references/music-transitions.md](references/music-transitions.md) |

| Adaptive music player wrapper | [audio_adaptive_music_player.gd](scripts/audio_adaptive_music_player.gd) |

| Autoload SFX entry | [audio_manager.gd](scripts/audio_manager.gd) |

| Footstep surface banks | [audio_footstep_surface_selector.gd](scripts/audio_footstep_surface_selector.gd) |

| Procedural hum / engine | [audio_procedural_generator_synth.gd](scripts/audio_procedural_generator_synth.gd) |

| Spectrum → gameplay / VFX | [audio_reactive_visualizer_component.gd](scripts/audio_reactive_visualizer_component.gd), [audio_visualizer.gd](scripts/audio_visualizer.gd) |

| Dialogue subtitle sync | [subtitle_sync_system.gd](scripts/subtitle_sync_system.gd) |

Available Scripts (catalog)

[audio_voice_pool_manager.gd](scripts/audio_voice_pool_manager.gd)

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

[audio_voice_limiter_manager.gd](scripts/audio_voice_limiter_manager.gd)

Concurrency cap for identical SFX instances.

[audio_bus_ducker_logic.gd](scripts/audio_bus_ducker_logic.gd)

Sidechain-style dialogue-over-music ducking.

[audio_bus_manager.gd](scripts/audio_bus_manager.gd)

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

[audio_manager.gd](scripts/audio_manager.gd)

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

[audio_linear_volume_interpolator.gd](scripts/audio_linear_volume_interpolator.gd)

Musically-correct linear↔dB UI slider mapping.

[audio_occlusion_raycast.gd](scripts/audio_occlusion_raycast.gd)

Raycast muffling via attenuation filter cutoff.

[audio_environmental_reverb_zone.gd](scripts/audio_environmental_reverb_zone.gd)

Area3D-driven reverb/bus override zones.

[audio_interactive_music_manager.gd](scripts/audio_interactive_music_manager.gd)

AudioStreamSynchronized vertical stem intensity.

[interactive_music_graph.gd](scripts/interactive_music_graph.gd)

AudioStreamInteractive horizontal clip graph.

[audio_adaptive_music_player.gd](scripts/audio_adaptive_music_player.gd)

Adaptive music player wrapper for intensity-driven stems.

[audio_footstep_surface_selector.gd](scripts/audio_footstep_surface_selector.gd)

Physics-driven surface → sound-bank selection.

[audio_procedural_generator_synth.gd](scripts/audio_procedural_generator_synth.gd)

Realtime procedural tones for hums/engines/signals.

[audio_reactive_visualizer_component.gd](scripts/audio_reactive_visualizer_component.gd)

FFT spectrum → gameplay/visual driver.

[audio_visualizer.gd](scripts/audio_visualizer.gd)

Spectrum analyzer visualization helper.

[subtitle_sync_system.gd](scripts/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](scripts/audio_voice_pool_manager.gd). Cap duplicate SFX with [audio_voice_limiter_manager.gd](scripts/audio_voice_limiter_manager.gd) — 50 same-frame explosions clip the mix.

Deep dive → [audio-pooling-and-buses.md](references/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](references/interactive-music-deep-dive.md), [music-transitions.md](references/music-transitions.md).

Occlusion muffling

Ray source→listener; blocked → Tween attenuation_filter_cutoff_hz down — [audio_occlusion_raycast.gd](scripts/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](scripts/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.