/audio-design

name: audio-design
description: >
  Engine-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

1. **Inventory first.** List every player or `AudioSource` and the bus or mixer group it outputs to; anything on Master or with no group bypasses the sliders. 2. **Lay out buses**: `Master ← Music ← MusicDuck`, `SFX`, `Ambience`, `UI`, `Voice`. Sliders map to bus gain; nobody sets per-clip volumes by hand. 3. **Map sliders to decibels**: square the 0..1 slider, convert with `linear_to_db`, mute at 0. 4. **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. 5. **Duck** music under voice with a sidechain compressor or by tweening a dedicated duck bus. 6. **Make music adaptive**: vertical layers for intensity, horizontal segments switched on bar lines for state changes, stingers for one-off events (see the reference). 7. **Vary repeated SFX** with sample pools and small pitch and volume offsets. 8. **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.

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 no