Reading a WaveLens report: what each check actually tells you

A WaveLens report never just says “pass” or “fail.” Underneath the overall verdict are six independent checks, each looking at a different way two audio files can stop being the same file. Here’s what each one is actually measuring, and what it means when one of them turns red.

Every run starts the same way: wavelens analyze takes a reference file and a device-under-test (DUT) copy, aligns them in time, then runs both through the same six-check battery.

$ wavelens analyze --ref reference.wav --dut device_under_test.wav --out report.html

wrote report.html (overall: FAIL -- Level Fidelity, Spectral Fidelity)

The one-line stdout summary gives the overall verdict and, when it is FAIL, the checks that failed it. The full report breaks the verdict down check by check, and that’s where the useful information actually lives. Two deeper checks, Time Domain and Impulse Template, are off by default; you turn them on with --deepscan and --impulse when you already suspect a problem.

Signal Alignment — the step before the six checks

Before any comparison can mean anything, both files need to be looking at the same moment in time. Signal Alignment finds the time offset between reference and DUT — a few samples of latency from a codec, a resampler, or a processing chain — and corrects for it before every other check runs. It gets its own section at the top of the report, but it isn’t one of the six checks below: it doesn’t produce a graded pass/fail result, it either succeeds quietly or the run stops early with an alignment error — because nothing after it means anything if the two files aren’t looking at the same instant. Right after alignment, WaveLens also checks that the DUT covers the reference’s whole length: a DUT that is materially shorter fails the Overall Verdict even if every check passed, so an incomplete capture can’t read as a clean PASS.

Spectral Fidelity

This is the frequency-domain comparison — does the DUT have the same frequency response as the reference, or has something rolled off the highs, boosted the low end, or introduced energy that wasn’t there before? A Spectral Fidelity failure usually points at filtering, EQ, or a lossy codec’s psychoacoustic model doing something audible.

Bit-Exactness

The strictest check on the report. Bit-Exactness asks a literal question: is every sample in the DUT identical to the corresponding sample in the reference? Not “close,” not “inaudibly different” — identical. A single flipped bit anywhere in the file fails this check.

This is also the check most likely to fail for reasons that don’t matter. Dither, a different but valid resampling implementation, or an intentional processing step will all break bit-exactness while leaving the audio perceptually identical. That’s exactly why it’s one check among six, and why by default it doesn’t gate the verdict — see Bit-Exact vs. “close enough” for when this one actually matters.

Level Fidelity

Checks that overall amplitude/gain wasn’t quietly changed somewhere in the chain — a mismatched gain stage, an unintended normalize, a broadcast chain applying makeup gain. Level Fidelity catches shifts that a spectral or loudness check alone might not flag clearly.

Artifact Detection

Scans for the kind of localized glitches a percentile-based check like Level Fidelity can miss entirely — dropouts, clicks, and spikes that don’t belong. A statistical outlier detector flags samples that break sharply from their local neighborhood, then reports exactly where the worst one starts. This is the check most likely to catch a corrupted frame or codec artifact that never shows up as a broad loudness or spectral shift.

Distortion

Compares the harmonic and noise floor content between files — has the DUT introduced clipping, quantization noise, or harmonic artifacts that weren’t present in the reference? This is where a bad gain-staging decision or an overloaded encoder tends to show up first. Distortion (THD+N) is a single-tone measurement, so for multitone or noise content you skip it with --no-distortion.

Loudness (BS.1770)

Measures integrated loudness, loudness range and true peak per the BS.1770 standard broadcasters actually use for delivery specs. A file can pass every other check and still read a different loudness if a normalization step or a broadcast chain moved it. By default the card is badged Reference Only: the reading is always shown, but it doesn’t fail the Overall Verdict unless you pass --loudness. See BS.1770 loudness, explained for what this measurement does and doesn’t catch.

Reading the overall verdict

The Overall Verdict rolls up the checks that gate, and by default not every check does. Spectral Fidelity, Level Fidelity, Artifact Detection and Distortion gate the verdict. Bit-Exactness and Loudness always run and always show their result, but a failure in either doesn’t fail the verdict unless you ask it to (--bitexact, --loudness), and the report says so explicitly rather than letting a PASS read as “everything matched.” The length check can fail the verdict on its own.

That’s deliberately not the end of the story. A report showing Bit-Exactness: FAIL next to five passes is telling you something very different from one showing Spectral Fidelity: FAIL and Level Fidelity: FAIL together. The point of six checks instead of one PASS/FAIL light is that you get to make that call yourself, with the actual evidence in front of you.