mp3rgain CLI Reference
Complete option reference for mp3rgain v3.1.0, plus exit codes, environment variables, output formats and the operational recipes that come up most often. The flag set is mp3gain-compatible, so anything you knew about mp3gain still applies.
The one-line mental model: mp3rgain [OPTIONS] <FILES>... —
with no options at all it only reports. Writing happens when you pass a gain
action (-r, -a, -g, -l, -u,
or -s d).
Options
| Option | Description |
|---|---|
-r | Apply Track gain (per-file ReplayGain analysis). |
-a | Apply Album gain — one shared gain across all files given in the same invocation. |
--rg2 | Analyse with ReplayGain 2.0: ITU-R BS.1770 gated loudness, −18 LUFS reference. |
--r128 | Analyse with EBU R128: ITU-R BS.1770 gated loudness, −23 LUFS target. |
-g <i> | Apply a manual gain of i steps. One step is 1.5 dB; i may be negative. |
-d <n> | Modify the suggested/target gain by n dB, rounded to the nearest step. Used with -r / -a. |
-m <i> | Modify the suggested gain by an integer number of steps. |
-l <c> <g> | Apply gain g to one channel only: c = 0 for left, 1 for right. |
-e | Skip album analysis even when several files are passed. |
-i <n> | Select which audio track to process (default: 0). |
-u | Undo previous gain changes, restoring the file from its stored undo tag. |
-x | Report the maximum amplitude only; nothing is written. |
-s <mode> | Stored-tag handling: c check/show, d delete, s skip writing, i use ID3v2, a use APEv2 (default), r force recalculation (accepted for mp3gain compatibility; always on). |
-p | Preserve the original file timestamp. |
-k | Prevent clipping by automatically limiting the applied gain. |
-c | Ignore clipping warnings and apply the gain anyway. |
-w | Wrap gain values instead of clamping them at the representable range. |
-q | Quiet mode — less output. |
-R | Recurse into directories. |
-n, --dry-run | Preview what would change; nothing is written. |
--skip-errors | Keep going past files that fail to analyse instead of aborting. Useful with -a on large libraries. |
-j <n>, --threads <n> | Worker threads for analysis. Default auto; 0 = auto, 1 = serial. |
-o <fmt> | Output format: text (default), json, or tsv. |
-t | Write via a temp file. Always on; accepted for mp3gain compatibility. |
-f | Assume MPEG 2 Layer III. Accepted for compatibility; no effect. |
-v | Print the version. |
-h | Print help. |
Analysis modes
ReplayGain 1.0 is the default and stays the default deliberately: it reproduces the original mp3gain's numbers exactly, so re-scanning a library that mp3gain already touched does not shift every file. The BS.1770 modes are opt-in.
| Mode | Flag | Algorithm | Reference | Use when |
|---|---|---|---|---|
| ReplayGain 1.0 | default | ReplayGain 1.0 | 89 dB | Migrating from mp3gain / aacgain, or matching an existing library |
| ReplayGain 2.0 | --rg2 | ITU-R BS.1770 (gated) | −18 LUFS | Matching modern taggers — rsgain, loudgain, foobar2000 |
| EBU R128 | --r128 | ITU-R BS.1770 (gated) | −23 LUFS | Broadcast delivery targets |
The BS.1770 measurements agree with ffmpeg ebur128 and other libebur128-based
tools to within 0.05 LU. Values from RG 1.0 and the BS.1770 modes are not
interchangeable — that is expected, not a bug.
Track gain vs album gain
-r gives every file its own gain, so each track hits the reference level on its
own. -a computes one gain for the whole set and applies it to every file, which
preserves the relative dynamics an album was mixed with. Album mode operates on the files
passed in a single invocation, so glob carefully:
# Correct: one album at a time
mp3rgain -a "Artist/Album/"*.mp3
# Wrong: treats an entire library as one album
mp3rgain -a -R /musicTags written
Applying gain writes standard ReplayGain metadata as well as the undo state, so the file
stays useful to ReplayGain-aware players. The container decides the tag format: APEv2 for MP3
by default, ID3v2 TXXX with -s i, MP4 freeform atoms for AAC/M4A.
| Tag | Written when | Meaning |
|---|---|---|
REPLAYGAIN_TRACK_GAIN / _PEAK | Any apply | Residual track gain remaining after the bitstream rewrite, following mp3gain's convention |
REPLAYGAIN_ALBUM_GAIN / _PEAK | -a | Same, for the album pass |
REPLAYGAIN_ALGORITHM | --rg2 / --r128 | ITU-R BS.1770 — records which measurement produced the values (v3.1+) |
MP3GAIN_UNDO, MP3GAIN_MINMAX | Any apply | mp3gain-compatible undo state, read back by -u |
Because the ReplayGain values are residuals, a ReplayGain-blind player and a
ReplayGain-aware one end up at the same loudness. -s c prints the stored tags,
-s d deletes them, and -s s applies gain without writing any.
Exit codes
| Code | Meaning |
|---|---|
0 | Success. Also returned by -h and -v. |
1 | Failure — invalid arguments, unreadable or undecodable input, or a write error. |
In a batch, one unreadable file aborts the run by default. Add --skip-errors to
report and continue, which is what you usually want for scheduled library sweeps.
Environment variables
| Variable | Effect |
|---|---|
MP3RGAIN_THREADS | Default worker-thread count for analysis, equivalent to -j. An explicit -j / --threads flag wins; 0 means auto. |
Useful for capping CPU use in containers or cron jobs without editing every command:
MP3RGAIN_THREADS=2 mp3rgain -r -R /musicOutput formats
-o text is the human-readable default. -o tsv emits the
tab-separated layout mp3gain produced, so existing parsers — beets among them — keep working
unchanged. -o json is the option to reach for in new automation:
mp3rgain -o json -r song.mp3 | jq '.'An unrecognised format argument falls back to TSV, matching how mp3gain behaved.
Recipes
Preview before touching anything
mp3rgain -n -r -R /musicNormalise a whole library, tolerating bad files
mp3rgain -r -R -k --skip-errors /music-k limits the gain where a full correction would clip.
Roll back a mistake
mp3rgain -u -R /musicUndo works from the stored tag, so it restores the exact original bitstream regardless of how the gain was applied — including AAC/M4A.
Audit what is already stored
mp3rgain -s c -R /musicKeep mtime stable for sync tools
mp3rgain -r -p -R /musicWithout -p, rewriting a file updates its mtime, which makes rsync, Syncthing and
most backup tools re-transfer the entire library.