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

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

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

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

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

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

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

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

@@ -23,7 +23,7 @@ __version__ = importlib.metadata.version("ffmpeg-normalize")
 _logger = logging.getLogger(__name__)
 
 
-def create_parser() -> argparse.ArgumentParser:
+def create_parser(suppress_defaults: bool = False) -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="ffmpeg-normalize",
         description=textwrap.dedent(
@@ -76,6 +76,9 @@ def create_parser() -> argparse.ArgumentParser:
         will be written to the default output folder with the name `<input>.<ext>`,
         where `<ext>` is the output extension (see `-ext` option).
 
+        Output paths must be distinct and cannot overwrite another input in the same run,
+        even with --force. Normalizing a file in place is allowed.
+
         Example: ffmpeg-normalize 1.wav 2.wav -o 1n.wav 2n.wav
         """
         ),
@@ -215,12 +218,31 @@ def create_parser() -> 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",
@@ -243,8 +265,9 @@ def create_parser() -> argparse.ArgumentParser:
         level. However, a group of music files all from the same album is generally meant to be
         listened to at the relative volumes they were recorded at. In batch mode, all the specified
         files are considered to be part of a single album and their relative volumes are preserved.
-        This is done by averaging the loudness of all the files, computing a single adjustment from
-        that, and applying a relative adjustment to all the files.
+        RMS mode targets the average level, reducing the shared gain if needed to avoid sample
+        clipping. Peak mode sets the loudest sample across the album to the target level.
+        With --lower-only, the shared gain cannot be positive.
 
         Batch mode works with all normalization types (EBU, RMS, peak).
         """
@@ -672,11 +695,16 @@ def create_parser() -> argparse.ArgumentParser:
         ),
         default=FFmpegNormalize.DEFAULTS["extension"],
     )
+    if suppress_defaults:
+        for action in parser._actions:
+            action.default = argparse.SUPPRESS
     return parser
 
 
 def main() -> None:
-    cli_args = create_parser().parse_args()
+    explicit_args = create_parser(suppress_defaults=True).parse_args()
+    cli_args = create_parser().parse_args([])
+    vars(cli_args).update(vars(explicit_args))
     setup_cli_logger(arguments=cli_args)
 
     def error(message: object) -> NoReturn:
@@ -707,7 +735,9 @@ def main() -> None:
         try:
             preset_data = preset_manager.load_preset(cli_args.preset)
             _logger.debug(f"Loaded preset '{cli_args.preset}': {preset_data}")
-            preset_manager.merge_preset_with_args(preset_data, cli_args)
+            preset_manager.merge_preset_with_args(
+                preset_data, cli_args, set(vars(explicit_args))
+            )
             _logger.info(f"Applied preset '{cli_args.preset}'")
         except (FileNotFoundError, json.JSONDecodeError, ValueError) as e:
             error(str(e))
@@ -752,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(
@@ -825,6 +861,7 @@ def main() -> None:
             "Please fix the issues above and try again."
         )
 
+    output_files: list[str] = []
     for index, input_file in enumerate(input_files):
         if cli_args.output is not None and index < len(cli_args.output):
             if cli_args.output_folder and cli_args.output_folder != "normalized":
@@ -843,12 +880,15 @@ def main() -> None:
                 + "."
                 + cli_args.extension,
             )
-            if not os.path.isdir(cli_args.output_folder) and not cli_args.dry_run:
-                _logger.warning(
-                    f"Output directory '{cli_args.output_folder}' does not exist, will create"
-                )
-                os.makedirs(cli_args.output_folder, exist_ok=True)
+        output_files.append(output_file)
 
+    try:
+        if not cli_args.replaygain:
+            FFmpegNormalize.validate_output_files(input_files, output_files)
+    except FFmpegNormalizeError as e:
+        error(e)
+
+    for input_file, output_file in zip(input_files, output_files):
         if (
             os.path.exists(output_file)
             and not cli_args.force
@@ -867,6 +907,10 @@ def main() -> None:
             _logger.warning(f"Input file '{input_file}' is not a file, skipping")
             continue
 
+        output_dir = os.path.dirname(output_file)
+        if output_dir and not cli_args.dry_run:
+            os.makedirs(output_dir, exist_ok=True)
+
         try:
             ffmpeg_normalize.add_media_file(input_file, output_file)
         except FFmpegNormalizeError as e:

{ffmpeg_normalize-1.43.0 → 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.0 → ffmpeg_normalize-1.44.0}/src/ffmpeg_normalize/_ffmpeg_normalize.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import logging
+import math
 import os
 import sys
 from itertools import chain
@@ -98,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.
@@ -148,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__(
@@ -193,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()
@@ -292,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:
@@ -385,23 +409,68 @@ class FFmpegNormalize:
                 errors.append(error_msg)
         return errors
 
+    @staticmethod
+    def validate_output_files(input_files: list[str], output_files: list[str]) -> None:
+        """Reject duplicate destinations and outputs that overwrite another input.
+
+        Resolve symlinks and existing hard links, while allowing each file to be
+        normalized in place and multiple outputs to the null device.
+        """
+
+        def path_keys(path: str) -> list[str | tuple[int, int]]:
+            keys: list[str | tuple[int, int]] = [
+                os.path.normcase(os.path.realpath(path))
+            ]
+            if os.path.exists(path):
+                stat = os.stat(path)
+                keys.append((stat.st_dev, stat.st_ino))
+            return keys
+
+        input_owners: dict[str | tuple[int, int], set[int]] = {}
+        for index, path in enumerate(input_files):
+            for key in path_keys(path):
+                input_owners.setdefault(key, set()).add(index)
+
+        output_owners: dict[str | tuple[int, int], str] = {}
+        for index, path in enumerate(output_files):
+            if os.path.realpath(path) == os.path.realpath(os.devnull):
+                continue
+            for key in path_keys(path):
+                if key in output_owners:
+                    raise FFmpegNormalizeError(
+                        f"Output collision: '{path}' and '{output_owners[key]}' "
+                        "refer to the same destination. Specify distinct output paths."
+                    )
+                if input_owners.get(key, set()) - {index}:
+                    raise FFmpegNormalizeError(
+                        f"Output '{path}' would overwrite another input file. "
+                        "Specify a different output path."
+                    )
+                output_owners[key] = path
+
     def _calculate_batch_reference(self) -> float | None:
         """
-        Calculate the batch reference loudness by averaging measurements across all files.
+        Calculate a shared reference from the selected streams' measurements.
+
+        Peak mode uses the highest sample peak. RMS mode uses the average RMS,
+        with gain capped by the highest sample peak. EBU uses average LUFS.
 
         Returns:
             float | None: The batch reference loudness value, or None if no measurements found.
 
         Note:
-            TODO: Add option to specify different averaging methods (duration-weighted,
-            use quietest/loudest track, etc.)
+            RMS and EBU averages weight each selected stream equally.
         """
         measurements: list[float] = []
+        peaks: list[float] = []
 
         for media_file in self.media_files:
-            # Access audio streams from the streams dict
-            audio_streams = media_file.streams.get("audio", {})
-            for stream in audio_streams.values():
+            if media_file.status == "error":
+                continue
+            for stream in media_file._get_streams_to_normalize():
+                peak = stream.loudness_statistics.get("max")
+                if peak is not None and math.isfinite(peak):
+                    peaks.append(float(peak))
                 if self.normalization_type == "ebu":
                     # Get EBU integrated loudness from first pass
                     ebu_stats = stream.loudness_statistics.get("ebu_pass1")
@@ -418,6 +487,7 @@ class FFmpegNormalize:
                     if max_val is not None:
                         measurements.append(float(max_val))
 
+        measurements = [value for value in measurements if math.isfinite(value)]
         if not measurements:
             _logger.warning(
                 "No loudness measurements found for batch reference calculation. "
@@ -425,12 +495,27 @@ class FFmpegNormalize:
             )
             return None
 
-        # Simple average of all measurements
-        batch_reference = sum(measurements) / len(measurements)
+        # Peak mode targets the loudest sample in the album. RMS mode targets
+        # the average level, but limits the shared gain to available headroom.
+        batch_reference = (
+            max(measurements)
+            if self.normalization_type == "peak"
+            else sum(measurements) / len(measurements)
+        )
+        if self.normalization_type == "rms" and peaks:
+            safe_reference = self.target_level + max(peaks)
+            if safe_reference > batch_reference:
+                _logger.warning(
+                    "Reducing album gain to avoid sample clipping; "
+                    "the requested RMS target will not be reached."
+                )
+                batch_reference = safe_reference
+        if self.lower_only and self.normalization_type in ("peak", "rms"):
+            batch_reference = max(batch_reference, self.target_level)
         _logger.debug(f"Batch mode: Measurements for batch reference: {measurements}")
         _logger.info(
             f"Batch mode: Calculated reference loudness = {batch_reference:.2f} "
-            f"({self.normalization_type.upper()}, averaged from {len(measurements)} stream(s))"
+            f"({self.normalization_type.upper()}, based on {len(measurements)} stream(s))"
         )
 
         return batch_reference
@@ -446,6 +531,22 @@ 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],
+                [media_file.output_file for media_file in self.media_files],
+            )
         if self.batch:
             # Batch mode: analyze all files first, then normalize with relative adjustments
             _logger.info(
@@ -524,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)
@@ -542,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)
@@ -652,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.0 → 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
@@ -784,7 +889,10 @@ class MediaFile:
             list[str]: the filters, in application order
         """
         skip_normalization = False
-        if self.ffmpeg_normalize.lower_only:
+        if self.ffmpeg_normalize.lower_only and not (
+            self.batch_reference is not None
+            and self.ffmpeg_normalize.normalization_type in ("peak", "rms")
+        ):
             if self.ffmpeg_normalize.normalization_type == "ebu":
                 if (
                     audio_stream.loudness_statistics["ebu_pass1"] is not None

{ffmpeg_normalize-1.43.0 → ffmpeg_normalize-1.44.0}/src/ffmpeg_normalize/_presets.py

@@ -9,8 +9,6 @@ import shutil
 from pathlib import Path
 from typing import Any
 
-from ._ffmpeg_normalize import FFmpegNormalize
-
 _logger = logging.getLogger(__name__)
 
 
@@ -171,60 +169,23 @@ class PresetManager:
         return preset_data
 
     def merge_preset_with_args(
-        self, preset_data: dict[str, Any], cli_args: Any
+        self, preset_data: dict[str, Any], cli_args: Any, explicit_args: set[str]
     ) -> None:
-        """Merge preset data with CLI arguments, giving precedence to CLI args.
+        """Apply preset values only to options omitted from the command line.
 
         Args:
-            preset_data: Dictionary of preset configuration
-            cli_args: Parsed CLI arguments (argparse Namespace object)
-
-        The CLI arguments take precedence over preset values. This function modifies
-        cli_args in place by setting attributes that were not explicitly provided
-        on the command line.
+            preset_data: Preset configuration.
+            cli_args: Parsed arguments, including defaults; modified in place.
+            explicit_args: Argument destinations explicitly supplied by the user.
         """
         for key, value in preset_data.items():
-            # Convert hyphens to underscores to match argparse attribute names
             attr_name = key.replace("-", "_")
-
-            # Check if this attribute exists in cli_args
             if not hasattr(cli_args, attr_name):
                 _logger.warning(
                     f"Preset option '{key}' is not a valid ffmpeg-normalize option. Skipping."
                 )
                 continue
-
-            # Get the current value
-            current_value = getattr(cli_args, attr_name)
-
-            # Check if this was explicitly set by the user
-            # For most types, we can infer this by checking against the defaults:
-            # - None values were not explicitly set
-            # - Empty lists were not explicitly set
-            # - False boolean flags were not explicitly set
-            # - Default numeric values (specific to each option) need special handling
-
-            should_apply = False
-
-            if isinstance(value, bool):
-                # For boolean flags, apply preset only if currently False (not set)
-                should_apply = not current_value
-            elif isinstance(current_value, list):
-                # For lists (like output), apply preset only if empty
-                should_apply = not current_value
-            elif current_value is None:
-                # For None values, always apply preset (not explicitly set)
-                should_apply = True
-            else:
-                # For other values (numbers, strings), check if they match known defaults
-                # This is conservative: only override if the value is a known default
-                if (
-                    attr_name in FFmpegNormalize.DEFAULTS
-                    and current_value == FFmpegNormalize.DEFAULTS[attr_name]
-                ):
-                    should_apply = True
-
-            if should_apply:
+            if attr_name not in explicit_args:
                 setattr(cli_args, attr_name, value)
                 _logger.debug(f"Applied preset option '{key}' = {value}")
 

{ffmpeg_normalize-1.43.0 → 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: