Wiring wavsummary into a CI pipeline

A single 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.

What it actually does

wavsummary scans a directory of wavelens HTML reports, including every subfolder, and rolls them up into a single pass/fail summary page. It doesn’t re-run any checks and never reads a WAV file; it reads the verdicts wavelens already wrote into each report. Point --input at the folder and -o at where the summary should go:

$ wavsummary --input reports -o summary.html

wrote summary.html (2 wavelens reports: 1 passed, 1 failed)

The exit code is what a pipeline gates on. 0 means every report in the directory passed. 1 means at least one report failed, or a run errored, or a file couldn’t be read, or --input itself was invalid. (When wavelens analyze can’t compare two files, it writes a small error report instead of a normal one; the summary counts it as an errored run and shows the reason, so a failed comparison can’t go missing.) The summary page lists each failure with the checks that failed; a check that differs without gating, such as Bit-Exactness by default, is shown separately as “Not gating” rather than as a failure. Add --json and wavsummary also writes a summary.json next to the page, for dashboards and scripts.

The minimal CI step

The whole point is that this fits into a build system as one command with a meaningful exit code:

$ wavelens analyze --quiet --ref reference.wav --dut build/output.wav --out reports/output.html
$ wavsummary --input reports -o summary.html || exit 1

(--quiet suppresses the three progress lines wavelens prints to stderr, which keeps a CI log tidy.) 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 --quiet --ref "refs/$(basename $f)" --dut "$f" --out "reports/$(basename $f .wav).html"
  done
$ wavsummary --input reports -o summary.html --json

wavsummary never runs the analyses itself: producing the reports is the script’s job, and wavsummary picks up after that. A failed unit fails the build, and nobody has to remember to open a report by hand for it to count.

What to gate on, and what not to

It’s worth deciding upfront which failures should actually block a merge versus which should just be visible. wavsummary reads each verdict exactly as wavelens decided it, so the gating rules live in wavelens: by default a Bit-Exactness failure and a Loudness failure are shown but don’t fail the Overall Verdict, while Spectral Fidelity, Level Fidelity, Artifact Detection and Distortion do. 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”). Leave --bitexact off for that pipeline and the exit code stays meaningful, without anyone filtering wavsummary’s output after the fact. If a check never applies to your content, --no-bitexact or --no-loudness drops it from the reports entirely.

Archiving the evidence

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 summary — each row of the summary links to its report, so a red build comes with the exact report that explains why, not just a number.