Local web service that turns a video URL into a readable web presentation with summary, detailed notes, key frames, timestamps, full transcript, and PDF export.

uv sync --extra dev
uv run kotomka serve

On macOS, add --extra ocr to enable Apple Vision OCR of slide frames (smarter dedupe of bullet-build slides and OCR-grounded captions); without it the pipeline runs the same minus OCR.

Open http://127.0.0.1:8000.

The service works without external AI keys by using fake providers. For live processing, configure:

• ASSEMBLYAI_API_KEY for speaker-labeled transcription.
• Either OPENAI_API_KEY for the public OpenAI Platform API, or run uv run kotomka codex-login to use the ChatGPT/Codex subscription route for report generation and frame scoring.

The Codex subscription route is not an OpenAI Platform API key. It stores a separate OAuth state under data/codex_subscription_auth.json by default and uses the ChatGPT Codex backend for Responses-style text/vision requests. It does not provide audio transcription; STT remains a separate pluggable provider.

1. yt-dlp downloads the video plus metadata (description, chapters, tags, upload date, language); ffmpeg extracts mono 16 kHz FLAC audio.
2. STT provider returns a normalized speaker-labeled transcript (AssemblyAI requests current speech models with keyterm boosting derived from the video metadata; the raw payload is kept as transcript_raw.json).
3. Candidate frames come from slide-aware plateau detection, scene detection, and gap filling; on macOS with the ocr extra they are OCR-annotated and bullet-build slide sequences collapse to the final slide.
4. The LLM scores frame batches against matching transcript windows, selection guarantees at least one frame per chapter, and the winners are re-captioned at high image detail.
5. The report is generated in one pass for short videos or map-reduced through chapter-aligned structured notes for long ones, with the selected frame images attached. Citations are then snapped to real transcript timestamps.
6. An assessment pass critiques originality, freshness (anchored to the upload date, optionally web-grounded on the OpenAI provider), audience, actionability, and whether the report replaces watching.
7. FastAPI renders HTML and exports a cached PDF.

KOTOMKA_LLM_PROVIDER=auto resolves in this order:

1. codex_subscription if a Codex OAuth auth file exists.
2. openai if OPENAI_API_KEY exists.
3. fake.

KOTOMKA_STT_PROVIDER defaults to fake. Set it to assemblyai for live speaker-labeled transcription, or to whisper for offline transcription with faster-whisper (uv sync --extra whisper; first run downloads model weights; no speaker diarization).

Settings come from .env.local / environment variables with the KOTOMKA_ prefix. Everything has a sensible default; the most useful knobs:

Example .env.local:

ASSEMBLYAI_API_KEY=...
OPENAI_API_KEY=...
KOTOMKA_STT_PROVIDER=assemblyai
KOTOMKA_LLM_PROVIDER=auto
KOTOMKA_ASSESSMENT_WEB_SEARCH=1

uv run pytest

Integration tests use fake providers and do not call external APIs.