Publish the reproducible Sound Lab and FPGA Colour Lab sources

This commit is contained in:
bholman committed 2026-11-18 12:28:31 -07:00
commit 88254d7e24
27 files changed
+4574

No files matched your search

+118
View File
@@ -0,0 +1,118 @@
# 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.