ffmpeg-normalize 1.28.2__tar.gz → 1.28.3__tar.gz

{ffmpeg-normalize-1.28.2 → ffmpeg-normalize-1.28.3}/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
 
+## v1.28.3 (2024-08-16)
+
+* Make colorama dependency windows-only.
+
+* Update.
+
+* Update badges.
+
+* Docs: add @kanjieater as a contributor.
+
+
 ## v1.28.2 (2024-06-22)
 
 * Provide an entrypoint for the Docker image.

{ffmpeg-normalize-1.28.2/ffmpeg_normalize.egg-info → ffmpeg-normalize-1.28.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ffmpeg-normalize
-Version: 1.28.2
+Version: 1.28.3
 Summary: Normalize audio via ffmpeg
 Home-page: https://github.com/slhck/ffmpeg-normalize
 Author: Werner Robitza
@@ -25,13 +25,13 @@ License-File: LICENSE
 
 # ffmpeg-normalize
 
-<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-18-orange.svg?style=flat-square)](#contributors-)
-<!-- ALL-CONTRIBUTORS-BADGE:END -->
-
 [![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)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/slhck/ffmpeg-normalize/python-package.yml)
 
-[![Python package](https://github.com/slhck/ffmpeg-normalize/actions/workflows/python-package.yml/badge.svg)](https://github.com/slhck/ffmpeg-normalize/actions/workflows/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-BADGE:END -->
 
 A utility for batch-normalizing audio using ffmpeg.
 
@@ -54,9 +54,8 @@ Read on for more info.
   - [ffmpeg](#ffmpeg)
 - [Installation](#installation)
 - [Usage with Docker](#usage-with-docker)
-  - [From Docker Hub](#from-docker-hub)
-- [Usage](#usage)
-- [Description](#description)
+- [High LeveL Introduction](#high-level-introduction)
+- [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Detailed Options](#detailed-options)
   - [File Input/Output](#file-inputoutput)
@@ -69,10 +68,11 @@ Read on for more info.
   - [Environment Variables](#environment-variables)
 - [API](#api)
 - [FAQ](#faq)
+  - [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)
   - [Why are my output files MKV?](#why-are-my-output-files-mkv)
-  - ["Could not write header for output file" error](#could-not-write-header-for-output-file-error)
+  - [I get a "Could not write header for output file" error](#i-get-a-could-not-write-header-for-output-file-error)
   - [The conversion does not work and I get a cryptic ffmpeg error!](#the-conversion-does-not-work-and-i-get-a-cryptic-ffmpeg-error)
   - [What are the different normalization algorithms?](#what-are-the-different-normalization-algorithms)
   - [Couldn't I just run `loudnorm` with ffmpeg?](#couldnt-i-just-run-loudnorm-with-ffmpeg)
@@ -87,7 +87,7 @@ Read on for more info.
 
 ## Requirements
 
-You need Python 3.8 or higher.
+You need Python 3.8 or higher, and ffmpeg.
 
 ### ffmpeg
 
@@ -126,9 +126,9 @@ pip3 install ffmpeg-normalize
 
 Or download this repository, then run `pip3 install .`.
 
-## Usage with Docker
+To later upgrade to the latest version, run `pip3 install --upgrade ffmpeg-normalize`.
 
-### From Docker Hub
+## Usage with Docker
 
 You can use the pre-built image from Docker Hub:
 
@@ -138,7 +138,7 @@ docker run -v "$(pwd):/tmp" -it slhck/ffmpeg-normalize
 
 Alternatively, download this repository and run
 
-```
+```bash
 docker build -t ffmpeg-normalize .
 ```
 
@@ -156,45 +156,31 @@ docker run  -v "$(pwd):/tmp" -it ffmpeg-normalize /tmp/yourfile.mp4 -o /tmp/your
 
 You will then find the normalized file in your current directory.
 
-## Usage
-
-```bash
-ffmpeg-normalize input [input ...][-h][-o OUTPUT [OUTPUT ...]] [options]
-```
-
-Example:
-
-```bash
-ffmpeg-normalize 1.wav 2.wav -o 1-normalized.m4a 2-normalized.m4a -c:a aac -b:a 192k
-```
-
-For more information on the options (`[options]`) available, run `ffmpeg-normalize -h`, or read on.
-
-## Description
+## High LeveL Introduction
 
 Please read this section for a high level introduction.
 
 **What does the program do?**
 
-The program takes one or more input files and, by default, writes them to a folder called `normalized`, using an `.mkv` container. All audio streams will be normalized so that they have the same (perceived) volume.
+The program takes one or more input files and, by default, writes them to a folder called `normalized`, using an `.mkv` container. All audio streams will be normalized so that they have the same (perceived) volume according to the EBU R128 standard. This is done by analyzing the audio streams and applying a filter to bring them to a target level. Under the hood, the program uses ffmpeg's `loudnorm` filter to do this.
 
 **How do I specify the input?**
 
-Just give the program one or more input files as arguments. It works with most media files.
+Just give the program one or more input files as arguments. It works with most media files, including video files.
 
 **How do I specify the output?**
 
-You can specify one output file name for each input file with the `-o` option. In this case, the container format (e.g. `.wav`) will be inferred from the file name extension that you've given.
+You don't have to specify an output file name (the default is `normalized/<input>.mkv`), but if you want to override it, you can specify one output file name for each input file with the `-o` option. In this case, the container format (e.g. `.wav`) will be inferred from the file name extension that you've given.
 
 Example:
 
-```
-ffmpeg-normalize 1.wav 2.wav -o 1n.wav 2n.wav
+```bash
+ffmpeg-normalize 1.wav 2.wav -o 1-normalized.wav 2-normalized.wav
 ```
 
-If you don't specify the output file name for an input file, the container format will be MKV, and the output will be written to `normalized/<input>.mkv`.
+Note that if you don't specify the output file name for an input file, the container format will be MKV, and the output will be written to `normalized/<input>.mkv`. The reason for choosing the MKV container is that it can handle almost any codec combination.
 
-Using the `-ext` option, you can supply a different output extension common to all output files, e.g. `-ext m4a`.
+Using the `-ext` option, you can supply a different output extension common to all output files, e.g. `-ext m4a`. However, you need to make sure that the container supports the codecs used for the output (see below).
 
 **What will get normalized?**
 
@@ -202,7 +188,7 @@ By default, all streams from the input file will be written to the output file.
 
 **How will the normalization be done?**
 
-The normalization will be performed with the [`loudnorm` filter](https://ffmpeg.org/ffmpeg-filters.html#loudnorm) from FFmpeg, which was [originally written by Kyle Swanson](https://k.ylo.ph/2016/04/04/loudnorm.html). It will bring the audio to a specified target level. This ensures that multiple files normalized with this filter will have the same perceived loudness.
+The normalization will be performed according to the EBU R128 algorithm with the [`loudnorm` filter](https://ffmpeg.org/ffmpeg-filters.html#loudnorm) from FFmpeg, which was [originally written by Kyle Swanson](https://k.ylo.ph/2016/04/04/loudnorm.html). It will bring the audio to a specified target level. This ensures that multiple files normalized with this filter will have the same perceived loudness.
 
 **What codec is chosen?**
 
@@ -210,6 +196,22 @@ The default audio encoding method is uncompressed PCM (`pcm_s16le`) to avoid int
 
 Some containers (like MP4) also cannot handle PCM audio. If you want to use such containers and/or keep the file size down, use `-c:a` and specify an audio codec (e.g., `-c:a aac` for ffmpeg's built-in AAC encoder).
 
+## Basic Usage
+
+Supply one or more input files, and optionally, output file names:
+
+```bash
+ffmpeg-normalize input [input ...][-h][-o OUTPUT [OUTPUT ...]] [options]
+```
+
+Example:
+
+```bash
+ffmpeg-normalize 1.wav 2.wav -o 1-normalized.m4a 2-normalized.m4a -c:a aac -b:a 192k
+```
+
+For more information on the options (`[options]`) available, run `ffmpeg-normalize -h`, or read on.
+
 ## Examples
 
 [Read the examples on the wiki.](https://github.com/slhck/ffmpeg-normalize/wiki/examples)
@@ -400,6 +402,32 @@ For more information see the [API documentation](https://htmlpreview.github.io/?
 
 ## FAQ
 
+### 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:
+
+* Integrated Loudness (I): The overall loudness of the entire audio.
+* Loudness Range (LRA): The variation in loudness over time.
+* True Peak (TP): The maximum level of the audio signal.
+
+The normalization process involves measuring these values (input) and then applying gain adjustments to meet target levels (output), typically -23 LUFS for integrated loudness. You can also specify a target loudness range (LRA) and true peak level (TP).
+
+**Linear mode** applies a constant gain adjustment across the entire audio file. This is generally preferred because:
+
+* It preserves the original dynamic range of the audio.
+* It maintains the relative loudness between different parts of the audio.
+* It avoids potential artifacts or pumping effects that can occur with dynamic processing.
+
+**Dynamic mode**, on the other hand, can change the volume dynamically throughout the file. While this can achieve more consistent loudness, it may alter the original artistic intent and potentially introduce audible artifacts (possibly due to some bugs in the ffmpeg filter).
+
+For most cases, linear mode is recommended. Dynamic mode should only be used when linear mode is not suitable or when a specific effect is desired. In some cases, `loudnorm` will still fall back to dynamic mode, and a warning will be printed to the console. Here's when this can happen:
+
+* When the input loudness range (LRA) is larger than the target loudness range: If the input file has a loudness range that exceeds the specified loudness range target, the loudnorm filter will automatically switch to dynamic mode. This is because linear normalization alone cannot reduce the loudness range without dynamic processing (limiting). The `--keep-loudness-range-target` option can be used to keep the input loudness range target above the specified target.
+
+* 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!
+
 ### The program doesn't work because the "loudnorm" filter can't be found
 
 Make sure you run a recent ffmpeg version and that `loudnorm` is part of the output when you run `ffmpeg -filters`. Many distributions package outdated ffmpeg versions, or (even worse), Libav's `ffmpeg` disguising as a real `ffmpeg` from the FFmpeg project.
@@ -412,13 +440,15 @@ If you have to use an outdated ffmpeg version, you can only use `rms` or `peak`
 
 ### Should I use this to normalize my music collection?
 
+Generally, no.
+
 When you run `ffmpeg-normalize` and re-encode files with MP3 or AAC, you will inevitably introduce [generation loss](https://en.wikipedia.org/wiki/Generation_loss). Therefore, I do not recommend running this on your precious music collection, unless you have a backup of the originals or accept potential quality reduction. If you just want to normalize the subjective volume of the files without changing the actual content, consider using [MP3Gain](http://mp3gain.sourceforge.net/) and [aacgain](http://aacgain.altosdesign.com/).
 
 ### Why are my output files MKV?
 
 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.
 
-### "Could not write header for output file" error
+### 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).
 
@@ -514,6 +544,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/sian1468"><img src="https://avatars.githubusercontent.com/u/58017832?v=4?s=100" width="100px;" alt="sian1468"/><br /><sub><b>sian1468</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=sian1468" title="Tests">⚠️</a></td>
       <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>
     </tr>
   </tbody>
   <tfoot>
@@ -561,6 +592,17 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 # Changelog
 
 
+## v1.28.3 (2024-08-16)
+
+* Make colorama dependency windows-only.
+
+* Update.
+
+* Update badges.
+
+* Docs: add @kanjieater as a contributor.
+
+
 ## v1.28.2 (2024-06-22)
 
 * Provide an entrypoint for the Docker image.

{ffmpeg-normalize-1.28.2 → ffmpeg-normalize-1.28.3}/README.md

@@ -1,12 +1,12 @@
 # ffmpeg-normalize
 
-<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-18-orange.svg?style=flat-square)](#contributors-)
-<!-- ALL-CONTRIBUTORS-BADGE:END -->
-
 [![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)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/slhck/ffmpeg-normalize/python-package.yml)
 
-[![Python package](https://github.com/slhck/ffmpeg-normalize/actions/workflows/python-package.yml/badge.svg)](https://github.com/slhck/ffmpeg-normalize/actions/workflows/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-BADGE:END -->
 
 A utility for batch-normalizing audio using ffmpeg.
 
@@ -29,9 +29,8 @@ Read on for more info.
   - [ffmpeg](#ffmpeg)
 - [Installation](#installation)
 - [Usage with Docker](#usage-with-docker)
-  - [From Docker Hub](#from-docker-hub)
-- [Usage](#usage)
-- [Description](#description)
+- [High LeveL Introduction](#high-level-introduction)
+- [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Detailed Options](#detailed-options)
   - [File Input/Output](#file-inputoutput)
@@ -44,10 +43,11 @@ Read on for more info.
   - [Environment Variables](#environment-variables)
 - [API](#api)
 - [FAQ](#faq)
+  - [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)
   - [Why are my output files MKV?](#why-are-my-output-files-mkv)
-  - ["Could not write header for output file" error](#could-not-write-header-for-output-file-error)
+  - [I get a "Could not write header for output file" error](#i-get-a-could-not-write-header-for-output-file-error)
   - [The conversion does not work and I get a cryptic ffmpeg error!](#the-conversion-does-not-work-and-i-get-a-cryptic-ffmpeg-error)
   - [What are the different normalization algorithms?](#what-are-the-different-normalization-algorithms)
   - [Couldn't I just run `loudnorm` with ffmpeg?](#couldnt-i-just-run-loudnorm-with-ffmpeg)
@@ -62,7 +62,7 @@ Read on for more info.
 
 ## Requirements
 
-You need Python 3.8 or higher.
+You need Python 3.8 or higher, and ffmpeg.
 
 ### ffmpeg
 
@@ -101,9 +101,9 @@ pip3 install ffmpeg-normalize
 
 Or download this repository, then run `pip3 install .`.
 
-## Usage with Docker
+To later upgrade to the latest version, run `pip3 install --upgrade ffmpeg-normalize`.
 
-### From Docker Hub
+## Usage with Docker
 
 You can use the pre-built image from Docker Hub:
 
@@ -113,7 +113,7 @@ docker run -v "$(pwd):/tmp" -it slhck/ffmpeg-normalize
 
 Alternatively, download this repository and run
 
-```
+```bash
 docker build -t ffmpeg-normalize .
 ```
 
@@ -131,45 +131,31 @@ docker run  -v "$(pwd):/tmp" -it ffmpeg-normalize /tmp/yourfile.mp4 -o /tmp/your
 
 You will then find the normalized file in your current directory.
 
-## Usage
-
-```bash
-ffmpeg-normalize input [input ...][-h][-o OUTPUT [OUTPUT ...]] [options]
-```
-
-Example:
-
-```bash
-ffmpeg-normalize 1.wav 2.wav -o 1-normalized.m4a 2-normalized.m4a -c:a aac -b:a 192k
-```
-
-For more information on the options (`[options]`) available, run `ffmpeg-normalize -h`, or read on.
-
-## Description
+## High LeveL Introduction
 
 Please read this section for a high level introduction.
 
 **What does the program do?**
 
-The program takes one or more input files and, by default, writes them to a folder called `normalized`, using an `.mkv` container. All audio streams will be normalized so that they have the same (perceived) volume.
+The program takes one or more input files and, by default, writes them to a folder called `normalized`, using an `.mkv` container. All audio streams will be normalized so that they have the same (perceived) volume according to the EBU R128 standard. This is done by analyzing the audio streams and applying a filter to bring them to a target level. Under the hood, the program uses ffmpeg's `loudnorm` filter to do this.
 
 **How do I specify the input?**
 
-Just give the program one or more input files as arguments. It works with most media files.
+Just give the program one or more input files as arguments. It works with most media files, including video files.
 
 **How do I specify the output?**
 
-You can specify one output file name for each input file with the `-o` option. In this case, the container format (e.g. `.wav`) will be inferred from the file name extension that you've given.
+You don't have to specify an output file name (the default is `normalized/<input>.mkv`), but if you want to override it, you can specify one output file name for each input file with the `-o` option. In this case, the container format (e.g. `.wav`) will be inferred from the file name extension that you've given.
 
 Example:
 
-```
-ffmpeg-normalize 1.wav 2.wav -o 1n.wav 2n.wav
+```bash
+ffmpeg-normalize 1.wav 2.wav -o 1-normalized.wav 2-normalized.wav
 ```
 
-If you don't specify the output file name for an input file, the container format will be MKV, and the output will be written to `normalized/<input>.mkv`.
+Note that if you don't specify the output file name for an input file, the container format will be MKV, and the output will be written to `normalized/<input>.mkv`. The reason for choosing the MKV container is that it can handle almost any codec combination.
 
-Using the `-ext` option, you can supply a different output extension common to all output files, e.g. `-ext m4a`.
+Using the `-ext` option, you can supply a different output extension common to all output files, e.g. `-ext m4a`. However, you need to make sure that the container supports the codecs used for the output (see below).
 
 **What will get normalized?**
 
@@ -177,7 +163,7 @@ By default, all streams from the input file will be written to the output file.
 
 **How will the normalization be done?**
 
-The normalization will be performed with the [`loudnorm` filter](https://ffmpeg.org/ffmpeg-filters.html#loudnorm) from FFmpeg, which was [originally written by Kyle Swanson](https://k.ylo.ph/2016/04/04/loudnorm.html). It will bring the audio to a specified target level. This ensures that multiple files normalized with this filter will have the same perceived loudness.
+The normalization will be performed according to the EBU R128 algorithm with the [`loudnorm` filter](https://ffmpeg.org/ffmpeg-filters.html#loudnorm) from FFmpeg, which was [originally written by Kyle Swanson](https://k.ylo.ph/2016/04/04/loudnorm.html). It will bring the audio to a specified target level. This ensures that multiple files normalized with this filter will have the same perceived loudness.
 
 **What codec is chosen?**
 
@@ -185,6 +171,22 @@ The default audio encoding method is uncompressed PCM (`pcm_s16le`) to avoid int
 
 Some containers (like MP4) also cannot handle PCM audio. If you want to use such containers and/or keep the file size down, use `-c:a` and specify an audio codec (e.g., `-c:a aac` for ffmpeg's built-in AAC encoder).
 
+## Basic Usage
+
+Supply one or more input files, and optionally, output file names:
+
+```bash
+ffmpeg-normalize input [input ...][-h][-o OUTPUT [OUTPUT ...]] [options]
+```
+
+Example:
+
+```bash
+ffmpeg-normalize 1.wav 2.wav -o 1-normalized.m4a 2-normalized.m4a -c:a aac -b:a 192k
+```
+
+For more information on the options (`[options]`) available, run `ffmpeg-normalize -h`, or read on.
+
 ## Examples
 
 [Read the examples on the wiki.](https://github.com/slhck/ffmpeg-normalize/wiki/examples)
@@ -375,6 +377,32 @@ For more information see the [API documentation](https://htmlpreview.github.io/?
 
 ## FAQ
 
+### 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:
+
+* Integrated Loudness (I): The overall loudness of the entire audio.
+* Loudness Range (LRA): The variation in loudness over time.
+* True Peak (TP): The maximum level of the audio signal.
+
+The normalization process involves measuring these values (input) and then applying gain adjustments to meet target levels (output), typically -23 LUFS for integrated loudness. You can also specify a target loudness range (LRA) and true peak level (TP).
+
+**Linear mode** applies a constant gain adjustment across the entire audio file. This is generally preferred because:
+
+* It preserves the original dynamic range of the audio.
+* It maintains the relative loudness between different parts of the audio.
+* It avoids potential artifacts or pumping effects that can occur with dynamic processing.
+
+**Dynamic mode**, on the other hand, can change the volume dynamically throughout the file. While this can achieve more consistent loudness, it may alter the original artistic intent and potentially introduce audible artifacts (possibly due to some bugs in the ffmpeg filter).
+
+For most cases, linear mode is recommended. Dynamic mode should only be used when linear mode is not suitable or when a specific effect is desired. In some cases, `loudnorm` will still fall back to dynamic mode, and a warning will be printed to the console. Here's when this can happen:
+
+* When the input loudness range (LRA) is larger than the target loudness range: If the input file has a loudness range that exceeds the specified loudness range target, the loudnorm filter will automatically switch to dynamic mode. This is because linear normalization alone cannot reduce the loudness range without dynamic processing (limiting). The `--keep-loudness-range-target` option can be used to keep the input loudness range target above the specified target.
+
+* 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!
+
 ### The program doesn't work because the "loudnorm" filter can't be found
 
 Make sure you run a recent ffmpeg version and that `loudnorm` is part of the output when you run `ffmpeg -filters`. Many distributions package outdated ffmpeg versions, or (even worse), Libav's `ffmpeg` disguising as a real `ffmpeg` from the FFmpeg project.
@@ -387,13 +415,15 @@ If you have to use an outdated ffmpeg version, you can only use `rms` or `peak`
 
 ### Should I use this to normalize my music collection?
 
+Generally, no.
+
 When you run `ffmpeg-normalize` and re-encode files with MP3 or AAC, you will inevitably introduce [generation loss](https://en.wikipedia.org/wiki/Generation_loss). Therefore, I do not recommend running this on your precious music collection, unless you have a backup of the originals or accept potential quality reduction. If you just want to normalize the subjective volume of the files without changing the actual content, consider using [MP3Gain](http://mp3gain.sourceforge.net/) and [aacgain](http://aacgain.altosdesign.com/).
 
 ### Why are my output files MKV?
 
 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.
 
-### "Could not write header for output file" error
+### 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).
 
@@ -489,6 +519,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/sian1468"><img src="https://avatars.githubusercontent.com/u/58017832?v=4?s=100" width="100px;" alt="sian1468"/><br /><sub><b>sian1468</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=sian1468" title="Tests">⚠️</a></td>
       <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>
     </tr>
   </tbody>
   <tfoot>

ffmpeg-normalize-1.28.3/ffmpeg_normalize/_version.py

@@ -0,0 +1 @@
+__version__ = "1.28.3"

{ffmpeg-normalize-1.28.2 → ffmpeg-normalize-1.28.3/ffmpeg_normalize.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ffmpeg-normalize
-Version: 1.28.2
+Version: 1.28.3
 Summary: Normalize audio via ffmpeg
 Home-page: https://github.com/slhck/ffmpeg-normalize
 Author: Werner Robitza
@@ -25,13 +25,13 @@ License-File: LICENSE
 
 # ffmpeg-normalize
 
-<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-18-orange.svg?style=flat-square)](#contributors-)
-<!-- ALL-CONTRIBUTORS-BADGE:END -->
-
 [![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)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/slhck/ffmpeg-normalize/python-package.yml)
 
-[![Python package](https://github.com/slhck/ffmpeg-normalize/actions/workflows/python-package.yml/badge.svg)](https://github.com/slhck/ffmpeg-normalize/actions/workflows/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-BADGE:END -->
 
 A utility for batch-normalizing audio using ffmpeg.
 
@@ -54,9 +54,8 @@ Read on for more info.
   - [ffmpeg](#ffmpeg)
 - [Installation](#installation)
 - [Usage with Docker](#usage-with-docker)
-  - [From Docker Hub](#from-docker-hub)
-- [Usage](#usage)
-- [Description](#description)
+- [High LeveL Introduction](#high-level-introduction)
+- [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Detailed Options](#detailed-options)
   - [File Input/Output](#file-inputoutput)
@@ -69,10 +68,11 @@ Read on for more info.
   - [Environment Variables](#environment-variables)
 - [API](#api)
 - [FAQ](#faq)
+  - [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)
   - [Why are my output files MKV?](#why-are-my-output-files-mkv)
-  - ["Could not write header for output file" error](#could-not-write-header-for-output-file-error)
+  - [I get a "Could not write header for output file" error](#i-get-a-could-not-write-header-for-output-file-error)
   - [The conversion does not work and I get a cryptic ffmpeg error!](#the-conversion-does-not-work-and-i-get-a-cryptic-ffmpeg-error)
   - [What are the different normalization algorithms?](#what-are-the-different-normalization-algorithms)
   - [Couldn't I just run `loudnorm` with ffmpeg?](#couldnt-i-just-run-loudnorm-with-ffmpeg)
@@ -87,7 +87,7 @@ Read on for more info.
 
 ## Requirements
 
-You need Python 3.8 or higher.
+You need Python 3.8 or higher, and ffmpeg.
 
 ### ffmpeg
 
@@ -126,9 +126,9 @@ pip3 install ffmpeg-normalize
 
 Or download this repository, then run `pip3 install .`.
 
-## Usage with Docker
+To later upgrade to the latest version, run `pip3 install --upgrade ffmpeg-normalize`.
 
-### From Docker Hub
+## Usage with Docker
 
 You can use the pre-built image from Docker Hub:
 
@@ -138,7 +138,7 @@ docker run -v "$(pwd):/tmp" -it slhck/ffmpeg-normalize
 
 Alternatively, download this repository and run
 
-```
+```bash
 docker build -t ffmpeg-normalize .
 ```
 
@@ -156,45 +156,31 @@ docker run  -v "$(pwd):/tmp" -it ffmpeg-normalize /tmp/yourfile.mp4 -o /tmp/your
 
 You will then find the normalized file in your current directory.
 
-## Usage
-
-```bash
-ffmpeg-normalize input [input ...][-h][-o OUTPUT [OUTPUT ...]] [options]
-```
-
-Example:
-
-```bash
-ffmpeg-normalize 1.wav 2.wav -o 1-normalized.m4a 2-normalized.m4a -c:a aac -b:a 192k
-```
-
-For more information on the options (`[options]`) available, run `ffmpeg-normalize -h`, or read on.
-
-## Description
+## High LeveL Introduction
 
 Please read this section for a high level introduction.
 
 **What does the program do?**
 
-The program takes one or more input files and, by default, writes them to a folder called `normalized`, using an `.mkv` container. All audio streams will be normalized so that they have the same (perceived) volume.
+The program takes one or more input files and, by default, writes them to a folder called `normalized`, using an `.mkv` container. All audio streams will be normalized so that they have the same (perceived) volume according to the EBU R128 standard. This is done by analyzing the audio streams and applying a filter to bring them to a target level. Under the hood, the program uses ffmpeg's `loudnorm` filter to do this.
 
 **How do I specify the input?**
 
-Just give the program one or more input files as arguments. It works with most media files.
+Just give the program one or more input files as arguments. It works with most media files, including video files.
 
 **How do I specify the output?**
 
-You can specify one output file name for each input file with the `-o` option. In this case, the container format (e.g. `.wav`) will be inferred from the file name extension that you've given.
+You don't have to specify an output file name (the default is `normalized/<input>.mkv`), but if you want to override it, you can specify one output file name for each input file with the `-o` option. In this case, the container format (e.g. `.wav`) will be inferred from the file name extension that you've given.
 
 Example:
 
-```
-ffmpeg-normalize 1.wav 2.wav -o 1n.wav 2n.wav
+```bash
+ffmpeg-normalize 1.wav 2.wav -o 1-normalized.wav 2-normalized.wav
 ```
 
-If you don't specify the output file name for an input file, the container format will be MKV, and the output will be written to `normalized/<input>.mkv`.
+Note that if you don't specify the output file name for an input file, the container format will be MKV, and the output will be written to `normalized/<input>.mkv`. The reason for choosing the MKV container is that it can handle almost any codec combination.
 
-Using the `-ext` option, you can supply a different output extension common to all output files, e.g. `-ext m4a`.
+Using the `-ext` option, you can supply a different output extension common to all output files, e.g. `-ext m4a`. However, you need to make sure that the container supports the codecs used for the output (see below).
 
 **What will get normalized?**
 
@@ -202,7 +188,7 @@ By default, all streams from the input file will be written to the output file.
 
 **How will the normalization be done?**
 
-The normalization will be performed with the [`loudnorm` filter](https://ffmpeg.org/ffmpeg-filters.html#loudnorm) from FFmpeg, which was [originally written by Kyle Swanson](https://k.ylo.ph/2016/04/04/loudnorm.html). It will bring the audio to a specified target level. This ensures that multiple files normalized with this filter will have the same perceived loudness.
+The normalization will be performed according to the EBU R128 algorithm with the [`loudnorm` filter](https://ffmpeg.org/ffmpeg-filters.html#loudnorm) from FFmpeg, which was [originally written by Kyle Swanson](https://k.ylo.ph/2016/04/04/loudnorm.html). It will bring the audio to a specified target level. This ensures that multiple files normalized with this filter will have the same perceived loudness.
 
 **What codec is chosen?**
 
@@ -210,6 +196,22 @@ The default audio encoding method is uncompressed PCM (`pcm_s16le`) to avoid int
 
 Some containers (like MP4) also cannot handle PCM audio. If you want to use such containers and/or keep the file size down, use `-c:a` and specify an audio codec (e.g., `-c:a aac` for ffmpeg's built-in AAC encoder).
 
+## Basic Usage
+
+Supply one or more input files, and optionally, output file names:
+
+```bash
+ffmpeg-normalize input [input ...][-h][-o OUTPUT [OUTPUT ...]] [options]
+```
+
+Example:
+
+```bash
+ffmpeg-normalize 1.wav 2.wav -o 1-normalized.m4a 2-normalized.m4a -c:a aac -b:a 192k
+```
+
+For more information on the options (`[options]`) available, run `ffmpeg-normalize -h`, or read on.
+
 ## Examples
 
 [Read the examples on the wiki.](https://github.com/slhck/ffmpeg-normalize/wiki/examples)
@@ -400,6 +402,32 @@ For more information see the [API documentation](https://htmlpreview.github.io/?
 
 ## FAQ
 
+### 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:
+
+* Integrated Loudness (I): The overall loudness of the entire audio.
+* Loudness Range (LRA): The variation in loudness over time.
+* True Peak (TP): The maximum level of the audio signal.
+
+The normalization process involves measuring these values (input) and then applying gain adjustments to meet target levels (output), typically -23 LUFS for integrated loudness. You can also specify a target loudness range (LRA) and true peak level (TP).
+
+**Linear mode** applies a constant gain adjustment across the entire audio file. This is generally preferred because:
+
+* It preserves the original dynamic range of the audio.
+* It maintains the relative loudness between different parts of the audio.
+* It avoids potential artifacts or pumping effects that can occur with dynamic processing.
+
+**Dynamic mode**, on the other hand, can change the volume dynamically throughout the file. While this can achieve more consistent loudness, it may alter the original artistic intent and potentially introduce audible artifacts (possibly due to some bugs in the ffmpeg filter).
+
+For most cases, linear mode is recommended. Dynamic mode should only be used when linear mode is not suitable or when a specific effect is desired. In some cases, `loudnorm` will still fall back to dynamic mode, and a warning will be printed to the console. Here's when this can happen:
+
+* When the input loudness range (LRA) is larger than the target loudness range: If the input file has a loudness range that exceeds the specified loudness range target, the loudnorm filter will automatically switch to dynamic mode. This is because linear normalization alone cannot reduce the loudness range without dynamic processing (limiting). The `--keep-loudness-range-target` option can be used to keep the input loudness range target above the specified target.
+
+* 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!
+
 ### The program doesn't work because the "loudnorm" filter can't be found
 
 Make sure you run a recent ffmpeg version and that `loudnorm` is part of the output when you run `ffmpeg -filters`. Many distributions package outdated ffmpeg versions, or (even worse), Libav's `ffmpeg` disguising as a real `ffmpeg` from the FFmpeg project.
@@ -412,13 +440,15 @@ If you have to use an outdated ffmpeg version, you can only use `rms` or `peak`
 
 ### Should I use this to normalize my music collection?
 
+Generally, no.
+
 When you run `ffmpeg-normalize` and re-encode files with MP3 or AAC, you will inevitably introduce [generation loss](https://en.wikipedia.org/wiki/Generation_loss). Therefore, I do not recommend running this on your precious music collection, unless you have a backup of the originals or accept potential quality reduction. If you just want to normalize the subjective volume of the files without changing the actual content, consider using [MP3Gain](http://mp3gain.sourceforge.net/) and [aacgain](http://aacgain.altosdesign.com/).
 
 ### Why are my output files MKV?
 
 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.
 
-### "Could not write header for output file" error
+### 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).
 
@@ -514,6 +544,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/sian1468"><img src="https://avatars.githubusercontent.com/u/58017832?v=4?s=100" width="100px;" alt="sian1468"/><br /><sub><b>sian1468</b></sub></a><br /><a href="https://github.com/slhck/ffmpeg-normalize/commits?author=sian1468" title="Tests">⚠️</a></td>
       <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>
     </tr>
   </tbody>
   <tfoot>
@@ -561,6 +592,17 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 # Changelog
 
 
+## v1.28.3 (2024-08-16)
+
+* Make colorama dependency windows-only.
+
+* Update.
+
+* Update badges.
+
+* Docs: add @kanjieater as a contributor.
+
+
 ## v1.28.2 (2024-06-22)
 
 * Provide an entrypoint for the Docker image.

{ffmpeg-normalize-1.28.2 → ffmpeg-normalize-1.28.3}/ffmpeg_normalize.egg-info/requires.txt

@@ -1,4 +1,6 @@
 tqdm
-colorama
 ffmpeg-progress-yield
 colorlog
+
+[:platform_system == "Windows"]
+colorama

{ffmpeg-normalize-1.28.2 → ffmpeg-normalize-1.28.3}/setup.py

@@ -34,7 +34,7 @@ setup(
     },
     install_requires=[
         "tqdm",
-        "colorama",
+        "colorama;platform_system=='Windows'",
         "ffmpeg-progress-yield",
         "colorlog",
     ],

ffmpeg-normalize-1.28.2/ffmpeg_normalize/_version.py

@@ -1 +0,0 @@
-__version__ = "1.28.2"