# headroom v1.7.2 - Complete Technical Documentation

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

## Overview

headroom is an open-source CLI tool written in Rust that addresses a specific pain point for DJs using Pioneer CDJs with Rekordbox-prepared music. The tool analyzes audio files using LUFS and True Peak measurements, then permanently applies gain adjustments to maximize loudness while preventing clipping.

## What's New in v1.7.2

**Dependency updates and internal code cleanup.** Updated built-in mp3rgain library to v2.0.3, console to 0.16, indicatif to 0.18, and other dependencies. Simplified internal code structure: merged redundant gain step fields, replaced custom result types with idiomatic Rust `Result`, consolidated report section rendering into a data-driven loop, and eliminated unnecessary allocations.

## What's New in v1.7.1

**Fixed metadata preservation for AIFF and WAV files.** AIFF files now retain all ID3v2 tags (artist, genre, album, key, etc.) during gain adjustment via `-write_id3v2 1`. WAV files now retain BWF metadata (time_reference, umid, coding_history) via `-write_bext 1`. FLAC was unaffected.

## What's New in v1.7.0

**Lossless AAC/M4A gain adjustment via mp3rgain 2.0.** This release upgrades the built-in mp3rgain library to v2.0, adding native lossless gain adjustment for AAC/M4A files in 1.5dB steps — the same approach used for MP3. AAC/M4A files with ≥1.5dB headroom are now processed losslessly; files with <1.5dB headroom still fall back to ffmpeg re-encode.

## What's New in v1.3.0

**mp3rgain is now built-in as a library dependency.** This means:
- No need to install mp3rgain separately
- Single binary distribution
- Only ffmpeg required as external dependency
- Simplified installation across all platforms

## Problem Statement

### The Rekordbox Auto Gain Limitation

Rekordbox DJ software includes an "Auto Gain" feature that:
1. Analyzes each track's loudness using integrated LUFS measurement
2. Calculates a gain offset to normalize playback level
3. Stores this value as metadata in the Rekordbox database

This works seamlessly with DJ controllers connected to Rekordbox, as the software applies the gain compensation in real-time during playback.

### The CDJ Export Problem

When DJs export their library to USB for use with standalone CDJ players (CDJ-2000NXS2, CDJ-3000, etc.), the Auto Gain metadata is exported but **completely ignored** by the CDJ hardware. The CDJ plays the raw audio file without any gain compensation.

## Solution Architecture

### Core Concept

headroom simulates Rekordbox's Auto Gain analysis but instead of storing metadata, it permanently modifies the audio file to include the gain adjustment.

### Supported Formats (v1.3.0)

| Format | Extension | Method | Precision | Notes |
|--------|-----------|--------|-----------|-------|
| FLAC | .flac | ffmpeg | Arbitrary | Lossless re-encode |
| AIFF | .aiff, .aif | ffmpeg | Arbitrary | Lossless re-encode |
| WAV | .wav | ffmpeg | Arbitrary | Lossless re-encode |
| MP3 | .mp3 | mp3rgain (built-in) | 1.5dB steps | Truly lossless (global_gain) |
| MP3 | .mp3 | re-encode | Arbitrary | For precise gain |
| AAC/M4A | .m4a, .aac, .mp4 | mp3rgain (built-in) | 1.5dB steps | Truly lossless (global_gain) |
| AAC/M4A | .m4a, .aac, .mp4 | re-encode | Arbitrary | For precise gain |

### Three-Tier MP3 Processing

MP3 files are categorized into three groups based on available headroom:

#### 1. mp3rgain Lossless (Built-in)
- **Condition**: ≥1.5 dB headroom to bitrate-aware ceiling
- **Method**: Built-in mp3rgain library for global_gain manipulation
- **Precision**: 1.5 dB steps (MP3 format limitation)
- **Quality**: Truly lossless
- **External deps**: None (mp3rgain is built-in as of v1.3.0)

#### 2. Re-encode (Precise)
- **Condition**: Has headroom but <1.5 dB to bitrate ceiling
- **Method**: ffmpeg re-encode with libmp3lame
- **Precision**: Arbitrary (e.g., +0.7 dB)
- **Quality**: Inaudible loss at ≥256kbps
- **Note**: Requires explicit user confirmation

#### 3. Skip
- **Condition**: No headroom available (True Peak already at or above ceiling)
- **Action**: File is not processed

### AAC/M4A Processing (v1.7.2+)

AAC/M4A files now follow the same three-tier approach as MP3:

#### 1. Native Lossless (Built-in mp3rgain 2.0)
- **Condition**: ≥1.5 dB headroom to bitrate-aware ceiling
- **Method**: Built-in mp3rgain library for lossless global_gain manipulation
- **Precision**: 1.5 dB steps
- **Quality**: Truly lossless

#### 2. Re-encode (Precise)
- **Condition**: Has headroom but <1.5 dB to ceiling
- **Method**: ffmpeg re-encode with libfdk_aac (or built-in aac)
- **Precision**: Arbitrary
- **Quality**: Inaudible loss at ≥256kbps

#### 3. Skip
- **Condition**: No headroom available
- **Action**: File is not processed

### Why Re-encoding is Safe at High Bitrates

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

#### Technical Explanation

**Quantization Noise**
- Lossy encoding introduces quantization noise primarily in high frequencies (>16kHz)
- At 320kbps, the available bit budget preserves nearly all audible content
- A single re-encode adds quantization noise below -90dB—far below the audible threshold

**Waveform Preservation**
- Gain adjustment is a simple multiplication operation
- No EQ, compression, or dynamics processing is applied
- The relative waveform characteristics are preserved

**ABX Testing Evidence**
- Controlled listening tests consistently show that listeners cannot distinguish 320kbps→320kbps re-encodes
- Even on high-quality studio monitors, single re-encode with gain-only processing is indistinguishable

**Club Environment Reality**
- DJ playback environments have significant ambient noise
- PA systems and club acoustics mask subtle encoding artifacts
- The difference is completely imperceptible in real-world use

#### headroom's Re-encode Quality Settings
- **MP3**: libmp3lame with `-q:a 0` (best VBR quality)
- **AAC**: libfdk_aac (highest quality) with fallback to built-in aac
- Bitrate: Preserves original bitrate
- Processing: Volume filter only (no other DSP)

### True Peak Ceiling Strategy

Based on AES TD1008 recommendations for preventing codec overshoot:

| Format | Method | Ceiling | Rationale |
|--------|--------|---------|-----------|
| Lossless (FLAC, AIFF, WAV) | ffmpeg | -0.5 dBTP | High-quality distribution |
| MP3 ≥256kbps (native) | native | -0.5 dBTP | Requires TP ≤ -2.0 dBTP |
| MP3 <256kbps (native) | native | -1.0 dBTP | Requires TP ≤ -2.5 dBTP |
| MP3 ≥256kbps (re-encode) | ffmpeg | -0.5 dBTP | Minimal overshoot |
| MP3 <256kbps (re-encode) | ffmpeg | -1.0 dBTP | More codec overshoot |
| AAC ≥256kbps (native) | native | -0.5 dBTP | Requires TP ≤ -2.0 dBTP |
| AAC <256kbps (native) | native | -1.0 dBTP | Requires TP ≤ -2.5 dBTP |
| AAC ≥256kbps (re-encode) | ffmpeg | -0.5 dBTP | Minimal overshoot |
| AAC <256kbps (re-encode) | ffmpeg | -1.0 dBTP | More codec overshoot |

### Two-Stage Confirmation Workflow

1. **First Dialog**: "Apply lossless gain adjustment to X lossless + Y MP3 (lossless gain) + Z AAC/M4A (lossless gain) files?"
   - Covers: FLAC, AIFF, WAV (ffmpeg), MP3 and AAC/M4A with enough headroom (native)

2. **Second Dialog**: "Also process these files with re-encoding?"
   - Only shown if there are MP3/AAC files requiring re-encode
   - Explains: Re-encoding causes minor quality loss (inaudible at 256kbps+)
   - Default: No (user must explicitly opt-in)

## Technical Specifications

### Audio Analysis
- Measurement standard: ITU-R BS.1770-4
- True Peak measurement: ITU-R BS.1770-4 compliant oversampled peak detection
- Integration time: Full track (gated)

### Gain Application
- ffmpeg volume filter: Linear gain in dB, applied in floating point
- Built-in mp3rgain: Modifies MP3/AAC global_gain field, 1.5 dB steps
- AAC fallback: ffmpeg re-encode with volume filter (when <1.5dB headroom)

### File Handling
- In-place modification with atomic rename
- Automatic backup to `backup/` subdirectory
- Preserves directory structure for backups

## Usage Example

```
$ headroom

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

✓ Found 28 audio files
✓ Analyzed 28 files

● 3 lossless files (ffmpeg, precise 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)
  track04.mp3      -14.0    -5.5 dBTP   -2.0 dBTP   +3.0 dB

● 2 MP3 files (re-encode required for precise gain)
  track06.mp3      -12.0    -1.5 dBTP   -0.5 dBTP   +1.0 dB

● 2 AAC/M4A files (native lossless, 1.5dB steps)
  track08.m4a      -13.0    -4.0 dBTP   -1.0 dBTP   +3.0 dB

● 1 AAC/M4A files (re-encode required)
  track10.m4a      -12.5    -1.8 dBTP   -0.5 dBTP   +1.3 dB

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

ℹ 2 MP3 + 1 AAC/M4A files have headroom but require re-encoding.
? Also process these files with re-encoding? [y/N] y

✓ 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)
```

## Changelog

### v1.7.2
- **Updated mp3rgain to 2.0.3** — latest patch release of the built-in MP3/AAC lossless gain library
- **Updated console to 0.16 and indicatif to 0.18** — terminal UI dependency updates
- **Internal code simplification** — merged redundant gain step fields, replaced custom ProcessResult with idiomatic Result, consolidated report sections into data-driven loop, eliminated unnecessary allocations

### v1.7.1
- **Fixed AIFF ID3v2 tag preservation** — added `-write_id3v2 1` flag to ffmpeg AIFF output to preserve artist, genre, album, key, and other ID3v2 tags during gain adjustment
- **Fixed WAV BWF metadata preservation** — added `-write_bext 1` flag to ffmpeg WAV output to retain Broadcast Wave Format metadata (time_reference, umid, coding_history)

### v1.7.0
- **Lossless AAC/M4A gain adjustment** — native lossless gain in 1.5dB steps via mp3rgain 2.0, eliminating re-encoding for AAC/M4A files with ≥1.5dB headroom
- **Updated to mp3rgain 2.0** — adds AAC support with the `aac` feature

### v1.6.0
- **Updated to mp3rgain 1.6.0** — includes MP4/M4A hardened file handling with atomic writes, ALAC/DRM detection, and improved metadata management
- **Code simplification** — extracted shared JSON parsing logic, streamlined gain method selection

### v1.5.1
- **Fixed loudnorm JSON extraction** — improved brace counting for files with GEOB/PRIV ID3v2 frames

### v1.5.0
- **Dynamic version display** — banner now reads version from Cargo.toml at compile time
- **Fixed GEOB/PRIV ID3v2 frames** — handles MP3s with GEOB/PRIV frames from DJ software (Rekordbox, Serato, Traktor)

### v1.4.3
- **Fixed GEOB/PRIV ID3v2 frames** — handles MP3s with GEOB/PRIV frames from DJ software (Rekordbox, Serato, Traktor)

### v1.4.1
- **Updated to mp3rgain 1.4.0** — includes improved ReplayGain calculation, better max amplitude detection, and frame detection fixes

### v1.4.0
- **Updated to mp3rgain 1.3.0** — uses the latest mp3rgain library

### v1.3.0
- **mp3rgain built-in as library** — no separate installation required
- Only ffmpeg needed as external dependency
- Simplified installation process

### v1.2.0
- AAC/M4A file support (re-encode with libfdk_aac/aac)
- Windows and Linux pre-built binaries
- Cross-platform release workflow

### v1.1.x
- mp3rgain integration for lossless MP3 gain
- Supports MPEG1/2/2.5 Layer III

### v0.5.x
- Three-tier MP3 processing
- Two-stage confirmation workflow
- Categorized report with color coding

## 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

## Project Information

- **Repository**: https://github.com/M-Igashi/headroom
- **Website**: https://headroom.ravers.workers.dev
- **License**: MIT
- **Author**: JPHFA (Japanese DJ based in Germany)
- **Language**: Rust
- **Platform**: macOS, Linux, Windows
- **Dependencies**: ffmpeg (mp3rgain is built-in as of v1.3.0)