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. AAC is handled in an M4A/MP4 container (including the audio track of a video MP4) and as a raw ADTS .aac stream.
- Lossless & reversible: no re-encoding; every change can be undone with
-u (MP3, AAC in M4A/MP4, and raw ADTS .aac)
- 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: )
CLI (mp3rgain)
| Platform | Command |
|---|
| macOS | brew install M-Igashi/tap/mp3rgain |
| Windows | winget install M-Igashi.mp3rgain |
| Arch Linux (AUR) | yay -S mp3rgain-bin |
| Ubuntu 26.04 LTS (PPA) | sudo add-apt-repository ppa:m-igashi/mp3rgain && sudo apt install mp3rgain |
| Debian | sudo apt install ./mp3rgain_*_amd64.deb (download) |
| Nix/NixOS | nix profile install github:M-Igashi/mp3rgain |
| Docker | docker pull ghcr.io/m-igashi/mp3rgain:latest |
| Cargo | cargo install mp3rgain |
GUI (mp3rgui)
| Platform | Command |
|---|
| macOS | brew install --cask M-Igashi/tap/mp3rgui |
| Windows | winget install M-Igashi.mp3rgui (portable; use the installer for a Start Menu entry) |
| Arch Linux (AUR) | yay -S mp3rgui |
| Ubuntu 26.04 LTS (PPA) | sudo add-apt-repository ppa:m-igashi/mp3rgui && sudo apt install mp3rgui |
| Debian/Ubuntu | sudo apt install ./mp3rgui_*_amd64.deb (download) |
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 -a --per-directory -R /music # One album per folder, whole library in one run (v3.6.1+)
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. File names in Japanese, Chinese or Korean are rendered with a CJK font already installed on your system; set MP3RGUI_FONT to a font file path to pick a different one.
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