Loudcheck

What chaoz23/loudcheck MCP server does

chaoz23/loudcheck MCP server turns ffmpeg loudness measurements into compliance decisions for media files. It supports EBU R 128, ATSC A/85, and BS.1770 measurement mode. EBU R 128 checks integrated loudness against −23.0 LUFS with a ±0.5 LU tolerance and limits true peak to −1 dBTP. ATSC A/85 checks −24 LKFS with a ±2 dB tolerance and requires true peak below −2 dBTP. BS.1770 reports measurements without applying a compliance judgment.

Results include the overall verdict, per-metric measurements, targets, tolerances, deltas, pass status, and citations for gated metrics. Failed checks also include a plain-language explanation and an ffmpeg correction command based on the measured delta. The tool reports loudness range as informational data. It does not modify media files or perform broader quality control such as codec, color, or cadence checks.

How it works

The implementation performs one ffmpeg analysis pass using the loudnorm filter in JSON output mode. The analysis provides integrated loudness, loudness range, true peak, and gating information. The returned measurement context includes the ffmpeg version, which is part of the result contract. The project cross-checks loudnorm readings against ffmpeg's ebur128 filter in its test suite.

The CLI can inspect the first audio stream in a video, select a particular stream, or evaluate all audio streams. It also accepts multiple files or a directory for batch processing. JSON output is intended for automation, while the exit status provides a simple delivery gate: 0 indicates pass, 1 indicates a non-compliant result, and 2 indicates an error such as a missing file, absent audio stream, or unavailable ffmpeg.

Setup and configuration

chaoz23/loudcheck requires Python 3.10 or newer and ffmpeg 5.0 or newer available on PATH. The MCP variant can be installed with the package's mcp extra. A zero-install invocation is:

uvx --from 'loudcheck[mcp]' loudcheck --mcp

Other documented installation choices are uvx loudcheck file.wav, pip install loudcheck for the CLI, and pip install "loudcheck[mcp]" for MCP support. The MCP process can also be started as loudcheck-mcp or with python -m loudcheck.mcp_server after installation.

No API key or external service credential is described. The server needs access to the local media path supplied to the tool and to the ffmpeg executable. The README does not specify environment variables or a client-specific configuration file.

Tools and capabilities

The MCP surface provides two tools:

• check_loudness(path, standard) evaluates a media file and returns the same structured result as the CLI.
• list_standards() returns the available standards and their citations.

The standard value selects EBU R 128, ATSC A/85, or BS.1770. The CLI additionally supports detailed output, batch summaries, per-stream selection, all-stream checks, and schema output. For a failed verdict, the remediation describes the gain adjustment and gives an example using ffmpeg filters such as volume or loudnorm; applying that correction remains the responsibility of the calling workflow.

Limitations and notes

chaoz23/loudcheck is for formal, stable loudness standards rather than platform-specific delivery templates. It is not a loudness correction engine, real-time monitor, GUI, or complete media QC system. Its measurements depend on the installed ffmpeg version, with version 5.0 listed as the minimum supported release. The project is licensed under MIT.