Metadata-Version: 2.4
Name: camel-watch
Version: 2.0.0
Summary: Give any AI eyes for video. 4 intelligent modes: 40x faster keyframe skim, scene-aware frames, deictic detection, duplicate dedup. YouTube/TikTok/Instagram/1800+ sites.
License: MIT
License-File: LICENSE
Keywords: video,claude,ai,youtube,transcription,whisper,frames,multimodal,yt-dlp,ffmpeg
Author: thecodingcamel
Author-email: mouaffakneten@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: all
Provides-Extra: local
Requires-Dist: Pillow (>=10,<11) ; extra == "all"
Requires-Dist: openai-whisper (>=202311,<202312) ; extra == "local" or extra == "all"
Requires-Dist: yt-dlp (>=2026,<2027)
Project-URL: Homepage, https://github.com/thecodingcamel/watch-video
Project-URL: Repository, https://github.com/thecodingcamel/watch-video
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://img.shields.io/badge/watch--video-2.0.0-blue?style=for-the-badge" alt="version">
  <img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="license">
  <img src="https://img.shields.io/badge/python-3.9%2B-orange?style=for-the-badge" alt="python">
  <img src="https://img.shields.io/badge/yt--dlp-1800%2B_sites-purple?style=for-the-badge" alt="sites">
  <img src="https://img.shields.io/badge/modes-4-cyan?style=for-the-badge" alt="modes">
</p>

<h1 align="center">🎬 watch-video</h1>
<h3 align="center">Give any AI eyes for video.</h3>
<p align="center">
  <b>40x faster keyframe skim · Scene-aware frames · "Look here" detection · Zero API key option</b>
</p>
<p align="center">
  YouTube · TikTok · Instagram · X/Twitter · Vimeo · Loom · Local files · <b>1800+ sites</b>
</p>

---

## 🚀 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

```bash
pip install camel-watch
```

Then:

```bash
# 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
```bash
/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
```python
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
```bash
watch "https://youtu.be/..." --mode efficient --json > analysis.json
```

## 🛠️ Requirements

- **Python 3.9+**
- **ffmpeg + yt-dlp** — auto-installed on macOS (`brew`), or:
  ```bash
  # 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):**
```bash
pip install camel-watch[local]
```

**For full features:**
```bash
pip install camel-watch[all]
```

No API key needed for local transcription. For API fallback, set:
```bash
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:

```bash
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.

---

<p align="center">
  <b>Made with ❤️ for everyone who's tired of skipping through videos</b>
</p>

