@they-juanreina/compost-cli 0.1.1 → 0.1.2

package/transcriber/app/vad.py

@@ -0,0 +1,145 @@
+"""Silero VAD integration + silence segmentation (#9).
+
+Two outputs (ROADMAP § Descriptive transcription A):
+  (a) speech-segment boundaries → fed to ASR
+  (b) silence boundaries → fed to the silence typer (#12)
+
+Silero v5 is loaded once per process (cold-start cached). The model call is
+lazily imported so this module — and the silence-segmentation maths, which is
+pure — works without torch installed. Install the `asr` extra for real VAD.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any, Protocol
+
+# Silences shorter than this are NOT first-class; they remain gaps only.
+MIN_FIRST_CLASS_SILENCE_MS = 1500
+
+
+@dataclass(frozen=True)
+class Segment:
+    start_ms: int
+    end_ms: int
+
+    @property
+    def duration_ms(self) -> int:
+        return self.end_ms - self.start_ms
+
+
+class VADBackend(Protocol):
+    def speech_timestamps(self, audio_path: str) -> list[dict[str, int]]: ...
+
+
+SILERO_SAMPLE_RATE = 16000
+
+
+class SileroBackend:  # pragma: no cover - needs torch + weights
+    """Concrete VADBackend wrapping silero-vad.
+
+    The Silero v5 model is loaded once per process. Audio is decoded to a
+    16 kHz mono waveform via the package's `read_audio` helper. Returns
+    speech segment boundaries in milliseconds.
+    """
+
+    def __init__(self) -> None:
+        try:
+            from silero_vad import (  # type: ignore
+                get_speech_timestamps,
+                load_silero_vad,
+                read_audio,
+            )
+        except ImportError as e:
+            raise RuntimeError(
+                "silero-vad is not installed. Install the asr extra: pip install -e '.[asr]'"
+            ) from e
+
+        self._model = load_silero_vad()
+        self._read_audio = read_audio
+        self._get_speech_timestamps = get_speech_timestamps
+
+    def speech_timestamps(self, audio_path: str) -> list[dict[str, int]]:
+        wav = self._read_audio(audio_path, sampling_rate=SILERO_SAMPLE_RATE)
+        raw = self._get_speech_timestamps(
+            wav,
+            self._model,
+            sampling_rate=SILERO_SAMPLE_RATE,
+            return_seconds=False,
+        )
+        # `raw` is a list of {start, end} in samples; convert to ms.
+        ms_per_sample = 1000 / SILERO_SAMPLE_RATE
+        return [
+            {
+                "start_ms": int(seg["start"] * ms_per_sample),
+                "end_ms": int(seg["end"] * ms_per_sample),
+            }
+            for seg in raw
+        ]
+
+
+@lru_cache(maxsize=1)
+def _load_silero() -> VADBackend:  # pragma: no cover - needs torch + weights
+    try:
+        import torch  # type: ignore  # noqa: F401
+    except ImportError as e:
+        raise RuntimeError(
+            "torch/silero not installed. Install the asr extra: pip install -e '.[asr]'"
+        ) from e
+    return SileroBackend()
+
+
+def speech_to_silences(
+    speech: list[Segment],
+    total_duration_ms: int,
+    min_silence_ms: int = MIN_FIRST_CLASS_SILENCE_MS,
+) -> list[Segment]:
+    """Derive first-class silence segments from speech segments.
+
+    Pure. Considers the gaps before the first speech, between speech segments,
+    and after the last speech. Only gaps >= min_silence_ms are returned.
+    Overlapping/auto-sorted by start.
+    """
+    ordered = sorted(speech, key=lambda s: s.start_ms)
+    silences: list[Segment] = []
+    cursor = 0
+    for seg in ordered:
+        if seg.start_ms - cursor >= min_silence_ms:
+            silences.append(Segment(cursor, seg.start_ms))
+        cursor = max(cursor, seg.end_ms)
+    if total_duration_ms - cursor >= min_silence_ms:
+        silences.append(Segment(cursor, total_duration_ms))
+    return silences
+
+
+def silences_to_schema(silences: list[Segment]) -> list[dict[str, Any]]:
+    """Render silence segments as transcript.json silences[] entries (untyped;
+    the silence typer #12 fills `context`)."""
+    out: list[dict[str, Any]] = []
+    for i, s in enumerate(silences, start=1):
+        out.append(
+            {
+                "id": f"SIL-{i:03d}",
+                "start_ms": s.start_ms,
+                "end_ms": s.end_ms,
+                "duration_ms": s.duration_ms,
+                "context": "thinking",  # placeholder until the typer runs
+            }
+        )
+    return out
+
+
+class VAD:
+    def __init__(self, backend: VADBackend | None = None):
+        self._backend = backend
+
+    def _get_backend(self) -> VADBackend:
+        return self._backend if self._backend is not None else _load_silero()
+
+    def segment(self, audio_path: str, total_duration_ms: int) -> tuple[list[Segment], list[Segment]]:
+        """Return (speech_segments, first_class_silences)."""
+        raw = self._get_backend().speech_timestamps(audio_path)
+        speech = [Segment(int(t["start_ms"]), int(t["end_ms"])) for t in raw]
+        silences = speech_to_silences(speech, total_duration_ms)
+        return speech, silences

package/transcriber/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "compost-transcriber"
+version = "0.1.2"
+description = "Compost descriptive transcriber: WhisperX + pyannote + Silero VAD + Whisper-event-tags, plus frame extraction and legacy ingest."
+requires-python = ">=3.11,<3.13"
+license = { text = "MIT" }
+authors = [{ name = "Juan Reina" }]
+
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "pydantic>=2.9.0",
+]
+
+[project.optional-dependencies]
+# Pinned in their own M1 issues (#9-#15) — kept out of the base install so
+# the skeleton boots quickly without pulling multi-GB ML wheels.
+asr = [
+    "whisperx",
+    "pyannote.audio>=3.3",
+    "silero-vad",
+    # WhisperX brings these transitively but pinning lets the lock file note
+    # the M1-Mac-friendly compute path.
+    "torch>=2.3",
+    "torchaudio>=2.3",
+    "ffmpeg-python",
+]
+# Native Apple-Silicon (Metal) path (#176/#183): Parakeet ASR + pyannote-on-MPS.
+# No whisperx/ctranslate2 — the default native engine is Parakeet (parakeet-mlx).
+# Provisioned by `compost setup --provision-native`.
+native = [
+    "parakeet-mlx",
+    "pyannote.audio>=3.3",
+    "silero-vad",
+    "torchaudio>=2.3",
+    "ffmpeg-python",
+]
+frames = [
+    "imagehash",
+    "Pillow",
+]
+legacy = [
+    "pdfminer.six",
+    "pdfplumber",
+    "python-docx",
+    "python-pptx",
+    "openpyxl",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B", "SIM"]
+ignore = ["E501"]