Files
VCCPlusDiagnostics/examples/sound-lab/audio/README.md
T

5.5 KiB

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.