Optional audio measurements
analyze.py measures a pre-existing uncompressed integer PCM WAV with Python
3.9 or later and no extra packages. It does not capture audio, operate an emulator,
change a cartridge, or identify hardware. Keep the raw WAV and its interval
manifest as evidence; the report includes SHA-256 digests of both inputs.
python3 examples/sound-lab/audio/analyze.py capture.wav intervals.json --output measurements.json
Reports go to standard output when --output is absent. Existing report files
are protected; --overwrite explicitly replaces a report, but cannot replace
either input. No command modifies the WAV or manifest. These potentially large
and private recordings belong outside Git.
Capture and interval preparation
Use an external line-level recorder or the platform's audio export. Ideally record uncompressed 48 kHz, 16-bit PCM, with a fixed gain and without AGC, noise suppression, equalization or other processing. Record lead-in and trailing silence. Record the connection path (real analog, emulator export, HDMI or other), gain, cartridge/configuration and any resampling in your own capture notes. WAV header values describe the file; they do not calibrate a real capture clock.
Use displayed/counted markers or an optional marker sound outside measured windows to locate each case. Enter actual offsets into the manifest after reviewing the recording. Guest counters and marker ticks do not necessarily coincide with audio sample boundaries. This analyzer does not infer markers or align recordings automatically.
{
"capture_context": {
"source": "real analog — user reported, not verified",
"gain_notes": "fixed recorder gain; no AGC",
"marker_notes": "start measured manually after the count-in"
},
"segments": [
{
"case_id": "TONE-EXAMPLE",
"vector_id": "exact-vector-identity-from-run",
"kind": "tone",
"start_seconds": 1.25,
"end_seconds": 3.25,
"nominal_hz": 440.0
}
]
}
A top-level array of segment objects is also accepted. Each segment requires a
nonempty case_id, explicit finite start_seconds and end_seconds, and a
kind of tone, noise, speech or silence. Overlapping windows are allowed
for deliberate analysis of the same samples. Windows must be within the file
and contain at least one sample. Samples with timestamps start <= n/rate < end
are included. Reports retain requested offsets, zero-based start/exclusive stop
frames, PCM payload byte offsets and actual sample-window duration. Byte offsets
refer to decoded PCM payload, not offsets into the WAV container.
vector_id is optional for individual measurements, but required for repeated
case comparison. Use the exact vector identity or CRC from the guest run. Only
matching case_id, vector_id and kind are compared; matching labels are
user assertions, not independently proven guest provenance.
Meaning and limits
The analyzer supports WAVE_FORMAT_PCM with 8-bit unsigned and 16/24/32-bit signed
integer PCM. It rejects compressed, floating-point or extensible-format WAV,
truncated payloads and unsupported sample widths. Convert unsupported containers
explicitly and preserve both the original and conversion notes. Channels are
measured independently without mixing or resampling.
RMS, AC RMS, peak and DC offset are normalized to signed full scale. The
clipping_count counts exact positive/negative PCM rails; reaching a rail is
evidence to inspect, not proof of a defective device. near_zero_ratio counts
samples within one LSB of digital zero; it is not a perceptual silence threshold.
For tone only, a frequency estimate uses linearly interpolated upward zero
crossings after removing the window's mean DC offset. At least three crossings
are required. The report includes crossing-period variation. This is appropriate
for an isolated pure tone: harmonics, noise, clipping, modulation and transients
can create extra crossings or bias the fundamental. Review the signal and window
before interpreting an estimate. No frequency estimate is made for noise or
speech, and silence cannot establish an output-stage fault.
The default assessment is MEASURE_BASELINE with observations OBSERVED and
human listening NOT_OBSERVED. No measured value establishes HEARD, general
success, analog waveform equality, real hardware identity or accurate clocks.
Repeated-case reports give differences, without an automatic pass/fail judgment.
Keep human listening results separate in the diagnostic run report.
If a qualified frequency tolerance has independently been established, a tone
segment with nominal_hz may additionally specify:
"frequency_tolerance": {
"absolute_hz": 2.0,
"qualification": "Example only: replace with the documented hardware/clock basis and reference"
}
This enables a measurement-only WITHIN_QUALIFIED_TOLERANCE or
OUTSIDE_QUALIFIED_TOLERANCE assessment on that channel when frequency can be
estimated. It does not certify the supplied justification or convert an
observation into a listening or compatibility pass. The report as a whole remains
MEASURE_BASELINE. Do not invent tolerances from an arbitrary passing run.
Portable checks
From the repository root:
python3 -m unittest discover -s examples/sound-lab/tests -p test_audio.py -v
Tests author their own temporary WAVs, including tones at both 44.1 and 48 kHz, silence, integer rails, different stereo channels and malformed inputs. They verify measurements and input preservation, not audible quality or hardware.