Claude Eye: análise de animação quadro a quadro
Você não pode assistir a um vídeo, mas pode ler imagens. Esta habilidade transforma um vídeo em um conjunto de quadros com timestamp, faz com que você observe cada quadro e registre o que cada elemento animado está fazendo, e então transforma essas observações em uma linha do tempo que mostra exatamente quando as coisas saem de sincronia. Bugs de temporização em animações CSS/JS geralmente são da ordem de 100-300 ms, muito rápidos para serem percebidos a olho nu, mas fáceis de ver em uma tabela de quadros.
Os scripts ficam ao lado deste arquivo em scripts/. Eles precisam apenas de Node 18+ e ffmpeg/ffprobe, sem necessidade de npm install. Abaixo, <skill> significa o diretório desta habilidade.
1. Verificar pré-requisitos
Execute ffmpeg -version. Se estiver faltando, informe ao usuário e forneça o comando de instalação para o sistema operacional dele (Windows: winget install Gyan.FFmpeg ou choco install ffmpeg; macOS: brew install ffmpeg; Linux: sudo apt install ffmpeg). Eles precisarão de um novo terminal após a instalação. Não instale você mesmo sem perguntar.
2. Extrair quadros
node <skill>/scripts/extract_frames.mjs <video> --fps 5 --out ./claude-eye-output [--start S] [--end S] [--width 960]
Isso escreve frames/frame_NNNN.png mais um manifest.json que mapeia cada número de quadro para seu timestamp. Sempre use os timestamps do manifesto, nunca os calcule de cabeça.
Controle sua leitura de imagens. Cada quadro lido consome contexto, então mire em cerca de 40 quadros ou menos por passada:
- Clipe curto (menos de ~8 s): 5 fps em todo o clipe é suficiente.
- Clipe mais longo, ou você não sabe onde está o problema: faça uma passada grossa primeiro (
--fps 1ou2em todo o vídeo) para encontrar onde as coisas se movem. Em seguida, reextraia apenas essa janela em fps mais alto (--start/--end,--fps 10-15) em um diretório--outseparado. Relate a passada fina. - Se o usuário nomear um momento ("por volta de 3 segundos", "quando o título aparece"), vá direto para essa janela.
A largura padrão de 960 px é suficiente para julgar opacidade e posição. Use uma --width maior apenas se os elementos forem minúsculos.
3. Observar os quadros e registrar observações
Leia os quadros em ordem com a ferramenta Read. Para cada quadro, observe todo elemento visível de texto/UI que está animando ou poderia estar: títulos, subtítulos, botões, imagens, spans de destaque, sobreposições e assim por diante.
Mantenha nomes de seletores estáveis entre quadros: escolha um nome descritivo em kebab-case na primeira vez que vir um elemento (hero-title, subtitle, cta-button) e reutilize exatamente esse nome em todos os quadros seguintes. A linha do tempo junta quadros pelo nome, então hero-title em um quadro e title no próximo se tornam dois elementos diferentes e a análise falha. Inclua um elemento com 0% assim que ele aparecer ou for conhecido como existente. Isso torna os pontos "oculto → entrando em transição" visíveis.
Para cada elemento, estime:
opacity_percent(0-100). Julgue em relação ao fundo e à aparência totalmente visível do elemento em quadros posteriores. Revele também revelações parciais: um clip-path ou máscara que está 40% revelada conta como 40.state: um dehidden(≤10%),transitioning-in(subindo),visible(≥90%),transitioning-out(descendo). Compare com quadros vizinhos para distinguir "entrando" de "saindo".- Opcional:
has_gradient,has_blurenotespara coisas como movimento ("translateY ~20px acima da posição final"), escala, quantidade de desfoque ou mudança de cor. Movimento e escala são tão importantes quanto opacidade, então registre-os emnotesquando os vir.
Escreva tudo em <out>/frames.json:
[
{
"frame": 1,
"elements": [
{ "selector": "hero-title", "opacity_percent": 0, "state": "hidden" },
{ "selector": "subtitle", "opacity_percent": 0, "state": "hidden" }
],
"overall_state": "pre-animation",
"observation": "Área do herói em branco; nada renderizado ainda."
}
]
frame deve corresponder aos números de quadro do manifesto. Os timestamps são preenchidos a partir do manifesto. Para execuções longas, escreva o arquivo em partes conforme avança, em vez de manter 40 quadros na memória.
A opacidade de um vídeo comprimido é aproximada. Uma diferença de ±10% entre quadros é ruído; padrões ao longo de vários quadros são o sinal.
4. Construir o relatório
node <skill>/scripts/build_report.mjs ./claude-eye-output --context "o que a animação deveria fazer"
Isso produz report.md (resumo, tabela de linha do tempo de opacidade, temporização por elemento, pontos de transição, eventos de dessincronização, observações) e analysis.json. Uma dessincronização é um quadro onde alguns elementos estão totalmente visíveis enquanto outros ainda estão em transição, com mais de 40 pontos de diferença de opacidade entre eles. Use --spread N para tornar isso mais ou menos rigoroso.
5. Interpretar: é aqui que você agrega valor
O script encontra quando as coisas acontecem. Seu trabalho é dizer por que e o que mudar:
- Substitua a seção
<!-- RECOMENDATIONS -->dereport.mdpor descobertas específicas. Leia a tabela de temporização dos elementos: por exemplo, "subtitlecomeça 200 ms depois dehero-titlee atinge a opacidade total 400 ms depois, o que aponta para uma duração maior combinada com um atraso." Converta diferenças de quadros em milissegundos usando o espaçamento entre quadros (1/fps). - Se o código-fonte do usuário estiver disponível, encontre o CSS/JS para esses elementos (
transition,animation,@keyframes,transition-delay, configurações do framer-motion/GSAP) e aponte para as linhas exatas que explicam a temporização observada. Proponha a correção concreta. - Mencione sua precisão de temporização (±1 quadro = ±1/fps s). Se uma conclusão depender de uma diferença menor que um quadro, reextraia essa janela em um fps mais alto antes de afirmá-la.
Em seguida, forneça ao usuário um breve resumo no chat: o que anima, as principais temporizações, cada dessincronização com seu timestamp e causa provável, e a correção. Inclua o caminho para report.md.
Não apenas opacidade
O pipeline de relatório é construído em torno de opacidade/visibilidade, mas a mesma abordagem de leitura de quadros funciona para outras questões, como mudança de layout, um elemento pulando, cintilação (um quadro com estado errado), um carregador girando quando não deveria, ou easing que parece linear. Para esses casos, ainda extraia quadros e leia-os. Você pode pular build_report.mjs e responder diretamente com timestamps referenciados por quadro do manifesto.