transcriber

Turn video files into transcript artifacts for LLM, RAG, and agent workflows.

Pipeline

video → ffmpeg (audio extract) → faster-whisper (ASR) → pyannote (diarization, optional) → json / md / txt

Setup

uv sync          # or: pip install -e .

Install ffmpeg and ensure it is on your PATH.

Speaker diarization requires a Hugging Face token (free):

1. Accept the license at https://huggingface.co/pyannote/speaker-diarization-3.1
2. Create a token at https://huggingface.co/settings/tokens
3. cp .env.example .env and set HF_TOKEN=..., or export HF_TOKEN=...

Diarization is optional. Use --no-diarize to transcribe without a token.

Usage

Single file:

python main.py path/to/video.mp4 --output-dir out/

Directory (recursive; mirrors folder structure under --output-dir):

python main.py path/to/videos/ --output-dir out/

Transcription only (skip speaker diarization):

python main.py path/to/videos/ --output-dir out/ --no-diarize

Options

Flag	Description
--model	faster-whisper model size: tiny, base, small, medium, large-v3. Default: base.
--device	cpu, cuda, or auto. Default: auto.
--no-diarize	Skip speaker diarization; label all speech SPEAKER.
--rediarize	Reuse an existing *.json transcript and rerun diarization only (skips Whisper).
--init-context	Write a <video>.context.yaml template next to each video missing one, then exit.

Context sidecars

ASR and diarization do not know who is speaking or what the recording is about. Add a sidecar file named <video>.context.yaml next to any video (or run --init-context to scaffold one):

speakers:
  SPEAKER_00: "Alice"
  SPEAKER_01: "Bob"
notes: |
  One-on-one interview. Alice is the host; Bob is the guest.
  Recorded for internal review.

When present:

• Speaker labels in all outputs are replaced with the mapped names.
• notes is stored in *.json under meta.notes.
• notes is prepended to *.md under a ## Context heading.

Typical workflow: run once without a sidecar to see which SPEAKER_00 / SPEAKER_01 labels pyannote assigns, fill the template, then rerun.

Outputs

For video.mp4 with --output-dir out/:

File	Purpose
out/video.json	Canonical source: segments with start, end, speaker, text, word-level timestamps, and metadata. Best for chunking, citations, or vector DB ingestion.
out/video.md	Speaker turns with [hh:mm:ss–hh:mm:ss] headers. Good as an LLM attachment or for human review.
out/video.txt	Plain Speaker: text lines without timestamps. Simplest format for prompts.