mp3rgain CLI reference
Updated · mp3rgain v3.16.2
Complete option reference for mp3rgain v3.16.2, plus exit codes, environment variables, output formats, and the recipes that come up most often. The flags follow mp3gain; where mp3rgain behaves differently, the table says so.
The one-line mental model: mp3rgain [OPTIONS] <FILES>...
with no options only reports. Files are written only when you pass an action:
-r, -a, -g, -l,
-u, or -s d. If you pass several, one wins:
-u -g 2 only undoes, and -r -g 2 ignores -g.
A read-only file is never written: a command that would change it fails for that file and
leaves it as it was, as in mp3gain (v3.11+).
Options
| Option | Description |
|---|---|
-r | Apply track gain: each file gets its own ReplayGain correction. |
-a | Apply album gain: one shared gain for every file given, mp3gain's rule. --album-by and --album-depth change what counts as one album. |
--album-by <dir|tag> | With -a: dir makes each directory one album; tag makes each release one album, keyed on MUSICBRAINZ_ALBUMID, else ALBUMARTIST (or ARTIST) plus ALBUM, so discs in subfolders share one album gain (files without an ALBUM tag fall back to their directory). Pairs with -R (v3.8+). |
--album-depth <n> | With -a -R: one album per directory n levels below each directory argument; deeper folders such as disc1/disc2 merge up. For untagged libraries: 2 suits Artist/Album trees, 0 makes each argument one album (v3.8+). |
--per-directory | Alias for --album-by dir (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. Cannot be combined with --rg2. |
--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 the audio untouched, the way loudgain and rsgain work, so the listener can still turn ReplayGain off in their player. Needs -r, -a, or -e; writes no undo tag, because nothing changed (v3.5+). |
-g <i> | Apply a manual gain of i steps (one step is 1.5 dB; i may be negative). Writes the undo tag and shifts any stored REPLAYGAIN_* values and MP3GAIN_ALBUM_MINMAX by the same amount, as mp3gain does (v3.10+; earlier versions left them describing the old audio). |
-d <n> | Shift the target gain by n dB, rounded to whole steps when audio is changed and applied exactly with --tags-only. Without -r / -a it shifts the recommendation the info scan prints. |
-m <i> | Shift the suggested gain by i steps; adds to -d. |
-l <c> <g> | Apply g steps to one channel only: c = 0 for left, 1 for right. MP3 only. Refused on mono and joint-stereo files, which are left untouched, as in mp3gain: a joint-stereo frame may code mid and side rather than left and right (v3.11+; earlier versions changed both channels). |
-e | Skip album analysis. On its own it only analyses each track and prints no album summary, as in mp3gain (v3.10+; earlier versions applied track gain). With -a it applies track gain like -r, unlike mp3gain. |
-i <n> | Audio track to analyse in a multi-track MP4 (default 0). Gain and tags always apply to the first audio track, so a value other than 0 is analysis-only: combining it with an option that writes is an error (v3.10+). |
-u | Undo previous gain changes from the stored undo tag. See what undo restores. |
-x | Report the maximum amplitude only; nothing is written. |
-s <mode> | Stored-tag handling: c show stored tags; d delete them (with -u, undo first; a file with nothing to delete is left untouched, v3.11+); s write no tags, so no undo either; R reuse stored RG 1.0 tags with -r / -a and analyse only files without them (mp3gain's default, v3.4+); r re-analyse, the default, accepted for mp3gain compatibility; i put every MP3 tag in ID3v2; a put every MP3 tag in APEv2 (mp3gain's layout). The default splits them: see where the tags land. |
-p | Preserve the file's modification time. |
-k | Limit the gain so the result does not clip. With -r / -a the limit comes from the decoded peak; with -g from the global_gain headroom. |
-c | Hide clipping warnings. Without -k, a gain that clips is applied anyway, with a warning. |
-w | Wrap gain values around 0..255 instead of clamping them. Disables the clipping check. |
-q | Quiet mode: less output. |
-R | Recurse into directory arguments, collecting .mp3, .m4a, .aac, and .mp4. Symlinked directories are not followed. |
-n, --dry-run | Preview what would change; nothing is written. |
--skip-errors | With -a: leave out files that fail to decode instead of failing the whole album. Useful on large libraries. |
-j <n>, --threads <n> | Worker threads for every per-file command. 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 on purpose: it lands on the same gain steps as mp3gain, so
re-scanning a library that mp3gain already touched does not shift every file. The BS.1770
modes are opt-in, and every mode changes the audio unless you add --tags-only.
| 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 test values agree with ffmpeg ebur128 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-LC in M4A / MP4 | Lossless bitstream gain and undo, including the audio track of a video MP4. |
AAC-LC, raw ADTS (.aac) | 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 -s a / -s i do not apply. |
| HE-AAC (v1 and v2), ALAC, DRM-protected M4P | Recognised but not adjustable. Reported as skipped, and does not affect the exit status of a batch (v3.7+; HE-AAC since v3.12). global_gain only reaches the core of HE-AAC, not its SBR high band, so earlier versions left that band at its original level. Undo still works on HE-AAC files they adjusted. |
| FLAC, Ogg (Vorbis, Opus), WAV | Not supported: mp3rgain cannot read them. Use a tag-based tool such as rsgain. |
With -R, directory scanning collects .mp3, .m4a,
.aac, and .mp4 and ignores everything else. A file named explicitly on
the command line is tried whatever its extension, based on what the file actually contains.
Channel gain (-l) is MP3 only.
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 album and applies it to every file, which
keeps the relative levels the album was mixed with. Bare -a pools every file it
is given into a single album, so either run it one album at a time or let
--album-by / --album-depth do the grouping:
# One album at a time
mp3rgain -a "Artist/Album/"*.mp3
# One album per folder, whole library in one run
mp3rgain -a --album-by dir -R /music
# One album per release from tags, discs in subfolders included (v3.8+)
mp3rgain -a --album-by tag -R /music
# Untagged Artist/Album tree: one album per folder two levels down (v3.8+)
mp3rgain -a --album-depth 2 -R /music
# Treats the entire library as one album (rarely what you want)
mp3rgain -a -R /musicThe GUI's default is per folder, the same as --album-by dir.
Tags written
Track and album gain (-r, -a) write 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 in MP4 always uses iTunes freeform atoms, and raw ADTS always uses
ID3v2. See where the tags land.
| Tag | Written by | Meaning |
|---|---|---|
REPLAYGAIN_TRACK_GAIN / _PEAK | -r, -a | Residual track gain left after the bitstream rewrite (mp3gain's convention); the absolute value with --tags-only |
REPLAYGAIN_ALBUM_GAIN / _PEAK | -a | Same, for the album |
REPLAYGAIN_ALGORITHM | --rg2 / --r128 | ITU-R BS.1770: records which measurement produced the values (v3.1+) |
MP3GAIN_UNDO, MP3GAIN_MINMAX | Every gain change except with -s s | mp3gain-compatible undo state, read back by -u (AAC uses mp3rgain_undo / mp3rgain_minmax) |
Because the ReplayGain values are residuals, a ReplayGain-blind player and a
ReplayGain-aware one end up at the same loudness. -g shifts them along with the
audio (v3.10+); -l does not update them, so run -r or -a
afterwards if you rely on the tags.
-s c prints the stored tags and -s d deletes them.
What undo restores
-u reads the undo tag and puts every frame's global_gain back, so the
audio is exactly as it was, on MP3 and AAC alike. On MP3 it also clears the now-stale
REPLAYGAIN_* values. Undo is cumulative across several applies. Limits:
- The file is byte-identical to the original whenever it had no ID3v2 tag of its own:
after
-g, after-r/-awith-s a, and since v3.16.2 after the default-r/-atoo, on MP3, M4A, and raw ADTS alike (earlier versions left an empty ID3v2 tag behind). An MP3 that already had an ID3v2 tag keeps it, rewritten as ID3v2.4, so it differs in the tag and not in the audio. - A frame whose gain hit the 0 or 255 limit was clamped and cannot be restored exactly. mp3rgain warns when this happens.
- An AAC file that crackles after a gain change by 2.8.0 to 3.11.1 has to be undone with that version, before upgrading. Those versions left some FDK-AAC frames at their original volume, and the undo of 3.12.0 or later raises them above it (#402).
- Nothing can be undone after
-s s(no undo tag) or--tags-only(nothing changed). - A record with different left and right values is refused on a mono or joint-stereo file
(v3.11+). mp3gain writes one when it refuses
-lthere without changing the audio, and one written by mp3rgain 3.10.0 or earlier after-lon such a file cannot be told apart from it.-s dremoves the record.
Exit codes
| Code | Meaning |
|---|---|
0 | Success, including files skipped as unsupported (HE-AAC, ALAC, M4P). Also returned by -h and -v. |
1 | Invalid arguments, no files found, or any file that failed to read, decode, or write, including a read-only file a command would have changed. |
A failed file does not stop the others: with -r or -g every other
file is still processed, and the run exits 1 at the end. With -a, one undecodable
file fails its whole album unless you add --skip-errors, which leaves it out.
An unknown single-letter option only prints a warning; an unknown long option is an error.
Environment variables
| Variable | Effect |
|---|---|
MP3RGAIN_THREADS | Default worker-thread count, equivalent to -j. An explicit -j / --threads flag wins; 0 means auto. |
MP3RGUI_RENDERER | GUI only: glow forces OpenGL. Windows defaults to wgpu (Direct3D 12 / Vulkan); other platforms always use OpenGL. |
MP3RGUI_FONT | GUI only: path to a font file for CJK file names. |
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 mp3gain's
tab-separated layout, so existing parsers such as beets keep working. -o on its
own, without a format word after it, also means TSV, as in mp3gain. -o json is the
one to use in new automation:
mp3rgain -o json -n -r song.mp3 | jq '.'Without an action flag, -o json reports frame statistics only (frame count,
MPEG version, channel mode, global_gain range, headroom) and runs no loudness
analysis.
Recipes
Preview before touching anything
mp3rgain -n -r -R /musicNormalise a whole library, avoiding clipping
mp3rgain -r -k -R /music-k limits the gain where a full correction would clip. Files that fail are
reported and the rest are still processed.
Album-tag a library, tolerating bad files
mp3rgain -a --album-by tag --skip-errors -R /musicRoll back a mistake
mp3rgain -u -R /musicUndo works from the stored tag, whichever way the gain was applied, MP3 and AAC alike. See what undo restores for the limits.
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. It works with RG 1.0 tags only, and is ignored with -d,
-m, --rg2, or --r128.
Tag the library without touching the audio (v3.5+)
mp3rgain -a --album-by dir --tags-only -R /musicWrites the absolute REPLAYGAIN_* values and leaves the audio untouched, the way
loudgain and rsgain work, so a player that honours ReplayGain applies the correction and one
that ignores it plays the file as it was. This is 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. Note that every write replaces the file
(temp file plus rename): permissions are kept, but hard links, ownership, and extended
attributes are not. A symlink keeps pointing at the updated file (v3.10+).