wavelens

Overview

wavelens answers one question, precisely: does this DUT file sound the same as this reference file, and if not, how? It runs a battery of independent checks — an exact sample comparison, a level-matching check, a distortion/noise scan, a spectral (frequency-response) comparison, a loudness comparison, and a few optional deeper checks — and folds the results into one HTML report you can open in any browser.

Every report is self-contained — a single HTML file with everything embedded (charts, data, styling). Nothing to install to view it, nothing else to send along with it.

Input requirements

• File format: 16-bit, 24-bit or 32-bit integer PCM, or 32-bit or 64-bit floating-point WAV, plain or WAVEX. Anything else (8-bit, compressed, non-PCM) is rejected at load time with a clear error — never silently converted.
• Floating-point files: values above 0 dBFS are read as they are and are not treated as clipping. A file containing NaN or infinite samples is refused, and the error names the first one. When either file is floating-point, Bit-Exactness measures the size of a difference in 24-bit steps.
• Sample rate: 22,050 Hz to 192,000 Hz inclusive. Covers every standard rate in common use (22.05k, 24k, 32k, 44.1k, 48k, 88.2k, 96k, 176.4k, 192k).
• Channels: mono or stereo. Reference and DUT must have the same channel count.
• A valid WaveLens license — see License setup below.

License setup

wavelens requires an active license file to run. It looks for one in this order — the first mechanism that resolves wins:

1. The --license flag — an explicit path, always wins if given.
2. The WAVELENS_LICENSE_FILE environment variable, if set.
3. A defaults file's general.license_path setting — see The defaults file.
4. Zero configuration: a file named exactly wavelens.lic sitting in the same folder as the wavelens executable.

# explicit path
wavelens analyze --license /path/to/wavelens.lic --ref ref.wav --dut dut.wav --out report.html

# or, once per shell session
export WAVELENS_LICENSE_FILE=/path/to/wavelens.lic
wavelens analyze --ref ref.wav --dut dut.wav --out report.html

# or simplest: drop wavelens.lic next to the wavelens executable and pass nothing

Not sure which license file wavelens would actually pick up, or whether it's still valid? Run wavelens license info — it tells you exactly which of the four mechanisms resolved, and the license's status.

Quick start

Compare a reference file against a DUT and write an HTML report:

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

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

Open report.html in any browser. The one-line stdout summary gives the overall verdict and, when it is FAIL, the checks that failed it. The report has the full picture, including which checks determine the overall pass/fail (a byte-exact mismatch alone doesn't fail a lossy-codec comparison by default — see The checks it runs).

New to WaveLens? Your first comparison walks through these steps one at a time and says what to expect at each one.

Commands

Run wavelens --help (or -h) to print the full usage in the terminal. It also works after a command, for example wavelens analyze --help, and needs no license.

# stop the pipeline on a FAIL verdict
wavelens analyze --exit-code --quiet --ref ref.wav --dut dut.wav --out report.html
# exit 0: PASS  ·  exit 2: FAIL  ·  exit 1: could not run

# exact output path
wavelens analyze --ref ref.wav --dut dut.wav --out results/my_report.html

# directory mode -- named automatically from the DUT's filename
wavelens analyze --ref ref.wav --dut dut.wav --out results/

# also write the raw numbers as JSON
wavelens analyze --ref ref.wav --dut dut.wav --out report.html --json

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

# capture the detection diagnostics (offsets, detection confidence) as JSON instead of stdout
wavelens trim --input raw_capture.wav --out clean.wav --report offsets.json

wavelens plot --input mystery_file.wav --out plot.html

# also write the file's own metadata as JSON
wavelens plot --input mystery_file.wav --out plot.html --json

wavelens license info

# example output
License File:    /opt/wavelens/wavelens.lic (next-to-executable default)
License ID:      b7b64b7e-904c-47d2-9c7c-47e00d463949
Customer:        you@example.com
Name:            Jane Doe
Product:         wavelens
License Type:    PERSONAL
Expiry:          2027-01-01
Signature:       VALID
License Status:  ACTIVE

Reading reports

Every report opens with an Overall Verdict — PASS or FAIL — at the top, followed by a row of navigation tabs, one per check that ran. A tab is marked when its own check failed, so you can jump straight to the section that needs attention instead of scrolling through everything.

Below that, each check gets its own section: what it measured, the numbers, and (for a failure) exactly where in the file the worst discrepancy was found. Charts are interactive — zoom and pan on the spectral and waveform-overview charts to inspect a specific region closely.

The checks it runs

Six checks run on every comparison by default; two more are available if you ask for them with a flag. Before any of them, Signal Alignment time-syncs the reference and DUT — that step gates the whole comparison (it can stop the run early with an alignment error) but isn't counted among the six, since it doesn't produce a graded pass/fail result of its own. See Reading reports above for where it shows up in the report. Immediately after it, a length-coverage check confirms the aligned DUT actually contains the reference's entire length — see the callout below.

Distortion doesn't fit every kind of content

Distortion (THD+N) is a single-tone measurement — it needs one dominant frequency to measure against. If your reference is multitone, broadband noise, or heavily clipped content with no single dominant tone, this check isn't meaningful and you should skip it with --no-distortion.

Understanding a failure

Each failed check's section shows the specific numbers that tripped its tolerance, and — where it makes sense for that check — exactly where in the file (which sample, which frame, which frequency) the worst point was found. Loudness is the one exception: it's a whole-file measurement, so there's no single "worst sample" to point to.

A quick way to triage a large batch of reports: check the nav tabs first. A report with only Bit-Exactness marked (and nothing else) is very different from one with Spectral Fidelity and Distortion both marked — the first might be an expected lossy-pipeline result, the second is a real, audible discrepancy worth investigating.

For stereo files, Signal Overview (the always-present full-waveform card at the top of the report) shows a full Left Channel envelope followed by a full Right Channel envelope — not just one channel's waveform standing in for both. Failure-position markers only ever apply to a specific channel's own data, so they only ever appear on that channel's chart, not overlaid on the other one.

A reading right at a tolerance line gets a tiny allowance for measurement noise. No real DSP pipeline (dB conversion, FFT, bit-depth quantization) produces an exact number for something like a synthesized "flat 1dB shift" — the true measurement lands a few millionths of a dB to one side or the other, depending on the specific frequency and level involved, not on anything wrong with your content. Level Fidelity, Spectral Fidelity, and Loudness all absorb that noise with a very small built-in allowance before deciding pass/fail, so a signal that's genuinely indistinguishable from your tolerance gives the same result whichever frequency happens to be tested. This doesn't loosen what you configure — a real difference worth catching is many orders of magnitude larger than the allowance, so nothing that should fail starts passing.

The defaults file

Rather than pass the same flags on every run, drop a wavelens-defaults.cfg file next to the wavelens executable. It's picked up automatically — no flag needed. Without it, wavelens simply uses its built-in defaults; the file only lets you replace them with your own.

{
  // wavelens-defaults.cfg -- // comments are supported
  "general": {
    "license_path": "/opt/wavelens/wavelens.lic"
  },
  "analysis": {
    "level_fidelity": {
      "p99_tolerance_db": 1.2
    },
    "loudness": {
      "integrated_tolerance_lu": 0.75
    }
  }
}

Want to use a defaults file from a non-default location, or check the file itself explicitly? Pass --defaults-cfg <path> on any command — available everywhere --license is.

wavelens analyze --defaults-cfg /opt/wavelens/wavelens-defaults.cfg --ref ref.wav --dut dut.wav --out report.html

Seeing every default at once

A ready-made wavelens-defaults.cfg ships next to the wavelens executable. It lists every tunable field as a compact // "field": built-in-value line, all still commented out — so it's exactly as inert as having no defaults file at all, every field falling straight through to the built-in default — and doubles as a one-page reference for what every setting defaults to. Because it sits next to the executable under exactly this name, it's picked up automatically; to change a default, uncomment that one line and edit its value, and leave everything else as it is.

Used unedited, it changes nothing at all — with every field commented out, it behaves identically to no defaults file being present. That also means it's safe to keep around indefinitely: a file made only of commented-out lines never goes stale against a future built-in change, since it was never actually setting anything. (Once you uncomment a line, that value is yours — it won't follow a later change to the built-in default.)

Tester identity in the footer

Every report's footer shows the tool version, license, and timestamp. If you also want it to show who ran the test — useful for a report handed to a client, or archived for your own records — set any of test_engineer, test_product, test_company_name in your defaults file's general section, and flip tester_info_enabled to true. None of the four is set by default. A defaults file with the identity values set but tester_info_enabled left false (or omitted) doesn't show them — you need both the identity values and tester_info_enabled: true for anything to appear.

{
  "general": {
    "test_engineer": "J. Rivera",
    "test_product": "SuperBass",
    "test_company_name": "Acme Audio Labs",
    "tester_info_enabled": true
  }
}

All three identity fields are optional and independent — set only the ones that apply. The footer combines them as Tested by ENGINEER · COMPANY · product PRODUCT, each part present only if you set it; an empty string ("") is treated the same as leaving the field out entirely.

test_company_name is for when the organization running the test isn't the one that built test_product — a lab testing a client's implementation, for example. It's descriptive text for the report, not tied to your license in any way — it doesn't need to match your license's own organization field.

Named shortcuts: general.default_profile

For the common "just turn this on" case, default_profile expands to the individual field(s) it implies, instead of you writing those out by hand. It belongs to the analysis settings' general section: in a --config file that's the top-level "general" section; in wavelens-defaults.cfg it's the "general" section nested under "analysis". (The defaults file's own top-level "general" section, which holds the tester-identity fields above, is a different one.)

// --config file: turn on Time Domain, same effect as --deepscan
{
  "general": {
    "default_profile": "time_domain"
  }
}

// wavelens-defaults.cfg: same thing, one level deeper
{
  "analysis": {
    "general": {
      "default_profile": "impulse_domain"
    }
  }
}

Any other value is rejected — analyze stops with an error naming all seven valid values, rather than silently ignoring a typo. An explicit field set anywhere else in the same file always wins over whatever the preset would have implied for that field — for example, default_profile: "time_domain" alongside an explicit "time_domain": { "enabled": false } in the same config leaves Time Domain off, the explicit value winning as usual.

This is equivalent to passing the corresponding CLI flags — reach for whichever is more convenient for how you're running wavelens: a flag for an ad-hoc run, default_profile for a config file you reuse across many runs.

Shared low-level-signal threshold: general.low_level_signal_threshold_db

A single dB level below which content counts as "quiet," shared across three places that would otherwise each need their own copy of the same number: fine alignment's own silence detection, Spectral Fidelity, and Time Domain. All three already default to -70.0dB on their own, so setting this field doesn't change anything by itself — it just lets you move that line once instead of three times. Same nesting rule as default_profile above — top level in a --config file, under "analysis" in wavelens-defaults.cfg.

{
  "general": {
    "low_level_signal_threshold_db": -60.0
  }
}

An explicit spectral_fidelity.low_level_signal_threshold_db or time_domain.low_level_signal_threshold_db (in either --config or wavelens-defaults.cfg) still takes precedence over this shared one for that check. Fine alignment has no check-specific field of its own, so for alignment this shared field — or the built-in default — is all there is.

The matching tolerance fields — spectral_fidelity.low_level_signal_tolerance_db (a dB figure) and time_domain.low_level_signal_tolerance_pct (a percentage) — stay independent of this setting. Both checks can run in the same analyze call (--deepscan adds Time Domain alongside the always-on Spectral Fidelity), and the two fields use different units, so one shared number couldn't serve both.

Length-mismatch tolerance: general.length_mismatch_tolerance_pct

How much of the reference file's own length the aligned DUT may leave uncovered before analyze flags a length mismatch and fails the overall verdict — the setting behind the length-coverage check (see The checks it runs) that catches a DUT materially shorter than its reference, rather than silently scoring only the portion that lined up. Default 1.0 (percent).

{
  "general": {
    "length_mismatch_tolerance_pct": 2.0
  }
}

Unlike the threshold field above, this one has no per-check override — it applies once, to the whole comparison.

Alignment tuning

Two fields live under a "alignment" section, for the rare case where a file's own timing characteristics trip up the default detection:

{
  "alignment": {
    "fine_align_agreement_tolerance_samples": 2,
    "sync_search_window_sec": 45.0
  }
}

fine_align_agreement_tolerance_samples (default 2) — for stereo input, the left and right channels are aligned independently, and if their computed offsets disagree by more than this many samples, analyze stops with an alignment error rather than risk comparing mis-synced audio. If you know your DUT introduces a genuine, small per-channel delay difference (some multiband processors do), raise this value to allow for it.

sync_search_window_sec (default 45.0) — how many seconds trim scans, from each end of the file inward, looking for the leading/trailing sync-tone burst (analyze itself never uses this field — it only matters when a file still carries the sync-tone wrapper and needs trim run on it first). The default already covers a typical hardware capture's pre-roll (silence, or the analyzer's own noise floor, before the tone — an Audio Precision capture, for example); widen it further if yours runs past roughly 40 seconds. It's also capped at half the file's own total length regardless of what you set, so the leading and trailing searches can never overlap on a short file — trim prints a note on stderr whenever that cap actually reduces the value you configured, so a failure caused by it is diagnosable rather than a mystery.

A few more advanced alignment fields exist beyond these two, for harder cases — contact support if the above don't resolve an alignment issue you're hitting.

Per-run overrides

For a one-off comparison that needs different tolerances than your usual defaults, pass --config <file.json> to analyze. Anything the file doesn't mention falls back to your defaults file (or the built-in default, if you don't have one) — you only need to specify what you're actually changing.

// loose_tolerance.json -- just this one run's Level Fidelity tolerance
{
  "level_fidelity": {
    "p99_tolerance_db": 2.0
  }
}

wavelens analyze --ref ref.wav --dut dut.wav --out report.html --config loose_tolerance.json

A ready-to-edit example ships next to the executable as user-config.json. It's a sample --config file for a single run — never loaded automatically, so pass it explicitly (analyze --config user-config.json) — using the same field names as the "analysis" section of wavelens-defaults.cfg. It's a sampler of different kinds of override, not a recommended setup: Spectral Fidelity's peak_tolerance_db (0.1), low_level_signal_threshold_db (-65.0) and signal_tolerance_db (4.0); Level Fidelity's p99_tolerance_db (1.5); Distortion switched off with distortion.enabled: false (the config-file form of --no-distortion); and Artifact Detection made non-gating with artifact.gates_overall: false (the config-file form of --artifact-ref-only). Copy it, delete the entries you don't need, and keep only what a given run actually changes.

Precedence, highest first: --config for this run > your wavelens-defaults.cfg > the built-in default. A convenience flag like --bitexact (below) always wins outright over either config file.

Turning checks on and off

Full flag reference

Examples

Standard codec/pipeline verification

Byte-for-byte equality isn't expected (it's a lossy pipeline), so leave Bit-Exactness non-gating — the default. This suits test signals (tones, sweeps, multitones) and regression checks; for music or speech through a lossy codec, see the next example:

wavelens analyze --ref original.wav --dut after_codec.wav --out report.html

Lossy codec on music or speech: compare against a golden output

WaveLens compares waveforms, so a perceptual codec that sounds transparent still fails on music or speech — typically Level Fidelity and Distortion, which compare sample by sample, and often Spectral Fidelity. To catch a regression in a codec, an encoder setting or a build, keep the decoded output of a version you trust and compare every new decoded output against it. With the same codec and settings the two are identical or very close, so any change stands out:

# golden_decoded.wav: the decoded output of the build you trust; new_decoded.wav: the same content from the new build
wavelens analyze --ref golden_decoded.wav --dut new_decoded.wav --out report.html --bitexact

Use --bitexact when the codec is deterministic, so any difference fails the verdict; leave it off to see how large a difference is. Whether a codec is transparent to the ear is a listening question, and WaveLens does not make that judgment.

Strict lossless verification

Confirming a "lossless" claim actually holds — require byte-exactness to pass:

wavelens analyze --ref original.wav --dut should_be_identical.wav --out report.html --bitexact

Broadcast-safety verification

Loudness runs by default but doesn't gate the overall verdict — its reading is shown as Reference Only, since a lossy codec or a processing chain can shift the loudness or raise the true peak on purpose (see above). If loudness/delivery compliance is actually what you're validating, require it to pass:

wavelens analyze --ref original.wav --dut delivery_master.wav --out report.html --loudness

Multitone or noise-based content

Skip Distortion (THD+N doesn't apply — see above):

wavelens analyze --ref multitone_ref.wav --dut multitone_dut.wav --out report.html --no-distortion

Frequency-sweep content with a tighter loudness tolerance

wavelens analyze --ref sweep_ref.wav --dut sweep_dut.wav --out report.html \
    --freqsweep --config tight_loudness.json

Here tight_loudness.json contains { "loudness": { "integrated_tolerance_lu": 0.25 } } — a tighter Loudness tolerance than the default 0.5.

Amplitude-sweep content

wavelens analyze --ref ampsweep_ref.wav --dut ampsweep_dut.wav --out report.html --ampsweep

Deeper checks for content you're specifically suspicious of

Time Domain and Impulse Template are off by default because they're slower, whole-file scans — worth turning on when you already suspect a problem and want more evidence:

wavelens analyze --ref original.wav --dut suspect.wav --out report.html --deepscan --impulse

A tolerant bit-level reading alongside the strict one

Keep Bit-Exactness non-gating but also see how close the DUT gets, in dB, when it isn't byte-identical:

wavelens analyze --ref original.wav --dut dut.wav --out report.html --bitaccuracy

Content whose spectrum changes over time

Take multiple spectral snapshots across the file instead of one fixed midpoint:

wavelens analyze --ref long_program.wav --dut long_program_dut.wav --out report.html --snapshots 5

Content with an intermittent fault

A steady tone, a step sequence or any other content with no sweep profile that you still want checked from start to end:

wavelens analyze --ref tone_ref.wav --dut tone_dut.wav --out report.html --config whole_file.json

Here whole_file.json contains { "spectral_fidelity": { "continuous": true } }.

Skipping a check that's expected to fail across a whole batch

Rather than a permanent FAIL badge on every report, drop the check entirely — no scan, no field, no card. Works the same way for any always-on check:

# e.g. every DUT in this batch is a lossy re-encode, so Bit-Exactness never applies
wavelens analyze --ref ref.wav --dut dut.wav --out report.html --no-bitexact

# e.g. content with no meaningful loudness target (short effects, clicks)
wavelens analyze --ref ref.wav --dut dut.wav --out report.html --no-loudness

Errors & troubleshooting

FAQ

Can WaveLens tell me whether a lossy codec is transparent on music?

No. A perceptual codec keeps the sound but not the exact waveform, and WaveLens's checks compare waveforms, so music or speech through a lossy codec fails Level Fidelity and Distortion, and often Spectral Fidelity, even when it sounds transparent (320 kbps AAC or MP3, for example). On test signals the verdicts fall in a sensible order: tones and sweeps pass at high bitrates and fail at low ones, and a sweep shows where a codec cuts off the top of the spectrum. For real content, use WaveLens to catch regressions — compare each new decoded output against a golden output from a build you trust (see Examples) — and judge transparency by listening.

Why did my report show Overall Verdict: PASS even though Bit-Exactness failed?

That's expected by default — see the callout in The checks it runs. Byte-exactness isn't required for an overall pass unless you pass --bitexact. The report itself always calls this out explicitly so it doesn't read as "everything succeeded" when one check structurally couldn't.

Why did my report FAIL even though every individual check passed?

Check the Signal Alignment card for a "Length mismatch" warning. Every check only ever looks at the region where ref and DUT actually overlap after alignment — if the DUT is materially shorter than the reference (an incomplete capture, most commonly), that covered region can pass every check cleanly while a real chunk of the reference was never compared at all. This one check has no softening flag, unlike every other check in this guide, because there's no legitimate reason to want a materially incomplete comparison to read as a clean PASS. See the callout in The checks it runs.

Why does my Loudness card say "Reference Only" instead of Pass or Fail?

Same idea as Bit-Exactness above, for the opposite reason: Loudness runs and its reading is always shown, but doesn't gate the overall verdict unless you pass --loudness. Its True Peak check compares the DUT's true peak with the reference's, so a DUT that peaks more than 0.5 dB higher fails it — codec overshoot is the usual cause — see the True Peak question below.

Why does a silent test file still produce a report?

A silent channel (ref, DUT, or both, below general.low_level_signal_threshold_db) never fails alignment on its own — see the callout in The checks it runs. You get a real report either way: a clean pass if both sides are genuinely silent, or a real FAIL from Bit-Exactness/Level Fidelity if only one side is — whether that's a DUT that went silent or one that leaked content into a channel meant to stay silent. The error: alignment failed messages are reserved for genuine problems — see Errors & troubleshooting.

When does True Peak fail?

True Peak compares the DUT with the reference: the DUT's true peak may exceed the reference's by at most 0.5 dB (loudness.true_peak_tolerance_db), and a DUT that peaks lower always passes. Identical files therefore always pass, even when the reference is mastered at full scale and itself reads above 0dBTP.

True Peak estimates the reconstructed analog waveform between the samples (oversampled, matching what a real DAC does), not just the samples on the grid. A file can keep its integrated loudness and still clip on reconstruction — a lossy codec or a limiter in the chain can raise those inter-sample peaks — and this is the check that catches it, independently of the Integrated Loudness delta.

To also hold the DUT to a fixed delivery ceiling such as −1.0dBTP (the EBU R128 convention), set loudness.true_peak_ceiling_dbtp via --config or the defaults file. It is off unless set, and when set it applies in addition to the comparison with the reference. Loudness doesn't gate the overall verdict by default (see the question above); add --loudness to make a True Peak or loudness failure count.

Can I compare more than one DUT to a reference in one command?

Not in a single invocation — wavelens analyze always compares exactly one reference to exactly one DUT. Loop over your DUT files from a script instead; see Examples.

My files are 5.1 surround. Can wavelens compare them directly?

No — wavelens only ever takes mono or stereo input. Split wider layouts into stereo/mono pairs first with the free wavchan tool's wavchan split command, then run wavelens analyze once per pair.

Do I need --json to get the raw numbers?

No — every HTML report already embeds the full raw results. --json is only for when you want that same data as a separate file, e.g. for your own scripts to parse.

What's the difference between analyze and plot?

analyze compares two files and produces a verdict. plot just visualizes one file — no comparison, no pass/fail, useful when you want to look at a signal's spectrum and waveform without a reference to check it against.