wavgen: generating repeatable test signals for regression suites

A regression suite is only as trustworthy as its test material is stable. If your reference signal is even slightly different every time you generate it, a 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.

Deterministic by default

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)

What it generates

• Tones — single-frequency sine waves at a specified frequency, level, and duration. The baseline for a distortion/noise-floor check.
• Sweeps — linear or logarithmic frequency sweeps, useful for exercising a full frequency range in one file rather than testing discrete tones one at a time.
• Multitone — several simultaneous frequencies in one signal, closer to how a Spectral Fidelity check would want to exercise a full frequency response at once.

Wrapping output for later trimming

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.

Building a regression suite around it

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.