feat: preserve input bit depth by default

When encoding to a non-PCM codec (e.g. FLAC), ffmpeg would pick its own
default sample format and could promote 16-bit audio to 24-bit. The
matching output sample format is now set automatically, so the input bit
depth is preserved without needing -e "-sample_fmt ...".

The format is chosen per encoder from the formats it actually supports
(packed for FLAC, planar for ALAC, etc.); 24-bit is carried in s32 since
ffmpeg has no 24-bit sample format. Floating-point sources are left to
the encoder to avoid silently converting them to integer.

This is enabled by default; use --no-keep-bit-depth to opt out. This
changes the bit depth of non-PCM output compared to previous versions.

Author: slhck

src/ffmpeg_normalize/__main__.py

@@ -463,6 +463,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",
@@ -721,6 +741,7 @@ def _split_options(opts: str) -> list[str]:
         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):

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.

src/ffmpeg_normalize/_ffmpeg_normalize.py

@@ -89,6 +89,7 @@ class FFmpegNormalize:
         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.
@@ -135,6 +136,7 @@ class FFmpegNormalize:
         "audio_default_only": False,
         "keep_other_audio": False,
         "keep_mtime": False,
+        "keep_bit_depth": True,
     }
 
     def __init__(
@@ -177,6 +179,7 @@ def __init__(
         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()
@@ -267,6 +270,7 @@ def __init__(
         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

src/ffmpeg_normalize/_media_file.py

@@ -181,8 +181,9 @@ def parse_streams(self) -> None:
                 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,
@@ -191,6 +192,7 @@ def parse_streams(self) -> None:
                     bit_depth,
                     duration,
                     is_default,
+                    is_float,
                 )
 
             elif "Video" in line:
@@ -844,6 +846,15 @@ def _second_pass(self) -> Iterator[float]:
             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():

src/ffmpeg_normalize/_streams.py

@@ -6,7 +6,11 @@
 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 @@
 
 _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
@@ -100,6 +121,7 @@ def __init__(
         bit_depth: int | None,
         duration: float | None,
         is_default: bool = False,
+        is_float: bool = False,
     ):
         """
         Create an AudioStream object.
@@ -112,6 +134,7 @@ def __init__(
             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 +150,7 @@ def __init__(
 
         self.duration = duration
         self.is_default = is_default
+        self.is_float = is_float
 
     @staticmethod
     def _constrain(
@@ -205,6 +229,84 @@ def get_pcm_codec(self) -> str:
             )
             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