gamedev-skills/awesome-gamedev-agent-skills / skills/disciplines/audio-design
audio-design
VerifiedEngine-neutral game audio technique: bus layout, volume sliders in decibels, loudness, ducking music under dialogue, adaptive music and SFX variation, with Godot, Unity and FMOD/Wwise mappings. Use when mixing a game, making music react to combat, fixing repetitive footsteps or beat sync, or a mix that clips or pumps. Not for the Godot audio API (`godot-audio`).
Audio design
Game audio is a mixing graph plus a music system. Every sound plays into a small set of buses
that the settings sliders and ducking act on, and music reacts to play through layers and
segments instead of one loop. This skill owns those decisions; godot-audio, Unity's
AudioMixer or FMOD/Wwise supply the API.
When to use
- Design a bus layout, volume sliders, group effects and a loudness target.
- Duck music and ambience under voice or big impacts.
- Build adaptive music, SFX variation, or beat-quantized gameplay.
Not this skill: Godot node, bus and stream API questions go to godot-audio; settings menu
layout goes to game-ui-ux; triggering sounds from hits goes through game-feel's feedback
bundle.
Workflow
- Inventory first. List every player or
AudioSourceand the bus or mixer group it outputs to; anything on Master or with no group bypasses the sliders. - Lay out buses:
Master ← Music ← MusicDuck,SFX,Ambience,UI,Voice. Sliders map to bus gain; nobody sets per-clip volumes by hand. - Map sliders to decibels: square the 0..1 slider, convert with
linear_to_db, mute at 0. - Set headroom and a loudness target: true peak at or below -1 dBTP; integrated loudness about -24 LUFS (±2) for console/PC on TV or speakers and about -18 LUFS (±2) for handheld and mobile. Streaming-music targets such as -14 LUFS are not game targets.
- Duck music under voice with a sidechain compressor or by tweening a dedicated duck bus.
- Make music adaptive: vertical layers for intensity, horizontal segments switched on bar lines for state changes, stingers for one-off events (see the reference).
- Vary repeated SFX with sample pools and small pitch and volume offsets.
- Measure, then listen. Capture a representative 2-5 minute session and meter it:
- Godot:
xvfb-run -a godot --path . --write-movie capture.avi --fixed-fps 60 --quit-after 9000(needs a renderer; Movie Maker crashes under--headless). Other engines: ask the user to record the game's output to a WAV and share the path. ffmpeg -hide_banner -nostats -i capture.avi -vn -af ebur128=peak=true:framelog=quiet -f null -prints integrated loudness (I:) and true peak (Peak:). Compare with step 4.- Then ask the user to listen on headphones and speakers and report whether ducking is audible but not pumping and whether music transitions land on the beat.
- Godot:
Patterns
Snippets are Godot 4.7 GDScript; the Unity 6.3 LTS and middleware equivalents follow each one.
1. Bus routing and slider-to-gain mapping
# Route sounds to named buses; control GROUPS, not individual clips.
sfx_player.bus = &"SFX"
music_player.bus = &"Music"
# Map a 0..1 settings slider to bus gain. Squaring the slider first spreads the
# audible change over the whole travel; a raw linear-amplitude slider puts most of
# the change in the bottom fifth.
func set_bus_volume(bus_name: StringName, slider01: float) -> void:
var idx := AudioServer.get_bus_index(bus_name)
var gain := clampf(slider01, 0.0, 1.0)
AudioServer.set_bus_mute(idx, gain <= 0.0) # true silence at 0
AudioServer.set_bus_volume_linear(idx, gain * gain) # = set_bus_volume_db(idx, linear_to_db(gain * gain))
# WRONG: AudioServer.set_bus_volume_db(idx, slider01): "0.5" is +0.5 dB (no audible
# change) and 0 is 0 dB (full volume).
Unity 6.3 LTS: expose the group's Volume as a mixer parameter, then
mixer.SetFloat("MusicVolume", 20f * Mathf.Log10(Mathf.Max(gain * gain, 0.0001f))) (the mixer
floor is -80 dB). An AudioSource whose Output group is empty plays outside your mixer groups,
so no category slider or snapshot affects it: route every source.
2. Ducking via sidechain (music dips under voice)
A compressor on the music bus, keyed by the voice bus, lowers the music while dialogue plays and releases afterwards. Starting values: threshold about -30 dB on the voice signal, ratio 4:1 to 8:1, attack as fast as the effect allows (up to ~10 ms), release 300-500 ms.
# Godot 4.7: AudioEffectCompressor reads its sidechain bus for threshold detection.
func _ready() -> void:
var duck := AudioEffectCompressor.new()
duck.sidechain = &"Voice" # the bus that triggers the dip
duck.threshold = -30.0 # dB, range -60..0
duck.ratio = 8.0 # range 1..48
duck.attack_us = 2000.0 # MICROseconds, range 20..2000 (2 ms is the maximum)
duck.release_ms = 400.0 # milliseconds, range 20..2000
AudioServer.add_bus_effect(AudioServer.get_bus_index(&"Music"), duck)
# No-compressor alternative: tween a dedicated "MusicDuck" bus that sits between
# Music and Master, so ducking never overwrites the player's Music slider.
func duck_music(active: bool) -> void:
var idx := AudioServer.get_bus_index(&"MusicDuck")
var from := AudioServer.get_bus_volume_db(idx)
var to := -12.0 if active else 0.0
create_tween().tween_method(
func(db: float) -> void: AudioServer.set_bus_volume_db(idx, db), from, to, 0.25)
Unity 6.3 LTS: add a Duck Volume effect to the Music group and a Send effect on the Voice group targeting it. FMOD Studio and Wwise have sidechain/auto-ducking on buses; prefer those over script tweens when the project already uses middleware.
3. SFX variation (kill the "machine gun" repeat)
# Godot 4.7: AudioStreamRandomizer picks a take (no immediate repeats by default)
# and randomizes pitch and volume on every play. No per-shot node allocation.
func make_footsteps(samples: Array[AudioStream]) -> void:
var rnd := AudioStreamRandomizer.new()
for s in samples:
rnd.add_stream(-1, s) # -1 appends; optional third arg = weight
rnd.random_pitch_semitones = 1.0 # up to +/-1 semitone (about 6%)
rnd.random_volume_offset_db = 2.0 # up to +/-2 dB
$Footsteps.stream = rnd
$Footsteps.max_polyphony = 4 # overlapping steps without new players
Unity 6.3 LTS: put the takes in an Audio Random Container asset (Random or Shuffle playback,
Avoid Repeating Last, volume and pitch randomization) and assign it to the AudioSource's
Audio Resource (AudioSource.resource); with Manual trigger each Play() picks a new take. For
full script control, keep an array of clips, pick one that differs from the last, set pitch in
a small range, and call PlayOneShot on a pooled AudioSource.
4. Beat-synced events (quantize to the music grid)
# Schedule gameplay/visuals on musical time, not frame time, so they land on beat.
const BPM := 120.0
const SECONDS_PER_BEAT := 60.0 / BPM
# What the player HEARS now: playback position, plus time since the last mix
# (the position only updates once per mixed chunk), minus output latency.
func song_time() -> float:
return ($Music.get_playback_position() + AudioServer.get_time_since_last_mix()
- AudioServer.get_output_latency())
func current_beat() -> int:
return floori(song_time() / SECONDS_PER_BEAT) # negative means beat 0 is not audible yet
# Quantize an action to the NEXT beat boundary instead of firing immediately.
func time_until_next_beat() -> float:
var time := song_time()
if time < 0.0:
return -time # pre-roll: wait for the first audible beat
return SECONDS_PER_BEAT - fposmod(time, SECONDS_PER_BEAT)
# At an exact non-negative beat boundary, NEXT means one full beat later.
Unity 6.3 LTS: read AudioSettings.dspTime and schedule with AudioSource.PlayScheduled(dspTime)
for sample-accurate starts.
Gotchas
- Slider values used as dB.
set_bus_volume_db(idx, 0.5)is +0.5 dB, and 0 is full volume. Convert, and square or cube the slider first: a raw linear-amplitude slider barely changes over most of its travel and then drops off at the bottom. - Sources that bypass the mix. A Unity
AudioSourcewith an empty Output, or a Godot player left onMaster, ignores the category sliders and snapshots. - Ducking that overwrites the player's slider. Tweening the Music bus back to 0 dB discards their setting. Duck a separate bus between Music and Master, or use the compressor.
- Godot
attack_usis in microseconds (20-2000), whilerelease_msis milliseconds; a value of 10 means 10 µs, not 10 ms. - Pumping. A fast release or high ratio makes the music audibly breathe after every line. Lengthen release (300-500 ms) or lower the ratio.
- Clipping the master. Summed sounds pass 0 dBFS and distort. Leave headroom; a limiter on Master is a safety net, not the mixer.
- Beat sync from frame time drifts within seconds. Use the playback position, plus time since
the last mix, minus output latency (Unity:
AudioSettings.dspTimeandPlayScheduled). - Stems started by separate players drift apart over a long loop. Use one synchronized
stream (Godot
AudioStreamSynchronized) or middleware. - Bar-quantized switches on
AudioStreamWAVnever quantize: only Ogg Vorbis and MP3 streams carrybpmandbar_beatsforAudioStreamInteractive. - Unbounded one-shot players leak and stack. Use
max_polyphony, a randomizer stream, or a pool; free onfinished. - Measuring in the editor with the meters alone. Editor meters show peak per bus, not integrated loudness over a session; meter a capture as in step 8.
References
references/adaptive-music.md: read when building layered or segmented music (stem sync, bar-quantized switches,AudioStreamSynchronized,AudioStreamInteractive, stingers, an intensity value with hysteresis).
Related skills
godot-audio: Godot players, buses, effects and import settings.game-feel: the feedback bundles that trigger impact sounds.game-ui-ux: the settings screen that holds the volume sliders.
Version notes
Last verified: 2026-11-11.
- Loudness targets: Sony ASWG-R001 (2013), -24 LUFS home and -18 LUFS portable, measured to ITU-R BS.1770; summarised at https://audiomediainternational.com/mobile-loudness-an-adaptive-approach (the original PDF is not publicly hosted by Sony).
- Godot 4.7:
AudioServer.set_bus_volume_linear,AudioEffectCompressor.sidechain/attack_us/release_ms,AudioStreamRandomizer,AudioStreamSynchronized(MAX_STREAMS= 32),AudioStreamInteractivewithTRANSITION_FROM_TIME_NEXT_BAR;bpm/bar_beatsexist onAudioStreamOggVorbisandAudioStreamMP3only (Godot 4.7.2 class reference). Movie Maker under--headlesscrashed in a local 4.7.2 test; it worked underxvfb-run. - Unity 6.3 LTS: Audio Random Container assigned via
AudioSource.resource; mixer floor -80 dB;AudioSettings.dspTimewithAudioSource.PlayScheduled. - ffmpeg
ebur128filter withpeak=truereports BS.1770 integrated loudness and true peak (https://ffmpeg.org/ffmpeg-filters.html#ebur128); tested with ffmpeg 6.1.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |