mp3rgain

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

🌐 Website: mp3rgain.tyna.ninja - install guide, full CLI reference, FAQ, and tool comparison

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.

• Lossless & reversible: no re-encoding; every change can be undone with -u (MP3 and AAC/M4A)
• ReplayGain: track and album analysis, with standard REPLAYGAIN_* tags written alongside the bitstream change
• mp3gain / aacgain compatible: drop-in replacement with identical CLI flags, TSV output, and undo tags
• Zero dependencies: single static binary; macOS, Linux, Windows (x86_64 and ARM64)
• GUI application: mp3rgui, a native desktop app for drag-and-drop workflows

Installation

Windows: download the installer

No terminal needed - Start Menu entry, uninstaller, Intel + ARM in one, no admin rights: Download mp3rgui for Windows (permanent link: https://mp3rgain.tyna.ninja/download/windows)

CLI (mp3rgain)

GUI (mp3rgui)

Binaries for all platforms are on GitHub Releases. For checksum verification and troubleshooting (Windows Defender false positives, missing OpenGL, PPA on older Ubuntu), see the install guide.

macOS manual download: if you see a "mp3rgui cannot be opened" warning, run xattr -cr /path/to/mp3rgui.app (not needed with Homebrew).

Quick Start

mp3rgain -r song.mp3          # Normalize a single track (ReplayGain)
mp3rgain -a *.mp3             # Normalize an album
mp3rgain -s R -a -R /music    # Apply from stored tags, rescan only where missing (v3.4+)
mp3rgain -g 2 song.mp3        # Manual gain (+3.0 dB; 1 step = 1.5 dB)
mp3rgain -u song.mp3          # Undo
mp3rgain song.mp3             # Show file info

Run mp3rgain -h for all options, or see the full CLI reference (analysis modes, tag handling, exit codes, recipes). Analysis runs in parallel by default; -j 1 forces the serial path (design and benchmarks).

Migrating from mp3gain?

mp3rgain is a drop-in replacement: CLI flags, TSV output, and the APEv2 mp3gain_undo tag are all mp3gain-compatible, so existing scripts and 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 flag equivalence table, where the tags land (ID3v2 vs APEv2, and the -s a / -s i overrides), and the small set of intentional behaviour differences. Bit-level verification lives in docs/compatibility-report.md.

GUI Application

mp3rgui covers the CLI's core workflow - track/album analysis and gain, undo, tag inspection, clipping prevention - with drag-and-drop loading and per-file progress. It shares the same apply pipeline as the CLI. Install via the table above.

Docker / CI

Multi-arch images (linux/amd64, linux/arm64) are published to GHCR as ghcr.io/m-igashi/mp3rgain with tags latest, v3, and exact versions. The image is FROM scratch (~2 MB); the entrypoint is the binary itself, so all flags work as on the host:

docker run --rm --user "$(id -u):$(id -g)" -v /path/to/music:/music ghcr.io/m-igashi/mp3rgain:latest -r -R /music

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"))?;

API documentation: docs.rs/mp3rgain.

Why mp3rgain?

The original mp3gain has been unmaintained upstream since ~2015, and aacgain since ~2009. mp3rgain is a memory-safe Rust replacement covering both formats, and the only maintained CLI for lossless AAC/M4A bitstream gain. It defaults to mp3gain-identical ReplayGain 1.0 values, with BS.1770 loudness (--rg2 / --r128) as an opt-in. How it compares to rsgain, loudgain, foobar2000, and ffmpeg - and when to use those instead - is covered in the tool comparison and docs/COMPARISON.md.

Documentation

• CLI Reference - options, analysis modes, exit codes, output formats, recipes
• Install Guide - all platforms, verification, troubleshooting
• Migration Guide - flag equivalence, substitution patterns, tag layout, beets config
• Technical Comparison - comparison with mp3gain, aacgain, and other ReplayGain tools
• Compatibility Report - bit-level verification against original mp3gain
• Parallel Performance - -j / --threads design and benchmarks
• Use Cases - integration examples (beets, headroom, etc.)
• Security - memory safety and CVE analysis
• Roadmap - development plans
• FAQ · Download Stats

Contributing

Contributions welcome! See CONTRIBUTING.md.

License

MIT License - see LICENSE.

See Also

• Original mp3gain
• headroom - DJ audio loudness optimizer