loudcheck

Purpose

loudcheck addresses one of the most common rejection reasons in audio delivery: loudness non-compliance. It goes beyond measuring numbers with ffmpeg; it interprets those numbers against the official delivery targets, tolerances, and gates, directly answering the key question of whether a file will pass the specification.

Key Capabilities

• Gives a compliance verdict per standard, rather than a raw level meter output.
• Supported standards: EBU R 128 (−23.0 LUFS ±0.5 LU, max −1 dBTP), ATSC A/85 (−24 LKFS ±2 dB, true peak below −2 dBTP), BS.1770 (measurement-only mode; this standard does not define a compliance target, so it returns a measured verdict with values and makes no compliance ruling).
• The JSON output is the complete contract: it includes the overall conclusion; each gate-constrained metric comes with the measured value, target value, tolerance, deviation, and pass/fail, along with the standard citation; failure reasons are explained in plain English; remediation advice gives the exact correction amount, for example "2.3 LU over target" will suggest applying a −2.3 LU gain, together with the corresponding ffmpeg command.
• The same engine provides both CLI and MCP, so agents and human users get consistent verdicts.
• Batch mode outputs one line per file (failed items include remediation advice) and gives a summary; in batch mode, --json outputs an array; the exit code is 1 if any file fails.
• Exit codes carry the verdict: 0 pass, 1 non-compliant, 2 error (file missing, no audio stream, no ffmpeg). Delivery pipelines can be gated on the exit code alone.
• tool.json at the repository root describes the interface in a machine-readable way, and loudcheck --schema can retrieve it live from any installation.
• Every verdict includes measurement_context.ffmpeg_version; the minimum supported ffmpeg is 5.0, with development and validation based on 8.1.

Usage

Requirements: Python 3.10+, and ffmpeg 5.0+ on PATH.

Install from clone: pip install -e ".[mcp,dev]".

MCP registration: loudcheck-mcp (stdio mode), or loudcheck --mcp, or python -m loudcheck.mcp_server.Zero-install method: uvx --from 'loudcheck[mcp]' loudcheck --mcp. MCP tools include check_loudness(path, standard) (returns the same JSON as the CLI) and list_standards() (returns the catalog of standards with specification references). Verified against mcp==1.28.1.

Agent entry point: SKILL.md explains when to call it, complete examples, and MUST/MUST NOT rules; the family contract is in FAMILY.md.

Measurement principle

Uses a single ffmpeg pass, calling loudnorm=print_format=json (analysis mode), to obtain overall loudness, loudness range, true peak (oversampled dBTP per BS.1770), and gating thresholds. The test suite cross-checks loudnorm's readings against ffmpeg's independent ebur128 implementation; the two must agree within 1 LU to pass CI, so if a change in ffmpeg version alters filter behavior it is caught by the test suite rather than discovered by users.

Verification method

pytest generates calibration test tones at runtime (no binary files are included in the repository): per the BS.1770 calibration notes, a 0 dBFS mono 997 Hz sine wave reads as −3.01 LKFS, so test tones are generated at precisely known loudness—compliant, too loud, too quiet, and true-peak-exceeding—and every verdict must match its known expectation.

Applicable scenarios

Processes that need a compliance gate on audio loudness before delivery or release, and especially suitable for automated invocation by agents: whether to allow release can be decided from the exit code alone, or the deviation and remediation commands can be read from the JSON result. It can also be used for manual verification of whether single or batch media files comply with formal standards such as EBU R 128, ATSC A/85, and others.

Limitations and boundaries

• Performs measurement and verdicts only; it does not apply fixes; fixes must be done by the caller using the deviation values provided by the tool together with ffmpeg loudnorm.
• Does not cover loudness correction, whole-file QC (codec, color, cadence), real-time monitoring, or a graphical interface.
• Does not include platform delivery templates (Netflix, DPP, Apple TV+, Amazon, broadcaster specifications, etc.); the repository includes only formal and stable standards, and changes to platform specifications are not maintained by this tool.
• BS.1770 mode has no compliance target, so it only returns the measured verdict and values, without making a pass/fail judgment.
• Requires the external dependencies ffmpeg and a Python environment; minimum ffmpeg 5.0.

Extending

Additional formal standards are welcome: standards are pure data in loudcheck/standards.py, containing targets, tolerances, and references, with no code changes required.