ffmpeg-normalize 1.38.0__tar.gz → 1.40.0__tar.gz

{ffmpeg_normalize-1.38.0 → ffmpeg_normalize-1.40.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffmpeg-normalize
-Version: 1.38.0
+Version: 1.40.0
 Summary: Normalize audio via ffmpeg
 Keywords: ffmpeg,normalize,audio
 Author: Werner Robitza
@@ -49,6 +49,7 @@ This program normalizes media files to a certain loudness level using the EBU R1
 - RMS-based normalization — Adjust audio to a specific RMS level
 - 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
 - Video file support — Process video files while preserving video streams
 - Docker support — Run via Docker container
 - Python API — Use programmatically in your Python projects
@@ -64,6 +65,22 @@ This program normalizes media files to a certain loudness level using the EBU R1
 
 ## 🆕 What's New
 
+- Version 1.40.0 can optionally **skip files that are already at the target level** via `--threshold` (e.g. `--threshold 0.5`, disabled by default). Such files are copied through unchanged instead of being re-encoded. The `--print-stats` output now includes a per-file `status` (`normalized`, `skipped`, or `error`, plus an `error` message on failure), and the exit code is non-zero if any file failed to process, so a script can tell what happened to each file.
+
+    Example:
+
+    ```bash
+    ffmpeg-normalize input.flac -nt peak -t 0 -c:a flac --print-stats -o output.flac
+    ```
+
+- Version 1.39.0 preserves the **input bit depth** by default when encoding to formats like FLAC, so 16-bit input stays 16-bit without needing `-e "-sample_fmt s16"`. Use `--no-keep-bit-depth` to opt out. It also adds `--keep-mtime` to copy the input file's modification time to the output, which is useful for preserving when a track was added to a music library.
+
+    Example:
+
+    ```bash
+    ffmpeg-normalize input.flac -nt peak -t 0 -c:a flac --keep-mtime -o output.flac
+    ```
+
 - Version 1.38.0 writes the normalized output  directly to the destination without using temporary files
 
 - Version 1.36.0 introduces **presets** with `--preset`! Save and reuse your favorite normalization configurations for different use cases. Comes with three built-in presets: `podcast` (AES standard), `music` (RMS-based batch normalization), and `streaming-video` (video content). Create custom presets too!

{ffmpeg_normalize-1.38.0 → ffmpeg_normalize-1.40.0}/README.md

@@ -18,6 +18,7 @@ This program normalizes media files to a certain loudness level using the EBU R1
 - RMS-based normalization — Adjust audio to a specific RMS level
 - 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
 - Video file support — Process video files while preserving video streams
 - Docker support — Run via Docker container
 - Python API — Use programmatically in your Python projects
@@ -33,6 +34,22 @@ This program normalizes media files to a certain loudness level using the EBU R1
 
 ## 🆕 What's New
 
+- Version 1.40.0 can optionally **skip files that are already at the target level** via `--threshold` (e.g. `--threshold 0.5`, disabled by default). Such files are copied through unchanged instead of being re-encoded. The `--print-stats` output now includes a per-file `status` (`normalized`, `skipped`, or `error`, plus an `error` message on failure), and the exit code is non-zero if any file failed to process, so a script can tell what happened to each file.
+
+    Example:
+
+    ```bash
+    ffmpeg-normalize input.flac -nt peak -t 0 -c:a flac --print-stats -o output.flac
+    ```
+
+- Version 1.39.0 preserves the **input bit depth** by default when encoding to formats like FLAC, so 16-bit input stays 16-bit without needing `-e "-sample_fmt s16"`. Use `--no-keep-bit-depth` to opt out. It also adds `--keep-mtime` to copy the input file's modification time to the output, which is useful for preserving when a track was added to a music library.
+
+    Example:
+
+    ```bash
+    ffmpeg-normalize input.flac -nt peak -t 0 -c:a flac --keep-mtime -o output.flac
+    ```
+
 - Version 1.38.0 writes the normalized output  directly to the destination without using temporary files
 
 - Version 1.36.0 introduces **presets** with `--preset`! Save and reuse your favorite normalization configurations for different use cases. Comes with three built-in presets: `podcast` (AES standard), `music` (RMS-based batch normalization), and `streaming-video` (video content). Create custom presets too!

{ffmpeg_normalize-1.38.0 → ffmpeg_normalize-1.40.0}/pyproject.toml

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

{ffmpeg_normalize-1.38.0 → ffmpeg_normalize-1.40.0}/src/ffmpeg_normalize/__main__.py

@@ -94,6 +94,18 @@ def create_parser() -> argparse.ArgumentParser:
         ),
         default=FFmpegNormalize.DEFAULTS["output_folder"],
     )
+    group_io.add_argument(
+        "--keep-mtime",
+        action="store_true",
+        help=textwrap.dedent(
+            """\
+            Copy the input file's modification time to the output file.
+
+            Only the access and modification times are copied; a file's creation
+            time (tracked separately on some operating systems) is not affected.
+        """
+        ),
+    )
 
     group_general = parser.add_argument_group("General Options")
     group_general.add_argument(
@@ -222,16 +234,28 @@ def create_parser() -> argparse.ArgumentParser:
         ),
     )
 
-    # group_normalization.add_argument(
-    #     '--threshold',
-    #     type=float,
-    #     help=textwrap.dedent("""\
-    #     Threshold below which normalization should not be run.
+    group_normalization.add_argument(
+        "--threshold",
+        type=float,
+        help=textwrap.dedent(
+            f"""\
+        Skip normalization when a file is already within this many dB/LU of the
+        target level (default: {FFmpegNormalize.DEFAULTS["threshold"]}, i.e. disabled).
+
+        When set to a positive value, a file whose measured level is within the
+        threshold of the target is considered already normalized and copied
+        through unchanged instead of being re-encoded. Its status is reported as
+        "skipped" in the `--print-stats` output.
 
-    #     If the stream falls within the threshold, it will simply be copied.
-    #     """),
-    #     default=0.5
-    # )
+        For EBU normalization, the measured integrated loudness is compared to
+        the target level; for peak and RMS, the measured peak/RMS level is used.
+
+        The default of 0 always normalizes. Has no effect in batch or ReplayGain
+        mode, or when a pre/post filter or channel downmix is used.
+        """
+        ),
+        default=FFmpegNormalize.DEFAULTS["threshold"],
+    )
 
     group_ebu = parser.add_argument_group("EBU R128 Normalization")
     group_ebu.add_argument(
@@ -451,6 +475,26 @@ def create_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Copy original, non-normalized audio streams to output file",
     )
+    group_acodec.add_argument(
+        "--keep-bit-depth",
+        action=argparse.BooleanOptionalAction,
+        default=FFmpegNormalize.DEFAULTS["keep_bit_depth"],
+        help=textwrap.dedent(
+            """\
+        Carry the detected input bit depth through to the output encoder
+        (default: enabled).
+
+        By default, the matching output sample format is set for the chosen
+        encoder (e.g. FLAC), so you do not need to pass it via
+        `-e`/`--extra-output-options` yourself. Use `--no-keep-bit-depth` to let
+        the encoder pick its own sample format instead.
+
+        The chosen sample format is constrained to what the encoder supports.
+        ffmpeg has no 24-bit sample format, so 24-bit audio is carried in the
+        32-bit `s32` format. Floating-point sources are left to the encoder.
+        """
+        ),
+    )
     group_acodec.add_argument(
         "-prf",
         "--pre-filter",
@@ -675,8 +719,8 @@ def main() -> None:
         normalization_type=cli_args.normalization_type,
         target_level=cli_args.target_level,
         print_stats=cli_args.print_stats,
+        threshold=cli_args.threshold,
         loudness_range_target=cli_args.loudness_range_target,
-        # threshold=cli_args.threshold,
         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,
@@ -708,6 +752,8 @@ def main() -> None:
         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,
     )
 
     if cli_args.output and len(cli_args.input) > len(cli_args.output):
@@ -792,6 +838,20 @@ def main() -> None:
     except FFmpegNormalizeError as e:
         error(e)
 
+    # Report per-file failures and exit non-zero if any file failed to process.
+    # Files that were skipped because they were already at the target level are
+    # not errors and do not affect the exit code.
+    failed_files = [
+        media_file
+        for media_file in ffmpeg_normalize.media_files
+        if media_file.status == "error"
+    ]
+    if failed_files:
+        _logger.error(f"{len(failed_files)} file(s) failed to process:")
+        for media_file in failed_files:
+            _logger.error(f"  - {media_file.input_file}: {media_file.error}")
+        sys.exit(1)
+
 
 if __name__ == "__main__":
     main()

{ffmpeg_normalize-1.38.0 → ffmpeg_normalize-1.40.0}/src/ffmpeg_normalize/_cmd_utils.py

@@ -204,6 +204,44 @@ def get_ffmpeg_exe() -> str:
     return ff_path
 
 
+_encoder_sample_formats_cache: dict[str, list[str]] = {}
+
+
+def get_encoder_sample_formats(encoder: str) -> list[str]:
+    """
+    Return the list of sample formats supported by an ffmpeg audio encoder.
+
+    The result is parsed from ``ffmpeg -h encoder=<encoder>`` and cached per
+    encoder for the lifetime of the process.
+
+    Args:
+        encoder: Name of the ffmpeg audio encoder (e.g. "flac").
+
+    Returns:
+        list[str]: Supported sample formats (e.g. ["s16", "s32"]), or an empty
+            list if they could not be determined.
+    """
+    if encoder in _encoder_sample_formats_cache:
+        return _encoder_sample_formats_cache[encoder]
+
+    formats: list[str] = []
+    try:
+        output = (
+            CommandRunner()
+            .run_command([get_ffmpeg_exe(), "-hide_banner", "-h", f"encoder={encoder}"])
+            .get_output()
+        )
+        if match := re.search(r"Supported sample formats:\s*(.+)", output):
+            formats = match.group(1).split()
+    except (RuntimeError, FFmpegNormalizeError) as e:
+        _logger.debug(
+            f"Could not determine sample formats for encoder '{encoder}': {e}"
+        )
+
+    _encoder_sample_formats_cache[encoder] = formats
+    return formats
+
+
 def ffmpeg_has_loudnorm() -> bool:
     """
     Run feature detection on ffmpeg to see if it supports the loudnorm filter.

{ffmpeg_normalize-1.38.0 → ffmpeg_normalize-1.40.0}/src/ffmpeg_normalize/_ffmpeg_normalize.py

@@ -55,6 +55,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.
+        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.
         keep_lra_above_loudness_range_target (bool, optional): Keep input loudness range above loudness range target. Defaults to False.
@@ -88,6 +89,8 @@ class FFmpegNormalize:
         audio_streams (list[int] | None, optional): List of audio stream indices to normalize. Defaults to None (all streams).
         audio_default_only (bool, optional): Only normalize audio streams with default disposition. Defaults to False.
         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.
 
     Raises:
         FFmpegNormalizeError: If the ffmpeg executable is not found or does not support the loudnorm filter.
@@ -99,6 +102,7 @@ class FFmpegNormalize:
         "normalization_type": "ebu",
         "target_level": -23.0,
         "print_stats": False,
+        "threshold": 0.0,
         "loudness_range_target": 7.0,
         "keep_loudness_range_target": False,
         "keep_lra_above_loudness_range_target": False,
@@ -133,6 +137,8 @@ class FFmpegNormalize:
         "audio_streams": None,
         "audio_default_only": False,
         "keep_other_audio": False,
+        "keep_mtime": False,
+        "keep_bit_depth": True,
     }
 
     def __init__(
@@ -140,7 +146,7 @@ class FFmpegNormalize:
         normalization_type: Literal["ebu", "rms", "peak"] = "ebu",
         target_level: float = -23.0,
         print_stats: bool = False,
-        # threshold=0.5,
+        threshold: float = 0.0,
         loudness_range_target: float = 7.0,
         keep_loudness_range_target: bool = False,
         keep_lra_above_loudness_range_target: bool = False,
@@ -174,6 +180,8 @@ class FFmpegNormalize:
         audio_streams: list[int] | None = None,
         audio_default_only: bool = False,
         keep_other_audio: bool = False,
+        keep_mtime: bool = False,
+        keep_bit_depth: bool = True,
     ):
         self.ffmpeg_exe = get_ffmpeg_exe()
         self.has_loudnorm_capabilities = ffmpeg_has_loudnorm()
@@ -197,7 +205,7 @@ class FFmpegNormalize:
 
         self.print_stats = print_stats
 
-        # self.threshold = float(threshold)
+        self.threshold = check_range(threshold, 0, 99, name="threshold")
 
         self.loudness_range_target = check_range(
             loudness_range_target, 1, 50, name="loudness_range_target"
@@ -263,6 +271,9 @@ class FFmpegNormalize:
         self.audio_default_only = audio_default_only
         self.keep_other_audio = keep_other_audio
 
+        self.keep_mtime = keep_mtime
+        self.keep_bit_depth = keep_bit_depth
+
         if (
             self.audio_codec is None or "pcm" in self.audio_codec
         ) and self.output_format in PCM_INCOMPATIBLE_FORMATS:
@@ -449,13 +460,10 @@ class FFmpegNormalize:
                             "Dynamic EBU mode: First pass skipped for this file."
                         )
                 except Exception as e:
-                    if len(self.media_files) > 1:
-                        _logger.error(
-                            f"Error analyzing input file {media_file}, will "
-                            f"continue batch-processing. Error was: {e}"
-                        )
-                    else:
-                        raise e
+                    media_file.status = "error"
+                    media_file.error = str(e)
+                    _logger.error(f"Error analyzing input file {media_file}: {e}")
+                    continue
 
             # Phase 2: Calculate batch reference loudness
             batch_reference = self._calculate_batch_reference()
@@ -470,6 +478,11 @@ class FFmpegNormalize:
                     position=0,
                 )
             ):
+                # Skip files that already failed during analysis
+                if media_file.status == "error":
+                    _logger.debug(f"Skipping {media_file} because its analysis failed")
+                    continue
+
                 _logger.info(
                     f"Normalizing file {media_file} ({index + 1} of {self.file_count})"
                 )
@@ -477,13 +490,10 @@ class FFmpegNormalize:
                 try:
                     media_file.run_normalization(batch_reference=batch_reference)
                 except Exception as e:
-                    if len(self.media_files) > 1:
-                        _logger.error(
-                            f"Error processing input file {media_file}, will "
-                            f"continue batch-processing. Error was: {e}"
-                        )
-                    else:
-                        raise e
+                    media_file.status = "error"
+                    media_file.error = str(e)
+                    _logger.error(f"Error processing input file {media_file}: {e}")
+                    continue
         else:
             # Non-batch mode: process each file completely before moving to the next
             for index, media_file in enumerate(
@@ -498,13 +508,10 @@ class FFmpegNormalize:
                 try:
                     media_file.run_normalization()
                 except Exception as e:
-                    if len(self.media_files) > 1:
-                        _logger.error(
-                            f"Error processing input file {media_file}, will "
-                            f"continue batch-processing. Error was: {e}"
-                        )
-                    else:
-                        raise e
+                    media_file.status = "error"
+                    media_file.error = str(e)
+                    _logger.error(f"Error processing input file {media_file}: {e}")
+                    continue
 
         if self.print_stats:
             json.dump(

{ffmpeg_normalize-1.38.0 → ffmpeg_normalize-1.40.0}/src/ffmpeg_normalize/_media_file.py

@@ -4,7 +4,7 @@ import logging
 import os
 import re
 import shlex
-from shutil import rmtree
+from shutil import copyfile, rmtree
 from tempfile import mkdtemp, mkstemp
 from typing import TYPE_CHECKING, Iterable, Iterator, Literal, TypedDict, Union
 
@@ -70,6 +70,12 @@ class MediaFile:
         """
         self.ffmpeg_normalize = ffmpeg_normalize
         self.skip = False
+        # Per-file outcome, reported in the --print-stats output: "normalized"
+        # (default), "skipped" (already within threshold of target), or "error".
+        # "error" is set by FFmpegNormalize.run_normalization when processing
+        # fails; on failure, self.error holds the error message.
+        self.status: str = "normalized"
+        self.error: str | None = None
         self.input_file = input_file
         self.output_file = output_file
         current_ext = os.path.splitext(output_file)[1][1:]
@@ -87,6 +93,9 @@ class MediaFile:
         self.streams: StreamDict = {"audio": {}, "video": {}, "subtitle": {}}
         self.temp_file: Union[str, None] = None
         self.batch_reference: float | None = None
+        # Input (access, modification) times captured before processing, used
+        # when the keep_mtime option is enabled.
+        self.input_timestamps: tuple[float, float] | None = None
 
         self.parse_streams()
 
@@ -178,8 +187,9 @@ class MediaFile:
                 sample_rate = (
                     int(sample_rate_match.group(1)) if sample_rate_match else None
                 )
-                bit_depth_match = re.search(r"[sfu](\d+)(p|le|be)?", line)
-                bit_depth = int(bit_depth_match.group(1)) if bit_depth_match else None
+                bit_depth_match = re.search(r"([sfu])(\d+)(p|le|be)?", line)
+                bit_depth = int(bit_depth_match.group(2)) if bit_depth_match else None
+                is_float = bit_depth_match.group(1) == "f" if bit_depth_match else False
                 self.streams["audio"][stream_id] = AudioStream(
                     self.ffmpeg_normalize,
                     self,
@@ -188,6 +198,7 @@ class MediaFile:
                     bit_depth,
                     duration,
                     is_default,
+                    is_float,
                 )
 
             elif "Video" in line:
@@ -280,6 +291,17 @@ class MediaFile:
         # Store batch reference for use in second pass
         self.batch_reference = batch_reference
 
+        # Capture the input file's timestamps before processing, since an
+        # in-place overwrite would otherwise lose the original modification time.
+        if self.ffmpeg_normalize.keep_mtime:
+            try:
+                stat = os.stat(self.input_file)
+                self.input_timestamps = (stat.st_atime, stat.st_mtime)
+            except OSError as e:
+                _logger.warning(
+                    f"Could not read timestamps from {self.input_file}: {e}"
+                )
+
         # run the first pass to get loudness stats, unless in dynamic EBU mode or batch mode
         # (in batch mode, first pass is already done in FFmpegNormalize.run_normalization)
         if batch_reference is None:
@@ -297,6 +319,14 @@ class MediaFile:
                 f"Batch mode: Skipping first pass (already completed), using batch reference = {batch_reference:.2f}"
             )
 
+        # If the file is already within the configured threshold of the target
+        # level, skip normalization entirely and copy the input through to the
+        # output unchanged. This avoids needless re-encoding of files that are
+        # already at the target level.
+        if self._is_within_threshold():
+            self._handle_skip()
+            return
+
         temp_dir = None
 
         if self.ffmpeg_normalize.replaygain:
@@ -336,8 +366,141 @@ class MediaFile:
             # Strip any existing ReplayGain tags from the output file
             # since they are no longer accurate after normalization
             self._strip_replaygain_tags(self.output_file)
+            # Copy input timestamps last, after any tag modifications, so the
+            # output ends up with the original modification time.
+            if self.ffmpeg_normalize.keep_mtime and not self.ffmpeg_normalize.dry_run:
+                self._apply_input_timestamps()
             _logger.info(f"Normalized file written to {self.output_file}")
 
+    def _is_within_threshold(self) -> bool:
+        """
+        Return whether every stream selected for normalization is already
+        within the configured threshold of the target level, meaning the file
+        can be copied through unchanged instead of being re-normalized.
+
+        The check compares the measured level against the absolute target level
+        (integrated loudness for EBU, peak/RMS level otherwise). It is disabled
+        when the threshold is zero or less, in batch mode (where files are
+        adjusted relative to a shared reference rather than an absolute target),
+        in ReplayGain mode (which only writes tags), when a pre/post filter or
+        channel downmix is requested (since these change the audio), and when
+        the output extension differs from the input (since the file is copied
+        verbatim, a container change would otherwise produce an invalid file).
+
+        Returns:
+            bool: True if the file should be skipped, False otherwise.
+        """
+        threshold = self.ffmpeg_normalize.threshold
+        if threshold <= 0:
+            return False
+
+        if self.ffmpeg_normalize.batch or self.ffmpeg_normalize.replaygain:
+            return False
+
+        if (
+            self.ffmpeg_normalize.pre_filter
+            or self.ffmpeg_normalize.post_filter
+            or self.ffmpeg_normalize.audio_channels
+        ):
+            return False
+
+        # A skipped file is copied verbatim, which only yields a valid file when
+        # the container stays the same. If the output extension differs, fall
+        # back to normal normalization so the requested format is produced.
+        input_ext = os.path.splitext(self.input_file)[1][1:].lower()
+        if input_ext != self.output_ext.lower():
+            return False
+
+        norm_type = self.ffmpeg_normalize.normalization_type
+        target = self.ffmpeg_normalize.target_level
+        streams = self._get_streams_to_normalize()
+        if not streams:
+            return False
+
+        for stream in streams:
+            measured: float | None
+            if norm_type == "ebu":
+                ebu_stats = stream.loudness_statistics["ebu_pass1"]
+                if ebu_stats is None:
+                    return False
+                measured = ebu_stats["input_i"]
+            elif norm_type == "peak":
+                measured = stream.loudness_statistics["max"]
+            else:  # rms
+                measured = stream.loudness_statistics["mean"]
+
+            if measured is None:
+                return False
+            if abs(target - float(measured)) > threshold:
+                return False
+
+        return True
+
+    def _handle_skip(self) -> None:
+        """
+        Mark this file as skipped (already at target) and copy the input
+        through to the output unchanged.
+
+        The input is copied verbatim (codec and other output options are not
+        applied to skipped files; use a threshold of 0 to always re-encode).
+        Stale ReplayGain tags are still stripped from the output, and the input
+        modification time is preserved if requested.
+        """
+        self.status = "skipped"
+        _logger.info(
+            f"{self.input_file}: already within {self.ffmpeg_normalize.threshold} "
+            f"of target level {self.ffmpeg_normalize.target_level}, "
+            "skipping normalization"
+        )
+
+        if self.ffmpeg_normalize.dry_run:
+            _logger.warning("Dry run used, not actually copying the file")
+            return
+
+        if self.output_file == os.devnull:
+            return
+
+        if os.path.realpath(self.input_file) != os.path.realpath(self.output_file):
+            try:
+                copyfile(self.input_file, self.output_file)
+            except OSError as e:
+                raise FFmpegNormalizeError(
+                    f"Could not copy {self.input_file} to {self.output_file}: {e}"
+                )
+        else:
+            _logger.debug(
+                "Output file is the same as the input file, leaving it unchanged"
+            )
+
+        # Remove any existing ReplayGain tags from the output, matching the
+        # behavior of a normal run.
+        self._strip_replaygain_tags(self.output_file)
+
+        if self.ffmpeg_normalize.keep_mtime:
+            self._apply_input_timestamps()
+
+        _logger.info(f"Skipped file copied to {self.output_file}")
+
+    def _apply_input_timestamps(self) -> None:
+        """
+        Copy the input file's access and modification times to the output file.
+
+        Used when the ``keep_mtime`` option is enabled. Only the access and
+        modification times are copied; a file's creation time (which some
+        operating systems such as Windows track separately) is not affected.
+        """
+        if self.input_timestamps is None:
+            return
+        atime, mtime = self.input_timestamps
+        try:
+            os.utime(self.output_file, (atime, mtime))
+            _logger.debug(
+                f"Copied input timestamps to {self.output_file} "
+                f"(atime={atime}, mtime={mtime})"
+            )
+        except OSError as e:
+            _logger.warning(f"Could not copy timestamps to {self.output_file}: {e}")
+
     def _run_replaygain(self) -> None:
         """
         Run the replaygain process for this file.
@@ -806,6 +969,15 @@ class MediaFile:
             for idx in range(len(streams_to_normalize)):
                 cmd.extend([f"-ac:a:{idx}", str(self.ffmpeg_normalize.audio_channels)])
 
+        # carry the input bit depth through to the output encoder, if requested
+        if self.ffmpeg_normalize.keep_bit_depth:
+            for idx, audio_stream in enumerate(streams_to_normalize):
+                sample_fmt = audio_stream.get_output_sample_fmt(
+                    self.ffmpeg_normalize.audio_codec
+                )
+                if sample_fmt is not None:
+                    cmd.extend([f"-sample_fmt:a:{idx}", sample_fmt])
+
         # ... and subtitles
         if not self.ffmpeg_normalize.subtitle_disable:
             for s in self.streams["subtitle"].keys():

{ffmpeg_normalize-1.38.0 → ffmpeg_normalize-1.40.0}/src/ffmpeg_normalize/_streams.py

@@ -6,7 +6,11 @@ import os
 import re
 from typing import TYPE_CHECKING, Iterator, Literal, TypedDict, cast
 
-from ._cmd_utils import CommandRunner, dict_to_filter_opts
+from ._cmd_utils import (
+    CommandRunner,
+    dict_to_filter_opts,
+    get_encoder_sample_formats,
+)
 from ._errors import FFmpegNormalizeError
 
 if TYPE_CHECKING:
@@ -17,6 +21,23 @@ _logger = logging.getLogger(__name__)
 
 _loudnorm_pattern = re.compile(r"\[Parsed_loudnorm_(\d+)")
 
+# Maps ffmpeg sample formats to (bit size, is_float). Planar variants share the
+# same characteristics as their packed counterparts.
+_SAMPLE_FMT_INFO: dict[str, tuple[int, bool]] = {
+    "u8": (8, False),
+    "u8p": (8, False),
+    "s16": (16, False),
+    "s16p": (16, False),
+    "s32": (32, False),
+    "s32p": (32, False),
+    "s64": (64, False),
+    "s64p": (64, False),
+    "flt": (32, True),
+    "fltp": (32, True),
+    "dbl": (64, True),
+    "dblp": (64, True),
+}
+
 
 class EbuLoudnessStatistics(TypedDict):
     input_i: float
@@ -38,10 +59,15 @@ class LoudnessStatistics(TypedDict):
     max: float | None
 
 
-class LoudnessStatisticsWithMetadata(LoudnessStatistics):
+class _OptionalStatisticsMetadata(TypedDict, total=False):
+    error: str
+
+
+class LoudnessStatisticsWithMetadata(LoudnessStatistics, _OptionalStatisticsMetadata):
     input_file: str
     output_file: str
     stream_id: int
+    status: str
 
 
 class MediaStream:
@@ -100,6 +126,7 @@ class AudioStream(MediaStream):
         bit_depth: int | None,
         duration: float | None,
         is_default: bool = False,
+        is_float: bool = False,
     ):
         """
         Create an AudioStream object.
@@ -112,6 +139,7 @@ class AudioStream(MediaStream):
             bit_depth (int): bit depth in bits
             duration (float): duration in seconds
             is_default (bool): Whether this stream has the default disposition flag
+            is_float (bool): Whether the stream uses a floating-point sample format
         """
         super().__init__(ffmpeg_normalize, media_file, "audio", stream_id)
 
@@ -127,6 +155,7 @@ class AudioStream(MediaStream):
 
         self.duration = duration
         self.is_default = is_default
+        self.is_float = is_float
 
     @staticmethod
     def _constrain(
@@ -171,7 +200,12 @@ class AudioStream(MediaStream):
             "ebu_pass2": self.loudness_statistics["ebu_pass2"],
             "mean": self.loudness_statistics["mean"],
             "max": self.loudness_statistics["max"],
+            "status": self.media_file.status,
         }
+        # 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:
+            stats["error"] = self.media_file.error
         return stats
 
     def set_second_pass_stats(self, stats: EbuLoudnessStatistics) -> None:
@@ -205,6 +239,84 @@ class AudioStream(MediaStream):
             )
             return "pcm_s16le"
 
+    def get_output_sample_fmt(self, codec: str | None) -> str | None:
+        """
+        Choose an output sample format for the given encoder that preserves the
+        detected input bit depth as closely as possible.
+
+        Used by the ``keep_bit_depth`` option (enabled by default) so that
+        encoders such as FLAC, which would otherwise pick their own default
+        sample format, retain the input bit depth. Only integer formats are
+        considered, and floating-point sources are left to the encoder, since
+        keeping bit depth is only meaningful for integer PCM sources.
+
+        Note that ffmpeg has no 24-bit sample format; 24-bit audio is carried in
+        the 32-bit ``s32`` format, and the encoder stores it accordingly.
+
+        Args:
+            codec: The output audio codec name, or None for the PCM default.
+
+        Returns:
+            str | None: The chosen sample format, or None if none should be set
+                (unknown bit depth, floating-point source, no explicit codec, no
+                encoder info, or an encoder without integer sample formats). In
+                all of these cases the encoder default is used.
+        """
+        if not self.bit_depth:
+            _logger.debug(
+                f"{self.media_file.input_file}: Could not determine input bit depth "
+                f"for stream {self.stream_id}; leaving the sample format to the encoder."
+            )
+            return None
+
+        if self.is_float:
+            # Pinning an integer sample format would silently convert a
+            # floating-point source to integer, so leave it to the encoder.
+            _logger.debug(
+                f"{self.media_file.input_file}: Stream {self.stream_id} is "
+                "floating-point; leaving the sample format to the encoder."
+            )
+            return None
+
+        if codec is None:
+            # The PCM default path already derives the bit depth from the input
+            # via get_pcm_codec(), so there is nothing to set here.
+            _logger.debug(
+                "keep_bit_depth has no effect for the default PCM output; the "
+                "input bit depth is already preserved."
+            )
+            return None
+
+        supported = get_encoder_sample_formats(codec)
+        if not supported:
+            _logger.debug(
+                f"Could not determine supported sample formats for codec '{codec}'; "
+                "not setting an explicit sample format."
+            )
+            return None
+
+        # Only consider integer formats, since keeping bit depth is meaningful
+        # for integer PCM sources (e.g. FLAC, ALAC).
+        int_formats = [
+            fmt
+            for fmt in supported
+            if fmt in _SAMPLE_FMT_INFO and not _SAMPLE_FMT_INFO[fmt][1]
+        ]
+        if not int_formats:
+            _logger.debug(
+                f"Encoder '{codec}' supports no integer sample formats; "
+                "leaving the sample format to the encoder."
+            )
+            return None
+
+        # Prefer the smallest integer format that holds at least the input bit
+        # depth; fall back to the largest available if none is big enough.
+        candidates = sorted(int_formats, key=lambda fmt: _SAMPLE_FMT_INFO[fmt][0])
+        for fmt in candidates:
+            if _SAMPLE_FMT_INFO[fmt][0] >= self.bit_depth:
+                return fmt
+        return candidates[-1]
+
     def _get_filter_str_with_pre_filter(self, current_filter: str) -> str:
         """
         Get a filter string for current_filter, with the pre-filter