Video Watch

video-watch

Video -> Whisper transcript -> findings. The script handles download, conversion, transcription and retention on its own; your job is steps 2 and 3.

Setup (once): copy .env.example (repo root) to .env in the repo root or in this skill folder (both locations are read) and set WHISPER_API_URL (plus WHISPER_API_KEY for hosted APIs). Groq, OpenAI and self-hosted servers all work; the endpoint just has to accept OpenAI-style audio/transcriptions requests. yt-dlp and ffmpeg must be on PATH (if they were installed seconds ago, refresh PATH or restart the shell first).

Workflow

1. Transcribe (run from the workspace root; a video-watch/ folder appears there):

   python3 <skill-path>/scripts/video-watch.py "<url>" [--frames] [--vocab "Term1, Term2"]
   

   • --vocab: proper nouns and jargon likely to occur in the video (derive from title and topic, e.g. product names). Improves Whisper accuracy noticeably.
   • --frames: only when visual questions are on the table or the user wants images (downloads the video on top of the audio). Frames are spread smartly over the full runtime: transcript pointer cues first ("look at this", "as you can see"), then even time coverage, so the second half of the video is represented too. A dedup pass (on by default) drops near-identical frames (talking head, held slide); index.md maps each frame to its timestamp and source. --no-dedup keeps everything.
   • Never run two videos with --frames in parallel. Two simultaneous video downloads from one IP tend to trigger YouTube's bot detection (audio survives, video fails). Run them sequentially.
2. Read transcript.md (paragraphs with timestamps; transcript.json has finer segments).
3. Write findings.md into the video folder using the format below.
4. For visual questions: open the relevant JPGs from frames/ (index.md maps frame -> timestamp).

Findings format (default; user instructions override)

Max one page, very compact, no filler. Write in the language the user speaks with you. Structure:

# Findings: <title>
<channel> | <duration> | <upload date> | <URL>

**Core claim:** <1-2 sentences>

## <Topic sections with (mm:ss) timestamps>
- Substance only; mark sponsor segments and outros as such instead of summarizing them

## For you
- 1-3 honest bullets tailored to this specific user, based on what you know
  about them and their current projects: what is concretely relevant,
  actionable, or safely skippable for THEM. No obligatory praise. If the video
  is barely relevant, say so and name the one usable takeaway. This section is
  the added value over a generic summary.

Follow-ups

Every video gets a folder video-watch/YYYY-MM-DD-<channel>-<title>--<id>/ containing transcript.md, transcript.json, meta.json, findings.md and possibly frames/. For follow-up questions ("what does he say about X", "make it 3 pages", "show me the key images") use that folder instead of transcribing again. Missing frames -> add them with --frames-only (reuses the existing folder, no second transcription).

Cost depends on your endpoint; at Groq's whisper-large-v3 pricing (as of 2026-07) about $0.111 per audio hour. After 90 days a sweep keeps findings.md and meta.json and deletes the rest of the folder, transcripts included (window configurable via VIDEO_WATCH_RETENTION_DAYS).