music-norm

批量音频响度归一化工具——告别播放时一会儿响一会儿轻。

扫描目录中的所有音乐文件，将每首歌的响度统一调整到目标值（默认 -14 LUFS），输出到新目录，绝不修改原始文件。

功能特点

两种模式：Tag 模式写入 ReplayGain 标签（无损）；Encode 模式重新编码永久调整音量
响度标准：基于 LUFS（EBU R128），与 Spotify / YouTube 同标准，符合人耳感知
格式支持：MP3、FLAC、OGG、M4A/AAC、WAV、WMA、Opus
并发处理：多线程并行，速度快
进度显示：实时显示每个文件的 LUFS 前后变化
断点续传：已输出的文件自动跳过，中断后可继续运行
保留目录结构：输出目录与源目录层级完全一致

安装

1. 安装 ffmpeg（必须）

macOS：

brew install ffmpeg

Ubuntu / Debian：

sudo apt update && sudo apt install ffmpeg

Windows： 从 ffmpeg.org 下载，将 bin/ 加入系统 PATH。

2. 安装 music-norm

git clone <repo-url>
cd music-volume-balance
pip install -e .

验证：

music-norm --help

快速上手

# Tag 模式（推荐：无损，写 ReplayGain 标签）
music-norm --tag /你的音乐目录 --output /处理后的目录

# Encode 模式（重新编码，兼容任意播放器）
music-norm --encode /你的音乐目录 --output /处理后的目录

# 递归处理所有子目录
music-norm --tag --recursive /你的音乐目录 --output /处理后的目录

运行效果：

[music-norm] 模式：Tag (ReplayGain) | 目标：-14.0 LUFS | 线程：8 | 文件：247 个

处理音频文件中…
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  120/247  48.6%  0:01:02  0:01:05
 ✓  周杰伦 - 晴天.mp3          -18.3 → -14.0 LUFS  (+4.3 dB)
 ✓  周杰伦 - 七里香.mp3        -16.1 → -14.0 LUFS  (+2.1 dB)
   ⟳ 分析中…  青花瓷.mp3
   ⟳ 分析中…  富士山下.mp3

[汇总] 已完成：247  失败：0  跳过：0  总耗时：128.4s

两种模式对比

	Tag 模式（`--tag`）	Encode 模式（`--encode`）
原理	写入 ReplayGain 标签，音频数据不变	ffmpeg loudnorm 重新编码
音质	无损 ✓	有损格式轻微降质；FLAC 仍无损
速度	快（只测量+写标签）	慢（两遍 ffmpeg 扫描）
兼容性	需播放器支持 ReplayGain	任意播放器 ✓
适合	foobar2000、VLC、Rockbox 等	手机默认播放器、车载设备等

拿不准选哪个？ 如果你用 foobar2000 或 VLC，选 --tag；其他情况选 --encode。

完整参数

music-norm [--tag | --encode] [选项] <输入目录>

参数	默认值	说明
`输入目录`	—	待处理的音频目录（必填）
`--output DIR` / `-o`	—	输出目录，不能与输入目录相同（必填）
`--tag`	—	Tag 模式（与 `--encode` 二选一）
`--encode`	—	Encode 模式（与 `--tag` 二选一）
`--target LUFS`	`-14.0`	目标响度，范围 -70 ~ 0
`--recursive` / `-r`	关闭	递归处理所有子目录
`--jobs N` / `-j`	自动	并发线程数（1 ~ 32）
`--overwrite`	关闭	覆盖输出目录中已存在的文件

`--target` 参考值

值	说明
`-14.0`（默认）	Spotify / YouTube 标准
`-16.0`	Apple Music 标准
`-18.0`	传统 ReplayGain 参考值

使用示例

# 整个音乐库，tag 模式，递归
music-norm --tag --recursive ~/Music --output ~/Music_normalized

# 自定义目标响度 -16 LUFS
music-norm --tag --target -16 ~/Music --output ~/Music_normalized

# 4 个线程加速处理
music-norm --encode --jobs 4 ~/Music --output ~/Music_normalized

# 重新处理（覆盖已有输出）
music-norm --tag --overwrite ~/Music --output ~/Music_normalized

# 中断后继续（已处理的文件自动跳过）
music-norm --tag --recursive ~/Music --output ~/Music_normalized