chaoz23/loudcheck

A **loudness compliance verdict**, not raw meter output. loudcheck measures
a media file with ffmpeg and answers the question that actually matters —
*does this file pass the spec?* — against formal published standards:
**Agents start here → SKILL.md** — when to call this, worked examples, MUST/MUST NOTs. Family contract: FAMILY.md.
- **EBU R 128** (European broadcast: −23.0 LUFS ±0.5 LU, max −1 dBTP)
- **ATSC A/85** (US television: −24 LKFS ±2 dB, true peak below −2 dBTP)
- **BS.1770** (measure-only: BS.1770 defines no compliance target, so this
mode returns verdict measured with the numbers and no judgment)
Ships as a CLI and an MCP tool over one engine, so agents and humans get the
identical verdict.
Why this exists
An agent (or an engineer) can run ffmpeg's ebur128 filter and get numbers.
What it can't get from a shell is the *verdict* — that requires knowing the
standard's target, tolerance, and gating, and interpreting integrated
loudness vs. LRA vs. true peak against them. Loudness is one of the most
common causes of delivery rejection, and the gap is not measurement — it's
the standards-aware answer. That's the whole tool.
Install
Requires Python 3.10+ and ffmpeg 5.0+ on PATH.
From a clone: pip install -e ".[mcp,dev]".
CLI
Batch mode prints one line per file (plus remediation for fails) and a
summary; --json in batch emits an array. Exit code is 1 if *any* file
fails.
For agents
- **Exit codes carry the verdict:** 0 = pass, 1 = fail (non-compliant),
2 = error (missing file, no audio stream, no ffmpeg). Gate a delivery on
the exit code alone.
- **--json is the full contract:** overall verdict, per-metric
measured/target/tolerance/delta/pass with the spec citation attached to
every gated metric, failures in plain English, and remediation with the
**exact correction** — a fail 2.3 LU over target tells you to apply
−2.3 LU gain and hands you the ffmpeg incantation. This tool never applies
the fix (measurement and verdict only); the agent one-shots it with
loudnorm using the delta provided.
- **MCP:** register loudcheck-mcp (stdio; or loudcheck --mcp, or
python -m loudcheck.mcp_server). Zero-install:
uvx --from 'loudcheck[mcp]' loudcheck --mcp. Tools:
check_loudness(path, standard) → same JSON as the CLI, and
list_standards() → the catalog with citations. Verified against
mcp==1.28.1.
- **tool.json** at the repo root describes the surface machine-readably —
or fetch it live from any install with loudcheck --schema (the file ships
inside the package; a test keeps the two copies in sync).
- **ffmpeg version is part of the contract:** every verdict includes
measurement_context.ffmpeg_version. Minimum supported: 5.0. Developed and
verified against 8.1.
The scope guardrail (read before contributing)
**Only formal, stable standards live in this repo; per-platform delivery
templates (Netflix, DPP, Apple TV+, Amazon, broadcaster specs) never do.**
Platform specs change unilaterally and cover far more than loudness — the