SCRYDOSBox-XReferenceFilesaudio_compareAlso in MAME

DOSBox-XFiles

audio_compare

Measure a WAV recording, or compare two, and get loudness, silence, timing and closeness as numbers.

audio_compare(method, path="", a="", b="", window=null, channel=null, align=null)

Try it

On Minesweeper, a game this repository builds, after the audio_record example recorded its explosion. b is the reference recording the demo keeps.
Ask

Is the explosion I recorded the same as the reference boom.wav, sample for sample?

Call
audio_compare(method="diff", a="./tmp/demos/mines/boom.wav", b="./demos/mines/boom.wav",
    align=false)
Reply 5 of 11 fields
{
  "summary": "audio_compare diff: exact, equal, envelope 1.0",
  "exact": true,
  "snr_db": {
    "available": false,
    "why": "the two are equal after alignment: there is no error to measure the signal against"
  },
  "class": "exact",
  "aligned_by_samples": 0
}

exact is true: the two files hold the same samples, compared from their first sample. With nothing differing there is no ratio to give, so snr_db is unavailable.

The whole reply
JSON
{
  "summary": "audio_compare diff: exact, equal, envelope 1.0",
  "status": "ok",
  "exact": true,
  "snr_db": {
    "available": false,
    "why": "the two are equal after alignment: there is no error to measure the signal against"
  },
  "class": "exact",
  "envelope_correlation": 1.0,
  "onset_delta_ms": 0.0,
  "length_delta_samples": 0,
  "aligned_by_samples": 0,
  "a": "<volatile>",
  "b": "./demos/mines/boom.wav"
}

The two methods

method what it answers
measure One recording: how loud it is, whether it is silent, when the sound begins and whether it clips.
diff Two recordings: whether they are equal and, if not, how close they are.

Arguments

method one of "measure", "diff", required
measure or diff, as above.
path string, default ""
For measure: the WAV to measure, 8- or 16-bit PCM. An absolute path, or one starting with ~.
a string, default ""
For diff: the recording under test.
b string, default ""
For diff: the reference recording, of the same sample rate, channels and bit depth as a.
window array of number, optional
The part of the recording to read, [from_s, to_s] in seconds. Left out, the whole file.
channel integer, optional
For measure: which of the file's channels to measure, numbered from 0. Left out, each of them.
align boolean, optional
For diff: true lines up where the two sounds begin before comparing them; false compares from the first sample. Left out, true.

What comes back

measures
For measure: one row for each of the channels, with channel, peak_dbfs, rms_dbfs, silent, silence_spans (its count and first), onset_s, clipping_run and clipped.
pcm_sha256
For measure: the SHA-256 of the samples in the window, equal for two files that hold the same sound.
exact
For diff: true when the two windows hold the same bytes.
class
For diff, the verdict in one word: exact, inaudible, audible or different.
snr_db
For diff: the signal-to-noise ratio of a against b, the worst of the channels. Unavailable when the two are equal once lined up.
aligned_by_samples
For diff: how many samples a was moved to line up with b.
All 16 reply fields
  • a (string)
  • b (string)
  • aligned_by_samples (integer)
  • bits (integer)
  • channels (integer)
  • envelope_correlation (number)
  • exact (boolean)
  • length_delta_samples (integer)
  • measures (array)
  • onset_delta_ms (number)
  • path (string)
  • pcm_sha256 (string)
  • sample_rate_hz (integer)
  • snr_db (number or object)
  • window (array)
  • class (string)

What it refuses

Why it works this way

The sound itself never comes back, only numbers, so a client that cannot listen checks a recording through them.

Each of the channels is measured and compared on its own, never mixed down first. Mixed, one in antiphase would cancel, and two swapped ones would average to the same sound.

diff lines up the two sounds unless align is false, so a recording that starts a few samples later is not called different. With align false, two recordings made from the same stop are compared sample for sample.

More on why
  • A steady level that is not zero is no sound: loudness, silence and the comparison read the window less its mean.
  • Two recordings whose lengths are more than a tenth of a second apart are different.
  • The reply repeats path, a, b and the window it read.
The contract your client receives
Text
Measure a WAV or compare two, in numbers. 8- or 16-bit PCM; `window` [from_s, to_s],
seconds, default the whole file.

`measure`: `path`, every channel or `channel` (0 the first). Reply: `measures`, per channel
`channel`, `peak_dbfs`, `rms_dbfs`, `silent` (RMS under 0.5% of full scale),
`silence_spans` (under -60 dBFS for 50 ms or more), `onset_s` (over 2% of the peak),
`clipping_run` (flat at 95% of the peak or above), `clipped` (a run past 8); then
`sample_rate_hz`, `channels`, `bits`, `pcm_sha256`.

`diff`: `a` against the reference `b`, of one format; `align` (default true) meets the
onsets, then the waveforms; false compares from the starts. Reply: `exact`, `snr_db`,
`class` (`exact`; `inaudible` 60 dB or more; `audible` 30 to 60; `different`),
`envelope_correlation` (64-window envelopes), `onset_delta_ms`, `length_delta_samples`,
`aligned_by_samples`.

Refused: an argument the method does not take; `control_silent` when both are silent.

Reads files only: it needs no machine and alters nothing. Every path is absolute or starts with `~`.

Reference: REFERENCE.md, Media files.
Tools