tzezhang1-crypto/claude-motion-explainer-video

Ciclo de revisión (versión HyperFrames)

No puedes ver el video, pero sí los fotogramas. Nunca reportes el video como terminado 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. Los párrafos marcados como "(nuevo en esta versión)" no forman parte del contenido original.

El siguiente SHEET 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, verificación automática (nuevo en esta versión): Ejecuta hyperframes check en la carpeta del proyecto. Realiza linting, verificación de tiempo de ejecución, desbordamiento de diseño, animación y contraste (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 revelaciones con máscara durante la entrada generarán inevitablemente un container_overflow; es intencional, añade data-layout-allow-overflow al contenedor de la máscara. Pero si después de asentarse sigue apareciendo text_box_overflow, el contenedor es demasiado bajo y cortará el texto (especialmente con caracteres chinos y superíndices); hay que aumentar la altura del contenedor.
1. Borrador: hyperframes_render, con parámetro quality: "draft", output_path establecido 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 tiempo (cuando la animación ya se ha estabilizado), las organiza en una cuadrícula de 4×2 como out/sheets/beats-N.png, etiquetando cada cuadro con el nombre del tiempo y su tiempo correspondiente. Cada cuadro tiene 360 px de ancho por defecto, que es el ancho real en dispositivos móviles.
3. Usa Read para abrir cada hoja y revisa punto por punto contra la lista de verificación a continuación.
4. Amplía las áreas sospechosas:
   • Escanea una transición: SHEET --video … --from 3 --to 5 --every 0.2 --name scrub
   • Observa un momento específico: SHEET --video … --at 3.7,3.75,3.8 --name exact
   • Ve un solo fotograma a resolución completa: hyperframes_still, rellena frame con el número de fotograma (segundos × fps)
   • Si no quieres volver a renderizar el video, también puedes usar hyperframes_snapshot con at para capturar directamente desde la composición, y luego combinar con SHEET --images … --labels ….
5. Después de corregir, vuelve al paso 0. Solo detente cuando una ronda completa no muestre ningún problema.
6. Versión final: hyperframes_render con quality: "high" para generar el video final, luego repite el paso 2 con ese video y realiza la verificación de audio (ver más abajo).

Lista de verificación

Composición

• Cada cuadro tiene solo un punto focal. Si dos elementos compiten por atención, uno debe esperar.
• No hay colisiones o superposiciones no intencionadas, especialmente durante las transiciones, cuando los elementos que salen y entran comparten el mismo espacio.
• Zona segura: el contenido importante no debe estar a menos de aproximadamente 60 px del borde.
• El primer cuadro es una imagen real, no negro (será la miniatura en plataformas sociales).

Texto

• No está cortado por máscaras, contenedores ni bordes del encuadre (a menos que sea intencional).
• Al reducirse al ancho de un teléfono (el tamaño de los cuadros del sheet), los mensajes clave siguen siendo legibles.
• Cuando debe leerse, el texto no se está moviendo.
• (Nuevo en esta versión) Chino: sin errores ortográficos; todo en caracteres tradicionales, sin mezclar con simplificados; signos de puntuación en ancho completo; sin caracteres faltantes en la fuente (que aparecen como cuadrados o fuentes notablemente diferentes).

Ritmo

• Cada estado que debe leerse permanece el tiempo suficiente (ver sección 4 de motion-design). Si en los cuadros intermedios el texto aún se está moviendo, la pausa es demasiado corta.
• Las escenas se superponen al transicionar, no cortan a un cuadro 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 exactamente el foco de ese cuadro.
• Un 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 tiempos en TL.
• Sonoridad (nuevo en esta versión, reemplaza el antiguo npm run wave): ffmpeg -hide_banner -nostats -i <video_final> -af ebur128=peak=true -f null - Revisa el resumen final para Integrated loudness y True peak. El objetivo es −14 LUFS ±1, true peak ≤ −1 dBFS.
• El acento y la emoción de la narración en chino deben ser evaluados por el usuario con el oído, no con una puntuación (nuevo en esta versión).

Reporte

Al finalizar, debes indicar claramente: qué se revisó, qué se corrigió y en qué hoja se pueden ver los resultados. No reclames haber corregido algo sin haber vuelto a renderizar y haberlo visto con tus propios ojos.