transcripy 1.0.0__tar.gz

transcripy-1.0.0/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/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,103 @@
+# 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/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "transcripy"
+version = "1.0.0"
+description = "Local transcription of voicebot calls and phone recordings into timed speaker turns."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Bartosz Niewolski" }]
+keywords = [
+    "transcription",
+    "whisper",
+    "faster-whisper",
+    "diarization",
+    "voicebot",
+    "call-center",
+    "speech-to-text",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["faster-whisper>=1.2.1,<2"]
+
+[project.optional-dependencies]
+diarize = ["pyannote.audio>=3.3"]
+server = [
+    "fastapi>=0.104,<1",
+    "uvicorn[standard]>=0.24,<1",
+    "python-multipart>=0.0.6,<1",
+]
+dev = [
+    "pytest>=8",
+    "httpx>=0.27,<0.28",
+    "fastapi>=0.104,<1",
+    "uvicorn[standard]>=0.24,<1",
+    "python-multipart>=0.0.6,<1",
+]
+
+[project.urls]
+Homepage = "https://github.com/niewolski/TranscriPy"
+Repository = "https://github.com/niewolski/TranscriPy"
+Issues = "https://github.com/niewolski/TranscriPy/issues"
+Changelog = "https://github.com/niewolski/TranscriPy/blob/main/CHANGELOG.md"
+
+[project.scripts]
+transcripy = "transcripy.cli:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["transcripy*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+markers = [
+    "integration: tests that need ffmpeg or real audio fixtures",
+]

transcripy-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

transcripy-1.0.0/tests/test_api.py

@@ -0,0 +1,232 @@
+import threading
+import time
+from pathlib import Path
+
+from fastapi.testclient import TestClient
+
+from api.jobs import JobStore
+from main import app
+from transcripy.models import Segment, Transcript
+
+
+class RecordingTranscriber:
+    def __init__(self) -> None:
+        self.source: Path | None = None
+        self.model: str | None = None
+        self.language: str | None = None
+        self.device: str | None = None
+
+    def __call__(
+        self,
+        source: str | Path,
+        *,
+        model: str = "large-v3",
+        language: str | None = None,
+        device: str = "cpu",
+        compute_type: str | None = None,
+        engine: object | None = None,
+        initial_prompt: str | None = None,
+        hotwords: str | None = None,
+        speakers: bool = False,
+        channel_labels=("left", "right"),
+        word_timestamps: bool = True,
+        on_progress=None,
+    ) -> Transcript:
+        self.source = Path(source)
+        assert self.source.is_file()
+        self.model = model
+        self.language = language
+        self.device = device
+        self.initial_prompt = initial_prompt
+        self.hotwords = hotwords
+        self.speakers = speakers
+        self.channel_labels = channel_labels
+        self.word_timestamps = word_timestamps
+        return Transcript.from_segments(
+            [Segment(0.0, 1.5, "hello")],
+            language=language or "en",
+            duration=1.5,
+        )
+
+
+def test_transcribe_upload_returns_json(monkeypatch):
+    recorder = RecordingTranscriber()
+    monkeypatch.setattr("api.routes.transcribe", recorder)
+    client = TestClient(app)
+
+    response = client.post(
+        "/api/v1/transcribe",
+        files={"file": ("call.mp3", b"not-real-audio", "audio/mpeg")},
+        data={"language": "en", "model": "tiny", "device": "cpu"},
+    )
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "text": "hello",
+        "language": "en",
+        "duration": 1.5,
+        "segments": [{"start": 0.0, "end": 1.5, "text": "hello", "speaker": None}],
+        "turns": [{"start": 0.0, "end": 1.5, "text": "hello", "speaker": None}],
+    }
+    assert recorder.model == "tiny"
+    assert recorder.language == "en"
+    assert recorder.device == "cpu"
+    assert recorder.source is not None
+    assert not recorder.source.exists()
+
+
+def test_transcribe_upload_can_return_subtitles(monkeypatch):
+    monkeypatch.setattr("api.routes.transcribe", RecordingTranscriber())
+    client = TestClient(app)
+    upload = {"file": ("film.mp4", b"not-real-video", "video/mp4")}
+
+    srt = client.post("/api/v1/transcribe?format=srt", files=upload)
+    vtt = client.post("/api/v1/transcribe?format=vtt", files=upload)
+    text = client.post("/api/v1/transcribe?format=txt", files=upload)
+
+    assert srt.status_code == 200
+    assert srt.text == "1\n00:00:00,000 --> 00:00:01,500\nhello\n"
+    assert srt.headers["content-type"].startswith("application/x-subrip")
+    assert vtt.text.startswith("WEBVTT\n")
+    assert text.text == "hello"
+
+
+def test_speakers_flag_is_forwarded(monkeypatch):
+    recorder = RecordingTranscriber()
+    monkeypatch.setattr("api.routes.transcribe", recorder)
+    client = TestClient(app)
+
+    response = client.post(
+        "/api/v1/transcribe",
+        files={"file": ("call.wav", b"stereo", "audio/wav")},
+        data={"speakers": "true"},
+    )
+
+    assert response.status_code == 200
+    assert recorder.speakers is True
+
+
+def test_empty_upload_is_rejected(monkeypatch):
+    monkeypatch.setattr("api.routes.transcribe", RecordingTranscriber())
+    client = TestClient(app)
+
+    response = client.post(
+        "/api/v1/transcribe",
+        files={"file": ("call.mp3", b"", "audio/mpeg")},
+    )
+
+    assert response.status_code == 400
+    assert response.json()["detail"] == "file is empty"
+
+
+def test_unknown_format_is_rejected():
+    client = TestClient(app)
+
+    response = client.post(
+        "/api/v1/transcribe?format=pdf",
+        files={"file": ("call.mp3", b"audio", "audio/mpeg")},
+    )
+
+    assert response.status_code == 400
+    assert response.json()["detail"] == "format must be json, txt, srt, or vtt"
+
+
+def test_job_returns_before_transcription_finishes(monkeypatch):
+    release = threading.Event()
+    reported = threading.Event()
+    recorder = RecordingTranscriber()
+
+    def slow(*args, on_progress=None, **kwargs):
+        if on_progress is not None:
+            on_progress(0.4, 2)
+        reported.set()
+        release.wait(2)
+        return recorder(*args, on_progress=on_progress, **kwargs)
+
+    monkeypatch.setattr("api.routes.jobs", JobStore(slow))
+    client = TestClient(app)
+
+    response = client.post(
+        "/api/v1/jobs?format=srt",
+        files={"file": ("film.mp4", b"video", "video/mp4")},
+        data={"language": "en", "model": "tiny", "device": "cpu"},
+    )
+
+    assert response.status_code == 202
+    job_id = response.json()["id"]
+    assert response.json()["status"] == "queued"
+    assert reported.wait(2)
+    running = client.get(f"/api/v1/jobs/{job_id}").json()
+    assert running["status"] == "running"
+    assert running["progress"] == 0.4
+    assert running["segments_done"] == 2
+    assert client.get(f"/api/v1/jobs/{job_id}/result").status_code == 409
+
+    release.set()
+    finished = _wait_for_job(client, job_id)
+
+    assert finished["status"] == "done"
+    assert finished["error"] is None
+    assert finished["progress"] == 1.0
+    assert finished["segments_done"] == 1
+    result = client.get(f"/api/v1/jobs/{job_id}/result")
+    assert result.status_code == 200
+    assert result.text == "1\n00:00:00,000 --> 00:00:01,500\nhello\n"
+    assert recorder.model == "tiny"
+    assert recorder.language == "en"
+    assert recorder.source is not None
+    assert not recorder.source.exists()
+
+
+def test_failed_job_reports_the_error_and_deletes_the_file(monkeypatch):
+    seen: dict[str, Path] = {}
+
+    def fail(source, **kwargs):
+        seen["path"] = Path(source)
+        raise RuntimeError("model missing")
+
+    monkeypatch.setattr("api.routes.jobs", JobStore(fail))
+    client = TestClient(app)
+    created = client.post(
+        "/api/v1/jobs",
+        files={"file": ("call.mp3", b"audio", "audio/mpeg")},
+    )
+    job_id = created.json()["id"]
+    finished = _wait_for_job(client, job_id)
+
+    assert finished["status"] == "failed"
+    assert finished["error"] == "model missing"
+    result = client.get(f"/api/v1/jobs/{job_id}/result")
+    assert result.status_code == 500
+    assert result.json()["detail"] == "model missing"
+    assert not seen["path"].exists()
+
+
+def test_unknown_job_is_not_found():
+    client = TestClient(app)
+
+    assert client.get("/api/v1/jobs/missing").status_code == 404
+    assert client.get("/api/v1/jobs/missing/result").status_code == 404
+
+
+def test_job_rejects_an_empty_file(monkeypatch):
+    monkeypatch.setattr("api.routes.jobs", JobStore(RecordingTranscriber()))
+    client = TestClient(app)
+
+    response = client.post(
+        "/api/v1/jobs",
+        files={"file": ("call.mp3", b"", "audio/mpeg")},
+    )
+
+    assert response.status_code == 400
+    assert response.json()["detail"] == "file is empty"
+
+
+def _wait_for_job(client: TestClient, job_id: str) -> dict:
+    last = {}
+    for _ in range(100):
+        last = client.get(f"/api/v1/jobs/{job_id}").json()
+        if last["status"] in {"done", "failed"}:
+            return last
+        time.sleep(0.01)
+    raise AssertionError(last)