#!/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())