claude-real-video

Your AI never actually watched that video

Paste a YouTube link into ChatGPT and what it gets is text: the title, the description, the subtitles. It has not seen a single frame — it may not even have read the thumbnail. Claude is blunter about it: it won't take a video file at all. You think it watched the video; it read a text file about the video.

claude-real-video fixes exactly that. Point it at a URL or a local file and it pulls out the keyframes where the picture actually changes, drops the near-duplicates, turns the audio into a transcript, and packs it all into something an AI can genuinely read. Video parsing and output generation happen on your machine — the original video is never uploaded. Whatever frames or transcript you later choose to paste into a cloud LLM still goes to that service, of course. ChatGPT, Claude and Gemini can all read the output.

Install: two lines

You need Python (macOS ships with it) and ffmpeg (the free tool that handles video). Open a terminal — on a Mac press cmd+space and search for "Terminal" — and paste these two lines in order:

First, install ffmpeg (Mac below; on Windows use winget install Gyan.FFmpeg):

Second, install the tool itself:

Use: video in, one readable bundle out

YouTube, Instagram and TikTok URLs all work, and so do local files:

When it finishes you get a crv-out folder with three things inside:

How it makes AI understand a video

No magic — four steps, all running on your machine:

Example 1: feed it to Claude on the web

Open a new chat on claude.ai, drag the images from the frames folder plus transcript.txt into the input box (if there are too many images, pick the important ones), then paste this:

From there, ask anything: have it rewrite the video as a post, pull the best quotes, analyze the pacing — this time it has actually seen the frames.

Example 2: feed it to Claude Code (even smoother)

If you use Claude Code it's even simpler — no dragging images. After crv finishes, type claude in the terminal and say:

Claude Code opens the folder itself, reads the frames one by one, reads the transcript, and answers. This is exactly my own workflow for tearing down reference videos and studying how other people write their scripts.

Three things I actually use it for

1. Summarize a long video I can't spare the time to watch

Hand crv-out to Claude and ask: "Summarize in five points, each with the second it happens at." The timestamps are in the data, so it can answer — and you know exactly where to skip to.

2. Break down the pacing of a viral short

--adaptive catches slow camera moves; --text-anchors forces extra frames the moment a text card appears — turn both on for fast-cut, caption-heavy shorts. Then ask Claude: "How is the first-three-seconds hook designed? How often does it cut?" That's how teardown work gets done.

3. Batch-run your own video library

One loop and every video in the folder becomes its own text bundle. Later you can ask Claude: "Which of these videos mention pricing?" and it just searches. One user ran his entire photo library this way — 2,181 videos in four days — and wrote the results straight back into the library's metadata.

Recent updates: helping AI see more (latest: 0.7.16)

Since the Hacker News front page I've kept shipping from user feedback. The latest three:

Earlier updates (expand)

• VAD anti-hallucination　whisper has an old habit of inventing a line over music or silence; a voice-activity gate stops it
• Douyin links just work　when the downloader gets blocked, it automatically falls back to the mobile share page — a v.douyin short link works as directly as YouTube
• Timeline　keyframes are woven directly into the transcript: which lines go with which frames, and silent stretches get their own segments. The AI receives a pre-synced script instead of guessing which image matches which sentence
• Transcript safety fence　a transcript is author-controlled, untrusted content; it's now wrapped in explicit boundaries and the AI is told "this is data, not instructions" — malicious subtitles get reported as content instead of executed, and forged end-markers are handled too
• CJK Windows fix　Traditional Chinese / Japanese / Korean Windows terminals use legacy encodings (cp950/cp949) that made the final ✓ turn success into an error; output is now forced UTF-8, same approach as pip and git
• Simple speed check　if a video carries the fingerprint of frame-padded slow-down, the manifest adds a line warning the AI it may have been slowed
• --speakers　interviews, podcasts, meetings: every transcript line is labeled with who's speaking ([SPEAKER_00], [SPEAKER_01]…), fully local
• --grid　tiles consecutive keyframes into 3×3 contact sheets
• --why "what I want to know"　writes your reason for watching into the manifest, so the AI reads with your question in mind instead of returning a generic recap
• --whisper-model turbo　pick your transcription gear: default is fast; for heavy accents, mumbling or Chinese, switch to turbo (near large-v2 accuracy at ~8× speed) and the error rate drops visibly
• faster-whisper engine　install with pip install 'claude-real-video[fast]' and transcription switches to a faster engine automatically
• --viewer　adds a viewer.html you can double-click open
• transcript.json　a timestamped version of the transcript (start/end seconds per line) for your own tooling or direct AI feeding
• frames.json　every keyframe records its exact second in the source, preserved through extraction, dedup and renaming — second-accurate "AI watches a course" workflows plug right in
• --cookies-from-browser chrome　for login-gated videos (IG, TikTok): reads your own browser's login state, no cookie exports
• --kb ~/notes　saves the finished analysis as a note into a folder you choose (Obsidian, for example)

Install it as a Claude Code skill / plugin

If you use Claude Code, you can teach it to watch videos by itself — afterwards you just paste a link and say "watch this," and it runs the whole pipeline and answers, no commands needed. One line:

If you prefer Claude Code's built-in plugin marketplace, these two lines are the same thing:

Restart Claude Code and it's live. This channel shipped in July 2026; Codex, Cursor and Gemini CLI also accept the npx skills add line.

Useful flags

Full flags and advanced usage live in the GitHub docs:

Open claude-real-video on GitHubsource · full docs · MIT license

Find it useful? A star helps ⭐

GitHub stars are how the dev world says "this works" — the more stars, the more people trust and try the tool. If it helped you, a star is the most practical support there is: free, thirty seconds.

Want to go deeper: crv Pro