audio-compare

Use this when you (an agent) need to weigh in on a DSP change: render/capture the audio before and after, then get a defended judgment — "did this make it worse?" — with cited evidence, not a bare pass/fail. It wraps the Audio Quality Lab's compare surface (tools/audio/quality-lab/, opt-in Python; see the audio-harness skill for the full vocabulary and rationale). Advisory and off-gate: it never fails a build.

Not this — reach for the gate instead when you just want an exact/numeric/spectral before-after diff with a pass/fail exit: use pulp audio validate compare a.wav b.wav [--mode null|spectral] [--tolerance <dbfs>] (shipped, deterministic, gate-oriented). Use /audio-compare when you want an interpreted judgment an agent can act on.

One-time setup (opt-in deps)

pulp tool install audio-quality-lab      # managed venv under ~/.pulp/tools
# — or a plain checkout venv —
cd tools/audio/quality-lab && python3 -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt

Run it

Invoke with two WAVs ($ARGUMENTS = <reference.wav> <candidate.wav> [extra flags]):

# Preferred — the shipped CLI verb (delegates to the managed tool; no venv juggling):
pulp audio compare $ARGUMENTS --profile tonal-balance --json /tmp/compare.json
# Equivalent lower-level forms:
#   pulp tool run audio-quality-lab -- compare $ARGUMENTS
#   python -m quality_lab.cli compare $ARGUMENTS
# Agents inside an MCP client can call the pulp_audio_compare tool for the report JSON directly.

• --reference-role golden — declare the reference known-good and the candidate expected unchanged. This is the ONLY mode that can return regression_suspected.
• default --reference-role peer — a neutral A/B; a changed candidate reads as material_change_detected, never "regression" (we don't assume which side is right).
• --profile — the measurement axis. Six today:
  • tonal-balance — LTAS spectral-centroid shift; bad direction duller.
  • added-hf — band-relative ≥8 kHz fraction ratio (dB); bad direction added HF fizz.
  • noise-roughness — harmonic-to-noise ratio drop (dB); bad direction rougher/noisier (tonal material).
  • graininess — relative spectral-flux increase; bad direction grainier (tonal material).
  • stereo-width — RMS(side)/RMS(mid) width + interchannel correlation; bad direction narrower/collapsed, and an out-of-phase candidate is flagged (needs 2-channel input; mono → not_applicable).
  • transient-integrity — per-onset attack-smear deficit (onset-aligned); bad direction softer/smeared attacks. Needs onset-bearing (percussive) material (too few onsets → not_applicable); one-directional (a sharper candidate reads no change).
  • regression_suspected also requires the change to be in that axis's bad direction — a brighter candidate on tonal-balance, or an HF-reduced one on added-hf, stays a neutral material_change_detected. New axes auto-appear in --profile; time-warp axes are deferred.
• --align <none|latency|varispeed:R|stretch:R|pitch:S|ratio:auto> — time-align first. latency trims a constant delay/offset before measuring, so a pure shift (delay plugin, tempo-sampler offset) reads as the tone change it is (corroborated) instead of a false not_corroborated; it refuses and measures unaligned when the difference isn't a reliable pure delay. Default none.
• --threshold <t> — override the axis's own materiality default (per-axis unit/range; the tool validates it — a fraction for tonal-balance, dB for added-hf/noise-roughness, etc.).