wirenote 0.1.0__py3-none-any.whl

wirenote/process/speakers.py

@@ -0,0 +1,295 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav
+"""Who spoke when on the Others track, and who they are (docs/dev/features-2-design.md › Speakers).
+
+- Diarization: sherpa-onnx, pyannote segmentation 3.0 plus a speaker-embedding
+  model, CPU only. Speakers are labelled S1, S2, ... in order of first speech.
+- Whisper's word timestamps are split at speaker changes, so one line never
+  mixes two people.
+- Names, in this order: a remembered voice (voices.json, taught by renaming a
+  speaker in the app), then the summary backend's reading of the transcript
+  ("Thanks, Anna") checked against the calendar attendees, else "Speaker N".
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+from ..config.settings import Settings, data_dir
+from .models import EMB_REPO, SEG_FILE, SEG_REPO, hub_file  # noqa: F401 - re-exported
+
+EMBED_SECONDS = 30.0      # speech per speaker used for its voice print
+MIN_TURN_S = 0.8          # shorter turns are too short for a reliable voice print
+
+
+@dataclass(frozen=True)
+class Turn:
+    start: float
+    end: float
+    label: int
+
+
+@dataclass(frozen=True)
+class Word:
+    start: float
+    end: float
+    text: str
+
+
+def label_name(label: str) -> str:
+    """S3 -> Speaker 3; Me and legacy Others stay."""
+    m = re.fullmatch(r"S(\d+)", label)
+    return f"Speaker {m.group(1)}" if m else label
+
+
+def display_name(label: str, speakers: dict) -> str:
+    info = speakers.get(label) or {}
+    return info.get("name") or label_name(label)
+
+
+def _unit(v) -> np.ndarray:
+    v = np.asarray(v, dtype=np.float32)
+    n = float(np.linalg.norm(v))
+    return v / n if n else v
+
+
+class Diarizer:
+    def __init__(self, settings: Settings) -> None:
+        import sherpa_onnx
+
+        seg = hub_file(SEG_REPO, SEG_FILE)
+        emb = hub_file(EMB_REPO, settings.diarize_model)
+        cfg = sherpa_onnx.OfflineSpeakerDiarizationConfig(
+            segmentation=sherpa_onnx.OfflineSpeakerSegmentationModelConfig(
+                pyannote=sherpa_onnx.OfflineSpeakerSegmentationPyannoteModelConfig(model=seg)),
+            embedding=sherpa_onnx.SpeakerEmbeddingExtractorConfig(model=emb),
+            clustering=sherpa_onnx.FastClusteringConfig(num_clusters=-1,
+                                                        threshold=settings.diarize_threshold),
+            min_duration_on=0.3, min_duration_off=0.5)
+        if not cfg.validate():
+            raise RuntimeError("speaker separation models are incomplete")
+        self.sd = sherpa_onnx.OfflineSpeakerDiarization(cfg)
+        self.extractor = sherpa_onnx.SpeakerEmbeddingExtractor(
+            sherpa_onnx.SpeakerEmbeddingExtractorConfig(model=emb))
+
+    def run(self, audio: np.ndarray, rate: int = 16000) -> tuple[list[Turn], dict[int, np.ndarray]]:
+        """Speaker turns of one file, plus one voice print per speaker."""
+        turns = [Turn(s.start, s.end, s.speaker) for s in self.sd.process(audio).sort_by_start_time()]
+        prints = {}
+        for label in {t.label for t in turns}:
+            mine = sorted((t for t in turns if t.label == label), key=lambda t: t.start - t.end)
+            chunks, total = [], 0.0
+            for t in mine:
+                if t.end - t.start < MIN_TURN_S and chunks:
+                    continue
+                chunks.append(audio[int(t.start * rate):int(t.end * rate)])
+                total += t.end - t.start
+                if total >= EMBED_SECONDS:
+                    break
+            stream = self.extractor.create_stream()
+            stream.accept_waveform(rate, np.concatenate(chunks))
+            stream.input_finished()
+            prints[label] = _unit(self.extractor.compute(stream))
+        return turns, prints
+
+
+def split_by_speaker(words: list[Word], turns: list[Turn]) -> list[tuple[int | None, list[Word]]]:
+    """Group consecutive words by the speaker whose turn holds each word's middle
+    (the nearest turn when none does)."""
+    runs: list[tuple[int | None, list[Word]]] = []
+    for w in words:
+        mid = (w.start + w.end) / 2
+        inside = [t for t in turns if t.start <= mid <= t.end]
+        if inside:
+            label = min(inside, key=lambda t: t.end - t.start).label
+        elif turns:
+            label = min(turns, key=lambda t: min(abs(t.start - mid), abs(t.end - mid))).label
+        else:
+            label = None
+        if runs and runs[-1][0] == label:
+            runs[-1][1].append(w)
+        else:
+            runs.append((label, [w]))
+    return runs
+
+
+SENTENCE_END = (".", "?", "!", "…", "。", "？", "！")
+MAX_PAUSE_S = 1.0          # a longer pause ends a sentence even without punctuation
+SPLIT_BELOW_SHARE = 0.6    # a sentence is split only if no speaker has this share of it
+MIN_SPLIT_WORDS = 6        # shorter sentences are never split
+
+
+def sentences(words: list[Word]) -> list[list[Word]]:
+    """Words grouped into sentences: at end punctuation or a pause. Whisper's own
+    segments are not used, because a vocabulary prompt turns them into one block."""
+    out: list[list[Word]] = []
+    for w in words:
+        if out and not out[-1][-1].text.strip().endswith(SENTENCE_END) \
+                and w.start - out[-1][-1].end <= MAX_PAUSE_S:
+            out[-1].append(w)
+        else:
+            out.append([w])
+    return out
+
+
+def _overlap(w: Word, t: Turn) -> float:
+    return max(0.0, min(w.end, t.end) - max(w.start, t.start))
+
+
+def assign_sentence(words: list[Word], turns: list[Turn]) -> list[tuple[int | None, list[Word]]]:
+    """A sentence goes to the speaker who covers most of it. Only a long sentence
+    that really spans two people is split; 1-word runs then rejoin a neighbour."""
+    share: dict[int, float] = {}
+    for w in words:
+        for t in turns:
+            o = _overlap(w, t)
+            if o:
+                share[t.label] = share.get(t.label, 0.0) + o
+    if not share:   # between turns: the nearest speaker takes the whole sentence
+        runs = split_by_speaker(words, turns)
+        return [(runs[0][0] if runs else None, words)]
+    best = max(share, key=share.get)
+    if len(words) < MIN_SPLIT_WORDS or share[best] / sum(share.values()) >= SPLIT_BELOW_SHARE:
+        return [(best, words)]
+    runs = split_by_speaker(words, turns)
+    merged: list[tuple[int | None, list[Word]]] = []
+    for label, ws in runs:
+        if merged and (len(ws) < 2 or merged[-1][0] == label):
+            merged[-1] = (merged[-1][0], merged[-1][1] + ws)
+        else:
+            merged.append((label, list(ws)))
+    if len(merged) > 1 and len(merged[0][1]) < 2:
+        merged[1] = (merged[1][0], merged[0][1] + merged[1][1])
+        merged.pop(0)
+    return merged
+
+
+class SpeakerBook:
+    """Speakers of one recording across its segment files, labelled S1, S2, ..."""
+
+    def __init__(self, same_voice: float) -> None:
+        self.same_voice = same_voice
+        self.prints: dict[str, np.ndarray] = {}
+        self.seconds: dict[str, float] = {}
+
+    def label_for(self, voice: np.ndarray) -> str:
+        best, score = None, -1.0
+        for label, v in self.prints.items():
+            s = float(v @ voice)
+            if s > score:
+                best, score = label, s
+        if best is not None and score >= self.same_voice:
+            return best
+        label = f"S{len(self.prints) + 1}"
+        self.prints[label] = voice
+        return label
+
+    def add_time(self, label: str, seconds: float) -> None:
+        self.seconds[label] = self.seconds.get(label, 0.0) + seconds
+
+
+# Remembered voices ---------------------------------------------------------
+
+def voices_path() -> Path:
+    return data_dir() / "voices.json"
+
+
+class Voices:
+    """Voice prints the user named in the app. Stay on this machine."""
+
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path or voices_path()
+        try:
+            self.data: dict = json.loads(self.path.read_text())
+        except (OSError, ValueError):
+            self.data = {}
+
+    def names(self) -> list[dict]:
+        return [{"name": n, "samples": v.get("count", 1), "updated": v.get("updated")}
+                for n, v in sorted(self.data.items())]
+
+    def match(self, voice, threshold: float) -> tuple[str | None, float]:
+        best, score = None, -1.0
+        for name, v in self.data.items():
+            s = float(_unit(v["embedding"]) @ _unit(voice))
+            if s > score:
+                best, score = name, s
+        return (best, score) if score >= threshold else (None, score)
+
+    def remember(self, name: str, voice) -> None:
+        old = self.data.get(name)
+        if old:
+            n = old.get("count", 1)
+            merged = _unit((_unit(old["embedding"]) * n + _unit(voice)) / (n + 1))
+            count = n + 1
+        else:
+            merged, count = _unit(voice), 1
+        self.data[name] = {"embedding": [round(float(x), 6) for x in merged], "count": count,
+                           "updated": dt.datetime.now().astimezone().isoformat(timespec="seconds")}
+        self._save()
+
+    def forget(self, name: str) -> bool:
+        if self.data.pop(name, None) is None:
+            return False
+        self._save()
+        return True
+
+    def _save(self) -> None:
+        self.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(".tmp")
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as f:
+            json.dump(self.data, f)
+        tmp.replace(self.path)
+
+
+# Names from the transcript ---------------------------------------------------
+
+NAME_SYSTEM = """You identify the speakers of a call transcript.
+Lines are labelled "Me" (the person who recorded) or S1, S2, ... (other people).
+For each S label, give the person's name only if the transcript makes it clear: \
+they introduce themselves, someone addresses them by name right before they answer, \
+or they are greeted by name. Otherwise give "".
+{attendees}evidence: the short quote that shows it, or "".
+Never give the same name to two labels. Never guess from voice or topic."""
+
+NAME_SCHEMA = {"type": "object", "properties": {"speakers": {"type": "array", "items": {
+    "type": "object",
+    "properties": {"label": {"type": "string"}, "name": {"type": "string"},
+                   "evidence": {"type": "string"}},
+    "required": ["label", "name", "evidence"], "additionalProperties": False}}},
+    "required": ["speakers"], "additionalProperties": False}
+
+
+def guess_names(text: str, labels: list[str], attendees: list[str], backend) -> dict[str, dict]:
+    """{label: {"name", "evidence"}} for labels the transcript names, checked:
+    the name must occur in the transcript (or be an invited attendee whose first
+    name occurs there)."""
+    if not labels:
+        return {}
+    who = (f"People invited to the call: {', '.join(attendees)}. Prefer these spellings.\n"
+           if attendees else "")
+    data = backend.complete_json(NAME_SYSTEM.format(attendees=who),
+                                 f"Labels to name: {', '.join(labels)}\n\nTranscript:\n{text}",
+                                 NAME_SCHEMA)
+    low = text.lower()
+    out: dict[str, dict] = {}
+    used: set[str] = set()
+    for item in data.get("speakers", []):
+        label, name = str(item.get("label", "")), str(item.get("name", "")).strip()
+        if label not in labels or not name or name.lower() in used:
+            continue
+        first = name.split()[0].lower()
+        if not re.search(rf"\b{re.escape(first)}\b", low):
+            continue        # not supported by the transcript
+        full = next((a for a in attendees if a.lower().split()[0] == first), name)
+        out[label] = {"name": full, "evidence": str(item.get("evidence", ""))[:200]}
+        used.add(full.lower())
+    return out

wirenote/process/summarize.py

@@ -0,0 +1,287 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav
+"""Meeting summary through a pluggable backend (docs/dev/PLAN.md › Processing, step 3).
+
+Backends: Ollama on this machine (the default, nothing leaves the laptop) or
+the Claude API. Both return JSON for one schema: title, summary points,
+decisions, action items with owners, open questions. Transcripts longer than
+summary_chunk_s are summarized per chunk, then the chunk notes are combined.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import socket
+import urllib.error
+import urllib.request
+from urllib.parse import urlsplit, urlunsplit
+from dataclasses import asdict, dataclass, field
+from typing import Protocol
+
+from ..config.secrets import load_secrets, secrets_path
+from ..config.settings import Settings
+from ..net.peer import listener_uid, trusted_owner
+from .merge import Line, as_text
+
+_LIST = {"type": "array", "items": {"type": "string"}}
+_ACTIONS = {"type": "array", "items": {
+    "type": "object",
+    "properties": {"owner": {"type": "string"}, "task": {"type": "string"},
+                   "due": {"type": "string"}},
+    "required": ["owner", "task", "due"], "additionalProperties": False}}
+_NOTES = {"summary": _LIST, "decisions": _LIST, "action_items": _ACTIONS,
+          "open_questions": _LIST}
+
+CHUNK_SCHEMA = {"type": "object", "properties": _NOTES, "required": list(_NOTES),
+                "additionalProperties": False}
+FINAL_SCHEMA = {"type": "object", "properties": {"title": {"type": "string"}, **_NOTES},
+                "required": ["title", *_NOTES], "additionalProperties": False}
+
+SYSTEM = """You write meeting notes from a call transcript.
+Speakers: "Me" is the person who recorded the call. Other people appear by name, \
+as "Speaker N" when their name is unknown, or as "Others" when several people share \
+one label. Use names as owners where you know them.
+The transcript comes from speech recognition, so expect some misheard words; \
+infer the meaning, do not quote errors.
+Only state what the transcript supports. Do not invent names, dates or decisions.
+Write every field, including the title, in {language}.
+
+Fields:
+- summary: 3 to 8 short bullet points covering the main topics and outcomes.
+- decisions: things the participants agreed on. Empty if none.
+- action_items: every task someone said they or another person will do, \
+including tasks "Me" took on. One entry per task. owner is "Me", the name \
+mentioned for it, or "Others" when unclear. due is the deadline said for that \
+task, or "" if none was said for it; do not reuse another task's date.
+- open_questions: questions raised but not resolved. Empty if none."""
+
+TITLE_FIELD = "\n- title: a short title for the meeting, at most 8 words."
+
+COMBINE = """These are notes for consecutive parts of one call, in order. Merge them \
+into notes for the whole call: remove repeats, keep every distinct decision, \
+action item and open question, and keep the summary to at most 8 points."""
+
+
+class SummaryError(Exception):
+    pass
+
+
+@dataclass
+class ActionItem:
+    owner: str
+    task: str
+    due: str = ""
+
+
+@dataclass
+class Summary:
+    title: str = ""
+    summary: list[str] = field(default_factory=list)
+    decisions: list[str] = field(default_factory=list)
+    action_items: list[ActionItem] = field(default_factory=list)
+    open_questions: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+class Backend(Protocol):
+    name: str
+
+    def complete_json(self, system: str, user: str, schema: dict) -> dict: ...
+
+
+# Backends --------------------------------------------------------------------
+
+def pin_local(url: str) -> tuple[str, str, int] | None:
+    """For a URL on this machine: (the URL with its host replaced by the numeric
+    loopback address, that address, the port); None for another machine.
+
+    The owner check and the request must use one address: "localhost" may
+    resolve to ::1, where someone else can listen while Ollama has 127.0.0.1."""
+    u = urlsplit(url)
+    host = u.hostname or ""
+    port = u.port or (443 if u.scheme == "https" else 80)
+    if host == "localhost":
+        ip = "127.0.0.1"
+    else:
+        try:
+            ip = str(ipaddress.ip_address(host))
+        except ValueError:
+            try:
+                ip = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)[0][4][0]
+            except (OSError, IndexError):
+                return None
+    if not ipaddress.ip_address(ip).is_loopback:
+        return None
+    netloc = f"[{ip}]:{port}" if ":" in ip else f"{ip}:{port}"
+    return urlunsplit((u.scheme, netloc, u.path, u.query, u.fragment)).rstrip("/"), ip, port
+
+
+class OllamaBackend:
+    """Ollama's /api/chat with a JSON schema as the format."""
+
+    def __init__(self, url: str, model: str, timeout_s: float = 900.0) -> None:
+        self.url = url.rstrip("/")
+        self.local = pin_local(self.url)
+        self.model = model
+        self.timeout_s = timeout_s
+        self.name = f"ollama:{model}"
+
+    def complete_json(self, system: str, user: str, schema: dict) -> dict:
+        # Other accounts can listen on loopback too: never hand a transcript to
+        # their server. Nothing listening is fine; the request fails below.
+        url = self.url
+        if self.local:
+            url, ip, port = self.local
+            owner = listener_uid(port, ip)
+            if owner is not None and not trusted_owner(owner):
+                raise SummaryError(f"Ollama on port {port} belongs to another user; "
+                                   "not sending the transcript")
+        body = {"model": self.model, "stream": False, "format": schema, "think": False,
+                "messages": [{"role": "system", "content": system},
+                             {"role": "user", "content": user}],
+                # 8k tokens holds a 15 min chunk; the model unloads soon after, so
+                # its RAM is free again for the next call or transcription.
+                "keep_alive": "60s", "options": {"num_ctx": 8192, "temperature": 0.2}}
+        req = urllib.request.Request(f"{url}/api/chat", data=json.dumps(body).encode(),
+                                     headers={"Content-Type": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout_s) as resp:
+                data = json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")[:300]
+            raise SummaryError(f"Ollama returned {e.code}: {detail}") from e
+        except (urllib.error.URLError, OSError) as e:
+            raise SummaryError(f"Ollama not reachable at {self.url} ({e}); is it installed "
+                               f"and running, and is the model pulled "
+                               f"(ollama pull {self.model})?") from e
+        return _parse_json(data.get("message", {}).get("content", ""))
+
+
+class AnthropicBackend:
+    """Claude API with structured output. Transcripts leave this machine."""
+
+    def __init__(self, model: str, api_key: str | None = None) -> None:
+        import anthropic
+
+        # No key in secrets.toml: the SDK falls back to ANTHROPIC_API_KEY or an
+        # `ant auth login` profile.
+        self.client = anthropic.Anthropic(api_key=api_key) if api_key else anthropic.Anthropic()
+        self.model = model
+        self.name = f"anthropic:{model}"
+
+    def complete_json(self, system: str, user: str, schema: dict) -> dict:
+        import anthropic
+
+        try:
+            resp = self.client.beta.messages.create(
+                model=self.model,
+                max_tokens=16000,
+                system=system,
+                messages=[{"role": "user", "content": user}],
+                output_config={"effort": "medium",
+                               "format": {"type": "json_schema", "schema": schema}},
+                # On a policy decline, re-run on Anthropic's recommended fallback model.
+                betas=["server-side-fallback-2026-07-01"],
+                fallbacks="default",
+            )
+        except anthropic.AuthenticationError as e:
+            raise SummaryError("Claude API: no valid API key (run `wirenote setup claude`, "
+                               f"or set anthropic_api_key in {secrets_path()})") from e
+        except anthropic.RateLimitError as e:
+            raise SummaryError("Claude API: rate limited, retry later") from e
+        except anthropic.APIStatusError as e:
+            raise SummaryError(f"Claude API error {e.status_code}: {e.message}") from e
+        except anthropic.APIConnectionError as e:
+            raise SummaryError(f"Claude API not reachable: {e}") from e
+        if resp.stop_reason == "refusal":
+            raise SummaryError("Claude API declined to summarize this transcript")
+        if resp.stop_reason == "max_tokens":
+            raise SummaryError("Claude API output was cut off (max_tokens)")
+        text = next((b.text for b in resp.content if b.type == "text"), "")
+        return _parse_json(text)
+
+
+def make_backend(settings: Settings) -> Backend | None:
+    if settings.summary_backend == "none":
+        return None
+    if settings.summary_backend == "ollama":
+        return OllamaBackend(settings.ollama_url, settings.ollama_model)
+    if settings.summary_backend == "anthropic":
+        return AnthropicBackend(settings.anthropic_model, load_secrets().get("anthropic_api_key"))
+    raise SummaryError(f"unknown summary_backend {settings.summary_backend!r} "
+                       "(ollama, anthropic or none)")
+
+
+# Summarizing -----------------------------------------------------------------
+
+def chunks(lines: list[Line], chunk_s: float) -> list[list[Line]]:
+    """Split at paragraph boundaries into windows of about chunk_s seconds."""
+    out: list[list[Line]] = []
+    for line in lines:
+        if not out or line.start - out[-1][0].start >= chunk_s:
+            out.append([])
+        out[-1].append(line)
+    return out
+
+
+def summarize(lines: list[Line], backend: Backend, chunk_s: float, language: str,
+              context: str = "", names: dict[str, str] | None = None) -> Summary:
+    if not lines:
+        raise SummaryError("empty transcript")
+    lang = "the same language as the transcript" if language == "auto" else language
+    system = SYSTEM.format(language=lang)
+    head = f"{context}\n\n" if context else ""
+    parts = chunks(lines, chunk_s)
+    if len(parts) == 1:
+        data = _ask(backend, system + TITLE_FIELD,
+                    f"{head}Transcript:\n{as_text(lines, names)}", FINAL_SCHEMA)
+        return _to_summary(data)
+    notes = []
+    for i, part in enumerate(parts, 1):
+        user = f"{head}Transcript, part {i} of {len(parts)}:\n{as_text(part, names)}"
+        notes.append(_ask(backend, system, user, CHUNK_SCHEMA))
+    user = f"{head}{COMBINE}\n\n" + "\n\n".join(
+        f"Part {i}:\n{json.dumps(n, ensure_ascii=False)}" for i, n in enumerate(notes, 1))
+    return _to_summary(_ask(backend, system + TITLE_FIELD, user, FINAL_SCHEMA))
+
+
+def _ask(backend: Backend, system: str, user: str, schema: dict) -> dict:
+    """One call, retried once if the JSON does not match the schema."""
+    last = None
+    for _ in range(2):
+        try:
+            data = backend.complete_json(system, user, schema)
+            _check(data, schema)
+            return data
+        except (ValueError, KeyError, TypeError) as e:
+            last = e
+    raise SummaryError(f"{backend.name} returned unusable JSON twice: {last}")
+
+
+def _parse_json(text: str) -> dict:
+    data = json.loads(text)
+    if not isinstance(data, dict):
+        raise ValueError("expected a JSON object")
+    return data
+
+
+def _check(data: dict, schema: dict) -> None:
+    for key in schema["required"]:
+        want = schema["properties"][key]["type"]
+        value = data[key]
+        if want == "string" and not isinstance(value, str):
+            raise TypeError(f"{key}: expected a string")
+        if want == "array" and not isinstance(value, list):
+            raise TypeError(f"{key}: expected a list")
+
+
+def _to_summary(data: dict) -> Summary:
+    strs = lambda xs: [str(x).strip() for x in xs if str(x).strip()]  # noqa: E731
+    items = [ActionItem(str(a.get("owner") or "Unassigned").strip(), str(a.get("task", "")).strip(),
+                        str(a.get("due") or "").strip())
+             for a in data.get("action_items", []) if isinstance(a, dict) and a.get("task")]
+    return Summary(str(data.get("title", "")).strip(), strs(data.get("summary", [])),
+                   strs(data.get("decisions", [])), items, strs(data.get("open_questions", [])))

wirenote/process/transcribe.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav
+"""Transcribe each recorded segment with faster-whisper (docs/dev/PLAN.md › Processing, step 1).
+
+CPU, int8; voice-activity filter on, word timestamps on, language auto-detect
+unless configured. Samples are decoded here (16 kHz mono s16 from pw-record)
+because faster-whisper's own decoder breaks with the installed PyAV.
+
+The vocabulary (names, product terms) goes in as hotwords, which faster-whisper
+puts into every window's prompt. On the system track, speakers are separated
+(process/speakers.py) and lines are split at speaker changes.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from ..capture import wav
+from ..config.settings import Settings
+from .merge import Line
+from .speakers import Diarizer, SpeakerBook, Word, assign_sentence, sentences
+
+MIN_SEGMENT_S = 0.5
+
+
+def log(msg: str) -> None:
+    print(f"worker: {msg}", file=sys.stderr, flush=True)
+
+
+class Transcriber:
+    def __init__(self, settings: Settings, vocabulary: list[str] | None = None) -> None:
+        from faster_whisper import WhisperModel
+
+        self.settings = settings
+        from .models import whisper_path
+
+        self.model = WhisperModel(whisper_path(settings.whisper_model), device="cpu",
+                                  compute_type="int8")
+        # Each term as its own sentence: Whisper copies the prompt's style, and a bare
+        # comma list made it drop sentence punctuation (docs/dev/features-2-design.md).
+        self.hotwords = " ".join(f"{t.rstrip('.')}." for t in vocabulary or [])[:600] or None
+        self.diarizer = None
+        if settings.diarize:
+            try:
+                self.diarizer = Diarizer(settings)
+            except Exception as e:  # noqa: BLE001 - fall back to a single "Others"
+                log(f"speaker separation unavailable, using 'Others': {e!r}")
+
+    def segment(self, path: Path, offset_s: float, track: str,
+                book: SpeakerBook) -> tuple[list[Line], dict]:
+        """Lines of one WAV, shifted by its offset in the recording, plus run info."""
+        if wav.duration_s(path) < MIN_SEGMENT_S:
+            return [], {"file": path.name, "skipped": "too short"}
+        audio = wav.load_float(path)
+        lang = None if self.settings.whisper_language == "auto" else self.settings.whisper_language
+        segments, info = self.model.transcribe(audio, language=lang, vad_filter=True,
+                                               word_timestamps=True, hotwords=self.hotwords)
+        segments = [s for s in segments if s.text.strip()]
+        run = {"file": path.name, "language": info.language,
+               "language_probability": round(info.language_probability, 2),
+               "audio_s": round(info.duration, 1), "speech_s": round(info.duration_after_vad, 1)}
+
+        words = [Word(w.start, w.end, w.word) for s in segments for w in (s.words or [])]
+        text = lambda ws: "".join(w.text for w in ws).strip()  # noqa: E731
+        line = lambda who, ws: Line(who, round(offset_s + ws[0].start, 2),  # noqa: E731
+                                    round(offset_s + ws[-1].end, 2), text(ws))
+
+        if track == "mic":
+            return [line("Me", ws) for ws in sentences(words) if text(ws)], run
+        if self.diarizer is None:
+            return [line("Others", ws) for ws in sentences(words) if text(ws)], run
+
+        turns, prints = self.diarizer.run(audio)
+        labels = {local: book.label_for(v) for local, v in prints.items()}
+        for t in turns:
+            book.add_time(labels[t.label], t.end - t.start)
+        lines = []
+        for sent in sentences(words):
+            for local, ws in assign_sentence(sent, turns):
+                if text(ws):
+                    lines.append(line(labels.get(local, "Others"), ws))
+        run["speakers"] = len(prints)
+        return lines, run
+
+    def recording(self, rec_dir: Path, manifest: dict) -> tuple[list[Line], list[dict], SpeakerBook]:
+        book = SpeakerBook(self.settings.voice_match)
+        lines, runs = [], []
+        for seg in manifest.get("segments", []):
+            path = rec_dir / seg["file"]
+            if not path.exists():
+                runs.append({"file": seg["file"], "skipped": "missing (audio deleted?)"})
+                continue
+            got, run = self.segment(path, seg["start_offset_s"], seg["track"], book)
+            lines += got
+            runs.append(run)
+        return lines, runs, book