ffmpeg-normalize 1.42.0__tar.gz → 1.43.0__tar.gz

{ffmpeg_normalize-1.42.0 → ffmpeg_normalize-1.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffmpeg-normalize
-Version: 1.42.0
+Version: 1.43.0
 Summary: Normalize audio via ffmpeg
 Keywords: ffmpeg,normalize,audio
 Author: Werner Robitza
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Requires-Dist: tqdm>=4.64.1
 Requires-Dist: colorama>=0.4.6 ; sys_platform == 'win32'
 Requires-Dist: ffmpeg-progress-yield>=1.0.1
@@ -29,7 +30,11 @@ Project-URL: Homepage, https://github.com/slhck/ffmpeg-normalize
 Project-URL: Repository, https://github.com/slhck/ffmpeg-normalize
 Description-Content-Type: text/markdown
 
-# ffmpeg-normalize
+<h1 align="center">ffmpeg-normalize</h1>
+
+<p align="center">
+  <img src="icon.png" alt="ffmpeg-normalize logo" width="160" height="160">
+</p>
 
 [![PyPI version](https://img.shields.io/pypi/v/ffmpeg-normalize.svg)](https://pypi.org/project/ffmpeg-normalize)
 [![Docker Image Version](https://img.shields.io/docker/v/slhck/ffmpeg-normalize?sort=semver&label=Docker%20image)](https://hub.docker.com/r/slhck/ffmpeg-normalize)
@@ -50,6 +55,7 @@ This program normalizes media files to a certain loudness level using the EBU R1
 - Peak normalization — Adjust audio to a specific peak level
 - Selective audio stream normalization — Normalize specific audio streams or only default streams
 - Skip files already at target — Avoid re-encoding files already within a threshold of the target level
+- Before/after summary — Print a table of input and output levels and the applied gain for all files with `--print-summary`
 - Self-documenting output — Optionally record the effective encoder settings as an `ENCODER_SETTINGS` tag
 - Video file support — Process video files while preserving video streams
 - Docker support — Run via Docker container

{ffmpeg_normalize-1.42.0 → ffmpeg_normalize-1.43.0}/README.md

@@ -1,4 +1,8 @@
-# ffmpeg-normalize
+<h1 align="center">ffmpeg-normalize</h1>
+
+<p align="center">
+  <img src="icon.png" alt="ffmpeg-normalize logo" width="160" height="160">
+</p>
 
 [![PyPI version](https://img.shields.io/pypi/v/ffmpeg-normalize.svg)](https://pypi.org/project/ffmpeg-normalize)
 [![Docker Image Version](https://img.shields.io/docker/v/slhck/ffmpeg-normalize?sort=semver&label=Docker%20image)](https://hub.docker.com/r/slhck/ffmpeg-normalize)
@@ -19,6 +23,7 @@ This program normalizes media files to a certain loudness level using the EBU R1
 - Peak normalization — Adjust audio to a specific peak level
 - Selective audio stream normalization — Normalize specific audio streams or only default streams
 - Skip files already at target — Avoid re-encoding files already within a threshold of the target level
+- Before/after summary — Print a table of input and output levels and the applied gain for all files with `--print-summary`
 - Self-documenting output — Optionally record the effective encoder settings as an `ENCODER_SETTINGS` tag
 - Video file support — Process video files while preserving video streams
 - Docker support — Run via Docker container

{ffmpeg_normalize-1.42.0 → ffmpeg_normalize-1.43.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ffmpeg-normalize"
-version = "1.42.0"
+version = "1.43.0"
 description = "Normalize audio via ffmpeg"
 readme = "README.md"
 license = "MIT"
@@ -27,6 +27,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
 ]
 requires-python = ">=3.10"
 dependencies = [

{ffmpeg_normalize-1.42.0 → ffmpeg_normalize-1.43.0}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ffmpeg-normalize"
-version = "1.42.0"
+version = "1.43.0"
 description = "Normalize audio via ffmpeg"
 readme = "README.md"
 license = "MIT"
@@ -26,6 +26,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
 ]
 requires-python = ">=3.10"
 dependencies = [

{ffmpeg_normalize-1.42.0 → ffmpeg_normalize-1.43.0}/src/ffmpeg_normalize/__main__.py

@@ -204,6 +204,23 @@ def create_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Print loudness statistics for both passes formatted as JSON to stdout.",
     )
+    group_normalization.add_argument(
+        "--print-summary",
+        action="store_true",
+        help=textwrap.dedent(
+            """\
+        Print a before/after summary table to stderr after processing.
+
+        For each file and audio stream, the table lists the input level, the
+        output level, the output peak, the applied gain, and the status. The
+        level is the integrated loudness for EBU, the RMS level for RMS, and the
+        peak level for peak normalization. Values that are not available are
+        shown as `-`.
+
+        Can be combined with `--print-stats`, which writes JSON to stdout.
+        """
+        ),
+    )
     group_normalization.add_argument(
         "--replaygain",
         action="store_true",
@@ -739,6 +756,7 @@ def main() -> None:
         normalization_type=cli_args.normalization_type,
         target_level=cli_args.target_level,
         print_stats=cli_args.print_stats,
+        print_summary=cli_args.print_summary,
         threshold=cli_args.threshold,
         loudness_range_target=cli_args.loudness_range_target,
         keep_loudness_range_target=cli_args.keep_loudness_range_target,

{ffmpeg_normalize-1.42.0 → ffmpeg_normalize-1.43.0}/src/ffmpeg_normalize/_ffmpeg_normalize.py

@@ -21,7 +21,7 @@ from ._errors import FFmpegNormalizeError
 from ._media_file import MediaFile
 
 if TYPE_CHECKING:
-    from ._streams import LoudnessStatisticsWithMetadata
+    from ._streams import LoudnessStatisticsWithMetadata, SummaryRow
 
 _logger = logging.getLogger(__name__)
 
@@ -60,6 +60,7 @@ class FFmpegNormalize:
         normalization_type (str, optional): Normalization type. Defaults to "ebu".
         target_level (float, optional): Target level. Defaults to -23.0.
         print_stats (bool, optional): Print loudnorm stats. Defaults to False.
+        print_summary (bool, optional): Print a before/after summary table to stderr after processing. Defaults to False.
         threshold (float, optional): When set to a positive value, skip normalization when the input is already within this many dB/LU of the target level, copying it through unchanged. Defaults to 0 (disabled, always normalize).
         loudness_range_target (float, optional): Loudness range target. Defaults to 7.0.
         keep_loudness_range_target (bool, optional): Keep loudness range target. Defaults to False.
@@ -108,6 +109,7 @@ class FFmpegNormalize:
         "normalization_type": "ebu",
         "target_level": -23.0,
         "print_stats": False,
+        "print_summary": False,
         "threshold": 0.0,
         "loudness_range_target": 7.0,
         "keep_loudness_range_target": False,
@@ -153,6 +155,7 @@ class FFmpegNormalize:
         normalization_type: Literal["ebu", "rms", "peak"] = "ebu",
         target_level: float = -23.0,
         print_stats: bool = False,
+        print_summary: bool = False,
         threshold: float = 0.0,
         loudness_range_target: float = 7.0,
         keep_loudness_range_target: bool = False,
@@ -212,6 +215,7 @@ class FFmpegNormalize:
             self.target_level = check_range(target_level, -99, 0, name="target_level")
 
         self.print_stats = print_stats
+        self.print_summary = print_summary
 
         self.threshold = check_range(threshold, 0, 99, name="threshold")
 
@@ -555,3 +559,97 @@ class FFmpegNormalize:
                 indent=4,
             )
             print()
+
+        if self.print_summary:
+            print(self.format_summary(), file=sys.stderr)
+
+    def get_summary(self) -> list[SummaryRow]:
+        """
+        Return the before/after summary for all audio streams of all files.
+
+        Each entry contains the input level, output level, output peak and the
+        applied gain in dB. The level is the integrated loudness for EBU, the
+        RMS level for RMS, and the peak level for peak normalization. The
+        output peak is the true peak for EBU and the sample peak otherwise.
+        Values that are not available are None.
+
+        Returns:
+            list[SummaryRow]: One summary entry per audio stream
+        """
+        return list(
+            chain.from_iterable(
+                media_file.get_summary() for media_file in self.media_files
+            )
+        )
+
+    def format_summary(self) -> str:
+        """
+        Return the before/after summary as a human-readable table.
+
+        Returns:
+            str: The formatted table, including a header line with the target
+        """
+        if self.normalization_type == "ebu":
+            header = (
+                f"EBU R128 normalization, target: {self.target_level:.1f} LUFS, "
+                f"true peak: {self.true_peak:.1f} dBTP"
+            )
+            if self.dynamic:
+                header += ", dynamic mode"
+            columns = ["Input (LUFS)", "Output (LUFS)", "True peak (dBTP)", "Gain (dB)"]
+        elif self.normalization_type == "rms":
+            header = f"RMS normalization, target: {self.target_level:.1f} dBFS"
+            columns = [
+                "Input RMS (dBFS)",
+                "Output RMS (dBFS)",
+                "Peak (dBFS)",
+                "Gain (dB)",
+            ]
+        else:
+            header = f"Peak normalization, target: {self.target_level:.1f} dBFS"
+            columns = ["Input peak (dBFS)", "Output peak (dBFS)", "Gain (dB)"]
+
+        if self.batch:
+            header += ", batch mode (relative loudness preserved)"
+        if self.dry_run:
+            header += ", dry run"
+
+        rows = self.get_summary()
+        if not rows:
+            return f"Summary ({header}): no files processed"
+
+        def fmt(value: float | None, signed: bool = False) -> str:
+            if value is None:
+                return "-"
+            return f"{value:+.1f}" if signed else f"{value:.1f}"
+
+        table: list[list[str]] = []
+        for row in rows:
+            values = [fmt(row["input_level"]), fmt(row["output_level"])]
+            if self.normalization_type != "peak":
+                values.append(fmt(row["output_peak"]))
+            values.append(fmt(row["gain"], signed=True))
+            table.append(
+                [row["input_file"], str(row["stream_id"]), *values, row["status"]]
+            )
+
+        headings = ["File", "Stream", *columns, "Status"]
+        widths = [
+            max(len(headings[i]), *(len(line[i]) for line in table))
+            for i in range(len(headings))
+        ]
+
+        def fmt_line(cells: list[str]) -> str:
+            # Left-align the file name and status, right-align everything else
+            parts = [
+                cell.ljust(widths[i])
+                if i in (0, len(cells) - 1)
+                else cell.rjust(widths[i])
+                for i, cell in enumerate(cells)
+            ]
+            return "  ".join(parts).rstrip()
+
+        lines = [f"Summary ({header}):", "", fmt_line(headings)]
+        lines.append(fmt_line(["-" * w for w in widths]))
+        lines.extend(fmt_line(line) for line in table)
+        return "\n".join(lines)

{ffmpeg_normalize-1.42.0 → ffmpeg_normalize-1.43.0}/src/ffmpeg_normalize/_media_file.py

@@ -27,6 +27,7 @@ from ._streams import (
     AudioStream,
     LoudnessStatisticsWithMetadata,
     SubtitleStream,
+    SummaryRow,
     VideoStream,
 )
 
@@ -811,6 +812,7 @@ class MediaFile:
                 f"Stream {audio_stream.stream_id} had measured input loudness lower than target, skipping normalization."
             )
             normalization_filter = "acopy"
+            audio_stream.applied_gain = 0.0
         else:
             if self.ffmpeg_normalize.normalization_type == "ebu":
                 normalization_filter = audio_stream.get_second_pass_opts_ebu(
@@ -1223,3 +1225,23 @@ class MediaFile:
         return (
             audio_stream.get_stats() for audio_stream in self.streams["audio"].values()
         )
+
+    def get_summary(self) -> list[SummaryRow]:
+        """
+        Return the before/after summary for each analyzed audio stream.
+
+        Streams without any measurement (e.g. streams not selected for
+        normalization) are left out, unless the file failed to process.
+
+        Returns:
+            list[SummaryRow]: One summary entry per audio stream
+        """
+        rows = [
+            audio_stream.get_summary()
+            for audio_stream in self.streams["audio"].values()
+        ]
+        return [
+            row
+            for row in rows
+            if row["status"] == "error" or row["input_level"] is not None
+        ]

{ffmpeg_normalize-1.42.0 → ffmpeg_normalize-1.43.0}/src/ffmpeg_normalize/_streams.py

@@ -59,6 +59,17 @@ class LoudnessStatistics(TypedDict):
     max: float | None
 
 
+class SummaryRow(TypedDict):
+    input_file: str
+    output_file: str
+    stream_id: int
+    status: str
+    input_level: float | None
+    output_level: float | None
+    output_peak: float | None
+    gain: float | None
+
+
 class _OptionalStatisticsMetadata(TypedDict, total=False):
     error: str
 
@@ -150,6 +161,11 @@ class AudioStream(MediaStream):
             "max": None,
         }
 
+        # Gain in dB applied by the second pass volume filter (peak/RMS), or 0
+        # when normalization is skipped for this stream (e.g. with lower_only).
+        # Stays None for EBU, where the gain is derived from the second pass stats.
+        self.applied_gain: float | None = None
+
         self.sample_rate = sample_rate
         self.bit_depth = bit_depth
 
@@ -208,6 +224,78 @@ class AudioStream(MediaStream):
             stats["error"] = self.media_file.error
         return stats
 
+    def get_summary(self) -> SummaryRow:
+        """
+        Return the before/after levels and the applied gain for the stream.
+
+        For EBU, the input level and true peak come from the first pass (or the
+        second pass in dynamic mode), and the output level, output true peak and
+        gain come from the second pass. For RMS and peak, the input level is the
+        measured RMS or peak level, and the output values are computed from the
+        applied gain. Values that are not available are None.
+
+        Returns:
+            dict: A dictionary with the summary values.
+        """
+        normalization_type = self.ffmpeg_normalize.normalization_type
+        status = self.media_file.status
+
+        input_level: float | None = None
+        input_peak: float | None = None
+        output_level: float | None = None
+        output_peak: float | None = None
+        gain: float | None = None
+
+        if normalization_type == "ebu":
+            pass1 = self.loudness_statistics["ebu_pass1"]
+            pass2 = self.loudness_statistics["ebu_pass2"]
+            input_stats = pass1 if pass1 is not None else pass2
+            if input_stats is not None:
+                input_level = float(input_stats["input_i"])
+                input_peak = float(input_stats["input_tp"])
+            if pass2 is not None:
+                output_level = float(pass2["output_i"])
+                output_peak = float(pass2["output_tp"])
+                # Input and output of the same pass, as the first pass input
+                # measurement can differ slightly from the second pass one
+                gain = output_level - float(pass2["input_i"])
+        else:
+            measured = (
+                self.loudness_statistics["mean"]
+                if normalization_type == "rms"
+                else self.loudness_statistics["max"]
+            )
+            if measured is not None:
+                input_level = float(measured)
+            if self.loudness_statistics["max"] is not None:
+                input_peak = float(self.loudness_statistics["max"])
+
+        applied_gain = 0.0 if status == "skipped" else self.applied_gain
+        if (
+            status != "error"
+            and output_level is None
+            and applied_gain is not None
+            and input_level is not None
+        ):
+            gain = applied_gain
+            output_level = input_level + applied_gain
+            if input_peak is not None:
+                output_peak = input_peak + applied_gain
+
+        if status == "error":
+            output_level = output_peak = gain = None
+
+        return {
+            "input_file": self.media_file.input_file,
+            "output_file": self.media_file.output_file,
+            "stream_id": self.stream_id,
+            "status": status,
+            "input_level": input_level,
+            "output_level": output_level,
+            "output_peak": output_peak,
+            "gain": gain,
+        }
+
     def set_second_pass_stats(self, stats: EbuLoudnessStatistics) -> None:
         """
         Set the EBU loudness statistics for the second pass.
@@ -815,6 +903,8 @@ class AudioStream(MediaStream):
             f"Adjusting stream {self.stream_id} by {adjustment} dB to reach {target_level}"
         )
 
+        self.applied_gain = float(adjustment)
+
         clip_amount = self.loudness_statistics["max"] + adjustment
         if clip_amount > 0:
             _logger.warning(