ffmpeg-normalize 1.41.1__tar.gz → 1.42.1__tar.gz

{ffmpeg_normalize-1.41.1 → ffmpeg_normalize-1.42.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffmpeg-normalize
-Version: 1.41.1
+Version: 1.42.1
 Summary: Normalize audio via ffmpeg
 Keywords: ffmpeg,normalize,audio
 Author: Werner Robitza
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Requires-Dist: tqdm>=4.64.1
 Requires-Dist: colorama>=0.4.6 ; sys_platform == 'win32'
 Requires-Dist: ffmpeg-progress-yield>=1.0.1
@@ -29,14 +30,18 @@ Project-URL: Homepage, https://github.com/slhck/ffmpeg-normalize
 Project-URL: Repository, https://github.com/slhck/ffmpeg-normalize
 Description-Content-Type: text/markdown
 
-# ffmpeg-normalize
+<h1 align="center">ffmpeg-normalize</h1>
+
+<p align="center">
+  <img src="icon.png" alt="ffmpeg-normalize logo" width="160" height="160">
+</p>
 
 [![PyPI version](https://img.shields.io/pypi/v/ffmpeg-normalize.svg)](https://pypi.org/project/ffmpeg-normalize)
 [![Docker Image Version](https://img.shields.io/docker/v/slhck/ffmpeg-normalize?sort=semver&label=Docker%20image)](https://hub.docker.com/r/slhck/ffmpeg-normalize)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/slhck/ffmpeg-normalize/python-package.yml)
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-23-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-24-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 A utility for batch-normalizing audio using ffmpeg.
@@ -50,6 +55,7 @@ This program normalizes media files to a certain loudness level using the EBU R1
 - 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
+- Self-documenting output — Optionally record the effective encoder settings as an `ENCODER_SETTINGS` tag
 - Video file support — Process video files while preserving video streams
 - Docker support — Run via Docker container
 - Python API — Use programmatically in your Python projects
@@ -65,6 +71,14 @@ This program normalizes media files to a certain loudness level using the EBU R1
 
 ## 🆕 What's New
 
+- Version 1.42.0 can optionally write an **`ENCODER_SETTINGS`** tag on each normalized audio stream via `--write-encoder-settings`. The tag holds an ffmpeg-command-equivalent string — the audio codec, bitrate, sample rate and channels, plus the normalization filter including the measured loudnorm values — so a normalized file documents how it was produced. This is a Matroska/WebM convention and has no effect with `--metadata-disable`.
+
+    Example:
+
+    ```bash
+    ffmpeg-normalize input.wav -c:a libopus -b:a 128k --write-encoder-settings -o output.mkv
+    ```
+
 - 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.
@@ -169,6 +183,7 @@ The only reason this project exists in its current form is because [@benjaoming]
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://davidbern.com/"><img src="https://avatars.githubusercontent.com/u/371066?v=4?s=100" width="100px;" alt="David Bern"/><br /><sub><b>David Bern</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=odie5533" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/randompersona1"><img src="https://avatars.githubusercontent.com/u/74961116?v=4?s=100" width="100px;" alt="randompersona1"/><br /><sub><b>randompersona1</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=randompersona1" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ppetr"><img src="https://avatars.githubusercontent.com/u/163061?v=4?s=100" width="100px;" alt="Petr"/><br /><sub><b>Petr</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=ppetr" title="Code">💻</a></td>
     </tr>
   </tbody>
   <tfoot>

{ffmpeg_normalize-1.41.1 → ffmpeg_normalize-1.42.1}/README.md

@@ -1,11 +1,15 @@
-# ffmpeg-normalize
+<h1 align="center">ffmpeg-normalize</h1>
+
+<p align="center">
+  <img src="icon.png" alt="ffmpeg-normalize logo" width="160" height="160">
+</p>
 
 [![PyPI version](https://img.shields.io/pypi/v/ffmpeg-normalize.svg)](https://pypi.org/project/ffmpeg-normalize)
 [![Docker Image Version](https://img.shields.io/docker/v/slhck/ffmpeg-normalize?sort=semver&label=Docker%20image)](https://hub.docker.com/r/slhck/ffmpeg-normalize)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/slhck/ffmpeg-normalize/python-package.yml)
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-23-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-24-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 A utility for batch-normalizing audio using ffmpeg.
@@ -19,6 +23,7 @@ This program normalizes media files to a certain loudness level using the EBU R1
 - 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
+- Self-documenting output — Optionally record the effective encoder settings as an `ENCODER_SETTINGS` tag
 - Video file support — Process video files while preserving video streams
 - Docker support — Run via Docker container
 - Python API — Use programmatically in your Python projects
@@ -34,6 +39,14 @@ This program normalizes media files to a certain loudness level using the EBU R1
 
 ## 🆕 What's New
 
+- Version 1.42.0 can optionally write an **`ENCODER_SETTINGS`** tag on each normalized audio stream via `--write-encoder-settings`. The tag holds an ffmpeg-command-equivalent string — the audio codec, bitrate, sample rate and channels, plus the normalization filter including the measured loudnorm values — so a normalized file documents how it was produced. This is a Matroska/WebM convention and has no effect with `--metadata-disable`.
+
+    Example:
+
+    ```bash
+    ffmpeg-normalize input.wav -c:a libopus -b:a 128k --write-encoder-settings -o output.mkv
+    ```
+
 - 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.
@@ -138,6 +151,7 @@ The only reason this project exists in its current form is because [@benjaoming]
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://davidbern.com/"><img src="https://avatars.githubusercontent.com/u/371066?v=4?s=100" width="100px;" alt="David Bern"/><br /><sub><b>David Bern</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=odie5533" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/randompersona1"><img src="https://avatars.githubusercontent.com/u/74961116?v=4?s=100" width="100px;" alt="randompersona1"/><br /><sub><b>randompersona1</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=randompersona1" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ppetr"><img src="https://avatars.githubusercontent.com/u/163061?v=4?s=100" width="100px;" alt="Petr"/><br /><sub><b>Petr</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=ppetr" title="Code">💻</a></td>
     </tr>
   </tbody>
   <tfoot>

ffmpeg_normalize-1.42.1/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["uv_build>=0.8.14,<1.0.0"]
+build-backend = "uv_build"
+
+[project]
+name = "ffmpeg-normalize"
+version = "1.42.1"
+description = "Normalize audio via ffmpeg"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.md"]
+keywords = [
+    "ffmpeg",
+    "normalize",
+    "audio",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Multimedia :: Sound/Audio :: Analysis",
+    "Topic :: Multimedia :: Sound/Audio :: Conversion",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "tqdm>=4.64.1",
+    "colorama>=0.4.6; platform_system=='Windows'",
+    "ffmpeg-progress-yield>=1.0.1",
+    "colorlog==6.7.0",
+    "mutagen>=1.47.0",
+]
+
+[[project.authors]]
+name = "Werner Robitza"
+email = "werner.robitza@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/slhck/ffmpeg-normalize"
+Repository = "https://github.com/slhck/ffmpeg-normalize"
+
+[project.scripts]
+ffmpeg-normalize = "ffmpeg_normalize.__main__:main"
+
+[tool.uv_build]
+src-layout = true
+
+[tool.uv_build.package-data]
+ffmpeg_normalize = ["data/**/*.json"]
+
+[tool.ty.rules]
+invalid-argument-type = "warn"
+too-many-positional-arguments = "warn"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "ruff>=0.12.11",
+    "types-tqdm",
+    "shtab>=1.7.0",
+    "ty>=0.0.24",
+]

ffmpeg_normalize-1.41.1/pyproject.toml → ffmpeg_normalize-1.42.1/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ffmpeg-normalize"
-version = "1.41.1"
+version = "1.42.1"
 description = "Normalize audio via ffmpeg"
 readme = "README.md"
 license = "MIT"
@@ -26,6 +26,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
 ]
 requires-python = ">=3.10"
 dependencies = [

{ffmpeg_normalize-1.41.1 → ffmpeg_normalize-1.42.1}/src/ffmpeg_normalize/__main__.py

@@ -562,6 +562,23 @@ def create_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Do not write chapters to output",
     )
+    group_vcodec.add_argument(
+        "--write-encoder-settings",
+        action="store_true",
+        help=textwrap.dedent(
+            """\
+        Write the effective encoder settings as an ENCODER_SETTINGS tag on each
+        normalized audio stream.
+
+        The tag holds an ffmpeg-command-equivalent string with the audio codec,
+        the bitrate, sample rate and channel count (when set), plus the
+        normalization filter including the measured loudnorm values.
+
+        This is a Matroska/WebM tag convention; other containers may store it
+        differently. Has no effect together with `--metadata-disable`.
+        """
+        ),
+    )
 
     group_format = parser.add_argument_group("Input/Output options")
     group_format.add_argument(
@@ -744,6 +761,7 @@ def main() -> None:
         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,

{ffmpeg_normalize-1.41.1 → ffmpeg_normalize-1.42.1}/src/ffmpeg_normalize/_cmd_utils.py

@@ -9,7 +9,7 @@ import subprocess
 import sys
 from contextlib import contextmanager
 from shutil import which
-from typing import Any, Iterator
+from typing import Any, Iterator, cast
 
 from ffmpeg_progress_yield import FfmpegProgress
 
@@ -161,13 +161,16 @@ class CommandRunner:
             _logger.debug("Dry mode specified, not actually running command")
             return self
 
-        p = subprocess.Popen(
-            cmd,
-            stdin=subprocess.PIPE,  # Apply stdin isolation by creating separate pipe.
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            universal_newlines=False,
-            **_get_ffmpeg_popen_kwargs(),
+        p = cast(
+            subprocess.Popen[bytes],
+            subprocess.Popen(
+                cmd,
+                stdin=subprocess.PIPE,  # Apply stdin isolation by creating separate pipe.
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=False,
+                **_get_ffmpeg_popen_kwargs(),
+            ),
         )
 
         stdout_bytes, stderr_bytes = p.communicate()

{ffmpeg_normalize-1.41.1 → ffmpeg_normalize-1.42.1}/src/ffmpeg_normalize/_ffmpeg_normalize.py

@@ -82,6 +82,7 @@ class FFmpegNormalize:
         subtitle_disable (bool, optional): Disable subtitles. Defaults to False.
         metadata_disable (bool, optional): Disable metadata. Defaults to False.
         chapters_disable (bool, optional): Disable chapters. Defaults to False.
+        write_encoder_settings (bool, optional): Write the effective encoder settings (codec, bitrate, sample rate, channels and the normalization filter including the measured loudnorm values) as an ENCODER_SETTINGS tag on each normalized audio stream. Defaults to False.
         extra_input_options (list, optional): Extra input options. Defaults to None.
         extra_output_options (list, optional): Extra output options. Defaults to None.
         output_format (str, optional): Output format. Defaults to None.
@@ -129,6 +130,7 @@ class FFmpegNormalize:
         "subtitle_disable": False,
         "metadata_disable": False,
         "chapters_disable": False,
+        "write_encoder_settings": False,
         "extra_input_options": None,
         "extra_output_options": None,
         "output_format": None,
@@ -173,6 +175,7 @@ class FFmpegNormalize:
         subtitle_disable: bool = False,
         metadata_disable: bool = False,
         chapters_disable: bool = False,
+        write_encoder_settings: bool = False,
         extra_input_options: list[str] | None = None,
         extra_output_options: list[str] | None = None,
         output_format: str | None = None,
@@ -257,6 +260,13 @@ class FFmpegNormalize:
         self.subtitle_disable = subtitle_disable
         self.metadata_disable = metadata_disable
         self.chapters_disable = chapters_disable
+        self.write_encoder_settings = write_encoder_settings
+
+        if self.write_encoder_settings and self.metadata_disable:
+            _logger.warning(
+                "write_encoder_settings has no effect together with metadata_disable; "
+                "no metadata will be written to the output."
+            )
 
         self.extra_input_options = extra_input_options
         self.extra_output_options = extra_output_options

{ffmpeg_normalize-1.41.1 → ffmpeg_normalize-1.42.1}/src/ffmpeg_normalize/_media_file.py

@@ -99,6 +99,10 @@ class MediaFile:
         self.streams: StreamDict = {"audio": {}, "video": {}, "subtitle": {}}
         self.temp_file: Union[str, None] = None
         self.batch_reference: float | None = None
+        # Second-pass filter chain per normalized audio stream, keyed by stream
+        # id. Populated by _get_audio_filter_cmd() and reused by
+        # _get_encoder_settings() so the normalization filter is not built twice.
+        self._stream_filter_chains: dict[int, list[str]] = {}
         # Input (access, modification) times captured before processing, used
         # when the keep_mtime option is enabled.
         self.input_timestamps: tuple[float, float] | None = None
@@ -768,6 +772,75 @@ class MediaFile:
                 for _ in fun():
                     pass
 
+    def _get_stream_filter_chain(self, audio_stream: AudioStream) -> list[str]:
+        """
+        Return the ordered list of ffmpeg audio filters applied to a single
+        stream in the second pass: the optional pre-filter, channel conversion,
+        the normalization filter itself (loudnorm for EBU, or the volume /
+        dynaudnorm filter for peak / RMS), and the optional post-filter.
+
+        Returns:
+            list[str]: the filters, in application order
+        """
+        skip_normalization = False
+        if self.ffmpeg_normalize.lower_only:
+            if self.ffmpeg_normalize.normalization_type == "ebu":
+                if (
+                    audio_stream.loudness_statistics["ebu_pass1"] is not None
+                    and audio_stream.loudness_statistics["ebu_pass1"]["input_i"]
+                    < self.ffmpeg_normalize.target_level
+                ):
+                    skip_normalization = True
+            elif self.ffmpeg_normalize.normalization_type == "peak":
+                if (
+                    audio_stream.loudness_statistics["max"] is not None
+                    and audio_stream.loudness_statistics["max"]
+                    < self.ffmpeg_normalize.target_level
+                ):
+                    skip_normalization = True
+            elif self.ffmpeg_normalize.normalization_type == "rms":
+                if (
+                    audio_stream.loudness_statistics["mean"] is not None
+                    and audio_stream.loudness_statistics["mean"]
+                    < self.ffmpeg_normalize.target_level
+                ):
+                    skip_normalization = True
+
+        if skip_normalization:
+            _logger.warning(
+                f"Stream {audio_stream.stream_id} had measured input loudness lower than target, skipping normalization."
+            )
+            normalization_filter = "acopy"
+        else:
+            if self.ffmpeg_normalize.normalization_type == "ebu":
+                normalization_filter = audio_stream.get_second_pass_opts_ebu(
+                    batch_reference=self.batch_reference
+                )
+            else:
+                normalization_filter = audio_stream.get_second_pass_opts_peakrms(
+                    batch_reference=self.batch_reference
+                )
+
+        filter_chain = []
+
+        if self.ffmpeg_normalize.pre_filter:
+            filter_chain.append(self.ffmpeg_normalize.pre_filter)
+
+        # Apply channel conversion before normalization so that the
+        # normalization filter operates on the same channel layout that
+        # was measured in the first pass. See issue #316.
+        if self.ffmpeg_normalize.audio_channels:
+            filter_chain.append(
+                f"aformat=sample_fmts=fltp:channel_layouts={self.ffmpeg_normalize.audio_channels}c"
+            )
+
+        filter_chain.append(normalization_filter)
+
+        if self.ffmpeg_normalize.post_filter:
+            filter_chain.append(self.ffmpeg_normalize.post_filter)
+
+        return filter_chain
+
     def _get_audio_filter_cmd(self) -> tuple[str, list[str]]:
         """
         Return the audio filter command and output labels needed.
@@ -778,76 +851,54 @@ class MediaFile:
         filter_chains = []
         output_labels = []
 
-        streams_to_normalize = self._get_streams_to_normalize()
+        self._stream_filter_chains = {}
 
-        for audio_stream in streams_to_normalize:
-            skip_normalization = False
-            if self.ffmpeg_normalize.lower_only:
-                if self.ffmpeg_normalize.normalization_type == "ebu":
-                    if (
-                        audio_stream.loudness_statistics["ebu_pass1"] is not None
-                        and audio_stream.loudness_statistics["ebu_pass1"]["input_i"]
-                        < self.ffmpeg_normalize.target_level
-                    ):
-                        skip_normalization = True
-                elif self.ffmpeg_normalize.normalization_type == "peak":
-                    if (
-                        audio_stream.loudness_statistics["max"] is not None
-                        and audio_stream.loudness_statistics["max"]
-                        < self.ffmpeg_normalize.target_level
-                    ):
-                        skip_normalization = True
-                elif self.ffmpeg_normalize.normalization_type == "rms":
-                    if (
-                        audio_stream.loudness_statistics["mean"] is not None
-                        and audio_stream.loudness_statistics["mean"]
-                        < self.ffmpeg_normalize.target_level
-                    ):
-                        skip_normalization = True
-
-            if skip_normalization:
-                _logger.warning(
-                    f"Stream {audio_stream.stream_id} had measured input loudness lower than target, skipping normalization."
-                )
-                normalization_filter = "acopy"
-            else:
-                if self.ffmpeg_normalize.normalization_type == "ebu":
-                    normalization_filter = audio_stream.get_second_pass_opts_ebu(
-                        batch_reference=self.batch_reference
-                    )
-                else:
-                    normalization_filter = audio_stream.get_second_pass_opts_peakrms(
-                        batch_reference=self.batch_reference
-                    )
+        for audio_stream in self._get_streams_to_normalize():
+            filter_chain = self._get_stream_filter_chain(audio_stream)
+            self._stream_filter_chains[audio_stream.stream_id] = filter_chain
 
             input_label = f"[0:{audio_stream.stream_id}]"
             output_label = f"[norm{audio_stream.stream_id}]"
             output_labels.append(output_label)
 
-            filter_chain = []
-
-            if self.ffmpeg_normalize.pre_filter:
-                filter_chain.append(self.ffmpeg_normalize.pre_filter)
-
-            # Apply channel conversion before normalization so that the
-            # normalization filter operates on the same channel layout that
-            # was measured in the first pass. See issue #316.
-            if self.ffmpeg_normalize.audio_channels:
-                filter_chain.append(
-                    f"aformat=sample_fmts=fltp:channel_layouts={self.ffmpeg_normalize.audio_channels}c"
-                )
-
-            filter_chain.append(normalization_filter)
-
-            if self.ffmpeg_normalize.post_filter:
-                filter_chain.append(self.ffmpeg_normalize.post_filter)
-
             filter_chains.append(input_label + ",".join(filter_chain) + output_label)
 
         filter_complex_cmd = ";".join(filter_chains)
 
         return filter_complex_cmd, output_labels
 
+    def _get_encoder_settings(
+        self, audio_stream: AudioStream, audio_codec: str | None
+    ) -> str:
+        """
+        Return an ffmpeg-command-equivalent description of how a single audio
+        stream is encoded in the second pass: the codec, then the bitrate,
+        sample rate and channel count when set, followed by the effective
+        filter chain (which includes the loudnorm measured values).
+
+        Written as the ``ENCODER_SETTINGS`` stream tag when
+        ``write_encoder_settings`` is enabled. The filter chain comes from the
+        cache populated by :meth:`_get_audio_filter_cmd`, which must run first.
+        The loudnorm ``print_format`` option is dropped, as it only controls
+        first-pass diagnostics and not the normalization itself.
+
+        Returns:
+            str: e.g. ``-c:a libopus -b:a 128000 -af loudnorm=i=-23.0:...``
+        """
+        codec = audio_codec if audio_codec else audio_stream.get_pcm_codec()
+        args = ["-c:a", codec]
+        if self.ffmpeg_normalize.audio_bitrate:
+            args += ["-b:a", str(self.ffmpeg_normalize.audio_bitrate)]
+        if self.ffmpeg_normalize.sample_rate:
+            args += ["-ar", str(self.ffmpeg_normalize.sample_rate)]
+        if self.ffmpeg_normalize.audio_channels:
+            args += ["-ac", str(self.ffmpeg_normalize.audio_channels)]
+        filter_chain = self._stream_filter_chains.get(audio_stream.stream_id, [])
+        if filter_chain:
+            af = re.sub(r":print_format=\w+", "", ",".join(filter_chain))
+            args += ["-af", af]
+        return shlex.join(args)
+
     def _get_audio_codec(self) -> str | None:
         """
         Return the audio encoder to use for normalized streams, or None to use
@@ -1011,6 +1062,21 @@ class MediaFile:
             for idx in range(len(streams_to_normalize)):
                 cmd.extend([f"-ac:a:{idx}", str(self.ffmpeg_normalize.audio_channels)])
 
+        # record how each normalized stream was encoded as an ENCODER_SETTINGS
+        # tag (a Matroska/WebM convention), so the output documents itself
+        if (
+            self.ffmpeg_normalize.write_encoder_settings
+            and not self.ffmpeg_normalize.metadata_disable
+        ):
+            for idx, audio_stream in enumerate(streams_to_normalize):
+                cmd.extend(
+                    [
+                        f"-metadata:s:a:{idx}",
+                        "ENCODER_SETTINGS="
+                        + self._get_encoder_settings(audio_stream, audio_codec),
+                    ]
+                )
+
         # 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):