https://github.com/slhck/ffmpeg-normalize
Audio Normalization for Python/ffmpeg
https://github.com/slhck/ffmpeg-normalize
audio ffmpeg python
Last synced: 3 days ago
JSON representation
Audio Normalization for Python/ffmpeg
- Host: GitHub
- URL: https://github.com/slhck/ffmpeg-normalize
- Owner: slhck
- License: other
- Created: 2014-07-31T08:55:49.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2026-02-04T07:26:00.000Z (3 days ago)
- Last Synced: 2026-02-04T08:46:17.231Z (3 days ago)
- Topics: audio, ffmpeg, python
- Language: HTML
- Homepage: https://slhck.info/ffmpeg-normalize/
- Size: 3.53 MB
- Stars: 1,474
- Watchers: 27
- Forks: 127
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
- awesome-video - slhck/ffmpeg-normalize - Audio Normalization for Python/ffmpeg. (Media Analysis, Quality Metrics & AI Tools / Audio Analysis & Processing)
README
# ffmpeg-normalize
[](https://pypi.org/project/ffmpeg-normalize)
[](https://hub.docker.com/r/slhck/ffmpeg-normalize)
[](#contributors-)
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
- 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
1. Install a recent version of [ffmpeg](https://ffmpeg.org/download.html)
2. Run `pip3 install ffmpeg-normalize` and `ffmpeg-normalize /path/to/your/file.mp4`, alternatively install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) and run `uvx ffmpeg-normalize /path/to/your/file.mp4`
3. Done! 🎧 (the normalized file will be called `normalized/file.mkv`)
## 🆕 What's New
- 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:
```bash
ffmpeg-normalize input.mp3 --preset podcast
```
applies the podcast preset (EBU R128, -16 LUFS) to your file. Learn more in the [presets guide](https://slhck.info/ffmpeg-normalize/usage/presets/).
- 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:
```bash
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:
```bash
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](https://slhck.info/ffmpeg-normalize/getting-started/installation/#shell-completions) 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](https://github.com/slhck/ffmpeg-normalize/blob/master/CHANGELOG.md) for all updates.
## 📓 Documentation
Check out our [documentation](https://slhck.info/ffmpeg-normalize/) for more info!
## 🤝 Contributors
The only reason this project exists in its current form is because [@benjaoming](https://github.com/slhck/ffmpeg-normalize/issues?q=is%3Apr+author%3Abenjaoming)'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
💻
07416
📖
sian1468
⚠️
Panayiotis Savva
💻
HighMans
💻
kanjieater
🤔
Ahmet Sait
💻
georgev93
💻
David Bern
💻
randompersona1
💻
Add your contributions