@they-juanreina/compost-cli 0.1.1 → 0.1.3

package/transcriber/app/shot_change.py

@@ -0,0 +1,74 @@
+"""Perceptual-hash shot-change detector (#15).
+
+Samples the video at a fixed cadence, computes a perceptual hash per sampled
+frame, and reports the timestamps where the hash distance to the previous
+sample crosses a threshold — i.e. a scene cut, slide change, or camera move.
+
+Output is a list of at_ms values consumed by the frame extractor (#14) as
+`shot_change` triggers. No classification beyond "something changed".
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+import imagehash
+from PIL import Image
+
+# Default Hamming-distance threshold between consecutive perceptual hashes.
+# Tunable via config ([frames].shot_change_phash_distance).
+DEFAULT_PHASH_DISTANCE = 12
+DEFAULT_SAMPLE_INTERVAL_MS = 1000
+
+
+def _sample_frame(video_path: Path, at_ms: int, out_path: Path) -> bool:
+    ts = at_ms / 1000.0
+    cmd = [
+        "ffmpeg",
+        "-y",
+        "-ss",
+        f"{ts:.3f}",
+        "-i",
+        str(video_path),
+        "-frames:v",
+        "1",
+        "-vf",
+        "scale=160:90",
+        str(out_path),
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    return proc.returncode == 0 and out_path.exists()
+
+
+def detect_shot_changes(
+    video_path: str | Path,
+    duration_ms: int,
+    threshold: int = DEFAULT_PHASH_DISTANCE,
+    sample_interval_ms: int = DEFAULT_SAMPLE_INTERVAL_MS,
+) -> list[int]:
+    """Return at_ms timestamps where a shot change is detected.
+
+    The first sampled frame is never a "change" (no predecessor). Distances at
+    or above `threshold` mark a change.
+    """
+    video_path = Path(video_path)
+    changes: list[int] = []
+    prev_hash: imagehash.ImageHash | None = None
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_dir = Path(tmp)
+        at = 0
+        idx = 0
+        while at < duration_ms:
+            frame_path = tmp_dir / f"s{idx}.png"
+            if _sample_frame(video_path, at, frame_path):
+                with Image.open(frame_path) as img:
+                    h = imagehash.phash(img)
+                if prev_hash is not None and (h - prev_hash) >= threshold:
+                    changes.append(at)
+                prev_hash = h
+            at += sample_interval_ms
+            idx += 1
+    return changes

package/transcriber/app/silence_typer.py

@@ -0,0 +1,144 @@
+"""Silence typer — heuristic post-processor that assigns a semantic type to each
+first-class silence (> threshold) from the surrounding utterance context.
+
+Types (ROADMAP § Descriptive transcription A):
+  - after_question : the silence follows a moderator question
+  - mid_utterance  : the silence sits inside one speaker's turn
+  - thinking       : a pre-response pause that isn't clearly after a question
+  - interruption   : the silence coincides with an overlap/turn-steal
+
+Rules are versioned. Researchers can override any assignment downstream; an
+override is recorded as a `researcher`-authored event in the provenance log
+(see issue #12 / provenance writer #27).
+
+CHANGELOG
+  v1 (2026-06-03): initial rule set.
+    - after_question: previous utterance is a moderator AND ends with '?'
+      (or a leading inverted '¿' question), and abuts the silence start.
+    - interruption: an overlap/interruption cue overlaps the silence window,
+      OR previous and next utterances are different speakers and the previous
+      did not end on sentence-final punctuation (cut off).
+    - mid_utterance: previous and next utterances are the same speaker.
+    - thinking: default.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+RULES_VERSION = "1"
+
+_SILENCE_TYPES = ("after_question", "mid_utterance", "thinking", "interruption")
+
+# How close (ms) the previous utterance's end must be to the silence start for
+# the silence to be considered "abutting" that utterance.
+_ABUT_TOLERANCE_MS = 250
+
+_SENTENCE_FINAL = (".", "!", "?", "…")
+
+
+def _ends_question(text: str) -> bool:
+    stripped = text.rstrip()
+    if stripped.endswith("?"):
+        return True
+    # Spanish inverted question mark opening with no closing yet still reads as a question.
+    return "¿" in stripped and "?" in stripped
+
+
+def _ends_sentence_final(text: str) -> bool:
+    stripped = text.rstrip()
+    return stripped.endswith(_SENTENCE_FINAL)
+
+
+def _speaker_type(speakers: list[dict[str, Any]], speaker_id: str | None) -> str | None:
+    if speaker_id is None:
+        return None
+    for s in speakers:
+        if s.get("id") == speaker_id:
+            return s.get("type")
+    return None
+
+
+def _cue_overlaps(silence: dict[str, Any], cues: list[dict[str, Any]]) -> bool:
+    s_start = silence["start_ms"]
+    s_end = silence["end_ms"]
+    for cue in cues:
+        if cue.get("kind") not in ("overlap", "interruption"):
+            continue
+        # any temporal overlap between the cue and the silence window
+        if cue["start_ms"] <= s_end and cue["end_ms"] >= s_start:
+            return True
+    return False
+
+
+def type_silence(
+    silence: dict[str, Any],
+    prev_utt: dict[str, Any] | None,
+    next_utt: dict[str, Any] | None,
+    speakers: list[dict[str, Any]],
+    cues: list[dict[str, Any]] | None = None,
+) -> str:
+    """Return one of the four silence types for a single silence."""
+    cues = cues or []
+
+    if _cue_overlaps(silence, cues):
+        return "interruption"
+
+    if prev_utt is not None:
+        abuts = abs(silence["start_ms"] - prev_utt["end_ms"]) <= _ABUT_TOLERANCE_MS
+        prev_type = _speaker_type(speakers, prev_utt.get("speaker_id"))
+        if abuts and prev_type == "moderator" and _ends_question(prev_utt.get("text", "")):
+            return "after_question"
+
+    if (
+        prev_utt is not None
+        and next_utt is not None
+        and prev_utt.get("speaker_id") == next_utt.get("speaker_id")
+    ):
+        return "mid_utterance"
+
+    # Different speakers (or unknown) and the previous turn was cut off → interruption.
+    if (
+        prev_utt is not None
+        and next_utt is not None
+        and prev_utt.get("speaker_id") != next_utt.get("speaker_id")
+        and not _ends_sentence_final(prev_utt.get("text", ""))
+    ):
+        return "interruption"
+
+    return "thinking"
+
+
+def _utterance_before(utterances: list[dict[str, Any]], at_ms: int) -> dict[str, Any] | None:
+    candidate = None
+    for u in utterances:
+        if u["end_ms"] <= at_ms + _ABUT_TOLERANCE_MS and (
+            candidate is None or u["end_ms"] > candidate["end_ms"]
+        ):
+            candidate = u
+    return candidate
+
+
+def _utterance_after(utterances: list[dict[str, Any]], at_ms: int) -> dict[str, Any] | None:
+    candidate = None
+    for u in utterances:
+        if u["start_ms"] >= at_ms - _ABUT_TOLERANCE_MS and (
+            candidate is None or u["start_ms"] < candidate["start_ms"]
+        ):
+            candidate = u
+    return candidate
+
+
+def type_all_silences(transcript: dict[str, Any]) -> dict[str, Any]:
+    """Annotate every silence in a transcript dict with a `context` type.
+
+    Mutates and returns the transcript. Idempotent. Fast: O(silences × utterances).
+    """
+    utterances = transcript.get("utterances", [])
+    cues = transcript.get("cues", [])
+    speakers = transcript.get("speakers", [])
+    for silence in transcript.get("silences", []):
+        prev_utt = _utterance_before(utterances, silence["start_ms"])
+        next_utt = _utterance_after(utterances, silence["end_ms"])
+        silence["context"] = type_silence(silence, prev_utt, next_utt, speakers, cues)
+    return transcript

package/transcriber/app/transcribe_cli.py

@@ -0,0 +1,82 @@
+"""Native (host) transcription entrypoint (#176).
+
+Runs the full pipeline ON THE HOST (no Docker) so Apple-Silicon ASR backends
+(`parakeet-mlx` / Metal) and pyannote use the GPU/CPU directly — the Docker
+container is CPU-only on macOS, which is the bottleneck this path removes. The
+Node CLI shells out to this when `transcriber.runtime = native`; the Docker
+`/transcribe` route stays the cross-platform fallback and shares the exact same
+`run_pipeline` orchestration.
+
+    python -m app.transcribe_cli \
+        --seed-path <seed> --session-id S001 \
+        --source-path <seed>/sessions/S001/source.mp3 \
+        --engine parakeet --language en
+
+Prints one JSON line mirroring the /transcribe response shape so the Node
+caller parses both paths identically.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from .asr import ASRConfig
+from .pipeline import PipelineBackends, PipelineConfig, run_pipeline, write_transcript
+
+_DEFAULT_MODEL = {
+    "parakeet": "mlx-community/parakeet-tdt-0.6b-v3",
+    "whisper": "large-v3-turbo",
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="compost-transcribe-native")
+    p.add_argument("--seed-path", required=True)
+    p.add_argument("--session-id", required=True)
+    p.add_argument("--source-path", required=True)
+    p.add_argument("--engine", default="parakeet", choices=["parakeet", "whisper"])
+    p.add_argument("--model", default=None, help="ASR model id (engine default if omitted)")
+    p.add_argument("--language", default=None)
+    p.add_argument("--device", default="auto")
+    p.add_argument("--compute-type", default="int8")
+    args = p.parse_args(argv)
+
+    asr = ASRConfig(
+        model_name=args.model or _DEFAULT_MODEL[args.engine],
+        device=args.device,
+        compute_type=args.compute_type,
+        language=args.language,
+        engine=args.engine,
+    )
+    config = PipelineConfig(asr=asr, asr_model_tag=f"{asr.model_name} ({args.engine})")
+
+    try:
+        transcript = run_pipeline(
+            seed_path=args.seed_path,
+            session_id=args.session_id,
+            source_path=args.source_path,
+            config=config,
+            backends=PipelineBackends(),  # all None → real lazy backends (Silero / engine ASR / pyannote)
+        )
+    except Exception as e:  # surface as JSON so the Node caller can report it
+        print(json.dumps({"status": "failed", "error": str(e)}))
+        return 1
+
+    path = write_transcript(args.seed_path, args.session_id, transcript)
+    print(
+        json.dumps(
+            {
+                "session_id": args.session_id,
+                "transcript_path": path,
+                "status": transcript.get("status", "ok"),
+                "engine": args.engine,
+                "model": asr.model_name,
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/transcriber/app/vad.py

@@ -0,0 +1,216 @@
+"""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
+    # Mean RMS energy over the segment's waveform (raw amplitude, ~0..1; speech
+    # peaks well below 1.0). `None` when the backend doesn't report it — the
+    # prosody stage then leaves volume at "normal" rather than guessing.
+    energy: float | None = None
+
+    @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, Any]]:
+        """Return speech segments as ``{"start_ms", "end_ms"}`` dicts, optionally
+        with a float ``"energy"`` (mean RMS over the segment)."""
+        ...
+
+
+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, Any]]:
+        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 and compute
+        # the mean RMS energy over each segment's waveform window (#9 → #13).
+        # `wav` is a mono float tensor in [-1, 1]; RMS = sqrt(mean(x^2)).
+        ms_per_sample = 1000 / SILERO_SAMPLE_RATE
+        out: list[dict[str, Any]] = []
+        for seg in raw:
+            start_sample, end_sample = int(seg["start"]), int(seg["end"])
+            window = wav[start_sample:end_sample]
+            rms = float(window.pow(2).mean().sqrt()) if window.numel() else 0.0
+            out.append(
+                {
+                    "start_ms": int(seg["start"] * ms_per_sample),
+                    "end_ms": int(seg["end"] * ms_per_sample),
+                    "energy": rms,
+                }
+            )
+        return out
+
+
+@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
+
+
+def utterance_energies(
+    speech: list[Segment],
+    utterances: list[dict[str, Any]],
+) -> dict[str, float]:
+    """Map utterance id → mean VAD RMS energy, normalized 0..1 across the session.
+
+    Pure. Feeds ``prosody.annotate_prosody(transcript, energies=...)`` so the
+    low|normal|high volume bucketing actually runs (without this signal volume
+    defaults to "normal" for every utterance).
+
+    Each utterance's raw energy is the overlap-duration-weighted mean RMS of the
+    speech segments it spans; segments with no energy reading are ignored. Raw
+    speech RMS peaks far below 1.0, so applying prosody's fixed 0.33/0.66 split
+    to raw values would bucket everything as "low" — we normalize by the loudest
+    utterance in the session so the split is meaningful and reproducible.
+    Utterances with no overlapping energy-bearing segment are omitted, so the
+    caller reports "normal" rather than guessing.
+
+    TODO(#13): normalization is per-session (global max) and prosody's
+    VOLUME_LOW/HIGH are global constants, so a soft speaker's loudest moment
+    still reads quieter than a loud speaker's baseline. Per-speaker
+    normalization (group by ``utterance["speaker_id"]`` and normalize within
+    each speaker) would make the buckets speaker-relative. Out of scope here.
+    """
+    raw: dict[str, float] = {}
+    for utt in utterances:
+        uid = utt.get("id")
+        if uid is None:
+            continue
+        u_start, u_end = utt.get("start_ms", 0), utt.get("end_ms", 0)
+        weighted_sum = 0.0
+        total_overlap = 0
+        for seg in speech:
+            if seg.energy is None:
+                continue
+            overlap = min(u_end, seg.end_ms) - max(u_start, seg.start_ms)
+            if overlap <= 0:
+                continue
+            weighted_sum += seg.energy * overlap
+            total_overlap += overlap
+        if total_overlap > 0:
+            raw[uid] = weighted_sum / total_overlap
+
+    peak = max(raw.values(), default=0.0)
+    if peak <= 0:
+        return {}
+    return {uid: value / peak for uid, value in raw.items()}
+
+
+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"]),
+                float(t["energy"]) if t.get("energy") is not None else None,
+            )
+            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"]