loudcheck MCP server

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.

mode returns verdict measured with the numbers and no judgment)

• 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

$ 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)

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.

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

From a clone: 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

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

Shortened. The full README is on GitHub.