Publish the reproducible Sound Lab and FPGA Colour Lab sources
This commit is contained in:
commit
88254d7e24
27 files changed
+4574
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user