WaveLens Docs
wavelens.dev GitHub
Docs / Quick start
Quick start

Your first comparison

Two audio files in, one report out. About five minutes, with nothing to install.

Covers wavelens · Windows, macOS and Linux
How a WaveLens run works Your original file goes through your own audio processing and comes out as the processed file. Both files go into wavelens analyze, which aligns them, runs six checks, and writes one HTML report. Reference original.wav what goes in Your pipeline Audio processing codec, effect, device or algorithm Device under test audio-processed.wav what comes out wavelens analyze Align Finds any delay between the two files Run six checks Bit-Exactness · Level Fidelity · Artifact Detection Spectral Fidelity · Distortion · Loudness report.html One PASS or FAIL, one card per check
You supply the two files. WaveLens lines them up, runs the checks and writes the report. Dashed means your own pipeline, outside WaveLens.

Before you start

The downloadUnzip it anywhere. It holds a folder for each system (windows, macos, linux), each with the tools and your license file, wavelens.lic.
Two WAV filesA reference, and the same audio after your processing: the device under test (DUT).
File formatMono or stereo with the same channel count in both, 16/24/32-bit integer or 32/64-bit float, 22,050 to 192,000 Hz.

Open a terminal in the folder for your system

Open a terminal in the windows, macos or linux folder you unzipped: Command Prompt or PowerShell on Windows, Terminal on macOS and Linux. On macOS and Linux put ./ in front of each command (./wavelens), and in PowerShell .\ (.\wavelens). The tools look for wavelens.lic next to themselves, so there is nothing to configure. These beta builds aren't signed yet, so Windows and macOS may warn the first time you run them; the download page shows what to do. Check it:

wavelens license info
You should seeYour license details, ending with License Status: ACTIVE. If you see an error instead, see If something goes wrong.

Compare your files

The reference is what went into your processing and the DUT is what came out:

wavelens analyze --ref original.wav --dut audio-processed.wav --out report.html
You should seeA new file, report.html, in the same folder. Open it in any browser.

WaveLens lines the two files up first, so a delay of up to 0.1 second between them is found and accounted for automatically. Files that start with a sync tone, or that have a longer lead-in, need wavelens trim first.

Read the report

The report is one HTML file that works offline. The Overall Verdict sits at the top, with one card per check below it and tabs to jump between them. A run that passes everything looks like this:

A simplified illustration. Open a real report to explore the charts.

  • One failing check that counts makes the whole run FAIL. Open that check's card to see what was measured and where.
  • Two things look odd at first, and both are intended. Bit-Exactness can show a failure while the overall verdict still passes, because a lossy pipeline is never identical to its source (add --bitexact to require it). Loudness is shown for reference and doesn't change the verdict unless you add --loudness.

Different kinds of content

Most runs need nothing beyond the command in step 2. Add a flag only when the content calls for it:

You are testingAddWhy
A frequency sweep, and only a sweep--freqsweepChecks the whole file instead of one moment of it. Leave it off for music, speech and tones.
An amplitude sweep--ampsweepThe same, for a level sweep.
Music or speech--snapshots 5Takes five independent spectral looks spread across the file. Through a lossy codec, see the note below.
Multitone or noise--no-distortionTHD+N means nothing without a single dominant tone.
A claim of "lossless"--bitexactMakes a Bit-Exactness failure fail the verdict.
5.1 or 7.1 contentwavchan splitSplit it into stereo or mono pairs with the free wavchan tool, then run wavelens once per pair.
!

Lossy codecs. On test signals (tones, sweeps, multitones) the verdicts fall in a sensible order: a high bitrate passes, a low bitrate fails, and a sweep shows where a codec cuts off the top of the spectrum. On music or speech through a lossy codec, expect a FAIL even from a codec that sounds transparent, such as 320 kbps AAC or MP3. A perceptual codec keeps the sound, not the exact waveform, and WaveLens compares waveforms: Level Fidelity and Distortion sample by sample, Spectral Fidelity bin by bin. To check a codec on real content, compare each new build’s decoded output against the output of a build you trust (a golden output); the Examples show how.

If something goes wrong

MessageWhat to do
error: license INVALID -- no license found at '...'Keep wavelens.lic in the same folder as the tool, or run wavelens license info to see where it looked.
error: failed to read --ref/--dut '...' (not a supported ... WAV file)Check the file is 16/24/32-bit integer or 32/64-bit float WAV. Compressed files such as MP3 or AAC must be decoded to WAV first.
error: ... sample rate ... is outside the supported rangeFiles must be between 22,050 and 192,000 Hz.
error: alignment failed -- ...The message says what was found. No consistent match: the two files may not contain the same audio, or the DUT is heavily degraded, so check you gave the right pair. Polarity-inverted: flip that channel. Outside the search window: the DUT starts later or earlier than the search covers; follow the message to widen it, or run wavelens trim on a file with a long lead-in or a sync tone. The start lines up but the end does not: samples were skipped or the clocks differ.

The full list is under Errors & troubleshooting in the wavelens guide.

Where next