mp3rgain

Lossless MP3 volume adjustment - a modern mp3gain replacement written in Rust

mp3rgain adjusts MP3 volume without re-encoding by modifying the global_gain field in each frame's side information. This preserves audio quality while achieving permanent volume changes.

Features

Lossless: No re-encoding, preserves original audio quality
Fast: Direct binary manipulation, no audio decoding required
Reversible: All changes can be undone
Zero dependencies: Single static binary (no ffmpeg, no mp3gain)
Cross-platform: macOS, Linux, Windows (x86_64 and ARM64)
mp3gain compatible: Same command-line interface as the original mp3gain
Pure Rust: Memory-safe implementation

Installation

Homebrew (macOS)

brew install M-Igashi/tap/mp3rgain

Cargo (all platforms)

cargo install mp3rgain

Download binary

Download the latest release from GitHub Releases:

macOS (Universal): mp3rgain-*-macos-universal.tar.gz
Linux (x86_64): mp3rgain-*-linux-x86_64.tar.gz
Windows (x86_64): mp3rgain-*-windows-x86_64.zip
Windows (ARM64): mp3rgain-*-windows-arm64.zip

Usage

Show file information (default)

mp3rgain song.mp3

Output:

song.mp3
  Format:      MPEG1 Layer III, Joint Stereo
  Frames:      5765
  Gain range:  89 - 217 (avg: 168.2)
  Headroom:    38 steps (+57.0 dB)

Apply gain adjustment

# Apply +2 steps (+3.0 dB)
mp3rgain -g 2 song.mp3

# Apply +4.5 dB (rounds to nearest step)
mp3rgain -d 4.5 song.mp3

# Reduce volume by 3 steps (-4.5 dB)
mp3rgain -g -3 *.mp3

# Apply gain and preserve file timestamp
mp3rgain -g 2 -p song.mp3

Undo previous adjustment

To undo a previous gain change, apply the inverse:

# Undo a +2 step adjustment
mp3rgain -g -2 song.mp3

Command-Line Options

Option	Description
`-g <i>`	Apply gain of i steps (each step = 1.5 dB)
`-d <n>`	Apply gain of n dB (rounded to nearest step)
`-s c`	Check/show file info (analysis only)
`-p`	Preserve original file timestamp
`-c`	Ignore clipping warnings
`-q`	Quiet mode (less output)
`-v`	Show version
`-h`	Show help

mp3gain Compatibility

mp3rgain uses the same command-line syntax as the original mp3gain:

# These commands work the same way in both mp3gain and mp3rgain
mp3gain -g 2 song.mp3      # original mp3gain
mp3rgain -g 2 song.mp3     # mp3rgain (drop-in replacement)

Not yet implemented:

-r (Track gain) - requires ReplayGain analysis
-a (Album gain) - requires ReplayGain analysis
-u (Undo from tags) - requires APEv2 tag support

Technical Details

Gain Steps

Each gain step equals 1.5 dB (fixed by MP3 specification). The global_gain field is 8 bits, allowing values 0-255.

Steps	dB Change
+1	+1.5 dB
+2	+3.0 dB
+4	+6.0 dB
-2	-3.0 dB

How It Works

MP3 files contain a global_gain field in each frame's side information that controls playback volume. mp3rgain directly modifies these values without touching the audio data, making the adjustment completely lossless and reversible.

Compatibility

MPEG1 Layer III (MP3)
MPEG2 Layer III
MPEG2.5 Layer III
Mono, Stereo, Joint Stereo, Dual Channel
ID3v2 tags (preserved)
VBR and CBR files

Why mp3rgain?

The original mp3gain has been unmaintained since ~2015 and has compatibility issues with modern systems (including Windows 11). mp3rgain is a modern replacement that:

Works on Windows 11, macOS, and Linux
Has no external dependencies
Is written in memory-safe Rust
Uses the same command-line interface
Includes a library API for integration

Library Usage

use mp3rgain::{apply_gain, apply_gain_db, analyze};
use std::path::Path;

// Apply +2 gain steps (+3.0 dB)
let frames = apply_gain(Path::new("song.mp3"), 2)?;
println!("Modified {} frames", frames);

// Analyze file
let info = analyze(Path::new("song.mp3"))?;
println!("Headroom: {} steps", info.headroom_steps);

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

We especially welcome:

Windows testing and compatibility reports
ReplayGain analysis implementation
Bug reports and feature requests

License

MIT License - see LICENSE for details.

mp3rgain 0.3.0