GitHub
🎛️ v1.0.1 — Pure Rust MP3 Processing

Bake Auto Gain Into Your Files.
Before You Export.

Rekordbox Auto Gain doesn't work on CDJs. headroom simulates Auto Gain and permanently applies it to your files—so every track hits the same level on the booth.

Get Started → View on GitHub

The CDJ Auto Gain Problem

Rekordbox's Auto Gain feature analyzes your tracks and calculates gain adjustments to normalize loudness. It works great with controllers.

But when you export to USB for CDJs, Auto Gain values are ignored.

  • Quiet tracks from smaller labels need +3~4dB trim boost
  • Old releases and CD rips are often much quieter
  • Constant trim adjustments mid-set break your flow
  • Risk of clipping if you forget to reset trim
Current Workflow
Rekordbox analyzes track → Auto Gain: +2.5dB
↓
Export to USB
↓
CDJ ignores Auto Gain value ⚠️
↓
Track plays too quiet → Manual trim adjustment

The Solution: Bake It In

headroom simulates what Rekordbox Auto Gain does—but instead of storing a metadata value, it permanently applies the gain to your audio files.

headroom Workflow
headroom analyzes track → Headroom: +2.5dB
↓
Gain baked into audio file ✓
↓
Export to USB (Rekordbox metadata preserved)
↓
CDJ plays at correct level ✓

Same Algorithm, Permanent Result

headroom uses the same approach as Rekordbox Auto Gain: it measures True Peak and calculates maximum safe gain without clipping.

  • Analyzes LUFS and True Peak (same as Rekordbox)
  • Pure Rust MP3 processing—no external tools needed
  • Applies gain without limiting or compression
  • Preserves all Rekordbox metadata
Terminal — v1.0.1 with native MP3 processing
$ headroom

╭─────────────────────────────────────╮
│ headroom v1.0.1 │
│ Audio Loudness Analyzer & Gain │
╰─────────────────────────────────────╯

✓ Found 24 audio files
✓ Analyzed 24 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

● 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

● 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

? Apply lossless gain adjustment to 3 lossless + 2 MP3 files? [y/N] y

ℹ 2 MP3 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 MP3 files with re-encoding? [y/N] y

✓ Done! 7 files processed.
• 3 lossless files (ffmpeg)
• 2 MP3 files (native, lossless)
• 2 MP3 files (re-encoded)

Three-Tier MP3 Processing

headroom intelligently chooses the best method for each MP3 file based on available headroom, prioritizing quality preservation. v1.0.1 introduces pure Rust MP3 processing—no external tools required.

Native Lossless Pure Rust

For files with ≥1.5dB headroom to bitrate ceiling

  • Truly lossless global_gain modification
  • 1.5 dB step increments
  • No external dependencies
  • No re-encoding, no quality loss

Re-encode Opt-in

For files needing precise gain (<1.5dB headroom)

  • Arbitrary precision (e.g., +0.7dB)
  • Preserves original bitrate
  • Requires explicit confirmation
  • Inaudible loss at ≥256kbps

Skip

For files already at optimal level

  • No headroom available
  • True Peak already at ceiling
  • File is not modified
  • Shown in analysis but skipped

🔬 Why Re-encoding is Safe at High Bitrates

A common concern is quality loss when re-encoding MP3. However, for gain adjustment only at high bitrates (≥256 kbps), the degradation is completely inaudible.

  • Quantization noise below -90dB — far below audible threshold
  • ABX tests confirm — listeners cannot distinguish 320kbps→320kbps re-encodes
  • Waveform preserved — gain is simple multiplication, no compression or EQ applied
  • Club environment — any theoretical difference is masked by ambient noise and PA characteristics
  • High-quality encoder — headroom uses libmp3lame with -q:a 0 (best quality)

Built for Rekordbox DJs

Everything you need for consistent levels on CDJs.

🦀

Pure Rust Implementation

v1.0.1 introduces native MP3 global_gain manipulation. No mp3gain dependency—just install headroom and ffmpeg.

🎚️

Auto Gain Simulation

Uses the same LUFS/True Peak analysis as Rekordbox. Calculates maximum safe gain to hit optimal ceiling without clipping.

💾

Rekordbox Compatible

Files are modified in-place, preserving the same path. All your cue points, hot cues, beat grids, and tags remain intact.

🔒

Non-Destructive

Original files are backed up before processing. Native MP3 lossless is truly bit-perfect. Your source collection stays safe.

✅

Two-Stage Confirmation

First confirm lossless processing, then optionally enable MP3 re-encoding. You're always in control.

📊

Smart True Peak Ceiling

Based on AES TD1008: -0.5 dBTP for lossless, -2.0 dBTP for native MP3, bitrate-aware for re-encode.

Supported Formats

All the formats Rekordbox DJs actually use.

Format Method Precision Quality
FLAC ffmpeg volume filter Arbitrary Lossless
AIFF ffmpeg volume filter Arbitrary Lossless
WAV ffmpeg volume filter Arbitrary Lossless
MP3 Native (Pure Rust) 1.5dB steps Lossless
MP3 ffmpeg re-encode (opt-in) Arbitrary Inaudible at ≥256kbps

Installation

Get up and running in seconds.

🍎 macOS (Homebrew)

brew tap M-Igashi/tap brew install headroom

ffmpeg is installed automatically. No other dependencies needed.

🐧 Linux

sudo apt install ffmpeg cargo install --git https://github.com/M-Igashi/headroom

Requires Rust toolchain

🪟 Windows

winget install ffmpeg cargo build --release

Build from source with Rust

Stop adjusting trim on the booth.

Run headroom before your next USB export and play with consistent levels.

View on GitHub