tzezhang1-crypto/claude-motion-explainer-video

Motion explainer (versión mejorada) — Animación para explicar principios, fotos como evidencia, videos IA para emoción

Esta skill encadena en un flujo fijo: "buscar información en internet → escribir guion → locución en chino → hacer animación cuadro por cuadro → subtítulos → esquema de colores → buscar fotos con licencia, generar imágenes conceptuales → generar video IA → auto-revisión → exportar MP4". En comparación con la versión básica motion-explainer, añade la capa de imágenes de la sección 7.5, la capa de video IA de la sección 7.6, y la sección 4 para corregir palabras mal pronunciadas; el resto de pasos son idénticos. El material de video se genera principalmente con IA: noticias, vídeos promocionales y material de archivo casi siempre tienen derechos de autor, no se recortan en vídeos educativos. Se apoya sobre tres pilares:

• HyperFrames (código abierto de HeyGen, HTML + GSAP para exportar MP4) y sus skills oficiales, especialmente la entrada /hyperframes y el flujo de trabajo /faceless-explainer. El método sigue lo oficial.
• Los skills motion-design (reglas de estilo: easing, ritmo, pausas, tipografía china) y review-loop (auto-revisión con contact sheet) de este repositorio. La estética se rige por estos dos.
• Las herramientas de la carpeta scripts/: complementan lo que el flujo oficial no maneja bien en locución china, subtítulos, consistencia tipográfica y tema de tres colores.

references/lessons.md recoge los errores reales cometidos; léelo antes de empezar, cada consejo ocurrió realmente en el primer video.

0. Comprobación del entorno (primera vez)

• Primero ejecuta python scripts/hw_check.py --project <proyecto>: detectará CPU, memoria, GPU y disco, y recomendará qué motor de locución usar, cuántos --workers poner y si los sub-agentes deben dividirse en lotes. Explica al usuario según references/hardware.md; las recomendaciones son estimaciones, no benchmarks.
• Node.js 22+, ffmpeg/ffprobe, Python 3 + Pillow + fonttools (pip install fonttools; si se instala brotli las fuentes se exportan como woff2, si no, como ttf).
• HyperFrames CLI: npm install -g hyperframes, luego ejecuta hyperframes doctor (Docker, Whisper, Kokoro, MusicGen son opcionales).
• Skills oficiales: hyperframes skills update, para este tipo de videos también hyperframes skills update faceless-explainer.
• Las estadísticas de uso anónimo están activadas por defecto; pregunta al usuario si quiere desactivarlas con hyperframes telemetry disable.
• TTS (elegir uno, preguntar al usuario):
  • edge-tts (por defecto): pip install edge-tts, no requiere GPU, necesita conexión a internet para generar. Acento taiwanés: zh-TW-HsiaoChenNeural (femenina), zh-TW-HsiaoYuNeural (femenina), zh-TW-YunJheNeural (masculina).
  • Breeze TTS 2 (avanzado): GPU NVIDIA local (aprox. 7.7 GB VRAM, se recomiendan 12 GB o más; el modelo ocupa unos 7 GB). Permite diseñar la voz mediante descripción textual, luego clonarla; el control de acento y emoción es el más fino.
  • Otros motores también son válidos: siempre que para cada frase se pueda generar assets/voice/raw/NN.wav. En videos en inglés se puede usar Kokoro/HeyGen integrado en HyperFrames.

1. Investigación (cuando hay búsqueda en internet)

• Busca los datos más recientes sobre el tema, al menos dos fuentes independientes. Anota las discrepancias numéricas y adopta el valor de la fuente más coherente.
• Clasifica cada número en tres categorías para mostrarlo después en pantalla: afirmación oficial / medición o reportaje / estimación propia.
• Haz cálculos físicos o matemáticos simples tú mismo para que el espectador pueda "verificarlos"; esa es la parte más valiosa de un video educativo. Las estimaciones deben contrastarse con la realidad (por ejemplo: "un coche normal aguanta como máximo 1.2 g" queda refutado por un coche de calle que acelera de 0 a 100 en 1.8 segundos; hay que cambiarlo a 1.5 g).
• No uses fotos de marca ni logotipos; el protagonista se dibuja como diagrama propio, etiquetado como "diagrama ilustrativo".
• Mientras investigas, anota pistas de imágenes: ¿hay "precedentes", "predecesores", "fotos de experimentos" que sirvan como evidencia (por ejemplo, fotos históricas de la NASA, productos similares ya existentes)? Esas serán las fotos reales que buscarás en la sección 7.5.

2. Entrevista de requisitos (según la capa de intención de /hyperframes, preguntar todo de una vez)

Debes confirmar: plataforma de reproducción (determina la relación de aspecto: clase/YouTube → 16:9), duración (se recomiendan 60–90 segundos; la longitud de la locución determinará la duración real), si se quiere locución (se recomienda sí), si se quiere revisar primero el storyboard, y si se desea automatización o ajustar mientras se hace.

Además, pregunta por tres colores (nuevo en esta skill), como en una plantilla de presentación:

• Color de fondo, color principal (para texto y líneas), color de acento (solo para respuestas, conclusiones, números clave, tarjetas de capítulo).
• Si no tiene preferencia, recomienda: fondo negro #121212, texto blanco #F2F0EA, acento naranja #FF7A1A.
• Tipografía: una sola tipografía para todo el video. Por defecto, GenSeki Gothic Bold (OFL license, se usa para chino, inglés, números, subtítulos). Si el usuario especifica otra tipografía, se cambia, pero hay que verificar que esa tipografía se pueda usar libremente.
• Los colores y la tipografía se escriben en el archivo theme.json del proyecto (formato en templates/theme.example.json, campos bg/fg/accent/font).

Resume los requisitos en un resumen dividido en dos secciones: "respuestas del usuario" y "lo que infiero". Solo se empieza a trabajar después de que el usuario lo confirme.

3. Crear proyecto y storyboard

1. hyperframes init videos/<kebab-name> --non-interactive --example=blank --skill=faceless-explainer, luego escribe BRIEF.md y sigue los pasos 0–2 de /faceless-explainer (capture/extracted/, seleccionar un frame preset para generar frame.md).
2. Al elegir el preset, prioriza aquellos con líneas claras (por ejemplo, cobalt-grid). Solo es un "esquema de colores de origen", que luego será reemplazado por los tres colores del usuario mediante theme.py.
3. En frame.md, añade sobreescritura para chino tradicional (tipografía, peso, espaciado entre caracteres, interlineado, tamaño mínimo de letra para proyector), siguiendo el contenido de la sección 5 de motion-design.
4. Ejecuta bash scripts/fetch_fonts.sh <proyecto> para descargar GenSeki Gothic Bold (desde el release oficial de GitHub), las tipografías Latin que usan los frame workers y Noto TC, todo en assets/fonts/. No dependas de Google Fonts en línea.
5. Escribe STORYBOARD.md y SCRIPT.md (formato según storyboard-format / script-format oficiales). La locución debe dividirse por "cláusulas": cada coma es un punto de revelación de pantalla; los números se escriben en caracteres chinos ("cero punto ocho uno segundos") para que el TTS no los pronuncie mal.

4. Locución

1. Genera assets/voice/raw/NN.wav (un archivo por frase, NN es el número del cuadro del storyboard):
   • edge-tts: python scripts/edge_tts_voice.py --project <p> --voice zh-TW-HsiaoChenNeural [--rate -5%]. Usa la misma voz para todo el video, así la voz es naturalmente consistente; --list zh-TW lista todas las voces.
   • Breeze TTS 2: python scripts/breeze_voice.py --project <p> --breeze-repo … --model … --voice "<descripción de la voz>" --only-ref. Primero diseña una voz de referencia para que el usuario la escuche; una vez confirmada, quita --only-ref para generar todas las frases (cada una copia esta voz de referencia). Si hay un ejecutor por lotes, usa scripts/tts_jobs.py para generar la lista de trabajos.
   • Si el usuario aún no ha instalado o no está seguro de qué elegir: da recomendaciones según references/tts-setup.md, paso a paso con confirmación, sin instalar por tu cuenta.
2. Primero haz que el usuario escuche una o dos frases: que decida el acento y la emoción con su oído, no con puntuaciones. Si no le gusta, cambia de voz o ajusta la velocidad, borra los WAV antiguos y regenera.
   • Si después de terminar todo el video se descubre que una palabra se pronuncia mal (por ejemplo, una marca en inglés, un carácter polifónico): no regrabes toda la frase, porque eso cambiaría el tiempo de animación de ese cuadro. En su lugar: genera 4–6 candidatos de la misma voz y la misma frase, cambiando la semilla o la ortografía (por ejemplo, Road-ster o caracteres homófonos con el mismo tono; los subtítulos siguen usando el texto original). Colócalos en assets/voice/fix/cand/NN_X.wav. Luego ejecuta python scripts/fix_voice.py --project . audition --line N --clauses <la cláusula donde está esa palabra>, que concatena el fragmento clave en un archivo de prueba para que el usuario seleccione con su oído. Después de seleccionar, ejecuta apply --line N --take NN_X; estirará o comprimirá la nueva frase completa para que tenga la misma duración que la original, ajustará el volumen al de la frase original y recalculará el tiempo de los subtítulos de esa frase (la duración de cada cuadro no cambia). Luego reconstruye los subtítulos → patch_captions.py → borra .hyperframes/pre-theme/compositions/captions.html (de lo contrario theme.py devolvería los subtítulos antiguos) → theme.py → place_media.py → vuelve a exportar. No dividas la frase regrabada en cláusulas según las pausas y luego sincronices los tiempos: las pausas de la regrabación tendrán posiciones diferentes, y los cortes caerían en medio de las palabras, resultando en omisiones o repeticiones (ocurrió en pruebas reales). El ASR solo sirve para filtrar errores evidentes; no puede detectar si el tono es correcto (ejemplo real: "llanta" el ASR lo dio por correcto, pero el usuario lo escuchó como incorrecto).
3. python scripts/voice_meta.py --project <p>: recorta el silencio inicial y final, mide la duración de cada cláusula y escribe audio_meta.json.
4. node <faceless-explainer>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
5. Volumen: el video final debe tener aproximadamente −14 LUFS, con pico verdadero ≤ −1 dBFS. Si la locución es demasiado baja, se aplica la misma ganancia con un limitador, manteniendo los niveles relativos entre frases.

5. Diseño de tomas (Paso 4)

• En shots.json (ver templates/shots.example.json), por cada cuadro escribe "número de cláusula → qué aparece en pantalla". Ejecuta python scripts/apply_shots.py --project <p> para convertir a segundos reales y escribirlo de vuelta en STORYBOARD.md.
• El campo blueprint solo puede ser <id> (Adapt), <id> (Reproduce) o compose; la explicación se pone aparte en note.
• Primero busca componentes existentes con hyperframes catalog --query; si no los hay, dibújalos tú mismo.
• Los protagonistas que aparecen repetidamente en varios cuadros (coche, persona, instrumento) se dibujan primero como un SVG compartido, con coordenadas fijas para todos los componentes; todos los workers deben copiarlo exactamente. De lo contrario, el protagonista se verá diferente en cada cuadro.

6. Hacer cada cuadro en paralelo

1. node <faceless-explainer>/scripts/frame-packets.mjs --project <p> --storyboard <p>/STORYBOARD.md
2. Copia templates/dispatch_context.md a .hyperframes/frame-packets/_dispatch_context.md y completa los valores del proyecto: dirección del video, materiales compartidos, reglas de tiempo, tipografía.
3. Asigna un sub-agente a cada cuadro, todos en paralelo. El prompt se lee en orden: _role.md → _dispatch_context.md → el packet de ese cuadro → frame.md → materiales compartidos.
4. Cuando cuadros adyacentes deben continuar la misma escena (por ejemplo, la misma regla graduada), la geometría precisa reportada por el cuadro que termine primero debe transmitirse inmediatamente al cuadro que aún está en proceso.
5. Cuando todos hayan terminado: python scripts/unify_frames.py --project <p> para unificar tipografía y posición de líneas finas.

7. Ensamblaje, subtítulos, esquema de colores

node <fe>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
node <fe>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json
python scripts/patch_captions.py --project .     # Tipografía y grosor de subtítulos en chino (por defecto negrita 700)
python scripts/theme.py --project .              # Aplica los tres colores y la tipografía de theme.json (índice, cada cuadro, subtítulos)
node <fe>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .
node <fe>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html
hyperframes lint && hyperframes check

(<fe> = carpeta del skill faceless-explainer instalado.) Cada vez que se reconstruyan los subtítulos, hay que volver a ejecutar patch_captions.py y luego theme.py. El campo accents de theme.json especifica qué elementos de cada cuadro usan el color de acento (block/fill/text); font cambia todo el texto de cada cuadro y los subtítulos a la misma tipografía y peso, sobrescribiendo la configuración original de los workers. Al cambiar la tipografía, el texto se ensancha; hay que volver a ejecutar hyperframes check para ver si hay desbordamiento o superposición.

El último paso es adelgazar la tipografía: python scripts/subset_fonts.py --project .. Esto deja solo los caracteres chinos utilizados en el video (la tipografía CJK pasa de 12–17 MB a unos pocos cientos de KB) y actualiza los @font-face de cada cuadro para que apunten al archivo adelgazado. Cualquier cambio posterior en texto, subtítulos o colores debe repetir: theme.py siempre vuelve a aplicar el color desde los archivos originales previos al color; esos archivos originales apuntan a la tipografía completa; si se añade un carácter nuevo que no está en el archivo adelgazado, se degrada a la tipografía del sistema.

7.5 Capa de imágenes (nuevo en esta skill)

Reglas completas en references/images.md. Puntos clave:

1. Planificación: 3–5 imágenes por video. Fotos reales como tarjetas de evidencia ("alguien realmente lo hizo"), imágenes generadas por Codex como fondos de ambiente para apertura y cierre. La animación es el cuerpo principal; las imágenes no deben robar protagonismo al principio explicado con líneas.
2. Buscar fotos: python scripts/find_images.py search "<palabra clave>" → get "File:…" --name <nombre corto> --project .. Solo se aceptan dominio público, CC0, CC BY, CC BY-SA; la fuente se escribe automáticamente en assets/images/web/CREDITS.md. Después de descargar, hay que revisar visualmente: personas, logotipos de otras marcas, marcas de agua deben recortarse.
3. Generar imágenes conceptuales: escribe los prompts en gen_prompts.json (ver templates/gen_prompts.example.json), ejecuta python scripts/codex_images.py --project .. Requiere Codex CLI iniciado localmente, usa el image_gen integrado, no necesita API key. Después de generar, revisa visualmente que no haya texto ni logotipos. Si no hay Codex, informa al usuario que puede usar otra herramienta de generación y colocar los PNG en assets/images/gen/.
4. Aplicar color: en media.json, escribe para cada imagen el recorte, tamaño y modo (las fotos usan duotone, las generadas usan keep), ejecuta python scripts/treat_images.py --project ..
5. Colocar: primero mira la contact sheet de cada cuadro terminado, busca áreas realmente vacías y en placements de media.json escribe: frame, mode (card/background), box, at, label, credit. Si quieres reemplazar el dibujo lineal original por la foto, usa hide. Luego, después de theme.py, ejecuta python scripts/place_media.py --project ..
6. Etiqueta en pantalla: las fotos llevan "Foto: autor · licencia · fuente", las generadas llevan "Imagen conceptual generada por IA".
7. Ejecuta hyperframes check (contraste del texto sobre la foto, superposiciones) y solo al final ejecuta subset_fonts.py, porque los pies de foto y las fuentes también tienen texto.

7.6 Capa de video IA (nuevo en esta skill)

Reglas completas en references/ai-video.md. Puntos clave:

1. Planificación: 2–4 clips por video. Se usan para el gancho inicial, una acción que no se puede filmar pero que coincide perfectamente con la locución (por ejemplo, "solo puede saltar una vez" → el coche aterriza), o la emoción final. Las escenas que requieren números exactos o direcciones de fuerza se siguen dejando al dibujo lineal.
2. Primer cuadro con imagen estática de Codex: primero genera una imagen que combine con el tema de colores según la sección 7.5; luego H3 comienza a animar desde esa imagen, para que el video y el estilo general sean coherentes.
3. Escribir la especificación: assets/videos/gen/specs/<nombre>.json (ejemplo en templates/video-specs/). Cada clip de 4–15 segundos, el sujeto se escribe "sin marca, sin texto", la acción como un evento claro en una frase, más la descripción del movimiento de cámara y el sonido.
4. Generar: python scripts/ai_video.py prompt --project . (formato oficial de seis párrafos) → run (necesita el runner de video_config.json, ver templates/video_config.example.json). Si no hay runner, entrega al usuario el prompt.txt y el primer cuadro, pídele que genere con la plantilla oficial MiniMax H3 R2V de ComfyUI y guarde el resultado en assets/videos/gen/<nombre>/clip.mp4.
5. Revisar: python scripts/ai_video.py check --project ., cada check-1.png debe revisarse visualmente: ¿hay deformaciones, piezas extrañas, texto o logotipos? ¿el tiempo de la acción coincide con la locución? Si no pasa, cambia la semilla y vuelve a generar.
6. Colocar: en placements de media.json, usa "video": "assets/videos/gen/<nombre>/clip.mp4", añade duration y opcionalmente out (para desvanecer la tarjeta antes de que termine el video). Después de theme.py, ejecuta place_media.py, luego hyperframes lint (el video debe tener id y no puede colocarse dentro de elementos con temporizador) y hyperframes check.
7. Etiqueta en pantalla: "Video generado por IA (H3)"; todos los videos se silencian, solo se usa la locución.

8. Revisión (review-loop)

• Primero hyperframes check, luego exporta el video completo en calidad draft (hyperframes render --quality draft --workers <valor recomendado por hw_check>; en la fase de revisión siempre usa draft). Captura un fotograma 0.15 segundos antes del final de cada cláusula (para obtener el estado final), compón una contact sheet con review-loop/scripts/sheet.py --video … --at …, revisa cada fotograma visualmente.
• Revisa punto por punto la lista de verificación de references/lessons.md. Corrige, vuelve a exportar y revisa hasta que no haya ningún problema en una ronda.
• Solo después de la revisión exporta la versión final: hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4, y vuelve a medir el volumen.

9. Entrega

Entrega la ruta del MP4, la duración, una contact sheet de resumen, y lista: las fuentes utilizadas, qué números son afirmaciones, cuáles son estimaciones, qué aspectos difieren de los requisitos (por ejemplo, la duración real supera lo previsto) y qué no se hizo (por ejemplo, no hay música de fondo).