claude-motion-explainer (HyperFrames 版)

Ciclo de revisión (HyperFrames Edition)

No puedes ver el vídeo, pero sí puedes ver los fotogramas. Nunca declares el vídeo como completo sin haber visto el contact sheet de la "versión actual".

Adaptado del skill review-loop de whaleyxbt/claude-motion (MIT, ver LICENSE en la misma carpeta). Los comandos originales npm run … se han reemplazado por las herramientas HyperFrames de kinocut MCP y el script scripts/sheet.py de esta carpeta. Las secciones marcadas con "(nuevo en esta versión)" no forman parte del contenido original.

El SHEET a continuación se refiere a python "<carpeta de este skill>/scripts/sheet.py" (por ejemplo, ~/.claude/skills/review-loop/scripts/sheet.py). Todas las rutas deben ser absolutas.

Ciclo

0. Primero, la verificación automática (nuevo en esta versión): Ejecuta hyperframes check en la carpeta del proyecto. Ejecuta lint, verifica tiempos de ejecución, desbordamiento de diseño, animación y contraste de una sola vez (oficialmente validate/inspect están obsoletos; usa check). Corrige cualquier error antes de continuar. Para más detalles, consulta el skill oficial hyperframes-cli.
   • Las máscaras de revelado en la entrada siempre reportarán container_overflow; es intencional. Agrega data-layout-allow-overflow al contenedor de la máscara. Pero si después de estabilizarse aún reporta text_box_overflow, el contenedor es demasiado bajo y cortará texto (especialmente con caracteres chinos y superíndices); debes aumentar la altura del contenedor.
1. Borrador: hyperframes_render, con parámetro quality: "draft" y output_path configurado como <proyecto>/out/draft.mp4.
2. Contact sheet: SHEET --video <proyecto>/out/draft.mp4 --timeline <proyecto>/timeline.js --out <proyecto>/out/sheets Toma una captura 0,3 segundos después de cada beat (cuando la animación ya se ha estabilizado), las organiza en una cuadrícula de 4×2 como out/sheets/beats-N.png, y etiqueta cada fotograma con el nombre del beat y el tiempo. Cada fotograma tiene un ancho predeterminado de 360 px, que es el ancho real en dispositivos móviles.
3. Abre cada hoja con Read y verifica cada elemento según la lista de verificación a continuación.
4. Para ampliar áreas sospechosas:
   • Escanea una transición: SHEET --video … --from 3 --to 5 --every 0.2 --name scrub
   • Mira momentos específicos: SHEET --video … --at 3.7,3.75,3.8 --name exact
   • Mira un fotograma individual a resolución completa: hyperframes_still, con frame como número de fotograma (segundos × fps)
   • Si no quieres volver a renderizar el vídeo, también puedes usar hyperframes_snapshot con at para capturar directamente desde la composición y luego usar SHEET --images … --labels … para organizarlas.
5. Después de las correcciones, vuelve al paso 0. Solo detente cuando no encuentres ningún problema tras una ronda completa.
6. Versión final: hyperframes_render, con quality: "high" para producir el vídeo final. Luego ejecuta el paso 2 nuevamente en el vídeo final y realiza la verificación de audio (ver más abajo).

Lista de verificación

Composición

• Cada fotograma tiene un solo punto focal. Cuando dos elementos compiten por la atención, uno debe esperar.
• Sin colisiones o superposiciones no intencionadas, especialmente durante las transiciones, donde los elementos que salen y entran comparten el mismo espacio.
• Zona segura: el contenido importante no debe estar a menos de ~60 píxeles del borde.
• El fotograma 0 es la imagen real, no negro (será la miniatura en las plataformas sociales).

Texto

• No está cortado por máscaras, contenedores o bordes del fotograma (a menos que sea intencional).
• Cuando se reduce al ancho de un teléfono (las celdas del sheet), la información clave sigue siendo legible.
• Cuando debe ser leído, el texto no está en movimiento.
• (Nuevo en esta versión) Chino: sin errores tipográficos; todo en caracteres tradicionales, sin mezcla de caracteres simplificados; puntuación de ancho completo; sin caracteres faltantes en la fuente (que aparecerían como cuadros o una fuente notablemente diferente).

Ritmo

• Cada estado que debe ser leído permanece el tiempo suficiente (ver sección 4 del motion-design). Si en los fotogramas intermedios de una pausa el texto aún se mueve, la pausa es demasiado corta.
• Las escenas se superponen; no hay cortes a una pantalla en blanco.
• Las salidas son más rápidas que las entradas.

Consistencia

• Solo se usan colores de la paleta :root; el color de énfasis marca el punto clave de ese fotograma.
• El mismo elemento se ve igual en todas las escenas donde aparece.

Audio (solo cuando hay sonido)

• Forma de onda: video_audio_waveform verifica que los picos de audio coincidan con los beats del TL.
• Sonoridad (nuevo en esta versión, reemplaza el npm run wave original): ffmpeg -hide_banner -nostats -i <vídeo final> -af ebur128=peak=true -f null - Revisa el resumen final: Integrated loudness y True peak. El objetivo es −14 LUFS ±1, true peak ≤ −1 dBFS.
• Acento y emoción de la narración en chino: el usuario debe escuchar con sus oídos; no se reemplaza con puntuaciones (nuevo en esta versión).

Informe

Al finalizar, debes indicar claramente: qué se revisó, qué se corrigió y en qué hoja del sheet se puede ver el resultado. Nunca declares una corrección como resuelta sin haber vuelto a renderizar y haber visto el resultado con tus propios ojos.