119 lines
5.5 KiB
Markdown
119 lines
5.5 KiB
Markdown
# 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.
|
|
|
|
```sh
|
|
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.
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
"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:
|
|
|
|
```sh
|
|
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.
|