feat: implement automatic audio codec selection based on output container

This is based on ffmpeg's default choice (a shell call to ffmpeg parses it), and still picks PCM for containers that support it to prevent quality loss.

Author: slhck

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:

docs/advanced/faq.md

@@ -36,6 +36,12 @@ If you decide to run `ffmpeg-normalize` with the default options, it will encode
 
 I chose MKV as a default output container since it handles almost every possible combination of audio, video, and subtitle codecs. If you know which audio/video codec you want, and which container is supported, use the output options to specify the encoder and output file name manually.
 
+## Which audio codec is used for my output?
+
+If you do not set `-c:a`/`--audio-codec`, the codec is chosen for you based on the output container: PCM (lossless) for containers that support it (such as WAV or MKV), or — for containers that cannot store PCM, like MP3, MP4, FLAC, or Opus — the same default codec your ffmpeg would use for that container (e.g. `.mp3` → MP3, `.m4a` → AAC, `.flac` → FLAC, `.opus` → Opus).
+
+See also: [How the output audio codec is chosen](../usage/file-input-output.md#how-the-output-audio-codec-is-chosen).
+
 ## I get a "Could not write header for output file" error
 
 See the [next section](#the-conversion-does-not-work-and-i-get-a-cryptic-ffmpeg-error).
@@ -54,7 +60,7 @@ One possible reason is that the input file contains some streams that cannot be
 
 - You are trying to normalize a movie file, writing to a `.wav` or `.mp3` file. WAV/MP3 files only support audio, not video. Disable video and subtitles with `-vn` and `-sn`, or choose a container that supports video (e.g. `.mkv`).
 
-- You are trying to normalize a file, writing to an `.mp4` container. This program defaults to PCM audio, but MP4 does not support PCM audio. Make sure that your audio codec is set to something MP4 containers support (e.g. `-c:a aac`).
+- You explicitly requested PCM audio (e.g. `-c:a pcm_s16le`) while writing to a container that cannot store PCM, such as `.mp4`, `.flac`, or `.opus`. Either drop the `-c:a` option, in which case a suitable codec is [chosen automatically](../usage/file-input-output.md#how-the-output-audio-codec-is-chosen), or pick a codec the container supports (e.g. `-c:a aac` for MP4).
 
 The default output container is `.mkv` as it will support most input stream types. If you want a different output container, [make sure that it supports](https://en.wikipedia.org/wiki/Comparison_of_container_file_formats) your input file's video, audio, and subtitle streams (if any).
 

docs/index.md

@@ -33,6 +33,8 @@ Batch processing of several input files is possible, including video files.
 
 ## 🆕 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:

docs/usage/cli-options.md

@@ -218,7 +218,7 @@ 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.
 
 ### `-b:a AUDIO_BITRATE, --audio-bitrate AUDIO_BITRATE`
 

docs/usage/file-input-output.md

@@ -73,9 +73,25 @@ for %i in (*.mkv) do ffmpeg-normalize "%i" -c:a aac -b:a 192k
 
     CMD loops run `ffmpeg-normalize` once per file. This means `--batch` mode will **not** work, because each invocation only sees a single file. Use one of the methods above if you need batch normalization.
 
+## How the output audio codec is chosen
+
+When you do not pass `-c:a`/`--audio-codec`, `ffmpeg-normalize` picks the audio codec for you, based on the output container:
+
+- For containers that can store uncompressed audio (such as WAV, MKV, or MOV), it uses **PCM** audio, matching the input bit depth. This is lossless, but produces large files.
+- For containers that cannot store PCM (MP3, MP4/M4A, FLAC, Ogg, Opus, WebM), it uses the **same default codec that ffmpeg itself would pick for that container**, so you do not have to specify one. For example:
+
+    - `.mp3` → MP3 (`libmp3lame`)
+    - `.m4a` / `.mp4` → AAC
+    - `.flac` → FLAC
+    - `.opus` → Opus (`libopus`)
+
+The exact codec is read from your ffmpeg build at runtime rather than hardcoded, so it always matches what plain ffmpeg would do. This means it can differ between builds: for example, on some builds `.ogg` defaults to FLAC rather than Vorbis. To see what your ffmpeg would choose for a given container, run e.g. `ffmpeg -h muxer=flac` and look at the "Default audio codec" line.
+
+You can always override this by setting `-c:a` explicitly, for example `-c:a libvorbis` to force an Ogg Vorbis file. Note that re-encoding to a lossy codec (MP3, AAC, Opus, …) introduces [generation loss](https://en.wikipedia.org/wiki/Generation_loss); to keep your audio lossless, use a PCM-capable container (WAV, MKV) or a lossless codec such as FLAC.
+
 ## Create an MP3 file as output
 
-Normalize an MP3 file and write an MP3 file (you have to explicitly specify the encoder):
+Normalize an MP3 file and write an MP3 file. The codec is chosen automatically (MP3 via `libmp3lame`), but you can specify the encoder and bitrate explicitly to control quality:
 
 ```bash
 ffmpeg-normalize input.mp3 -c:a libmp3lame -b:a 320k -o output.mp3

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.
         """
         ),
     )

src/ffmpeg_normalize/_cmd_utils.py

@@ -44,6 +44,27 @@ def _get_ffmpeg_env() -> dict[str, str] | None:
     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.

src/ffmpeg_normalize/_ffmpeg_normalize.py

@@ -9,7 +9,14 @@
 
 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 @@
 _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 @@ def __init__(
         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 @@ def add_media_file(self, input_file: str, output_file: str) -> None:
         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