Godot Audio Systems Agent Skill

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.

Godot 4.7: Audio Breaking Changes

• AudioEffectSpectrumAnalyzer.tap_back_pos removed — migrate analyzers to alternative tap APIs.
• AudioStreamPlayer default area_mask is now 0 (disabled), not layer 1. If using Area2D/Area3D audio_bus_override, explicitly set area_mask to layer 1 or your bus layer.

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.