Come insegnare a Claude Code a guardare video e capire cosa succede sullo schermo

Ieri stavo cercando di spiegare a Claude Code esattamente quando un'utility genera un errore in una registrazione dello schermo. Ho dovuto fare manualmente uno screenshot, ritagliare l'area rilevante e inserire il file nella chat. Quando ci sono molti bug o il problema emerge al minuto dieci di una registrazione di una riunione, questo approccio manuale diventa rapidamente frustrante.

La maggior parte dei modelli linguistici non può eseguire lo streaming o leggere direttamente file MP4 pesanti. Il repository claude-video-vision dello sviluppatore Jordan Vasconcelos risolve questo problema in modo elegante. È un plugin per Claude Code e un server MCP allo stesso tempo, che funziona come un livello di percezione. Converte il video in una serie di fotogrammi e testo trascritto con timestamp, poi passa tutto alla rete neurale.

Come funziona internamente

Il flusso di lavoro qui è piuttosto semplice. Tutto il lavoro tecnico di segmentazione ed estrazione dei dati multimediali è gestito dal server MCP Node.js.

Quando chiedi a Claude di analizzare un video, si avviano due processi paralleli:

1. ffmpeg segmenta i fotogrammi in formato JPEG, PNG o WebP e li codifica in base64.
2. Backend audio prende la traccia sonora e la converte in una trascrizione testuale con timestamp.

Poi Claude riceve un set pronto di immagini e testo cronologico. Un dettaglio interessante: il modello decide autonomamente quale frequenza di fotogrammi e risoluzione usare per segmentare il video.

Se chiedi "Cosa c'è scritto sulla lavagna al secondo 90?", il plugin non elaborerà l'intero video di un'ora. Il modello richiederà fotogrammi ad alta risoluzione con intervalli frequenti specificamente per il segmento tra 01:25 e 01:35. Se chiedi un breve riassunto dell'intera lezione, il plugin abbasserà la frequenza dei fotogrammi e raccoglierà anteprime sparse per tutta la durata.

Sotto il cofano: opzioni del backend

Per l'elaborazione audio, l'autore ha fornito tre opzioni tra cui scegliere:

• Gemini API. Il limite gratuito di 15.000 richieste al giorno copre la maggior parte dei compiti ed elabora non solo il parlato ma anche gli eventi sonori di sottofondo. Serve solo una chiave API.
• Whisper locale. Funziona tramite whisper.cpp o pacchetto Python openai-whisper. Funziona completamente offline e i modelli richiesti vengono scaricati automaticamente al primo avvio.
• OpenAI API. Usa l'API Whisper a pagamento di OpenAI se non vuoi caricare un processore locale e configurare un account in Google AI Studio.

Vale la pena menzionare separatamente il supporto per YouTube. Se passi un link video, il plugin lo scarica tramite yt-dlp. Il server cerca prima di recuperare i sottotitoli manuali. Se non sono disponibili, recupera le didascalie auto-generate di YouTube. Se le didascalie mancano o sono troppo frammentate, entra in gioco il backend audio selezionato. Claude vede la fonte della trascrizione e capisce il livello di accuratezza del testo.

Configurazione e primi comandi

Il plugin si installa direttamente in una sessione di Claude Code. Basta eseguire i comandi in sequenza:

/plugin marketplace add https://github.com/jordanrendric/claude-video-vision
/plugin install claude-video-vision

Dopo l'installazione, si avvia una procedura guidata di configurazione interattiva:

/claude-video-vision:setup-video-vision

La procedura guidata verifica la presenza di ffmpeg, ti permette di scegliere un backend audio e scarica il modello Whisper se hai selezionato la modalità offline. La configurazione viene salvata in ~/.claude-video-vision/config.json. Lì puoi impostare la risoluzione predefinita dei fotogrammi, il formato dell'immagine (ad esempio, PNG è utile per testo nitido negli screenshot) e il numero massimo di fotogrammi per richiesta.

Puoi lavorare con il plugin tramite comandi speciali o in un formato di chat normale:

/watch-video ~/Downloads/demo.mp4 "какой язык программирования используется в туториале?"
/watch-video https://www.youtube.com/watch?v=... "сделай краткое содержание"

Oppure scrivi semplicemente nella chat:

Guarda il primo secondo del bug da ~/videos/bug-report.mov e dimmi cosa è andato storto.

Dove può essere utile

Lo strumento copre diversi compiti comuni di sviluppo:

1. Analisi di segnalazioni di bug. Un utente o un QA ha inviato una registrazione dello schermo. Invece di rivedere il video, puoi passare il file a Claude e chiedere quale errore è apparso nella console al terzo secondo.
2. Prendere appunti su talk e tutorial. Puoi passare un link a una presentazione YouTube di un'ora e ottenere una struttura con timestamp e screenshot delle slide chiave.
3. Revisione di animazioni UI. Quando i fotogrammi vengono inviati in formato PNG senza perdita, il modello può valutare il layout e la fluidità delle transizioni nel video.
4. Ricerca rapida nelle registrazioni di riunioni. Una registrazione di una riunione di un'ora può essere rapidamente filtrata per argomenti chiave senza perdere tempo con la navigazione manuale.

Vale la pena provarlo

Il progetto è nuovo, ma ha già oltre mille stelle su GitHub. I punti di forza principali sono l'architettura ben pensata, la gestione sensata della finestra di contesto attraverso fps adattivi e la possibilità di lavorare completamente in locale tramite whisper.cpp.

Alcune avvertenze: richiede che ffmpeg sia installato, e yt-dlp è necessario per i video di YouTube. Su macOS, tutte le dipendenze si installano tramite Homebrew in un paio di clic; su altri sistemi operativi, dovrai installarle manualmente.

Se usi attivamente Claude Code nel terminale e lavori regolarmente con registrazioni video o clip dimostrative, questo plugin ti farà risparmiare una quantità significativa di tempo.