SCRYMAMEReferenceFilesaudio_compareAlso in DOSBox-X
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
audio_record wrote. No machine is running.Did card.wav record any sound? Measure it.
audio_compare(method="measure", path="./tmp/demos/tour/card.wav"){
"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
{
"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 measureordiff, 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,channelsand bit depth asa. - 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'schannelsto measure, numbered from 0. Left out, each of them. - align boolean, optional
- For
diff:truelines up where the two sounds begin before comparing them;falsecompares from the first sample. Left out,true.
What comes back
- measures
- For
measure: one row for each of thechannels, withchannel,peak_dbfs,rms_dbfs,silent,silence_spans(itscountandfirst),onset_s,clipping_runandclipped. - 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:truewhen the two windows hold the same bytes. - class
- For
diff, the verdict in one word:exact,inaudible,audibleordifferent. - snr_db
- For
diff: the signal-to-noise ratio ofaagainstb, the worst of thechannels. Unavailable when the two are equal once lined up. - aligned_by_samples
- For
diff: how many samplesawas moved to line up withb.
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
- An argument the method does not take (
bad_argument). - A file that is not 8- or 16-bit PCM, holds no sample or cannot be read (
bad_argument). - A
windowoutside the recording, or achannelnumber the file does not have (bad_argument). - For
diff, two recordings that differ in sample rate,channelsor bit depth (bad_argument). - For
diff, two recordings that are both silent over the window (control_silent).
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,band thewindowit read.
Related tools
The contract your client receives
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.