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: 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
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
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
Based on AES TD1008 recommendations. The ceiling depends on bitrate, not format:
Bitrate
Ceiling
Native lossless requires
Lossless (FLAC, AIFF, WAV)
-0.5 dBTP
—
Lossy ≥256kbps
-0.5 dBTP
TP ≤ -2.0 dBTP
Lossy <256kbps
-1.0 dBTP
TP ≤ -2.5 dBTP
How It Works
Scans the current directory for audio files (FLAC, AIFF, WAV, MP3, AAC/M4A)
Measures LUFS (Integrated Loudness) and True Peak using ffmpeg
Categorizes files by processing method:
Green: Lossless files (ffmpeg)
Yellow: MP3/AAC files with enough headroom for native lossless gain
Magenta: MP3/AAC files requiring re-encode
Displays categorized report
Two-stage confirmation:
First: "Apply lossless gain adjustment?" (lossless + native MP3/AAC)
Second: "Also process files with re-encoding?" (MP3/AAC requiring re-encode)
Creates backups and processes files
Example
$ cd ~/Music/DJ-Tracks
$ headroom
╭─────────────────────────────────────╮
│ headroom v1.7.2 │
│ Audio Loudness Analyzer & Gain │
╰─────────────────────────────────────╯
▸ Target directory: /Users/xxx/Music/DJ-Tracks
✓ Found 28 audio files
✓ Analyzed 28 files
● 3 lossless files (ffmpeg, precise gain)
Filename LUFS True Peak Target Gain
track01.flac -13.3 -3.2 dBTP -0.5 dBTP +2.7 dB
track02.aif -14.1 -4.5 dBTP -0.5 dBTP +4.0 dB
track03.wav -12.5 -2.8 dBTP -0.5 dBTP +2.3 dB
● 2 MP3 files (native lossless, 1.5dB steps, target: -2.0 dBTP)
Filename LUFS True Peak Target Gain
track04.mp3 -14.0 -5.5 dBTP -2.0 dBTP +3.0 dB
track05.mp3 -13.5 -6.0 dBTP -2.0 dBTP +3.0 dB
● 2 AAC/M4A files (native lossless, 1.5dB steps)
Filename LUFS True Peak Target Gain
track08.m4a -13.0 -4.0 dBTP -1.0 dBTP +3.0 dB
track09.m4a -12.5 -4.5 dBTP -1.0 dBTP +3.0 dB
● 2 MP3 files (re-encode required for precise gain)
Filename LUFS True Peak Target Gain
track06.mp3 -12.0 -1.5 dBTP -0.5 dBTP +1.0 dB
track07.mp3 -11.5 -1.2 dBTP -0.5 dBTP +0.7 dB
● 1 AAC/M4A files (re-encode required)
Filename LUFS True Peak Target Gain
track10.m4a -12.5 -1.8 dBTP -0.5 dBTP +1.3 dB
✓ Report saved: ./headroom_report_20250109_123456.csv
? Apply lossless gain adjustment to 3 lossless + 2 MP3 (lossless gain) + 2 AAC/M4A (lossless gain) files? [y/N] y
ℹ 2 MP3 + 1 AAC/M4A files have headroom but require re-encoding for precise gain.
• Re-encoding causes minor quality loss (inaudible at 256kbps+)
• Original bitrate will be preserved
? Also process these files with re-encoding? [y/N] y
? Create backup before processing? [Y/n] y
✓ Backup directory: ./backup
✓ Done! 10 files processed.
• 3 lossless files (ffmpeg)
• 2 MP3 files (native, lossless)
• 2 AAC/M4A files (native, lossless)
• 2 MP3 files (re-encoded)
• 1 AAC/M4A files (re-encoded)
Installation
headroom requires ffmpeg. Package managers install it automatically.
Platform
Command
macOS (Homebrew)
brew install M-Igashi/tap/headroom
Windows (winget)
winget install M-Igashi.headroom
Cargo
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.