← Back to Home

claude-video: Give Claude the Ability to Watch Any Video

2026-07-16

claude-video: Give Claude the Ability to Watch Any Video 🎬

What is it? claude-video is an open-source /watch skill that gives Claude (or any coding agent supporting the Agent Skills standard) the ability to watch a video. Paste a YouTube URL, TikTok link, or local file path, ask a question, and Claude fetches captions, extracts frames, transcribes audio, and answers grounded in what's actually on screen — not just the title or description.

Why it's trending: claude-video hit 8,600+ GitHub stars because it solves a fundamental limitation of AI coding agents. Claude can read code, browse the web, and run scripts, but it can't watch a video. When you paste a YouTube link, it has to guess from the title or pull a bare transcript missing 90% of what's on screen. This tool bridges that gap — it gives Claude actual vision over video content, scene by scene, frame by frame. Built by bradautomates, MIT licensed, and compatible with Claude Code, Codex, Cursor, Gemini CLI, and 50+ other AI coding agents.

How It Works

Architecture

The workflow is a straightforward pipeline from video URL to grounded answer:

  1. You paste a video URL and a question. Anything yt-dlp supports — YouTube, Loom, TikTok, X, Instagram, Vimeo, plus hundreds more — or a local file (.mp4, .mov, .mkv, .webm).
  2. yt-dlp checks captions first. At transcript detail level, captioned URLs return without downloading video. Otherwise, it downloads only what's needed.
  3. ffmpeg extracts frames at the chosen detail level. Three modes: efficient (fast keyframes, ~0.5s), balanced (scene-change detection, default), and token-burner (uncapped scene-candidate frames).
  4. Transcript comes from captions or Whisper. Native captions (auto-generated or manual) are free and instant. When none exist, the script extracts a mono 16 kHz audio clip and sends it to Whisper — Groq's whisper-large-v3 (preferred, cheaper) or OpenAI's whisper-1.
  5. Frame deduplication drops near-identical frames via a 16×16 grayscale thumbnail comparison, so your token budget is spent on distinct content.
  6. Claude Reads every frame and the timestamped transcript in parallel, answering based on what's actually visible and audible.

The key insight: Claude sees the frames as images and reads the transcript with timestamps. It's not guessing — it's analyzing what's on screen.

Prerequisites

  • Python 3.10+ (for the watch.py script)
  • ffmpeg and yt-dlp (installed automatically on macOS via brew; Linux/Windows get exact instructions)
  • Claude Code (recommended) or any Agent Skills-compatible host (Codex, Cursor, Gemini CLI, Copilot, etc.)
  • Optional: Groq API key (free tier available) for Whisper transcription when videos lack captions

Installation

Claude Code (Recommended)

Claude Code has a built-in plugin marketplace for instant install:

# Add the plugin marketplace source
/plugin marketplace add bradautomates/claude-video

# Install the /watch skill
/plugin install watch@claude-video

Update later with /plugin update watch@claude-video.

Codex, Cursor, Gemini CLI, and 50+ Other Hosts

The Agent Skills CLI installs the skill into whatever agents it detects on your system:

npx skills add bradautomates/claude-video -g

The -g flag installs globally. Drop it to scope to the current project. For specific agents:

npx skills add bradautomates/claude-video -a codex -a cursor

First Run Setup

On the first /watch call, the setup script checks for dependencies:

  • macOS — auto-runs brew install ffmpeg yt-dlp
  • Linux — prints exact apt / dnf / pipx commands
  • Windows — prints winget / pip commands
  • API key — scaffolds ~/.config/watch/.env with commented placeholders for GROQ_API_KEY (preferred) and OPENAI_API_KEY

Manual Install (Developer)

git clone https://github.com/bradautomates/claude-video.git
ln -s "$(pwd)/claude-video/skills/watch" ~/.claude/skills/watch

Quick Start

Basic Usage

The simplest use case — paste a URL and ask a question:

/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?

Claude fetches captions, extracts frames around the 30-second mark, and answers based on what's actually on screen.

Local Files

/watch ~/Movies/screen-recording.mov when does the UI break?

This works with .mp4, .mov, .mkv, and .webm files.

Focused Mode (Best for Long Videos)

For long videos, use --start and --end to zoom in on a specific section. This gives you a much denser frame budget:

/watch https://youtu.be/abc --start 2:15 --end 2:45
/watch video.mp4 --start 50 --end 60

Detail Modes

The --detail flag controls the frame extraction strategy, balancing speed, token cost, and coverage:

Mode Engine Frame cap Use case
transcript None (captions only) 0 Quick summaries, text-heavy content
efficient Keyframes (fast) 50 Fast scan, short clips
balanced Scene-change 100 Default — good coverage
token-burner Scene-change (uncapped) Unlimited Deep analysis, long videos 
# Fast scan — just keyframes
/watch https://youtu.be/abc --detail efficient

# Deep analysis — every scene-change frame
/watch https://youtu.be/abc --detail token-burner

Frame Budget by Video Length

The auto-fps logic adjusts frame budgets to avoid blowing your context:

  • ≤30s — ~30 frames (dense, every key moment)
  • 30s–1min — ~40 frames
  • 1–3min — ~60 frames
  • 3–10min — ~80 frames
  • >10min — 100 frames (capped) — use --start/--end for focused analysis

Advanced Options

Custom Timestamps

Target specific moments with --timestamps:

/watch https://youtu.be/abc --timestamps 0:15,1:30,2:45

Claude reads the transcript first, then grabs frames at each exact timestamp.

Higher Resolution for On-Screen Text

When the video contains slides, terminal output, or code:

/watch https://youtu.be/abc --resolution 1024

This bumps frame width to 1024px for better text readability.

Disable Whisper

If you only want frames without transcription:

/watch https://youtu.be/abc --no-whisper

What People Actually Use It For

Analyze content structure — paste a viral video and ask Claude to break down the hook, the structure, and the key moments. Great for ad creative, competitor launches, and podcast intros.

Debug from screen recordings — someone sends you a screen recording of a bug. /watch bug-repro.mov what's going wrong? Claude watches the recording and finds the frame where the issue appears.

Summarize long content — /watch https://youtu.be/long-talk summarize this pulls the structure, key moments, and what was actually said and shown, faster than watching at 2x.

Cut through marketing hype — /watch https://youtu.be/launch-video what's actually new — skip the hype strips a feature drop down to the real substance.

Build searchable notes from playlists — run /watch across a course or channel, file per-video summaries, and create a searchable knowledge base without re-watching hours of content.

Architecture

The architecture is intentionally modular. Each component — download, frame extraction, transcription, deduplication — is a separate Python script in skills/watch/scripts/:

  • watch.py — entry point, orchestrates the full pipeline
  • download.py — yt-dlp wrapper for video downloading and caption fetching
  • frames.py — ffmpeg wrapper with auto-fps logic and three extraction modes
  • transcribe.py — VTT parsing, deduplication, and Whisper orchestration
  • whisper.py — Groq / OpenAI clients (pure Python stdlib, no heavy dependencies)
  • config.py — shared configuration via ~/.config/watch/.env
  • setup.py — preflight checks and first-run dependency installer

The pipeline is simple: download → extract frames → transcribe → deduplicate → feed to Claude. Each stage can run independently, making it easy to debug or customize.

Limitations

  • Long videos with capped modes — past ~10 minutes, frame coverage thins out. Use --start/--end for focused analysis or --detail token-burner for uncapped coverage.
  • Token cost — image tokens add up fast. At 512px width, each frame is ~197 tokens (per Anthropic's pricing). A 100-frame analysis costs ~19.7k tokens in images alone.
  • Whisper API key needed — videos without captions require a Groq or OpenAI API key for transcription. Native captions cover most public YouTube videos for free.
  • Network dependency — the tool downloads video/audio content on each run. Offline use requires pre-downloaded local files.

Resources

Comparison with Alternatives

  • Browser DevTools — let you inspect network requests but offer no video frame extraction or multimodal analysis. claude-video automates the entire pipeline from URL to answer.
  • Manual transcript reading — reading a transcript alone misses 90% of visual context (UI changes, body language, code on screen). claude-video combines frames + transcript for full multimodal analysis.
  • Video summarization tools — existing tools generate summaries from transcripts only, missing visual content. claude-video gives Claude actual vision over every frame.
  • Custom scripting — you could script yt-dlp + ffmpeg + Whisper manually, but claude-video packages it into one /watch command with auto-fps, dedup, and multi-mode frame extraction built-in.
← Retour à l'Accueil

claude-video : Donnez à Claude la capacité de regarder n'importe quelle vidéo

2026-07-16

claude-video : Donnez à Claude la capacité de regarder n'importe quelle vidéo 🎬

Qu'est-ce que c'est ? claude-video est une compétence open-source /watch qui permet à Claude (ou à tout agent de codage supportant le standard Agent Skills) de regarder une vidéo. Collez une URL YouTube, un lien TikTok, ou un chemin de fichier local, posez une question, et Claude récupère les sous-titres, extrait les images, transcrit l'audio, et répond en se basant sur ce qui est réellement à l'écran — pas seulement le titre ou la description.

Pourquoi ça cartonne : claude-video a atteint 8 600+ étoiles GitHub parce qu'il résout une limitation fondamentale des agents de codage IA. Claude peut lire du code, naviguer sur le web et exécuter des scripts, mais il ne peut pas regarder une vidéo. Quand vous collez un lien YouTube, il doit deviner à partir du titre ou extraire un transcript brut qui manque 90% de ce qui est à l'écran. Cet outil comble ce fossé — il donne à Claude une véritable vision du contenu vidéo, scène par scène, image par image. Développé par bradautomates, sous licence MIT, et compatible avec Claude Code, Codex, Cursor, Gemini CLI, et 50+ autres agents de codage IA.

Comment ça fonctionne

Architecture

Le workflow est un pipeline direct de l'URL vidéo à la réponse fondée :

  1. Vous collez une URL vidéo et une question. Tout ce que yt-dlp supporte — YouTube, Loom, TikTok, X, Instagram, Vimeo, plus des centaines d'autres — ou un fichier local (.mp4, .mov, .mkv, .webm).
  2. yt-dlp vérifie d'abord les sous-titres. Au niveau de détail transcript, les URLs avec sous-titres reviennent sans télécharger la vidéo. Sinon, il télécharge uniquement ce qui est nécessaire.
  3. ffmpeg extrait les images au niveau de détail choisi. Trois modes : efficient (images clés rapides, ~0,5s), balanced (détection de changement de scène, par défaut), et token-burner (images de scène sans limite).
  4. Le transcript provient des sous-titres ou de Whisper. Les sous-titres natifs (auto-générés ou manuels) sont gratuits et instantanés. Quand il n'y en a pas, le script extrait un clip audio mono 16 kHz et l'envoie à Whisper — whisper-large-v3 de Groq (recommandé, moins cher) ou whisper-1 d'OpenAI.
  5. La déduplication d'images supprime les images quasi-identiques via une comparaison de vignettes en niveaux de gris 16×16, pour que votre budget de tokens soit dépensé sur du contenu distinct.
  6. Claude Read chaque image et le transcript horodaté en parallèle, répondant en se basant sur ce qui est réellement visible et audible.

L'idée clé : Claude voit les images et lit le transcript avec les horodatages. Il ne devine pas — il analyse ce qui est à l'écran.

Prérequis

  • Python 3.10+ (pour le script watch.py)
  • ffmpeg et yt-dlp (installés automatiquement sur macOS via brew ; Linux/Windows reçoivent les commandes exactes)
  • Claude Code (recommandé) ou tout hôte compatible Agent Skills (Codex, Cursor, Gemini CLI, Copilot, etc.)
  • Optionnel : Clé API Groq (niveau gratuit disponible) pour la transcription Whisper quand les vidéos manquent de sous-titres

Installation

Claude Code (Recommandé)

Claude Code dispose d'un marché de plugins pour une installation instantanée :

# Ajouter la source du marché de plugins
/plugin marketplace add bradautomates/claude-video

# Installer la compétence /watch
/plugin install watch@claude-video

Mettez à jour plus tard avec /plugin update watch@claude-video.

Codex, Cursor, Gemini CLI, et 50+ autres hôtes

Le CLI Agent Skills installe la compétence dans les agents détectés sur votre système :

npx skills add bradautomates/claude-video -g

Le flag -g installe globalement. Supprimez-le pour limiter au projet courant. Pour des agents spécifiques :

npx skills add bradautomates/claude-video -a codex -a cursor

Première exécution

Lors du premier appel /watch, le script de configuration vérifie les dépendances :

  • macOS — exécute automatiquement brew install ffmpeg yt-dlp
  • Linux — affiche les commandes apt / dnf / pipx exactes
  • Windows — affiche les commandes winget / pip
  • Clé API — crée ~/.config/watch/.env avec des emplacements commentés pour GROQ_API_KEY (recommandé) et OPENAI_API_KEY

Installation manuelle (développeur)

git clone https://github.com/bradautomates/claude-video.git
ln -s "$(pwd)/claude-video/skills/watch" ~/.claude/skills/watch

Démarrage rapide

Utilisation de base

Le cas d'usage le plus simple — collez une URL et posez une question :

/watch https://youtu.be/dQw4w9WgXcQ que se passe-t-il à 30 secondes ?

Claude récupère les sous-titres, extrait les images autour de la marque des 30 secondes, et répond en se basant sur ce qui est réellement à l'écran.

Fichiers locaux

/watch ~/Vidéos/enregistrement-ecran.mov où l'interface plante-t-elle ?

Cela fonctionne avec les fichiers .mp4, .mov, .mkv, et .webm.

Mode ciblé (meilleur pour les longues vidéos)

Pour les vidéos longues, utilisez --start et --end pour zoomer sur une section spécifique :

/watch https://youtu.be/abc --start 2:15 --end 2:45
/watch video.mp4 --start 50 --end 60

Modes de détail

Le flag --detail contrôle la stratégie d'extraction d'images, équilibrant vitesse, coût en tokens, et couverture :

Mode Moteur Limite d'images Cas d'usage
transcript Aucun (sous-titres seulement) 0 Résumés rapides, contenu textuel
efficient Images clés (rapide) 50 Analyse rapide, courts extraits
balanced Changement de scène 100 Par défaut — bonne couverture
token-burner Changement de scène (sans limite) Illimité Analyse approfondie, longues vidéos 
# Analyse rapide — juste les images clés
/watch https://youtu.be/abc --detail efficient

# Analyse approfondie — toutes les images de changement de scène
/watch https://youtu.be/abc --detail token-burner

Budget d'images par longueur de vidéo

La logique auto-fps ajuste les budgets d'images pour éviter de saturer le contexte :

  • ≤30s — ~30 images (dense, chaque moment clé)
  • 30s–1min — ~40 images
  • 1–3min — ~60 images
  • 3–10min — ~80 images
  • >10min — 100 images (limité) — utilisez --start/--end pour une analyse ciblée

Options avancées

Horodatages personnalisés

Ciblez des moments spécifiques avec --timestamps :

/watch https://youtu.be/abc --timestamps 0:15,1:30,2:45

Claude lit d'abord le transcript, puis capture les images à chaque horodatage exact.

Résolution plus élevée pour le texte à l'écran

Quand la vidéo contient des diapositives, du terminal ou du code :

/watch https://youtu.be/abc --resolution 1024

Augmente la largeur des images à 1024px pour une meilleure lisibilité.

Désactiver Whisper

Si vous voulez seulement les images sans transcription :

/watch https://youtu.be/abc --no-whisper

Cas d'usage concrets

Analyser la structure du contenu — collez une vidéo virale et demandez à Claude de décomposer l'accroche, la structure et les moments clés. Idéal pour les publicités, les lancements concurrents et les intros de podcast.

Déboguer à partir d'enregistrements d'écran — quelqu'un vous envoie un enregistrement d'écran d'un bug. /watch bug-repro.mov quel est le problème ? Claude regarde l'enregistrement et trouve l'image où le problème apparaît.

Résumer du contenu long — /watch https://youtu.be/long-talk résume ça extrait la structure, les moments clés, et ce qui a été réellement dit et montré, plus vite qu'en regardant en accéléré.

Couper à travers le marketing — /watch https://youtu.be/launch-video qu'est-ce qui est réellement nouveau ? réduit une annonce à l'essentiel.

Créer des notes à partir de listes de lecture — exécutez /watch sur une série de vidéos, archivez des résumés par vidéo, et créez une base de connaissances sans revisionner des heures de contenu.

Architecture

L'architecture est intentionnellement modulaire. Chaque composant — téléchargement, extraction d'images, transcription, déduplication — est un script Python séparé dans skills/watch/scripts/ :

  • watch.py — point d'entrée, orchestre le pipeline complet
  • download.py — wrapper yt-dlp pour le téléchargement vidéo et la récupération des sous-titres
  • frames.py — wrapper ffmpeg avec logique auto-fps et trois modes d'extraction
  • transcribe.py — analyse VTT, déduplication, et orchestration Whisper
  • whisper.py — clients Groq / OpenAI (Python pur, sans dépendances lourdes)
  • config.py — configuration partagée via ~/.config/watch/.env
  • setup.py — vérifications préalables et installation des dépendances

Le pipeline est simple : télécharger → extraire les images → transcrire → dédupliquer → envoyer à Claude. Chaque étape peut fonctionner indépendamment, facilitant le débogage et la personnalisation.

Limitations

  • Vidéos longues avec modes limités — au-delà de ~10 minutes, la couverture des images s'amincit. Utilisez --start/--end pour une analyse ciblée ou --detail token-burner pour une couverture sans limite.
  • Coût en tokens — les tokens d'image s'accumulent rapidement. À 512px de largeur, chaque image coûte ~197 tokens (selon la tarification Anthropic). Une analyse de 100 images coûte ~19,7k tokens rien qu'en images.
  • Clé API Whisper nécessaire — les vidéos sans sous-titres nécessitent une clé API Groq ou OpenAI pour la transcription. Les sous-titres natifs couvrent la plupart des vidéos YouTube publiques gratuitement.
  • Dépendance réseau — l'outil télécharge le contenu vidéo/audio à chaque exécution. L'utilisation hors ligne nécessite des fichiers locaux pré-téléchargés.

Ressources

Comparaison avec les alternatives

  • Outils développeur du navigateur — permettent d'inspecter les requêtes réseau mais n'offrent ni extraction d'images vidéo ni analyse multimodale. claude-video automatise tout le pipeline de l'URL à la réponse.
  • Lecture manuelle de transcript — lire un transcript seul manque 90% du contexte visuel (changements d'interface, langage corporel, code à l'écran). claude-video combine images + transcript pour une analyse multimodale complète.
  • Outils de résumé vidéo — les outils existants génèrent des résumés à partir des transcriptions seulement, manquant le contenu visuel. claude-video donne à Claude une vision réelle de chaque image.
  • Scripts personnalisés — vous pourriez script yt-dlp + ffmpeg + Whisper manuellement, mais claude-video regroupe tout en une seule commande /watch avec auto-fps, déduplication, et extraction multi-mode intégrée.