Skip to main content
Glama

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)

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

loudcheck demo: FAIL with exact fix, apply it, PASS, exit code carries the 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.

Related MCP server: music-perception-mcp

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

  • 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 moment they enter, this stops being a near-zero-maintenance community tool and becomes a yearly-maintenance product. If a PR adds a target that a platform can change on its own, it belongs in a separate template layer built on top of this primitive, not here.

Contributions of additional formal standards (e.g. a plain ITU-R BS.1770 mode) are welcome: a standard is pure data in loudcheck/standards.py — targets, tolerances, and citations. No code changes required.

How it measures

One ffmpeg pass with loudnorm=print_format=json (analysis mode) yields integrated loudness, loudness range, true peak (oversampled dBTP per BS.1770), and the gating threshold. The test suite cross-checks loudnorm's reading against ffmpeg's independent ebur128 implementation — the two must agree within 1 LU for CI to pass, so an ffmpeg release that changes filter behavior is caught by the suite, not by users.

Verification corpus

pytest generates calibrated test tones on the fly (no binaries in the repo): per BS.1770's calibration statement, a mono 997 Hz sine at 0 dBFS reads −3.01 LKFS, so tones are generated at exact known loudness — compliant, too loud, too quiet, and true-peak-hot — and every verdict must match its known expectation.

Out of scope, permanently

Loudness correction (use ffmpeg loudnorm with the delta this tool gives you) · full-file QC (codec/colour/cadence) · real-time monitoring · GUIs · platform delivery templates (see guardrail).

License

MIT

Available Tools

2 tools
check_loudnessA

Loudness compliance verdict for a media file against a formal published standard. Measures integrated loudness, loudness range, and true peak (via ffmpeg), then evaluates them against the named standard's targets and tolerances.

Args: path: media file to check (any format ffmpeg can read). standard: EBU_R128 (broadcast, -23 LUFS), ATSC_A85 (US TV, -24 LKFS), or BS_1770 (measurement only — verdict "measured", no gates). stream: zero-based audio stream index for multi-track files. detailed: also report max momentary / max short-term loudness (one extra ffmpeg pass).

Returns: dict with: verdict (pass|fail|measured), per-metric measured/target/delta and pass booleans, failures (plain-English causes), remediation (exact corrections, e.g. "apply -2.3 LU gain"), and measurement_context (ffmpeg version, stream info).

Inputs: path (required), stream, detailed, standard.

list_standardsA

List the standards this tool can verdict against, with their targets, tolerances, and spec citations.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one checks loudness against a standard, the other lists available standards. No overlap in functionality.

    Naming Consistency5/5

    Both tool names follow a consistent verb_noun pattern: check_loudness and list_standards. The naming is predictable and clear.

    Tool Count3/5

    With only 2 tools, the server is on the low end of the typical range. While the tools cover the core functionality, a batch processing tool or a tool to preview raw measurements would round out the set.

    Completeness4/5

    The server covers the main use case of loudness checking and provides standards listing. Minor gaps exist, such as batch processing or the ability to update standards, but the core workflow is complete.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Turns silent defects in AI-generated video and audio — wrong speaking pace, mismatched loudness, truncation, dead air, late captions, broken layout — into hard assertion failures inside tests and CI. Enables agents to check individual files or whole output directories against platform presets, returning pass/fail exit codes and human-readable bug reports instead of raw measurements.
      18 PyPI
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to compare a processed audio file against its reference and report how much perceptual quality was lost, using PEAQ ODG, ViSQOL MOS-LQO and an optional licensed POLQA binary, plus waveform, loudness and Bark-band spectral metrics. Runs headless over stdio, installs itself with uv, and returns rankings across codecs or bitrates.
      GPL 3.0