Every run starts the same way: wavelens analyze takes a reference file and a device-under-test (DUT) copy, and runs both through the same six-check battery.
$ wavelens analyze --ref reference.wav --dut device_under_test.wav --out report.html wrote report.html (bit_exact: FAIL, level_fidelity: PASS, loudness: PASS)
The one-line stdout summary is a preview. The full report breaks the verdict down check by check, and that’s where the useful information actually lives.
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. If this check fails, every other result on the report should be treated with suspicion: the tool may be comparing the wrong samples to each other.
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.
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.
Bit-Exactness · sample 48,204 — the report names the exact sample where the files first diverge, so you're not hunting for it by ear.
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, not the whole verdict — see Bit-Exact vs. “close enough” for when this one actually matters.
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.
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.
Added in v0.7.0. Measures integrated loudness per the BS.1770 standard broadcasters actually use for delivery specs. A file can pass every other check and still fail loudness if a normalization step or a broadcast chain pushed it out of spec — see BS.1770 loudness, explained for what this measurement does and doesn’t catch.
The Overall Verdict is a rollup of all six — if any check fails, the run fails. That’s deliberately strict by default, and 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 Loudness: 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.
]]>Here’s a report from a real codec round-trip — encode, decode, done:
Signal Alignment PASS Spectral Fidelity PASS Bit-Exactness FAIL · sample 12 Level Fidelity PASS Distortion PASS Loudness PASS Overall Verdict PASS
Five checks pass, Bit-Exactness fails at sample 12 — the very start of the file, which is the tell: that’s almost always a dither pattern applied during the encode, not a real defect. The Overall Verdict is still PASS, because Bit-Exactness is non-gating by default. That’s not the tool shrugging off a failure; it’s the tool correctly recognizing that “not byte-identical” and “not the same audio” aren’t the same claim.
The cases where you genuinely need bit-exact equality are narrower than they first seem:
For any of these, add --bitexact to make a Bit-Exactness failure fail the overall verdict — otherwise it’s informational only, exactly as in the report above.
Everything else — did processing change the sound, not just the bytes — is what Spectral Fidelity, Level Fidelity, Distortion, and Loudness are built to answer, with real tolerances instead of a strict yes/no. A codec round-trip, a valid resampling implementation, or intentional dithering will all break Bit-Exactness while leaving those four checks clean, which is exactly what the report above shows. See Bit-Exactness vs. Bit Accuracy for the tolerant middle ground when you want a measured answer instead of a strict pass/fail, and Reading a WaveLens report for how all six checks combine into one verdict.
]]>The upgrade was three minor versions ahead of what the pipeline had been running, pulled in as part of a broader dependency refresh. Nothing in the changelog mentioned audio behavior. The listening pass — a quick A/B on a handful of representative files — came back clean; nothing sounded obviously wrong. It would have shipped on that basis alone if the nightly comparison hadn’t run.
The nightly wavelens comparison against the previous build’s reference output came back FAIL, with exactly one check marked:
Level Fidelity · consistent +1.4 dB offset across the full file duration — Spectral Fidelity, Distortion, and Loudness all reported PASS.
That pattern narrowed the search immediately. Not a quality regression — Spectral Fidelity and Distortion were both clean, so nothing had introduced new artifacts or reshaped the frequency response. Just amplitude, and consistently across the whole file rather than in one section, which pointed at something structural in the encode path rather than a one-off glitch.
A few minutes into the codec library’s changelog turned up the actual cause: a default had changed for an internal gain-normalization option, three versions back, buried in a “behavior changes” section rather than called out as a breaking change. The previous codec version hadn’t applied it; the new one did, silently, unless explicitly disabled.
+1.4 dB applied consistently across an entire file is genuinely hard to catch by ear in a quick listening pass — especially without an A/B reference playing at the exact same moment, which a quick spot-check pass usually doesn’t set up. It’s exactly the class of change a level-fidelity check is built to catch and a human review pass is built to miss.
The fix was a one-line configuration change to pin the old gain-normalization behavior. The more lasting change was to the release checklist: the nightly wavelens analyze comparison against the previous release’s output, which had been an informational step someone occasionally glanced at, became a required gate with wavsummary blocking the build on any failure.
$ wavelens analyze --ref previous_release.wav --dut candidate_build.wav --out reports/nightly.html --json $ wavsummary ./reports --json || exit 1
Not a replacement for listening — a catch for the class of regression a listening pass reliably won’t flag on its own.
]]>BS.1770 isn’t a peak meter and it isn’t RMS — it’s the ITU-R standard broadcasters actually use for delivery specs, and it works by applying a K-weighting filter (which de-emphasizes very low frequencies, roughly matching how the ear perceives loudness) before integrating the result over time. The output is a single number in LUFS (loudness units relative to full scale) that’s meant to correlate with perceived loudness far better than a raw amplitude measurement does.
wavelens runs this on both the reference and the DUT and compares the two integrated values against a tolerance.
$ wavelens analyze --ref reference.wav --dut device_under_test.wav --out report.html
wrote report.html (loudness: FAIL — integrated -14.2 LUFS vs -18.6 LUFS reference)
The most common cause of a Loudness failure isn’t distortion or a bad encode — it’s a delivery-chain step that adjusted overall level on purpose. A loudness normalization pass, a broadcast chain applying makeup gain, or a platform-specific loudness target (streaming services each have their own) can all push a file’s integrated loudness outside your reference’s tolerance while leaving every other check clean.
That’s not necessarily a bug in your pipeline — sometimes it’s the pipeline doing exactly what it was told to do. The report just tells you it happened; deciding whether it should have happened is still a human call.
Loudness is a whole-file, integrated measurement — there’s no single “worst sample” the way there is for Bit-Exactness or Distortion, because the whole point is that it’s averaged over time. That has two consequences worth knowing:
Loudness and Level Fidelity look related but answer different questions. Level Fidelity tracks amplitude/gain sample-by-sample against tolerance — it’s built to catch a mismatched gain stage or an unintended normalize as a local event. Loudness reports the integrated, perceptual result over the whole file. A file can fail one without the other: a brief gain glitch might trip Level Fidelity without moving the integrated LUFS enough to fail Loudness, and a deliberate whole-file loudness target change can fail Loudness while Level Fidelity — tracking relative shifts, not absolute targets — still passes.
If you’re triaging a report and only Loudness is marked, start by asking whether something in the chain was supposed to change overall level before you assume it’s a regression.
]]>wavelens analyze run answers “did this one file change?” wavsummary answers the question a CI pipeline actually needs: “did anything in this batch change?” — and it answers it with an exit code, not a report you have to open by hand.
wavsummary scans a directory of wavelens reports (the JSON output, written with --json alongside each report’s HTML) and rolls every one of them up into a single pass/fail summary. It doesn’t re-run any checks — it’s purely a rollup of results wavelens already produced.
$ wavsummary ./reports --json
142 reports · 3 failed
exit 1
Exit code 0 means every report in the directory passed. Anything else means at least one didn’t, and the summary output tells you which ones.
The whole point is that this fits into a build system as one command with a meaningful exit code:
$ wavelens analyze --ref reference.wav --dut build/output.wav --out reports/output.html --json
$ wavsummary ./reports --json || exit 1
In a real pipeline you’re usually generating many reports first — one per test file, one per platform build, one per content type — and then running wavsummary once at the end as a single gate:
$ for f in build/*.wav; do
wavelens analyze --ref "refs/$(basename $f)" --dut "$f" --out "reports/$(basename $f .wav).html" --json
done
$ wavsummary ./reports --json
A failed unit fails the build. Nobody has to remember to open a report by hand for it to count.
It’s worth deciding upfront which failures should actually block a merge versus which should just be visible. A codec round-trip that reliably fails Bit-Exactness but passes everything else isn’t a regression — it’s expected behavior for a lossy pipeline (see Bit-Exact vs. “close enough”). If that’s your situation, run wavelens analyze without --bitexact so Bit-Exactness stays non-gating, rather than filtering wavsummary’s output after the fact — the exit code stays meaningful, and nobody has to remember why a “failure” is actually fine.
wavsummary’s exit code is what gates the build, but the individual HTML reports are what someone actually looks at when a build fails. Most teams archive the reports/ directory as a build artifact alongside the wavsummary output — that way a red build comes with the exact report that explains why, not just a number.
wavelens only ever compares a mono or stereo pair — so multichannel content has to go through wavchan first. That step isn’t just a format conversion; it’s a real signal-processing operation with its own tolerances to think about before you compare.
A naive 5.1-to-stereo downmix — summing left and right surrounds straight into the stereo pair, full level — clips easily and throws away the spatial information a real downmix coefficient set is designed to preserve. wavchan’s downmix follows the standard ITU coefficients: front left/right pass through at unity, center is split evenly between the stereo pair at a reduced coefficient, and the surrounds are folded in at their own reduced level rather than full strength.
$ wavchan downmix --input program_5.1.wav --out program_stereo.wav --preset itu
That means a correct downmix is not bit-exact with any simple sum you’d compute by hand — the coefficients are doing real attenuation, not just channel routing.
Once you have a stereo file on each side of a pipeline change, the comparison itself is ordinary wavelens analyze — but the tolerances you’d use for a straight stereo-to-stereo comparison are often too tight for a downmix comparison, because small differences in how two downmix implementations round or dither can add up to real, non-bit-exact differences that aren’t a regression.
$ wavchan downmix --input program_5.1.wav --out ref_stereo.wav --preset itu
$ wavchan downmix --input program_5.1_reencoded.wav --out dut_stereo.wav --preset itu
$ wavelens analyze --ref ref_stereo.wav --dut dut_stereo.wav --out report.html
Bit-Exactness will very often fail here even between two correct downmixes — that’s expected, not a bug, the same way it’s expected after a codec round-trip. Spectral Fidelity and Level Fidelity are the checks that actually tell you whether the downmix changed in a way that matters.
Not every multichannel workflow wants a mixed-down stereo pair — sometimes you want the individual channels split out and compared separately, channel by channel, rather than folded together. wavchan split does that instead:
$ wavchan split --input program_5.1.wav --out-dir channels/
That gives you one mono file per channel (channels/FL.wav, channels/FR.wav, channels/C.wav, and so on), each of which wavelens can compare directly against its own reference — useful when you specifically need to know whether, say, the center channel alone changed, rather than whether the downmixed result changed.
The inverse operation — wavchan pack — takes separate mono/stereo files and interleaves them back into one multichannel file, for when a pipeline step needs multichannel input rather than the split-apart pieces.
The headline addition: a full integrated-loudness check per the ITU-R BS.1770 standard, running as a sixth check alongside Signal Alignment, Spectral Fidelity, Bit-Exactness, Level Fidelity, and Distortion. See BS.1770 loudness, explained for what it measures and where it has blind spots.
$ wavelens analyze --ref reference.wav --dut device_under_test.wav --out report.html
wrote report.html (loudness: FAIL — integrated -14.2 LUFS vs -18.6 LUFS reference)
Every report now shows an Analysis Mode tile indicating whether that run’s comparison used time-domain or frequency-domain alignment internally — useful when triaging a Signal Alignment result, since the two modes handle certain kinds of latency differently.
wavsummary output now includes a per-check failure breakdown, not just the overall pass/fail count.Upgrade notes: existing wavelens-defaults.cfg files don’t need any changes — Loudness runs with sensible defaults out of the box, and --no-loudness is available if you need to skip it for content without a meaningful loudness target.
Bit-Exactness is binary. Every sample in the DUT either matches the reference exactly, or it doesn’t — there’s no partial credit, no tolerance, no “close.” One flipped bit anywhere in the file is a fail. It’s the strictest check WaveLens runs, and by default it’s non-gating: a Bit-Exactness fail alone doesn’t fail the Overall Verdict, because plenty of correct, expected processing (a codec round-trip, a valid resampling implementation, intentional dither) breaks it without changing anything anyone can hear.
$ wavelens analyze --ref ref.wav --dut dut.wav --out report.html --bitexact
Add --bitexact when you specifically need to require byte-for-byte equality for a PASS — confirming a “lossless” claim actually holds is the usual reason.
--bitaccuracy adds a second, separate reading alongside Bit-Exactness — a tolerant, measured comparison expressed in dB, rather than a strict pass/fail. Where Bit-Exactness can only tell you “identical” or “not identical,” bit accuracy tells you how far off, which is the more useful number when you already expect some non-zero difference and want to know whether it’s within an acceptable range.
$ wavelens analyze --ref ref.wav --dut dut.wav --out report.html --bitaccuracy
The two flags are independent of each other — --bitaccuracy doesn’t change whether Bit-Exactness itself gates the verdict, it just adds the additional measurement to the report.
--bitexact. You want a hard yes/no, and any non-zero difference is a real finding.--bitaccuracy. A codec round-trip or a valid alternate resampling implementation will always show some numeric difference — the question is whether it’s small enough to not matter, and Bit-Exactness alone can’t answer that.--bitexact and --no-bitexact can’t be combined (they’re opposites), but --bitaccuracy can be added alongside either — you get the strict verdict and the measured distance in the same report.The report itself calls out explicitly when Bit-Exactness didn’t gate the verdict, so a PASS next to a Bit-Exactness FAIL never silently reads as “everything matched.”
]]>wavelens comparison against yesterday’s build and today’s build is comparing against two different things — and any diff you see might just be signal drift, not a real regression.
wavgen seeds every generator deterministically. Given the same parameters, it produces bit-identical output every time — the same tone, the same sweep, the same multitone burst, run to run, machine to machine. That’s what makes it safe to check a generated reference file into a repo (or regenerate it on demand in CI) without worrying that a “fresh” reference will silently differ from the one a previous build was compared against.
$ wavgen tone --freq 1000 --duration 5 --out tone_1khz.wav
$ wavgen tone --freq 1000 --duration 5 --out tone_1khz_again.wav
$ wavelens analyze --ref tone_1khz.wav --dut tone_1khz_again.wav --out report.html --bitexact
wrote report.html (bit_exact: PASS)
Real pipelines often need to capture audio through a system rather than compare a file directly — recording off a physical output, for instance — and a raw capture usually has extra silence or noise at the start and end. wavgen can wrap its output with a leading and trailing sync-tone marker for exactly this case:
$ wavgen sweep --start 20 --end 20000 --duration 10 --synctone --out sweep_wrapped.wav
wavelens trim (part of the core wavelens tool) finds both markers in a captured recording and extracts just the clean content between them, with a small silence guard on each side — and it fails loudly, with no output file, if it can’t confidently locate both markers, rather than guessing at where the real content starts.
The pattern most teams land on: generate a fixed library of wavgen reference material once (tones at standard frequencies, a representative sweep, a multitone burst), commit it or cache it in CI, and run every pipeline change against that same fixed set with wavelens analyze. Because the generation is deterministic, the reference library itself never needs regenerating unless you deliberately change it — which means every comparison in the suite is actually testing your pipeline, not testing whether your test material stayed the same.
wavscan doesn’t compare two files the way wavelens does — it inspects one file on its own, no reference needed. That makes it the right tool for a quick sanity check before committing to a full comparison, but only if you’re reading the right number for what you’re actually trying to catch.
$ wavscan --input mystery_file.wav
Peak: -0.8 dBFS
RMS: -18.3 dBFS
Crest factor: 17.5 dB
Sample rate: 48000 Hz
Channels: 2
No --ref, no verdict, no pass/fail — just a level and format snapshot of the file as it is.
Peak level is the loudest single sample in the file, full stop. It’s the number that matters for headroom and clipping — if peak is sitting at or above 0 dBFS, you’re clipping (or right at the edge of it), regardless of how loud the file sounds on average. Peak tells you nothing about perceived loudness; a file can have a high peak from one short transient while sounding quiet overall.
RMS (root mean square) is a windowed average of the signal’s energy — closer to “how loud does this sound,” though still not a perceptual loudness measurement the way BS.1770 is (see BS.1770 loudness, explained for that). RMS is useful for a quick relative comparison — “is this file noticeably quieter than that one” — without needing a full wavelens loudness check.
The difference between peak and RMS — crest factor — tells you something neither number alone does: how much of the file’s dynamic range is being used. A low crest factor (peak and RMS close together) usually means heavy compression or limiting; a high crest factor means the file has real dynamic range, with occasional loud moments well above the average level.
wavscan is the right call when you just need to eyeball one file — checking that a freshly generated wavgen reference isn’t clipping, confirming a captured file actually has signal in it before running a full comparison, or spot-checking level on a batch of files without a reference for any of them. It’s not a substitute for wavelens analyze once you actually have a reference to compare against — peak and RMS on a single file can’t tell you whether this file still matches that one, which is the question a real comparison answers.