ffmpeg-normalize

ffmpeg-normalize logo

GitHub Actions Workflow Status

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_SETTINGS tag
Video file support — Process video files while preserving video streams
Docker support — Run via Docker container
Python API — Use programmatically in your Python projects
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-normalize and ffmpeg-normalize /path/to/your/file.mp4, alternatively install uv and run uvx 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_SETTINGS tag on each normalized audio stream via --write-encoder-settings. The tag holds an ffmpeg-command-equivalent string — the audio codec, bitrate, sample rate and channels, plus the normalization filter including the measured loudnorm values — so a normalized file documents how it was produced. This is a Matroska/WebM convention and has no effect with --metadata-disable.

Example:
```
ffmpeg-normalize input.wav -c:a libopus -b:a 128k --write-encoder-settings -o output.mkv
```
Version 1.41.0 automatically picks the correct output audio codec for the output container, so you no longer need to specify -c:a/--audio-codec unless you want to override the default. PCM is chosen for containers that support it; others will use teh default that ffmpeg picks. See the usage guide for details.
Version 1.40.0 can optionally skip files that are already at the target level via --threshold (e.g. --threshold 0.5, disabled by default). Such files are copied through unchanged instead of being re-encoded. The --print-stats output now includes a per-file status (normalized, skipped, or error, plus an error message on failure), and the exit code is non-zero if any file failed to process, so a script can tell what happened to each file.

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-depth to opt out. It also adds --keep-mtime to 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), and streaming-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,2 to 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-only option — 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!

_{Benjamin Balder Bach} 💻	_{Eleni Lixourioti} 💻	_thenewguy 💻	_{Anthony Violo} 💻	_{Eric Jacobs} 💻	_kostalski 💻	_{Justin Pearson} 💻
_ad90xa0-aa 💻	_Mathijs 💻	_{Marc Püls} 💻	_{Michael V. Battista} 💻	_WyattBlue 💻	_{Jan-Frederik Schmidt} 💻	_mjhalwa 💻
₀₇₄₁₆ 📖	_sian1468 ⚠️	_{Panayiotis Savva} 💻	_HighMans 💻	_kanjieater 🤔	_{Ahmet Sait} 💻	_georgev93 💻
_{David Bern} 💻	_{randompersona1} 💻	_Petr 💻
Add your contributions

Metadata

Release files for ffmpeg-normalize 1.42.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ffmpeg-normalize 1.42.1
File	Size	Uploaded
ffmpeg_normalize-1.42.1.tar.gz	44.5 kB	Oct 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ffmpeg-normalize 1.42.1
File	Interpreter	ABI	Platform	Reset
ffmpeg_normalize-1.42.1-py3-none-any.whl 50.8 kB Oct 11, 2026	Python 3	none	any	Details

Total release size: 95.3 kB

Release files / ffmpeg_normalize-1.42.1.tar.gz

Download URL	ffmpeg_normalize-1.42.1.tar.gz
Size	44.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`87d68bad2285ef5e7acb291af995156fe7fd3b0e8a5a3e61be1429af7f522ee3`
BLAKE2b-256 checksum How to use checksums	`551176bca2b0053dcf3633be0b6a755d33e7e30f033ddb2ee0fb8291a5aad9d2`
Upload date	Oct 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / ffmpeg_normalize-1.42.1-py3-none-any.whl

Download URL	ffmpeg_normalize-1.42.1-py3-none-any.whl
Size	50.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`fb18488e308c0e20bc95b4b5164e04d9c47726592e44ae3435ffcbaf7e854269`
BLAKE2b-256 checksum How to use checksums	`83e261e8094cb5f34909512bec280fb5b6f9ffce688272b8a7490530f6f16b24`
Upload date	Oct 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`