MP3Gain Command Line Guide: Every Flag That Matters
The Windows program is a friendly shell over a command-line engine — backend version 1.5.2 — and on Linux and macOS that engine is all you get (see how to install it). The good news: the CLI does everything the GUI does, and it scripts beautifully. Every flag below is documented in the official mp3gain(1) man page; this guide translates that page into the options you will actually use, in the order you will reach for them.
The one rule to learn first: with none of -r, -a, -g or -l present, mp3gain only analyzes your files and writes the recommended gain into a tag — the audio is untouched. The apply flags are what actually change the gain inside the MP3 frames, in the format’s native 1.5 dB steps (see why the steps are 1.5 dB).
The apply flags: make it louder, make it quieter
| Flag | What it does |
|---|---|
-r | Track gain. Analyzes each file and adjusts it independently so every track lands at the same loudness. The default choice for mixed folders and playlists. |
-a | Album gain. Treats all files on the command line as one album: a single shared gain change is applied to all of them, so the quiet intro stays quiet relative to the loud finale, while the album as a whole matches your other albums. |
-g i | Direct gain. Applies a gain of i steps (each step = 1.5 dB) with no analysis at all. For when you already know a file needs, say, exactly two steps up: -g 2. |
-l 0 i / -l 1 i | Per-channel gain. Applies gain only to the left (0) or right (1) channel, for fixing lopsided rips. Only works on true stereo MP3s, not joint stereo. |
One interaction to memorize: if you pass both -r and -a, only the second one takes effect — the man page says so explicitly, and it is the most common cause of “I ran album mode but got track mode” confusion.
Targeting and clipping: aim, and don’t overshoot
| Flag | What it does |
|---|---|
-k | Clip protection. Automatically lowers the gain to the highest value that will not clip the audio, instead of applying the full suggested amount. The single most useful companion to -r and -a. |
-c | Ignore clipping warnings. Without -c, mp3gain stops and asks before applying a gain that might clip — good interactively, fatal to an unattended script. Prefer -k (prevents the clip) over -c (ignores the warning). |
-d n | dB offset. Modifies the suggested gain by a floating-point n decibels. mp3gain aims at the 89 dB ReplayGain reference by default; -d 3.0 aims 3 dB hotter. Read what 89 dB means before reaching for this — louder targets are paid for in clipping. |
-m i | Step offset. Like -d, but in whole 1.5 dB steps: -m 1 adds one step to whatever gain mp3gain suggests. |
Tags and undo: where the memory lives
mp3gain stores its analysis, the applied gain and the undo information in tags — APEv2 by default. The -s family controls that storage:
| Flag | What it does |
|---|---|
-s a | Store gain data in an APEv2 tag (the default). |
-s i | Store gain data in an ID3v2 tag; existing APEv2 gain data is upgraded to ID3v2. Useful when your player reads ID3v2 ReplayGain fields but not APEv2. |
-s c | Check only: print the stored tag information, do no other processing. The fastest way to see what a previous run did to a file. |
-s d | Delete the stored tag information. Warning: this also deletes your undo path — undo first, delete after, never the reverse. |
-s s | Skip tags entirely: do not read or write tag data. Combined with no apply flag, this gives you a pure dry-run analysis that leaves files byte-identical. |
-s r | Force re-calculation: ignore stored tag info and analyze from scratch. |
-u | Undo. Reverses changes mp3gain previously made, based on the stored tag info. This is the command-line twin of the GUI’s Undo Gain changes — the full mechanism, and its limits, are in our undo guide. |
Workflow flags for scripts and big libraries
-q— quiet mode, no status messages; pair with-ofor machine-readable, tab-delimited output you can pipe into a spreadsheet or log.-t— write the modified MP3 to a temporary file, then replace the original (the safer behavior, and the default in Debian builds). Its opposite,-T, modifies the original in place.-p— preserve the original file timestamps, so your library’s sort order survives processing.-x— report only the maximum amplitude of each file, a quick scan for tracks that are already at full scale.-f— force mp3gain to treat input as MPEG Layer III without checking (for mis-named files);-whandles the rare edge case where a gain change would wrap past the frame field’s 0–255 range;-vprints the version;-?prints the built-in help.
Three real jobs, three commands
1. One album, leveled as an album. Change into the album’s folder and apply album gain with clip protection to every file in it:
mp3gain -a -k *.mp3
The -a makes mp3gain compute one shared change for the whole set; -k guarantees the loudest track’s peaks cap the change before anything clips.
2. A whole mixed library, track by track, unattended. Recurse through a music tree and level every file independently:
find ~/Music -iname "*.mp3" -exec mp3gain -r -k {} +
-r is right here because the files are unrelated singles; -k means no file can clip and nothing stops to ask questions halfway through a 5,000-file run. Run it on a backup copy first if the library is irreplaceable — the full library workflow explains the safety routine.
3. Undo everything in a folder. Changed your mind about a processed album? Restore the original volumes from the stored undo data:
mp3gain -u *.mp3
This only works while the tags carrying the undo information are intact — which is why -s d (delete tag info) should always be the last thing you ever do to a file, if you do it at all.
Frequently asked questions
Does running mp3gain with no options change my files?
No. Without an apply flag (-r, -a, -g or -l), mp3gain only analyzes each file and writes the recommended gain into a tag — APEv2 by default. The audio data is modified only when you explicitly apply a gain.
Should I use -r or -a?
Use -r (track gain) for unrelated files — singles, playlists, a folder of mixed downloads — so each song is leveled on its own. Use -a (album gain) for a real album, so one shared adjustment preserves the intended loudness differences between its tracks. If you pass both, only the second one takes effect.
Why does mp3gain stop and ask about clipping?
Because without -c, it asks for confirmation before applying a gain that might push a file into clipping. You have three choices: answer the prompt, add -c to apply anyway (the file may clip), or — usually best — add -k, which automatically lowers the gain to the highest clip-free value.
Can I undo a gain change made from the command line?
Yes. Run mp3gain -u on the files and mp3gain reverses its earlier changes using the undo information stored in the files’ tags. The undo stops being possible if those tags were deleted (-s d) or stripped by another tool, so keep the tags until you are sure you are done.
Prefer buttons to flags?
The Windows GUI runs this exact engine with a file list and an Apply button — same analysis, same reversible changes.
Go to the Download PageNext steps: Make All MP3s the Same Volume · Undo MP3Gain Changes · MP3Gain on Linux