mp3rgain CLI Reference
Complete option reference for mp3rgain v3.8.1, 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. |
--per-directory | With -a: group the files by parent directory and compute one album gain for each, so a whole library can be album-tagged in a single run. Pairs with -R (v3.6.1+). |
--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. |
--true-peak | Measure true peak (BS.1770-4 Annex 2) for REPLAYGAIN_*_PEAK instead of sample peak. Requires --rg2 or --r128 (v3.3+). |
--tags-only | Write the REPLAYGAIN_* tags and leave every audio frame untouched, the way loudgain and rsgain work, so the listener can still turn ReplayGain off in their player. Needs -r / -a; no undo tag is written, because nothing was changed to undo (v3.5+). |
-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, R apply from stored ReplayGain tags with -r/-a, rescanning only files whose tags are missing (mp3gain's default behavior, v3.4+), r force recalculation (the default; accepted for mp3gain compatibility), i put every tag in ID3v2, a put every tag in APEv2 (mp3gain's layout). The default splits them — see where the tags land. |
-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.
Supported formats
| Format | Support |
|---|---|
| MP3 (MPEG 1 / 2 / 2.5 Layer III) | Full lossless global_gain rewrite and undo. |
| AAC in M4A / MP4 | Full lossless bitstream gain and undo, including the audio track of a video MP4. HE-AAC/SBR is handled at the base layer. |
AAC, raw ADTS (.aac) | Full lossless bitstream gain and undo (v3.7+). A raw stream has no container for metadata, so its undo and REPLAYGAIN_* values go into an ID3v2 tag and the -s a / -s i layout choice does not apply. |
| ALAC, DRM-protected M4P | Recognised but not adjustable. Reported as skipped, and does not affect the exit status of a batch (v3.7+). |
| FLAC, Opus, Vorbis, WAV | Not supported. These have no in-bitstream gain field to rewrite; use a tag-based tool such as rsgain. |
With -R, directory scanning collects .mp3, .m4a,
.aac and .mp4. A file named explicitly on the command line is
processed whatever its extension, dispatched on what the container actually is.
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. Bare -a pools every file
it is given into a single album, so either glob one album at a time or let
--per-directory do the grouping:
# One album at a time
mp3rgain -a "Artist/Album/"*.mp3
# One album per folder, whole library in one run (v3.6.1+)
mp3rgain -a --per-directory -R /music
# Treats the entire library as one album — rarely what you want
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. On MP3 the two families are split by default:
REPLAYGAIN_* into ID3v2 TXXX where players look,
MP3GAIN_UNDO / MP3GAIN_MINMAX into APEv2 where mp3gain looks.
-s a puts everything in APEv2, -s i everything in ID3v2. AAC/M4A
always uses MP4 freeform atoms. See where the tags land.
| 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 /musicRe-apply gain from existing tags, no rescan (v3.4+)
mp3rgain -s R -a -R /musicFiles that already carry ReplayGain tags are applied from those values instead of being re-analysed; only files with missing tags are scanned. For album gain the whole album is rescanned unless every file in it has a consistent set of album tags. This mirrors mp3gain's default behaviour.
Tag the library without touching the audio (v3.5+)
mp3rgain -a --per-directory --tags-only -R /musicWrites the absolute REPLAYGAIN_* values and leaves every frame byte-identical,
the way loudgain and rsgain work, so a player that honours ReplayGain applies the correction
and one that ignores it plays the file untouched. The opposite trade-off from the bitstream
rewrite: nothing is baked in, so nothing needs undoing, but ReplayGain-blind hardware sees no
correction at all.
Keep 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.