内容
# loudcheck
**响度合规性判决**，而非原始仪表输出。`loudcheck` 使用 ffmpeg 测量媒体文件，并回答一个关键问题：*该文件是否符合规范？* 与正式发布的标准进行对比：
- **EBU R 128** （欧洲广播：−23.0 LUFS ±0.5 LU，最大 −1 dBTP）
- **ATSC A/85** （美国电视：−24 LKFS ±2 dB，真实峰值低于 −2 dBTP）
- **BS.1770** （仅测量：BS.1770 定义了无合规目标，因此此模式返回带有数字的判决 `measured` 且无判断）
```bash
$ loudcheck master.wav --standard EBU_R128
FAIL — EBU R 128
✗ 集成 -19.4 LUFS （目标 -23.0 ±0.5，偏差 +3.6）
✓ 真实峰值 -16.3 dBTP （最大 -1.0）
· LRA 0.0 LU （信息性）
→ 应用 -3.6 LU 增益以达到 -23.0 LUFS （例如 ffmpeg -af volume=-3.6dB，或 loudnorm I=-23）
```
作为 CLI 和 MCP 工具发布，使用同一个引擎，因此代理和人工获得相同的判决。
## 为什么存在
代理（或工程师）可以运行 ffmpeg 的 `ebur128` 过滤器并获得数值。但是，从 shell 无法获得的是 *判决* —— 这需要了解标准的目标、容差和门控，并将综合响度与 LRA 和真实峰值进行对比。响度是最常见的交付拒绝原因之一，而问题不在于测量，而在于符合标准的答案。这就是该工具的全部内容。
## 安装
```bash
uvx loudcheck file.wav # 零安装运行（需要 ffmpeg >= 5.0 在 PATH 上）
pip install loudcheck # CLI
pip install "loudcheck[mcp]" # + MCP 服务器
```
从克隆仓库开始：`pip install -e ".[mcp,dev]"`。
## CLI
```bash
loudcheck file.wav # 默认 EBU R128
loudcheck file.mp4 --standard ATSC_A85 # 视频的第一音频流
loudcheck file.wav --json # 完整的结构化判决
loudcheck file.wav --standard BS_1770 # 仅测量，无门控
loudcheck file.mov --all-streams # 每个音频轨道的判决
loudcheck file.mov --stream 1 # 特定的音频轨道
loudcheck file.wav --detailed # + 最大瞬时 / 短期
loudcheck masters/ --standard EBU_R128 # 批处理目录 -> 表格
loudcheck a.wav b.wav c.wav # 批处理多个文件
loudcheck --schema # 打印工具定义
```
批处理模式每文件打印一行（加上失败的补救措施）和总结；`--json` 在批处理中输出数组。如果 *任何* 文件失败，退出代码为 `1`。
## 适用于代理
- **退出代码携带判决：** `0` = 通过，`1` = 失败（不符合），`2` = 错误（缺少文件，无音频流，无 ffmpeg）。使用退出代码对交付进行门控。
- **`--json` 是完整的合同：** 总体 `verdict`，每个指标的 `measured/target/tolerance/delta/pass` 以及规范引用，附带每个受控指标的 `failures` 和 `remediation` 提供 **精确的修正** —— 失败 2.3 LU 超出目标，告诉您应用 −2.3 LU 增益，并提供 ffmpeg 命令。此工具从不应用修复（仅测量和判决）；代理使用提供的增益一次性应用 `loudnorm`。
- **MCP：** 注册 `loudcheck-mcp` （stdio；或 `loudcheck --mcp`，或 `python -m loudcheck.mcp_server`）。零安装：`uvx --from 'loudcheck[mcp]' loudcheck --mcp`。工具：`check_loudness(path, standard)` → 与 CLI 相同的 JSON，以及 `list_standards()` → 带有引用的目录。已针对 `mcp==1.28.1` 进行验证。
- **`tool.json`** 在仓库根目录以机器可读的方式描述接口 —— 或从任何安装中获取它，运行 `loudcheck --schema` （文件随软件包一起提供；测试保持两个副本同步）。
- **ffmpeg 版本是合同的一部分：** 每个判决都包含 `measurement_context.ffmpeg_version`。最低支持版本：5.0。已开发并针对 8.1 版本进行验证。
## 范围防护栏（贡献前请阅读）
**只有正式的、稳定的标准在此仓库中生效；平台交付模板（Netflix、DPP、Apple TV+、Amazon、广播公司规格）永远不会生效。** 平台规格单方面更改，涵盖的内容远不止响度 —— 一旦它们进入此仓库，此工具将不再是一个近乎零维护的社区工具，而是成为每年都需要维护的产品。如果 PR 添加了平台可以自行更改的目标，则它属于在此原始工具之上构建的单独模板层，而不是此处。
欢迎为增加正式标准（例如纯 ITU-R BS.1770 模式）做出贡献：标准是 [`loudcheck/standards.py`](loudcheck/standards.py) 中的纯数据 —— 目标、容差和引用。无需更改代码。
## 它如何测量
使用 `loudnorm=print_format=json` 的 ffmpeg 单次运行（分析模式）可得出综合响度、响度范围、真实峰值（BS.1770 的过采样 dBTP）和门控阈值。测试套件将 loudnorm 的读数与 ffmpeg 独立的 `ebur128` 实现进行交叉检查 —— 两者必须在 1 LU 内达成一致，以便 CI 通过，因此 ffmpeg 版本更改的行为不会被用户捕获，而会被测试套件捕获。
## 验证语料库
`pytest` 动态生成校准测试音（仓库中没有二进制文件）：根据 BS.1770 的校准声明，单声道 997 Hz 正弦波在 0 dBFS 下读取 −3.01 LKFS，因此在已知响度下生成音调 —— 合规、过响、过静和真实峰值过高 —— 每个判决必须与其已知的预期结果匹配。
## 永久超出范围
响度 **校正** （使用 ffmpeg `loudnorm` 和该工具提供的增益）· 全文件质量控制（codec/color/cadence）· 实时监控 · GUI · 平台交付模板（参见防护栏）。
## 许可证
MIT
<!-- mcp-name: io.github.chaoz23/loudcheck -->
