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
Smart True Peak ceiling: Based on AES TD1008, uses -0.5 dBTP for high-quality files, -1.0 dBTP for low-bitrate
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: Files are overwritten in place, so Rekordbox tags, cue points, and other metadata remain intact
No limiter: Pure gain adjustment only — dynamics are preserved
Interactive CLI: Guided step-by-step process with two-stage confirmation
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 bitrate-aware ceiling
Truly lossless global_gain header modification in 1.5dB steps
cargo install headroom (ffmpeg must be installed separately)
Pre-built binaries are available on the Releases page (ffmpeg must be installed separately).
Build from Source
git clone https://github.com/M-Igashi/headroom.git
cd headroom
cargo build --release
Usage
cd ~/Music/DJ-Tracks
headroom
The tool will guide you through:
Scanning and analyzing all audio files
Reviewing the categorized report
Confirming lossless processing
Optionally enabling MP3/AAC re-encoding
Creating backups (recommended)
Output
CSV Report
Filename
Format
Bitrate (kbps)
LUFS
True Peak (dBTP)
Target (dBTP)
Headroom (dB)
Method
Effective Gain (dB)
track01.flac
Lossless
-
-13.3
-3.2
-0.5
+2.7
ffmpeg
+2.7
track04.mp3
MP3
320
-14.0
-5.5
-2.0
+3.5
mp3rgain
+3.0
track06.mp3
MP3
320
-12.0
-1.5
-0.5
+1.0
re-encode
+1.0
track08.m4a
AAC
256
-13.0
-4.0
-1.0
+3.0
native
+3.0
track10.m4a
AAC
256
-12.5
-1.8
-0.5
+1.3
re-encode
+1.3
Backup Structure
./
├── 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.
Bitrate-Aware Ceiling for Native Lossless
Since native lossless gain only works in 1.5dB steps, at least 1.5dB of headroom to the target ceiling is required:
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.