godot-audio-systems

$npx mdskill add thedivergentai/GD-Agentic-Skills/godot-audio-systems

Designs and implements Godot audio systems with expert patterns.

  • Solves audio mixing, spatial positioning, and performance pooling challenges.
  • Depends on AudioStreamPlayer variants, AudioBus, AudioServer, and AudioEffect nodes.
  • Recommends patterns based on game type, audio category, and performance needs.
  • Delivers code examples, bus routing diagrams, and configuration snippets.

SKILL.md

.github/skills/godot-audio-systemsView on GitHub ↗
---
name: godot-audio-systems
description: "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
- **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](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)](https://docs.godotengine.org/en/stable/tutorials/audio/index.html) — Entry point for buses, streams, effects, sync, mic, and TTS before diving into class pages.
- [Audio buses](https://docs.godotengine.org/en/stable/tutorials/audio/audio_buses.html) — Decibel scale, Master/sub-bus routing, and why linear slider values break mixing.
- [Audio streams](https://docs.godotengine.org/en/stable/tutorials/audio/audio_streams.html) — AudioStreamPlayer / 2D / 3D roles, randomizers, and how streams reach buses.
- [Audio effects](https://docs.godotengine.org/en/stable/tutorials/audio/audio_effects.html) — Bus FX chain (EQ, filters, reverb, compressor, limiter) for ducking and environment zones.
- [Sync the gameplay with audio and music](https://docs.godotengine.org/en/stable/tutorials/audio/sync_with_audio.html) — Playback-position helpers (`get_time_since_last_mix`, latency) for BPM and subtitle sync.
- [Importing audio samples](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_audio_samples.html) — WAV/Ogg/MP3 tradeoffs that decide pool size and CPU cost for SFX spam.
- [AudioServer](https://docs.godotengine.org/en/stable/classes/class_audioserver.html) — Runtime bus volume, mute, effect add/remove, and spectrum analyzer instances.
- [AudioStreamPlayer](https://docs.godotengine.org/en/stable/classes/class_audiostreamplayer.html) — Non-positional music/UI/voice player API used by pools and crossfade managers.
- [AudioStreamPlayer3D](https://docs.godotengine.org/en/stable/classes/class_audiostreamplayer3d.html) — Attenuation models, Doppler, and filter cutoff for spatial SFX and occlusion.
- [AudioStreamInteractive](https://docs.godotengine.org/en/stable/classes/class_audiostreaminteractive.html) — Clip graph / switch modes for horizontal combat↔explore music transitions.
- [AudioStreamSynchronized](https://docs.godotengine.org/en/stable/classes/class_audiostreamsynchronized.html) — Stem layering API (`set_sync_stream_volume`) for vertical intensity mixes.

### Related Skills

#### Prerequisites
- [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — Bus names, import defaults, and project audio latency settings must exist before runtime mix code.
- [godot-autoload-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-autoload-architecture/SKILL.md) — Music/SFX pools and bus managers are almost always Autoloads; use this for singleton ownership and boot order.
- [godot-gdscript-mastery](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-gdscript-mastery/SKILL.md) — Typed Resources, signals, and await/Tween patterns underpin pooling, ducking, and interactive music graphs.

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

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

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting audio concern.

More from thedivergentai/GD-Agentic-Skills

SkillDescription
godot-2d-animationExpert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0).
godot-2d-physicsExpert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
godot-3d-lightingExpert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment.
godot-3d-materialsExpert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters.
godot-3d-world-buildingExpert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG.
godot-ability-systemExpert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path.
godot-adapt-2d-to-3dExpert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
godot-adapt-3d-to-2dExpert patterns for simplifying 3D games to 2D including dimension reduction strategies, 2.5D fake-depth, isometric ports, camera flattening, physics conversion, 3D-to-sprite art pipeline, and control simplification. Use when porting 3D to 2D, building 2.5D / isometric / fake-depth gameplay, creating 2D versions for mobile, or prototyping. Trigger keywords: CharacterBody3D to CharacterBody2D, Camera3D to Camera2D, Vector3 to Vector2, flatten Z-axis, 2.5D, isometric, fake depth, Y-sort, simulated Z, orthogonal projection, 3D to sprite conversion, performance optimization.
godot-adapt-desktop-to-mobileExpert patterns for porting desktop games to mobile including touch control schemes (virtual joystick, gesture detection), UI scaling for small screens, performance optimization for mobile GPUs, battery life management, and platform-specific features. Use when creating mobile ports or cross-platform mobile builds. Trigger keywords: TouchScreenButton, virtual_joystick, gesture_detector, InputEventScreenTouch, InputEventScreenDrag, mobile_optimization, battery_saving, adaptive_performance, MOBILE_ENABLED.
godot-adapt-mobile-to-desktopExpert patterns for scaling mobile games to desktop including mouse/keyboard controls, increased resolution and graphical fidelity, expanded UI layouts, settings menus, window management, and platform-specific features. Use when creating desktop ports or cross-platform releases. Trigger keywords: mouse_controls, keyboard_shortcuts, resolution_scaling, graphics_settings, fullscreen_toggle, window_modes, Steam_integration, desktop_optimization.