Video Perception

Guida un server ffmpeg MCP in modo che Claude legga frame video e trascrizioni con timestamp.

di jordanrendric · jordanrendric/claude-video-vision

Richiede configurazione ★ 6.8/10

Video Perception — Guida un server ffmpeg MCP in modo che Claude legga frame video e trascrizioni con timestamp.

Cosa fa

Collega Claude Code al server MCP claude-video-vision in modo che possa leggere file video locali (.mp4, .mov, .mkv, .webm) e URL di YouTube come frame immagine più trascrizione audio con timestamp. La skill prescrive un workflow: recuperare metadati, eseguire l'analisi strutturale di ffmpeg (cambi di scena, intervalli di silenzio, movimento) prima di estrarre qualsiasi frame, quindi estrarre frame a FPS adattivi intorno ai momenti importanti. Si attiva quando un percorso di file video, un link YouTube o una richiesta di guardare, revisionare o riassumere un video appare nella conversazione.

Rapporto di test

Ho installato claude-video-vision@1.3.2 da npm in una HOME in sandbox, ho guidato il server MCP tramite JSON-RPC su stdio e ho confermato che tutti e sei gli strumenti rispondono, quindi ho generato un video di test di 3 minuti con quattro capitoli etichettati e un flash di 1 secondo "ERROR CODE 7742" a 01:37. BASELINE (video_watch ingenuo, fps auto): 100 frame / 487KB di immagini; ha catturato il flash a 00:01:37 ma ha raggiunto silenziosamente max_frames=100 e non ha mai estratto gli ultimi 41 secondi del video. Esecuzione SKILL (video_info quindi video_analyze quindi un'estrazione di segmento pianificata): video_analyze ha restituito l'esatta lista di tagli 00:00:45, 00:01:30, 00:01:37, 00:01:38, 00:02:15 più l'intervallo di silenzio 00:00:45-00:01:30 per zero token immagine — inclusi i tagli 02:15 che la baseline non ha mai visto — ma l'estrazione di segmento prescritta ha restituito solo 34KB di frame etichettati 00:00:10, 00:01:48, 00:01:41, 00:02:21, 00:02:34 e 00:03:54 (oltre la durata di 3:00) e ha mancato completamente il flash di errore. Causa principale che ho letto in dist/extractors/frames.js: -ss viene passato prima di -i mentre -to viene passato dopo, quindi ogni richiesta di finestra viene eseguita fino a EOF; l'ho riprodotta su segmenti video_watch, video_watch start_time/end_time e video_detail in una HOME pulita. La trascrizione restituisce anche un array vuoto senza avviso quando nessun backend whisper/API è configurato.

Testato il: 2026-07-21 · Claude Code 2.x (agent harness)

Installazione

git clone --depth 1 https://github.com/jordanrendric/claude-video-vision.git /tmp/video-perception-src
mkdir -p ~/.claude/skills
cp -R /tmp/video-perception-src/skills/video-perception ~/.claude/skills/video-perception
# The skill is only guidance — it is USELESS without the MCP server that provides
# video_info / video_analyze / video_watch / video_detail / video_configure / video_setup.
#
# Register the MCP server (needs Node 20+ and ffmpeg on PATH):
#   claude mcp add claude-video-vision -- npx -y claude-video-vision@latest
#
# Or install the whole plugin instead of this skill, inside Claude Code, one at a time:
#   /plugin marketplace add https://github.com/jordanrendric/claude-video-vision
#   /plugin install claude-video-vision
#   /setup-video-vision
#
# Required deps:
#   brew install ffmpeg            # frame extraction (mandatory)
#   brew install yt-dlp            # only for YouTube URLs
# Audio transcription needs a backend, otherwise transcription silently returns []:
#   export GEMINI_API_KEY=...      # free tier, backend "gemini-api"
#   brew install whisper-cpp       # fully local, backend "local"
#   export OPENAI_API_KEY=...      # paid, backend "openai"
# Config lives at ~/.claude-video-vision/config.json (set via the video_configure tool).
#
# Known defect in the published v1.3.2 server: any time-bounded request over-extracts.
# ffmpeg is called with -ss before -i but -to after -i, so asking for 01:36-01:39
# returns ~100 frames spanning 01:36-02:25. Prefer whole-video video_watch and lean on
# video_analyze for timestamps until this is fixed.

Comandi e prompt di esempio

/video-perceptionGuida un server ffmpeg MCP in modo che Claude legga frame video e trascrizioni con timestamp.

Gli skill si attivano con richieste in linguaggio naturale, senza comandi da ricordare. Dopo l'installazione, prompt come questi lo attivano (in inglese):

Watch this video and summarize what happens
Analyze this YouTube link for key moments
Review this MP4 and describe the scenes

Rapporto completo →