TheCraigHewitt Watch — read a video like a PDF
You don't have a video input. This skill bundles a Python script that fetches the timestamped transcript (and optionally frames) so you can answer questions about video content.
Default mode is transcript-only. No video download, no frame extraction — just captions pulled via yt-dlp in a few seconds. That covers ~every YouTube video and is the right default for research, summarization, and content analysis.
Opt into --with-frames only when the visual layer matters: debugging a screen recording, breaking down a thumbnail/hook visually, reading on-screen text, analyzing UI behavior.
Requirements
Locally installed:
yt-dlp—brew install yt-dlp(macOS) /pipx install yt-dlp(Linux) /winget install yt-dlp.yt-dlp(Windows)ffmpeg+ffprobe—brew install ffmpeg/sudo apt install ffmpeg/winget install Gyan.FFmpeg. Only required for--with-framesand the Whisper audio fallback. Transcript-only on a captioned YouTube video does not need ffmpeg.
If the user's missing one, tell them the install command and stop. Do not auto-install.
How to invoke
The script lives next to this SKILL.md. Invoke it with the absolute path or ${CLAUDE_SKILL_DIR}/watch.py:
python3 "${CLAUDE_SKILL_DIR}/watch.py" "<url-or-path>"
If ${CLAUDE_SKILL_DIR} isn't set in this agent, resolve the path yourself — it's the directory holding this SKILL.md file.
Default (transcript-only)
python3 "${CLAUDE_SKILL_DIR}/watch.py" "https://youtu.be/abc123"
Returns a markdown report with title, channel, duration, and a timestamped transcript like:
[00:01] All right, so here we are, in front of the elephants
[00:05] the cool thing about these guys is that they have really...
With frames (visual layer)
python3 "${CLAUDE_SKILL_DIR}/watch.py" "<url>" --with-frames
Returns frame paths + transcript. Read each frame path in parallel with the Read tool so you see the full chronological visual flow alongside the transcript.
Focus on a section
python3 "${CLAUDE_SKILL_DIR}/watch.py" "<url>" --start 1:30 --end 2:00
Works in both modes. Times accept SS, MM:SS, or HH:MM:SS. In transcript-only mode it filters the transcript. In --with-frames mode it also limits frame extraction and switches to a denser frame budget.
Other flags
| Flag | Purpose |
|---|---|
--no-whisper |
Don't fall back to Whisper if captions are missing. Fail with a clear error instead. |
--whisper groq|openai |
Force a Whisper backend. Default: prefer Groq, fall back to OpenAI. |
--max-frames N |
(frames mode) Cap on frame count. Default 80, hard max 100. |
--resolution W |
(frames mode) Frame width in px. Default 512. Bump to 1024 only if reading on-screen text matters. |
--fps F |
(frames mode) Override auto-fps (clamped to 2 fps). |
--out-dir DIR |
Keep working files somewhere specific (default: tmp). |
--json |
(transcript mode) Emit machine-readable JSON instead of markdown. |
When the script needs Whisper
If a video has no captions (rare for YouTube, common for Loom / Instagram / local files) and you didn't pass --no-whisper, the script will:
- Download audio only (transcript-only mode) or extract from the downloaded video (
--with-frames) - Upload it to Groq's
whisper-large-v3(preferred — cheap, fast) or OpenAI'swhisper-1 - Return the same
[MM:SS]timestamped format
To enable Whisper, set one of these (script reads env vars or ~/.config/watch/.env):
GROQ_API_KEY=... # console.groq.com/keys
OPENAI_API_KEY=... # platform.openai.com/api-keys
If neither key is set and captions are missing, the script exits 2 with a clear message — tell the user how to enable Whisper or that this particular video can't be transcribed.
Output flow
Transcript-only (default). The script prints a self-contained markdown report. Quote timestamps when citing claims. Don't re-print the full transcript back to the user — summarize, extract, or answer their question.
--with-frames. Same report plus a list of frame paths. After running:
- Read every frame path in a single parallel batch — you need them all to follow the visual flow.
- Combine frames with the transcript when answering. If the user asked about the hook, look at frames 1-3 + transcript 0:00–0:15.
Cleanup
The script prints a working directory. If the user isn't going to ask follow-ups about this video, rm -rf <dir> when you're done. Otherwise leave it in place — re-runs can reuse it via --out-dir.
Common research workflows
Hook deconstruction. python3 watch.py "<url>" --start 0 --end 15 --with-frames → analyze cold open: words said, what's on screen, pattern interrupt timing.
Channel research. Run transcript-only on 5-10 competitor videos. Compare structure, topic mix, CTA placement, transcript length-to-duration ratio.
Quote extraction. Transcript-only + grep for a topic in the report (use Bash on the printed work dir).
UI bug repro. --with-frames on a screen recording, then ask which frame the bug appears. Frames mode shines here.
Don't
- Don't re-run the script on a video you already watched this session — you have the transcript in context. Just answer.
- Don't pass
--with-framesfor pure-text research. It downloads the full video and burns image tokens for no benefit. - Don't write API keys into the repo or to stdout. They live in
~/.config/watch/.env(mode 0600).
Security
The script runs yt-dlp and ffmpeg locally — no third-party server in the middle. Audio only leaves the machine when Whisper is needed AND a key is configured (Groq or OpenAI endpoint, whichever matches). The video itself never gets uploaded.
Inspect watch.py before first run if you want to verify.