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.

Repeatable by design

wavgen is one of the free tools in the toolkit — no license needed — and its output is repeatable. Given the same command, it writes the same file: the same tone, the same sweep, the same multitone burst, run to run. Tones, sweeps, square and sawtooth waves are computed directly from your parameters. Noise is the one signal that looks random, so it takes a --seed (1 if you leave it out), and the same seed always reproduces the same noise. We check this before every release: the same commands produce byte-identical files on Windows, macOS and Linux.

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 --mode tone --tone 1000:-20 --samplerate 48000 --bitdepth 24 --duration 5 -o tone_1khz.wav
wrote tone_1khz.wav (48000 Hz, 24-bit, 1 ch, 5.000s, 240000 frames)
$ wavgen --mode tone --tone 1000:-20 --samplerate 48000 --bitdepth 24 --duration 5 -o tone_1khz_again.wav
wrote tone_1khz_again.wav (48000 Hz, 24-bit, 1 ch, 5.000s, 240000 frames)
$ wavelens analyze --ref tone_1khz.wav --dut tone_1khz_again.wav --out report.html --bitexact

wrote report.html (overall: PASS)

What it generates

• Tones — one or more sine tones at a frequency and level you choose; repeat --tone for several at once. The baseline for a distortion/noise-floor check.
• Sweeps — linear or logarithmic frequency sweeps (linear-sweep, log-sweep), useful for exercising a full frequency range in one file rather than testing discrete tones one at a time.
• Level steps — an amplitude staircase (step-sweep) or a free-form sequence of levels (step-seq), such as a compressor attack/release burst.
• Noise — white or pink, set in RMS dBFS, with a seed.
• Square and sawtooth waves — band-limited, so they don’t alias on their own.
• Silence — digital zero, for noise-floor and gating tests.

A multitone file, several frequencies in one signal, is closer to how a Spectral Fidelity check wants to exercise a whole frequency response at once:

$ wavgen --mode tone --tone 500:-12 --tone 2000:-12 --tone 8000:-18 --samplerate 48000 --bitdepth 24 --duration 10 -o multitone.wav

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 --mode log-sweep --start 20:-6 --end 20000:-6 --samplerate 48000 --bitdepth 24 --duration 10 --synctone -o sweep_wrapped.wav
wrote sweep_wrapped.wav (48000 Hz, 24-bit, 1 ch, 15.500s, 744000 frames, sync-tone wrapped)

wavelens trim 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:

$ wavelens trim --input raw_capture.wav --out clean.wav

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 repeatable, 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.