Index of every page on this site: llms.txt
All skills
jame581 avatar

/audio-system

@426e8ab
by Jan Mesarčjame581/godotprompter979 stars
63
Run it yourself

Use when implementing audio — audio buses, AudioStreamPlayer, spatial audio, music management, SFX pooling, and dynamic mixing

Use this Skill: https://skilld.dev/gh/jame581/godotprompter/audio-system

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈36 tokens for metadata: the name and description. ≈3.7k when used: this file. ≈4.7k more on demand in 4 files.

Description uses 1.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈141 characters, or 1.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Audio System in Godot 4.3+

All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.

Related skills: event-bus for decoupled audio triggers, save-load for persisting audio settings, resource-pattern for audio data containers.


1. Core Concepts

Audio Node Types

Node Dimensions Use For
AudioStreamPlayer Non-positional Music, UI sounds, global SFX
AudioStreamPlayer2D 2D positional Footsteps, gunfire, environmental sounds
AudioStreamPlayer3D 3D positional Same as 2D but in 3D space

Audio Bus Architecture

Godot routes all audio through buses (like a mixing console).

Master (always exists)
├── Music          → volume, effects for background music
├── SFX            → volume, effects for sound effects
│   ├── Footsteps  → sub-bus for fine-tuning
│   └── Weapons    → sub-bus for fine-tuning
└── UI             → volume for menu sounds

Setup: Bottom panel → Audio tab → Add buses, set names, route outputs.

Every AudioStreamPlayer has a bus property — set it to the target bus name (e.g., "SFX", "Music").


2. Basic Audio Playback

GDScript

extends Node2D

@onready var sfx_player: AudioStreamPlayer2D = $AudioStreamPlayer2D
@onready var music_player: AudioStreamPlayer = $MusicPlayer

func _ready() -> void:
    # Play background music (looping is set on the AudioStream resource)
    music_player.play()

func play_jump_sound() -> void:
    sfx_player.stream = preload("res://audio/sfx/jump.wav")
    sfx_player.play()

C#

using Godot;

public partial class AudioExample : Node2D
{
    private AudioStreamPlayer2D _sfxPlayer;
    private AudioStreamPlayer _musicPlayer;

    public override void _Ready()
    {
        _sfxPlayer = GetNode<AudioStreamPlayer2D>("AudioStreamPlayer2D");
        _musicPlayer = GetNode<AudioStreamPlayer>("MusicPlayer");
        _musicPlayer.Play();
    }

    public void PlayJumpSound()
    {
        _sfxPlayer.Stream = GD.Load<AudioStream>("res://audio/sfx/jump.wav");
        _sfxPlayer.Play();
    }
}

Looping Audio

Looping is configured on the AudioStream resource, not the player node:

  • WAV: Import tab → Loop Mode → Forward (or Ping-Pong)
  • OGG: Import tab → Loop → On, set Loop Offset
  • MP3: Import tab → Loop → On

Always use OGG Vorbis for music (smaller files, good quality). Use WAV for short SFX (PCM or QOA, cheap to decode). Avoid MP3 for SFX — depending on the encoder it can start with padding silence.


3. Audio Bus Management

Setting Volume from Code

Godot uses decibels (dB) for volume. Linear-to-dB conversion is required for sliders.

GDScript
# Get bus index by name
var bus_index: int = AudioServer.get_bus_index("SFX")

# Set volume in dB directly
AudioServer.set_bus_volume_db(bus_index, -6.0)  # -6 dB ≈ half amplitude (db_to_linear(-6.0) ≈ 0.5)

# Convert linear (0.0–1.0) to dB — use for UI sliders
func set_bus_volume_linear(bus_name: String, linear: float) -> void:
    var index := AudioServer.get_bus_index(bus_name)
    AudioServer.set_bus_volume_db(index, linear_to_db(linear))

# Mute / unmute a bus
AudioServer.set_bus_mute(bus_index, true)

# Read current volume as linear (for displaying on a slider)
func get_bus_volume_linear(bus_name: String) -> float:
    var index := AudioServer.get_bus_index(bus_name)
    return db_to_linear(AudioServer.get_bus_volume_db(index))
C#
int busIndex = AudioServer.GetBusIndex("SFX");

// Set volume in dB
AudioServer.SetBusVolumeDb(busIndex, -6.0f);

// Linear to dB conversion for UI sliders
public void SetBusVolumeLinear(string busName, float linear)
{
    int index = AudioServer.GetBusIndex(busName);
    AudioServer.SetBusVolumeDb(index, Mathf.LinearToDb(linear));
}

// Mute / unmute
AudioServer.SetBusMute(busIndex, true);

// Read current volume as linear
public float GetBusVolumeLinear(string busName)
{
    int index = AudioServer.GetBusIndex(busName);
    return Mathf.DbToLinear(AudioServer.GetBusVolumeDb(index));
}

Audio Bus Effects

Add effects to buses in the Audio panel (bottom dock). Common effects:

Effect Use For
Reverb Cave, cathedral, bathroom ambience
Delay Echo effects
Compressor Normalize loud/quiet sounds (master bus)
HardLimiter Prevent clipping on master bus (Limiter is deprecated)
LowPassFilter Muffled sounds (underwater, behind walls)
HighPassFilter Thin/tinny sound (radio, phone)
Chorus Thicken sounds
Distortion Gritty/overdrive effects
EQ Fine-tune frequency bands

Dynamic Effect Toggle

# Enable/disable an effect on a bus at runtime
var bus_index := AudioServer.get_bus_index("SFX")
var effect_index := 0  # First effect on the bus
AudioServer.set_bus_effect_enabled(bus_index, effect_index, true)

# Apply low-pass filter for "underwater" feel
func set_underwater(enabled: bool) -> void:
    var index := AudioServer.get_bus_index("SFX")
    # Assumes a LowPassFilter is the first effect on the SFX bus
    AudioServer.set_bus_effect_enabled(index, 0, enabled)

4. Spatial Audio (2D & 3D)

AudioStreamPlayer2D

Automatically adjusts volume and panning based on distance to the current AudioListener2D (or the centre of the screen if none is current).

Enemy (CharacterBody2D)
├── Sprite2D
└── AudioStreamPlayer2D   ← positioned at enemy's location
    bus = "SFX"
    max_distance = 1000.0
    attenuation = 1.0

Key properties:

Property Description Default
max_distance Beyond this distance, sound is silent 2000.0
attenuation Volume falloff curve (1.0 = linear, higher = sharper) 1.0
max_polyphony Max simultaneous instances of this player 1
panning_strength How much the sound pans left/right 1.0

AudioStreamPlayer3D

Same concept but in 3D. Works with AudioListener3D (or the Camera3D).

Key additional properties:

Property Description
unit_size Distance at which volume is 0 dB
max_db Maximum volume cap
attenuation_model Inverse, InverseSquare, Logarithmic, Disabled
doppler_tracking Enable Doppler effect for moving sources

AudioListener

# Make a specific camera the audio listener
# 2D: add AudioListener2D as child of Camera2D, call make_current()
# 3D: add AudioListener3D as child of Camera3D, call make_current()

# By default, the current Camera2D/3D acts as the listener.
# Only add an explicit AudioListener if you need a different listening position.
// 2D spatial player
public partial class Footsteps : AudioStreamPlayer2D
{
    public override void _Ready()
    {
        Bus = "SFX";
        MaxDistance = 1000.0f;     // Pixels at which volume reaches zero
        Attenuation = 1.0f;         // Linear falloff (higher = sharper)
        MaxPolyphony = 4;           // Allow overlapping footstep sounds
    }

    public void PlayStep() => Play();
}

// 3D spatial player
public partial class EngineHum : AudioStreamPlayer3D
{
    public override void _Ready()
    {
        Bus = "SFX";
        UnitSize = 4.0f;            // Meters at which volume is 0 dB
        MaxDistance = 50.0f;
        AttenuationModel = AttenuationModelEnum.InverseDistance;
    }
}

// Custom listener — overrides the default Camera2D / Camera3D listener.
public partial class FollowCamListener : AudioListener3D
{
    public override void _Ready() => MakeCurrent();
}

⚠️ Changed in Godot 4.7: The default area_mask on AudioStreamPlayer2D/AudioStreamPlayer3D changed from 1 to 0 (disabled) — the audio_bus_override feature on Area2D/Area3D (e.g. an underwater bus) stops working for players left at the default. Set area_mask back to layer 1 to restore it; masks explicitly set to anything other than layer 1 keep working. (The migration guide says "AudioStreamPlayer", but area_mask only exists on the 2D/3D variants.) See the 4.7 migration guide.


5. Music Manager (Autoload)

Crossfade between background tracks via a singleton autoload that manages two AudioStreamPlayer nodes and tweens their volume_db. Wire a Music audio bus so the settings menu can adjust music separately.

See references/music-manager.md for the full GDScript and C# autoload (crossfade, fade-out stop, music bus volume).


6. SFX Pool

Pre-instantiate a fixed pool of AudioStreamPlayer nodes; play_sfx(stream) finds the next free player and plays. Avoids per-shot instancing churn for high-volume effects (gunshots, footsteps, hits).

See references/sfx-pooling.md for the GDScript + C# pooled player and a 2D positional variant (pool of AudioStreamPlayer2D nodes that follow a target).


7. Audio Settings Integration

Wire HSliders in the settings menu to bus volumes via AudioServer.set_bus_volume_db(bus_idx, linear_to_db(value)). Persist with ConfigFile. Use the linear_to_db / db_to_linear helpers — never log-base by hand.

See references/audio-settings.md for the full settings menu wiring with persistence (GDScript + C#).


8. Interactive & Adaptive Music (Godot 4.3+)

Three stream types for adaptive music: AudioStreamPlaylist (sequenced or shuffled tracks), AudioStreamSynchronized (multiple stems played in sync — vertical layering for combat intensity), AudioStreamInteractive (clip transitions on triggers — state-driven music). Godot 4.4+ adds AudioStreamWAV.load_from_file() for runtime WAV loading.

Godot 4.7+: AudioStreamInteractive now exposes TRANSITION_TO_TIME_PREVIOUS_POSITION (TransitionToTime enum) to scripts — the destination clip resumes from its last played position if there was a previous transition from that clip, otherwise it plays from its start. Ideal for exploration ↔ combat music that picks up where it left off.

See references/interactive-music.md for the stream-type comparison, GDScript recipes, the 4.7+ resume-position transition, and the 4.4+ runtime-load example.


9. Audio Import Best Practices

Format Use For File Size Decode Latency Loop Support
WAV Short SFX Large None (PCM) / light (QOA, 4.4+ default) Via import
OGG Music, long SFX Small Minimal Via import
MP3 Music (fallback) Small Has padding Via import

Import Settings

In the Import dock (select an audio file):

  • Loop: Enable for music and ambient loops
  • BPM / Beat Count / Bar Beats: Set for rhythm-synced games
  • Force Mono (WAV only): Enable for 3D positional audio (stereo doesn't spatialize well); export OGG/MP3 as mono from your audio editor

Tip: Keep SFX as 16-bit WAV at 44.1kHz. Set the WAV import Compress > Mode to PCM (Uncompressed) for zero decode overhead — 4.4+ defaults to QOA (4.3 defaults to PCM, labelled Disabled). For music, OGG Vorbis at quality 6–8 is a good balance.


11. Common Pitfalls

Symptom Cause Fix
Sound doesn't play Player not in the scene tree Ensure the AudioStreamPlayer is add_child()'d before play()
Sound plays but no audio heard Bus muted or turned down Check the bus in the Audio panel; a misspelled bus name falls back to Master (bypassing your bus)
Music restarts on scene change Player is part of the scene, not an autoload Move music player to an autoload (MusicManager)
3D positional audio is silent No current Camera3D or AudioListener3D (2D uses the screen centre) Add an AudioListener3D or ensure a Camera3D is current
Sound clicks or pops Audio file has no fade-in/fade-out Add a tiny fade (2–5ms) at start/end of WAV in audio editor
Too many sounds playing at once No polyphony limit Set max_polyphony on players or use an SFX pool
Volume slider feels non-linear Using dB directly instead of linear conversion Use linear_to_db() / db_to_linear() for slider values
3D audio sounds mono/flat Stereo source file Use mono files (WAV: Force Mono in Import tab) for 3D spatialization
MP3 has silence at start Encoder padding in the file Use WAV for timing-critical SFX, OGG for music

12. Implementation Checklist

  • Audio buses are set up: Master, Music, SFX (minimum)
  • All AudioStreamPlayer nodes have the correct bus property assigned
  • Music uses OGG Vorbis format; short SFX uses WAV
  • Music player is in an autoload (survives scene changes)
  • Music crossfading is implemented for smooth transitions
  • SFX pool is used instead of creating new AudioStreamPlayer nodes dynamically
  • Volume sliders use linear_to_db() / db_to_linear() conversion
  • Near-zero slider values mute the bus (avoid linear_to_db(0.0) = -inf)
  • 3D audio sources use mono audio files for proper spatialization
  • Audio settings are saved and restored on game launch (ConfigFile or similar)
  • Looping is configured on the AudioStream resource, not in code
  • Interactive/adaptive music uses AudioStreamPlaylist, AudioStreamSynchronized, or AudioStreamInteractive (Godot 4.3+) instead of manual track-switching code

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts29d3 checks · Risk SAFE
  • Gen Agent Trust Hub29d

    The skill provides comprehensive documentation and code samples for implementing audio systems in Godot 4.3+. It covers core concepts, spatial audio, music management, and performance optimization techniques such as object pooling and adaptive music streams. No security issues were detected.

  • Socket29d

    No alerts

  • Snyk29d

    Risk: LOW · No issues

Signed by skilld at 426e8ab. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 days ago.

Activeupdated last month

README badge

README badge for jame581/godotprompter/audio-system