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,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())
|
||||
Reference in new issue
Block a user