webinar-transcriber 1.3.0__py3-none-any.whl

webinar_transcriber/__init__.py

@@ -0,0 +1,27 @@
+"""Project metadata for webinar-transcriber."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+__all__ = ["__version__", "get_version"]
+
+try:
+    from webinar_transcriber import _version
+except ModuleNotFoundError:  # pragma: no cover
+    _source_version: str | None = None
+else:
+    _source_version = _version.__version__
+
+
+def get_version() -> str:
+    """Return the generated source version or installed package version."""
+    if _source_version is not None:
+        return _source_version
+    try:
+        return version("webinar-transcriber")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+__version__ = get_version()

webinar_transcriber/__main__.py

@@ -0,0 +1,8 @@
+"""Module entry point for `python -m webinar_transcriber`."""
+
+from __future__ import annotations
+
+from webinar_transcriber.cli import main
+
+if __name__ == "__main__":
+    main()

webinar_transcriber/_env.py

@@ -0,0 +1,56 @@
+"""Environment-variable accessors and optional-dependency loaders."""
+
+from __future__ import annotations
+
+import importlib
+import os
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from types import ModuleType
+
+LLM_PROVIDER_ENV = "LLM_PROVIDER"
+TQDM_DISABLE_ENV = "TQDM_DISABLE"
+WEBINAR_DIARIZATION_CACHE_DIR_ENV = "WEBINAR_DIARIZATION_CACHE_DIR"
+
+
+def load_sherpa_onnx() -> ModuleType | None:
+    """Return the imported sherpa-onnx module, or None when the optional wheel is absent.
+
+    Shared by speech-region detection and speaker diarization, which both depend on sherpa-onnx.
+
+    Returns:
+        ModuleType | None: The sherpa-onnx module, or None if it is not installed.
+    """
+    try:
+        return importlib.import_module("sherpa_onnx")
+    except ImportError:  # pragma: no cover - optional wheel/import boundary
+        return None
+
+
+def llm_provider_name() -> str:
+    """Return the configured LLM provider name."""
+    return os.environ.get(LLM_PROVIDER_ENV, "openai").strip().casefold()
+
+
+def diarization_cache_dir() -> Path | None:
+    """Return the configured diarization cache directory, if any."""
+    value = os.environ.get(WEBINAR_DIARIZATION_CACHE_DIR_ENV)
+    return Path(value).expanduser() if value else None
+
+
+@contextmanager
+def temporary_environment_variable(name: str, value: str) -> Iterator[None]:
+    """Temporarily set one environment variable."""
+    previous = os.environ.get(name)
+    os.environ[name] = value
+    try:
+        yield
+    finally:
+        if previous is None:
+            os.environ.pop(name, None)
+        else:
+            os.environ[name] = previous

webinar_transcriber/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.3.0'
+__version_tuple__ = version_tuple = (1, 3, 0)
+
+__commit_id__ = commit_id = None

webinar_transcriber/asr/__init__.py

@@ -0,0 +1,22 @@
+"""ASR adapter built on top of the whisper.cpp C API."""
+
+from __future__ import annotations
+
+from webinar_transcriber.asr.config import (
+    ASR_BACKEND_NAME,
+    WHISPER_CPP_MODEL_EXAMPLE,
+    WHISPER_CPP_MODEL_FILENAME,
+    default_asr_threads,
+)
+from webinar_transcriber.asr.transcriber import AsrProcessingError, WhisperCppTranscriber
+from webinar_transcriber.asr.windows import plan_inference_windows
+
+__all__ = [
+    "ASR_BACKEND_NAME",
+    "WHISPER_CPP_MODEL_EXAMPLE",
+    "WHISPER_CPP_MODEL_FILENAME",
+    "AsrProcessingError",
+    "WhisperCppTranscriber",
+    "default_asr_threads",
+    "plan_inference_windows",
+]

webinar_transcriber/asr/carryover.py

@@ -0,0 +1,21 @@
+"""Prompt-carryover helpers for adjacent whisper inference windows."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from webinar_transcriber.asr.config import CARRYOVER_MAX_CHARS
+
+if TYPE_CHECKING:
+    from webinar_transcriber.models import DecodedWindow
+
+_CARRYOVER_WHITESPACE = re.compile(r"\s+")
+
+
+def build_prompt_carryover(decoded_window: DecodedWindow) -> str:
+    """Return a bounded prompt suffix for the next window; empty when the text is empty."""
+    cleaned = _CARRYOVER_WHITESPACE.sub(" ", decoded_window.text.strip())
+    if len(cleaned) <= CARRYOVER_MAX_CHARS:
+        return cleaned
+    return cleaned[-CARRYOVER_MAX_CHARS:].lstrip()

webinar_transcriber/asr/config.py

@@ -0,0 +1,20 @@
+"""ASR configuration, defaults, and host-capability helpers."""
+
+from __future__ import annotations
+
+import os
+
+ASR_BACKEND_NAME = "whisper.cpp"
+WHISPER_CPP_MODEL_FILENAME = "large-v3-turbo"
+WHISPER_CPP_MODEL_EXAMPLE = "models/whisper-cpp/ggml-large-v3-turbo.bin"
+CARRYOVER_MAX_CHARS = 300
+WHISPER_ENTROPY_THOLD = 2.4
+WHISPER_LOGPROB_THOLD = -1.0
+WHISPER_NO_SPEECH_THOLD = 0.6
+WHISPER_TEMPERATURE_INC = 0.2
+DEFAULT_MAX_ASR_THREADS = 8
+
+
+def default_asr_threads() -> int:
+    """Return the preferred default whisper.cpp thread count for this host."""
+    return min(max(1, os.cpu_count() or 4), DEFAULT_MAX_ASR_THREADS)

webinar_transcriber/asr/transcriber.py

@@ -0,0 +1,362 @@
+"""ASR adapter built on top of pywhispercpp."""
+
+from __future__ import annotations
+
+import importlib
+import io
+import os
+import re
+import sys
+from contextlib import contextmanager, redirect_stderr
+from dataclasses import replace
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Self
+
+import numpy as np
+
+from webinar_transcriber._env import TQDM_DISABLE_ENV, temporary_environment_variable
+from webinar_transcriber.asr.carryover import build_prompt_carryover
+from webinar_transcriber.asr.config import (
+    WHISPER_CPP_MODEL_EXAMPLE,
+    WHISPER_CPP_MODEL_FILENAME,
+    WHISPER_ENTROPY_THOLD,
+    WHISPER_LOGPROB_THOLD,
+    WHISPER_NO_SPEECH_THOLD,
+    WHISPER_TEMPERATURE_INC,
+)
+from webinar_transcriber.models import DecodedWindow, TranscriptSegment
+from webinar_transcriber.normalized_audio import sample_index_for_time
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator
+    from types import TracebackType
+
+    from pywhispercpp.model import Model
+
+    from webinar_transcriber.models import InferenceWindow
+
+GPU_BACKEND_PATTERN = re.compile(r"(?i)\b(metal|mtl|cuda)\b[^|]*?(?:=|:)\s*(?:1|true)")
+_WHISPER_TICKS_PER_SECOND = 100.0
+
+
+def _missing_model_error_message(model_path: Path) -> str:
+    model_path_text = str(model_path)
+    example_path = WHISPER_CPP_MODEL_EXAMPLE
+    location_hint = f"Download a whisper.cpp model there, or use --asr-model {example_path}."
+    return (
+        f"whisper.cpp model file does not exist: {model_path_text}. "
+        f"{location_hint} See README.md for model setup details."
+    )
+
+
+def _model_prepare_error_message(model_name: str) -> str:
+    return (
+        f"Could not prepare whisper.cpp model '{model_name}'. "
+        "pywhispercpp accepts model identifiers such as 'large-v3-turbo' or local ggml model "
+        f"paths such as {WHISPER_CPP_MODEL_EXAMPLE}."
+    )
+
+
+def _model_cls() -> type[Model]:
+    return importlib.import_module("pywhispercpp.model").Model
+
+
+def _looks_like_model_path(model_name: str) -> bool:
+    model_path = Path(model_name).expanduser()
+    return model_path.suffix == ".bin" or model_path.parent != Path()
+
+
+@contextmanager
+def _disable_tqdm_progress() -> Iterator[None]:
+    """Suppress pywhispercpp download progress while constructing a model."""
+    # pywhispercpp does not expose a per-call progress flag for model downloads;
+    # tqdm reads TQDM_DISABLE when the progress bar is created.
+    with temporary_environment_variable(TQDM_DISABLE_ENV, "1"), redirect_stderr(io.StringIO()):
+        yield
+
+
+@contextmanager
+def _redirect_native_output(log_path: Path | None) -> Iterator[None]:
+    if log_path is None:
+        yield
+        return
+
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    sys.stdout.flush()
+    sys.stderr.flush()
+    with log_path.open("a", encoding="utf-8") as log_file:
+        saved_fds = _duplicated_output_fds()
+        try:
+            for fd, _saved_fd in saved_fds:
+                os.dup2(log_file.fileno(), fd)
+            yield
+        finally:
+            sys.stdout.flush()
+            sys.stderr.flush()
+            for fd, saved_fd in saved_fds:
+                os.dup2(saved_fd, fd)
+                os.close(saved_fd)
+
+
+def _duplicated_output_fds() -> list[tuple[int, int]]:
+    saved_fds: list[tuple[int, int]] = []
+    for fd in _output_fds():
+        try:
+            saved_fds.append((fd, os.dup(fd)))
+        except OSError:  # pragma: no cover - defensive for invalid inherited descriptors
+            continue
+    return saved_fds
+
+
+def _output_fds() -> list[int]:
+    fds: list[int] = [1, 2]
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            fd = stream.fileno()
+        except (  # pragma: no cover - defensive for streams without OS file descriptors
+            AttributeError,
+            OSError,
+            io.UnsupportedOperation,
+        ):
+            continue
+        if fd not in fds:
+            fds.append(fd)
+    return fds
+
+
+class AsrProcessingError(RuntimeError):
+    """Raised when the whisper.cpp ASR adapter cannot prepare or run."""
+
+
+class WhisperCppTranscriber:
+    """ASR implementation using pywhispercpp."""
+
+    def __init__(
+        self,
+        model_name: str | None = None,
+        *,
+        threads: int,
+        language: str | None = None,
+        log_path: Path | None = None,
+    ) -> None:
+        """Initialize the whisper.cpp transcriber wrapper."""
+        self._model_name = model_name or WHISPER_CPP_MODEL_FILENAME
+        self._threads = threads
+        self._language = language.strip() if language else None
+        self._log_path = log_path
+        self._model: Model | None = None
+
+    @property
+    def model_name(self) -> str:
+        """Return the configured model identifier or explicit local path."""
+        return self._model_name
+
+    @property
+    def device_name(self) -> str:
+        """Return the detected runtime backend name."""
+        if (system_info := self.system_info) is None:
+            return "auto"
+        return device_name_from_system_info(system_info)
+
+    def __str__(self) -> str:
+        """Return the model and runtime device description."""
+        return f"{self.model_name} | {self.device_name}"
+
+    @property
+    def system_info(self) -> str | None:
+        """Return the whisper.cpp runtime system info string when available."""
+        if self._model is None:
+            return None
+        return self._model.system_info()
+
+    def __enter__(self) -> Self:
+        """Return the transcriber as a context manager."""
+        return self
+
+    def set_log_path(self, log_path: Path) -> None:
+        """Set the whisper.cpp native log destination for future model loads."""
+        self._log_path = log_path
+
+    def prepare_model(self) -> None:
+        """Resolve the model and initialize one pywhispercpp model instance.
+
+        Raises:
+            AsrProcessingError: If model resolution or model creation fails.
+        """
+        self._model_name = self._resolve_model_name()
+        self.close()
+        model_kwargs: dict[str, Any] = {
+            "n_threads": self._threads,
+            "print_realtime": False,
+            "print_progress": False,
+            "no_context": True,
+            "split_on_word": False,
+            "entropy_thold": WHISPER_ENTROPY_THOLD,
+            "logprob_thold": WHISPER_LOGPROB_THOLD,
+            "no_speech_thold": WHISPER_NO_SPEECH_THOLD,
+            "temperature_inc": WHISPER_TEMPERATURE_INC,
+        }
+        try:
+            with _redirect_native_output(self._log_path), _disable_tqdm_progress():
+                model = _model_cls()(self._model_name, **model_kwargs)
+        except Exception as ex:
+            raise AsrProcessingError(_model_prepare_error_message(self._model_name)) from ex
+        # pywhispercpp keeps the native whisper context in Model._ctx and leaves it None when
+        # initialization failed without raising. A missing attribute (future pywhispercpp
+        # versions) is treated as healthy; only a present-but-None context is a failed init.
+        if getattr(model, "_ctx", "missing") is None:
+            raise AsrProcessingError(_model_prepare_error_message(self._model_name))
+        self._model = model
+
+    def transcribe_inference_windows(
+        self,
+        audio_samples: np.ndarray,
+        windows: list[InferenceWindow],
+        *,
+        progress_callback: Callable[[int, int], None] | None = None,
+        warning_callback: Callable[[str], None] | None = None,
+    ) -> list[DecodedWindow]:
+        """Decode ordered inference windows into transcript segments.
+
+        Returns:
+            list[DecodedWindow]: The decoded windows in deterministic order.
+        """
+        model = self._ensure_model()
+        ordered_windows = sorted(
+            windows, key=lambda item: (item.start_sec, item.end_sec, item.region_index, item.id)
+        )
+        forced_language = self._language
+        language_hint: str | None = forced_language
+        carryover_prompt = ""
+        decoded_windows: list[DecodedWindow] = []
+        decoded_segment_count = 0
+        previous_region_index: int | None = None
+
+        for window_index, window in enumerate(ordered_windows, start=1):
+            if forced_language is None and previous_region_index != window.region_index:
+                language_hint = None
+            decoded_window = self._transcribe_window(
+                model,
+                audio_samples,
+                window,
+                prompt=carryover_prompt,
+                language_hint=language_hint,
+                warning_callback=warning_callback,
+            )
+            decoded_windows.append(replace(decoded_window, input_prompt=carryover_prompt or None))
+            decoded_segment_count += len(decoded_window.segments)
+            next_carryover = build_prompt_carryover(decoded_window)
+            if forced_language is None:
+                language_hint = decoded_window.detected_language
+            previous_region_index = window.region_index
+            carryover_prompt = next_carryover
+            if progress_callback is not None:
+                progress_callback(window_index, decoded_segment_count)
+        return decoded_windows
+
+    def close(self) -> None:
+        """Release any active pywhispercpp model resources."""
+        if self._model is None:
+            return
+        with _redirect_native_output(self._log_path):
+            # pywhispercpp exposes native cleanup through Model.__del__ rather than a
+            # public close/free method. Dropping the adapter's reference runs that
+            # destructor immediately on CPython unless another reference is held.
+            self._model = None
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the transcriber when leaving a context manager block."""
+        self.close()
+
+    def _ensure_model(self) -> Model:
+        if self._model is None:
+            self.prepare_model()
+        if self._model is None:
+            raise AsrProcessingError(
+                "pywhispercpp model was not initialized during model preparation."
+            )
+        return self._model
+
+    def _resolve_model_name(self) -> str:
+        if not _looks_like_model_path(self._model_name):
+            return self._model_name
+        configured_model_path = Path(self._model_name).expanduser()
+        if not configured_model_path.exists():
+            raise AsrProcessingError(_missing_model_error_message(configured_model_path))
+        return str(configured_model_path)
+
+    def _transcribe_window(
+        self,
+        model: Model,
+        audio_samples: np.ndarray,
+        window: InferenceWindow,
+        *,
+        prompt: str,
+        language_hint: str | None,
+        warning_callback: Callable[[str], None] | None,
+    ) -> DecodedWindow:
+        start_index = sample_index_for_time(window.start_sec)
+        end_index = min(len(audio_samples), sample_index_for_time(window.end_sec))
+        window_samples = np.ascontiguousarray(
+            audio_samples[start_index:end_index], dtype=np.float32
+        )
+        if window_samples.size == 0:
+            return DecodedWindow(window=window, detected_language=language_hint)
+
+        detected_language = language_hint
+        if detected_language is None:
+            try:
+                # pywhispercpp returns (("ru", 0.99), {"ru": 0.99, ...}).
+                detected_language = model.auto_detect_language(
+                    window_samples, n_threads=self._threads
+                )[0][0]
+            except (RuntimeError, ValueError, IndexError):
+                if warning_callback is not None:
+                    warning_callback(
+                        f"whisper.cpp language detection failed for {window.id}; "
+                        "transcribing without an explicit language hint."
+                    )
+
+        transcribe_kwargs: dict[str, str] = {}
+        if prompt:
+            transcribe_kwargs["initial_prompt"] = prompt
+        if detected_language is not None:
+            transcribe_kwargs["language"] = detected_language
+        try:
+            # ty can't match the dynamically built **transcribe_kwargs to transcribe()'s typed
+            # parameters; the call is valid at runtime and the return type still infers.
+            raw_segments = model.transcribe(window_samples, **transcribe_kwargs)  # type: ignore
+        except Exception as ex:
+            raise AsrProcessingError(f"whisper.cpp inference failed for {window.id}.") from ex
+
+        segments: list[TranscriptSegment] = []
+        for segment_index, raw_segment in enumerate(raw_segments):
+            seg_start = window.start_sec + (float(raw_segment.t0) / _WHISPER_TICKS_PER_SECOND)
+            seg_end = window.start_sec + (float(raw_segment.t1) / _WHISPER_TICKS_PER_SECOND)
+            segments.append(
+                TranscriptSegment(
+                    id=f"{window.id}-segment-{segment_index + 1}",
+                    text=str(raw_segment.text).strip(),
+                    start_sec=max(window.start_sec, seg_start),
+                    end_sec=min(window.end_sec, max(seg_start, seg_end)),
+                )
+            )
+        return DecodedWindow(
+            window=window,
+            text=" ".join(segment.text for segment in segments if segment.text).strip(),
+            segments=segments,
+            detected_language=detected_language,
+        )
+
+
+def device_name_from_system_info(system_info: str) -> str:
+    """Return a user-facing ASR device name from pywhispercpp system info."""
+    if match := GPU_BACKEND_PATTERN.search(system_info):
+        backend_name = match.group(1).lower()
+        return "metal" if backend_name == "mtl" else backend_name
+    return "cpu"

webinar_transcriber/asr/windows.py

@@ -0,0 +1,43 @@
+"""Whisper inference-window planning over detected speech regions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from webinar_transcriber.models import InferenceWindow
+
+if TYPE_CHECKING:
+    from webinar_transcriber.models import SpeechRegion
+
+INFERENCE_WINDOW_DURATION_SEC = 28.0
+INFERENCE_WINDOW_OVERLAP_SEC = 2.0
+
+
+def plan_inference_windows(speech_regions: list[SpeechRegion]) -> list[InferenceWindow]:
+    """Plan bounded Whisper inference windows from speech regions.
+
+    Returns:
+        list[InferenceWindow]: Ordered windows with overlap inside long regions.
+    """
+    windows: list[InferenceWindow] = []
+
+    for region_index, region in enumerate(speech_regions):
+        if region.duration_sec <= 0:
+            continue
+
+        window_start_sec = region.start_sec
+        while window_start_sec < region.end_sec:
+            window_end_sec = min(region.end_sec, window_start_sec + INFERENCE_WINDOW_DURATION_SEC)
+            windows.append(
+                InferenceWindow(
+                    id=f"window-{len(windows) + 1}",
+                    region_index=region_index,
+                    start_sec=window_start_sec,
+                    end_sec=window_end_sec,
+                )
+            )
+            if window_end_sec >= region.end_sec:
+                break
+            window_start_sec = max(window_start_sec, window_end_sec - INFERENCE_WINDOW_OVERLAP_SEC)
+
+    return windows

webinar_transcriber/assets/__init__.py

@@ -0,0 +1 @@
+"""Packaged runtime model assets."""