godot-audio

Q: How do I install godot-audio?

Run npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-audio in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/godot-audio/ (personal) or .claude/skills/godot-audio/ (project).

by gamedev-skillsMedia & Creative

Play and mix audio in Godot 4.7: AudioStreamPlayer (2D/3D variants), audio buses with volume/mute and effects, music vs SFX routing, db/linear volume, and precise sync-to-beat playback timing. Use when playing sounds or music in a Godot project, routing AudioStreamPlayer nodes to buses, adjusting bus volume via AudioServer, or syncing gameplay to the beat.

Installs: 6.5K
Last 24h: +335
Trending rank: #896
Security: Pass

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-audio

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads godot-audio automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub PassSAFE ·This skill provides documentation and GDScript code examples for managing audio systems in the Godot 4.7 engine. It covers features such as audio buses, effects, and beat-accurate synchronization. No security issues were detected.

Socket PassNo alerts

Snyk PassLOW ·Risk: LOW · No issues

SKILL.md

The instructions your agent reads when the skill is triggered.

Godot Audio (4.x)

Play SFX and music, route them through buses, control volume in decibels, and time gameplay to the beat. Targets Godot 4.7.

When to use

Use when playing sound effects or music, routing audio to buses (Master/Music/SFX), adjusting volume/mute from code, adding bus effects (reverb, compressor), positional 3D audio, or syncing events to music.

When not to use: engine-agnostic audio design (adaptive music structure, mixing philosophy, ducking patterns) → audio-design; importing/encoding assets outside Godot.

Core workflow

Pick the player node:
- AudioStreamPlayer — non-positional (music, UI, global SFX).
- AudioStreamPlayer2D / AudioStreamPlayer3D — positional; volume/pan from distance.
Assign an AudioStream to stream (.ogg for music/loops, .wav for short SFX) and play(). Set autoplay for music that starts with the scene.
Route to a bus. Set the player's bus to a named bus (e.g. "Music", "SFX"). Define buses in the Audio panel (bottom dock); each can have volume, mute, solo, and effects.
Control volume in dB, not linear (audio is logarithmic). 0 dB = unchanged, -80 dB ≈ silent. Convert with linear_to_db/db_to_linear, or use the linear helpers (volume_linear on players, AudioServer.set_bus_volume_linear()), which convert for you.
Drive volume/mute from code with AudioServer by bus index.
For rhythm, compute precise playback time using output latency compensation.

Patterns

1. One-shot SFX (fire-and-forget)

@onready var sfx: AudioStreamPlayer = $Sfx   # stream assigned in the editor

func play_jump() -> void:
    sfx.pitch_scale = randf_range(0.95, 1.05)   # slight variation avoids fatigue
    sfx.play()

# For overlapping copies, raise sfx.max_polyphony (default 1), use an
# AudioStreamPolyphonic stream, or spawn short-lived players and free on `finished`.

2. Set a bus's volume and mute via AudioServer

func set_music_volume(linear_0_to_1: float) -> void:
    var bus := AudioServer.get_bus_index("Music")
    # Convert a 0..1 slider to decibels; clamp avoids -inf at 0.
    AudioServer.set_bus_volume_db(bus, linear_to_db(maxf(linear_0_to_1, 0.0001)))

func toggle_sfx(muted: bool) -> void:
    AudioServer.set_bus_mute(AudioServer.get_bus_index("SFX"), muted)

3. Crossfade between two music tracks

@onready var a: AudioStreamPlayer = $MusicA
@onready var b: AudioStreamPlayer = $MusicB

func crossfade_to(stream: AudioStream, secs := 1.5) -> void:
    b.stream = stream
    b.volume_db = -40.0
    b.play()
    var tw := create_tween().set_parallel(true)
    tw.tween_property(a, "volume_db", -40.0, secs)   # fade out current
    tw.tween_property(b, "volume_db", 0.0, secs)     # fade in next
    tw.chain().tween_callback(a.stop)
    var tmp := a; a = b; b = tmp                      # swap roles

4. Beat-accurate timing (compensate for output latency)

@onready var music: AudioStreamPlayer = $Music

func get_playback_time() -> float:
    # Add time since the last audio mix, subtract output latency, for sub-frame accuracy.
    var t := music.get_playback_position() + AudioServer.get_time_since_last_mix()
    return t - AudioServer.get_output_latency()

Pitfalls

Treating volume as linear. volume_db/set_bus_volume_db are decibels. Setting volume_db = 0.5 is nearly full volume, not half. Map sliders with linear_to_db.
linear_to_db(0.0) is -inf. It is silent, but tweening or doing math from -inf produces NaN. Clamp the linear value to a small minimum (e.g. 0.0001) before converting, or special-case 0 → mute. set_bus_volume_linear(bus, 0.0) stores -inf too.
Bus name typos fail quietly. get_bus_index("Muisc") returns -1; calls then error or no-op. Match the exact bus name from the Audio panel.
Short SFX cut off when the same player is retriggered → max_polyphony defaults to 1. Raise it (e.g. 4) so play() overlaps copies, or use an AudioStreamPolyphonic / separate players freed on finished.
Music doesn't loop unless the import/stream loop is enabled (.ogg import has a Loop option; AudioStreamWAV has loop_mode).
Syncing to get_playback_position() alone is jittery — it updates per audio mix, not per frame; add get_time_since_last_mix() and subtract get_output_latency().
3D audio inaudible → no AudioListener3D/Camera3D to hear it, or max_distance/ attenuation too tight, or wrong bus muted.

References

For the bus layout (.tres), adding effects (reverb/compressor/EQ) and side-chain ducking, AudioStreamPolyphonic/AudioStreamInteractive, microphone capture, and procedural audio with AudioStreamGenerator, read references/buses-and-effects.md.

Related skills

audio-design — engine-agnostic adaptive music, mixing, and ducking practice.
godot-animation — syncing animation/Tween to get_playback_position().
godot-ui-control — volume sliders wired to AudioServer.

FAQ

What does the godot-audio skill do?

How do I install godot-audio?

Run npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-audio in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/godot-audio/ (personal) or .claude/skills/godot-audio/ (project).

Which AI agents can use godot-audio?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is godot-audio safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains godot-audio?

It is published by gamedev-skills in gamedev-skills/awesome-gamedev-agent-skills. It has 6,528 recorded installs.