audio_fidelity_mcp

What it does

Give it two audio files. It aligns them, then reports what changed:

• Perceptual scores: PEAQ Basic ODG (ITU-R BS.1387-1) and ViSQOL MOS-LQO (Google, speech or audio mode). POLQA (ITU-T P.863) runs if you point it at your licensed binary.

• Waveform measurements: sub-sample delay, SNR, segmental SNR, residual peak, correlation, optimal gain, clipping, BS.1770 loudness.

• Spectral measurements: log-spectral distance, bandwidth of each file, and a noise-to-mask ratio per Bark band that points at the bands where damage concentrates.

Setup is one config block. uv run reads the dependency block inside the script and installs everything on first run, so there is nothing to compile and nothing to download by hand.

Related MCP server: io.github.attenlabs/hotato

Setup

You need uv on the machine. Nothing else.

Paste the prompt below into your agent (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, or any LLM with shell access). It clones the repo, registers the server, asks about POLQA, and verifies that the backends came up.

Install the MCP server "audio_fidelity_mcp" (measures audio quality loss: PEAQ ODG,
ViSQOL MOS-LQO, POLQA wrapper).

1. Run `uv --version`. If uv is missing, stop and link me to
   https://docs.astral.sh/uv/getting-started/installation/. Do not install anything else,
   do not use pip or virtualenvs.

2. Ask me where to clone (default ~/Projects/audio_fidelity_mcp), then:
   git clone https://github.com/sittiev/audio_fidelity_mcp.git <path>

3. Ask me: "Do you have a licensed POLQA binary? (y/n)". If no, skip to step 4.
   If yes, ask for its path and add to the server entry:
     "env": { "POLQA_BIN": "<path>", "POLQA_ARGS": "-t {ref} -d {deg} -o {out}" }
   Mention that the default POLQA_ARGS is an assumption we could not test, and that the tool
   returns the binary's raw output so we can fix the flags if it fails.

4. Register the server. Prefer the CLI:
   Claude Code: claude mcp add audio-fidelity -- uv run <path>/audio_fidelity_mcp.py
   Other clients: add this block to that client's MCP config, with an absolute path:
     { "command": "uv", "args": ["run", "<path>/audio_fidelity_mcp.py"] }

5. Call server_info() through the MCP client and report which backends are up (PEAQ, ViSQOL
   speech, ViSQOL audio, POLQA). Then run visqol_score() on a speech WAV I point you at and
   report the MOS-LQO.

Do not edit files inside the repo.

git clone https://github.com/sittiev/audio_fidelity_mcp.git
cd audio_fidelity_mcp
uv run audio_fidelity_mcp.py        # headless stdio, deps resolved on first run

Register it in your MCP client (keep the path absolute):

{
  "mcpServers": {
    "audio-fidelity": {
      "command": "uv",
      "args": ["run", "/PATH/audio_fidelity_mcp/audio_fidelity_mcp.py"]
    }
  }
}

"env": {
  "POLQA_BIN": "/path/to/Polqa",
  "POLQA_ARGS": "-t {ref} -d {deg} -o {out}"
}

Tools

ODG runs from 0 (imperceptible) to -4 (very annoying). MOS-LQO runs from 5 (perfect) to 1 (bad). Identical files give ODG near +0.2 and MOS-LQO near 4.73, which are the ceilings of the two models, not a disagreement between them.

All tools take local paths. WAV, FLAC, OGG and MP3 are read natively; anything else works if ffmpeg is installed. Downmix to mono, resampling and alignment are handled for you. Every tool is marked readOnly, so calling one changes nothing.

Usage

Ask your agent to compare two files:

Compare /music/master.wav against /music/song_128.mp3 and tell me if the degradation is audible.

This is what comes back, cut down to the interesting fields:

{
  "alignment":  { "delay_samples": -0.007, "delay_ms": 0.0 },
  "time_domain":{ "snr_db": 24.8, "segmental_snr_db": 15.1, "correlation": 0.97 },
  "spectrum":   { "lsd_db": 6.2, "reference_bandwidth_hz": 20500, "test_bandwidth_hz": 16000 },
  "psychoacoustic_proxy": { "audible_time_freq_cells_pct": 3.1, "total_nmr_db": -12.4 },
  "peaq":       { "odg": -1.42, "odg_interpretation": "perceptible but not annoying",
                  "distortion_index": 0.9 },
  "visqol":     { "mode": "audio", "moslqo": 3.9, "vnsim": 0.88 },
  "verdict":    "Subtle degradation (few audible time-frequency regions in the proxy)"
}

More prompts are in MCP_USECASES.md.

Which metric to use

• Voice, speech and VoIP: visqol_score(mode="speech"). ViSQOL's speech mode was calibrated on speech and runs at 16 kHz. With a licensed binary, polqa_score is the telecom standard for calls.

• Music and audio codecs: visqol_score(mode="audio") at 48 kHz, and peaq_odg beside it.

• Long files: read the MOVs, not just the ODG. Bandwidth, Noise-to-Mask and Average Modulation Difference usually tell you where the damage is.

• IIR filters and anything else that distorts phase break time-domain SNR, because no single delay aligns every frequency. Trust the spectral numbers and the perceptual scores there.

What is verified

If the bundled PEAQ binary refuses to run (a noexec mount, antivirus), the server_info tool says why and PEAQ_BIN points it at another copy.

Limits

• PEAQ here is Basic, not Advanced. POLQA is a wrapper, and it needs your own licensed binary.

• ODG and MOS-LQO compare versions of the same material. They are not physical measurements, and they were not built to rank two different recordings against each other.

Credits

• peaqb, PEAQ Basic by G. Gottardi, with Akinori Ito's speed patch, plus FFTW 2.x. Source and COPYING are in vendor/.

• visqol-python, a pure-Python implementation of Google's ViSQOL.

• ai-edge-litert runs the lattice model, libsvm-official runs the audio SVR.

• Structure follows the mcp-builder guide.

License

GPL-3.0-or-later, because vendor/peaqb is GPLv2. See LICENSE and NOTICE for third-party components and the changes made to them.