headroom is an audio analysis tool designed to measure loudness (LUFS) and headroom in audio files, then apply precise gain adjustments to maximize loudness while preserving dynamics. It supports a wide range of file formats, including MP3, AAC/M4A, FLAC, AIFF, and WAV.
Key Features:
Lossless gain adjustment for MP3 and AAC files using the built-in mp3rgain library.
Batch processing capability for efficient workflow.
Metadata preservation to maintain Rekordbox tags, cue points, and other embedded data.
Smart True Peak ceiling targeting based on AES TD1008 recommendations.
Guided command-line interface with two-stage confirmation for safe processing.
Ideal for DJs, producers, and mastering engineers looking to normalize track levels without compromising audio quality. headroom ensures consistent playback volume across tracks while maintaining dynamic integrity. It can be installed via winget for Windows users.
README
headroom
Audio loudness analyzer and gain adjustment tool for mastering and DJ workflows.
What is this?
headroom simulates the behavior of Rekordbox's Auto Gain feature, but with a key difference: it identifies files with available headroom (True Peak below the target ceiling) and applies gain adjustment without using a limiter.
This tool is designed for DJs and producers who want to maximize loudness while preserving dynamics, ensuring tracks hit the optimal True Peak ceiling without clipping.
Key Features
Single binary: mp3rgain is built-in as a library — only ffmpeg required as external dependency
Uniform True Peak ceiling: -0.5 dBTP for every file by default — the most aggressive, AES TD1008–blessed delivery target — fully overridable via --tp-target
Multiple processing methods: ffmpeg for lossless formats, built-in mp3rgain for lossless MP3/AAC gain, ffmpeg re-encode for precise gain
Non-destructive workflow: Original files are backed up before processing
Metadata preservation: Audio tags (ID3v2, Vorbis comment, BWF) are preserved during processing, and files are overwritten in place so Rekordbox cue points and other external metadata remain linked
No limiter: Pure gain adjustment only — dynamics are preserved
Interactive CLI: Guided step-by-step process with two-stage confirmation
Scriptable CLI: Non-interactive mode for pipelines and CI (paths, globs, and flags)
Processing Methods
headroom selects the optimal method for each file based on format and headroom:
Format
Method
Precision
Quality Loss
FLAC, AIFF, WAV
ffmpeg
Arbitrary
None
MP3, AAC/M4A
mp3rgain (built-in)
1.5dB steps
None (global_gain modification)
MP3, AAC/M4A
ffmpeg re-encode
Arbitrary
Inaudible at ≥256kbps
Three-Tier Approach for Lossy Formats (MP3/AAC)
Each MP3 and AAC/M4A file is categorized into one of three tiers:
Native Lossless — ≥1.5 dB headroom to the configured ceiling
Applied automatically (no user confirmation needed)
Re-encode — headroom exists but <1.5 dB to ceiling
Uses ffmpeg for arbitrary precision gain
MP3: libmp3lame with -q:a 0 / AAC: libfdk_aac (falls back to built-in aac)
Preserves original bitrate; requires explicit user confirmation
Skip — no headroom available
True Peak Ceiling
Default — uniform delivery target
Every file targets -0.5 dBTP by default. This is the maximum-aggression value that AES TD1008 §7B describes for high-rate codec inputs ("may work satisfactorily with as little as -0.5 dBTP for the limiting threshold").
File class
Ceiling
Native lossless requires
Lossless (FLAC, AIFF, WAV)
-0.5 dBTP
—
MP3 (any bitrate)
-0.5 dBTP
TP ≤ -2.0 dBTP
AAC/M4A (any bitrate)
-0.5 dBTP
TP ≤ -2.0 dBTP
Why a single ceiling — pre-encode vs delivery
TD1008 has two related but distinct numbers:
Generic delivery recommendation (§4) — "Maximum True Peak level not exceed -1 dBTP at the codec input of lossy-encoded streams." This is the pre-encode limiter threshold.
High-rate codec relaxation (§7B) — "High-rate (e.g., 256 kbps) coders may work satisfactorily with as little as -0.5 dBTP" — also a codec-input threshold; "the limiting threshold may need to be reduced below the recommended -1.0 dBTP" for lower bit rates.
Both bullets describe the limiter that sits in front of the encoder. headroom operates in the opposite position: on already-encoded delivery files. There is no further codec stage downstream to absorb additional overshoot, so the bitrate-dependent slack TD1008 grants the pre-encode limiter does not transfer to the end product. A single, codec-agnostic delivery ceiling is the correct interpretation. -0.5 dBTP is chosen because it is the most aggressive value TD1008 sanctions for any limiter in the chain; lossless and high-rate lossy files were already at -0.5, and low-rate files now stop giving up an unnecessary 0.5 dB of loudness.
./
├── track01.flac ← Modified
├── track04.mp3 ← Modified
├── track08.m4a ← Modified
├── subfolder/
│ └── track06.mp3 ← Modified
└── backup/ ← Created by headroom
├── track01.flac ← Original
├── track04.mp3 ← Original
├── track08.m4a ← Original
└── subfolder/
└── track06.mp3 ← Original
Important Notes
Files are overwritten in place after backup — Rekordbox metadata remains linked
Only files with positive effective gain are shown and processed
MP3/AAC native lossless requires at least 1.5dB headroom to be processed
MP3/AAC re-encoding is opt-in and requires explicit confirmation
macOS resource fork files (._*) are automatically ignored
Technical Details
Why 1.5dB Steps?
Both MP3 and AAC store a "global_gain" value as an integer. Each ±1 increment changes the gain by 2^(1/4) = ±1.5 dB. This is a format-level constraint, not a tool limitation.
headroom uses the built-in mp3rgain library to directly modify this field — no decoding or re-encoding involved.
Native Lossless Threshold
Since native lossless gain only works in 1.5 dB steps, at least 1.5 dB of headroom to the configured target ceiling is required. The threshold scales automatically:
At ≥256kbps, re-encoding introduces quantization noise below -90dB — far below audible threshold. Only gain is applied (no EQ, compression, or dynamics processing), and original bitrate is preserved.