add replaygain support

Author: slhck

README.md

@@ -294,6 +294,12 @@ For more information on the options (`[options]`) available, run `ffmpeg-normali
 
 - `-p, --print-stats`: Print loudness statistics for both passes formatted as JSON to stdout.
 
+- `--replaygain`: 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.
+
+    Only works with EBU normalization, and only with .mp3, .mp4/.m4a, .ogg, .opus for now.
+
 ### EBU R128 Normalization
 
 - `-lrt LOUDNESS_RANGE_TARGET, --loudness-range-target LOUDNESS_RANGE_TARGET`: EBU Loudness Range Target in LUFS (default: 7.0).
@@ -488,9 +494,9 @@ If you have to use an outdated ffmpeg version, you can only use `rms` or `peak`
 
 ### Should I use this to normalize my music collection?
 
-Generally, no.
+You can use the `--replaygain` option to write ReplayGain tags to the original file without normalizing. This makes most music players understand the loudness difference and adjust the volume accordingly.
 
-When you run `ffmpeg-normalize` and re-encode files with MP3 or AAC, you will inevitably introduce [generation loss](https://en.wikipedia.org/wiki/Generation_loss). Therefore, I do not recommend running this on your precious music collection, unless you have a backup of the originals or accept potential quality reduction. If you just want to normalize the subjective volume of the files without changing the actual content, consider using [MP3Gain](http://mp3gain.sourceforge.net/) and [aacgain](http://aacgain.altosdesign.com/).
+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.
 
 ### Why are my output files MKV?
 

ffmpeg_normalize/__main__.py

@@ -159,6 +159,17 @@ def create_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Print loudness statistics for both passes formatted as JSON to stdout.",
     )
+    group_normalization.add_argument(
+        "--replaygain",
+        action="store_true",
+        help=textwrap.dedent(
+            """\
+        Write ReplayGain tags to the original file without normalizing.
+        This mode will overwrite the input file and ignore other options.
+        Only works with EBU normalization, and only with .mp3, .mp4/.m4a, .ogg, .opus for now.
+        """
+        ),
+    )
 
     # group_normalization.add_argument(
     #     '--threshold',
@@ -562,6 +573,7 @@ def _split_options(opts: str) -> list[str]:
         extension=cli_args.extension,
         dry_run=cli_args.dry_run,
         progress=cli_args.progress,
+        replaygain=cli_args.replaygain,
     )
 
     if cli_args.output and len(cli_args.input) > len(cli_args.output):
@@ -595,7 +607,11 @@ def _split_options(opts: str) -> list[str]:
                 )
                 os.makedirs(cli_args.output_folder, exist_ok=True)
 
-        if os.path.exists(output_file) and not cli_args.force:
+        if (
+            os.path.exists(output_file)
+            and not cli_args.force
+            and not cli_args.replaygain
+        ):
             _logger.warning(
                 f"Output file '{output_file}' already exists, skipping. Use -f to force overwriting."
             )

ffmpeg_normalize/_ffmpeg_normalize.py

@@ -83,6 +83,7 @@ class FFmpegNormalize:
         dry_run (bool, optional): Dry run. Defaults to False.
         debug (bool, optional): Debug. Defaults to False.
         progress (bool, optional): Progress. Defaults to False.
+        replaygain (bool, optional): Write ReplayGain tags without normalizing. Defaults to False.
 
     Raises:
         FFmpegNormalizeError: If the ffmpeg executable is not found or does not support the loudnorm filter.
@@ -122,6 +123,7 @@ def __init__(
         dry_run: bool = False,
         debug: bool = False,
         progress: bool = False,
+        replaygain: bool = False,
     ):
         self.ffmpeg_exe = get_ffmpeg_exe()
         self.has_loudnorm_capabilities = ffmpeg_has_loudnorm()
@@ -203,6 +205,7 @@ def __init__(
         self.dry_run = dry_run
         self.debug = debug
         self.progress = progress
+        self.replaygain = replaygain
 
         if (
             self.audio_codec is None or "pcm" in self.audio_codec
@@ -212,6 +215,12 @@ def __init__(
                 "Please choose a suitable audio codec with the -c:a option."
             )
 
+        # replaygain only works for EBU for now
+        if self.replaygain and self.normalization_type != "ebu":
+            raise FFmpegNormalizeError(
+                "ReplayGain only works for EBU normalization type for now."
+            )
+
         self.stats: list[LoudnessStatisticsWithMetadata] = []
         self.media_files: list[MediaFile] = []
         self.file_count = 0
@@ -263,8 +272,14 @@ def run_normalization(self) -> None:
                     # raise the error so the program will exit
                     raise e
 
-            _logger.info(f"Normalized file written to {media_file.output_file}")
-
         if self.print_stats:
-            json.dump(list(chain.from_iterable(media_file.get_stats() for media_file in self.media_files)), sys.stdout, indent=4)
+            json.dump(
+                list(
+                    chain.from_iterable(
+                        media_file.get_stats() for media_file in self.media_files
+                    )
+                ),
+                sys.stdout,
+                indent=4,
+            )
             print()

ffmpeg_normalize/_media_file.py

@@ -8,6 +8,11 @@
 from tempfile import mkdtemp
 from typing import TYPE_CHECKING, Iterable, Iterator, Literal, TypedDict
 
+from mutagen.id3 import ID3, TXXX
+from mutagen.mp3 import MP3
+from mutagen.mp4 import MP4
+from mutagen.oggopus import OggOpus
+from mutagen.oggvorbis import OggVorbis
 from tqdm import tqdm
 
 from ._cmd_utils import DUR_REGEX, CommandRunner
@@ -198,6 +203,11 @@ def run_normalization(self) -> None:
         # run the first pass to get loudness stats
         self._first_pass()
 
+        # shortcut to apply replaygain
+        if self.ffmpeg_normalize.replaygain:
+            self._run_replaygain()
+            return
+
         # run the second pass as a whole
         if self.ffmpeg_normalize.progress:
             with tqdm(
@@ -212,6 +222,103 @@ def run_normalization(self) -> None:
             for _ in self._second_pass():
                 pass
 
+        _logger.info(f"Normalized file written to {self.output_file}")
+
+    def _run_replaygain(self) -> None:
+        """
+        Run the replaygain process for this file.
+        """
+        _logger.debug(f"Running replaygain for {self.input_file}")
+
+        # get the audio streams
+        audio_streams = list(self.streams["audio"].values())
+
+        # get the loudnorm stats from the first pass
+        loudnorm_stats = audio_streams[0].loudness_statistics["ebu_pass1"]
+
+        if loudnorm_stats is None:
+            _logger.error("no loudnorm stats available in first pass stats!")
+            return
+
+        # apply the replaygain tag from the first audio stream (to all audio streams)
+        if len(audio_streams) > 1:
+            _logger.warning(
+                f"Your input file has {len(audio_streams)} audio streams. "
+                "Only the first audio stream's replaygain tag will be applied. "
+                "All audio streams will receive the same tag."
+            )
+
+        target_level = self.ffmpeg_normalize.target_level
+        input_i = loudnorm_stats["input_i"]  # Integrated loudness
+        input_tp = loudnorm_stats["input_tp"]  # True peak
+
+        if input_i is None or input_tp is None:
+            _logger.error("no input_i or input_tp available in first pass stats!")
+            return
+
+        track_gain = -(input_i - target_level)  # dB
+        track_peak = 10 ** (input_tp / 20)  # linear scale
+
+        _logger.debug(f"Track gain: {track_gain} dB")
+        _logger.debug(f"Track peak: {track_peak}")
+
+        self._write_replaygain_tags(track_gain, track_peak)
+
+    def _write_replaygain_tags(self, track_gain: float, track_peak: float) -> None:
+        """
+        Write the replaygain tags to the input file.
+
+        This is based on the code from bohning/usdb_syncer, licensed under the MIT license.
+        See: https://github.com/bohning/usdb_syncer/blob/2fa638c4f487dffe9f5364f91e156ba54cb20233/src/usdb_syncer/resource_dl.py
+        """
+        _logger.debug(f"Writing ReplayGain tags to {self.input_file}")
+
+        input_file_ext = os.path.splitext(self.input_file)[1]
+        if input_file_ext == ".mp3":
+            mp3 = MP3(self.input_file, ID3=ID3)
+            if not mp3.tags:
+                return
+            mp3.tags.add(
+                TXXX(desc="REPLAYGAIN_TRACK_GAIN", text=[f"{track_gain:.2f} dB"])
+            )
+            mp3.tags.add(TXXX(desc="REPLAYGAIN_TRACK_PEAK", text=[f"{track_peak:.6f}"]))
+            mp3.save()
+        elif input_file_ext in [".mp4", ".m4a", ".m4v", ".mov"]:
+            mp4 = MP4(self.input_file)
+            if not mp4.tags:
+                mp4.add_tags()
+            if not mp4.tags:
+                return
+            mp4.tags["----:com.apple.iTunes:REPLAYGAIN_TRACK_GAIN"] = [
+                f"{track_gain:.2f} dB".encode()
+            ]
+            mp4.tags["----:com.apple.iTunes:REPLAYGAIN_TRACK_PEAK"] = [
+                f"{track_peak:.6f}".encode()
+            ]
+            mp4.save()
+        elif input_file_ext == ".ogg":
+            ogg = OggVorbis(self.input_file)
+            ogg["REPLAYGAIN_TRACK_GAIN"] = [f"{track_gain:.2f} dB"]
+            ogg["REPLAYGAIN_TRACK_PEAK"] = [f"{track_peak:.6f}"]
+            ogg.save()
+        elif input_file_ext == ".opus":
+            opus = OggOpus(self.input_file)
+            # See https://datatracker.ietf.org/doc/html/rfc7845#section-5.2.1
+            opus["R128_TRACK_GAIN"] = [str(round(256 * track_gain))]
+            opus.save()
+        else:
+            _logger.error(
+                f"Unsupported input file extension: {input_file_ext} for writing replaygain tags."
+                "Only .mp3, .mp4/.m4a, .ogg, .opus are supported."
+                "If you think this should support more formats, please let me know at "
+                "https://github.com/slhck/ffmpeg-normalize/issues"
+            )
+            return
+
+        _logger.info(
+            f"Successfully wrote replaygain tags to input file {self.input_file}"
+        )
+
     def _can_write_output_video(self) -> bool:
         """
         Determine whether the output file can contain video at all.

requirements.txt

@@ -2,3 +2,4 @@ tqdm>=4.64.1
 colorama>=0.4.6
 ffmpeg-progress-yield>=0.11.0
 colorlog==6.7.0
+mutagen>=1.47.0

test/test.mp3

@@ -475,3 +475,15 @@ def test_audio_channels(self):
         assert os.path.isfile("normalized/test2.wav")
         stream_info = _get_stream_info("normalized/test2.wav")[0]
         assert stream_info["channels"] == 2
+
+    def test_replaygain(self):
+        for file in [
+            "test/test.mp4",
+            "test/test.mp3",
+            "test/test.ogg",
+            "test/test.opus",
+        ]:
+            original_mtime = os.path.getmtime(file)
+            ffmpeg_normalize_call([file, "--replaygain"])
+            assert os.path.isfile(file)
+            assert os.path.getmtime(file) > original_mtime