ffmpeg-normalize
A utility for batch-normalizing audio using ffmpeg.
This program normalizes media files to a certain loudness level using the EBU R128 loudness normalization procedure. It can also perform RMS-based normalization (where the mean is lifted or attenuated), or peak normalization to a certain target level.
✨ Features
- EBU R128 loudness normalization — Two-pass by default, with an option for one-pass dynamic normalization
- RMS-based normalization — Adjust audio to a specific RMS level
- Peak normalization — Adjust audio to a specific peak level
- Selective audio stream normalization — Normalize specific audio streams or only default streams
- Skip files already at target — Avoid re-encoding files already within a threshold of the target level
- Self-documenting output — Optionally record the effective encoder settings as an
ENCODER_SETTINGStag - Video file support — Process video files while preserving video streams
- Docker support — Run via Docker container
- Python API — Use programmatically in your Python projects
- Shell completions — Available for bash, zsh, and fish
- Album Batch normalization – Process files jointly, preserving relative loudness
🚀 Quick Start
- Install a recent version of ffmpeg and Python 3.10 or higher
- Run
pip3 install ffmpeg-normalizeandffmpeg-normalize /path/to/your/file.mp4, alternatively installuvand runuvx ffmpeg-normalize /path/to/your/file.mp4 - Done! 🎧 (the normalized file will be called
normalized/file.mkv)
🆕 What's New
-
Version 1.42.0 can optionally write an
ENCODER_SETTINGStag on each normalized audio stream via--write-encoder-settings. The tag holds an ffmpeg-command-equivalent string — the audio codec, bitrate, sample rate and channels, plus the normalization filter including the measured loudnorm values — so a normalized file documents how it was produced. This is a Matroska/WebM convention and has no effect with--metadata-disable.Example:
ffmpeg-normalize input.wav -c:a libopus -b:a 128k --write-encoder-settings -o output.mkv
-
Version 1.41.0 automatically picks the correct output audio codec for the output container, so you no longer need to specify
-c:a/--audio-codecunless you want to override the default. PCM is chosen for containers that support it; others will use teh default that ffmpeg picks. See the usage guide for details. -
Version 1.40.0 can optionally skip files that are already at the target level via
--threshold(e.g.--threshold 0.5, disabled by default). Such files are copied through unchanged instead of being re-encoded. The--print-statsoutput now includes a per-filestatus(normalized,skipped, orerror, plus anerrormessage on failure), and the exit code is non-zero if any file failed to process, so a script can tell what happened to each file.Example:
ffmpeg-normalize input.flac -nt peak -t 0 -c:a flac --print-stats -o output.flac
-
Version 1.39.0 preserves the input bit depth by default when encoding to formats like FLAC, so 16-bit input stays 16-bit without needing
-e "-sample_fmt s16". Use--no-keep-bit-depthto opt out. It also adds--keep-mtimeto copy the input file's modification time to the output, which is useful for preserving when a track was added to a music library.Example:
ffmpeg-normalize input.flac -nt peak -t 0 -c:a flac --keep-mtime -o output.flac
-
Version 1.38.0 writes the normalized output directly to the destination without using temporary files
-
Version 1.36.0 introduces presets with
--preset! Save and reuse your favorite normalization configurations for different use cases. Comes with three built-in presets:podcast(AES standard),music(RMS-based batch normalization), andstreaming-video(video content). Create custom presets too!Example:
ffmpeg-normalize input.mp3 --preset podcast
applies the podcast preset (EBU R128, -16 LUFS) to your file. Learn more in the presets guide.
-
Version 1.35.0 has batch/album normalization with
--batch. It preserves relative loudness between files! Perfect for music albums where you want to shift all tracks by the same amount.Example:
ffmpeg-normalize album/*.flac --batch -nt rms -t -20
shifts the entire album so the average RMS is -20 dB, preserving the original relative loudness as mastered.
-
Version 1.34.0 brings selective audio stream normalization! You can now:
-
Normalize specific audio streams with
-as/--audio-streams(e.g.,-as 1,2to normalize only streams 1 and 2) -
Normalize only default audio streams with
--audio-default-only(useful for files with multiple language tracks) -
Keep other streams unchanged with
--keep-other-audio(copy non-selected streams without normalization)Example:
ffmpeg-normalize input.mkv -as 1 --keep-other-audio
normalizes stream 1 and copies all other audio streams unchanged.
-
Other recent additions:
- Shell completions (v1.31.0) — Tab completion for bash, zsh, and fish shells. See the installation guide for setup instructions.
--lower-onlyoption — Prevent audio from increasing in loudness, only lower it if needed (works with all normalization types).
See the full changelog for all updates.
📓 Documentation
Check out our documentation for more info!
🤝 Contributors
The only reason this project exists in its current form is because @benjaoming's initial PRs. Thanks for everyone's support!
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ffmpeg_normalize-1.42.0.tar.gz.
File metadata
- Download URL: ffmpeg_normalize-1.42.0.tar.gz
- Upload date:
- Size: 44.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
702aaaa6e9c5ef39f8407a12dd04c0b727935fff80288c4554c97a14e5988d6c
|
|
| MD5 |
a9789cf3671754dcfd1ed880a5a5fbc9
|
|
| BLAKE2b-256 |
5b74d0a3a9bdd2748c41dedafb90f522ad3fbb614ed41fee574eb2d9950e40f5
|
File details
Details for the file ffmpeg_normalize-1.42.0-py3-none-any.whl.
File metadata
- Download URL: ffmpeg_normalize-1.42.0-py3-none-any.whl
- Upload date:
- Size: 50.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
49829d27e03003307a1af82b7baf328aa52f0b7f9f71e884beafd49fb619dab8
|
|
| MD5 |
0a8c7af11ee9b658a0ba72c8f08ac254
|
|
| BLAKE2b-256 |
80628a1b7eab64ccaa07a85f637b31fee6f071751dc6001cdee4342e3014f4ff
|
