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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffmpeg-normalize
-Version: 1.40.0
+Version: 1.41.0
 Summary: Normalize audio via ffmpeg
 Keywords: ffmpeg,normalize,audio
 Author: Werner Robitza
@@ -65,6 +65,8 @@ This program normalizes media files to a certain loudness level using the EBU R1
 
 ## 🆕 What's New
 
+- Version 1.41.0 automatically picks the correct output audio codec for the output container, so you no longer need to specify `-c:a`/`--audio-codec` unless you want to override the default. PCM is chosen for containers that support it; others will use teh default that ffmpeg picks. See [the usage guide](https://slhck.info/ffmpeg-normalize/usage/file-input-output/#how-the-output-audio-codec-is-chosen) for details.
+
 - 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:

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

@@ -34,6 +34,8 @@ This program normalizes media files to a certain loudness level using the EBU R1
 
 ## 🆕 What's New
 
+- Version 1.41.0 automatically picks the correct output audio codec for the output container, so you no longer need to specify `-c:a`/`--audio-codec` unless you want to override the default. PCM is chosen for containers that support it; others will use teh default that ffmpeg picks. See [the usage guide](https://slhck.info/ffmpeg-normalize/usage/file-input-output/#how-the-output-audio-codec-is-chosen) for details.
+
 - 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:

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

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

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

@@ -429,7 +429,10 @@ def create_parser() -> argparse.ArgumentParser:
         Audio codec to use for output files.
         See `ffmpeg -encoders` for a list.
 
-        Will use PCM audio with input stream bit depth by default.
+        Will use PCM audio with input stream bit depth by default. For output
+        containers that cannot store PCM (e.g. MP3, FLAC, Opus), the codec that
+        ffmpeg uses by default for that container is chosen automatically, so
+        you usually do not need to set this.
         """
         ),
     )

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

@@ -44,6 +44,27 @@ DUR_REGEX = re.compile(
     r"Duration: (?P<hour>\d{2}):(?P<min>\d{2}):(?P<sec>\d{2})\.(?P<ms>\d{2})"
 )
 
+# Containers that cannot store raw PCM audio. For these, the bit-depth-aware PCM
+# default cannot be used, so a real audio codec has to be chosen (either via the
+# -c:a option or by falling back to ffmpeg's own default for the container, see
+# get_muxer_default_audio_encoder()). PCM_INCOMPATIBLE_FORMATS is matched against
+# the -f/--output-format value, PCM_INCOMPATIBLE_EXTS against the output file
+# extension (which additionally lists m4a).
+PCM_INCOMPATIBLE_FORMATS = {"flac", "mp3", "mp4", "ogg", "oga", "opus", "webm"}
+PCM_INCOMPATIBLE_EXTS = {"flac", "mp3", "mp4", "m4a", "ogg", "oga", "opus", "webm"}
+
+# Output extensions whose ffmpeg muxer is registered under a different name.
+# ffmpeg's av_guess_format() resolves these internally; for the "-h muxer="
+# query in get_muxer_default_audio_encoder() we need the muxer's own name.
+_MUXER_NAME_FOR_EXT = {
+    "m4a": "ipod",
+    "m4b": "ipod",
+    "m4v": "ipod",
+    "aac": "adts",
+    "mka": "matroska",
+    "mkv": "matroska",
+}
+
 
 class CommandRunner:
     """
@@ -242,6 +263,114 @@ def get_encoder_sample_formats(encoder: str) -> list[str]:
     return formats
 
 
+_codec_encoders_cache: dict[str, list[str]] | None = None
+_muxer_default_encoder_cache: dict[str, str | None] = {}
+
+
+def _get_codec_encoders() -> dict[str, list[str]]:
+    """
+    Map each ffmpeg codec name to its available encoders.
+
+    Parsed once from ``ffmpeg -codecs`` and cached for the process lifetime. A
+    codec with no explicit ``(encoders: ...)`` list uses an encoder of the same
+    name, so it maps to an empty list here.
+
+    Returns:
+        dict[str, list[str]]: Mapping of codec name to encoder names.
+    """
+    global _codec_encoders_cache
+    if _codec_encoders_cache is not None:
+        return _codec_encoders_cache
+
+    encoders: dict[str, list[str]] = {}
+    try:
+        output = (
+            CommandRunner()
+            .run_command([get_ffmpeg_exe(), "-hide_banner", "-codecs"])
+            .get_output()
+        )
+        for line in output.splitlines():
+            # Rows look like: " DEAIL. opus  Opus ... (encoders: opus libopus)"
+            match = re.match(r"\s*[D.][E.][AVS.][I.][L.][S.]\s+([A-Za-z0-9_]+)", line)
+            if not match:
+                continue
+            enc_match = re.search(r"\(encoders:([^)]*)\)", line)
+            encoders[match.group(1)] = enc_match.group(1).split() if enc_match else []
+    except (RuntimeError, FFmpegNormalizeError) as e:
+        _logger.debug(f"Could not list ffmpeg codecs: {e}")
+
+    _codec_encoders_cache = encoders
+    return encoders
+
+
+def _resolve_encoder_for_codec(codec_id: str) -> str:
+    """
+    Return the encoder ffmpeg uses by default for a codec id.
+
+    This mirrors ffmpeg's own selection when no encoder is given on the command
+    line: the external library wrapper (e.g. ``libopus``) is preferred over an
+    experimental native encoder of the same name (``opus``). Codecs without an
+    explicit encoder list use an encoder named like the codec itself.
+
+    Args:
+        codec_id: The codec id as reported by ffmpeg (e.g. "opus", "flac").
+
+    Returns:
+        str: The encoder name to pass to ``-c:a``.
+    """
+    encoders = _get_codec_encoders().get(codec_id, [])
+    lib_variant = f"lib{codec_id}"
+    if lib_variant in encoders:
+        return lib_variant
+    if encoders:
+        return encoders[0]
+    return codec_id
+
+
+def get_muxer_default_audio_encoder(container: str) -> str | None:
+    """
+    Return the audio encoder ffmpeg would use by default for a container.
+
+    This replicates ffmpeg's own per-container choice when no ``-c:a`` is given,
+    rather than hardcoding a table, so it tracks whatever the installed ffmpeg
+    does (e.g. ``.ogg`` may default to flac on some builds). The container's
+    default audio codec is read from ``ffmpeg -h muxer=<name>`` and then mapped
+    to a concrete, non-experimental encoder via _resolve_encoder_for_codec().
+
+    Results are cached per container for the process lifetime, so batch runs only
+    query ffmpeg once per container.
+
+    Args:
+        container: Output file extension or ffmpeg format name without a leading
+            dot (e.g. "flac", "m4a", "ipod").
+
+    Returns:
+        str | None: The encoder name (e.g. "flac", "libopus"), or None if it
+            could not be determined.
+    """
+    container = container.lower()
+    if container in _muxer_default_encoder_cache:
+        return _muxer_default_encoder_cache[container]
+
+    muxer = _MUXER_NAME_FOR_EXT.get(container, container)
+    encoder: str | None = None
+    try:
+        output = (
+            CommandRunner()
+            .run_command([get_ffmpeg_exe(), "-hide_banner", "-h", f"muxer={muxer}"])
+            .get_output()
+        )
+        if match := re.search(r"Default audio codec:\s*([A-Za-z0-9_]+)", output):
+            encoder = _resolve_encoder_for_codec(match.group(1))
+    except (RuntimeError, FFmpegNormalizeError) as e:
+        _logger.debug(
+            f"Could not determine default audio codec for container '{container}': {e}"
+        )
+
+    _muxer_default_encoder_cache[container] = encoder
+    return encoder
+
+
 def ffmpeg_has_loudnorm() -> bool:
     """
     Run feature detection on ffmpeg to see if it supports the loudnorm filter.

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

@@ -9,7 +9,14 @@ from typing import TYPE_CHECKING, Literal
 
 from tqdm import tqdm
 
-from ._cmd_utils import ffmpeg_has_loudnorm, get_ffmpeg_exe, validate_input_file
+from ._cmd_utils import (
+    PCM_INCOMPATIBLE_EXTS,
+    PCM_INCOMPATIBLE_FORMATS,
+    ffmpeg_has_loudnorm,
+    get_ffmpeg_exe,
+    get_muxer_default_audio_encoder,
+    validate_input_file,
+)
 from ._errors import FFmpegNormalizeError
 from ._media_file import MediaFile
 
@@ -19,8 +26,6 @@ if TYPE_CHECKING:
 _logger = logging.getLogger(__name__)
 
 NORMALIZATION_TYPES = ("ebu", "rms", "peak")
-PCM_INCOMPATIBLE_FORMATS = {"flac", "mp3", "mp4", "ogg", "oga", "opus", "webm"}
-PCM_INCOMPATIBLE_EXTS = {"flac", "mp3", "mp4", "m4a", "ogg", "oga", "opus", "webm"}
 
 
 def check_range(number: object, min_r: float, max_r: float, name: str = "") -> float:
@@ -274,13 +279,21 @@ class FFmpegNormalize:
         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:
-            raise FFmpegNormalizeError(
-                f"Output format {self.output_format} does not support PCM audio. "
-                "Please choose a suitable audio codec with the -c:a option."
-            )
+        if self.output_format in PCM_INCOMPATIBLE_FORMATS:
+            if self.audio_codec is not None and "pcm" in self.audio_codec:
+                raise FFmpegNormalizeError(
+                    f"Output format {self.output_format} does not support PCM audio. "
+                    "Please choose a suitable audio codec with the -c:a option."
+                )
+            if (
+                self.audio_codec is None
+                and get_muxer_default_audio_encoder(self.output_format) is None
+            ):
+                raise FFmpegNormalizeError(
+                    f"Output format {self.output_format} does not support PCM audio, "
+                    "and a default audio codec could not be determined. Please choose "
+                    "a suitable audio codec with the -c:a option."
+                )
 
         # replaygain only works for EBU for now
         if self.replaygain and self.normalization_type != "ebu":
@@ -316,14 +329,22 @@ class FFmpegNormalize:
         if not os.path.exists(input_file):
             raise FFmpegNormalizeError(f"file {input_file} does not exist")
 
-        ext = os.path.splitext(output_file)[1][1:]
-        if (
-            self.audio_codec is None or "pcm" in self.audio_codec
-        ) and ext in PCM_INCOMPATIBLE_EXTS:
-            raise FFmpegNormalizeError(
-                f"Output extension {ext} does not support PCM audio. "
-                "Please choose a suitable audio codec with the -c:a option."
-            )
+        ext = os.path.splitext(output_file)[1][1:].lower()
+        if ext in PCM_INCOMPATIBLE_EXTS:
+            if self.audio_codec is not None and "pcm" in self.audio_codec:
+                raise FFmpegNormalizeError(
+                    f"Output extension {ext} does not support PCM audio. "
+                    "Please choose a suitable audio codec with the -c:a option."
+                )
+            if (
+                self.audio_codec is None
+                and get_muxer_default_audio_encoder(ext) is None
+            ):
+                raise FFmpegNormalizeError(
+                    f"Output extension {ext} does not support PCM audio, and a "
+                    "default audio codec could not be determined. Please choose a "
+                    "suitable audio codec with the -c:a option."
+                )
 
         self.media_files.append(MediaFile(self, input_file, output_file))
         self.file_count += 1

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

@@ -15,7 +15,13 @@ from mutagen.oggopus import OggOpus
 from mutagen.oggvorbis import OggVorbis
 from tqdm import tqdm
 
-from ._cmd_utils import DUR_REGEX, CommandRunner
+from ._cmd_utils import (
+    DUR_REGEX,
+    PCM_INCOMPATIBLE_EXTS,
+    PCM_INCOMPATIBLE_FORMATS,
+    CommandRunner,
+    get_muxer_default_audio_encoder,
+)
 from ._errors import FFmpegNormalizeError
 from ._streams import (
     AudioStream,
@@ -842,6 +848,40 @@ class MediaFile:
 
         return filter_complex_cmd, output_labels
 
+    def _get_audio_codec(self) -> str | None:
+        """
+        Return the audio encoder to use for normalized streams, or None to use
+        the bit-depth-aware PCM default.
+
+        An explicit ``--audio-codec`` (``-c:a``) always takes precedence.
+        Otherwise, for a container that cannot store PCM (e.g. FLAC, MP3, Opus),
+        fall back to the codec ffmpeg itself would default to for that container,
+        so audio-only outputs work without requiring ``-c:a``. PCM-friendly
+        containers (e.g. WAV, Matroska) keep the lossless PCM default regardless
+        of their own muxer default.
+
+        Returns:
+            str | None: The encoder name, or None to use the PCM default.
+        """
+        if self.ffmpeg_normalize.audio_codec:
+            return self.ffmpeg_normalize.audio_codec
+
+        output_format = self.ffmpeg_normalize.output_format
+        if output_format in PCM_INCOMPATIBLE_FORMATS:
+            container = output_format
+        elif self.output_ext.lower() in PCM_INCOMPATIBLE_EXTS:
+            container = self.output_ext
+        else:
+            return None
+
+        encoder = get_muxer_default_audio_encoder(container)
+        if encoder is not None:
+            _logger.debug(
+                f"No audio codec set; using ffmpeg's default '{encoder}' for "
+                f"container '{container}'"
+            )
+        return encoder
+
     def _second_pass(self) -> Iterator[float]:
         """
         Construct the second pass command and run it.
@@ -934,12 +974,14 @@ class MediaFile:
         # Track output audio stream index for codec assignment
         output_audio_idx = 0
 
+        # Resolve the audio codec once: an explicit --audio-codec wins, otherwise
+        # fall back to ffmpeg's own default codec for the output container (None
+        # means use the bit-depth-aware PCM default).
+        audio_codec = self._get_audio_codec()
+
         # set audio codec for normalized streams
         for audio_stream in streams_to_normalize:
-            if self.ffmpeg_normalize.audio_codec:
-                codec = self.ffmpeg_normalize.audio_codec
-            else:
-                codec = audio_stream.get_pcm_codec()
+            codec = audio_codec if audio_codec else audio_stream.get_pcm_codec()
             cmd.extend([f"-c:a:{output_audio_idx}", codec])
             output_audio_idx += 1
 
@@ -950,7 +992,7 @@ class MediaFile:
 
         # other audio options (if any) - only apply to normalized streams
         if self.ffmpeg_normalize.audio_bitrate:
-            if self.ffmpeg_normalize.audio_codec == "libvorbis":
+            if audio_codec == "libvorbis":
                 # libvorbis takes just a "-b" option, for some reason
                 # https://github.com/slhck/ffmpeg-normalize/issues/277
                 cmd.extend(["-b", str(self.ffmpeg_normalize.audio_bitrate)])
@@ -972,9 +1014,7 @@ class MediaFile:
         # 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
-                )
+                sample_fmt = audio_stream.get_output_sample_fmt(audio_codec)
                 if sample_fmt is not None:
                     cmd.extend([f"-sample_fmt:a:{idx}", sample_fmt])