tzezhang1-crypto/claude-motion-explainer-video

Ciclo de Revisão (versão HyperFrames)

Você não consegue assistir vídeos, mas consegue ver quadros. Nunca reporte um vídeo como finalizado sem ter visto o contact sheet da versão atual.

Adaptado da skill review-loop do 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. Parágrafos marcados como "(novo nesta versão)" não fazem parte do conteúdo original.

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

O Ciclo

0. Primeiro, verificação automática (novo nesta versão): Execute hyperframes check na pasta do projeto. Ele executa lint, tempo de execução, vazamento de layout, movimento e contraste de uma só vez (oficialmente validate/inspect foram depreciados; use check). Corrija erros antes de prosseguir. Detalhes na skill oficial hyperframes-cli.
   • Revelações por máscara inevitavelmente geram container_overflow durante a entrada, o que é intencional; adicione data-layout-allow-overflow ao contêiner da máscara. Mas se, após a estabilização, ainda houver text_box_overflow, significa que o contêiner é muito baixo e cortará o texto (especialmente caracteres chineses e sobrescritos); aumente a altura do contêiner.
1. Rascunho: hyperframes_render, parâmetros quality: "draft", 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 quadro 0,3 segundos após cada batida (quando o movimento já estabilizou), monta em 4×2 como out/sheets/beats-N.png, cada quadro rotulado com o nome da batida e o tempo. Cada quadro tem 360 px de largura por padrão, que é a largura real em um feed de celular.
3. Abra cada sheet com Read e verifique item por item na checklist abaixo.
4. Amplie áreas suspeitas:
   • 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, preencha frame com o número do quadro (segundos × fps)
   • Quando não quiser renderizar o vídeo novamente, use hyperframes_snapshot com at para capturar diretamente da composição e monte com SHEET --images … --labels ….
5. Após corrigir, volte ao passo 0. Pare somente quando uma rodada completa não encontrar problemas.
6. Versão final: hyperframes_render, parâmetros quality: "high" para exportar o vídeo finalizado. Em seguida, execute o passo 2 novamente no vídeo finalizado e faça a verificação de áudio (veja abaixo).

Checklist

Composição

• Cada quadro tem apenas um ponto focal. Quando dois elementos disputam atenção, um deve esperar.
• Sem colisões ou sobreposições não intencionais, especialmente durante transições, quando elementos saindo e entrando compartilham o mesmo espaço.
• Zona segura: Conteúdo importante não deve ficar a menos de ~60 px das bordas.
• O quadro 0 é a imagem real, não preto (ele será a miniatura nas redes sociais).

Texto

• Não cortado por máscaras, contêineres ou bordas do quadro (a menos que intencional).
• Quando reduzido à largura de celular (grade da sheet), as informações principais ainda são legíveis.
• O texto não está em movimento no momento em que deve ser lido.
• (Novo nesta versão) Chinês: Sem erros de caractere; todos devem estar em caracteres tradicionais, sem mistura com simplificados; pontuação em largura total; sem caracteres ausentes na fonte (exibindo quadrados vazios ou fontes visivelmente diferentes).

Ritmo

• Cada estado que deve ser lido permanece tempo suficiente (veja seção 4 de motion-design). Se, em quadros intermediários de uma pausa, o texto ainda estiver se movendo, a pausa é muito curta.
• As cenas se sobrepõem, não cortam para um quadro em branco.
• A saída é mais rápida que a entrada.

Consistência

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

Áudio (apenas se houver áudio)

• Forma de onda: video_audio_waveform verifica se os picos de áudio coincidem com as batidas da TL.
• Loudness (novo nesta versão, substitui o npm run wave original): ffmpeg -hide_banner -nostats -i <video_final> -af ebur128=peak=true -f null - Verifique o resumo final para Integrated loudness e True peak. Alvo: −14 LUFS ±1, true peak ≤ −1 dBFS.
• Acento e emoção da narração em chinês: o usuário deve ouvir com os ouvidos, não confiar em métricas (novo nesta versão).

Relatório

Ao finalizar, informe claramente: o que foi verificado, o que foi corrigido e em qual sheet o resultado pode ser visto. Não declare que uma correção foi feita sem ter reexportado e visto pessoalmente o resultado.