godot-audio-systems

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 0c0182b848c3 · 23 Oct 2026Report an issue or request a re-scan

• Publisherthedivergentai GitHub userOwner of the repository this skill is read from
• Source folderthedivergentai/gd-agentic-skills/skills/godot-audio-systemsThe exact folder we audited
• LicenceLGPL-3.0As the repository states it
• Commit pinned for this verdict0c0182b848c3A new audit runs when the source changes
• Repository statusNot archivedLast push 6 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

---
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.

---

## 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` 

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/thedivergentai/gd-agentic-skills
git -C gd-agentic-skills checkout 0c0182b848c3

Works in

1. 2026-10-23
   ✓SAFE B 89 / 100

   first audit · source 0c0182b848c3

Questions about godot-audio-systems

• github.com/thedivergentai/gd-agentic-skills/tree/main/skills/god — the audited source at commit 0c0182b848c3 and every finding aboveObserved · 23 Oct 2026

Spotted something wrong? Report a correction · Methodology