Files
VCCPlusDiagnostics/examples/sound-lab/audio/analyze.py
T

274 lines
13 KiB
Python

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