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.
+273
View File
@@ -0,0 +1,273 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-or-later
"""Measure explicitly identified Sound Lab intervals; never infer listening success."""
import argparse
import hashlib
import io
import json
import math
from pathlib import Path
import statistics
import sys
import wave
KINDS = {"tone", "noise", "speech", "silence"}
def finite_number(value, label):
if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
raise ValueError(label + " must be a finite number")
return float(value)
def sha256(data):
return hashlib.sha256(data).hexdigest()
def load_pcm(path):
"""Return integer samples and the capture's declared format, without resampling."""
raw = Path(path).read_bytes()
# New Python versions also accept IEEE float through wave. Enforce the same
# integer-only, portable WAVE_FORMAT_PCM contract on every supported Python.
if len(raw) < 12 or raw[:4] != b"RIFF" or raw[8:12] != b"WAVE":
raise ValueError("expected a little-endian RIFF/WAVE file")
offset = 12
format_tag = None
while offset + 8 <= len(raw):
size = int.from_bytes(raw[offset + 4:offset + 8], "little")
if raw[offset:offset + 4] == b"fmt ":
if size < 16 or offset + 8 + size > len(raw):
raise ValueError("invalid WAV format chunk")
format_tag = int.from_bytes(raw[offset + 8:offset + 10], "little")
break
offset += 8 + size + (size % 2)
if format_tag != 1:
raise ValueError("only WAVE_FORMAT_PCM integer WAV is supported; convert compressed, float or extensible WAV explicitly")
try:
with wave.open(io.BytesIO(raw), "rb") as source:
if source.getcomptype() != "NONE":
raise ValueError("only uncompressed integer PCM WAV is supported")
width = source.getsampwidth()
channels = source.getnchannels()
rate = source.getframerate()
frames = source.getnframes()
if width not in (1, 2, 3, 4):
raise ValueError("supported PCM widths are 8, 16, 24 and 32 bits")
if rate <= 0 or channels <= 0 or frames <= 0:
raise ValueError("WAV must contain samples at a positive rate")
payload = source.readframes(frames)
except (wave.Error, EOFError) as error:
raise ValueError("unsupported or invalid PCM WAV: " + str(error)) from error
if len(payload) != frames * channels * width:
raise ValueError("truncated WAV sample data")
samples = [[] for _ in range(channels)]
for index in range(0, len(payload), width):
value = int.from_bytes(payload[index:index + width], "little", signed=width != 1)
if width == 1:
value -= 128
samples[(index // width) % channels].append(value)
return samples, {
"filename": Path(path).name, "sha256": sha256(raw), "byte_count": len(raw),
"sample_rate_hz": rate, "channels": channels, "bit_depth": width * 8,
"frame_count": frames, "duration_seconds": frames / rate,
"format": "uncompressed integer PCM", "sample_rate_source": "WAV header; not clock calibration",
}
def validate_manifest(document, info):
if isinstance(document, list):
segments = document
elif isinstance(document, dict):
segments = document.get("segments")
else:
segments = None
if not isinstance(segments, list) or not segments:
raise ValueError("manifest must contain a nonempty segments list")
checked = []
for index, segment in enumerate(segments):
label = "segment " + str(index)
if not isinstance(segment, dict):
raise ValueError(label + " must be an object")
case_id = segment.get("case_id")
if not isinstance(case_id, str) or not case_id.strip():
raise ValueError(label + " needs a nonempty case_id")
if segment.get("kind") not in KINDS:
raise ValueError(label + " has unsupported kind")
start = finite_number(segment.get("start_seconds"), label + " start_seconds")
end = finite_number(segment.get("end_seconds"), label + " end_seconds")
if start < 0 or end <= start or end > info["duration_seconds"]:
raise ValueError(label + " interval must satisfy 0 <= start < end <= WAV duration")
# Samples at timestamps start <= n/rate < end; no implied counter alignment.
first = math.ceil(start * info["sample_rate_hz"])
stop = min(info["frame_count"], math.ceil(end * info["sample_rate_hz"]))
if stop <= first:
raise ValueError(label + " interval contains no sample timestamps")
item = dict(segment)
item.update(start_seconds=start, end_seconds=end, start_frame=first, stop_frame=stop)
vector_id = item.get("vector_id")
if vector_id is not None and (not isinstance(vector_id, str) or not vector_id.strip()):
raise ValueError(label + " vector_id must be a nonempty string when supplied")
if "nominal_hz" in item:
nominal = finite_number(item["nominal_hz"], label + " nominal_hz")
if item["kind"] != "tone" or not 0 < nominal < info["sample_rate_hz"] / 2:
raise ValueError(label + " nominal_hz needs a tone below the Nyquist frequency")
item["nominal_hz"] = nominal
tolerance = item.get("frequency_tolerance")
if tolerance is not None:
if not isinstance(tolerance, dict) or "nominal_hz" not in item:
raise ValueError(label + " frequency_tolerance needs nominal_hz")
limit = finite_number(tolerance.get("absolute_hz"), label + " absolute_hz")
qualification = tolerance.get("qualification")
if limit < 0 or not isinstance(qualification, str) or not qualification.strip():
raise ValueError(label + " tolerance needs a nonnegative absolute_hz and qualification")
checked.append(item)
return checked
def tone_estimate(values, rate):
"""Interpolated upward crossings after DC removal, meaningful only for pure tones."""
mean = statistics.fmean(values)
crossings = []
for index in range(1, len(values)):
before, after = values[index - 1] - mean, values[index] - mean
if before < 0 <= after:
crossings.append(index - 1 + (-before / (after - before)))
result = {
"technique": "DC-removed linearly interpolated upward zero crossings",
"limitations": "Pure-tone estimate only. Harmonics, noise, clipping and transients can add crossings or bias the fundamental. No clock calibration is inferred.",
"upward_crossing_count": len(crossings), "estimated_hz": None,
}
if len(crossings) < 3:
result["availability"] = "INSUFFICIENT_CROSSINGS"
return result
periods = [b - a for a, b in zip(crossings, crossings[1:])]
mean_period = statistics.fmean(periods)
result.update(
availability="OBSERVED", estimated_hz=rate / mean_period,
crossing_period_variation_ratio=statistics.pstdev(periods) / mean_period,
measured_span_seconds=(crossings[-1] - crossings[0]) / rate,
)
return result
def channel_metrics(values, bits, rate, segment):
full_scale = 2 ** (bits - 1)
count = len(values)
dc = statistics.fmean(values)
result = {
"rms_full_scale": math.sqrt(sum(value * value for value in values) / count) / full_scale,
"ac_rms_full_scale": math.sqrt(sum((value - dc) ** 2 for value in values) / count) / full_scale,
"peak_full_scale": max(abs(value) for value in values) / full_scale,
"dc_offset_full_scale": dc / full_scale,
"clipping_count": sum(value in (-full_scale, full_scale - 1) for value in values),
"near_zero_ratio": sum(abs(value) <= 1 for value in values) / count,
"near_zero_definition": "absolute signed PCM value <= 1 LSB; a measurement, not an audibility threshold",
"assessment": "MEASURE_BASELINE",
}
if segment["kind"] == "tone":
estimate = tone_estimate(values, rate)
result["frequency"] = estimate
if "nominal_hz" in segment and estimate["estimated_hz"] is not None:
delta = estimate["estimated_hz"] - segment["nominal_hz"]
estimate["nominal_hz"] = segment["nominal_hz"]
estimate["difference_hz"] = delta
tolerance = segment.get("frequency_tolerance")
if tolerance:
estimate["qualified_tolerance"] = tolerance
result["assessment"] = ("WITHIN_QUALIFIED_TOLERANCE" if abs(delta) <= tolerance["absolute_hz"]
else "OUTSIDE_QUALIFIED_TOLERANCE")
return result
def repeated_cases(segments):
groups = {}
for index, segment in enumerate(segments):
if segment.get("vector_id"):
groups.setdefault((segment["case_id"], segment["vector_id"]), []).append(index)
comparisons = []
for (case_id, vector_id), indexes in groups.items():
if len(indexes) < 2:
continue
reference = segments[indexes[0]]
for index in indexes[1:]:
current = segments[index]
if current["kind"] != reference["kind"]:
continue
channels = []
for base, observed in zip(reference["channels"], current["channels"]):
delta = {key + "_difference": observed[key] - base[key]
for key in ("rms_full_scale", "peak_full_scale", "dc_offset_full_scale")}
a = base.get("frequency", {}).get("estimated_hz")
b = observed.get("frequency", {}).get("estimated_hz")
if a is not None and b is not None:
delta["estimated_hz_difference"] = b - a
channels.append(delta)
comparisons.append({
"case_id": case_id, "vector_id": vector_id,
"reference_segment_index": indexes[0], "observed_segment_index": index,
"duration_difference_seconds": current["sample_duration_seconds"] - reference["sample_duration_seconds"],
"channels": channels, "assessment": "OBSERVED",
})
return comparisons
def analyze(wav_path, manifest_path):
samples, info = load_pcm(wav_path)
manifest_bytes = Path(manifest_path).read_bytes()
try:
document = json.loads(manifest_bytes)
except (ValueError, UnicodeDecodeError) as error:
raise ValueError("invalid JSON manifest: " + str(error)) from error
segments = validate_manifest(document, info)
measurements = []
for segment in segments:
first, stop = segment["start_frame"], segment["stop_frame"]
item = dict(segment)
item.update(
sample_count_per_channel=stop - first,
first_sample_seconds=first / info["sample_rate_hz"],
exclusive_stop_seconds=stop / info["sample_rate_hz"],
sample_duration_seconds=(stop - first) / info["sample_rate_hz"],
byte_offset_in_pcm_payload=first * info["channels"] * (info["bit_depth"] // 8),
observation_status="OBSERVED", human_status="NOT_OBSERVED",
channels=[channel_metrics(values[first:stop], info["bit_depth"], info["sample_rate_hz"], segment)
for values in samples],
)
measurements.append(item)
return {
"schema_version": 1, "capture": info,
"manifest": {"filename": Path(manifest_path).name, "sha256": sha256(manifest_bytes)},
"reported_capture_context": document.get("capture_context", {}) if isinstance(document, dict) else {},
"assessment": "MEASURE_BASELINE", "human_status": "NOT_OBSERVED",
"interval_convention": "[start_seconds,end_seconds); include sample timestamps n/rate in that interval; frames are zero based",
"limitations": "Measurements do not establish listening success, hardware identity, calibrated clock accuracy, analog equality or cross-target compatibility. Capture context is supplied by the user, not verified.",
"segments": measurements, "repeated_cases": repeated_cases(measurements),
}
def main(argv=None):
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("wav", type=Path)
parser.add_argument("manifest", type=Path)
parser.add_argument("--output", type=Path, help="JSON output; stdout if omitted; existing files protected")
parser.add_argument("--overwrite", action="store_true", help="explicitly replace an existing report (never an input)")
args = parser.parse_args(argv)
try:
if args.output and args.output.resolve() in (args.wav.resolve(), args.manifest.resolve()):
raise ValueError("report output cannot replace either input")
report = analyze(args.wav, args.manifest)
serialized = json.dumps(report, indent=2, allow_nan=False) + "\n"
if args.output:
with args.output.open("w" if args.overwrite else "x", encoding="utf-8") as output:
output.write(serialized)
else:
sys.stdout.write(serialized)
except (ValueError, OSError) as error:
parser.exit(2, "error: " + str(error) + "\n")
return 0
if __name__ == "__main__":
sys.exit(main())