mp3rgain

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

🌐 Website: mp3rgain.tyna.ninja

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.

Features

• CLI lossless AAC bitstream gain: re-encode-free global_gain rewrite for AAC/M4A — replacing the long-abandoned aacgain, with -u undo (foobar2000's GUI equivalent has no undo path)
• Lossless & Reversible: No re-encoding, all changes can be undone (MP3 and AAC)
• ReplayGain: Track and album gain analysis for MP3 and AAC/M4A, with standard REPLAYGAIN_* tags written alongside the bitstream change (APEv2, ID3v2 TXXX, or MP4 freeform)
• Zero dependencies: Single static binary (no ffmpeg, no mp3gain, no aacgain)
• Cross-platform: macOS, Linux, Windows (x86_64 and ARM64)
• mp3gain / aacgain compatible: Drop-in replacement with identical CLI
• GUI Application: Native desktop app for drag-and-drop workflow

Installation

CLI (mp3rgain)

GUI (mp3rgui)

Binaries for all platforms are also available from GitHub Releases.

[!NOTE] Windows: Defender occasionally flags mp3rgui.exe as a false positive. The GUI is an unsigned, statically linked Rust binary, which sometimes trips Microsoft Defender's cloud/ML heuristics. Any such detection is a false positive: every release is built from public source by a public GitHub Actions workflow, and each release ships .sha256 files so you can verify what you downloaded. Detections are reported to Microsoft when they appear — the v3.0.0 binaries were analysed and confirmed "Not malware". If you hit a detection on a newer release, please open an issue so it can be reported.

Quick Start

# Normalize a single track (ReplayGain)
mp3rgain -r song.mp3

# Normalize an album
mp3rgain -a *.mp3

# Manual gain adjustment (+3.0 dB)
mp3rgain -g 2 song.mp3

# Undo changes
mp3rgain -u song.mp3

# Show file info
mp3rgain song.mp3

Migrating from mp3gain?

Already running mp3gain (or aacgain) in a script, Dockerfile, or CI pipeline? mp3rgain is a drop-in replacement — the CLI flags, the TSV output format, and the APEv2 mp3gain_undo tag are all mp3gain-compatible, so existing parsers (e.g. beets) keep working unchanged. For most setups, migration is a one-line substitution:

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

See docs/migrating-from-mp3gain.md for the full flag equivalence table, Dockerfile/CI substitution patterns, tag interop notes, and the small set of intentional behaviour differences. Bit-level verification lives in docs/compatibility-report.md.

GUI Application

A native GUI application (mp3rgui) is available for users who prefer a graphical interface.

Features:

• Drag-and-drop file / folder loading (recurses subfolders)
• Track and Album ReplayGain analysis (parallel, with Cancel)
• Apply Track / Album Gain — shares the same apply_with_options pipeline as the CLI
• Options panel: Prevent clipping (-k), Preserve mtime (-p), Wrap mode (-w), MP3 tag layout (-s a / -s i), Dry run (-n)
• Modify Gain menu: Apply Track / Album / Manual (-g) / Channel (-l) Gain, Undo (-u), Delete Stored Tags (-s d)
• Analysis menu: Track / Album Analysis, Find Max Amplitude (-x), Check Stored Tags (-s c)
• Stored RG table column shows existing ReplayGain / undo tags (APE / ID3v2 / MP4 freeform) with a per-tag breakdown on hover
• Responsive UI: all batch work runs on a worker thread with per-file progress and a Cancel button

Install: See Installation above for Homebrew, Winget, and AUR options. Binaries are also available from GitHub Releases:

• mp3rgui-*-macos-universal.dmg (macOS)
• mp3rgui-*-linux-x86_64.tar.gz / mp3rgui-*-linux-arm64.tar.gz (Linux)
• mp3rgui-*-windows-x86_64.zip / mp3rgui-*-windows-arm64.zip (Windows)
• mp3rgui_*_amd64.deb / mp3rgui_*_arm64.deb (Debian/Ubuntu)

macOS manual download: If you see "mp3rgui cannot be opened" warning, run:

xattr -cr /path/to/mp3rgui.app

This is not needed when installing via Homebrew.

Command-Line Options

Run mp3rgain -h for the full list of options.

ReplayGain analysis runs in parallel by default (std::thread::available_parallelism() worker threads). Use -j 1 or MP3RGAIN_THREADS=1 for the legacy serial path. See docs/perf-parallel.md for the design and real-corpus benchmark numbers.

Documentation

• Migration Guide - Drop-in replacement for mp3gain: flag equivalence, sed/Dockerfile/CI substitution patterns, beets config
• Parallel Performance - -j / --threads design and real-corpus benchmark numbers
• Roadmap - Development plans and upcoming features
• Security - Memory safety and CVE analysis
• Compatibility Report - Verification against original mp3gain
• Technical Comparison - Comparison with similar tools
• Use Cases - Integration examples (beets, headroom, etc.)
• Download Stats - Weekly download trends across all platforms

Why mp3rgain?

The original mp3gain has been unmaintained upstream since ~2015 (though distribution maintainers continue to apply security patches). aacgain, its AAC counterpart, has been unmaintained since ~2009 and is effectively unbuildable on modern 64-bit systems. mp3rgain is a modern, memory-safe replacement written in Rust that covers both.

These are all ReplayGain tools, mp3rgain included — it runs a ReplayGain analysis and writes the standard REPLAYGAIN_* tags like any tagger. What separates them is where the correction ends up. rsgain / loudgain / FFmpeg -af replaygain stop at the tags, which non-compliant players ignore; ffmpeg loudnorm re-encodes. The mp3gain lineage — mp3gain, aacgain, and now mp3rgain — writes the tags and bakes the gain into the bitstream, losslessly and reversibly.

AAC/M4A on the CLI is the differentiator. That combination is what has no other maintained CLI implementation: foobar2000 offers an equivalent "Apply ReplayGain to file content" pass for AAC in MP4/MKA, but it is Windows GUI only, has no undo, and is not built for batch, headless, or container workflows. mp3rgain fills the cross-platform, scriptable, reversible niche.

[!TIP] Want the most standards-faithful ReplayGain, on Windows, in a GUI? Use foobar2000. It is the closest thing ReplayGain 2.0 has to a reference implementation — a full BS.1770 scanner whose numbers other tools get checked against — it tags far more formats than mp3rgain does, and it can bake gain into MP3 and AAC bitstreams too. mp3rgain is the better fit when you need a command line, a non-Windows host, mp3gain-identical ReplayGain 1.0 values, or an undo path — and the two coexist fine, since mp3rgain writes the same standard REPLAYGAIN_* tags foobar2000 reads — in ID3v2, where it looks for them — with --rg2 deliberately matching its measurement.

mp3rgain implements the ReplayGain 1.0 algorithm (89 dB reference level) by default for full compatibility with the original mp3gain / aacgain — an existing library re-scans to identical values. Modern BS.1770 loudness measurement is available as an opt-in: --rg2 (ReplayGain 2.0, −18 LUFS reference) and --r128 (EBU R128, −23 LUFS target) produce values consistent with foobar2000, loudgain, and ffmpeg loudnorm.

Files scanned with --rg2 / --r128 also carry a REPLAYGAIN_ALGORITHM tag set to ITU-R BS.1770, so a player (or you, years later) can tell which measurement produced the stored values. The default RG1 mode writes no such tag — an absent one means the classic mp3gain measurement, which is what every pre-existing tagged file already implies.

Where the tags go (MP3)

MP3 has two competing metadata containers, and the two tag families mp3rgain writes have different audiences. By default each goes where its readers are:

Two flags override the split when you want everything in one place:

mp3rgain -r *.mp3          # default: ReplayGain in ID3v2, undo in APEv2
mp3rgain -r -s a *.mp3     # everything in APEv2 — byte-for-byte mp3gain
mp3rgain -r -s i *.mp3     # everything in ID3v2

MP3GAIN_ALBUM_MINMAX is APEv2-only in every mode. AAC/M4A is unaffected — it always uses MP4 freeform atoms.

-s c reads both containers and merges them, and -u finds the undo tag in either, so files tagged by mp3gain or by an earlier -s i run still inspect and roll back correctly.

Changed in 3.2.0. Earlier versions put everything in APEv2. If you depend on the old layout, -s a restores it exactly. Re-running the default over an APEv2-tagged file moves the ReplayGain values to ID3v2 and clears the APEv2 copies so the two cannot disagree.

Use mp3rgain in Docker / CI

Official multi-arch images (linux/amd64, linux/arm64) are published to GHCR:

ghcr.io/m-igashi/mp3rgain:latest
ghcr.io/m-igashi/mp3rgain:v3          # latest 3.x
ghcr.io/m-igashi/mp3rgain:v3.1.0      # exact version

The image is built FROM scratch with a fully static (musl) binary — no shell, no runtime deps, ~2 MB. Drop-in replacement for mp3gain in containerized batch / cron pipelines (e.g. Plex maintenance windows):

# Normalize a music library by mounting it into the container
docker run --rm \
  -v /path/to/music:/music \
  ghcr.io/m-igashi/mp3rgain:latest -r -R /music

# Run as your own user so written files keep correct ownership
docker run --rm \
  --user "$(id -u):$(id -g)" \
  -v /path/to/music:/music \
  ghcr.io/m-igashi/mp3rgain:latest -r -R /music

Because the entrypoint is the binary itself, all mp3rgain flags work exactly the same as the host CLI (-r, -a, -R, -k, -u, …).

Library Usage

use mp3rgain::{apply_gain, analyze};
use std::path::Path;

let frames = apply_gain(Path::new("song.mp3"), 2)?;  // +3.0 dB
let info = analyze(Path::new("song.mp3"))?;

Contributing

Contributions welcome! See CONTRIBUTING.md.

License

MIT License - see LICENSE.

See Also

• Original mp3gain
• headroom - DJ audio loudness optimizer