Skip to content

Commit 03e70ef

Browse files
m_igashim_igashi
m_igashi
authored and
m_igashi
committed
feat: mp3gain-compatible CLI interface
BREAKING CHANGE: Replaced subcommand-based CLI with mp3gain-compatible flag-based CLI - Use same command syntax as original mp3gain (-g, -d, -s c, -p, -c, -q, -v) - Remove clap dependency for lighter binary - Update README with compatibility information - Update outreach docs to emphasize drop-in replacement goal Examples: mp3rgain -g 2 song.mp3 # Apply +2 steps mp3rgain -d 4.5 song.mp3 # Apply +4.5 dB mp3rgain song.mp3 # Show file info
1 parent a6755b2 commit 03e70ef

File tree

4 files changed

+487
-205
lines changed

4 files changed

+487
-205
lines changed

‎Cargo.toml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "mp3rgain"
3-
version = "0.2.0"
3+
version = "0.3.0"
44
edition = "2021"
55
authors = ["Masanari Higashi <M-Igashi@users.noreply.github.com>"]
66
description = "Lossless MP3 volume adjustment - a modern mp3gain replacement written in Rust"
@@ -13,7 +13,6 @@ categories = ["multimedia::audio", "command-line-utilities"]
1313

1414
[dependencies]
1515
anyhow = "1.0"
16-
clap = { version = "4.4", features = ["derive"] }
1716
colored = "2.0"
1817

1918
[lib]

‎README.md‎

Lines changed: 76 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,21 @@
22

33
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
44
[![Rust](https://img.shields.io/badge/rust-1.70%2B-blue.svg)](https://www.rust-lang.org)
5+
[![crates.io](https://img.shields.io/crates/v/mp3rgain.svg)](https://crates.io/crates/mp3rgain)
56

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

89
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.
910

1011
## Features
1112

12-
- 🎵 **Lossless**: No re-encoding, preserves original audio quality
13-
- ⚡ **Fast**: Direct binary manipulation, no audio decoding required
14-
- 🔄 **Reversible**: All changes can be undone
15-
- 📦 **Zero dependencies**: Single static binary (no ffmpeg, no mp3gain)
16-
- 🦀 **Pure Rust**: Memory-safe, cross-platform
13+
- **Lossless**: No re-encoding, preserves original audio quality
14+
- **Fast**: Direct binary manipulation, no audio decoding required
15+
- **Reversible**: All changes can be undone
16+
- **Zero dependencies**: Single static binary (no ffmpeg, no mp3gain)
17+
- **Cross-platform**: macOS, Linux, Windows (x86_64 and ARM64)
18+
- **mp3gain compatible**: Same command-line interface as the original mp3gain
19+
- **Pure Rust**: Memory-safe implementation
1720

1821
## Installation
1922

@@ -23,35 +26,26 @@ mp3rgain adjusts MP3 volume without re-encoding by modifying the `global_gain` f
2326
brew install M-Igashi/tap/mp3rgain
2427
```
2528

26-
### From source
29+
### Cargo (all platforms)
2730

2831
```bash
2932
cargo install mp3rgain
3033
```
3134

3235
### Download binary
3336

34-
Download the latest release from [GitHub Releases](https://github.com/M-Igashi/mp3rgain/releases).
37+
Download the latest release from [GitHub Releases](https://github.com/M-Igashi/mp3rgain/releases):
38+
- macOS (Universal): `mp3rgain-*-macos-universal.tar.gz`
39+
- Linux (x86_64): `mp3rgain-*-linux-x86_64.tar.gz`
40+
- Windows (x86_64): `mp3rgain-*-windows-x86_64.zip`
41+
- Windows (ARM64): `mp3rgain-*-windows-arm64.zip`
3542

3643
## Usage
3744

38-
### Apply gain adjustment
39-
40-
```bash
41-
# Apply +2 steps (+3.0 dB)
42-
mp3rgain apply -g 2 song.mp3
43-
44-
# Apply +4.5 dB (rounds to nearest step)
45-
mp3rgain apply -d 4.5 song.mp3
46-
47-
# Reduce volume by 3 steps (-4.5 dB)
48-
mp3rgain apply -g -3 *.mp3
49-
```
50-
51-
### Show file information
45+
### Show file information (default)
5246

5347
```bash
54-
mp3rgain info song.mp3
48+
mp3rgain song.mp3
5549
```
5650

5751
Output:
@@ -63,13 +57,59 @@ song.mp3
6357
Headroom: 38 steps (+57.0 dB)
6458
```
6559

60+
### Apply gain adjustment
61+
62+
```bash
63+
# Apply +2 steps (+3.0 dB)
64+
mp3rgain -g 2 song.mp3
65+
66+
# Apply +4.5 dB (rounds to nearest step)
67+
mp3rgain -d 4.5 song.mp3
68+
69+
# Reduce volume by 3 steps (-4.5 dB)
70+
mp3rgain -g -3 *.mp3
71+
72+
# Apply gain and preserve file timestamp
73+
mp3rgain -g 2 -p song.mp3
74+
```
75+
6676
### Undo previous adjustment
6777

78+
To undo a previous gain change, apply the inverse:
79+
6880
```bash
6981
# Undo a +2 step adjustment
70-
mp3rgain undo -g 2 song.mp3
82+
mp3rgain -g -2 song.mp3
83+
```
84+
85+
## Command-Line Options
86+
87+
| Option | Description |
88+
|--------|-------------|
89+
| `-g <i>` | Apply gain of i steps (each step = 1.5 dB) |
90+
| `-d <n>` | Apply gain of n dB (rounded to nearest step) |
91+
| `-s c` | Check/show file info (analysis only) |
92+
| `-p` | Preserve original file timestamp |
93+
| `-c` | Ignore clipping warnings |
94+
| `-q` | Quiet mode (less output) |
95+
| `-v` | Show version |
96+
| `-h` | Show help |
97+
98+
### mp3gain Compatibility
99+
100+
mp3rgain uses the same command-line syntax as the original mp3gain:
101+
102+
```bash
103+
# These commands work the same way in both mp3gain and mp3rgain
104+
mp3gain -g 2 song.mp3 # original mp3gain
105+
mp3rgain -g 2 song.mp3 # mp3rgain (drop-in replacement)
71106
```
72107

108+
**Not yet implemented:**
109+
- `-r` (Track gain) - requires ReplayGain analysis
110+
- `-a` (Album gain) - requires ReplayGain analysis
111+
- `-u` (Undo from tags) - requires APEv2 tag support
112+
73113
## Technical Details
74114

75115
### Gain Steps
@@ -98,12 +138,12 @@ MP3 files contain a `global_gain` field in each frame's side information that co
98138

99139
## Why mp3rgain?
100140

101-
The original [mp3gain](http://mp3gain.sourceforge.net/) has been unmaintained since ~2015. mp3rgain is a modern replacement that:
141+
The original [mp3gain](http://mp3gain.sourceforge.net/) has been unmaintained since ~2015 and has compatibility issues with modern systems (including Windows 11). mp3rgain is a modern replacement that:
102142

103-
- Is actively maintained
143+
- Works on Windows 11, macOS, and Linux
104144
- Has no external dependencies
105145
- Is written in memory-safe Rust
106-
- Provides a clean, modern CLI
146+
- Uses the same command-line interface
107147
- Includes a library API for integration
108148

109149
## Library Usage
@@ -121,14 +161,20 @@ let info = analyze(Path::new("song.mp3"))?;
121161
println!("Headroom: {} steps", info.headroom_steps);
122162
```
123163

124-
## License
164+
## Contributing
125165

126-
MIT License - see [LICENSE](LICENSE) for details.
166+
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
127167

128-
## Contributing
168+
We especially welcome:
169+
- Windows testing and compatibility reports
170+
- ReplayGain analysis implementation
171+
- Bug reports and feature requests
172+
173+
## License
129174

130-
Contributions are welcome! Please open an issue or submit a pull request.
175+
MIT License - see [LICENSE](LICENSE) for details.
131176

132177
## See Also
133178

179+
- [Original mp3gain](http://mp3gain.sourceforge.net/) - The original C implementation
134180
- [headroom](https://github.com/M-Igashi/headroom) - DJ audio loudness optimizer (uses mp3rgain internally)

‎docs/outreach/elfchief-mp3gain-issue.md‎

Lines changed: 60 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Issue for elfchief/mp3gain
22

33
## Title
4-
Introducing mp3rgain: A modern Rust rewrite of mp3gain
4+
mp3rgain: A drop-in Rust replacement for mp3gain with full command-line compatibility
55

66
## Body
77

@@ -11,25 +11,43 @@ I wanted to share a project that might be of interest to the mp3gain community.
1111

1212
### Introducing mp3rgain
1313

14-
I've created [**mp3rgain**](https://github.com/M-Igashi/mp3rgain), a modern reimplementation of mp3gain written in Rust. It provides the same core functionality - lossless MP3 volume adjustment by modifying the global gain field - but with some modern advantages.
14+
I've created [**mp3rgain**](https://github.com/M-Igashi/mp3rgain), a drop-in replacement for mp3gain written in Rust. It aims for **full command-line compatibility** with the original mp3gain, so existing scripts and workflows continue to work without modification.
1515

16-
### Why a new implementation?
16+
### Command-line Compatibility
17+
18+
mp3rgain uses the **same command-line syntax** as mp3gain:
19+
20+
```bash
21+
# These commands work identically in both tools
22+
mp3gain -g 2 song.mp3 # original mp3gain
23+
mp3rgain -g 2 song.mp3 # mp3rgain (drop-in replacement)
24+
25+
mp3gain -d 4.5 song.mp3 # apply dB
26+
mp3rgain -d 4.5 song.mp3
27+
28+
mp3gain -s c song.mp3 # check/analyze
29+
mp3rgain -s c song.mp3
30+
```
31+
32+
Supported options: `-g`, `-d`, `-s c`, `-p`, `-c`, `-q`, `-v`, `-h`
33+
34+
### Why a drop-in replacement?
1735

1836
The original mp3gain has been an invaluable tool for many years, but:
1937
- Development appears to have stalled
2038
- There are reports of compatibility issues with Windows 11
2139
- Building from source can be challenging on modern systems
40+
- Users need a tool that "just works" on modern platforms
2241

23-
### Features of mp3rgain
42+
### Features
2443

25-
- **Lossless** - Modifies global gain field directly, no re-encoding
26-
- **Fast** - Pure binary manipulation, no audio decoding required
44+
- **Full CLI compatibility** - Same command-line interface as mp3gain
45+
- **Lossless** - Modifies global_gain field directly, no re-encoding
46+
- **Cross-platform binaries** - macOS, Linux, Windows (x86_64 and ARM64)
2747
- **Zero dependencies** - Single static binary, no external tools needed
28-
- **Cross-platform** - macOS (Intel/Apple Silicon), Linux, Windows (x86_64/ARM64)
2948
- **Memory safe** - Written in Rust
30-
- **Easy installation** - Available via `cargo install mp3rgain`, Homebrew, or binary download
3149

32-
### Technical compatibility
50+
### Technical Compatibility
3351

3452
mp3rgain uses the same approach as the original mp3gain:
3553
- Modifies the global_gain field in MP3 frame side information
@@ -38,20 +56,49 @@ mp3rgain uses the same approach as the original mp3gain:
3856
- Handles VBR and CBR files
3957
- Preserves ID3v2 tags
4058

59+
### Current Status
60+
61+
**Implemented:**
62+
- `-g <i>` - Apply gain in steps
63+
- `-d <n>` - Apply gain in dB
64+
- `-s c` - Check/analyze files
65+
- `-p` - Preserve timestamp
66+
- `-c` - Ignore clipping warnings
67+
- `-q` - Quiet mode
68+
69+
**Not yet implemented (contributions welcome!):**
70+
- `-r` - Track gain (requires ReplayGain analysis)
71+
- `-a` - Album gain (requires ReplayGain analysis)
72+
- `-u` - Undo from APEv2 tags
73+
4174
### Links
4275

4376
- **GitHub**: https://github.com/M-Igashi/mp3rgain
4477
- **crates.io**: https://crates.io/crates/mp3rgain
78+
- **Releases**: https://github.com/M-Igashi/mp3rgain/releases (binaries for all platforms)
4579

46-
### Looking for contributors
80+
### Looking for Contributors
4781

4882
I'm actively looking for contributors, especially those with experience in:
49-
- Windows development and testing
83+
- Windows development and testing (especially Windows 11)
84+
- ReplayGain implementation (`-r` and `-a` options)
85+
- APEv2 tag handling (`-u` option)
5086
- MP3 format internals
51-
- ReplayGain implementation
5287

5388
If anyone from the mp3gain community would like to contribute, test, or provide feedback, I would greatly appreciate it!
5489

90+
### Installation
91+
92+
```bash
93+
# Homebrew (macOS)
94+
brew install M-Igashi/tap/mp3rgain
95+
96+
# Cargo (all platforms)
97+
cargo install mp3rgain
98+
99+
# Or download binaries from GitHub Releases
100+
```
101+
55102
---
56103

57-
Thank you for maintaining the original mp3gain all these years. It's been an inspiration for this project.
104+
Thank you for maintaining the original mp3gain all these years. The goal of mp3rgain is to carry on that legacy with a modern, maintainable codebase while preserving full compatibility for existing users.

0 commit comments

Comments
 (0)