# Video Watch

> Transcribe YouTube videos and podcast episodes in high quality (Whisper via a configurable API endpoint) and distill compact findings with timestamps. Use whenever the user wants a video "watched", summarized, transcribed or analyzed, drops a YouTube or podcast URL together with a question, asks "what does he say about X in that video", or follows up on an earlier video folder, even when the word "transcribe" never appears. For visual questions, frames can be extracted on top. NOT for local audio files (voice memos, recordings); that is the audio-transcribe skill.

- Skill: `belschak/video-watch` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add belschak/video-watch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/belschak/video-watch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: belschak (https://skillmd.com/u/belschak)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/belschak/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:

```markdown
# 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`).