feat: add AAC/M4A ReplayGain support (issue #17)

- Add mp4meta module for reading/writing iTunes freeform metadata
- Support ReplayGain tag writing to M4A files (com.apple.iTunes format)
- Integrate AAC audio analysis using symphonia's aac/isomp4 features
- Update file collection to include .m4a, .aac, .mp4 extensions
- Handle MP4 moov/udta/meta/ilst atom structure
- Update stco/co64 chunk offsets when modifying metadata

Note: For AAC files, only ReplayGain tags are written (no audio modification)
as AAC lacks a lossless gain adjustment mechanism like MP3's global_gain.

Author: m_igashi

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mp3rgain"
-version = "0.8.0"
+version = "0.9.0"
 edition = "2021"
 authors = ["Masanari Higashi <M-Igashi@users.noreply.github.com>"]
 description = "Lossless MP3 volume adjustment - a modern mp3gain replacement written in Rust"
@@ -14,11 +14,13 @@ categories = ["multimedia::audio", "command-line-utilities"]
 [features]
 default = []
 replaygain = ["symphonia"]
+aac = ["symphonia-aac"]
+symphonia-aac = ["symphonia"]
 
 [dependencies]
 anyhow = "1.0"
 colored = "2.0"
-symphonia = { version = "0.5", optional = true, default-features = false, features = ["mp3"] }
+symphonia = { version = "0.5", optional = true, default-features = false, features = ["mp3", "aac", "isomp4"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 indicatif = "0.17"

README.md

@@ -8,12 +8,15 @@
 
 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.
 
+**NEW in v0.9.0**: AAC/M4A support - analyze and write ReplayGain tags to M4A files!
+
 ## Features
 
 - **Lossless**: No re-encoding, preserves original audio quality
 - **Fast**: Direct binary manipulation, no audio decoding required
 - **Reversible**: All changes can be undone (stored in APEv2 tags)
 - **ReplayGain**: Track and album gain analysis (optional feature)
+- **AAC/M4A Support**: Analyze and tag M4A files with ReplayGain metadata
 - **Zero dependencies**: Single static binary (no ffmpeg, no mp3gain)
 - **Cross-platform**: macOS, Linux, Windows (x86_64 and ARM64)
 - **mp3gain compatible**: Full command-line compatibility with original mp3gain
@@ -91,6 +94,25 @@ mp3rgain -r *.mp3
 mp3rgain -a *.mp3
 ```
 
+### AAC/M4A Support (requires `--features replaygain`)
+
+```bash
+# Analyze and tag M4A files with ReplayGain
+mp3rgain -r song.m4a
+mp3rgain -r *.m4a
+
+# Album gain for M4A files
+mp3rgain -a *.m4a
+
+# Mix MP3 and M4A files
+mp3rgain -r *.mp3 *.m4a
+
+# Recursive directory processing includes M4A files
+mp3rgain -R /path/to/music
+```
+
+Note: For M4A files, mp3rgain writes ReplayGain tags (iTunes freeform format) but does not modify the audio data, as AAC doesn't have a lossless gain adjustment mechanism like MP3's `global_gain` field.
+
 ### Undo previous adjustment
 
 ```bash
@@ -270,22 +292,33 @@ MP3 files contain a `global_gain` field in each frame's side information that co
 
 ### 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:
+When built with the `replaygain` feature, mp3rgain uses the [symphonia](https://github.com/pdrat/symphonia) crate for audio decoding and implements the ReplayGain 1.0 algorithm:
 
-1. Decode MP3 to PCM audio
+1. Decode MP3/AAC 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
 
+### AAC/M4A Support
+
+For AAC/M4A files, mp3rgain:
+- Analyzes audio loudness using the same ReplayGain algorithm as MP3
+- Writes ReplayGain tags in iTunes freeform format (`com.apple.iTunes:replaygain_*`)
+- Does NOT modify audio data (AAC lacks a lossless gain mechanism)
+
+Players that support ReplayGain tags will automatically apply volume normalization during playback.
+
 ### Compatibility
 
 - MPEG1 Layer III (MP3)
 - MPEG2 Layer III
 - MPEG2.5 Layer III
+- AAC/M4A (ReplayGain tags only)
 - Mono, Stereo, Joint Stereo, Dual Channel
 - ID3v2 tags (preserved)
 - APEv2 tags (for undo support)
+- iTunes metadata (for M4A files)
 - VBR and CBR files
 
 ## Why mp3rgain?

src/lib.rs

@@ -37,6 +37,7 @@
 //! Each gain step equals 1.5 dB (fixed by MP3 specification).
 //! The global_gain field is 8 bits, allowing values 0-255.
 
+pub mod mp4meta;
 pub mod replaygain;
 
 use anyhow::{Context, Result};

src/main.rs

@@ -6,7 +6,8 @@
 use anyhow::Result;
 use colored::*;
 use indicatif::{ProgressBar, ProgressStyle};
-use mp3rgain::replaygain::{self, ReplayGainResult, REPLAYGAIN_REFERENCE_DB};
+use mp3rgain::mp4meta;
+use mp3rgain::replaygain::{self, AudioFileType, ReplayGainResult, REPLAYGAIN_REFERENCE_DB};
 use mp3rgain::{
     analyze, apply_gain_channel_with_undo, apply_gain_with_undo, apply_gain_with_undo_wrap,
     db_to_steps, delete_ape_tag, find_max_amplitude, read_ape_tag_from_file, steps_to_db,
@@ -47,6 +48,12 @@ enum StoredTagMode {
     UseApev2, // -s a: Use APEv2 tags (default)
 }
 
+/// Album gain info for AAC files
+struct AacAlbumInfo {
+    album_gain_db: f64,
+    album_peak: f64,
+}
+
 #[derive(Default)]
 struct Options {
     // Gain options
@@ -399,7 +406,7 @@ fn expand_files_recursive(paths: &[PathBuf]) -> Result<Vec<PathBuf>> {
 
     for path in paths {
         if path.is_dir() {
-            collect_mp3_files(path, &mut result)?;
+            collect_audio_files(path, &mut result)?;
         } else {
             result.push(path.clone());
         }
@@ -409,15 +416,19 @@ fn expand_files_recursive(paths: &[PathBuf]) -> Result<Vec<PathBuf>> {
     Ok(result)
 }
 
-fn collect_mp3_files(dir: &Path, result: &mut Vec<PathBuf>) -> Result<()> {
+fn collect_audio_files(dir: &Path, result: &mut Vec<PathBuf>) -> Result<()> {
     for entry in std::fs::read_dir(dir)? {
         let entry = entry?;
         let path = entry.path();
 
         if path.is_dir() {
-            collect_mp3_files(&path, result)?;
+            collect_audio_files(&path, result)?;
         } else if let Some(ext) = path.extension() {
-            if ext.eq_ignore_ascii_case("mp3") {
+            if ext.eq_ignore_ascii_case("mp3")
+                || ext.eq_ignore_ascii_case("m4a")
+                || ext.eq_ignore_ascii_case("aac")
+                || ext.eq_ignore_ascii_case("mp4")
+            {
                 result.push(path);
             }
         }
@@ -437,7 +448,7 @@ fn run(mut opts: Options) -> Result<()> {
     if opts.recursive {
         opts.files = expand_files_recursive(&opts.files)?;
         if opts.files.is_empty() {
-            eprintln!("{}: no MP3 files found", "error".red().bold());
+            eprintln!("{}: no audio files found (MP3/M4A)", "error".red().bold());
             std::process::exit(1);
         }
     }
@@ -1376,7 +1387,17 @@ fn cmd_album_gain(files: &[PathBuf], opts: &Options) -> Result<()> {
                 progress_set_message(&pb, filename);
 
                 let track_result = &album_result.tracks[i];
-                let result = process_apply_replaygain(file, steps, track_result, opts)?;
+                let album_info = AacAlbumInfo {
+                    album_gain_db: album_result.album_gain_db,
+                    album_peak: album_result.album_peak,
+                };
+                let result = process_apply_replaygain_with_album(
+                    file,
+                    steps,
+                    track_result,
+                    opts,
+                    Some(&album_info),
+                )?;
                 if opts.output_format == OutputFormat::Json {
                     if result.status.as_deref() == Some("success") {
                         successful += 1;
@@ -1930,6 +1951,16 @@ fn process_apply_replaygain(
     steps: i32,
     result: &ReplayGainResult,
     opts: &Options,
+) -> Result<JsonFileResult> {
+    process_apply_replaygain_with_album(file, steps, result, opts, None)
+}
+
+fn process_apply_replaygain_with_album(
+    file: &PathBuf,
+    steps: i32,
+    result: &ReplayGainResult,
+    opts: &Options,
+    album_info: Option<&AacAlbumInfo>,
 ) -> Result<JsonFileResult> {
     let filename = file
         .file_name()
@@ -1998,12 +2029,17 @@ fn process_apply_replaygain(
     // Dry run: don't actually modify
     if opts.dry_run {
         if opts.output_format == OutputFormat::Text && !opts.quiet {
+            let format_info = match result.file_type {
+                AudioFileType::Aac => " (tags only)",
+                AudioFileType::Mp3 => "",
+            };
             println!(
-                "  {} [DRY RUN] {} (would apply {:+.1} dB, {} steps)",
+                "  {} [DRY RUN] {} (would apply {:+.1} dB, {} steps{})",
                 "~".cyan(),
                 filename,
                 steps_to_db(actual_steps),
-                actual_steps
+                actual_steps,
+                format_info
             );
         }
         return Ok(JsonFileResult {
@@ -2019,6 +2055,20 @@ fn process_apply_replaygain(
         });
     }
 
+    // Handle AAC/M4A files differently - only write ReplayGain tags
+    if result.file_type == AudioFileType::Aac {
+        return process_apply_replaygain_aac_with_album(
+            file,
+            actual_steps,
+            result,
+            opts,
+            warning_msg,
+            original_mtime,
+            album_info,
+        );
+    }
+
+    // MP3: Apply gain to audio frames
     let apply_result = if opts.wrap_gain {
         apply_with_temp_file(file, |f| apply_gain_with_undo_wrap(f, actual_steps), opts)
     } else {
@@ -2069,6 +2119,80 @@ fn process_apply_replaygain(
     }
 }
 
+/// Apply ReplayGain to AAC/M4A files with optional album info
+fn process_apply_replaygain_aac_with_album(
+    file: &PathBuf,
+    _actual_steps: i32,
+    result: &ReplayGainResult,
+    opts: &Options,
+    warning_msg: Option<String>,
+    original_mtime: Option<std::time::SystemTime>,
+    album_info: Option<&AacAlbumInfo>,
+) -> Result<JsonFileResult> {
+    let filename = file
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("unknown");
+
+    // Create ReplayGain tags for AAC
+    let mut tags = mp4meta::ReplayGainTags::new();
+    tags.set_track(result.gain_db, result.peak);
+
+    // Add album tags if available
+    if let Some(album) = album_info {
+        tags.set_album(album.album_gain_db, album.album_peak);
+    }
+
+    // Write tags to file
+    match mp4meta::write_replaygain_tags(file, &tags) {
+        Ok(()) => {
+            // Restore timestamp if needed
+            if let Some(mtime) = original_mtime {
+                restore_timestamp(file, mtime);
+            }
+
+            let tag_type = if album_info.is_some() {
+                "track+album tags"
+            } else {
+                "tags"
+            };
+
+            if opts.output_format == OutputFormat::Text && !opts.quiet {
+                println!(
+                    "  {} {} ({} written, {:+.1} dB)",
+                    "v".green(),
+                    filename,
+                    tag_type,
+                    result.gain_db
+                );
+            }
+
+            Ok(JsonFileResult {
+                file: file.display().to_string(),
+                status: Some("success".to_string()),
+                loudness_db: Some(result.loudness_db),
+                peak: Some(result.peak),
+                gain_applied_steps: Some(result.gain_steps()),
+                gain_applied_db: Some(result.gain_db),
+                warning: warning_msg,
+                ..Default::default()
+            })
+        }
+        Err(e) => {
+            if opts.output_format == OutputFormat::Text && !opts.quiet {
+                eprintln!("  {} {} - {}", "x".red(), filename, e);
+            }
+
+            Ok(JsonFileResult {
+                file: file.display().to_string(),
+                status: Some("error".to_string()),
+                error: Some(e.to_string()),
+                ..Default::default()
+            })
+        }
+    }
+}
+
 fn restore_timestamp(file: &PathBuf, mtime: SystemTime) {
     let _ = std::fs::File::options()
         .write(true)