godot-audio-systems

Files (17)

• SKILL.md
• audio_adaptive_music_player.gd · scripts/
• audio_bus_ducker_logic.gd · scripts/
• audio_bus_manager.gd · scripts/
• audio_environmental_reverb_zone.gd · scripts/
• audio_footstep_surface_selector.gd · scripts/
• audio_interactive_music_manager.gd · scripts/
• audio_linear_volume_interpolator.gd · scripts/
• audio_manager.gd · scripts/
• audio_occlusion_raycast.gd · scripts/
• audio_procedural_generator_synth.gd · scripts/
• audio_reactive_visualizer_component.gd · scripts/
• audio_visualizer.gd · scripts/
• audio_voice_limiter_manager.gd · scripts/
• audio_voice_pool_manager.gd · scripts/
• interactive_music_graph.gd · scripts/
• subtitle_sync_system.gd · scripts/

SKILL.md (first lines)

# Audio Systems

Expert guidance for Godot's audio engine and mixing architecture.

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

## Available Scripts

> **MANDATORY**: Read the appropriate script before implementing the corresponding pattern.

### [audio_voice_pool_manager.gd](scripts/audio_voice_pool_manager.gd)
Expert high-performance voice pooler with priority-based 'voice stealing' logic.

### [audio_occlusion_raycast.gd](scripts/audio_occlusion_raycast.gd)
Professional Raycast-based audio occlusion for dynamic muffling behind walls.

### [audio_interactive_music_manager.gd](scripts/audio_interactive_music_manager.gd)
Manager for vertical music layering using AudioStreamSynchronized for dynamic intensity.

### [audio_reactive_visualizer_component.gd](scripts/audio_reactive_visualizer_component.gd)
Expert FFT spectrum analysis component for driving logic-to-data visuals.

### [audio_bus_ducker_logic.gd](scripts/audio_bus_ducker_logic.gd)
Professional sidechain-style bus ducking (Dialogue-over-Music).

### [audio_procedural_generator_synth.gd](scripts/audio_procedural_generator_synth.gd)
Expert real-time synthesizer for procedural hums, engines, and signals.

### [audio_environmental_reverb_zone.gd](scripts/audio_environmental_reverb_zone.gd)
Dynamic reverb/bus effect management via Area3D trigger zones.

### [audio_voice_limiter_manager.gd](scripts/audio_voice_limiter_manager.gd)
Concurrency manager that prevents 'Ear Bleed' by capping identical SFX instances.

### [audio_linear_volume_interpolator.gd](scripts/audio_linear_volume_interpolator.gd)
Expert helper for smooth, musically-accurate UI volume slider mapping.

### [audio_footstep_surface_selector.gd](scripts/audio_footstep_surface_selector.gd)
Physics-driven surface detection and sound-bank selector for footsteps.

---

## AudioStreamPlayer Variants

### AudioStreamPlayer (Global/UI)

```gdscript
# No spatial positioning, same volume everywhere
# Use for: Music, UI sounds, voiceovers

@onready var music := AudioStreamPlayer.new()

func _ready() -> void:
    music.stream = load("res://audio/music_main.ogg")
    music.volume_db = -10  # Quieter
    music.autoplay = false
    music.bus = "Music"  # Route to Music bus
    add_child(music)
    music.play()
```

### AudioStreamPlayer2D (Positional)

```gdscript
# 2D panning based on distance from camera
# Use for: 2D games, top-down audio cues

extends Area2D

@onready var footstep := AudioStreamPlayer2D.new()

func _ready() -> void:
    footstep.stream = load("res://audio/footstep.ogg")
    footstep.max_distance = 500  # Audible range (pixels)
    footstep.attenuation = 2.0  # Falloff curve (higher = faster fadeout)
    add_child(footstep)

func play_footstep() -> void:
    if not footstep.playing:
        footstep.play()
```

### AudioStreamPlayer3D (Spatial)

```gdscript
# 3D spatial audio with doppler, reverb send
# Use for: 3D games, realistic sound positioning

extends Node3D

@onready var explosion := AudioStreamPlayer3D.new()

func _ready() -> void:
    explosion.stream = load("res://audio/explosion.ogg")
    explosion.unit_size = 10.0  # Size of sound source
    explosion.max_distance = 100.0  # Range
    explosion.attenuation_model = AudioStreamPlayer3D.ATTENUATION_INVERSE_DISTANCE

From bgrenat/godot-game-dev-studio, LGPL-3.0.

More from bgrenat/godot-game-dev-studio