ffmpeg-normalize 1.29.2__py2.py3-none-any.whl → 1.31.0__py2.py3-none-any.whl

ffmpeg_normalize/__main__.py

@@ -201,9 +201,7 @@ def create_parser() -> argparse.ArgumentParser:
         help=textwrap.dedent(
             """\
         Keep input loudness range above loudness range target.
-        - `LOUDNESS_RANGE_TARGET` for input loudness range `<= LOUDNESS_RANGE_TARGET` or
-        - keep input loudness range target above `LOUDNESS_RANGE_TARGET`.
-        as alternative to `--keep-loudness-range-target` to allow for linear normalization.
+        Can be used as an alternative to `--keep-loudness-range-target` to allow for linear normalization.
         """
         ),
     )
@@ -235,6 +233,34 @@ def create_parser() -> argparse.ArgumentParser:
         default=0.0,
     )
 
+    group_ebu.add_argument(
+        "--lower-only",
+        action="store_true",
+        help=textwrap.dedent(
+            """\
+        Whether the audio should not increase in loudness.
+
+        If the measured loudness from the first pass is lower than the target
+        loudness then normalization pass will be skipped for the measured audio
+        source.
+        """
+        ),
+    )
+
+    group_ebu.add_argument(
+        "--auto-lower-loudness-target",
+        action="store_true",
+        help=textwrap.dedent(
+            """\
+        Automatically lower EBU Integrated Loudness Target to prevent falling
+        back to dynamic filtering.
+
+        Makes sure target loudness is lower than measured loudness minus peak
+        loudness (input_i - input_tp) by a small amount (0.1 LUFS).
+        """
+        ),
+    )
+
     group_ebu.add_argument(
         "--dual-mono",
         action="store_true",
@@ -514,6 +540,8 @@ def main() -> None:
         keep_lra_above_loudness_range_target=cli_args.keep_lra_above_loudness_range_target,
         true_peak=cli_args.true_peak,
         offset=cli_args.offset,
+        lower_only=cli_args.lower_only,
+        auto_lower_loudness_target=cli_args.auto_lower_loudness_target,
         dual_mono=cli_args.dual_mono,
         dynamic=cli_args.dynamic,
         audio_codec=cli_args.audio_codec,

ffmpeg_normalize/_cmd_utils.py

@@ -7,7 +7,7 @@ import shlex
 import subprocess
 from platform import system
 from shutil import which
-from typing import Iterator
+from typing import Iterator, Any
 
 from ffmpeg_progress_yield import FfmpegProgress
 
@@ -128,12 +128,12 @@ class CommandRunner:
         return self.output
 
 
-def dict_to_filter_opts(opts: dict[str, object]) -> str:
+def dict_to_filter_opts(opts: dict[str, Any]) -> str:
     """
     Convert a dictionary to a ffmpeg filter option string
 
     Args:
-        opts (dict[str, object]): Dictionary of options
+        opts (dict[str, Any]): Dictionary of options
 
     Returns:
         str: Filter option string

ffmpeg_normalize/_ffmpeg_normalize.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import json
 import logging
 import os
+import sys
+from itertools import chain
 from typing import TYPE_CHECKING, Literal
 
 from tqdm import tqdm
@@ -58,6 +60,8 @@ class FFmpegNormalize:
         keep_lra_above_loudness_range_target (bool, optional): Keep input loudness range above loudness range target. Defaults to False.
         true_peak (float, optional): True peak. Defaults to -2.0.
         offset (float, optional): Offset. Defaults to 0.0.
+        lower_only (bool, optional): Whether the audio should not increase in loudness. Defaults to False.
+        auto_lower_loudness_target (bool, optional): Automatically lower EBU Integrated Loudness Target.
         dual_mono (bool, optional): Dual mono. Defaults to False.
         dynamic (bool, optional): Dynamic. Defaults to False.
         audio_codec (str, optional): Audio codec. Defaults to "pcm_s16le".
@@ -94,6 +98,8 @@ class FFmpegNormalize:
         keep_lra_above_loudness_range_target: bool = False,
         true_peak: float = -2.0,
         offset: float = 0.0,
+        lower_only: bool = False,
+        auto_lower_loudness_target: bool = False,
         dual_mono: bool = False,
         dynamic: bool = False,
         audio_codec: str = "pcm_s16le",
@@ -164,6 +170,8 @@ class FFmpegNormalize:
 
         self.true_peak = check_range(true_peak, -9, 0, name="true_peak")
         self.offset = check_range(offset, -99, 99, name="offset")
+        self.lower_only = lower_only
+        self.auto_lower_loudness_target = auto_lower_loudness_target
 
         # Ensure library user is passing correct types
         assert isinstance(dual_mono, bool), "dual_mono must be bool"
@@ -254,5 +262,6 @@ class FFmpegNormalize:
 
             _logger.info(f"Normalized file written to {media_file.output_file}")
 
-        if self.print_stats and self.stats:
-            print(json.dumps(self.stats, indent=4))
+        if self.print_stats:
+            json.dump(list(chain.from_iterable(media_file.get_stats() for media_file in self.media_files)), sys.stdout, indent=4)
+            print()

ffmpeg_normalize/_media_file.py

@@ -6,13 +6,18 @@ import re
 import shlex
 from shutil import move, rmtree
 from tempfile import mkdtemp
-from typing import TYPE_CHECKING, Iterator, Literal, TypedDict
+from typing import TYPE_CHECKING, Iterable, Iterator, Literal, TypedDict
 
 from tqdm import tqdm
 
 from ._cmd_utils import DUR_REGEX, NUL, CommandRunner
 from ._errors import FFmpegNormalizeError
-from ._streams import AudioStream, SubtitleStream, VideoStream
+from ._streams import (
+    AudioStream,
+    LoudnessStatisticsWithMetadata,
+    SubtitleStream,
+    VideoStream,
+)
 
 if TYPE_CHECKING:
     from ffmpeg_normalize import FFmpegNormalize
@@ -240,11 +245,6 @@ class MediaFile:
                 for _ in fun():
                     pass
 
-        # set initial stats (for dry-runs, this is the only thing we need to do)
-        self.ffmpeg_normalize.stats = [
-            audio_stream.get_stats() for audio_stream in self.streams["audio"].values()
-        ]
-
     def _get_audio_filter_cmd(self) -> tuple[str, list[str]]:
         """
         Return the audio filter command and output labels needed.
@@ -256,10 +256,40 @@ class MediaFile:
         output_labels = []
 
         for audio_stream in self.streams["audio"].values():
-            if self.ffmpeg_normalize.normalization_type == "ebu":
-                normalization_filter = audio_stream.get_second_pass_opts_ebu()
+            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:
-                normalization_filter = audio_stream.get_second_pass_opts_peakrms()
+                if self.ffmpeg_normalize.normalization_type == "ebu":
+                    normalization_filter = audio_stream.get_second_pass_opts_ebu()
+                else:
+                    normalization_filter = audio_stream.get_second_pass_opts_peakrms()
 
             input_label = f"[0:{audio_stream.stream_id}]"
             output_label = f"[norm{audio_stream.stream_id}]"
@@ -421,16 +451,10 @@ class MediaFile:
         # in the second pass, we do not normalize stream-by-stream, so we set the stats based on the
         # overall output (which includes multiple loudnorm stats)
         if self.ffmpeg_normalize.normalization_type == "ebu":
-            all_stats = AudioStream.prune_and_parse_loudnorm_output(
-                output, num_stats=len(self.streams["audio"])
-            )
-            for idx, audio_stream in enumerate(self.streams["audio"].values()):
-                audio_stream.set_second_pass_stats(all_stats[idx])
-
-        # collect all stats for the final report, again (overwrite the input)
-        self.ffmpeg_normalize.stats = [
-            audio_stream.get_stats() for audio_stream in self.streams["audio"].values()
-        ]
+            all_stats = AudioStream.prune_and_parse_loudnorm_output(output)
+            for stream_id, audio_stream in self.streams["audio"].items():
+                if stream_id in all_stats:
+                    audio_stream.set_second_pass_stats(all_stats[stream_id])
 
         # warn if self.media_file.ffmpeg_normalize.dynamic == False and any of the second pass stats contain "normalization_type" == "dynamic"
         if self.ffmpeg_normalize.dynamic is False:
@@ -446,3 +470,8 @@ class MediaFile:
                     )
 
         _logger.debug("Normalization finished")
+
+    def get_stats(self) -> Iterable[LoudnessStatisticsWithMetadata]:
+        return (
+            audio_stream.get_stats() for audio_stream in self.streams["audio"].values()
+        )

ffmpeg_normalize/_streams.py

@@ -15,6 +15,7 @@ if TYPE_CHECKING:
 
 _logger = logging.getLogger(__name__)
 
+_loudnorm_pattern = re.compile(r"\[Parsed_loudnorm_(\d+)")
 
 class EbuLoudnessStatistics(TypedDict):
     input_i: float
@@ -166,7 +167,7 @@ class AudioStream(MediaStream):
         }
         return stats
 
-    def set_second_pass_stats(self, stats: EbuLoudnessStatistics):
+    def set_second_pass_stats(self, stats: EbuLoudnessStatistics) -> None:
         """
         Set the EBU loudness statistics for the second pass.
 
@@ -320,58 +321,36 @@ class AudioStream(MediaStream):
             f"Loudnorm first pass command output: {CommandRunner.prune_ffmpeg_progress_from_output(output)}"
         )
 
-        self.loudness_statistics["ebu_pass1"] = (
-            AudioStream.prune_and_parse_loudnorm_output(
-                output, num_stats=1
-            )[0]  # only one stream
-        )
+        # only one stream
+        self.loudness_statistics["ebu_pass1"] = next(iter(AudioStream.prune_and_parse_loudnorm_output(output).values()))
 
     @staticmethod
     def prune_and_parse_loudnorm_output(
-        output: str, num_stats: int = 1
-    ) -> List[EbuLoudnessStatistics]:
+        output: str
+    ) -> dict[int, EbuLoudnessStatistics]:
         """
         Prune ffmpeg progress lines from output and parse the loudnorm filter output.
         There may be multiple outputs if multiple streams were processed.
 
         Args:
             output (str): The output from ffmpeg.
-            num_stats (int): The number of loudnorm statistics to parse.
 
         Returns:
             list: The EBU loudness statistics.
         """
         pruned_output = CommandRunner.prune_ffmpeg_progress_from_output(output)
         output_lines = [line.strip() for line in pruned_output.split("\n")]
-
-        ret = []
-        idx = 0
-        while True:
-            _logger.debug(f"Parsing loudnorm stats for stream {idx}")
-            loudnorm_stats = AudioStream._parse_loudnorm_output(
-                output_lines, stream_index=idx
-            )
-            idx += 1
-
-            if loudnorm_stats is None:
-                continue
-            ret.append(loudnorm_stats)
-
-            if len(ret) >= num_stats:
-                break
-
-        return ret
+        return AudioStream._parse_loudnorm_output(output_lines)
 
     @staticmethod
     def _parse_loudnorm_output(
-        output_lines: list[str], stream_index: Optional[int] = None
-    ) -> Optional[EbuLoudnessStatistics]:
+        output_lines: list[str]
+    ) -> dict[int, EbuLoudnessStatistics]:
         """
         Parse the output of a loudnorm filter to get the EBU loudness statistics.
 
         Args:
             output_lines (list[str]): The output lines of the loudnorm filter.
-            stream_index (int): The stream index, optional to filter out the correct stream. If unset, the first stream is used.
 
         Raises:
             FFmpegNormalizeError: When the output could not be parsed.
@@ -379,64 +358,58 @@ class AudioStream(MediaStream):
         Returns:
             EbuLoudnessStatistics: The EBU loudness statistics, if found.
         """
+        result = dict[int, EbuLoudnessStatistics]()
+        stream_index = -1
         loudnorm_start = 0
-        loudnorm_end = 0
         for index, line in enumerate(output_lines):
-            if line.startswith(f"[Parsed_loudnorm_{stream_index}"):
-                loudnorm_start = index + 1
-                continue
-            if loudnorm_start and line.startswith("}"):
-                loudnorm_end = index + 1
-                break
-
-        if not (loudnorm_start and loudnorm_end):
-            if stream_index is not None:
-                # not an error
-                return None
-
-            raise FFmpegNormalizeError(
-                "Could not parse loudnorm stats; no loudnorm-related output found"
-            )
-
-        try:
-            loudnorm_stats = json.loads(
-                "\n".join(output_lines[loudnorm_start:loudnorm_end])
-            )
-
-            _logger.debug(
-                f"Loudnorm stats for stream {stream_index} parsed: {json.dumps(loudnorm_stats)}"
-            )
-
-            for key in [
-                "input_i",
-                "input_tp",
-                "input_lra",
-                "input_thresh",
-                "output_i",
-                "output_tp",
-                "output_lra",
-                "output_thresh",
-                "target_offset",
-                "normalization_type",
-            ]:
-                if key not in loudnorm_stats:
-                    continue
-                if key == "normalization_type":
-                    loudnorm_stats[key] = loudnorm_stats[key].lower()
-                # handle infinite values
-                elif float(loudnorm_stats[key]) == -float("inf"):
-                    loudnorm_stats[key] = -99
-                elif float(loudnorm_stats[key]) == float("inf"):
-                    loudnorm_stats[key] = 0
-                else:
-                    # convert to floats
-                    loudnorm_stats[key] = float(loudnorm_stats[key])
-
-            return cast(EbuLoudnessStatistics, loudnorm_stats)
-        except Exception as e:
-            raise FFmpegNormalizeError(
-                f"Could not parse loudnorm stats; wrong JSON format in string: {e}"
-            )
+            if stream_index < 0:
+                if m := _loudnorm_pattern.match(line):
+                    loudnorm_start = index + 1
+                    stream_index = int(m.group(1))
+            else:
+                if line.startswith("}"):
+                    loudnorm_end = index + 1
+                    loudnorm_data = "\n".join(output_lines[loudnorm_start:loudnorm_end])
+
+                    try:
+                        loudnorm_stats = json.loads(loudnorm_data)
+
+                        _logger.debug(
+                            f"Loudnorm stats for stream {stream_index} parsed: {loudnorm_data}"
+                        )
+
+                        for key in [
+                            "input_i",
+                            "input_tp",
+                            "input_lra",
+                            "input_thresh",
+                            "output_i",
+                            "output_tp",
+                            "output_lra",
+                            "output_thresh",
+                            "target_offset",
+                            "normalization_type",
+                        ]:
+                            if key not in loudnorm_stats:
+                                continue
+                            if key == "normalization_type":
+                                loudnorm_stats[key] = loudnorm_stats[key].lower()
+                            # handle infinite values
+                            elif float(loudnorm_stats[key]) == -float("inf"):
+                                loudnorm_stats[key] = -99
+                            elif float(loudnorm_stats[key]) == float("inf"):
+                                loudnorm_stats[key] = 0
+                            else:
+                                # convert to floats
+                                loudnorm_stats[key] = float(loudnorm_stats[key])
+
+                        result[stream_index] = cast(EbuLoudnessStatistics, loudnorm_stats)
+                        stream_index = -1
+                    except Exception as e:
+                        raise FFmpegNormalizeError(
+                            f"Could not parse loudnorm stats; wrong JSON format in string: {e}"
+                        )
+        return result
 
     def get_second_pass_opts_ebu(self) -> str:
         """
@@ -508,26 +481,40 @@ class AudioStream(MediaStream):
                 "Specify -ar/--sample-rate to override it."
             )
 
+        target_level = self.ffmpeg_normalize.target_level
+        if self.ffmpeg_normalize.auto_lower_loudness_target:
+            safe_target = (
+                self.loudness_statistics["ebu_pass1"]["input_i"]
+                - self.loudness_statistics["ebu_pass1"]["input_tp"]
+                + self.ffmpeg_normalize.true_peak
+                - 0.1
+            )
+            if safe_target < self.ffmpeg_normalize.target_level:
+                target_level = safe_target
+                _logger.warning(
+                    f"Using loudness target {target_level} because --auto-lower-loudness-target given.",
+                )
+
         stats = self.loudness_statistics["ebu_pass1"]
 
         opts = {
-            "i": self.media_file.ffmpeg_normalize.target_level,
+            "i": target_level,
             "lra": self.media_file.ffmpeg_normalize.loudness_range_target,
             "tp": self.media_file.ffmpeg_normalize.true_peak,
             "offset": self._constrain(
-                float(stats["target_offset"]), -99, 99, name="target_offset"
+                stats["target_offset"], -99, 99, name="target_offset"
             ),
             "measured_i": self._constrain(
-                float(stats["input_i"]), -99, 0, name="input_i"
+                stats["input_i"], -99, 0, name="input_i"
             ),
             "measured_lra": self._constrain(
-                float(stats["input_lra"]), 0, 99, name="input_lra"
+                stats["input_lra"], 0, 99, name="input_lra"
             ),
             "measured_tp": self._constrain(
-                float(stats["input_tp"]), -99, 99, name="input_tp"
+                stats["input_tp"], -99, 99, name="input_tp"
             ),
             "measured_thresh": self._constrain(
-                float(stats["input_thresh"]), -99, 0, name="input_thresh"
+                stats["input_thresh"], -99, 0, name="input_thresh"
             ),
             "linear": "false" if self.media_file.ffmpeg_normalize.dynamic else "true",
             "print_format": "json",

ffmpeg_normalize/_version.py

@@ -1 +1 @@
-__version__ = "1.29.2"
+__version__ = "1.31.0"

{ffmpeg_normalize-1.29.2.dist-info → ffmpeg_normalize-1.31.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ffmpeg-normalize
-Version: 1.29.2
+Version: 1.31.0
 Summary: Normalize audio via ffmpeg
 Home-page: https://github.com/slhck/ffmpeg-normalize
 Author: Werner Robitza
@@ -15,12 +15,12 @@ Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.8
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: tqdm
@@ -35,7 +35,7 @@ Requires-Dist: colorama; platform_system == "Windows"
 ![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-19-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-20-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 A utility for batch-normalizing audio using ffmpeg.
@@ -58,6 +58,7 @@ Read on for more info.
 - [Requirements](#requirements)
   - [ffmpeg](#ffmpeg)
 - [Installation](#installation)
+  - [Shell Completions](#shell-completions)
 - [Usage with Docker](#usage-with-docker)
 - [High LeveL Introduction](#high-level-introduction)
 - [Basic Usage](#basic-usage)
@@ -73,6 +74,7 @@ Read on for more info.
   - [Environment Variables](#environment-variables)
 - [API](#api)
 - [FAQ](#faq)
+  - [My output file is too large?](#my-output-file-is-too-large)
   - [What options should I choose for the EBU R128 filter? What is linear and dynamic mode?](#what-options-should-i-choose-for-the-ebu-r128-filter-what-is-linear-and-dynamic-mode)
   - [The program doesn't work because the "loudnorm" filter can't be found](#the-program-doesnt-work-because-the-loudnorm-filter-cant-be-found)
   - [Should I use this to normalize my music collection?](#should-i-use-this-to-normalize-my-music-collection)
@@ -92,7 +94,7 @@ Read on for more info.
 
 ## Requirements
 
-You need Python 3.8 or higher, and ffmpeg.
+You need Python 3.9 or higher, and ffmpeg.
 
 ### ffmpeg
 
@@ -133,6 +135,54 @@ Or download this repository, then run `pip3 install .`.
 
 To later upgrade to the latest version, run `pip3 install --upgrade ffmpeg-normalize`.
 
+### Shell Completions
+
+This tool provides shell completions for bash and zsh. To install them:
+
+<!--
+Note to self: Generate the shtab ones with:
+
+  shtab --shell=bash -u ffmpeg_normalize.__main__.create_parser > completions/ffmpeg-normalize-shtab.bash
+  shtab --shell=zsh -u ffmpeg_normalize.__main__.create_parser > completions/ffmpeg-normalize-shtab.zsh
+
+but these are not properly working yet.
+-->
+
+#### Bash
+
+If you have [`bash-completion`](https://github.com/scop/bash-completion) installed, you can just copy your new completion script to the `/usr/local/etc/bash_completion.d` directory.
+
+```bash
+curl -L https://raw.githubusercontent.com/slhck/ffmpeg-normalize/master/completions/ffmpeg-normalize-completion.bash \
+  -o /usr/local/etc/bash_completion.d/ffmpeg-normalize
+```
+
+Without bash-completion, you can manually install the completion script:
+
+```bash
+# create completions directory if it doesn't exist
+mkdir -p ~/.bash_completions.d
+
+# download and install completion script
+curl -L https://raw.githubusercontent.com/slhck/ffmpeg-normalize/master/completions/ffmpeg-normalize-completion.bash \
+  -o ~/.bash_completions.d/ffmpeg-normalize
+
+# source it in your ~/.bashrc
+echo 'source ~/.bash_completions.d/ffmpeg-normalize' >> ~/.bashrc
+```
+
+#### Zsh
+
+Download the completion script and place it in the default `site-functions` directory:
+
+```bash
+curl -L https://raw.githubusercontent.com/slhck/ffmpeg-normalize/master/completions/ffmpeg-normalize.zsh \
+  -o /usr/local/share/zsh/site-functions/
+```
+
+You may choose any other directory that is in your `$FPATH` variable.
+Make sure your `.zshrc` file contains `autoload -Uz compinit && compinit`.
+
 ## Usage with Docker
 
 You can use the pre-built image from Docker Hub:
@@ -284,10 +334,7 @@ For more information on the options (`[options]`) available, run `ffmpeg-normali
 
 - `--keep-lra-above-loudness-range-target`: Keep input loudness range above loudness range target.
 
-  - `LOUDNESS_RANGE_TARGET` for input loudness range `<= LOUDNESS_RANGE_TARGET` or
-  - keep input loudness range target above `LOUDNESS_RANGE_TARGET`.
-
-  as alternative to `--keep-loudness-range-target` to allow for linear normalization.
+    Can be used as an alternative to `--keep-loudness-range-target` to allow for linear normalization.
 
 - `-tp TRUE_PEAK, --true-peak TRUE_PEAK`: EBU Maximum True Peak in dBTP (default: -2.0).
 
@@ -299,6 +346,16 @@ For more information on the options (`[options]`) available, run `ffmpeg-normali
 
     Range is -99.0 - +99.0.
 
+- `--lower-only`: Whether the audio should not increase in loudness.
+
+    If the measured loudness from the first pass is lower than the target loudness then normalization pass will be skipped for the measured audio source.
+
+- `--auto-lower-loudness-target`: Automatically lower EBU Integrated Loudness Target.
+
+    Automatically lower EBU Integrated Loudness Target to prevent falling back to dynamic filtering.
+
+    Makes sure target loudness is lower than measured loudness minus peak loudness (input_i - input_tp) by a small amount.
+
 - `--dual-mono`: Treat mono input files as "dual-mono".
 
     If a mono file is intended for playback on a stereo system, its EBU R128 measurement will be perceptually incorrect. If set, this option will compensate for this effect. Multi-channel input files are not affected by this option.
@@ -307,7 +364,7 @@ For more information on the options (`[options]`) available, run `ffmpeg-normali
 
     Instead of applying linear EBU R128 normalization, choose a dynamic normalization. This is not usually recommended.
 
-    Dynamic mode will automatically change the sample rate to 192 kHz. Use -ar/--sample-rate to specify a different output sample rate.
+    Dynamic mode will automatically change the sample rate to 192 kHz. Use `-ar`/`--sample-rate` to specify a different output sample rate.
 
 ### Audio Encoding
 
@@ -409,6 +466,16 @@ For more information see the [API documentation](https://htmlpreview.github.io/?
 
 ## FAQ
 
+### My output file is too large?
+
+This is because the default output codec is PCM, which is uncompressed. If you want to reduce the file size, you can specify an audio codec with `-c:a` (e.g., `-c:a aac` for ffmpeg's built-in AAC encoder), and optionally a bitrate with `-b:a`.
+
+For example:
+
+```bash
+ffmpeg-normalize input.wav -o output.m4a -c:a aac -b:a 192k
+```
+
 ### What options should I choose for the EBU R128 filter? What is linear and dynamic mode?
 
 EBU R128 is a method for normalizing audio loudness across different tracks or programs. It works by analyzing the audio content and adjusting it to meet specific loudness targets. The main components are:
@@ -433,7 +500,11 @@ For most cases, linear mode is recommended. Dynamic mode should only be used whe
 
 * When the required gain adjustment to meet the integrated loudness target would result in the true peak exceeding the specified true peak limit. This is because linear processing alone cannot reduce peaks without affecting the entire signal. For example, if a file needs to be amplified by 6 dB to reach the target integrated loudness, but doing so would push the true peak above the specified limit, the filter might switch to dynamic mode to handle this situation. If your content allows for it, you can increase the true peak target to give more headroom for linear processing. If you're consistently running into true peak issues, you might also consider lowering your target integrated loudness level.
 
-At this time, the `loudnorm` filter in ffmpeg does not provide a way to force linear mode when the input loudness range exceeds the target or when the true peak would be exceeded. The `--keep-loudness-range-target` option can be used to keep the input loudness range target above the specified target, but it will not force linear mode in all cases. We are working on a solution to handle this automatically!
+At this time, the `loudnorm` filter in ffmpeg does not provide a way to force linear mode when the input loudness range exceeds the target or when the true peak would be exceeded. There are some options to mitigate this:
+
+- The `--keep-lra-above-loudness-range-target` option can be used to keep the input loudness range above the specified target, but it will not force linear mode in all cases.
+- Similarly, the `--keep-loudness-range-target` option can be used to keep the input loudness range target.
+- The `--lower-only` option can be used to skip the normalization pass completely if the measured loudness is lower than the target loudness.
 
 ### The program doesn't work because the "loudnorm" filter can't be found
 
@@ -552,6 +623,7 @@ If you found this program useful and feel like giving back, feel free to send a
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/psavva"><img src="https://avatars.githubusercontent.com/u/1454758?v=4?s=100" width="100px;" alt="Panayiotis Savva"/><br /><sub><b>Panayiotis Savva</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=psavva" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/HighMans"><img src="https://avatars.githubusercontent.com/u/42877729?v=4?s=100" width="100px;" alt="HighMans"/><br /><sub><b>HighMans</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=HighMans" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/kanjieater"><img src="https://avatars.githubusercontent.com/u/32607317?v=4?s=100" width="100px;" alt="kanjieater"/><br /><sub><b>kanjieater</b></sub></a><br /><a href="#ideas-kanjieater" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://ahmetsait.com/"><img src="https://avatars.githubusercontent.com/u/8372246?v=4?s=100" width="100px;" alt="Ahmet Sait"/><br /><sub><b>Ahmet Sait</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=ahmetsait" title="Code">💻</a></td>
     </tr>
   </tbody>
   <tfoot>
@@ -599,6 +671,44 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 # Changelog
 
 
+## v1.31.0 (2024-12-15)
+
+* Update docs and completions.
+
+* Implement `--auto-lower-loudness-target`
+
+* Fix deprecations and mypy --strict errors.
+
+* Feat: add completions.
+
+* Docs: update explainer.
+
+* Docs: update docs to include lower-only.
+
+
+## v1.30.0 (2024-11-22)
+
+* Change lower-only message to warning.
+
+* Make setup name PEP 625 compliant.
+
+* Docs: add @ahmetsait as a contributor.
+
+* Implement `--lower-only`
+
+* Fix: `--print-stats` only outputs the last stream.
+
+* More robust `loudnorm` output parsing.
+
+* Remove unnecessary conversions.
+
+* Update .editorconfig.
+
+* Remove python 3.8, add python 3.12, 3.13.
+
+* Add README on file size.
+
+
 ## v1.29.2 (2024-11-18)
 
 * Fix: show percentage with two decimal digits in progress.

ffmpeg_normalize-1.31.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ffmpeg_normalize/__init__.py,sha256=aAhlk93ZE6SQcWUDzZQcw9vJh0bJcKEUNFGhVc5ZIto,453
+ffmpeg_normalize/__main__.py,sha256=AuyIcMU1WxGamczZtZyISfgMsEIt3Y1kSJ87dCoH9J4,19393
+ffmpeg_normalize/_cmd_utils.py,sha256=S7PLXQAZHmJ30RM9K6b--vXuxMf-cQHtaFOPtILxz-4,5360
+ffmpeg_normalize/_errors.py,sha256=brTQ4osJ4fTA8wnyMPVVYfGwJ0wqeShRFydTEwi_VEY,48
+ffmpeg_normalize/_ffmpeg_normalize.py,sha256=VoxhER57Ew0RKC_WcGpoCmyKKoqsHYuqNFMm7z4BPM4,11080
+ffmpeg_normalize/_logger.py,sha256=3Ap4Fxg7xGrzz7h4IGuNEf0KKstx0Rq_eLbHPrHzcrI,1841
+ffmpeg_normalize/_media_file.py,sha256=KUAjyI5hAGv5M-Y7NurrS8nmH0gelgIfw9CbLYWOWf8,17972
+ffmpeg_normalize/_streams.py,sha256=LIllXl4SKLxlyPVjD3ieHqc_byF2eUTjnK-clh2g_CY,20211
+ffmpeg_normalize/_version.py,sha256=jYtGJTa-bBcDTtE3IrYQBdcmjbk5Cfx7X6sxv2dEPwg,23
+ffmpeg_normalize/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ffmpeg_normalize-1.31.0.dist-info/LICENSE,sha256=zeqAHGWrSIwdPHsZMZv1_N0gGFO1xxjcZEz9CplR4EM,1086
+ffmpeg_normalize-1.31.0.dist-info/METADATA,sha256=TaXepF_i6VrztwLBsg8SEik_g3TOss4RQSTuX0RuUqI,60081
+ffmpeg_normalize-1.31.0.dist-info/WHEEL,sha256=fS9sRbCBHs7VFcwJLnLXN1MZRR0_TVTxvXKzOnaSFs8,110
+ffmpeg_normalize-1.31.0.dist-info/entry_points.txt,sha256=X0EC5ptb0iGOxrk3Aa65dVQtvUixngLd_2-iAtSixdc,68
+ffmpeg_normalize-1.31.0.dist-info/top_level.txt,sha256=wnUkr17ckPrrU1JsxZQiXbEBUnHKsC64yck-MemEBuI,17
+ffmpeg_normalize-1.31.0.dist-info/RECORD,,

ffmpeg_normalize-1.29.2.dist-info/RECORD

@@ -1,16 +0,0 @@
-ffmpeg_normalize/__init__.py,sha256=aAhlk93ZE6SQcWUDzZQcw9vJh0bJcKEUNFGhVc5ZIto,453
-ffmpeg_normalize/__main__.py,sha256=vIVZAKPyI7zO9K22FYeaE-q_4JeZAQg1xlQc0739Gqk,18603
-ffmpeg_normalize/_cmd_utils.py,sha256=A6quxjOl5tLHxgcs7SdMXzuOCP_JjUTzL1iUD4G7DJk,5361
-ffmpeg_normalize/_errors.py,sha256=brTQ4osJ4fTA8wnyMPVVYfGwJ0wqeShRFydTEwi_VEY,48
-ffmpeg_normalize/_ffmpeg_normalize.py,sha256=mARUHvgLwcs0yGsuDkkDZYqE2JJmnEZtkADKUS4giRc,10556
-ffmpeg_normalize/_logger.py,sha256=3Ap4Fxg7xGrzz7h4IGuNEf0KKstx0Rq_eLbHPrHzcrI,1841
-ffmpeg_normalize/_media_file.py,sha256=ym9t_J3Z_jCiL0YMGwk0-E0o3qg858d4-3JX7hAiFmk,16651
-ffmpeg_normalize/_streams.py,sha256=5zLlSK2vMTBs0HzBTmI5UiJVqSp1Nk19TZXpxNtjkIA,19973
-ffmpeg_normalize/_version.py,sha256=x7VlhF5gtHvQF5azFyGSActBYj8D2TvquvRXi3DdQdA,23
-ffmpeg_normalize/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ffmpeg_normalize-1.29.2.dist-info/LICENSE,sha256=zeqAHGWrSIwdPHsZMZv1_N0gGFO1xxjcZEz9CplR4EM,1086
-ffmpeg_normalize-1.29.2.dist-info/METADATA,sha256=En7t5Ll7zA6K2mbO9nCu5DqjZhHZJlyIPHZlZoW-N6M,56315
-ffmpeg_normalize-1.29.2.dist-info/WHEEL,sha256=fS9sRbCBHs7VFcwJLnLXN1MZRR0_TVTxvXKzOnaSFs8,110
-ffmpeg_normalize-1.29.2.dist-info/entry_points.txt,sha256=X0EC5ptb0iGOxrk3Aa65dVQtvUixngLd_2-iAtSixdc,68
-ffmpeg_normalize-1.29.2.dist-info/top_level.txt,sha256=wnUkr17ckPrrU1JsxZQiXbEBUnHKsC64yck-MemEBuI,17
-ffmpeg_normalize-1.29.2.dist-info/RECORD,,