# claude-real-video

> A local CLI tool that lets any LLM actually watch a video by extracting scene-aware, deduplicated keyframes and transcripts from URLs or local files.

claude-real-video (crv) is an open-source Python CLI tool that solves a fundamental limitation of current AI assistants: they can't truly watch a video. Built by LeoAido and published under the MIT license, it reached the Hacker News front page and has accumulated over 730 GitHub stars. The tool runs entirely on your local machine — only the frames and text you choose to paste into an LLM are ever sent anywhere.

## What It Is

`claude-real-video` is a video preprocessing pipeline for LLMs. Instead of sampling frames at a fixed interval (the approach used by most tools and Gemini's default pipeline), it uses scene-change detection combined with a sliding-window deduplication pass to extract only the frames that actually differ visually. The result is a clean folder of keyframes, an optional Whisper-generated transcript, and a `MANIFEST.txt` that any LLM can read. It works with YouTube, Instagram, TikTok, and other yt-dlp-supported URLs, as well as local video files.

## How the Pipeline Works

The tool runs six sequential steps entirely on your machine:

- **Fetch** — downloads via `yt-dlp` for URLs, or copies a local file
- **Extract** — a single `ffmpeg select` pass captures every scene change plus a configurable density floor (at least one frame every N seconds)
- **Dedup** — compares real pixel differences (downscaled RGB, not perceptual hashes) against a sliding window of the last N kept frames, so repeated shots aren't re-sent
- **Text** — uses existing subtitle tracks (`.srt`/`.vtt`) when available; falls back to Whisper transcription only when no subtitles exist
- **Audio** *(optional)* — saves the full original soundtrack (`audio.m4a`) losslessly for models that can listen
- **Manifest** — writes `MANIFEST.txt` summarising everything for the model

The `--grid` flag packs consecutive keyframes into contact sheets, reducing token count further. The `--why` flag writes your analysis intent into the manifest so the LLM focuses on what you care about rather than producing a generic summary.

## Why It Differs from Fixed-Interval Sampling

The README provides a direct comparison: fixed-interval sampling at 1 fps produces 58 frames for a 58-second clip; crv keeps 26 that actually differ and packs them into 3 contact sheets. A 10-minute static screencast collapses to a single frame under dedup; a fast-cut reel catches every visual change that a 1 fps sampler would miss. The tool also handles the A-B-A cut problem — a shot the model has already seen doesn't re-appear after a cutaway.

## Claude Code Integration

The repository ships a `skills/` directory that lets Claude Code use crv autonomously. After installing the package and copying the skill folder to `~/.claude/skills/`, users can paste a video link directly into Claude Code and ask about it — Claude will invoke crv on its own without manual frame extraction.

## Update: v0.4.0 — Contact Sheets, Purpose-Aware Manifests, Knowledge Base

The latest release (v0.4.0, published July 3 2026) added three headline features: `--grid` contact sheets that pack nine consecutive keyframes per image, `--why` for purpose-aware manifests, and `--kb` for saving analysis as dated markdown notes into a personal knowledge base folder (e.g., an Obsidian vault). Version 0.3.0 introduced `--why` and `--kb`; v0.4.0 added the grid output. The repository shows active development with the last push on July 4 2026.

## crv Pro Add-On

The free open-source tool covers frame extraction and transcription. The developer also offers crv Pro, a paid one-time add-on at leoaido.com/crv-pro/, which adds a `--motion` pass for camera-move classification (static/pan/tilt/zoom/handheld), editing rhythm analysis (shot list, cuts per minute, pacing curve), action-burst frame sequences at 0.2-second intervals, and a `--breakdown` report covering hook analysis, camera language, and a Reels-algorithm lens. All processing remains local.

## Features
- Scene-change detection for keyframe extraction
- Sliding-window pixel-difference deduplication
- yt-dlp URL support (YouTube, Instagram, TikTok, etc.)
- Local file support
- Whisper audio transcription with language detection
- Existing subtitle track reuse (.srt/.vtt)
- Contact sheet grid output (--grid)
- Purpose-aware manifests (--why)
- Knowledge base integration (--kb)
- Full audio track export (--keep-audio)
- Cookie-based authentication for gated videos
- Claude Code skill integration
- HTML report for keep/drop decisions (--report)
- Python API (process() function)
- Configurable scene sensitivity, fps floor, and dedup thresholds

## Integrations
Claude, ChatGPT, Gemini, Claude Code, yt-dlp, ffmpeg, Whisper, Obsidian

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source, Free tier available

## Version
v0.4.0

## Links
- Website: https://github.com/HUANGCHIHHUNGLeo/claude-real-video
- Documentation: https://github.com/HUANGCHIHHUNGLeo/claude-real-video
- Repository: https://github.com/HUANGCHIHHUNGLeo/claude-real-video
- EveryDev.ai: https://www.everydev.ai/tools/claude-real-video