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.

DEV Community: Jesse Pinkman