feat: add ReplayGain analysis (-r track gain, -a album gain)

- Add symphonia as optional dependency for MP3 decoding
- Implement equal-loudness filter (Yule-Walker + Butterworth)
- Implement RMS loudness calculation with 95th percentile
- Add -r flag for track gain (normalizes each file to 89 dB)
- Add -a flag for album gain (normalizes album to 89 dB)
- Update README with full mp3gain compatibility

Closes #1

Author: m_igashi

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mp3rgain"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2021"
 authors = ["Masanari Higashi <M-Igashi@users.noreply.github.com>"]
 description = "Lossless MP3 volume adjustment - a modern mp3gain replacement written in Rust"
@@ -11,9 +11,14 @@ readme = "README.md"
 keywords = ["mp3", "audio", "gain", "volume", "lossless"]
 categories = ["multimedia::audio", "command-line-utilities"]
 
+[features]
+default = []
+replaygain = ["symphonia"]
+
 [dependencies]
 anyhow = "1.0"
 colored = "2.0"
+symphonia = { version = "0.5", optional = true, default-features = false, features = ["mp3"] }
 
 [lib]
 name = "mp3rgain"

README.md

@@ -12,10 +12,11 @@ mp3rgain adjusts MP3 volume without re-encoding by modifying the `global_gain` f
 
 - **Lossless**: No re-encoding, preserves original audio quality
 - **Fast**: Direct binary manipulation, no audio decoding required
-- **Reversible**: All changes can be undone
+- **Reversible**: All changes can be undone (stored in APEv2 tags)
+- **ReplayGain**: Track and album gain analysis (optional feature)
 - **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
+- **mp3gain compatible**: Full command-line compatibility with original mp3gain
 - **Pure Rust**: Memory-safe implementation
 
 ## Installation
@@ -29,7 +30,11 @@ brew install M-Igashi/tap/mp3rgain
 ### Cargo (all platforms)
 
 ```bash
+# Basic installation
 cargo install mp3rgain
+
+# With ReplayGain analysis support (-r and -a options)
+cargo install mp3rgain --features replaygain
 ```
 
 ### Download binary
@@ -73,13 +78,22 @@ mp3rgain -g -3 *.mp3
 mp3rgain -g 2 -p song.mp3
 ```
 
-### Undo previous adjustment
+### ReplayGain (requires `--features replaygain`)
+
+```bash
+# Apply track gain (normalize each file to 89 dB)
+mp3rgain -r song.mp3
+mp3rgain -r *.mp3
 
-To undo a previous gain change, apply the inverse:
+# Apply album gain (normalize album to 89 dB)
+mp3rgain -a *.mp3
+```
+
+### Undo previous adjustment
 
 ```bash
-# Undo a +2 step adjustment
-mp3rgain -g -2 song.mp3
+# Undo gain changes (uses APEv2 tag info)
+mp3rgain -u song.mp3
 ```
 
 ## Command-Line Options
@@ -88,6 +102,9 @@ mp3rgain -g -2 song.mp3
 |--------|-------------|
 | `-g <i>` | Apply gain of i steps (each step = 1.5 dB) |
 | `-d <n>` | Apply gain of n dB (rounded to nearest step) |
+| `-r` | Apply Track gain (ReplayGain analysis) |
+| `-a` | Apply Album gain (ReplayGain analysis) |
+| `-u` | Undo gain changes (restore from APEv2 tag) |
 | `-s c` | Check/show file info (analysis only) |
 | `-p` | Preserve original file timestamp |
 | `-c` | Ignore clipping warnings |
@@ -97,18 +114,19 @@ mp3rgain -g -2 song.mp3
 
 ### mp3gain Compatibility
 
-mp3rgain uses the same command-line syntax as the original mp3gain:
+mp3rgain is fully compatible with the original mp3gain command-line interface:
 
 ```bash
 # 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
+mp3gain -r *.mp3           # original mp3gain
+mp3rgain -r *.mp3          # mp3rgain (requires --features replaygain)
+
+mp3gain -a *.mp3           # original mp3gain  
+mp3rgain -a *.mp3          # mp3rgain (requires --features replaygain)
+```
 
 ## Technical Details
 
@@ -127,21 +145,32 @@ Each gain step equals **1.5 dB** (fixed by MP3 specification). The `global_gain`
 
 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.
 
+### ReplayGain Analysis
+
+When built with the `replaygain` feature, mp3rgain uses the [symphonia](https://github.com/pdrat/symphonia) crate for MP3 decoding and implements the ReplayGain 1.0 algorithm:
+
+1. Decode MP3 to PCM audio
+2. Apply equal-loudness filter (Yule-Walker + Butterworth)
+3. Calculate RMS loudness in 50ms windows
+4. Use 95th percentile for loudness measurement
+5. Calculate gain to reach 89 dB reference level
+
 ### Compatibility
 
 - MPEG1 Layer III (MP3)
 - MPEG2 Layer III
 - MPEG2.5 Layer III
 - Mono, Stereo, Joint Stereo, Dual Channel
 - ID3v2 tags (preserved)
+- APEv2 tags (for undo support)
 - VBR and CBR files
 
 ## Why mp3rgain?
 
 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:
 
 - Works on Windows 11, macOS, and Linux
-- Has no external dependencies
+- Has no external dependencies (base installation)
 - Is written in memory-safe Rust
 - Uses the same command-line interface
 - Includes a library API for integration
@@ -161,13 +190,17 @@ let info = analyze(Path::new("song.mp3"))?;
 println!("Headroom: {} steps", info.headroom_steps);
 ```
 
+## Acknowledgments
+
+- [symphonia](https://github.com/pdrat/symphonia) - Pure Rust audio decoding library (used for ReplayGain analysis)
+- [Original mp3gain](http://mp3gain.sourceforge.net/) - The original C implementation that inspired this project
+
 ## Contributing
 
 Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 We especially welcome:
 - Windows testing and compatibility reports
-- ReplayGain analysis implementation
 - Bug reports and feature requests
 
 ## License

src/lib.rs

@@ -12,6 +12,12 @@
 //! - **Compatible**: Works with all MP3 files (MPEG1/2/2.5 Layer III)
 //! - **Reversible**: Changes can be undone by applying negative gain
 //!
+//! ## Optional Features
+//!
+//! - **replaygain**: Enable ReplayGain analysis (requires symphonia)
+//!   - Track gain calculation (`-r` flag)
+//!   - Album gain calculation (`-a` flag)
+//!
 //! ## Example
 //!
 //! ```no_run
@@ -31,6 +37,8 @@
 //! Each gain step equals 1.5 dB (fixed by MP3 specification).
 //! The global_gain field is 8 bits, allowing values 0-255.
 
+pub mod replaygain;
+
 use anyhow::{Context, Result};
 use std::fs;
 use std::path::Path;
@@ -299,7 +307,7 @@ fn read_gain_at(data: &[u8], loc: &GainLocation) -> u8 {
         data[idx]
     } else if idx + 1 < data.len() {
         let shift = loc.bit_offset;
-        let high = (data[idx] << shift) as u8;
+        let high = data[idx] << shift;
         let low = data[idx + 1] >> (8 - shift);
         high | low
     } else {