ffmpeg-normalize 1.43.1__tar.gz → 1.44.0__tar.gz

{ffmpeg_normalize-1.43.1 → ffmpeg_normalize-1.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffmpeg-normalize
-Version: 1.43.1
+Version: 1.44.0
 Summary: Normalize audio via ffmpeg
 Keywords: ffmpeg,normalize,audio
 Author: Werner Robitza

{ffmpeg_normalize-1.43.1 → ffmpeg_normalize-1.44.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ffmpeg-normalize"
-version = "1.43.1"
+version = "1.44.0"
 description = "Normalize audio via ffmpeg"
 readme = "README.md"
 license = "MIT"

{ffmpeg_normalize-1.43.1 → ffmpeg_normalize-1.44.0}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ffmpeg-normalize"
-version = "1.43.1"
+version = "1.44.0"
 description = "Normalize audio via ffmpeg"
 readme = "README.md"
 license = "MIT"

{ffmpeg_normalize-1.43.1 → ffmpeg_normalize-1.44.0}/src/ffmpeg_normalize/__main__.py

@@ -218,12 +218,31 @@ def create_parser(suppress_defaults: bool = False) -> argparse.ArgumentParser:
         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 `-`.
+        shown as `-`. Output values are filter statistics (EBU) or calculated
+        from gain (RMS/peak). Use --verify for separate encoded-output measurements.
 
         Can be combined with `--print-stats`, which writes JSON to stdout.
         """
         ),
     )
+    group_normalization.add_argument(
+        "--verify",
+        action="store_true",
+        help="Measure the encoded output and fail if level or peak checks exceed tolerance. "
+        "Skipped during dry runs; incompatible with --replaygain.",
+    )
+    group_normalization.add_argument(
+        "--verify-loudness-tolerance",
+        type=float,
+        default=FFmpegNormalize.DEFAULTS["verify_loudness_tolerance"],
+        help="Allowed deviation from the effective output level in dB/LU (default: 0.5).",
+    )
+    group_normalization.add_argument(
+        "--verify-peak-tolerance",
+        type=float,
+        default=FFmpegNormalize.DEFAULTS["verify_peak_tolerance"],
+        help="Allowed overshoot above the output peak ceiling in dB (default: 0.1).",
+    )
     group_normalization.add_argument(
         "--replaygain",
         action="store_true",
@@ -763,48 +782,54 @@ def main() -> None:
     if cli_args.audio_default_only and cli_args.audio_streams:
         error("Cannot use both --audio-default-only and --audio-streams together.")
 
-    ffmpeg_normalize = FFmpegNormalize(
-        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,
-        keep_lra_above_loudness_range_target=cli_args.keep_lra_above_loudness_range_target,
-        true_peak=cli_args.true_peak,
-        offset=cli_args.offset,
-        lower_only=cli_args.lower_only,
-        auto_lower_loudness_target=cli_args.auto_lower_loudness_target,
-        dual_mono=cli_args.dual_mono,
-        dynamic=cli_args.dynamic,
-        audio_codec=cli_args.audio_codec,
-        audio_bitrate=cli_args.audio_bitrate,
-        sample_rate=cli_args.sample_rate,
-        audio_channels=cli_args.audio_channels,
-        keep_original_audio=cli_args.keep_original_audio,
-        pre_filter=cli_args.pre_filter,
-        post_filter=cli_args.post_filter,
-        video_codec=cli_args.video_codec,
-        video_disable=cli_args.video_disable,
-        subtitle_disable=cli_args.subtitle_disable,
-        metadata_disable=cli_args.metadata_disable,
-        chapters_disable=cli_args.chapters_disable,
-        write_encoder_settings=cli_args.write_encoder_settings,
-        extra_input_options=extra_input_options,
-        extra_output_options=extra_output_options,
-        output_format=cli_args.output_format,
-        extension=cli_args.extension,
-        dry_run=cli_args.dry_run,
-        progress=cli_args.progress,
-        replaygain=cli_args.replaygain,
-        batch=cli_args.batch,
-        audio_streams=audio_streams,
-        audio_default_only=cli_args.audio_default_only,
-        keep_other_audio=cli_args.keep_other_audio,
-        keep_mtime=cli_args.keep_mtime,
-        keep_bit_depth=cli_args.keep_bit_depth,
-    )
+    try:
+        ffmpeg_normalize = FFmpegNormalize(
+            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,
+            keep_lra_above_loudness_range_target=cli_args.keep_lra_above_loudness_range_target,
+            true_peak=cli_args.true_peak,
+            offset=cli_args.offset,
+            lower_only=cli_args.lower_only,
+            auto_lower_loudness_target=cli_args.auto_lower_loudness_target,
+            dual_mono=cli_args.dual_mono,
+            dynamic=cli_args.dynamic,
+            audio_codec=cli_args.audio_codec,
+            audio_bitrate=cli_args.audio_bitrate,
+            sample_rate=cli_args.sample_rate,
+            audio_channels=cli_args.audio_channels,
+            keep_original_audio=cli_args.keep_original_audio,
+            pre_filter=cli_args.pre_filter,
+            post_filter=cli_args.post_filter,
+            video_codec=cli_args.video_codec,
+            video_disable=cli_args.video_disable,
+            subtitle_disable=cli_args.subtitle_disable,
+            metadata_disable=cli_args.metadata_disable,
+            chapters_disable=cli_args.chapters_disable,
+            write_encoder_settings=cli_args.write_encoder_settings,
+            extra_input_options=extra_input_options,
+            extra_output_options=extra_output_options,
+            output_format=cli_args.output_format,
+            extension=cli_args.extension,
+            dry_run=cli_args.dry_run,
+            progress=cli_args.progress,
+            replaygain=cli_args.replaygain,
+            batch=cli_args.batch,
+            audio_streams=audio_streams,
+            audio_default_only=cli_args.audio_default_only,
+            keep_other_audio=cli_args.keep_other_audio,
+            keep_mtime=cli_args.keep_mtime,
+            keep_bit_depth=cli_args.keep_bit_depth,
+            verify=cli_args.verify,
+            verify_loudness_tolerance=cli_args.verify_loudness_tolerance,
+            verify_peak_tolerance=cli_args.verify_peak_tolerance,
+        )
+    except FFmpegNormalizeError as e:
+        error(e)
 
     if cli_args.output and len(cli_args.input) > len(cli_args.output):
         _logger.warning(

{ffmpeg_normalize-1.43.1 → ffmpeg_normalize-1.44.0}/src/ffmpeg_normalize/_cmd_utils.py

@@ -179,7 +179,11 @@ class CommandRunner:
         stderr = stderr_bytes.decode("utf8", errors="replace")
 
         if p.returncode != 0:
-            raise RuntimeError(f"Error running command {shlex.join(cmd)}: {stderr}")
+            reason = (
+                stderr.strip()
+                or f"exited with status {p.returncode} without diagnostics"
+            )
+            raise RuntimeError(f"Error running command {shlex.join(cmd)}: {reason}")
 
         self.output = stdout + stderr
         return self
@@ -219,7 +223,9 @@ def get_ffmpeg_exe() -> str:
     if ff_path := os.getenv("FFMPEG_PATH"):
         if os.sep in ff_path:
             if not os.path.isfile(ff_path):
-                raise FFmpegNormalizeError(f"No file exists at {ff_path}")
+                raise FFmpegNormalizeError(
+                    f"ffmpeg executable does not exist: {ff_path}"
+                )
 
             return ff_path
 
@@ -392,7 +398,21 @@ def ffmpeg_has_loudnorm() -> bool:
     Returns:
         bool: True if loudnorm is supported, False otherwise
     """
-    output = CommandRunner().run_command([get_ffmpeg_exe(), "-filters"]).get_output()
+    executable = get_ffmpeg_exe()
+    command = [executable, "-filters"]
+    try:
+        output = CommandRunner().run_command(command).get_output()
+    except (OSError, RuntimeError) as error:
+        _logger.debug("ffmpeg startup failed", exc_info=True)
+        reason = (
+            str(error)
+            .removeprefix(f"Error running command {shlex.join(command)}: ")
+            .strip()
+        )
+        reason = " ".join(reason.splitlines()[:2])
+        raise FFmpegNormalizeError(
+            f"Could not start ffmpeg '{executable}': {reason}"
+        ) from error
     supports_loudnorm = "loudnorm" in output
     if not supports_loudnorm:
         _logger.error(

{ffmpeg_normalize-1.43.1 → ffmpeg_normalize-1.44.0}/src/ffmpeg_normalize/_ffmpeg_normalize.py

@@ -99,6 +99,9 @@ class FFmpegNormalize:
         keep_other_audio (bool, optional): Keep non-selected audio streams in output (copy without normalization). Defaults to False.
         keep_mtime (bool, optional): Copy the input file's modification time to the output file. Defaults to False.
         keep_bit_depth (bool, optional): Carry the detected input bit depth through to the output encoder. Defaults to True.
+        verify (bool, optional): Measure the encoded output and check its effective target and peak ceiling. Defaults to False. Not available with ReplayGain; skipped during dry runs.
+        verify_loudness_tolerance (float, optional): Allowed level deviation in dB/LU. Defaults to 0.5.
+        verify_peak_tolerance (float, optional): Allowed peak overshoot in dB. Defaults to 0.1.
 
     Raises:
         FFmpegNormalizeError: If the ffmpeg executable is not found or does not support the loudnorm filter.
@@ -149,6 +152,9 @@ class FFmpegNormalize:
         "keep_other_audio": False,
         "keep_mtime": False,
         "keep_bit_depth": True,
+        "verify": False,
+        "verify_loudness_tolerance": 0.5,
+        "verify_peak_tolerance": 0.1,
     }
 
     def __init__(
@@ -194,6 +200,9 @@ class FFmpegNormalize:
         keep_other_audio: bool = False,
         keep_mtime: bool = False,
         keep_bit_depth: bool = True,
+        verify: bool = False,
+        verify_loudness_tolerance: float = 0.5,
+        verify_peak_tolerance: float = 0.1,
     ):
         self.ffmpeg_exe = get_ffmpeg_exe()
         self.has_loudnorm_capabilities = ffmpeg_has_loudnorm()
@@ -293,6 +302,20 @@ class FFmpegNormalize:
 
         self.keep_mtime = keep_mtime
         self.keep_bit_depth = keep_bit_depth
+        self.verify = verify
+        self.verify_loudness_tolerance = check_range(
+            verify_loudness_tolerance, 0, 99, name="verify_loudness_tolerance"
+        )
+        self.verify_peak_tolerance = check_range(
+            verify_peak_tolerance, 0, 99, name="verify_peak_tolerance"
+        )
+        if not all(
+            math.isfinite(value)
+            for value in (self.verify_loudness_tolerance, self.verify_peak_tolerance)
+        ):
+            raise FFmpegNormalizeError("Verification tolerances must be finite")
+        if verify and replaygain:
+            raise FFmpegNormalizeError("--verify cannot be combined with --replaygain")
 
         if self.output_format in PCM_INCOMPATIBLE_FORMATS:
             if self.audio_codec is not None and "pcm" in self.audio_codec:
@@ -508,6 +531,17 @@ class FFmpegNormalize:
         In non-batch mode, each file is processed completely (both passes) before
         moving to the next file.
         """
+        if (
+            self.verify
+            and not self.dry_run
+            and any(
+                os.path.realpath(file.output_file) == os.path.realpath(os.devnull)
+                for file in self.media_files
+            )
+        ):
+            raise FFmpegNormalizeError(
+                "--verify requires an output file, not the null device"
+            )
         if not self.replaygain:
             self.validate_output_files(
                 [media_file.input_file for media_file in self.media_files],
@@ -591,6 +625,8 @@ class FFmpegNormalize:
 
                 try:
                     media_file.run_normalization(batch_reference=batch_reference)
+                    if self.verify and not self.dry_run:
+                        media_file.verify_output()
                 except Exception as e:
                     media_file.status = "error"
                     media_file.error = str(e)
@@ -609,6 +645,8 @@ class FFmpegNormalize:
 
                 try:
                     media_file.run_normalization()
+                    if self.verify and not self.dry_run:
+                        media_file.verify_output()
                 except Exception as e:
                     media_file.status = "error"
                     media_file.error = str(e)
@@ -719,4 +757,23 @@ class FFmpegNormalize:
         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)
+        lines.append(
+            "\nOutput values above: loudnorm filter statistics for EBU; "
+            "calculated from applied gain for RMS/peak; input levels for skipped files."
+        )
+        verified = [row for row in rows if "verification" in row]
+        if verified:
+            level_unit = "LUFS" if self.normalization_type == "ebu" else "dBFS"
+            peak_unit = "dBTP" if self.normalization_type == "ebu" else "dBFS"
+            lines.append("\nEncoded-output verification (measured after encoding):")
+            for row in verified:
+                result = row["verification"]
+                outcome = "passed" if result["passed"] else "FAILED"
+                lines.append(
+                    f"{row['output_file']} stream {result['output_stream_id']}: "
+                    f"level {fmt(result['output_level'])} {level_unit}, "
+                    f"peak {fmt(result['output_peak'])} {peak_unit}, {outcome}"
+                )
+        elif self.verify and self.dry_run:
+            lines.append("\nEncoded-output verification skipped: dry run.")
         return "\n".join(lines)

{ffmpeg_normalize-1.43.1 → ffmpeg_normalize-1.44.0}/src/ffmpeg_normalize/_media_file.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import logging
+import math
+from copy import copy
 import os
 import re
 import shlex
@@ -29,6 +31,7 @@ from ._streams import (
     SubtitleStream,
     SummaryRow,
     VideoStream,
+    VerificationResult,
 )
 
 if TYPE_CHECKING:
@@ -383,6 +386,108 @@ class MediaFile:
                 self._apply_input_timestamps()
             _logger.info(f"Normalized file written to {self.output_file}")
 
+    def verify_output(self) -> None:
+        """Verify encoded audio, restoring requested timestamps after reading it."""
+        try:
+            self._verify_output()
+        finally:
+            if self.ffmpeg_normalize.keep_mtime:
+                self._apply_input_timestamps()
+
+    def _verify_output(self) -> None:
+        """Measure encoded audio without reapplying filters or input options.
+
+        Only normalized streams are checked. They precede passthrough and
+        original audio in encoded outputs; skipped files retain input indices.
+        Verification keeps the encoded file even if a check fails.
+        """
+        config = copy(self.ffmpeg_normalize)
+        config.pre_filter = config.post_filter = None
+        config.extra_input_options = None
+        config.audio_channels = None
+        measured_file = MediaFile(config, self.output_file, os.devnull)
+        selected = self._get_streams_to_normalize()
+        output_streams = list(measured_file.streams["audio"].values())
+        if self.status == "skipped":
+            output_streams = [
+                measured_file.streams["audio"][stream.stream_id] for stream in selected
+            ]
+        if not selected or len(output_streams) < len(selected):
+            raise FFmpegNormalizeError(
+                "Cannot verify output: selected audio streams are missing"
+            )
+
+        failures: list[str] = []
+        for source, measured in zip(selected, output_streams):
+            summary = source.get_summary()
+            expected = summary["output_level"]
+            if config.normalization_type == "ebu":
+                for _ in measured.parse_loudnorm_stats():
+                    pass
+                stats = measured.loudness_statistics["ebu_pass1"]
+                if stats is None:
+                    raise FFmpegNormalizeError(
+                        "Cannot verify output: loudness measurement is missing"
+                    )
+                level, peak = float(stats["input_i"]), float(stats["input_tp"])
+                if self.status != "skipped":
+                    expected = source.verification_target_level
+                    if expected is None:
+                        expected = summary["input_level"]
+                peak_limit = config.true_peak
+            else:
+                for _ in measured.parse_astats():
+                    pass
+                level = measured.loudness_statistics[
+                    "mean" if config.normalization_type == "rms" else "max"
+                ]
+                peak = measured.loudness_statistics["max"]
+                peak_limit = (
+                    config.target_level if config.normalization_type == "peak" else 0.0
+                )
+
+            if self.status == "skipped" and summary["output_peak"] is not None:
+                peak_limit = summary["output_peak"]
+
+            def finite(value: float | None) -> float | None:
+                return value if value is not None and math.isfinite(value) else None
+
+            level, peak, expected = finite(level), finite(peak), finite(expected)
+            errors: list[str] = []
+            if level is None or expected is None:
+                errors.append("output level or expected level is not finite")
+            elif abs(level - expected) > config.verify_loudness_tolerance:
+                errors.append(
+                    f"level {level:.2f} differs from expected {expected:.2f} "
+                    f"by more than {config.verify_loudness_tolerance:g} dB/LU"
+                )
+            if peak is None:
+                errors.append("output peak is not finite")
+            elif peak > peak_limit + config.verify_peak_tolerance:
+                errors.append(
+                    f"peak {peak:.2f} exceeds ceiling {peak_limit:.2f} "
+                    f"plus {config.verify_peak_tolerance:g} dB tolerance"
+                )
+            result: VerificationResult = {
+                "output_stream_id": measured.stream_id,
+                "output_level": level,
+                "output_peak": peak,
+                "expected_level": expected,
+                "peak_limit": peak_limit,
+                "loudness_tolerance": config.verify_loudness_tolerance,
+                "peak_tolerance": config.verify_peak_tolerance,
+                "passed": not errors,
+                "errors": errors,
+            }
+            source.verification = result
+            if errors:
+                failures.append(f"stream {source.stream_id}: " + "; ".join(errors))
+        if failures:
+            raise FFmpegNormalizeError(
+                "Encoded-output verification failed: " + "; ".join(failures)
+            )
+        _logger.info(f"Encoded-output verification passed for {self.output_file}")
+
     def _is_within_threshold(self) -> bool:
         """
         Return whether every stream selected for normalization is already

{ffmpeg_normalize-1.43.1 → ffmpeg_normalize-1.44.0}/src/ffmpeg_normalize/_streams.py

@@ -59,7 +59,23 @@ class LoudnessStatistics(TypedDict):
     max: float | None
 
 
-class SummaryRow(TypedDict):
+class VerificationResult(TypedDict):
+    output_stream_id: int
+    output_level: float | None
+    output_peak: float | None
+    expected_level: float | None
+    peak_limit: float
+    loudness_tolerance: float
+    peak_tolerance: float
+    passed: bool
+    errors: list[str]
+
+
+class _OptionalVerification(TypedDict, total=False):
+    verification: VerificationResult
+
+
+class SummaryRow(_OptionalVerification):
     input_file: str
     output_file: str
     stream_id: int
@@ -68,9 +84,10 @@ class SummaryRow(TypedDict):
     output_level: float | None
     output_peak: float | None
     gain: float | None
+    output_source: str
 
 
-class _OptionalStatisticsMetadata(TypedDict, total=False):
+class _OptionalStatisticsMetadata(_OptionalVerification, total=False):
     error: str
 
 
@@ -165,6 +182,8 @@ class AudioStream(MediaStream):
         # 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.verification_target_level: float | None = None
+        self.verification: VerificationResult | None = None
 
         self.sample_rate = sample_rate
         self.bit_depth = bit_depth
@@ -218,6 +237,8 @@ class AudioStream(MediaStream):
             "max": self.loudness_statistics["max"],
             "status": self.media_file.status,
         }
+        if self.verification is not None:
+            stats["verification"] = self.verification
         # Only present when the file failed to process, per the per-file outcome
         # reporting (status is "error").
         if self.media_file.error is not None:
@@ -232,7 +253,9 @@ class AudioStream(MediaStream):
         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.
+        applied gain. Values that are not available are None. The output_source
+        field labels these values; verification, when present, contains separate
+        measurements of the encoded output and the check results.
 
         Returns:
             dict: A dictionary with the summary values.
@@ -285,7 +308,19 @@ class AudioStream(MediaStream):
         if status == "error":
             output_level = output_peak = gain = None
 
-        return {
+        source = "unavailable"
+        if output_level is not None:
+            source = (
+                "input"
+                if status == "skipped"
+                else (
+                    "filter"
+                    if normalization_type == "ebu"
+                    and self.loudness_statistics["ebu_pass2"] is not None
+                    else "calculated"
+                )
+            )
+        summary: SummaryRow = {
             "input_file": self.media_file.input_file,
             "output_file": self.media_file.output_file,
             "stream_id": self.stream_id,
@@ -294,7 +329,11 @@ class AudioStream(MediaStream):
             "output_level": output_level,
             "output_peak": output_peak,
             "gain": gain,
+            "output_source": source,
         }
+        if self.verification is not None:
+            summary["verification"] = self.verification
+        return summary
 
     def set_second_pass_stats(self, stats: EbuLoudnessStatistics) -> None:
         """
@@ -701,6 +740,7 @@ class AudioStream(MediaStream):
             if self.media_file.ffmpeg_normalize.dual_mono:
                 opts["dual_mono"] = "true"
 
+            self.verification_target_level = float(opts["i"])
             return "loudnorm=" + dict_to_filter_opts(opts)
 
         if not self.loudness_statistics["ebu_pass1"]:
@@ -843,6 +883,7 @@ class AudioStream(MediaStream):
         if self.media_file.ffmpeg_normalize.dual_mono:
             opts["dual_mono"] = "true"
 
+        self.verification_target_level = target_level
         return "loudnorm=" + dict_to_filter_opts(opts)
 
     def get_second_pass_opts_peakrms(self, batch_reference: float | None = None) -> str: