claude-motion-explainer

Loop de Revisão (HyperFrames)

Você não consegue ver vídeos, mas consegue ver imagens estáticas. Nunca reporte um vídeo como finalizado sem ter visto o contact sheet da "versão atual".

Adaptado do skill review-loop de whaleyxbt/claude-motion (MIT, veja LICENSE na mesma pasta). Os comandos originais npm run … foram substituídos pelas ferramentas HyperFrames do MCP kinocut e pelo script scripts/sheet.py desta pasta. Seções marcadas como "(novo nesta versão)" não fazem parte do conteúdo original.

Abaixo, SHEET refere-se a python "<pasta deste skill>/scripts/sheet.py" (ex.: ~/.claude/skills/review-loop/scripts/sheet.py). Todos os caminhos devem ser absolutos.

O Ciclo

0. Primeiro, passe pela verificação automática (novo nesta versão): execute hyperframes check na pasta do projeto. Ele executa lint, runtime, overflow de layout, movimento e contraste de uma vez (oficialmente validate/inspect estão obsoletos, use check). Corrija quaisquer erros antes de prosseguir. Detalhes no skill oficial hyperframes-cli.
   • A revelação de máscaras durante a entrada sempre gera container_overflow (intencional); adicione data-layout-allow-overflow no contêiner da máscara. Mas se após a animação estabilizar ainda aparecer text_box_overflow, o contêiner está muito baixo e cortará texto (especialmente em chinês e sobrescritos); aumente a altura do contêiner.
1. Rascunho: hyperframes_render com parâmetros quality: "draft" e output_path definido como <projeto>/out/draft.mp4.
2. Contact sheet: SHEET --video <projeto>/out/draft.mp4 --timeline <projeto>/timeline.js --out <projeto>/out/sheets Captura um frame 0,3 segundos após cada batida (quando a animação já estabilizou), organiza em grade 4×2, salva como out/sheets/beats-N.png, com cada quadro rotulado com o nome da batida e o tempo. Cada quadro tem 360 px de largura (largura real em dispositivos móveis).
3. Use a ferramenta Read para abrir cada sheet e verifique item por item usando a checklist abaixo.
4. Áreas suspeitas: amplie com zoom:
   • Varra uma transição: SHEET --video … --from 3 --to 5 --every 0.2 --name scrub
   • Veja momentos específicos: SHEET --video … --at 3.7,3.75,3.8 --name exact
   • Veja um quadro em resolução total: hyperframes_still com frame = número do quadro (segundos × fps)
   • Se não quiser re-exportar o vídeo, use hyperframes_snapshot com at para capturar diretamente da composição, e então SHEET --images … --labels … para montar.
5. Após corrigir, volte ao passo 0. Só pare quando um ciclo completo não encontrar nenhum problema.
6. Versão final: hyperframes_render com quality: "high" para exportar o vídeo final. Execute o passo 2 novamente no vídeo final e depois faça a verificação de áudio (veja abaixo).

Checklist

Composição

• Cada quadro tem apenas um ponto focal. Se dois elementos competirem pela atenção, um deve esperar.
• Não há colisões ou sobreposições não intencionais, especialmente durante transições, onde elementos que saem e entram compartilham o mesmo espaço.
• Zona segura: conteúdo importante deve estar a pelo menos 60 px das bordas.
• O quadro 0 é a imagem real, não um fundo preto (será a miniatura nas redes sociais).

Texto

• Nenhum texto é cortado por máscaras, contêineres ou bordas do quadro (a menos que intencional).
• Quando reduzido à largura de celular (grade da sheet), as mensagens críticas ainda são legíveis.
• O texto não está em movimento quando deve ser lido.
• (novo nesta versão) Chinês: sem erros de escrita; todos os caracteres em grafia tradicional (sem simplificados); pontuação em largura total; sem glifos ausentes (quadrados ou fontes visivelmente diferentes).

Ritmo

• Cada estado que precisa ser lido permanece visível por tempo suficiente (veja seção 4 do motion-design). Se os quadros no meio da pausa ainda mostrarem texto em movimento, a pausa é muito curta.
• As cenas se sobrepõem, não cortam para um quadro vazio.
• As saídas são mais rápidas que as entradas.

Consistência

• Apenas cores do conjunto :root são usadas; a cor de destaque marca exatamente o foco daquele quadro.
• O mesmo elemento parece idêntico em todas as cenas em que aparece.

Som (apenas se houver áudio)

• Forma de onda: video_audio_waveform verifica se os picos de áudio estão alinhados com as batidas da TL.
• Loudness (novo nesta versão, substitui o npm run wave original): ffmpeg -hide_banner -nostats -i <vídeo_final> -af ebur128=peak=true -f null - Consulte o resumo final para Integrated loudness e True peak. Alvo: −14 LUFS ±1, true peak ≤ −1 dBFS.
• Sotaque e emoção da narração em chinês: o usuário deve ouvir e confiar no próprio julgamento, não em pontuações (novo nesta versão).

Relatório

Ao concluir, informe claramente: o que foi verificado, o que foi corrigido e em qual sheet os resultados podem ser vistos. Não declare uma correção como concluída sem ter re-exportado e inspecionado pessoalmente.