transcripy 1.0.0__py3-none-any.whl

transcripy/__init__.py

@@ -0,0 +1,7 @@
+"""Local transcription of voicebot calls and phone recordings."""
+
+from transcripy.models import Segment, Transcript, Turn, Word
+from transcripy.transcribe import DEFAULT_MODEL, transcribe
+
+__all__ = ["DEFAULT_MODEL", "Segment", "Transcript", "Turn", "Word", "transcribe"]
+__version__ = "1.0.0"

transcripy/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m transcripy``."""
+
+from transcripy.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

transcripy/audio.py

@@ -0,0 +1,175 @@
+"""Read a soundtrack from a video or an unusual recording."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+# Formats faster-whisper can open directly through PyAV.
+PASSTHROUGH_SUFFIXES = {".wav", ".mp3", ".m4a", ".flac", ".ogg", ".opus", ".aac"}
+
+
+def prepare_media(
+    source: Path,
+    *,
+    which=shutil.which,
+    runner=subprocess.run,
+) -> tuple[Path, bool]:
+    """Return audio for the recognizer and whether that file is temporary.
+
+    Plain audio is returned unchanged. Video and other containers are converted
+    with ffmpeg to 16 kHz mono WAV. The second value is true when the caller
+    must delete the returned file.
+    """
+    if source.suffix.lower() in PASSTHROUGH_SUFFIXES:
+        return source, False
+
+    executable = which("ffmpeg")
+    if not executable:
+        raise RuntimeError(
+            "ffmpeg is required to read this file. Install ffmpeg and add it to PATH."
+        )
+
+    descriptor, name = tempfile.mkstemp(suffix=".wav")
+    os.close(descriptor)
+    destination = Path(name)
+    try:
+        completed = runner(
+            [
+                executable,
+                "-y",
+                "-i",
+                str(source),
+                "-vn",
+                "-ac",
+                "1",
+                "-ar",
+                "16000",
+                str(destination),
+            ],
+            capture_output=True,
+            check=False,
+        )
+        if completed.returncode != 0:
+            detail = _last_line(getattr(completed, "stderr", b""))
+            message = "ffmpeg could not read the soundtrack"
+            if detail:
+                message = f"{message}: {detail}"
+            raise RuntimeError(message)
+    except Exception:
+        destination.unlink(missing_ok=True)
+        raise
+    return destination, True
+
+
+def split_stereo(
+    source: Path,
+    *,
+    labels: tuple[str, str] = ("left", "right"),
+    which=shutil.which,
+    runner=subprocess.run,
+) -> list[tuple[str, Path]] | None:
+    """Split a stereo recording into two 16 kHz mono files.
+
+    ``labels`` names the first and second channel (for example ``agent`` /
+    ``customer``). Returns nothing when the soundtrack has one channel. Both
+    returned files are temporary and the caller deletes them.
+    """
+    if len(labels) != 2 or not all(label.strip() for label in labels):
+        raise ValueError("labels must be two non-empty channel names")
+
+    ffmpeg = which("ffmpeg")
+    ffprobe = which("ffprobe")
+    if not ffmpeg or not ffprobe:
+        raise RuntimeError(
+            "ffmpeg is required to separate speakers. Install ffmpeg and add it to PATH."
+        )
+
+    probe = runner(
+        [
+            ffprobe,
+            "-v",
+            "error",
+            "-select_streams",
+            "a:0",
+            "-show_entries",
+            "stream=channels",
+            "-of",
+            "csv=p=0",
+            str(source),
+        ],
+        capture_output=True,
+        check=False,
+    )
+    if probe.returncode != 0:
+        detail = _last_line(getattr(probe, "stderr", b""))
+        message = "ffprobe could not read the audio channels"
+        if detail:
+            message = f"{message}: {detail}"
+        raise RuntimeError(message)
+    channels = _channel_count(getattr(probe, "stdout", b""))
+    if channels < 2:
+        return None
+
+    created: list[Path] = []
+    try:
+        for index, speaker in enumerate(labels):
+            descriptor, name = tempfile.mkstemp(suffix=".wav")
+            os.close(descriptor)
+            destination = Path(name)
+            created.append(destination)
+            completed = runner(
+                [
+                    ffmpeg,
+                    "-y",
+                    "-i",
+                    str(source),
+                    "-vn",
+                    "-af",
+                    f"pan=mono|c0=c{index}",
+                    "-ac",
+                    "1",
+                    "-ar",
+                    "16000",
+                    str(destination),
+                ],
+                capture_output=True,
+                check=False,
+            )
+            if completed.returncode != 0:
+                detail = _last_line(getattr(completed, "stderr", b""))
+                message = f"ffmpeg could not extract the {speaker} channel"
+                if detail:
+                    message = f"{message}: {detail}"
+                raise RuntimeError(message)
+    except Exception:
+        for path in created:
+            path.unlink(missing_ok=True)
+        raise
+    return [(labels[0], created[0]), (labels[1], created[1])]
+
+
+def _channel_count(stdout: bytes | str) -> int:
+    if isinstance(stdout, bytes):
+        text = stdout.decode("utf-8", errors="replace")
+    else:
+        text = stdout
+    token = text.strip().splitlines()
+    if not token:
+        return 1
+    try:
+        return int(token[0].strip())
+    except ValueError:
+        return 1
+
+
+def _last_line(stderr: bytes | str) -> str:
+    if isinstance(stderr, bytes):
+        text = stderr.decode("utf-8", errors="replace")
+    else:
+        text = stderr
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    return lines[-1] if lines else ""

transcripy/cli.py

@@ -0,0 +1,173 @@
+"""Command line entry point for one-file transcription."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from transcripy.models import Transcript
+from transcripy.transcribe import DEFAULT_MODEL, transcribe
+
+_FORMATS = ("txt", "srt", "vtt", "json")
+
+
+def main(argv: list[str] | None = None, *, transcriber=transcribe) -> int:
+    """Transcribe one call recording and print it or write it to ``--output``."""
+    parser = argparse.ArgumentParser(
+        prog="transcripy",
+        description=(
+            "Transcribe a voicebot call, phone recording, or meeting soundtrack "
+            "into timed turns with optional speaker labels."
+        ),
+    )
+    parser.add_argument("source", help="audio or video file")
+    parser.add_argument(
+        "-o",
+        "--output",
+        help="file to write; the extension picks txt, srt, vtt, or json",
+    )
+    parser.add_argument("--language", help="ISO language code, for example en")
+    parser.add_argument(
+        "--model",
+        default=DEFAULT_MODEL,
+        help=f"Whisper model name (default: {DEFAULT_MODEL})",
+    )
+    parser.add_argument("--device", default="cpu", help="cpu or cuda")
+    parser.add_argument("--prompt", help="words the recording is likely to contain")
+    parser.add_argument("--hotwords", help="names or phrases to bias recognition toward")
+    parser.add_argument(
+        "--speakers",
+        action="store_true",
+        help="label stereo channels, or separate voices on a mono recording",
+    )
+    parser.add_argument(
+        "--channel-labels",
+        default="left,right",
+        help="comma-separated stereo channel names (default: left,right)",
+    )
+    parser.add_argument(
+        "--no-word-timestamps",
+        action="store_true",
+        help="skip per-word timings to speed up transcription a little",
+    )
+    parser.add_argument(
+        "--pause",
+        type=float,
+        default=1.0,
+        help="seconds of silence that start a new utterance",
+    )
+    parser.add_argument(
+        "--format",
+        choices=_FORMATS,
+        help="output format; overrides the extension of --output",
+    )
+    args = parser.parse_args(argv)
+
+    if args.pause < 0:
+        print("pause must be >= 0", file=sys.stderr)
+        return 1
+
+    try:
+        channel_labels = _parse_channel_labels(args.channel_labels)
+    except ValueError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+
+    try:
+        output_format = choose_format(args.output, args.format)
+    except ValueError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+
+    reported = False
+
+    def on_progress(fraction: float, segments_done: int) -> None:
+        nonlocal reported
+        reported = True
+        percent = int(round(min(max(fraction, 0.0), 1.0) * 100))
+        print(
+            f"\r{percent:3d}%  {segments_done} segments",
+            file=sys.stderr,
+            end="",
+            flush=True,
+        )
+
+    try:
+        result = transcriber(
+            args.source,
+            model=args.model,
+            language=args.language,
+            device=args.device,
+            initial_prompt=args.prompt,
+            hotwords=args.hotwords,
+            speakers=args.speakers,
+            channel_labels=channel_labels,
+            word_timestamps=not args.no_word_timestamps,
+            on_progress=on_progress,
+        )
+    except (FileNotFoundError, RuntimeError, ValueError) as exc:
+        if reported:
+            print(file=sys.stderr)
+        print(exc, file=sys.stderr)
+        return 1
+    if reported:
+        print(file=sys.stderr)
+
+    rendered = render(result, output_format, args.pause)
+    if args.output is None:
+        sys.stdout.write(rendered)
+        return 0
+
+    destination = Path(args.output).expanduser()
+    try:
+        destination.write_text(rendered, encoding="utf-8", newline="\n")
+    except OSError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    return 0
+
+
+def _parse_channel_labels(raw: str) -> tuple[str, str]:
+    parts = [part.strip() for part in raw.split(",")]
+    if len(parts) != 2 or not all(parts):
+        raise ValueError(
+            "channel labels must be two non-empty names, for example agent,customer"
+        )
+    return parts[0], parts[1]
+
+
+def choose_format(output: str | None, explicit: str | None) -> str:
+    """Pick txt, srt, vtt, or json from a flag or a file name."""
+    if explicit:
+        return explicit
+    if not output:
+        return "txt"
+    suffix = Path(output).suffix.lower().lstrip(".")
+    if suffix in _FORMATS:
+        return suffix
+    if suffix == "":
+        return "txt"
+    raise ValueError(
+        f"cannot tell the format from .{suffix}; pass --format txt, srt, vtt, or json"
+    )
+
+
+def render(result: Transcript, output_format: str, pause: float = 1.0) -> str:
+    """Turn a transcript into the text that should be stored."""
+    if output_format == "txt":
+        if not result.text or result.text.endswith("\n"):
+            return result.text
+        return result.text + "\n"
+    if output_format == "srt":
+        return result.to_srt()
+    if output_format == "vtt":
+        return result.to_vtt()
+    if output_format == "json":
+        return json.dumps(result.to_dict(pause=pause), ensure_ascii=False, indent=2) + "\n"
+    raise ValueError(f"unsupported format: {output_format}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

transcripy/diarize.py

@@ -0,0 +1,99 @@
+"""Label who is speaking on a single mixed recording."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from transcripy.models import Segment, Transcript
+
+_MODEL = "pyannote/speaker-diarization-3.1"
+
+
+@dataclass(frozen=True)
+class SpeakerSpan:
+    """One stretch of audio assigned to a speaker by a diarizer."""
+
+    start: float
+    end: float
+    speaker: str
+
+    def __post_init__(self) -> None:
+        if self.start < 0:
+            raise ValueError("speaker span start must be >= 0")
+        if self.end < self.start:
+            raise ValueError("speaker span end is before start")
+        if not self.speaker.strip():
+            raise ValueError("speaker is required")
+
+
+def assign_speakers(transcript: Transcript, spans: list[SpeakerSpan]) -> Transcript:
+    """Give each segment the speaker it overlaps the most."""
+    labeled = [
+        Segment(
+            start=segment.start,
+            end=segment.end,
+            text=segment.text,
+            speaker=_best_speaker(segment, spans),
+            words=segment.words,
+        )
+        for segment in transcript.segments
+    ]
+    return Transcript.from_segments(
+        labeled,
+        language=transcript.language,
+        duration=transcript.duration,
+    )
+
+
+def pyannote_speakers(source: Path) -> list[SpeakerSpan]:
+    """Diarize a mono file with pyannote.
+
+    The model is downloaded on first use. Set ``HF_TOKEN`` to a Hugging Face
+    token that can read ``pyannote/speaker-diarization-3.1``.
+    """
+    token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+    if not token:
+        raise RuntimeError(
+            "Set HF_TOKEN to label speakers on a mono recording. "
+            "The token must be allowed to download pyannote/speaker-diarization-3.1."
+        )
+    try:
+        pipeline = _load_pyannote(token)
+    except ImportError as exc:
+        raise RuntimeError(
+            "pyannote.audio is required to label speakers on a mono recording. "
+            "Install it with: pip install 'transcripy[diarize]'"
+        ) from exc
+    annotation = pipeline(str(source))
+    spans: list[SpeakerSpan] = []
+    for turn, _, speaker in annotation.itertracks(yield_label=True):
+        spans.append(
+            SpeakerSpan(start=float(turn.start), end=float(turn.end), speaker=str(speaker))
+        )
+    return spans
+
+
+def _best_speaker(segment: Segment, spans: list[SpeakerSpan]) -> str | None:
+    best_name: str | None = None
+    best_overlap = 0.0
+    for span in spans:
+        amount = _overlap(segment.start, segment.end, span.start, span.end)
+        if amount > best_overlap:
+            best_overlap = amount
+            best_name = span.speaker
+    return best_name
+
+
+def _overlap(start: float, end: float, other_start: float, other_end: float) -> float:
+    return max(0.0, min(end, other_end) - max(start, other_start))
+
+
+def _load_pyannote(token: str):
+    from pyannote.audio import Pipeline
+
+    try:
+        return Pipeline.from_pretrained(_MODEL, token=token)
+    except TypeError:
+        return Pipeline.from_pretrained(_MODEL, use_auth_token=token)

transcripy/models.py

@@ -0,0 +1,220 @@
+"""Transcript types returned by the library."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Word:
+    """One timed word inside a segment."""
+
+    start: float
+    end: float
+    word: str
+    probability: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.start < 0:
+            raise ValueError("word start must be >= 0")
+        if self.end < self.start:
+            raise ValueError("word end is before start")
+        if not self.word.strip():
+            raise ValueError("word text is required")
+
+
+@dataclass(frozen=True)
+class Segment:
+    """One stretch of speech with start and end in seconds."""
+
+    start: float
+    end: float
+    text: str
+    speaker: str | None = None
+    words: tuple[Word, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.start < 0:
+            raise ValueError("segment start must be >= 0")
+        if self.end < self.start:
+            raise ValueError("segment end is before start")
+
+
+@dataclass(frozen=True)
+class Turn:
+    """Consecutive segments spoken close together."""
+
+    start: float
+    end: float
+    text: str
+    speaker: str | None = None
+
+
+@dataclass(frozen=True)
+class Transcript:
+    """Full transcription of one recording."""
+
+    text: str
+    language: str
+    duration: float
+    segments: tuple[Segment, ...]
+
+    @classmethod
+    def from_segments(
+        cls,
+        segments: list[Segment] | tuple[Segment, ...],
+        *,
+        language: str,
+        duration: float | None = None,
+    ) -> Transcript:
+        if not language or not language.strip():
+            raise ValueError("language is required")
+
+        cleaned: list[Segment] = []
+        for segment in segments:
+            text = segment.text.strip()
+            if not text:
+                continue
+            words = tuple(
+                Word(
+                    start=word.start,
+                    end=word.end,
+                    word=word.word.strip(),
+                    probability=word.probability,
+                )
+                for word in segment.words
+                if word.word.strip()
+            )
+            cleaned.append(
+                Segment(
+                    start=segment.start,
+                    end=segment.end,
+                    text=text,
+                    speaker=segment.speaker,
+                    words=words,
+                )
+            )
+
+        if duration is None:
+            duration = cleaned[-1].end if cleaned else 0.0
+        if duration < 0:
+            raise ValueError("duration must be >= 0")
+
+        full_text = " ".join(segment.text for segment in cleaned)
+        return cls(
+            text=full_text,
+            language=language.strip(),
+            duration=float(duration),
+            segments=tuple(cleaned),
+        )
+
+    def turns(self, pause: float = 1.0) -> tuple[Turn, ...]:
+        """Group segments into utterances separated by at least ``pause`` seconds."""
+        if pause < 0:
+            raise ValueError("pause must be >= 0")
+
+        grouped: list[list[Segment]] = []
+        for segment in self.segments:
+            previous = grouped[-1][-1] if grouped else None
+            gap = segment.start - previous.end if previous else pause
+            speaker_changed = previous is not None and segment.speaker != previous.speaker
+            if gap >= pause or speaker_changed:
+                grouped.append([])
+            grouped[-1].append(segment)
+
+        return tuple(
+            Turn(
+                start=segments[0].start,
+                end=segments[-1].end,
+                text=" ".join(segment.text for segment in segments),
+                speaker=segments[0].speaker,
+            )
+            for segments in grouped
+        )
+
+    def to_dict(self, *, pause: float = 1.0) -> dict[str, object]:
+        return {
+            "text": self.text,
+            "language": self.language,
+            "duration": self.duration,
+            "segments": [
+                {
+                    "start": segment.start,
+                    "end": segment.end,
+                    "text": segment.text,
+                    "speaker": segment.speaker,
+                    "words": [
+                        {
+                            "start": word.start,
+                            "end": word.end,
+                            "word": word.word,
+                            "probability": word.probability,
+                        }
+                        for word in segment.words
+                    ],
+                }
+                for segment in self.segments
+            ],
+            "turns": [
+                {
+                    "start": turn.start,
+                    "end": turn.end,
+                    "text": turn.text,
+                    "speaker": turn.speaker,
+                }
+                for turn in self.turns(pause)
+            ],
+        }
+
+    def to_srt(self) -> str:
+        blocks = [
+            "\n".join(
+                [
+                    str(index),
+                    (
+                        f"{format_timestamp(segment.start)} --> "
+                        f"{format_timestamp(segment.end)}"
+                    ),
+                    _cue_text(segment),
+                ]
+            )
+            for index, segment in enumerate(self.segments, start=1)
+        ]
+        if not blocks:
+            return ""
+        return "\n\n".join(blocks) + "\n"
+
+    def to_vtt(self) -> str:
+        cues = [
+            "\n".join(
+                [
+                    (
+                        f"{format_timestamp(segment.start, decimal_separator='.')} --> "
+                        f"{format_timestamp(segment.end, decimal_separator='.')}"
+                    ),
+                    _cue_text(segment),
+                ]
+            )
+            for segment in self.segments
+        ]
+        body = "\n\n".join(cues)
+        if body:
+            return f"WEBVTT\n\n{body}\n"
+        return "WEBVTT\n"
+
+
+def _cue_text(segment: Segment) -> str:
+    if segment.speaker:
+        return f"[{segment.speaker}] {segment.text}"
+    return segment.text
+
+
+def format_timestamp(seconds: float, *, decimal_separator: str = ",") -> str:
+    """Format seconds as an SRT or VTT timestamp."""
+    if seconds < 0:
+        seconds = 0.0
+    total_milliseconds = int(round(float(seconds) * 1000))
+    hours, remainder = divmod(total_milliseconds, 3_600_000)
+    minutes, remainder = divmod(remainder, 60_000)
+    secs, milliseconds = divmod(remainder, 1000)
+    return f"{hours:02d}:{minutes:02d}:{secs:02d}{decimal_separator}{milliseconds:03d}"

transcripy/transcribe.py

@@ -0,0 +1,281 @@
+"""Transcribe one recording into a Transcript."""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+from collections.abc import Callable, Sequence
+from typing import Any, Protocol
+
+from transcripy.audio import prepare_media, split_stereo
+from transcripy.diarize import SpeakerSpan, assign_speakers, pyannote_speakers
+from transcripy.models import Segment, Transcript, Word
+
+Progress = Callable[[float, int], None]
+Diarizer = Callable[[Path], list[SpeakerSpan]]
+DEFAULT_MODEL = "large-v3"
+DEFAULT_CHANNEL_LABELS = ("left", "right")
+
+_models: dict[tuple[str, str, str], Any] = {}
+_models_lock = threading.Lock()
+
+
+class SpeechEngine(Protocol):
+    """Something that can turn one media file into a transcript."""
+
+    def transcribe(
+        self,
+        source: Path,
+        language: str | None = None,
+        *,
+        initial_prompt: str | None = None,
+        hotwords: str | None = None,
+        word_timestamps: bool = True,
+        on_progress: Progress | None = None,
+    ) -> Transcript:
+        """Transcribe ``source`` and return timed text."""
+
+
+def transcribe(
+    source: str | Path,
+    *,
+    model: str = DEFAULT_MODEL,
+    language: str | None = None,
+    device: str = "cpu",
+    compute_type: str | None = None,
+    initial_prompt: str | None = None,
+    hotwords: str | None = None,
+    speakers: bool = False,
+    channel_labels: Sequence[str] = DEFAULT_CHANNEL_LABELS,
+    word_timestamps: bool = True,
+    on_progress: Progress | None = None,
+    engine: SpeechEngine | None = None,
+    diarizer: Diarizer | None = None,
+) -> Transcript:
+    """Transcribe a voicebot call, phone recording, or meeting soundtrack.
+
+    The first call for a given model downloads its weights. Later calls reuse
+    the loaded model. ``language`` is an ISO code such as ``en``; when it is
+    omitted, the model detects the language. ``initial_prompt`` and ``hotwords``
+    bias the recognizer toward names and phrases that are likely to be spoken.
+    ``on_progress`` receives a fraction from 0 to 1 and the number of segments
+    finished so far. ``speakers`` labels a stereo call with ``channel_labels``
+    (default ``left`` / ``right``). On a mono recording it separates the mixed
+    voices. That path needs pyannote and an ``HF_TOKEN``.
+    """
+    path = Path(source).expanduser()
+    if not path.is_file():
+        raise FileNotFoundError(f"media file not found: {path}")
+
+    labels = _normalize_channel_labels(channel_labels)
+
+    if engine is None:
+        engine = FasterWhisperEngine(
+            model_name=model,
+            device=device,
+            compute_type=compute_type or default_compute_type(device),
+        )
+
+    channels: list[tuple[str | None, Path]] = [(None, path)]
+    temporary: list[Path] = []
+    if speakers:
+        split = split_stereo(path, labels=labels)
+        if split:
+            channels = [(speaker, audio) for speaker, audio in split]
+            temporary = [audio for _, audio in split]
+
+    try:
+        parts: list[Transcript] = []
+        finished = 0
+        weight = 1 / len(channels)
+        for index, (speaker, audio) in enumerate(channels):
+            result = engine.transcribe(
+                audio,
+                language=language,
+                initial_prompt=_blank_to_none(initial_prompt),
+                hotwords=_blank_to_none(hotwords),
+                word_timestamps=word_timestamps,
+                on_progress=_scale_progress(on_progress, index * weight, weight, finished),
+            )
+            parts.append(_label(result, speaker))
+            finished += len(result.segments)
+        if len(parts) == 1:
+            result = parts[0]
+            if speakers and channels[0][0] is None:
+                spans = (diarizer or pyannote_speakers)(path)
+                result = assign_speakers(result, spans)
+            return result
+        return _merge(parts)
+    finally:
+        for audio in temporary:
+            audio.unlink(missing_ok=True)
+
+
+def _normalize_channel_labels(channel_labels: Sequence[str]) -> tuple[str, str]:
+    labels = tuple(label.strip() for label in channel_labels)
+    if len(labels) != 2 or not all(labels):
+        raise ValueError("channel_labels must be two non-empty names, for example ('agent', 'customer')")
+    return labels[0], labels[1]
+
+
+def _scale_progress(
+    on_progress: Progress | None,
+    offset: float,
+    weight: float,
+    finished: int,
+) -> Progress | None:
+    if on_progress is None:
+        return None
+
+    def report(fraction: float, count: int) -> None:
+        on_progress(min(offset + fraction * weight, 1.0), finished + count)
+
+    return report
+
+
+def _label(result: Transcript, speaker: str | None) -> Transcript:
+    if speaker is None:
+        return result
+    return Transcript.from_segments(
+        [
+            Segment(
+                start=segment.start,
+                end=segment.end,
+                text=segment.text,
+                speaker=speaker,
+                words=segment.words,
+            )
+            for segment in result.segments
+        ],
+        language=result.language,
+        duration=result.duration,
+    )
+
+
+def _merge(parts: list[Transcript]) -> Transcript:
+    segments = [segment for part in parts for segment in part.segments]
+    segments.sort(key=lambda segment: (segment.start, segment.speaker or ""))
+    return Transcript.from_segments(
+        segments,
+        language=parts[0].language,
+        duration=max(part.duration for part in parts),
+    )
+
+
+def _blank_to_none(value: str | None) -> str | None:
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+def default_compute_type(device: str) -> str:
+    """Pick a quantization that runs on the given device."""
+    if device == "cpu":
+        return "int8"
+    return "float16"
+
+
+class FasterWhisperEngine:
+    """Local transcription through faster-whisper."""
+
+    def __init__(
+        self,
+        model_name: str = DEFAULT_MODEL,
+        device: str = "cpu",
+        compute_type: str = "int8",
+        model: Any | None = None,
+    ) -> None:
+        self._model = model if model is not None else load_model(
+            model_name,
+            device,
+            compute_type,
+        )
+
+    def transcribe(
+        self,
+        source: Path,
+        language: str | None = None,
+        *,
+        initial_prompt: str | None = None,
+        hotwords: str | None = None,
+        word_timestamps: bool = True,
+        on_progress: Progress | None = None,
+    ) -> Transcript:
+        prepared, temporary = prepare_media(source)
+        try:
+            options: dict[str, Any] = {
+                "language": language,
+                "vad_filter": True,
+                "word_timestamps": word_timestamps,
+            }
+            if initial_prompt:
+                options["initial_prompt"] = initial_prompt
+            if hotwords:
+                options["hotwords"] = hotwords
+            segments_iter, info = self._model.transcribe(str(prepared), **options)
+            duration = getattr(info, "duration", None)
+            duration = float(duration) if duration is not None else 0.0
+            segments: list[Segment] = []
+            for index, segment in enumerate(segments_iter, start=1):
+                words = ()
+                if word_timestamps:
+                    raw_words = getattr(segment, "words", None) or ()
+                    words = tuple(
+                        Word(
+                            start=float(word.start),
+                            end=float(word.end),
+                            word=str(word.word),
+                            probability=(
+                                float(word.probability)
+                                if getattr(word, "probability", None) is not None
+                                else None
+                            ),
+                        )
+                        for word in raw_words
+                        if str(getattr(word, "word", "")).strip()
+                    )
+                segments.append(
+                    Segment(
+                        start=segment.start,
+                        end=segment.end,
+                        text=segment.text,
+                        words=words,
+                    )
+                )
+                if on_progress is not None:
+                    fraction = segment.end / duration if duration > 0 else 0.0
+                    on_progress(min(max(fraction, 0.0), 1.0), index)
+            if on_progress is not None:
+                on_progress(1.0, len(segments))
+            detected = language or getattr(info, "language", None) or "unknown"
+            reported_duration = duration if duration > 0 else None
+            return Transcript.from_segments(
+                segments,
+                language=str(detected),
+                duration=reported_duration,
+            )
+        finally:
+            if temporary:
+                prepared.unlink(missing_ok=True)
+
+
+def load_model(model_name: str, device: str, compute_type: str) -> Any:
+    """Load a Whisper model once per name, device, and compute type."""
+    key = (model_name, device, compute_type)
+    with _models_lock:
+        cached = _models.get(key)
+        if cached is None:
+            try:
+                from faster_whisper import WhisperModel
+            except ImportError as exc:
+                raise RuntimeError(
+                    "faster-whisper is required. Install it with: pip install faster-whisper"
+                ) from exc
+            cached = WhisperModel(
+                model_name,
+                device=device,
+                compute_type=compute_type,
+            )
+            _models[key] = cached
+        return cached

transcripy-1.0.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: transcripy
+Version: 1.0.0
+Summary: Local transcription of voicebot calls and phone recordings into timed speaker turns.
+Author: Bartosz Niewolski
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/niewolski/TranscriPy
+Project-URL: Repository, https://github.com/niewolski/TranscriPy
+Project-URL: Issues, https://github.com/niewolski/TranscriPy/issues
+Project-URL: Changelog, https://github.com/niewolski/TranscriPy/blob/main/CHANGELOG.md
+Keywords: transcription,whisper,faster-whisper,diarization,voicebot,call-center,speech-to-text
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: faster-whisper<2,>=1.2.1
+Provides-Extra: diarize
+Requires-Dist: pyannote.audio>=3.3; extra == "diarize"
+Provides-Extra: server
+Requires-Dist: fastapi<1,>=0.104; extra == "server"
+Requires-Dist: uvicorn[standard]<1,>=0.24; extra == "server"
+Requires-Dist: python-multipart<1,>=0.0.6; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx<0.28,>=0.27; extra == "dev"
+Requires-Dist: fastapi<1,>=0.104; extra == "dev"
+Requires-Dist: uvicorn[standard]<1,>=0.24; extra == "dev"
+Requires-Dist: python-multipart<1,>=0.0.6; extra == "dev"
+Dynamic: license-file
+
+# TranscriPy
+
+Local transcription of **voicebot calls and phone recordings** into timed turns with speaker labels. Audio stays on your machine.
+
+```bash
+pip install transcripy
+```
+
+```python
+from transcripy import transcribe
+
+result = transcribe(
+    "call.wav",
+    language="en",
+    speakers=True,
+    channel_labels=("agent", "customer"),
+    hotwords="TranscriPy, Acme",
+    initial_prompt="A voicebot call about the TranscriPy product.",
+)
+
+for turn in result.turns():
+    print(f"[{turn.speaker}] {turn.text}")
+```
+
+```bash
+transcripy call.wav \
+  --language en \
+  --speakers \
+  --channel-labels agent,customer \
+  --hotwords "TranscriPy, Acme" \
+  --prompt "A voicebot call about the TranscriPy product." \
+  -o call.json
+```
+
+## What it is for
+
+- Stereo call recordings where each party has a channel (agent / customer)
+- Mono mixed calls when you install the optional diarization extra
+- Offline / self-hosted pipelines that must not upload audio to a cloud ASR API
+
+The public contract is simple: one media file in, a `Transcript` with `segments`, `turns`, and optional per-word timings out. Export as text, SRT, VTT, or JSON.
+
+## Requirements
+
+- Python 3.10+
+- [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) (installed with the package)
+- [`ffmpeg`](https://ffmpeg.org/) on `PATH` for video containers and stereo channel split
+- Optional NVIDIA CUDA for `--device cuda`
+- Optional Hugging Face token for mono speaker diarization (see below)
+
+## Speakers
+
+**Stereo (recommended for voicebots).** `--speakers` (or `speakers=True`) splits the two channels and labels them with `--channel-labels` / `channel_labels`. Default labels are `left` and `right`.
+
+**Mono.** The same flag runs [pyannote](https://github.com/pyannote/pyannote-audio) and assigns each segment the speaker with the largest time overlap. Overlapping speech and similar voices reduce quality; this is not WhisperX-level alignment.
+
+```bash
+pip install "transcripy[diarize]"
+```
+
+1. Accept the user agreements for [`pyannote/speaker-diarization-3.1`](https://huggingface.co/pyannote/speaker-diarization-3.1) and [`pyannote/segmentation-3.0`](https://huggingface.co/pyannote/segmentation-3.0).
+2. Create a Hugging Face access token.
+3. Export it as `HF_TOKEN` (or `HUGGING_FACE_HUB_TOKEN`).
+
+## Defaults
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| `model` | `large-v3` | Pass a smaller Whisper name (`medium`, `small`, `tiny`) to trade quality for speed |
+| `language` | auto-detect | Prefer an ISO code such as `en` or `pl` for call center audio |
+| `word_timestamps` | on | Disable with `--no-word-timestamps` / `word_timestamps=False` |
+| `device` | `cpu` | Use `cuda` when a GPU is available |
+
+Compared with [WhisperX](https://github.com/m-bain/whisperX): TranscriPy focuses on a small call-recording API and reliable **stereo channel labels**. WhisperX is stronger when you need batched GPU throughput and forced word alignment on mixed mono audio.
+
+## Non-goals (1.0)
+
+- Live / streaming microphone transcription
+- Hosted cloud ASR
+- Production HTTP API (the `api/` folder in this repo is experimental; not shipped in the wheel)
+- High-throughput batched GPU pipelines
+- Subtitle tooling for films as the primary use case
+
+## Install options
+
+```bash
+pip install transcripy              # library + CLI
+pip install "transcripy[diarize]"   # + pyannote for mono speakers
+pip install "transcripy[dev]"       # tests and the experimental server deps
+```
+
+## Development
+
+```bash
+git clone https://github.com/niewolski/TranscriPy.git
+cd TranscriPy
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Model weight notices are in [NOTICE](NOTICE).

transcripy-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+transcripy/__init__.py,sha256=ga2SL74UFhZx8gSsRx3qXv8Al6oPc9xIrcS-hwzNOo0,295
+transcripy/__main__.py,sha256=Xzz0PD_p-VNRGEM60RfVrAU1FKQTPy7s4wklH0b0Q_k,128
+transcripy/audio.py,sha256=0x2cChBPXqEutQU-NThN7H5Y6wmju480yc5vqvYuNf4,5241
+transcripy/cli.py,sha256=FIAOG4LUN8dg4gPUTzwSmcrxJ0klBGn4UvHd4wh7hPQ,5429
+transcripy/diarize.py,sha256=oS6w8n9dVk_fWOy5hamqvXQIFw1Lamo01W2qLHX1m4g,3145
+transcripy/models.py,sha256=vQzD4NigodN1FJ75kq3YVNFT4df3qOgdmsfsB016U7Y,6614
+transcripy/transcribe.py,sha256=vnarLJKYqUO6BrW2dHMLY772Mf1Sr0mWLgBhTa5dAhY,9710
+transcripy-1.0.0.dist-info/licenses/LICENSE,sha256=n9ZWa05VVPUZ1MOHqCoMwqk6U6VW2-ODNRseaOR6Img,1074
+transcripy-1.0.0.dist-info/licenses/NOTICE,sha256=SPQZQbmvl0K40MphlOv64i-CzlAb3ahJBjVODm9nALY,766
+transcripy-1.0.0.dist-info/METADATA,sha256=Zu3VcykNmfqL-XlF05TqfjR2ONOsD2O_R5_STvmkswY,5499
+transcripy-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+transcripy-1.0.0.dist-info/entry_points.txt,sha256=Fr8YsO0kcp8T7z7SKhIafGv2-pG8Kb5y32YSOhs_pIU,51
+transcripy-1.0.0.dist-info/top_level.txt,sha256=SHXg_1ernjC7pJ-XDxJk1RiiSuH4F1zVB2dPbIc6sjw,11
+transcripy-1.0.0.dist-info/RECORD,,

transcripy-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

transcripy-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+transcripy = transcripy.cli:main

transcripy-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bartosz Niewolski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

transcripy-1.0.0.dist-info/licenses/NOTICE

@@ -0,0 +1,15 @@
+TranscriPy
+Copyright (c) 2026 Bartosz Niewolski
+
+This product uses third-party speech models and runtimes:
+
+- OpenAI Whisper model weights, used through faster-whisper / CTranslate2.
+  See https://github.com/openai/whisper and the model cards on Hugging Face.
+- faster-whisper (MIT), https://github.com/SYSTRAN/faster-whisper
+- Optional mono speaker diarization via pyannote.audio and the gated Hugging
+  Face pipelines pyannote/speaker-diarization-3.1 and pyannote/segmentation-3.0.
+  Users must accept those model agreements and set HF_TOKEN before first use.
+  See https://github.com/pyannote/pyannote-audio and the linked model cards.
+
+TranscriPy itself does not redistribute those model weights; they are downloaded
+on first use under each project's own terms.

transcripy-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+transcripy