# Audio Loudness Normalization

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

- Skill: `godot-fun/audio-loudness-normalization` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add godot-fun/audio-loudness-normalization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/godot-fun/audio-loudness-normalization/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: godot-fun (https://skillmd.com/u/godot-fun)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/godot-fun/audio-loudness-normalization

---


# 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](../skill-dependency-manager.md) — 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>`:

```bash
.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`

```bash
.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

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 `-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 .ai/audio-loudness-normalization/test_normalize.py
```

Manual CLI examples: [cli/audio-loudness-normalization.md](../../../cli/audio-loudness-normalization.md)