# headroom v1.7.2

> Bake Rekordbox Auto Gain into your audio files before CDJ export

headroom is a CLI tool that solves the CDJ Auto Gain problem for Rekordbox DJs. While Rekordbox's Auto Gain feature analyzes tracks and calculates gain adjustments, these values are ignored when exporting to USB for CDJ playback. headroom permanently applies the gain adjustment to your audio files, ensuring consistent loudness on any CDJ.

## The Problem

Rekordbox Auto Gain works great with DJ controllers but fails on CDJs:
- CDJs ignore Auto Gain metadata values
- Quiet tracks from smaller labels need +3-4dB trim boost
- Old releases and CD rips are often much quieter
- Constant manual trim adjustments break DJ flow

## The Solution

headroom simulates Rekordbox Auto Gain but permanently bakes the gain into audio files:
1. Analyzes LUFS and True Peak (same approach as Rekordbox)
2. Calculates maximum safe gain without clipping
3. Applies gain directly to audio file
4. Preserves all Rekordbox metadata (cue points, beat grids, hot cues)

## Key Features (v1.7.2)

- **Single binary**: Built-in mp3rgain 2.0 library — only ffmpeg required
- **Three-tier MP3 processing**: Built-in mp3rgain for lossless, ffmpeg re-encode for precise gain, skip if no headroom
- **AAC/M4A lossless gain**: Native lossless gain adjustment in 1.5dB steps via mp3rgain 2.0, ffmpeg re-encode fallback for precise gain
- **Two-stage confirmation**: First confirm lossless processing, then optionally enable re-encoding
- **Smart True Peak Ceiling**: -0.5 dBTP for lossless/high-bitrate, -1.0 dBTP for low-bitrate (AES TD1008)
- **Rekordbox Compatible**: In-place modification preserves all metadata
- **Non-Destructive**: Automatic backups before processing
- **Cross-platform**: macOS, Linux, and Windows binaries available

## Supported Formats

| Format | Extension | Method | Precision |
|--------|-----------|--------|-----------|
| FLAC | .flac | ffmpeg volume filter | Arbitrary |
| AIFF | .aiff, .aif | ffmpeg volume filter | Arbitrary |
| WAV | .wav | ffmpeg volume filter | Arbitrary |
| MP3 | .mp3 | mp3rgain (built-in) or ffmpeg re-encode | 1.5dB steps or arbitrary |
| AAC/M4A | .m4a, .aac, .mp4 | mp3rgain (built-in) or ffmpeg re-encode | 1.5dB steps or arbitrary |

## MP3 Processing Methods

| Method | When Used | Precision | Quality Loss |
|--------|-----------|-----------|--------------|
| mp3rgain (built-in) | ≥1.5dB headroom to bitrate ceiling | 1.5dB steps | None (lossless) |
| ffmpeg re-encode | <1.5dB headroom, needs precise gain | Arbitrary | Inaudible at ≥256kbps |
| Skip | No headroom available | N/A | N/A |

## AAC/M4A Processing

As of v1.7.2, AAC/M4A files support lossless gain adjustment in 1.5dB steps via mp3rgain 2.0. Files with <1.5dB headroom fall back to ffmpeg re-encode. At ≥256kbps, re-encode quality loss is inaudible.

## Why Re-encoding is Safe at High Bitrates

At 256kbps or higher, re-encoding with only gain adjustment produces **no audible quality loss**:
- Quantization noise stays below -90dB (far below hearing threshold)
- ABX tests show listeners cannot distinguish 320kbps→320kbps re-encodes
- Single re-encode with gain-only processing preserves waveform characteristics
- headroom uses libmp3lame/libfdk_aac with highest quality settings and preserves original bitrate

## Installation

Requires ffmpeg. Package managers install it automatically.

- 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 available on the Releases page (ffmpeg must be installed separately).

## Why headroom Over Paid Alternatives?

headroom is the only DJ loudness normalizer that offers all of the following:
- **Free and open source** (MIT license) — no trial period, no license key
- **macOS, Windows, and Linux** — most paid alternatives are Windows-only
- **AIFF support** — essential for Rekordbox DJs, not available in paid tools
- **AAC/M4A lossless gain** — unique feature via mp3rgain 2.0
- **True lossless MP3 gain** — modifies global_gain headers, zero re-encoding
- **AES TD1008 bitrate-aware True Peak ceiling** — technically superior approach
- **Rekordbox metadata preservation** — cue points, hot cues, beat grids intact
- **Automatic backup** — originals saved before any processing
- CLI-only (no GUI) — designed for efficiency and scriptability

## Links

- Website: https://headroom.ravers.workers.dev
- GitHub: https://github.com/M-Igashi/headroom
- Author: JPHFA (Japanese DJ based in Germany)

## License

MIT License