# mp3rgain v2.10.0 - Complete Technical Documentation

> Lossless MP3/AAC volume adjustment — a modern mp3gain / aacgain replacement written in Rust.

> AI usage policy: This documentation is MIT-licensed. Free to use for indexing,
> citation, summarization, retrieval-augmented generation, and model training.
> All AI agents and crawlers are welcome. Attribution to https://github.com/M-Igashi/mp3rgain
> is appreciated but not required.

## Overview

mp3rgain adjusts MP3 and AAC volume without re-encoding by modifying the `global_gain` field in each frame. This preserves audio quality bit-exactly while achieving permanent volume changes that any player and any device will honor — unlike ReplayGain *tags*, which non-compliant players simply ignore.

It is the only actively maintained CLI for lossless AAC/M4A bitstream gain adjustment:

- mp3gain (http://mp3gain.sourceforge.net/) — unmaintained upstream since ~2015
- aacgain (http://aacgain.altosdesign.com/) — unmaintained since ~2009, effectively unbuildable on modern 64-bit systems
- rsgain / loudgain / FFmpeg — either only write ReplayGain tags or re-encode the audio
- foobar2000 — has a comparable "Apply ReplayGain to file content" feature for AAC in MP4/MKA, but it is Windows GUI only, has no undo, and is unsuited for batch / headless / container workflows

mp3rgain fills the cross-platform, scriptable, reversible niche, covering both MP3 and AAC in one memory-safe Rust binary.

## How It Works

1. **Analysis**: implements the ReplayGain 1.0 algorithm (89 dB reference level) for full compatibility with the original mp3gain / aacgain. Loudness values will differ from EBU R128/LUFS-based tools (foobar2000, loudgain, ffmpeg loudnorm) — that is by design.
2. **Gain application**: rewrites the `global_gain` field in every MP3 frame (or AAC `global_gain` in each AAC frame inside M4A/MP4). One step = 1.5 dB. No audio data is decoded or re-encoded.
3. **Undo**: the previous gain state is recorded in an APEv2 `mp3gain_undo` tag (MP4 freeform tag for AAC), so `mp3rgain -u` restores the original file exactly.

## Command-Line Options

| Option | Description |
|--------|-------------|
| `-r` | Apply Track gain (ReplayGain) |
| `-a` | Apply Album gain (ReplayGain) |
| `-g <i>` | Apply gain of i steps (1 step = 1.5 dB) |
| `-d <n>` | Modify suggested dB gain by n (mp3gain-compatible; applied with `-r` / `-a`) |
| `-u` | Undo gain changes |
| `-k` | Prevent clipping |
| `-l <ch> <i>` | Channel gain |
| `-x` | Find max amplitude |
| `-s c` / `-s d` / `-s i` | Check / delete stored tags, use ID3v2 |
| `-p` | Preserve file mtime |
| `-w` | Wrap mode |
| `-R` | Process directories recursively |
| `--skip-errors` | Keep album analysis (`-a`) going past unreadable files |
| `-n` | Dry-run mode |
| `-j <n>` / `--threads <n>` | Worker threads for analysis (default: auto, 0=auto, 1=serial) |
| `-o [fmt]` | Output format: `text`, `json`, `tsv` (default: tsv if no argument) |

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.

## Quick Start

```bash
# 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 / aacgain

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:

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

Full migration guide (flag equivalence table, Dockerfile/CI substitution patterns, tag interop notes, intentional behaviour differences):
https://github.com/M-Igashi/mp3rgain/blob/main/docs/migrating-from-mp3gain.md

Bit-level verification against the original mp3gain:
https://github.com/M-Igashi/mp3rgain/blob/main/docs/compatibility-report.md

## Installation

### 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 25.10 (PPA) | `sudo add-apt-repository ppa:m-igashi/mp3rgain && sudo apt install mp3rgain` (amd64/arm64) |
| Debian | `sudo apt install ./mp3rgain_*_amd64.deb` (from GitHub Releases; ARM64 also available) |
| 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` |
| Arch Linux (AUR) | `yay -S mp3rgui` |
| Ubuntu 25.10 (PPA) | `sudo add-apt-repository ppa:m-igashi/mp3rgui && sudo apt install mp3rgui` (amd64/arm64) |
| Debian/Ubuntu | `sudo apt install ./mp3rgui_*_amd64.deb` (ARM64 also available; requires Ubuntu 24.04+ / Debian trixie+) |

Pre-built binaries for all platforms: https://github.com/M-Igashi/mp3rgain/releases

## GUI Application (mp3rgui)

A native desktop app for users who prefer a graphical interface:

- 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), Use ID3v2 (-s i), Dry run (-n)
- Modify Gain menu: 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)
- Responsive UI: batch work runs on a worker thread with per-file progress and Cancel

## Docker / CI Usage

Official multi-arch images (linux/amd64, linux/arm64) on GHCR:

```
ghcr.io/m-igashi/mp3rgain:latest
ghcr.io/m-igashi/mp3rgain:v2          # latest 2.x
ghcr.io/m-igashi/mp3rgain:v2.10.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):

```bash
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.

## Library Usage (Rust crate)

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

mp3rgain is embedded as a library in Bake'n Deck (baken), a Rekordbox → CDJ prep toolkit: https://baken.ravers.workers.dev

## Documentation

- Migration Guide: https://github.com/M-Igashi/mp3rgain/blob/main/docs/migrating-from-mp3gain.md
- Parallel Performance (-j design + benchmarks): https://github.com/M-Igashi/mp3rgain/blob/main/docs/perf-parallel.md
- Security (memory safety, CVE analysis): https://github.com/M-Igashi/mp3rgain/blob/main/docs/security.md
- Compatibility Report: https://github.com/M-Igashi/mp3rgain/blob/main/docs/compatibility-report.md
- Technical Comparison with similar tools: https://github.com/M-Igashi/mp3rgain/blob/main/docs/COMPARISON.md
- Use Cases (beets, headroom/baken, …): https://github.com/M-Igashi/mp3rgain/blob/main/docs/use-cases.md
- Download Stats (weekly trends across all platforms): https://m-igashi.github.io/mp3rgain/

## Links

- Website: https://mp3rgain.tyna.ninja
- GitHub: https://github.com/M-Igashi/mp3rgain
- crates.io: https://crates.io/crates/mp3rgain
- Download stats: https://m-igashi.github.io/mp3rgain/

## License

MIT License