Como Ensinar o Claude Code a Assistir Vídeos e Compreender O Que Está Acontecendo na Tela

Ontem eu estava tentando explicar ao Claude Code exatamente quando um utilitário lança um erro em uma gravação de tela. Eu tinha que tirar manualmente uma captura de tela, cortar a área relevante e soltar o arquivo no chat. Quando há muitos bugs ou o problema aparece no minuto dez de uma gravação de reunião, essa abordagem manual fica cansativa rápido.

A maioria dos modelos de linguagem não consegue transmitir ou ler diretamente arquivos MP4 pesados. O repositório claude-video-vision do desenvolvedor Jordan Vasconcelos resolve isso de forma elegante. É um plugin para Claude Code e um servidor MCP ao mesmo tempo, funcionando como uma camada de percepção. Ele converte vídeo em um conjunto de frames e texto transcrito com timestamps, depois alimenta tudo para a rede neural.

Como funciona nos bastidores

O fluxo de trabalho aqui é bem direto. Todo o trabalho técnico de dividir e extrair dados de mídia é tratado pelo servidor MCP em Node.js.

Quando você pede ao Claude para analisar um vídeo, dois processos paralelos são iniciados:

1. ffmpeg corta frames em formato JPEG, PNG ou WebP e os codifica em base64.
2. Backend de áudio pega a faixa de som e a converte em uma transcrição de texto com timestamps.

Então o Claude recebe um conjunto pronto de imagens e texto cronológico. Um detalhe interessante: o modelo decide por conta própria qual taxa de quadros e resolução usar para dividir o vídeo.

Se você perguntar "O que está escrito na lousa no marco de 90 segundos?", o plugin não processará o vídeo inteiro de uma hora. O modelo solicitará frames de alta resolução com intervalos frequentes especificamente para o segmento de 01:25 a 01:35. Se você pedir um resumo breve de toda a palestra, o plugin diminuirá a taxa de quadros e coletará visualizações esparsas em toda a duração.

Nos bastidores: opções de backend

Para processamento de áudio, o autor forneceu três opções para escolher:

• Gemini API. O limite gratuito de 15.000 solicitações por dia cobre a maioria das tarefas e processa não apenas fala, mas também eventos sonoros de fundo. Você só precisa de uma chave de API.
• Whisper local. Funciona via whisper.cpp ou pacote Python openai-whisper. Executa completamente offline, e os modelos necessários são baixados automaticamente na primeira execução.
• OpenAI API. Usa a API Whisper paga da OpenAI se você não quiser carregar um processador local e configurar uma conta no Google AI Studio.

Vale a pena mencionar o suporte ao YouTube separadamente. Se você passar um link de vídeo, o plugin baixa via yt-dlp. O servidor primeiro tenta buscar legendas manuais. Se não estiverem disponíveis, ele obtém as legendas geradas automaticamente do YouTube. Se as legendas estiverem faltando ou muito fragmentadas, o backend de áudio selecionado entra em ação. O Claude vê a fonte da transcrição e entende o nível de precisão do texto.

Configuração e primeiros comandos

O plugin é instalado diretamente em uma sessão do Claude Code. Basta executar os comandos sequencialmente:

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

Após a instalação, um assistente de configuração interativo é iniciado:

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

O assistente verifica se ffmpeg está instalado, permite escolher um backend de áudio e baixa o modelo Whisper se você selecionou o modo offline. A configuração é salva em ~/.claude-video-vision/config.json. Lá você pode definir a resolução de frame padrão, o formato da imagem (por exemplo, PNG é útil para texto nítido em capturas de tela) e o número máximo de frames por solicitação.

Você pode trabalhar com o plugin via comandos especiais ou em um formato de chat normal:

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

Ou simplesmente digite no chat:

Olhe para o primeiro segundo do bug em ~/videos/bug-report.mov e me diga o que deu errado.

Onde isso é útil

A ferramenta cobre várias tarefas comuns de desenvolvimento:

1. Análise de relatórios de bugs. Um usuário ou engenheiro de QA enviou uma gravação de tela. Em vez de assistir ao vídeo novamente, você pode soltar o arquivo no Claude e perguntar qual erro apareceu no console no terceiro segundo.
2. Tomar notas em apresentações e tutoriais. Você pode soltar um link para uma apresentação do YouTube de uma hora e obter um esboço estruturado com timestamps e capturas de tela dos slides principais.
3. Revisão de animações de UI. Quando os frames são enviados em formato PNG sem perda, o modelo pode avaliar o layout e a suavidade das transições no vídeo.
4. Busca rápida em gravações de reuniões. Uma gravação de reunião de uma hora pode ser rapidamente filtrada por tópicos-chave sem perder tempo com navegação manual.

Vale a pena tentar

O projeto é novo, mas já tem mais de mil estrelas no GitHub. Os principais pontos fortes são arquitetura bem pensada, tratamento sensato da janela de contexto através de fps adaptativo e a capacidade de trabalhar completamente localmente via whisper.cpp.

Algumas ressalvas: requer que ffmpeg esteja instalado, e yt-dlp é necessário para vídeos do YouTube. No macOS, todas as dependências são instaladas via Homebrew em alguns cliques; em outros sistemas operacionais, você precisará instalá-las manualmente.

Se você usa ativamente o Claude Code no terminal e trabalha regularmente com gravações de vídeo ou clipes de demonstração, este plugin economizará uma quantidade significativa de tempo.