🎬 watch-video

Give any AI eyes for video.

40x faster keyframe skim · Scene-aware frames · "Look here" detection · Zero API key option

YouTube · TikTok · Instagram · X/Twitter · Vimeo · Loom · Local files · 1800+ sites

---

🚀 What is this?

watch-video lets any AI (Claude, OpenAI, Gemini, or just you) watch a video instead of just guessing from the title. It downloads the video, extracts the most intelligent frames, pulls a timestamped transcript, and hands everything over for analysis.

Old way: "I can't watch videos, but based on the title..." New way: "Here's what happened at 1:23, what was said at 3:45, and what was on screen."

✨ Features

Feature	Description
🚀 Efficient Mode	40x faster — extracts only keyframes (I-frames), skips delta decode. Perfect for daily use.
⚖️ Balanced Mode	Scene-change detection — one frame per shot cut. Intelligent, token-efficient.
🔥 Token Burner	Maximum coverage — 2 fps uniform + all scene changes merged. For when you need to see everything.
⚡ Transcript Mode	Zero frames, just the transcript. Fastest option for podcasts/talking heads.
👁️ Deictic Detection	Scans for "look here", "as you can see", "watch this" — grabs a frame at that exact moment.
🧹 Duplicate Dedup	Compares 32×32 thumbnails, discards near-identical frames. Solves the "talking head" problem.
🎙️ Multi-Engine Transcript	Captions → Local Whisper (free, private) → Groq → OpenAI. Falls through automatically.
🍪 Login-Gated Sources	Instagram, X/Twitter, private YouTube — borrow cookies from your browser.

📦 One-Command Install

pip install camel-watch

Then:

# Quick vibe check (40x faster)
watch "https://youtu.be/dQw4w9WgXcQ" --mode efficient

# Deep scene-aware analysis
watch "recording.mp4" --mode balanced

# Maximum coverage (expensive, use sparingly)
watch "https://youtu.be/..." --mode token-burner

# Just the transcript (fastest)
watch "https://youtu.be/..." --mode transcript

# Focus on a specific section
watch "talk.mp4" --start 10:00 --end 15:00 --mode token-burner

🔧 How It Works

You paste a URL or path
        │
        ▼
   yt-dlp downloads video + captions (1800+ sites)
        │
        ▼
   ffmpeg extracts frames in your chosen mode
   ├── transcript → 0 frames
   ├── efficient  → keyframes only (40x faster)
   ├── balanced   → scene-change detection
   └── token-burner → 2fps + all scenes merged
        │
        ▼
   Deictic detection: "look here" → grab that frame
        │
        ▼
   Duplicate dedup: discard near-identical frames
        │
        ▼
   Transcript pipeline:
   captions → local Whisper (private!) → Groq → OpenAI
        │
        ▼
   🎯 AI can now answer anything about the video

🎯 Use Cases

• Summarize a 2-hour interview in 5 seconds
• Analyze YouTube hooks — what's on screen in the first 3 seconds?
• Diagnose a bug from a screen recording someone sent you
• Extract quotes from a webinar with timestamps
• Catalog visual moments — "when does the slide change?"
• Competitor analysis — what visuals do top creators use?

📊 Mode Comparison

                   Frames    Speed    Cost    Best For
transcript        0         ⚡⚡⚡    Free    Podcasts, talking heads
efficient (40x)   ~100      🚀       Low     Everyday use, long videos
balanced          ~80       ⚖️       Med     Default — scene-aware
token-burner      ~600      🔥       High    Forensics, critical analysis

🔌 Use with Any AI

Claude Code

/plugin marketplace add watch-video/watch-video
/plugin install watch@watch-video

Pi (coding agent)

The skill auto-discovers from ~/.pi/agent/skills/watch/.

Direct API

from watch_video.core.orchestrator import run_watch

result = run_watch("https://youtu.be/...", mode="balanced")
print(result["frames_total"])  # Number of frames
print(result["transcript_segments"])  # Transcript

CLI with JSON output

watch "https://youtu.be/..." --mode efficient --json > analysis.json

🛠️ Requirements

• Python 3.9+
• ffmpeg + yt-dlp — auto-installed on macOS (brew), or:

  # Windows
  winget install Gyan.FFmpeg
  pip install yt-dlp
  
  # Linux
  sudo apt install ffmpeg
  pip install yt-dlp
  

For local transcription (no API key, audio never leaves your machine):

pip install camel-watch[local]

For full features:

pip install camel-watch[all]

No API key needed for local transcription. For API fallback, set:

export GROQ_API_KEY="gsk_..."   # Cheaper, faster
# or
export OPENAI_API_KEY="sk-..."  # Universal fallback

🍪 Login-Gated Sources

Instagram, X/Twitter, and private YouTube videos need your browser cookies:

watch "https://www.instagram.com/reel/..." --cookies-from-browser chrome

Or export a cookies.txt from a browser extension and pass --cookies cookies.txt.

🔒 Your cookies are read live and piped into yt-dlp. Never stored or transmitted.

📋 All Options

usage: watch [-h] [--mode {transcript,efficient,balanced,token-burner}]
             [--max-frames N] [--resolution W] [--fps F]
             [--start T] [--end T] [--intent STR]
             [--no-whisper] [--whisper {local,groq,openai}]
             [--no-dedup] [--no-deictic] [--json]
             [--cookies-from-browser B] [--cookies FILE]
             source

positional arguments:
  source                Video URL or local file path

options:
  --mode MODE           Frame extraction mode (default: balanced)
  --max-frames N        Cap on frame count
  --resolution W        Frame width in pixels (default: 512)
  --fps F               Override fps
  --start T             Start time (SS, MM:SS, HH:MM:SS)
  --end T               End time (SS, MM:SS, HH:MM:SS)
  --intent STR          Why you're watching (shapes analysis)
  --no-whisper          Disable whisper fallback
  --whisper BACKEND     Force whisper backend
  --no-dedup            Disable frame deduplication
  --no-deictic          Disable deictic detection
  --json                Output JSON
  --cookies-from-browser B  Browser cookies (chrome, firefox, etc.)
  --cookies FILE        Path to cookies.txt

📈 Token Efficiency

Mode	5 min	30 min	2 hr
transcript	~2k	~10k	~40k
efficient	~15-30k img	~30-60k img	~60-120k img
balanced	~30-60k img	~50-80k img	~80-100k img
token-burner	~60-120k img	~150-300k img	~300-600k img

Image tokens at 512px. 1024px roughly quadruples — use --resolution 1024 only when reading on-screen text.

🔒 Privacy

• Local transcription — audio never leaves your machine
• No telemetry — zero data collection
• No accounts — no signup needed
• Cookies stay local — read live, never stored

🧠 Philosophy

Most AI video tools are black boxes — you upload a video to their servers and hope for the best. watch-video runs everything locally. The only network traffic is downloading the video itself (which you'd do anyway if you were watching it manually).

📄 License

MIT — do whatever you want with it.

⭐ Support

If this saved you time, drop a star on GitHub. It helps more people find it.

---

Made with ❤️ for everyone who's tired of skipping through videos