ffmpeg-normalize 1.30.0__py2.py3-none-any.whl → 1.31.1__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.
         """
         ),
     )
@@ -249,6 +247,20 @@ def create_parser() -> argparse.ArgumentParser:
         ),
     )
 
+    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",
@@ -529,6 +541,7 @@ def main() -> None:
         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

@@ -61,6 +61,7 @@ class FFmpegNormalize:
         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".
@@ -98,6 +99,7 @@ class FFmpegNormalize:
         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",
@@ -169,6 +171,7 @@ 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"

ffmpeg_normalize/_media_file.py

@@ -177,8 +177,7 @@ class MediaFile:
             and len(self.streams["audio"].values()) > 1
         ):
             _logger.warning(
-                "Output file only supports one stream. "
-                "Keeping only first audio stream."
+                "Output file only supports one stream. Keeping only first audio stream."
             )
             first_stream = list(self.streams["audio"].values())[0]
             self.streams["audio"] = {first_stream.stream_id: first_stream}
@@ -281,7 +280,7 @@ class MediaFile:
                         skip_normalization = True
 
             if skip_normalization:
-                _logger.warn(
+                _logger.warning(
                     f"Stream {audio_stream.stream_id} had measured input loudness lower than target, skipping normalization."
                 )
                 normalization_filter = "acopy"
@@ -390,7 +389,12 @@ class MediaFile:
 
         # other audio options (if any)
         if self.ffmpeg_normalize.audio_bitrate:
-            cmd.extend(["-b:a", str(self.ffmpeg_normalize.audio_bitrate)])
+            if self.ffmpeg_normalize.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)])
+            else:
+                cmd.extend(["-b:a", str(self.ffmpeg_normalize.audio_bitrate)])
         if self.ffmpeg_normalize.sample_rate:
             cmd.extend(["-ar", str(self.ffmpeg_normalize.sample_rate)])
         if self.ffmpeg_normalize.audio_channels:

ffmpeg_normalize/_streams.py

@@ -167,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.
 
@@ -481,10 +481,24 @@ 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(

ffmpeg_normalize/_version.py

@@ -1 +1 @@
-__version__ = "1.30.0"
+__version__ = "1.31.1"

{ffmpeg_normalize-1.30.0.dist-info → ffmpeg_normalize-1.31.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ffmpeg-normalize
-Version: 1.30.0
+Version: 1.31.1
 Summary: Normalize audio via ffmpeg
 Home-page: https://github.com/slhck/ffmpeg-normalize
 Author: Werner Robitza
@@ -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)
@@ -134,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:
@@ -285,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).
 
@@ -300,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.
@@ -308,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
 
@@ -444,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
 
@@ -611,6 +671,30 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 # Changelog
 
 
+## v1.31.1 (2025-02-19)
+
+* Fix bitrate setting for libvorbis, fixes #277.
+
+* Update issue templates.
+
+* Prevent blank issues.
+
+
+## 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.

ffmpeg_normalize-1.31.1.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=BnFTOGOAxzofGS5k7ueG3k6LsUxro_VM6qWCQH5o81A,18258
+ffmpeg_normalize/_streams.py,sha256=LIllXl4SKLxlyPVjD3ieHqc_byF2eUTjnK-clh2g_CY,20211
+ffmpeg_normalize/_version.py,sha256=VFBXpgylen4bFLDe4KfNX1OmaXu_M6UnJYtTvQRQz4c,23
+ffmpeg_normalize/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ffmpeg_normalize-1.31.1.dist-info/LICENSE,sha256=zeqAHGWrSIwdPHsZMZv1_N0gGFO1xxjcZEz9CplR4EM,1086
+ffmpeg_normalize-1.31.1.dist-info/METADATA,sha256=Trwdo0wpKwL38BgLgBLXzAWhqyMjhEnKDgL2jFHtMXU,60209
+ffmpeg_normalize-1.31.1.dist-info/WHEEL,sha256=fS9sRbCBHs7VFcwJLnLXN1MZRR0_TVTxvXKzOnaSFs8,110
+ffmpeg_normalize-1.31.1.dist-info/entry_points.txt,sha256=X0EC5ptb0iGOxrk3Aa65dVQtvUixngLd_2-iAtSixdc,68
+ffmpeg_normalize-1.31.1.dist-info/top_level.txt,sha256=wnUkr17ckPrrU1JsxZQiXbEBUnHKsC64yck-MemEBuI,17
+ffmpeg_normalize-1.31.1.dist-info/RECORD,,

ffmpeg_normalize-1.30.0.dist-info/RECORD

@@ -1,16 +0,0 @@
-ffmpeg_normalize/__init__.py,sha256=aAhlk93ZE6SQcWUDzZQcw9vJh0bJcKEUNFGhVc5ZIto,453
-ffmpeg_normalize/__main__.py,sha256=mixrjY4XggMMpy31Q23MtUj85LB4EUQxlE-_mpVgrbk,19035
-ffmpeg_normalize/_cmd_utils.py,sha256=A6quxjOl5tLHxgcs7SdMXzuOCP_JjUTzL1iUD4G7DJk,5361
-ffmpeg_normalize/_errors.py,sha256=brTQ4osJ4fTA8wnyMPVVYfGwJ0wqeShRFydTEwi_VEY,48
-ffmpeg_normalize/_ffmpeg_normalize.py,sha256=9AkUoUi-qLH8fPjw4aZcKA3NDCpfBjfPtGhebpZFgZs,10856
-ffmpeg_normalize/_logger.py,sha256=3Ap4Fxg7xGrzz7h4IGuNEf0KKstx0Rq_eLbHPrHzcrI,1841
-ffmpeg_normalize/_media_file.py,sha256=tOtoVc931ynCI-BkbBWw2sMsMy9ZdactiwRZGFTTazs,17969
-ffmpeg_normalize/_streams.py,sha256=dAwhlSirx4OlW_IoWcOSedB2BCRnIAAeWMbjWQi-QP8,19605
-ffmpeg_normalize/_version.py,sha256=a214_SpyTblEsutXQ0q4k-AFdSRCCSNLN1gRUBDn6x4,23
-ffmpeg_normalize/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ffmpeg_normalize-1.30.0.dist-info/LICENSE,sha256=zeqAHGWrSIwdPHsZMZv1_N0gGFO1xxjcZEz9CplR4EM,1086
-ffmpeg_normalize-1.30.0.dist-info/METADATA,sha256=Zem-Rn-UkzYuhKGR6uanCFDG_Doea_DzKpCIGa5cJqw,57487
-ffmpeg_normalize-1.30.0.dist-info/WHEEL,sha256=fS9sRbCBHs7VFcwJLnLXN1MZRR0_TVTxvXKzOnaSFs8,110
-ffmpeg_normalize-1.30.0.dist-info/entry_points.txt,sha256=X0EC5ptb0iGOxrk3Aa65dVQtvUixngLd_2-iAtSixdc,68
-ffmpeg_normalize-1.30.0.dist-info/top_level.txt,sha256=wnUkr17ckPrrU1JsxZQiXbEBUnHKsC64yck-MemEBuI,17
-ffmpeg_normalize-1.30.0.dist-info/RECORD,,