SCRYMAMEReferenceFilesaudio_compareAlso in DOSBox-X

MAMEFiles

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 the WAV the Gridlee example of audio_record wrote. No machine is running.
Ask

Did card.wav record any sound? Measure it.

Call
audio_compare(method="measure", path="./tmp/demos/tour/card.wav")
Reply 6 of 9 fields
{
  "summary": "audio_compare measure: ch0 silent",
  "sample_rate_hz": 48000,
  "channels": 1,
  "bits": 16,
  "window": [0.0, 0.5],
  "pcm_sha256": "bb918147fe10391b43adeba4bd21b9ef32e5bd6c5076c3517733a05ed6dd0569"
}

The summary's ch0 is the first and only one of the file's channels, and it is silent over its half second. Gridlee's sound samples are not in the free set, hence the silence.

The whole reply
JSON
{
  "summary": "audio_compare measure: ch0 silent",
  "status": "ok",
  "sample_rate_hz": 48000,
  "channels": 1,
  "bits": 16,
  "window": [0.0, 0.5],
  "measures": [
    {
      "channel": 0,
      "peak_dbfs": {"available": false, "why": "a level of zero has no value in dB"},
      "rms_dbfs": {"available": false, "why": "a level of zero has no value in dB"},
      "silent": true,
      "silence_spans": {"count": 1, "first": [0.0, 0.5]},
      "onset_s": {"available": false, "why": "a silent window has no onset"},
      "clipping_run": 0,
      "clipped": false
    }
  ],
  "pcm_sha256": "bb918147fe10391b43adeba4bd21b9ef32e5bd6c5076c3517733a05ed6dd0569",
  "path": "./tmp/demos/tour/card.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