loudcheck

loudcheck

响度合规判定，而非原始仪表输出。loudcheck 使用 ffmpeg 测量媒体文件，并根据正式发布的标准回答真正重要的问题——这个文件是否符合规范？

Agent 从这里开始 → SKILL.md — 了解何时调用、示例以及 MUST/MUST NOT 要求。系列契约：FAMILY.md。

• 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，提供数值但不作判断）

$ loudcheck master.wav --standard EBU_R128
FAIL — EBU R 128
  ✗ integrated -19.4 LUFS (target -23.0 ±0.5, delta +3.6)
  ✓ true peak -16.3 dBTP (max -1.0)
  · LRA 0.0 LU (informational)
  → apply -3.6 LU gain to reach -23.0 LUFS (e.g. ffmpeg -af volume=-3.6dB, or loudnorm I=-23)

CLI 和 MCP 工具共用同一引擎，因此 Agent 和用户得到的判定完全一致。

为什么要开发这个工具

Agent（或工程师）可以运行 ffmpeg 的 ebur128 滤镜并获取数值。但仅靠 shell 无法得到判定结果——这需要了解标准的目标值、容差和门限，并据此解读综合响度、LRA 和真峰值。响度是交付被拒最常见的原因之一，而真正的差距不在测量，而在于能否基于标准给出答案。这就是这个工具的全部用途。

安装

需要 Python 3.10+，并确保 ffmpeg 5.0+ 位于 PATH 中。

uvx loudcheck file.wav          # zero-install run (requires ffmpeg >= 5.0 on PATH)
pip install loudcheck           # CLI
pip install "loudcheck[mcp]"    # + MCP server

从克隆的仓库安装：pip install -e ".[mcp,dev]"。

CLI

loudcheck file.wav                          # EBU R128 by default
loudcheck file.mp4 --standard ATSC_A85      # first audio stream of a video
loudcheck file.wav --json                   # full structured verdict
loudcheck file.wav --standard BS_1770       # measurement only, no gates
loudcheck file.mov --all-streams            # verdict every audio track
loudcheck file.mov --stream 1               # a specific audio track
loudcheck file.wav --detailed               # + max momentary / short-term
loudcheck masters/ --standard EBU_R128      # batch a directory -> table
loudcheck a.wav b.wav c.wav                 # batch multiple files
loudcheck --schema                          # print the tool definition

批处理模式会为每个文件打印一行结果（失败时附带修正方法），并输出摘要；批处理时使用 --json 会输出数组。只要有任意文件未通过，退出代码就是 1。

面向 Agent

• 退出代码承载判定结果： 0 = 通过，1 = 未通过（不合规），2 = 错误（文件缺失、没有音频流或没有 ffmpeg）。仅凭退出代码即可决定是否放行交付。
• --json 是完整契约： 包含总体 verdict、每项指标的 measured/target/tolerance/delta/pass（每项受门限约束的指标均附有规范引用）、通俗易懂的 failures，以及提供精确修正方法的 remediation——如果响度比目标高出 2.3 LU，就会提示应用 −2.3 LU 的增益，并提供相应的 ffmpeg 命令。本工具不会应用修正（仅测量并给出判定）；Agent 可使用提供的差值，通过 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 中以纯数据形式定义——包括目标值、容差和引用。无需修改代码。

测量方式

一次使用 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 和此工具提供的差值）· 全文件 QC（编解码器／色彩／帧率）· 实时监控 · GUI · 平台交付模板（参见护栏）。

许可证

MIT