# Bake'n Deck (baken) v3.0.1

> NOTE: headroom is now **Bake'n Deck 3.0** — the `baken` binary replaces `headroom`. The old install channels under the headroom name (brew, winget, cargo, AUR) no longer receive updates; reinstall via the baken packages (`brew install M-Igashi/tap/baken`, `winget install M-Igashi.baken`, `cargo install baken`, `yay -S baken-bin`). See https://github.com/M-Igashi/baken/issues/60.

> Built for the Rekordbox → CDJ workflow. Rekordbox's Auto Gain doesn't survive USB export, Rekordbox has never offered compound Key+BPM playlist sort (Serato had it for years — but never exported to CDJs), and pre-NXS2 CDJs won't reliably play anything but MP3. Bake'n Deck bakes all three into the files themselves, so what you prep is what plays on the deck.

> AI usage policy: This documentation is MIT-licensed and free to use for indexing,
> citation, summarization, retrieval-augmented generation, and model training.
> Attribution welcome but not required. See /llms-full.txt for the full technical reference.

Bake'n Deck (`baken`) is a Rekordbox → CDJ prep toolkit — a CLI that fills three structural gaps in the workflow, all with the same idea: bake the work into something the CDJ will actually read. The loudness analyzer runs as `baken headroom`, the playlist sorter as `baken rbsort`, and the CDJ-safe MP3 transcoder as `baken cdjsafe` (new in v3.0.0).

1. **Auto Gain on CDJs**: Rekordbox's Auto Gain analyzes tracks and stores a metadata gain offset, but the value is ignored on standalone CDJs when exporting via USB. Bake'n Deck permanently bakes the gain into the audio file, ensuring consistent loudness on any CDJ.
2. **Sort by Key AND BPM, on CDJ**: Rekordbox's UI doesn't support multi-column sorting, and CDJs play tracks in playlist order anyway. The `rbsort` subcommand (v2.0.0+) bakes Camelot Key (1A→12B) then BPM ascending order into the playlist itself, emitting a `Sorted (Key+BPM)/` folder (mirroring the analyzer's `backup/` pattern) with each sorted copy named after its source. Run on one playlist or every playlist in one pass. After import-back and EXPORT-mode right-click → Export Playlist to USB, your CDJ plays the set in that order with no on-deck reordering.
3. **Format compatibility on older CDJs**: Rekordbox exports FLAC/ALAC/AIFF/WAV/AAC to USB without complaint, but pre-NXS2 players (CDJ-2000NXS, CDJ-2000, CDJ-900NXS, CDJ-850, …) only play MP3 reliably — FLAC needs NXS2 (2016+) hardware, and the other formats fail on specific firmwares, sometimes mid-set. The `cdjsafe` subcommand (v3.0.0) converts every track in a playlist to 320 kbps CBR MP3 @ 44.1 kHz and emits an updated XML where each converted track inherits the source's beatgrid and hot/memory cues verbatim, grouped under a `CDJ-safe (MP3)/` folder — an emergency-backup USB that plays on any deck in the booth, cues intact.

## The Problem — Three gaps in the Rekordbox → CDJ workflow

### Gap 1 — Auto Gain doesn't survive USB export

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

### Gap 2 — Compound Key+BPM sort never existed in Rekordbox

Harmonic mixing wants a playlist sorted by Camelot Key, then by BPM within each key group. Rekordbox's UI has never offered compound sort — its *Sort by Key* view is single-column, so BPMs scatter inside each key group. Serato DJ has supported compound (Shift-click multi-column) sort for years, but Serato has no USB export path to standalone CDJs. The pattern itself isn't new in DJ software — it has just never reached the Rekordbox → CDJ booth side of the ecosystem. And even if Rekordbox added the sort tomorrow, CDJs play tracks in playlist order, not by software sort, so any in-software ordering is invisible on the deck.

### Gap 3 — Format support doesn't survive the trip to older CDJs

Rekordbox happily exports any format it manages to USB, but the booth decides what actually plays. Pre-NXS2 players (CDJ-2000NXS, CDJ-2000, CDJ-900NXS, CDJ-850, …) only play MP3 reliably: FLAC requires NXS2 hardware (2016+), and ALAC/AIFF/WAV/AAC fail on specific firmwares — sometimes mid-set, after loading fine at first. A lossless-first library is the right prep choice, but it silently assumes modern decks. When the venue turns out to run older CDJs, you need an MP3-only fallback USB — with your cues and beatgrids intact, not re-analyzed from scratch.

## The Solution

Bake'n Deck takes the prep work Rekordbox does in software and writes it into something the CDJ will actually read — the audio file (for gain), the playlist itself (for Key+BPM order), or a CDJ-safe MP3 copy of the whole playlist (for format compatibility):
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 (v3.0.1)

- **Rekordbox playlist sorter (`rbsort`)**: Sort a playlist by Camelot Key (1A→12B) then BPM ascending, output as a new playlist in `collection.xml`. Fills the missing multi-column sort in the Rekordbox UI.
- **CDJ-safe MP3 transcoder (`cdjsafe`, v3.0.0)**: Convert every track in a playlist to 320 kbps CBR MP3 @ 44.1 kHz for pre-NXS2 CDJs, with beatgrids and hot/memory cues carried over verbatim in the emitted XML — no re-analysis needed. Already-compliant MP3s are copied byte-identically.
- **Single binary**: Built-in mp3rgain 2.10 library — only ffmpeg required (rbsort does not need ffmpeg)
- **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, ffmpeg re-encode fallback for precise gain
- **Interactive and scriptable modes**: Guided two-stage confirmation for DJ workflows, or non-interactive flags (paths, globs, --lossless/--reencode/--backup/--report/--analyze-only) for pipelines and CI
- **Uniform True Peak ceiling**: -0.5 dBTP for every file by default — the most aggressive value AES TD1008 §7B sanctions for any limiter in the chain — fully overridable via `--tp-target` (e.g. `-1.0` for Spotify/Apple/YouTube delivery max) or `--tp-split-bitrate` for the legacy split
- **Rekordbox Compatible**: In-place modification preserves all metadata
- **Non-Destructive**: Automatic backups before processing
- **Cross-platform**: macOS, Linux, and Windows binaries available

## Rekordbox Playlist Sorter (rbsort, v2.0.0+)

Rekordbox does not expose a "sort by Key AND BPM" option in its UI. The `rbsort` subcommand fills that gap:

```bash
# Sort every TrackID-referenced playlist in the XML at once
baken rbsort --xml ~/Music/rekordbox/collection.xml

# Or target a single playlist (top-level: just the name)
baken rbsort \
  --xml ~/Music/rekordbox/collection.xml \
  --playlist "MyPlaylist"

# Nested under a folder ('/'-separated)
baken rbsort \
  --xml ~/Music/rekordbox/collection.xml \
  --playlist "Folder/MyPlaylist"

# Output defaults to <input-stem>-out.<ext> next to the input
# (collection.xml -> collection-out.xml). Pass --output PATH to override.
```

Workflow:
1. Set Rekordbox key display to Alphanumeric / 1A..12B (Preferences > View > Key display format > Alphanumeric).
2. File > Export Collection in xml format.
3. Run `baken rbsort ...` — a `Sorted (Key+BPM)/` folder is appended to the output XML, containing each sorted playlist under its original name (mirrors the `backup/` directory pattern from the analyzer).
4. Preferences > Advanced > Database > rekordbox xml > Imported Library — point to the output file, then restart Rekordbox.
5. Open the `rekordbox xml` tree in the left sidebar (a separate tree from your main library — switch via the sidebar icon column). The sorted results are at `rekordbox xml > Playlists > Sorted (Key+BPM)/`.
6. Click any playlist inside that folder to verify: tracks run 1A (low BPM) → 1B → ... → 12B (high BPM).
7. Drag the playlists you want out of `Sorted (Key+BPM)/` into your main `Playlists` to use in sets. Your originals stay untouched.

Sort rules:
- Primary: Camelot Key ascending (1A → 1B → 2A → ... → 12A → 12B)
- Secondary: BPM ascending within each key group
- Tracks with no Camelot key sort after all known keys; tracks with BPM 0 sort last within a key group

## CDJ-Safe MP3 Prep (cdjsafe, v3.0.0)

Pre-NXS2 CDJs (CDJ-2000NXS, CDJ-2000, CDJ-900NXS, CDJ-850, …) only play MP3 reliably. The `cdjsafe` subcommand builds an emergency-backup USB from any playlist:

```bash
baken cdjsafe \
  --xml ~/Music/rekordbox/collection.xml \
  --playlist "Sets/Friday" \
  --out-dir ~/Music/cdjsafe \
  [-o <out.xml>]
```

What it does:
- Converts EVERY track in the playlist to 320 kbps CBR MP3 @ 44.1 kHz with ID3v2.3 tags; embedded artwork is kept (JPEG, ≤500×500)
- Sources that are already exactly 320 kbps CBR @ 44.1 kHz MP3 are copied byte-identically — no generation loss, LAME header untouched
- Emits an updated XML where each converted track is a NEW entry (fresh TrackID) that inherits the source's beatgrid (TEMPO) and hot/memory cues (POSITION_MARK) verbatim, grouped under a `CDJ-safe (MP3)/<playlist>` folder; track comments get a `[cdjsafe]` marker
- Lossy→lossy re-encodes (e.g. a 192 kbps MP3 source) are accepted but listed in the run report, so you can refresh those from lossless masters later
- All-or-nothing: if any track fails to convert, no XML is written — a partial backup USB defeats the point

Workflow:
1. Run `baken cdjsafe ...` against your exported `collection.xml`.
2. Load the output XML via Preferences > Advanced > Database > rekordbox xml.
3. Right-click the imported tracks → Import to Collection — cues and beatgrids are carried over, no re-analysis.
4. Export the `CDJ-safe (MP3)` playlist to USB as usual.

Design notes:
- The output profile is locked (no flags to change it) — 320 CBR @ 44.1 kHz is the one profile every CDJ back to the CDJ-850 plays
- CBR sidesteps Rekordbox's known VBR cue-offset problem; ffmpeg writes a valid Xing/LAME header so cues stay sample-aligned
- Requires ffmpeg with libmp3lame (soxr resampling is used when 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.5 dB headroom to configured ceiling | 1.5 dB 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.0, AAC/M4A files support lossless gain adjustment in 1.5dB steps via mp3rgain. 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
- Bake'n Deck 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/baken
- Windows (winget): winget install M-Igashi.baken
- Arch Linux (AUR): yay -S baken-bin
- Cargo: cargo install baken (ffmpeg must be installed separately)

Pre-built binaries available on the Releases page (ffmpeg must be installed separately).

## Why Bake'n Deck Over Paid Alternatives?

Bake'n Deck 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.6+)
- **True lossless MP3 gain** — modifies global_gain headers, zero re-encoding
- **AES TD1008-aligned True Peak ceiling** — uniform -0.5 dBTP delivery target (the most aggressive value TD1008 sanctions), tunable per file or restored to the legacy bitrate-split via flag
- **Rekordbox metadata preservation** — cue points, hot cues, beat grids intact
- **Automatic backup** — originals saved before any processing
- **CDJ-safe MP3 prep (v3.0.0)** — one command converts a whole playlist to 320 kbps CBR MP3 for pre-NXS2 CDJs, cues and beatgrids carried over
- CLI-only (no GUI) — designed for efficiency and scriptability

## Links

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

## License

MIT License