scenario-godot-audio

Godot audio (audio implementer)

Target: Godot 4.7.2.stable, macOS Apple Silicon.

At expert level, the mix is designed as data and then measured. Bus layouts, music transitions and voice limits are written as specs. Every claim gets checked with numbers read from the mixer, since an agent cannot listen. Experts spend more effort deciding which sounds not to play than on playing them. That is the core of combat audio. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-godot-expert (channels, gd_run, the review loop, 4.7 traps).

Status (2026-10-02): 18 live jobs in 12 test groups, the round-2 checks (P15) and 13 offline tests all pass in Godot 4.7.2 (references/procedures.md, tests/code/godot-audio/).

Stance (the expert delta)

1. Measure headless; do not trust the "no sound" warning. The version deltas say --headless uses the Dummy driver and is silent. That is true for the speakers only. In 4.7.2 the Dummy driver still mixes in real time at 44.1 kHz. Peak meters, AudioEffectCapture and AudioEffectRecord all work there, and a -24.08 dBFS file reads -24.07 (observed). For timing, render offline with AudioStreamPlayback.mix_audio() (audio_meter.render_stream), sample-exact; real-time recordings start about 0.2 s late (observed).
2. Good combat audio comes from not playing sounds. Somberg: "a lot of audio technology is about not playing sounds" (Vjm-- 00:05:20). Cap each sound type, keep about two plays within a radius, and cull by distance before spending a voice. Measured here with 200 enemies firing at 10 Hz: the naive mix peaks at +32.4 dBFS before the limiter, while a 32-voice pool with caps peaks at +8.5 (P6).
3. Watch out for synchronous starts. With a hard cap and no cooldown, all 12 voices start on the same tick and end together. The mix then pulses in bursts (waveform sheet, P6). A per-type cooldown of 25 ms plus 4 randomized takes spreads them out, and the peak drops to -13.9 dBFS [added, measured].
4. Write music as a transition table and audit every reachable pair. Octodemy builds the matrix cell by cell (spBa 00:03:59). Bittmann wants every state change designed (dPXa 00:18:07). An unlisted pair is not a hard cut. In 4.7.2 it waits for the next beat, then fades the source out over about one beat (observed, P9). music_builder.audit_interactive lists the missing pairs.
5. Put hold on the transition that leaves the clip you want to come back to. Docs and Octodemy describe "hold previous" plus return-to-hold (spBa 00:07:49). In 4.7.2 the return only works when hold is set on the earlier transition, the one that leaves the interrupted clip. With hold on the transition into the stinger, all 6 variants went silent after the stinger (observed, P9).
6. Route everything through named buses, and reference them by name. Create Music and SFX buses first (DevWorm 07Ky, Game Dev Artisan h3_1). A player whose bus is renamed reads back "Master" and plays there. It recovers once the name is restored (observed). Audit scenes for players on Master or on missing buses (P13).
7. Measure spatial audio on the real curve. With 4.7.2 defaults (unit_size 10, max_db +3), a 3D source is flat from 1 m to 7 m, drops 3 dB at 10 m and 21 dB at 80 m. A low-pass removes a further 22 dB of 8 kHz at 20 m. area_mask defaults to 0, so Area3D reverb overrides do nothing until it is set to 1 (P7).
8. Condition generated audio before import, and verify it on the loaded resource. AI MP3s arrive hot (one test file: -8.4 LUFS, peak +0.99 dB) with silent padding. Normalize long files with two-pass loudnorm. Level short one-shots by peak, because loudnorm missed its target by 3 LU on a 0.5 s hit (observed, P4).