godot-fun Audio Loudness Normalization
Loudness-normalize one audio file to a target LUFS with true-peak limiting. Preserves input format — same extension and sample rate as the source. Directories are not supported; run once per file to process a folder.
Rules
When this skill applies, read and follow skill-dependency-manager — run scripts as documented, install missing tools into .dependency/.
Quick Start
Default: -14 LUFS, -1.5 dBTP, output to <audio-dir>/audio-loudness-normalization/<audio-name>:
.dependency/python/python .ai/audio-loudness-normalization/normalize.py --audio path/to/audio.wav
Example: audio/sfx/tank/tank_move.wav → audio/sfx/tank/audio-loudness-normalization/tank_move.wav
LUFS Targets
| Category | LUFS |
|---|---|
| UI / clicks | -18 to -14 |
| Gameplay SFX | -16 to -12 |
| Explosions | -12 to -8 |
| Ambience | -22 to -18 |
| BGM / voice | -16 to -14 |
One category per folder. Mixed folders: split first, then normalize each file with matching -t.
Common Flags
--audio · -t / --target-lufs · -output
.dependency/python/python .ai/audio-loudness-normalization/normalize.py --audio Audio/SFX/click.wav -t -14
Never overwrite source files. The script writes only to audio-loudness-normalization/ (or -output). Supported inputs: .wav, .mp3, .ogg, .flac, .aac, .m4a, .wma.
Agent Notes
- Use the bundled script (two-pass
loudnorm), not hand-written FFmpeg. - Preserves input format — same extension and sample rate (
-arforced to source); does not resample. - Missing Python/FFmpeg → populate
.dependency/per skill-dependency-manager, retry same command. - Do not copy, move, or replace the source with the normalized output — tell the user where
audio-loudness-normalization/files are; they swap assets manually when ready. - Do not use
-outputpointing at the source file; the script refuses paths that would overwrite the input. - Do not fix uneven levels with per-asset volume in game code — re-normalize sources.
- Engine bus defaults and rationale: reference.md
Tests
From repo root:
.dependency/python/python .ai/audio-loudness-normalization/test_normalize.py
Manual CLI examples: cli/audio-loudness-normalization.md