Make Whisper resilient: chunking, retry caps, transcript cache

[JoseBallestas]

Summary

Fixes a chain of related Whisper transcription bugs that prevented /watch from working on anything longer than ~10 min, and adds a transcript cache so re-runs are free.

Discovered while trying to use /watch on a 40-min local lesson video. A single transient Groq 500 turned into a 4-attempt retry storm that burned through Groq's 7200s/hour quota and produced zero transcript. From there it cascaded — turned out the script also re-uploaded the full audio even with --start/--end, the failure-mode message lied to the user about why the transcript was missing, and there was no way to process audio over Groq's 25 MB single-file cap (~52 min).

Five commits, each a self-contained fix:

1. Cap 5xx retries to prevent quota burn — MAX_5XX_RETRIES = 2, symmetric with the existing 429 cap. Each retry re-uploads the audio and counts against the per-hour quota, so 4 attempts of a 40-min file = ~3 hours of "audio" billed and locks the user out of the free tier.
2. Surface the actual failure reason in the report — when Whisper failed for any reason (rate limit, network, parse), the markdown report hardcoded "no API key set, or --no-whisper was used" — neither was true. Now it surfaces the real exception.
3. Extract only the focused window for Whisper — --start/--end previously constrained frame extraction but Whisper still got the full audio. On a 40-min video focused to 5 min, that meant uploading 18 MB to transcribe 2 MB worth of content. Now extract_audio() honors -ss/-to and transcribe_video() offsets the returned segment timestamps so they align with the source-video timeline.
4. Chunk Whisper uploads — audio over 10 min is split into chunks, each uploaded independently. A chunk that fails permanently is reported and skipped — caller gets segments from the successful chunks plus a list of (start, end, reason) tuples for failures. Fixes the hard 25 MB / ~52 min cap and means a single 5xx no longer kills the entire transcript.
5. Cache successful chunk transcripts — successful transcriptions cached to ~/.cache/watch/chunks/ keyed by (file path + size + mtime + window + backend). On re-run with matching inputs, both extraction and the API call are skipped. Means partial-failure recovery (focused re-run on the missing window) is free for the chunks that already worked.

Real-world validation

After landing all five fixes, I used the patched /watch to transcribe a complete 16-lesson storyboarding course — ~14 hours of video, ~10,000+ Whisper segments returned. Several lessons exceeded 1 hour individually; lesson 13 was 2h 20m (categorically beyond Groq's free-tier single-file cap pre-fix). Multiple lessons hit transient 500s and 429s mid-run; all recovered cleanly. One lesson's first chunk failed both retries; the cache let me kill the run, wait for the rolling-hour window to reset, retry, and pick up exactly where the previous attempt left off without re-paying for the chunks that had already succeeded.

Without these fixes, none of that would have been possible on Groq's free tier.

Test plan

• Unit tests for retry-cap behavior (5xx, 429, 4xx, network errors) — see test runs in commits
• Unit tests for ffmpeg start/end window arg construction
• Unit tests for chunking + partial-failure path + total-failure path
• Unit tests for cache hit / miss / invalidation paths (5 scenarios incl. partial-cache recovery)
• End-to-end on 14 hours of real audio across 16 separate runs, including focused re-runs and post-quota recovery scenarios

Notes

• All changes live in scripts/whisper.py and scripts/watch.py. No new dependencies, no API changes that aren't backward-compatible (the transcribe_video return tuple grew from 2-tuple to 3-tuple, but the only caller is watch.py which I updated).
• The cache is opt-out implicit (delete ~/.cache/watch/chunks/) and never breaks the pipeline — load failures silently fall through to a fresh upload.
• CHUNK_DURATION_SECONDS = 600 chosen to keep each chunk well under the 25 MB cap (~4.7 MB at 64 kbps mono) and divide cleanly into Groq's 7200s/hour quota.

🤖 Generated with Claude Code