用途
loudcheck 解决的是音频交付中最常见的一类拒收原因：响度不合规。它不止于用 ffmpeg 测量出数字，而是把数字放到正式发布的标准目标、容差与门限上进行解释，直接回答“这个文件能否通过规范”这一关键问题。
主要能力
- 按标准给出合规判定，而非原始电平表输出。
- 支持标准：EBU R 128（−23.0 LUFS ±0.5 LU，最大 −1 dBTP）、ATSC A/85（−24 LKFS ±2 dB，真峰值低于 −2 dBTP）、BS.1770（仅测量模式，该标准不定义合规目标，因此返回 measured 判定与数值，不做合规裁决）。
- JSON 输出即完整契约：包含整体结论；每个受门限约束的指标附有实测值、目标值、容差、偏差与是否通过，并附带规范引用；失败原因用通俗英文说明；修复建议给出精确修正量，例如“超出目标 2.3 LU”会提示施加 −2.3 LU 增益，并附上对应的 ffmpeg 命令。
- 同一引擎同时提供 CLI 与 MCP，智能体与人类用户获得一致判定。
- 批量模式每个文件输出一行（失败项附修复建议）并给出汇总；批量下使用 --json 输出数组；任一文件失败时退出码为 1。
- 退出码承载判定：0 通过、1 不合规、2 错误（文件缺失、无音频流、无 ffmpeg）。可仅依据退出码对交付流程进行卡点。
- 仓库根目录的 tool.json 以机器可读方式描述接口，也可用 loudcheck --schema 从任意安装中实时获取。
- 每个判定都包含 measurement_context.ffmpeg_version；最低支持 ffmpeg 5.0，开发与验证基于 8.1。
使用方式
环境要求：Python 3.10+，且 ffmpeg 5.0+ 位于 PATH 中。
从克隆安装：pip install -e ".[mcp,dev]"。
MCP 注册：loudcheck-mcp（stdio 方式），或 loudcheck --mcp，或 python -m loudcheck.mcp_server。零安装方式：uvx --from 'loudcheck[mcp]' loudcheck --mcp。MCP 工具包括 check_loudness(path, standard)（返回与 CLI 相同的 JSON）和 list_standards()（返回带规范引用的标准目录）。已针对 mcp==1.28.1 验证。
智能体入口：SKILL.md 说明何时调用、完整示例与 MUST/MUST NOT 规则；家族契约见 FAMILY.md。
测量原理
使用一次 ffmpeg 处理，调用 loudnorm=print_format=json（分析模式），得到整体响度、响度范围、真峰值（按 BS.1770 过采样 dBTP）以及门限阈值。测试套件会将 loudnorm 的读数与 ffmpeg 独立的 ebur128 实现交叉核对，二者须在 1 LU 内一致才能通过 CI，因此 ffmpeg 版本改变滤波器行为时会被测试套件捕获，而不是由用户发现。
验证方式
pytest 在运行时生成校准测试音（仓库中不含二进制文件）：依据 BS.1770 的校准说明，0 dBFS 的单声道 997 Hz 正弦波读数为 −3.01 LKFS，因此测试音以精确已知响度生成——合规、过响、过轻以及真峰值超标——每个判定都必须与其已知预期一致。
适用场景
需要在交付或发布前对音频响度做合规卡点的流程，尤其适合智能体自动化调用：可以仅凭退出码判定是否放行，或在 JSON 结果中读取偏差与修复命令。也可用于人工核查单个或批量媒体文件是否符合 EBU R 128、ATSC A/85 等正式标准。
限制与边界
- 只做测量与判定，不应用修复；修复需由调用方使用工具给出的偏差值配合 ffmpeg loudnorm 自行完成。
- 不覆盖响度修正、整文件 QC（编解码、色彩、节奏）、实时监听、图形界面。
- 不包含平台交付模板（Netflix、DPP、Apple TV+、Amazon、广播机构规范等）；仓库只收录正式且稳定的标准，平台规范变化不由本工具维护。
- BS.1770 模式不设合规目标，因此只返回 measured 判定与数值，不做通过/不通过判断。
- 需要外部依赖 ffmpeg 与 Python 环境；最低 ffmpeg 5.0。
扩展
欢迎补充其他正式标准：标准在 loudcheck/standards.py 中为纯数据，包含目标、容差与引用，无需改动代码。
