DEV Community: Jesse Pinkman

rekordbox sorts by key or by BPM, never both, and the sort never reaches the CDJ

Jesse Pinkman — Fri, 18 Sep 2026 17:51:27 +0000

A warm-up set usually wants two things at once: keys that sit next to each other on the Camelot wheel, and BPM rising inside each key. rekordbox cannot express that, and neither can the players.

Press Sort by Key on a CDJ and the tracks group by key, but inside 1A the BPMs come out in whatever order you dragged them into the playlist. Press Sort by BPM and the BPM lines up while the keys scatter. There is no compound sort in the UI, on the desktop or on the deck.

That is the visible half of the problem. The half that costs you a set is this: sorting on a player is a view. It never changes the order stored in the playlist, and the order stored in the playlist is what a CDJ reads off the USB stick. Toggle Sort by Key on the laptop, export, and the deck plays the original order back at you.

Six tracks, three sorts

Registration order, which is also the stored order:

#	Track	Key	BPM
1	A	1A	130
2	B	2A	124
3	C	1A	124
4	D	2B	130
5	E	2A	128
6	F	2B	124

The same six tracks under each sort:

#	Sort by Key	Sort by BPM	Compound (key → BPM)
1	A · 1A · 130	C · 1A · 124	C · 1A · 124
2	C · 1A · 124	B · 2A · 124	A · 1A · 130
3	B · 2A · 124	F · 2B · 124	B · 2A · 124
4	E · 2A · 128	E · 2A · 128	E · 2A · 128
5	D · 2B · 130	A · 1A · 130	F · 2B · 124
6	F · 2B · 124	D · 2B · 130	D · 2B · 130

Sort by key and the BPM inside 1A and 2B runs 130 → 124, the opposite direction of a warm-up. Sort by BPM and the key walks 1A → 2A → 2B → 2A → 1A → 2B, a tour of the wheel that ignores harmonic adjacency. Only the third column keeps the keys ascending and the BPM rising inside each one.

Where you can write the order

rekordbox exports its library as an XML file, and it will read that file back in as a second tree in the sidebar, the rekordbox xml tree, alongside your real library. The playlists in that file are lists of <TRACK Key="…"/> references, and their order is the stored order.

So the fix is to rewrite the references:

baken rbsort ~/Music/rekordbox/collection.xml

Camelot key ascending as the primary key, BPM ascending as the tiebreaker inside each key group. Tracks with no Camelot key sort after all known keys. Nothing else in the file changes: names, folder structure, Count and Entries attributes and whitespace are all preserved byte for byte, which means running it twice is a no-op and it can safely run on every export.

Your actual library is never touched. The sorted playlists show up in the separate rekordbox xml tree, you drag the one you want into your real playlists, switch to EXPORT mode and write the USB. The deck plays it in that order in its default browse screen, with nothing to do on the night.

Two things worth knowing before you run it. Keys have to be in Camelot notation, which is Preferences → View → Key display format → Alphanumeric; if they are not, the tool stops rather than guessing. And the rekordbox xml tree is a different sidebar tree from Playlists, which is the single most common reason people think nothing happened.

Why not just ask for the feature

Even if rekordbox shipped a compound sort tomorrow, it would be a view, and the CDJ would still read the stored order. The same is true of Auto Gain: rekordbox works out a per-track gain, applies it in performance mode, and never writes it into the file, so a player reading USB has no idea it exists. Anything that lives only in the laptop app does not follow the music onto the deck. The general move is to bake it into the thing that travels.

The tool is baken, MIT, Rust, macOS, Windows and Linux: https://github.com/M-Igashi/baken. rbsort needs nothing but the XML, not even ffmpeg. There is a native Mac app too, which shows the resulting order before it writes anything, but the command line does the same sort and stays free.

Full version of this write-up, which is the canonical one: https://baken.ravers.workers.dev/sort

rekordbox, CDJ and Pioneer DJ are trademarks of AlphaTheta Corporation. This project is not affiliated with or endorsed by AlphaTheta Corporation.

I rewrote mp3gain in Rust — 'compatible' turned out to be three different things

Jesse Pinkman — Sat, 02 May 2026 21:29:13 +0000

If you maintain a podcast, music server, or any audio pipeline that needs consistent volume across files, there's a non-trivial chance you have one of these somewhere:

RUN apt-get install -y mp3gain

Or in a beets config:

replaygain:
  backend: command
  command: mp3gain

Or buried in a cron job from 2014.

mp3gain was written in C by Glen Sawyer in 2003. Upstream development stopped around 2009. Distributors (Debian, Ubuntu, Homebrew) keep it alive with security patches, but no new features have shipped in 15+ years. Its AAC counterpart aacgain died around the same time and doesn't even build cleanly on modern 64-bit systems.

People keep using both because the popular alternatives — loudgain, rsgain, ffmpeg loudnorm — solve a related problem (writing ReplayGain tags) but not the same problem. A tag-only tool doesn't help when your players ignore tags entirely: DJ hardware, smart speakers, most car audio, podcast publishing pipelines that bake volume into the file. For those, you need the bitstream itself rewritten — losslessly, reversibly, fast.

Rather than CVE-patch a 22-year-old C codebase one more time, I spent the last year writing mp3rgain, a Rust implementation that reads and writes the same files mp3gain does. Halfway through, I realized the word "compatible" was hiding three completely different things.

Layer 1 — byte-identical output

The strictest compatibility claim is that the output file is bit-for-bit identical:

cp original.mp3 a.mp3 && cp original.mp3 b.mp3
mp3gain  -g 2 a.mp3
mp3rgain -g 2 b.mp3
sha256sum a.mp3 b.mp3
# → same hash

To get there, the Rust implementation has to match every detail of the C version's bitstream rewrite: synchronization word detection, MPEG version dispatch, side-information size calculation (which differs by MPEG version × channel mode), and bit-level reads/writes that span byte boundaries.

I wanted to "clean up" something the C code did awkwardly more than once. Every time I had to remind myself: the moment I lose byte-identical output, I lose the right to call this a drop-in replacement. There's a CI script (scripts/compatibility-test.sh) that diffs SHA-256 hashes between both tools across MPEG1/2/2.5, mono/stereo/joint stereo, CBR/VBR, and a range of gain values. If even one case mismatches, the PR doesn't merge.

Layer 2 — tag interoperability

mp3gain stores undo information in APEv2 tags:

mp3gain_undo: -3,-2,N
mp3gain_minmax: 100,148

If I run mp3gain -g 2, then later mp3rgain -u, the undo has to work — and vice versa. This is a different layer from byte-identical output: it's about the metadata block, not the audio frame data.

mp3rgain reads and writes the same APEv2 fields with the same string format. There's one intentional break: after -u, mp3gain leaves an empty APEv2 tag block in place (probably because rewriting it would shift downstream frame offsets). mp3rgain removes the tag completely. The audio data is identical either way and the bidirectional undo property still holds, so I judged this as still "compatible enough."

Layer 3 — text protocol

mp3gain -o (no argument) prints a tab-separated table:

File    MP3 gain    dB gain Max Amplitude   Max global_gain Min global_gain
song.mp3    0   0.0 17234   148 100

beets parses this with regex. So do an unknown number of personal scripts that have run unmodified for a decade. Change the column order, the header text, or the separator, and you break all of them silently.

mp3rgain emits the exact same header — one println! line at main.rs:1275:

println!("File\tMP3 gain\tdB gain\tMax Amplitude\tMax global_gain\tMin global_gain");

New structured output lives behind -o json, opt-in, never the default.

What I deliberately didn't keep

Compatibility isn't free, and not every quirk is worth preserving:

AAC support: mp3gain has none. mp3rgain rewrites AAC global_gain in place (the same idea aacgain used) and stores undo info in MP4 freeform metadata atoms because APEv2 doesn't fit MP4 containers.
-o json and --dry-run: new flags for automated pipelines. Preview safely, then apply — something the original CLI didn't really support.
ID3v2 RVA2 / TXXX ReplayGain tags (-s i): opt-in. foobar2000, mpd, and other ReplayGain-aware players read these; APEv2 tags are invisible to them.

Migrating: what it actually looks like

For most pipelines, migration is one substitution.

Shell scripts:

sed -i 's/\bmp3gain\b/mp3rgain/g' your_pipeline.sh

Dockerfile — replace the apt-installed binary with a 2 MB static image:

- RUN apt-get install -y mp3gain && rm -rf /var/lib/apt/lists/*
- ENTRYPOINT ["mp3gain"]
- FROM ghcr.io/m-igashi/mp3rgain:latest

That's it. The image is FROM scratch with a musl-static binary: no shell, no glibc, no apt cache to clean.

beets — change one line in ~/.config/beets/config.yaml:

replaygain:
  backend: command
- command: mp3gain
- command: mp3rgain

The full migration guide is at docs/migrating-from-mp3gain.md, with sed patterns, CI snippets, and the apt/dnf/pacman/brew/winget/cargo install matrix.

Why bother

Three reasons that mattered to me:

Memory safety. mp3gain's history includes a stream of CVEs — heap overflows in the side-info parser, mostly. Patching those in 2025 means tracking down a long-quiet maintainer's intent. A Rust rewrite removes the whole class from the picture.
AAC. Most personal libraries on Apple platforms are AAC, and there's been no working tool to volume-normalize them losslessly since aacgain stopped building. DJ hardware, car audio, and smart speakers all ignore ReplayGain tags, so tag-only tools don't help.
Distribution. Static binary in a 2 MB image, plus packages on Homebrew / Winget / AUR / PPA / Docker / Cargo. No "build from source on this niche distro" required.

M-Igashi / mp3rgain

Lossless MP3 volume adjustment - a modern mp3gain replacement written in Rust

mp3rgain

Lossless MP3/AAC volume adjustment - a modern mp3gain / aacgain replacement written in Rust

mp3rgain adjusts MP3 and AAC volume without re-encoding by modifying the global_gain field in each frame. This preserves audio quality while achieving permanent volume changes.

The only actively maintained tool that performs lossless AAC/M4A bitstream gain adjustment. aacgain has been unmaintained since ~2009 and rarely builds on modern 64-bit systems. mp3rgain is the only practical option today for re-encode-free AAC volume normalization.

Features

Only tool with lossless AAC bitstream gain: re-encode-free global_gain rewrite for AAC/M4A — a capability previously only available in the long-abandoned aacgain
Lossless & Reversible: No re-encoding, all changes can be undone (MP3 and AAC)
ReplayGain: Track and album gain analysis for MP3 and AAC/M4A
Zero dependencies: Single static binary (no ffmpeg, no mp3gain, no aacgain)
Cross-platform: macOS, Linux, Windows (x86_64 and ARM64)
mp3gain / aacgain compatible…

View on GitHub

What I'd love to hear

If you have mp3gain or aacgain in a pipeline somewhere, I'd be curious which of the three compatibility layers actually matters to you in practice — and whether anyone is relying on -s i ID3v2 ReplayGain tags I should know about. Issues and migration reports welcome.

Disclosure: prose drafted and generated descriptive cover.png with AI editorial assistance. Code, design decisions, and the SHA-256 verification setup are my own.