git:20260825.544e8de to git:20260825.45bb87c

9 added, 9 removed. Audit A to A.

---

name: audio-loudness-normalization

- description: Batch-normalizes audio files to consistent LUFS loudness with true-peak limiting using FFmpeg. Use when the user wants loudness normalization, volume matching, unified audio levels, batch SFX/UI/BGM processing, or mentions LUFS, true peak, loudnorm, or inconsistent game audio.

+ description: Normalizes a single audio file to consistent LUFS loudness with true-peak limiting using FFmpeg. Use when the user wants loudness normalization, volume matching, unified audio levels, SFX/UI/BGM leveling, or mentions LUFS, true peak, loudnorm, or inconsistent game audio.

---

# Audio Loudness Normalization

- Batch-normalize audio to consistent LUFS with true-peak limiting. **Preserves input format** — same extension and sample rate as the source.

+ 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](../skill-dependency-manager.md) — run scripts as documented, install missing tools into `.dependency/`.

## Quick Start

- Default: **-14 LUFS**, **-1.5 dBTP**, output to a sibling `audio-loudness-normalization/` folder (source files are read-only):

+ Default: **-14 LUFS**, **-1.5 dBTP**, output to `<audio-dir>/audio-loudness-normalization/<audio-name>`:

```bash

- .dependency/python/python.exe .ai/audio-loudness-normalization/normalize.py path/to/audio_or_folder

+ .dependency/python/python.exe .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 batch with matching `-t`.

+ One category per folder. Mixed folders: split first, then normalize each file with matching `-t`.

## Common Flags

- `-t` / `--target-lufs` · `-o` / `--output-dir`

+ `--audio` · `-t` / `--target-lufs` · `-output`

```bash

- .dependency/python/python.exe .ai/audio-loudness-normalization/normalize.py Audio/SFX -t -14

+ .dependency/python/python.exe .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 `-o`). Directory inputs include subfolders. Supported inputs: `.wav`, `.mp3`, `.ogg`, `.flac`, `.aac`, `.m4a`, `.wma`.

+ **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

1. Use the bundled script (two-pass `loudnorm`), not hand-written FFmpeg.

2. **Preserves input format** — same extension and sample rate (`-ar` forced to source); does not resample.

3. Missing Python/FFmpeg → populate `.dependency/` per skill-dependency-manager, retry same command.

4. **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.

- 5. Do not use `-o` pointing at the source folder; the script refuses output paths that would overwrite inputs.

+ 5. Do not use `-output` pointing at the source file; the script refuses paths that would overwrite the input.

6. Do not fix uneven levels with per-asset volume in game code — re-normalize sources.

7. Engine bus defaults and rationale: [reference.md](reference.md)

## Tests

From repo root:

```bash

.dependency/python/python.exe .ai/audio-loudness-normalization/test_normalize.py

```