fix: strip ReplayGain tags after normalization, fixes #308

Author: slhck

CLAUDE.md

@@ -93,6 +93,8 @@ When adding, removing, or modifying CLI options, YOU MUST:
 
 This ensures users have accurate documentation and working shell completions for all CLI flags.
 
+**Important:** When modifying CLI descriptions (help texts), make sure to update the corresponding documentation in `docs/usage/cli-options.md` to keep them consistent, as well as the shell completions.
+
 ### Dependencies
 
 The project uses:

completions/ffmpeg-normalize-shtab.zsh

@@ -5,7 +5,7 @@
 
 _shtab_ffmpeg_normalize_commands() {
   local _commands=(
-    
+
   )
   _describe 'ffmpeg-normalize commands' _commands
 }
@@ -63,7 +63,7 @@ Otherwise, the range is -99 to 0.
 ]:target_level:"
   {-p,--print-stats}"[Print loudness statistics for both passes formatted as JSON to stdout.]"
   "--replaygain[Write ReplayGain tags to the original file without normalizing.
-This mode will overwrite the input file and ignore other options.
+This mode will overwrite the input file and ignore other options. It will strip all ReplayGain tags.
 Only works with EBU normalization, and only with .mp3, .mp4\/.m4a, .ogg, .opus for now.
 ]"
   "--batch[Preserve relative loudness between files (album mode).
@@ -231,7 +231,7 @@ _shtab_ffmpeg_normalize() {
       (( CURRENT += 1 ))
       curcontext="${curcontext%:*:*}:_shtab_ffmpeg_normalize-$line[1]:"
       case $line[1] in
-        
+
       esac
   esac
 }

docs/advanced/faq.md

@@ -30,6 +30,8 @@ You can use the `--replaygain` option to write ReplayGain tags to the original f
 
 If you decide to run `ffmpeg-normalize` with the default options, it will encode the audio with PCM audio (the default), and the resulting files will be very large. You can also choose to re-encode the files with MP3 or AAC, but you will inevitably introduce [generation loss](https://en.wikipedia.org/wiki/Generation_loss). Therefore, I do not recommend running this kind of destructive operation on your precious music collection, unless you have a backup of the originals or accept potential quality reduction.
 
+**Note:** When normalizing files (without the `--replaygain` option), any existing ReplayGain tags from the input file are automatically stripped from the output, as they are no longer accurate after normalization.
+
 ## Why are my output files MKV?
 
 I chose MKV as a default output container since it handles almost every possible combination of audio, video, and subtitle codecs. If you know which audio/video codec you want, and which container is supported, use the output options to specify the encoder and output file name manually.

docs/usage/cli-options.md

@@ -110,7 +110,7 @@ Print loudness statistics for both passes formatted as JSON to stdout.
 
 Write [ReplayGain](https://en.wikipedia.org/wiki/ReplayGain) tags to the original file without normalizing.
 
-This mode will overwrite the input file and ignore other options.
+This mode will overwrite the input file and ignore other options. It will strip all ReplayGain tags.
 
 Only works with EBU normalization, and only with .mp3, .mp4/.m4a, .ogg, .opus for now.
 

src/ffmpeg_normalize/__main__.py

@@ -197,7 +197,7 @@ def create_parser() -> argparse.ArgumentParser:
         help=textwrap.dedent(
             """\
         Write ReplayGain tags to the original file without normalizing.
-        This mode will overwrite the input file and ignore other options.
+        This mode will overwrite the input file and ignore other options. It will strip all ReplayGain tags.
         Only works with EBU normalization, and only with .mp3, .mp4/.m4a, .ogg, .opus for now.
         """
         ),

src/ffmpeg_normalize/_media_file.py

@@ -332,8 +332,10 @@ def run_normalization(self, batch_reference: float | None = None) -> None:
                 "ReplayGain tagging is enabled. Proceeding with tag calculation/application."
             )
             self._run_replaygain()
-
-        if not self.ffmpeg_normalize.replaygain:
+        else:
+            # Strip any existing ReplayGain tags from the output file
+            # since they are no longer accurate after normalization
+            self._strip_replaygain_tags(self.output_file)
             _logger.info(f"Normalized file written to {self.output_file}")
 
     def _run_replaygain(self) -> None:
@@ -461,6 +463,103 @@ def _write_replaygain_tags(self, track_gain: float, track_peak: float) -> None:
             f"Successfully wrote replaygain tags to input file {self.input_file}"
         )
 
+    def _strip_replaygain_tags(self, output_file: str) -> None:
+        """
+        Strip ReplayGain tags from the output file after normalization.
+
+        This ensures that old ReplayGain tags from the input are removed,
+        since they are no longer accurate after normalization.
+
+        Args:
+            output_file (str): Path to the output file to strip tags from
+        """
+        _logger.debug(f"Stripping ReplayGain tags from {output_file}")
+
+        output_file_ext = os.path.splitext(output_file)[1]
+        if output_file_ext == ".mp3":
+            try:
+                mp3 = MP3(output_file, ID3=ID3)
+                if not mp3.tags:
+                    return
+                # Remove REPLAYGAIN_* tags
+                tags_to_remove = [
+                    key for key in mp3.tags if key.startswith("TXXX:REPLAYGAIN_")
+                ]
+                for tag in tags_to_remove:
+                    del mp3.tags[tag]
+                if tags_to_remove:
+                    mp3.save()
+                    _logger.debug(
+                        f"Stripped {len(tags_to_remove)} ReplayGain tag(s) from {output_file}"
+                    )
+            except Exception as e:
+                _logger.warning(
+                    f"Could not strip ReplayGain tags from {output_file}: {e}"
+                )
+        elif output_file_ext in [".mp4", ".m4a", ".m4v", ".mov"]:
+            try:
+                mp4 = MP4(output_file)
+                if not mp4.tags:
+                    return
+                # Remove REPLAYGAIN_* tags
+                tags_to_remove = [
+                    key
+                    for key in mp4.tags
+                    if "REPLAYGAIN_" in key.upper() or "REPLAYGAIN" in key.upper()
+                ]
+                for tag in tags_to_remove:
+                    del mp4.tags[tag]
+                if tags_to_remove:
+                    mp4.save()
+                    _logger.debug(
+                        f"Stripped {len(tags_to_remove)} ReplayGain tag(s) from {output_file}"
+                    )
+            except Exception as e:
+                _logger.warning(
+                    f"Could not strip ReplayGain tags from {output_file}: {e}"
+                )
+        elif output_file_ext == ".ogg":
+            try:
+                ogg = OggVorbis(output_file)
+                # Remove REPLAYGAIN_* tags (case-insensitive)
+                tags_to_remove = [
+                    key for key in ogg.keys() if key.upper().startswith("REPLAYGAIN_")
+                ]
+                for tag in tags_to_remove:
+                    del ogg[tag]
+                if tags_to_remove:
+                    ogg.save()
+                    _logger.debug(
+                        f"Stripped {len(tags_to_remove)} ReplayGain tag(s) from {output_file}"
+                    )
+            except Exception as e:
+                _logger.warning(
+                    f"Could not strip ReplayGain tags from {output_file}: {e}"
+                )
+        elif output_file_ext == ".opus":
+            try:
+                opus = OggOpus(output_file)
+                # Remove R128_* tags (Opus uses R128 instead of REPLAYGAIN, case-insensitive)
+                tags_to_remove = [
+                    key for key in opus.keys() if key.upper().startswith("R128_")
+                ]
+                for tag in tags_to_remove:
+                    del opus[tag]
+                if tags_to_remove:
+                    opus.save()
+                    _logger.debug(
+                        f"Stripped {len(tags_to_remove)} R128 tag(s) from {output_file}"
+                    )
+            except Exception as e:
+                _logger.warning(
+                    f"Could not strip ReplayGain tags from {output_file}: {e}"
+                )
+        else:
+            # For other formats, we don't need to strip tags
+            _logger.debug(
+                f"Skipping ReplayGain tag stripping for {output_file_ext} (not supported/needed)"
+            )
+
     def _can_write_output_video(self) -> bool:
         """
         Determine whether the output file can contain video at all.

tests/test_all.py

@@ -659,6 +659,194 @@ def test_valid_file_passes_validation(self):
         ffmpeg_normalize_call(["tests/test.mp4", "-n"])  # dry run
         # No assertion needed - if validation fails, the command will error
 
+    def test_replaygain_tags_stripped_after_normalization(self, tmp_path):
+        """Test that ReplayGain tags are stripped after normalization."""
+        import shutil
+        from mutagen.id3 import ID3, TXXX
+        from mutagen.mp3 import MP3
+
+        temp_input = tmp_path / "test_with_replaygain.mp3"
+        temp_output = tmp_path / "normalized_output.mp3"
+
+        try:
+            # Create a temporary copy of test.mp3 with ReplayGain tags
+            shutil.copy("tests/test.mp3", temp_input)
+
+            # Add ReplayGain tags to the input file
+            mp3 = MP3(str(temp_input), ID3=ID3)
+            if not mp3.tags:
+                mp3.add_tags()
+            mp3.tags.add(TXXX(desc="REPLAYGAIN_TRACK_GAIN", text=["-5.00 dB"]))
+            mp3.tags.add(TXXX(desc="REPLAYGAIN_TRACK_PEAK", text=["0.950000"]))
+            mp3.save()
+
+            # Verify tags were added
+            mp3_check = MP3(str(temp_input), ID3=ID3)
+            assert "TXXX:REPLAYGAIN_TRACK_GAIN" in mp3_check.tags
+            assert "TXXX:REPLAYGAIN_TRACK_PEAK" in mp3_check.tags
+
+            # Normalize the file
+            ffmpeg_normalize_call(
+                [str(temp_input), "-o", str(temp_output), "-c:a", "libmp3lame"]
+            )
+
+            # Check that output file exists
+            assert temp_output.exists()
+
+            # Check that ReplayGain tags were stripped from the output
+            mp3_output = MP3(str(temp_output), ID3=ID3)
+            if mp3_output.tags:
+                assert "TXXX:REPLAYGAIN_TRACK_GAIN" not in mp3_output.tags, (
+                    "REPLAYGAIN_TRACK_GAIN tag should be stripped"
+                )
+                assert "TXXX:REPLAYGAIN_TRACK_PEAK" not in mp3_output.tags, (
+                    "REPLAYGAIN_TRACK_PEAK tag should be stripped"
+                )
+        finally:
+            # Clean up temp files even if test fails
+            if temp_input.exists():
+                temp_input.unlink()
+            if temp_output.exists():
+                temp_output.unlink()
+
+    def test_replaygain_tags_stripped_m4a(self, tmp_path):
+        """Test that ReplayGain tags are stripped from M4A files after normalization."""
+        import shutil
+        from mutagen.mp4 import MP4
+
+        temp_input = tmp_path / "test_with_replaygain.m4a"
+        temp_output = tmp_path / "normalized_output.m4a"
+
+        try:
+            # Create a temporary copy of test.m4a with ReplayGain tags
+            shutil.copy("tests/test.m4a", temp_input)
+
+            # Add ReplayGain tags to the input file
+            mp4 = MP4(str(temp_input))
+            if not mp4.tags:
+                mp4.add_tags()
+            mp4.tags["----:com.apple.iTunes:REPLAYGAIN_TRACK_GAIN"] = [b"-5.00 dB"]
+            mp4.tags["----:com.apple.iTunes:REPLAYGAIN_TRACK_PEAK"] = [b"0.950000"]
+            mp4.save()
+
+            # Verify tags were added
+            mp4_check = MP4(str(temp_input))
+            assert "----:com.apple.iTunes:REPLAYGAIN_TRACK_GAIN" in mp4_check.tags
+            assert "----:com.apple.iTunes:REPLAYGAIN_TRACK_PEAK" in mp4_check.tags
+
+            # Normalize the file
+            ffmpeg_normalize_call(
+                [str(temp_input), "-o", str(temp_output), "-c:a", "aac"]
+            )
+
+            # Check that output file exists
+            assert temp_output.exists()
+
+            # Check that ReplayGain tags were stripped from the output
+            mp4_output = MP4(str(temp_output))
+            if mp4_output.tags:
+                assert (
+                    "----:com.apple.iTunes:REPLAYGAIN_TRACK_GAIN" not in mp4_output.tags
+                ), "REPLAYGAIN_TRACK_GAIN tag should be stripped"
+                assert (
+                    "----:com.apple.iTunes:REPLAYGAIN_TRACK_PEAK" not in mp4_output.tags
+                ), "REPLAYGAIN_TRACK_PEAK tag should be stripped"
+        finally:
+            # Clean up temp files even if test fails
+            if temp_input.exists():
+                temp_input.unlink()
+            if temp_output.exists():
+                temp_output.unlink()
+
+    def test_replaygain_tags_stripped_ogg(self, tmp_path):
+        """Test that ReplayGain tags are stripped from OGG files after normalization."""
+        import shutil
+        from mutagen.oggvorbis import OggVorbis
+
+        temp_input = tmp_path / "test_with_replaygain.ogg"
+        temp_output = tmp_path / "normalized_output.ogg"
+
+        try:
+            # Create a temporary copy of test.ogg with ReplayGain tags
+            shutil.copy("tests/test.ogg", temp_input)
+
+            # Add ReplayGain tags to the input file
+            ogg = OggVorbis(str(temp_input))
+            ogg["REPLAYGAIN_TRACK_GAIN"] = ["-5.00 dB"]
+            ogg["REPLAYGAIN_TRACK_PEAK"] = ["0.950000"]
+            ogg.save()
+
+            # Verify tags were added
+            ogg_check = OggVorbis(str(temp_input))
+            assert "REPLAYGAIN_TRACK_GAIN" in ogg_check
+            assert "REPLAYGAIN_TRACK_PEAK" in ogg_check
+
+            # Normalize the file
+            ffmpeg_normalize_call(
+                [str(temp_input), "-o", str(temp_output), "-c:a", "libvorbis"]
+            )
+
+            # Check that output file exists
+            assert temp_output.exists()
+
+            # Check that ReplayGain tags were stripped from the output
+            ogg_output = OggVorbis(str(temp_output))
+            # OGG stores tags in lowercase
+            assert "replaygain_track_gain" not in ogg_output, (
+                "replaygain_track_gain tag should be stripped"
+            )
+            assert "replaygain_track_peak" not in ogg_output, (
+                "replaygain_track_peak tag should be stripped"
+            )
+        finally:
+            # Clean up temp files even if test fails
+            if temp_input.exists():
+                temp_input.unlink()
+            if temp_output.exists():
+                temp_output.unlink()
+
+    def test_replaygain_tags_stripped_opus(self, tmp_path):
+        """Test that R128 tags are stripped from OPUS files after normalization."""
+        import shutil
+        from mutagen.oggopus import OggOpus
+
+        temp_input = tmp_path / "test_with_r128.opus"
+        temp_output = tmp_path / "normalized_output.opus"
+
+        try:
+            # Create a temporary copy of test.opus with R128 tags
+            shutil.copy("tests/test.opus", temp_input)
+
+            # Add R128 tags to the input file (Opus uses R128 instead of REPLAYGAIN)
+            opus = OggOpus(str(temp_input))
+            opus["R128_TRACK_GAIN"] = ["-1280"]  # -5.00 dB * 256
+            opus.save()
+
+            # Verify tags were added
+            opus_check = OggOpus(str(temp_input))
+            assert "R128_TRACK_GAIN" in opus_check
+
+            # Normalize the file
+            ffmpeg_normalize_call(
+                [str(temp_input), "-o", str(temp_output), "-c:a", "libopus"]
+            )
+
+            # Check that output file exists
+            assert temp_output.exists()
+
+            # Check that R128 tags were stripped from the output
+            opus_output = OggOpus(str(temp_output))
+            # OPUS stores tags in lowercase
+            assert "r128_track_gain" not in opus_output, (
+                "r128_track_gain tag should be stripped"
+            )
+        finally:
+            # Clean up temp files even if test fails
+            if temp_input.exists():
+                temp_input.unlink()
+            if temp_output.exists():
+                temp_output.unlink()
+
 
 def test_ffmpeg_env():
     """Verify that ffmpeg_env context manager sets environment correctly."""