txtify: Instructions file for Claude Code

Txtify — agent guide

FastAPI web app that transcribes/translates audio & video: YouTube URL or upload → Whisper via stable-ts → optional DeepL translation → export as txt/srt/vtt/sbv/pdf. Single Docker container on port 8011, Jinja2 templates + vanilla JS frontend, SQLite for job state. Deployed from Docker Hub lkmeta/txtify.

Architecture (read this before touching job flow)

• src/main.py — all HTTP endpoints. POST /transcribe inserts a DB row (the job id), then handle_transcription spawns a detached worker subprocess and stores its OS pid in the same row. The frontend polls GET /status?pid=<job id> — the query param is named pid for historical reasons but it is the job id, not the OS pid. Keep it that way; the OS pid (row column 12) is only for cancellation/kill.
• src/utils.py — media download/upload handling, worker spawn, format converters (srt/vtt/sbv/pdf). MAX_UPLOAD_SIZE_MB / MAX_VIDEO_DURATION live here — when changing them, update the copy in templates/index.html and templates/faq.html too.
• src/transcribe_process.py — worker entrypoint; receives the job id as argv[1]. Never look up "the latest row" — that reintroduces the concurrency race fixed in #15.
• src/models.py — stable-ts transcription + DeepL translation. DeepL may merge/split lines; save_final_transcription aligns best-effort and must never raise on count mismatch.
• src/db.py — per-operation SQLite connections with WAL (async handlers + worker subprocesses share the file). Don't add a module-level shared connection.
• GET /history renders the read-only dashboard of past jobs (db.list_jobs, template history.html + static/history.js for client-side sort/filter/paginate). POST /history/delete and POST /history/clear remove a job's files + DB row (both refuse in-flight jobs). All three 404 when ENABLE_HISTORY=False (default True) — the page lists every job by id and there's no auth.
• src/status.py — single source of truth for job status strings and the terminal-state guard. The status values are a contract: the frontend (static/scripts.js) branches on the exact strings via /status's phase (=== 'Completed successfully!', === 'Canceled', .includes('Error'), .startsWith('Error:')), and existing DB rows store them — change a VALUE only with a matching frontend change + migration. Use the constants/predicates (PROCESSING, CANCELED, error(), is_locked(), NOT_LOCKED_SQL), never hardcode a status string or the != 'Canceled' AND NOT LIKE '%Error%' guard. test_status.py asserts is_locked (Python) and NOT_LOCKED_SQL (SQLite) agree on every status.
• Job outputs live in output/<job id>/; output/ is gitignored and dockerignored — media, transcripts, and .db files must never be committed or baked into the image.