goesb-runner 0.0.1__py3-none-any.whl

goesb_runner-0.0.1.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: goesb-runner
+Version: 0.0.1
+Summary: Official Open Edge Speech Benchmark (GOESB) runner
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: packaging>=23.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff~=0.16.0; extra == 'dev'
+Provides-Extra: faster-whisper
+Requires-Dist: faster-whisper>=1.0.0; extra == 'faster-whisper'
+Provides-Extra: vosk
+Requires-Dist: soundfile>=0.12; extra == 'vosk'
+Requires-Dist: vosk>=0.3.44; extra == 'vosk'
+Provides-Extra: whisper-cpp
+Requires-Dist: pywhispercpp>=1.5.0; extra == 'whisper-cpp'
+Requires-Dist: soundfile>=0.12; extra == 'whisper-cpp'
+Description-Content-Type: text/markdown
+
+# GOESB Runner
+
+The official, reproducible benchmark runner. It loads a signed **Benchmark
+Profile** and **Benchmark Pack**, captures the full hardware/software/model
+environment, runs the benchmark (batch / streaming / conversation) against a
+pluggable **runtime adapter**, computes metrics, and emits a signed,
+hash-verifiable result.
+
+The runner **never executes arbitrary user code** (see the security model).
+
+## Quick start
+```bash
+pip install -e ".[dev,faster-whisper]"
+goesb --help
+goesb env          # print captured environment fingerprint
+goesb validate profiles/whisper-medium-en-batch/profile.yaml
+goesb validate packs/example-librispeech-en-batch/pack.yaml
+
+# Fetch the example pack's audio (not committed to git — FR-3.5) before
+# running against it. Reruns are safe with --skip-download.
+python ../scripts/fetch_librispeech_subset.py
+
+# Run a batch benchmark end-to-end: environment capture, transcription,
+# normalization + WER/CER/RTF/CPU/RAM, a signed+hashed result on disk.
+goesb run whisper-medium-en-batch example-librispeech-en-batch --repeats 2
+```
+
+Pass `--model-override tiny` (or `base`) to `goesb run` for a fast local smoke
+test instead of downloading the full `whisper-medium` the profile specifies —
+results from an override are for pipeline verification only, never comparable
+to the official profile's numbers.
+
+Schema validation currently requires running from within this monorepo
+checkout (see `oesb_runner.schema_validation`); standalone packaging of the
+schemas is tracked for M2.

goesb_runner-0.0.1.dist-info/RECORD

@@ -0,0 +1,39 @@
+oesb_runner/__init__.py,sha256=8YtgbYrqEBNLgm98giT9VQITTwsHQuQpO18K09n1AE0,50
+oesb_runner/audio.py,sha256=AXY7QIsMnu_waa13vVEv1OTfkKTuxjXjVYvBfREoMBI,4704
+oesb_runner/cli.py,sha256=cncvIJdDxpd3pZTVk5HjXwJbzuQp2Cf_LvWyVQ4d_Vc,24285
+oesb_runner/energy.py,sha256=m0dImAJlmAhpUwAIs011NlENM-nRe9zTcKhyJkkAfos,3099
+oesb_runner/environment.py,sha256=yDAqmSy_8ZMdKdscFMHTIVaGwgSstt-NnYkAqHotqZ0,5034
+oesb_runner/hashing.py,sha256=BgJtmoQBW0hlLzD-9JVIIhOf0XkcbP7Mis0sH-hs4Jo,2816
+oesb_runner/pack.py,sha256=icBzcpW7mEt36L-5pPESPrZGX8HclbXWzHiPaQr63Xs,3346
+oesb_runner/remote.py,sha256=X6J23DCzRq3sVMmK7hYtBApIzicGsBX6_9ySSWINVMQ,3088
+oesb_runner/schema_validation.py,sha256=w_feJGvU1PKiCBwnTUNFlLu1UN1gymQfjRninmWr2uc,984
+oesb_runner/signing.py,sha256=nylMPdQrZ9fJpIgD_anmBzM-4DsUJ-n-z9-hEA-LCvM,6971
+oesb_runner/stats.py,sha256=T58rk2YvpmUSasqng6Pa5PgwHQfDpPhx0cEHOYaL_8E,1319
+oesb_runner/streaming.py,sha256=D8MEJOr_ogm3ZOYyTFO-lhn_zP5OBJji2DLBuY2OIzA,1415
+oesb_runner/adapters/__init__.py,sha256=kKKYjtbF8ig0hlFAEEJfZuWnIfNEJU4O_O7y8P6_ZQ8,1803
+oesb_runner/adapters/faster_whisper.py,sha256=6Vx6GuQT5PlS2xDbvd7xlPr_mQKZN-wmExWpMdQ6Ol0,6239
+oesb_runner/adapters/vosk.py,sha256=VbrVAA4d0ZyAfwjzjaEZW2NTwWco1hp5v1Hfu129BF8,3500
+oesb_runner/adapters/whisper_cpp.py,sha256=kTSUgNOtImyZhAUiAlcFVy7x6h6Kj55M5IkdikOxBH0,2938
+oesb_runner/metrics/_align.py,sha256=cKdc5G3SsdBwQOMTz5XoXAdGAkNt13CZtJgREjy0NKg,795
+oesb_runner/metrics/cer.py,sha256=ISNxKxeNQ9ugfVHlJheEYESbd6Y0y4mylfV3n-dvLHM,766
+oesb_runner/metrics/cpu_ram.py,sha256=M5Vihcsljk1O81HdtiZTdBDiJceaKZgxd3u0XT8wSfg,1402
+oesb_runner/metrics/end_of_speech_latency.py,sha256=zVod6z2cdWhesrUIPcxlQjS_MkxpFWCzg0wPj_DhHbg,732
+oesb_runner/metrics/energy.py,sha256=QudNMTtf0V7CzEVEabNuGIyIqh52ZyHdGy-QO_LYbPI,926
+oesb_runner/metrics/first_final_latency.py,sha256=B-bnc8kPa-VqFwmYZ6Vfgwx-GhW05JDrrH_NRhdELWA,925
+oesb_runner/metrics/first_partial_latency.py,sha256=Of85eh5a0BSb6NlFJs4Jdk8T_ceqOjSqLIks6xOfwYc,928
+oesb_runner/metrics/partial_stability.py,sha256=kX5sewPClAf_55XRxuzagSi1LOkBErjDMj_tVGKcMZ0,1349
+oesb_runner/metrics/rtf.py,sha256=xHp5WaqMsknlT1ts1gEEylrFeBefoBun-69e1SKn1Qo,447
+oesb_runner/metrics/streaming_responsiveness.py,sha256=PaoQnJPaNaGZYCbugx6JZeYlJN4ks79bGBcZ6x_DOaQ,1010
+oesb_runner/metrics/temperature.py,sha256=uH466d_rwEwQINgfn2B3utRxw1MigSUctzsHz7OATXk,485
+oesb_runner/metrics/update_frequency.py,sha256=OQRB9NljQvIVkojUWJgWOVtzH0UA1WYVztRt2doEtRs,969
+oesb_runner/metrics/wer.py,sha256=uHEKGx4izcRjy7tJxkPm7TGGE00jwh6X2V1HmYaz5hI,1089
+oesb_runner/normalization/__init__.py,sha256=MKmhGu--FNPjZL6Ie3eQKYVkDdnqsgxV-kx2yIeDOCk,1346
+oesb_runner/normalization/oesb_en_v1.py,sha256=S8TLI5JkvmPF2tu5skKhtVcN-o1vRMwE8RYdTwu6ePQ,2353
+oesb_runner/normalization/oesb_nl_v1.py,sha256=eI-zfC4LKolM1edPRt-GoTbuuf8DC_tTYU4FCaKiuz0,2998
+oesb_runner/schemas/benchmark-pack.schema.json,sha256=4Gj2nJwmUKsF2gFNkXBgmFom2uW3NeeaDeQncu2UcqE,2881
+oesb_runner/schemas/benchmark-profile.schema.json,sha256=nrLv5mbDBpNRj75zM33wlhCeYSKPn_uqfSTH8Epw1LE,2888
+oesb_runner/schemas/benchmark-result.schema.json,sha256=S8mi0a0_SbQyYZnK1lUXIAL9FSE_6tsrQI8APfkJErg,6257
+goesb_runner-0.0.1.dist-info/METADATA,sha256=VdEK8RKxaEvCKHp_2ZJvZES4-DSj8vvGCKWWdiFhmUE,2410
+goesb_runner-0.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+goesb_runner-0.0.1.dist-info/entry_points.txt,sha256=ZBJ9wBZBWBbX8rPK7Q_th0fObz8MzZ0FYof_DK-05GQ,46
+goesb_runner-0.0.1.dist-info/RECORD,,

goesb_runner-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

goesb_runner-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+goesb = oesb_runner.cli:app

oesb_runner/__init__.py

@@ -0,0 +1,2 @@
+"""GOESB runner package."""
+__version__ = "0.0.1"

oesb_runner/adapters/__init__.py

@@ -0,0 +1,50 @@
+"""Runtime adapter registry (FR-11.1): how a model is driven for a benchmark
+type. Each adapter is reviewed, in-tree code (ADR-0004) — never a plugin
+supplied at run time. Core dispatch here is runtime-agnostic; adapter modules
+lazy-import their actual ML dependency so importing this package never
+requires it to be installed.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Transcription:
+    """One utterance's batch-adapter output — shared shape every batch
+    adapter (faster-whisper, vosk, whisper.cpp, ...) returns, so the CLI's
+    batch run loop stays adapter-agnostic."""
+    utterance_id: str
+    hypothesis_text: str
+    processing_time_s: float
+
+
+# Keyed by (runtime_name, benchmark_type) — a runtime can implement more than
+# one benchmark type (e.g. faster-whisper's "batch" and "streaming" loops are
+# different callables, same underlying runtime).
+_ADAPTERS: dict[tuple[str, str], Callable] = {}
+
+
+def register(runtime_name: str, benchmark_type: str = "batch") -> Callable[[Callable], Callable]:
+    def decorator(fn: Callable) -> Callable:
+        key = (runtime_name, benchmark_type)
+        if key in _ADAPTERS:
+            raise ValueError(f"runtime adapter already registered: {key!r}")
+        _ADAPTERS[key] = fn
+        return fn
+
+    return decorator
+
+
+def get_adapter(runtime_name: str, benchmark_type: str = "batch") -> Callable:
+    try:
+        return _ADAPTERS[(runtime_name, benchmark_type)]
+    except KeyError:
+        raise ValueError(
+            f"unknown runtime adapter: {runtime_name!r} for benchmark_type {benchmark_type!r}"
+        ) from None
+
+
+# Built-in adapters register themselves on import.
+from . import faster_whisper, vosk, whisper_cpp  # noqa: F401

oesb_runner/adapters/faster_whisper.py

@@ -0,0 +1,169 @@
+"""`faster-whisper` batch runtime adapter (docs/02-architecture.md §4).
+
+Optional dependency (`pip install goesb-runner[faster-whisper]`) — the actual
+`faster_whisper` package is only imported inside `run_batch`, so importing
+`oesb_runner.adapters` never requires it, matching the normalization plugin
+pattern.
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from ..pack import Utterance
+from ..streaming import PartialUpdate, StreamTrace
+from . import Transcription, register
+
+
+def _resolve_model_id(model_name: str) -> str:
+    """Translate GOESB's runtime-agnostic model name (profiles say
+    'whisper-medium') into the identifier faster-whisper's own API expects
+    ('medium') — this translation belongs in the adapter, not the profile,
+    so profiles stay independent of any one runtime's naming convention."""
+    prefix = "whisper-"
+    return model_name.removeprefix(prefix)
+
+
+@register("faster-whisper", benchmark_type="batch")
+def run_batch(
+    model_name: str,
+    utterances: list[Utterance],
+    *,
+    quantization: str = "int8",
+    beam_size: int = 5,
+    temperature: float = 0.0,
+    vad: bool = True,
+    threads: int = 4,
+    download_root: str | Path | None = None,
+) -> list[Transcription]:
+    """Transcribe every utterance once, batch-style, and time each call.
+
+    Model load time is deliberately excluded from per-utterance timing (it is
+    a one-off cost, not part of what RTF measures) but the loaded model is
+    reused across all utterances, matching how a real deployment would run.
+
+    `download_root`, when given, pins exactly where the model snapshot is
+    cached — the caller (the CLI) hashes that directory as `model.sha256`, so
+    it must actually be where the weights land, not faster-whisper's default
+    shared HF cache.
+    """
+    try:
+        from faster_whisper import WhisperModel
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise RuntimeError(
+            "faster-whisper is not installed; run "
+            "`pip install goesb-runner[faster-whisper]`"
+        ) from exc
+
+    model = WhisperModel(
+        _resolve_model_id(model_name),
+        compute_type=quantization,
+        cpu_threads=threads,
+        download_root=str(download_root) if download_root is not None else None,
+    )
+
+    results: list[Transcription] = []
+    for utterance in utterances:
+        start = time.perf_counter()
+        segments, _info = model.transcribe(
+            str(utterance.audio_path),
+            beam_size=beam_size,
+            temperature=temperature,
+            vad_filter=vad,
+        )
+        hypothesis_text = " ".join(segment.text.strip() for segment in segments).strip()
+        elapsed = time.perf_counter() - start
+        results.append(Transcription(
+            utterance_id=utterance.utterance_id,
+            hypothesis_text=hypothesis_text,
+            processing_time_s=elapsed,
+        ))
+    return results
+
+
+@register("faster-whisper", benchmark_type="streaming")
+def run_streaming(
+    model_name: str,
+    utterances: list[Utterance],
+    *,
+    chunk_ms: int = 1000,
+    quantization: str = "int8",
+    beam_size: int = 5,
+    temperature: float = 0.0,
+    vad: bool = True,
+    threads: int = 4,
+    download_root: str | Path | None = None,
+) -> list[StreamTrace]:
+    """Feed each utterance to faster-whisper in `chunk_ms` chunks, re-decoding
+    the growing buffer after every chunk (faster-whisper has no incremental
+    decoder state to resume, so "streaming" here means repeated whole-buffer
+    re-transcription — the same "local agreement" pattern used by e.g.
+    whisper_streaming). One `StreamTrace` per utterance records the resulting
+    hypothesis timeline for the streaming metric plugins to score.
+    """
+    try:
+        from faster_whisper import WhisperModel
+        from faster_whisper.audio import decode_audio
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise RuntimeError(
+            "faster-whisper is not installed; run "
+            "`pip install goesb-runner[faster-whisper]`"
+        ) from exc
+
+    sample_rate = 16000
+    chunk_samples = max(1, int(chunk_ms / 1000 * sample_rate))
+
+    model = WhisperModel(
+        _resolve_model_id(model_name),
+        compute_type=quantization,
+        cpu_threads=threads,
+        download_root=str(download_root) if download_root is not None else None,
+    )
+
+    traces: list[StreamTrace] = []
+    for utterance in utterances:
+        samples = decode_audio(str(utterance.audio_path), sampling_rate=sample_rate)
+        total_samples = len(samples)
+        audio_duration_s = total_samples / sample_rate
+
+        updates: list[PartialUpdate] = []
+        processing_time_s = 0.0
+        end = 0
+        while end < total_samples:
+            end = min(end + chunk_samples, total_samples)
+            is_last_chunk = end >= total_samples
+            chunk_end_s = end / sample_rate
+
+            start = time.perf_counter()
+            segments, _info = model.transcribe(
+                samples[:end],
+                beam_size=beam_size,
+                temperature=temperature,
+                vad_filter=vad,
+            )
+            segments = list(segments)
+            decode_wall_s = time.perf_counter() - start
+            processing_time_s += decode_wall_s
+
+            text = " ".join(segment.text.strip() for segment in segments).strip()
+            if is_last_chunk:
+                committed_word_count = len(text.split())
+            else:
+                committed_text = " ".join(s.text.strip() for s in segments[:-1]).strip()
+                committed_word_count = len(committed_text.split())
+
+            updates.append(PartialUpdate(
+                chunk_end_s=chunk_end_s,
+                emit_time_s=chunk_end_s + decode_wall_s,
+                text=text,
+                committed_word_count=committed_word_count,
+            ))
+
+        traces.append(StreamTrace(
+            utterance_id=utterance.utterance_id,
+            audio_duration_s=audio_duration_s,
+            processing_time_s=processing_time_s,
+            updates=updates,
+            final_text=updates[-1].text if updates else "",
+        ))
+    return traces

oesb_runner/adapters/vosk.py

@@ -0,0 +1,98 @@
+"""`vosk` batch runtime adapter (docs/02-architecture.md §4).
+
+Optional dependency (`pip install goesb-runner[vosk]`) — `vosk`/`soundfile`
+are only imported inside `run_batch`, matching the lazy-import pattern used
+by every other adapter.
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.request
+import zipfile
+from pathlib import Path
+
+from ..audio import decode_pcm
+from ..pack import Utterance
+from . import Transcription, register
+
+_MODEL_URLS = {
+    "vosk-model-small-en-us-0.15":
+        "https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip",
+}
+_SAMPLE_RATE = 16000
+
+
+def _resolve_model_dir(model_name: str, download_root: Path) -> Path:
+    """Download + unzip the pinned vosk model into `download_root` if not
+    already there. `vosk.Model(model_path=...)` needs an already-extracted
+    local directory — unlike faster-whisper's HF snapshot download, vosk has
+    no built-in fetch-by-pinned-version — so this does it explicitly: a
+    declarative fetch of a named, version-pinned asset, not arbitrary code
+    (ADR-0004)."""
+    model_dir = download_root / model_name
+    if model_dir.exists():
+        return model_dir
+    try:
+        url = _MODEL_URLS[model_name]
+    except KeyError:
+        raise ValueError(
+            f"unknown vosk model {model_name!r}; known models: {sorted(_MODEL_URLS)}"
+        ) from None
+
+    download_root.mkdir(parents=True, exist_ok=True)
+    zip_path = download_root / f"{model_name}.zip"
+    urllib.request.urlretrieve(url, zip_path)
+    with zipfile.ZipFile(zip_path) as zf:
+        zf.extractall(download_root)
+    zip_path.unlink()
+    return model_dir
+
+
+@register("vosk", benchmark_type="batch")
+def run_batch(
+    model_name: str,
+    utterances: list[Utterance],
+    *,
+    quantization: str = "int8",
+    beam_size: int = 5,
+    temperature: float = 0.0,
+    vad: bool = True,
+    threads: int = 4,
+    download_root: str | Path | None = None,
+) -> list[Transcription]:
+    """Transcribe every utterance once, batch-style, and time each call.
+
+    `quantization`/`beam_size`/`temperature`/`vad`/`threads` are accepted for
+    call-shape parity with the other batch adapters (docs/03-roadmap.md M2
+    exit criterion: adapters swap without core changes) but unused — vosk's
+    Kaldi decoder has no equivalent tunables exposed through its Python API.
+    """
+    try:
+        import vosk
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise RuntimeError(
+            "vosk is not installed; run `pip install goesb-runner[vosk]`"
+        ) from exc
+    vosk.SetLogLevel(-1)  # silence vosk's own stderr logging
+
+    root = Path(download_root) if download_root is not None else Path.home() / ".goesb" / "models" / model_name
+    model_dir = _resolve_model_dir(model_name, root)
+    model = vosk.Model(model_path=str(model_dir))
+
+    results: list[Transcription] = []
+    for utterance in utterances:
+        samples = decode_pcm(utterance.audio_path, dtype="int16")
+        recognizer = vosk.KaldiRecognizer(model, _SAMPLE_RATE)
+
+        start = time.perf_counter()
+        recognizer.AcceptWaveform(samples.tobytes())
+        hypothesis_text = json.loads(recognizer.FinalResult()).get("text", "")
+        elapsed = time.perf_counter() - start
+
+        results.append(Transcription(
+            utterance_id=utterance.utterance_id,
+            hypothesis_text=hypothesis_text,
+            processing_time_s=elapsed,
+        ))
+    return results

oesb_runner/adapters/whisper_cpp.py

@@ -0,0 +1,79 @@
+"""`whisper.cpp` (via `pywhispercpp`) batch runtime adapter
+(docs/02-architecture.md §4).
+
+Optional dependency (`pip install goesb-runner[whisper-cpp]`) —
+`pywhispercpp`/`soundfile` are only imported inside `run_batch`, matching the
+lazy-import pattern used by every other adapter.
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from ..audio import decode_pcm
+from ..pack import Utterance
+from . import Transcription, register
+
+
+def _resolve_model_id(model_name: str) -> str:
+    """Translate GOESB's runtime-agnostic model name ('whisper-base.en') into
+    the ggml model id pywhispercpp/whisper.cpp expects ('base.en') — same
+    translation role as faster_whisper._resolve_model_id; each adapter
+    carries its own runtime's naming convention rather than the profile."""
+    prefix = "whisper-"
+    return model_name.removeprefix(prefix)
+
+
+@register("whisper-cpp", benchmark_type="batch")
+def run_batch(
+    model_name: str,
+    utterances: list[Utterance],
+    *,
+    quantization: str = "int8",
+    beam_size: int = 5,
+    temperature: float = 0.0,
+    vad: bool = True,
+    threads: int = 4,
+    download_root: str | Path | None = None,
+) -> list[Transcription]:
+    """Transcribe every utterance once, batch-style, and time each call.
+
+    `quantization`/`beam_size`/`vad` are accepted for call-shape parity with
+    the other batch adapters (docs/03-roadmap.md M2 exit criterion: adapters
+    swap without core changes) but unused here — whisper.cpp's ggml models
+    are pre-quantized by model-file choice rather than a runtime flag,
+    `beam_size` lives under a nested `beam_search` param pywhispercpp's flat
+    `**params` doesn't set (defaults to whisper.cpp's own greedy strategy),
+    and this batch adapter doesn't chunk audio (that's M5's streaming
+    concern).
+    """
+    try:
+        from pywhispercpp.model import Model
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise RuntimeError(
+            "pywhispercpp is not installed; run "
+            "`pip install goesb-runner[whisper-cpp]`"
+        ) from exc
+
+    model = Model(
+        _resolve_model_id(model_name),
+        models_dir=str(download_root) if download_root is not None else None,
+        n_threads=threads,
+        temperature=temperature,
+        print_realtime=False,
+        print_progress=False,
+    )
+
+    results: list[Transcription] = []
+    for utterance in utterances:
+        samples = decode_pcm(utterance.audio_path, dtype="float32")
+        start = time.perf_counter()
+        segments = model.transcribe(samples)
+        hypothesis_text = " ".join(segment.text.strip() for segment in segments).strip()
+        elapsed = time.perf_counter() - start
+        results.append(Transcription(
+            utterance_id=utterance.utterance_id,
+            hypothesis_text=hypothesis_text,
+            processing_time_s=elapsed,
+        ))
+    return results

oesb_runner/audio.py

@@ -0,0 +1,104 @@
+"""Minimal audio introspection and decoding.
+
+`flac_duration_s` is dependency-free by design: FLAC duration, parsed straight
+from the STREAMINFO metadata block (no ffmpeg/libsndfile required just to know
+how long a pack's clips are). `decode_pcm` is the one exception — adapters
+that need actual PCM samples (vosk, whisper.cpp) lazy-import `soundfile` for
+it, same optional-dependency pattern as the runtime adapters themselves, so
+importing this module never requires it.
+"""
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import numpy as np
+
+
+def wav_duration_s(path: str | Path) -> float:
+    """Duration in seconds, read straight from a WAV file's RIFF chunks —
+    no extra dependency, same spirit as `flac_duration_s` below. Parsed by
+    hand rather than via the stdlib `wave` module: `wave` only understands
+    integer-PCM format tag 1 and raises on anything else, but datasets
+    published as 32-bit float WAV (format tag 3 — e.g. FLEURS) are common
+    and don't need decoding just to know their length."""
+    with open(path, "rb") as f:
+        if f.read(4) != b"RIFF":
+            raise ValueError(f"not a RIFF/WAV file: {path}")
+        f.read(4)  # overall chunk size, unused
+        if f.read(4) != b"WAVE":
+            raise ValueError(f"not a WAVE file: {path}")
+
+        sample_rate: int | None = None
+        block_align: int | None = None
+        while True:
+            header = f.read(8)
+            if len(header) < 8:
+                break
+            chunk_id, chunk_size = header[:4], int.from_bytes(header[4:8], "little")
+            if chunk_id == b"fmt ":
+                fmt = f.read(chunk_size)
+                # channels(2)@2, sample_rate(4)@4, block_align(2)@12
+                sample_rate = struct.unpack("<I", fmt[4:8])[0]
+                block_align = struct.unpack("<H", fmt[12:14])[0]
+            elif chunk_id == b"data":
+                if sample_rate is None or block_align is None:
+                    raise ValueError(f"WAV data chunk came before fmt chunk: {path}")
+                frames = chunk_size / block_align
+                return frames / sample_rate
+            else:
+                f.seek(chunk_size, 1)
+            if chunk_size % 2:
+                f.seek(1, 1)  # RIFF chunks are word-aligned; skip the pad byte
+        raise ValueError(f"WAV file has no data chunk: {path}")
+
+
+def flac_duration_s(path: str | Path) -> float:
+    """Duration in seconds, read from a FLAC file's STREAMINFO block."""
+    with open(path, "rb") as f:
+        if f.read(4) != b"fLaC":
+            raise ValueError(f"not a FLAC file: {path}")
+        while True:
+            header = f.read(4)
+            if len(header) < 4:
+                raise ValueError(f"FLAC file has no STREAMINFO block: {path}")
+            is_last = header[0] & 0x80
+            block_type = header[0] & 0x7F
+            length = int.from_bytes(header[1:4], "big")
+            body = f.read(length)
+            if block_type == 0:  # STREAMINFO
+                # bytes 10..18 of STREAMINFO pack sample_rate(20)/channels(3)/
+                # bits_per_sample(5)/total_samples(36) into 64 bits.
+                packed = struct.unpack(">Q", body[10:18])[0]
+                sample_rate = packed >> 44
+                total_samples = packed & 0xF_FFFF_FFFF
+                if sample_rate == 0:
+                    raise ValueError(f"FLAC STREAMINFO has zero sample rate: {path}")
+                return total_samples / sample_rate
+            if is_last:
+                raise ValueError(f"FLAC file has no STREAMINFO block: {path}")
+
+
+def decode_pcm(path: str | Path, dtype: str = "int16") -> np.ndarray:
+    """Decode an audio file to a 1-D mono PCM array at its native sample rate.
+
+    `dtype` is `"int16"` (what vosk's `AcceptWaveform` expects as raw bytes)
+    or `"float32"` (what pywhispercpp's `transcribe()` accepts directly).
+    Every GOESB pack shipped so far is already mono at the profile's target
+    rate (see each pack's `pack.yaml` `audio.sample_rate_hz`), so this does
+    not resample — a documented assumption, not a silent one.
+    """
+    try:
+        import soundfile as sf
+    except ImportError as exc:  # pragma: no cover - exercised only without an extra
+        raise RuntimeError(
+            "soundfile is not installed; run `pip install goesb-runner[vosk]` "
+            "or `pip install goesb-runner[whisper-cpp]`"
+        ) from exc
+
+    samples, _sample_rate = sf.read(str(path), dtype=dtype, always_2d=False)
+    if samples.ndim > 1:  # collapse stereo to mono by averaging channels
+        samples = samples.mean(axis=1).astype(samples.dtype)
+    return samples