Communitygithub.com

jgilb17/jpg

Renderiza vídeos MP4/WebM a partir de composiciones HTML.

¿Qué es jpg?

HyperFrames es una habilidad para sistemas de agentes de IA (como Claude Code, Cursor, Codex) que convierte composiciones HTML en vídeos MP4/WebM. El HTML es la fuente de verdad para el vídeo: una composición es un archivo HTML con atributos `data-*` para el tiempo, una línea de tiempo de GSAP para la animación y CSS para la apariencia. El motor HyperFrames captura la página fotograma a fotograma y la codifica con FFmpeg. Es ideal para gráficos en movimiento, vídeos con narración y subtítulos, recorridos de productos, superposiciones para redes sociales y transiciones entre escenas, complementando a `manim-video` para animaciones matemáticas/geométricas. El flujo de trabajo incluye planificación, andamio, diseño estático, animación con GSAP, adición de audio/subtítulos/TTS, linting/validación, previsualización y renderizado. Soporta renderizado con Docker para reproducibilidad, múltiples plantillas, transiciones de shader y efectos reactivos al audio. Las reglas clave incluyen: definir una identidad visual antes de escribir HTML (a través de un archivo DESIGN.md o preguntas al usuario), usar animaciones deterministas (sin `Math.random()`, `repeat: -1` o construcción asíncrona de líneas de tiempo), y seguir un procedimiento estricto de 8 pasos que va desde el andamio hasta la entrega. La habilidad también incluye verificación integral (lint, validación de contraste WCAG, inspección visual de diseño, mapa de animación) y manejo robusto de errores.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jgilb17/jpg/tree/HEAD/.claude/skills/hyperframes

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

HyperFrames

HTML es la fuente de verdad para el vídeo. Una composición es un archivo HTML con atributos data-* para el tiempo, una línea de tiempo de GSAP para la animación y CSS para la apariencia. El motor HyperFrames captura la página fotograma a fotograma y la codifica a MP4/WebM con FFmpeg.

Complemento de manim-video: Usa manim-video para explicadores matemáticos/geométricos (ecuaciones, estilo 3B1B). Usa hyperframes para gráficos en movimiento, cabezas parlantes con subtítulos, recorridos de productos, superposiciones para redes sociales, transiciones de sombreado y cualquier cosa impulsada por medios de vídeo/audio reales.

Cuándo Usarlo

  • El usuario solicita un vídeo renderizado a partir de texto, un guion o un sitio web
  • Tarjetas de título animadas, tercios inferiores o intros tipográficas
  • Vídeo de narración con subtítulos (TTS + subtítulos sincronizados con la forma de onda)
  • Visuales reactivos al audio (sincronización de ritmo, barras de espectro, brillo pulsante)
  • Transiciones de escena a escena (encadenado, barrido, deformación de sombreado, destello a blanco)
  • Superposiciones para redes sociales (estilo Instagram/TikTok/YouTube)
  • Pipeline de sitio web a vídeo (captura una URL, produce un promocional)
  • Cualquier animación HTML/CSS/JS que deba renderizarse de manera determinista a un archivo de vídeo

No uses esta habilidad para:

  • Animación pura de matemáticas/ecuaciones (→ manim-video)
  • Generación de imágenes o memes (→ meme-generation, modelos de imagen)
  • Videoconferencias en vivo o transmisión

Referencia Rápida

npx hyperframes init my-video               # andamiar un proyecto
cd my-video
npx hyperframes lint                        # validar antes de previsualizar/renderizar
npx hyperframes preview                     # previsualización en navegador con recarga en vivo (puerto 3002)
npx hyperframes render --output final.mp4   # renderizar a MP4
npx hyperframes doctor                      # diagnosticar problemas del entorno

Indicadores de renderizado: --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker (reproducible) · --strict.

Referencia completa de CLI: references/cli.md.

Configuración (única vez)

bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

El script:

  1. Verifica que Node.js >= 22 y FFmpeg estén instalados (imprime instrucciones de corrección si no).
  2. Instala la CLI de hyperframes globalmente (npm install -g hyperframes@>=0.4.2).
  3. Precarga chrome-headless-shell a través de Puppeteer — requerido para renderizado de mejor calidad a través de la ruta de captura HeadlessExperimental.beginFrame de Chrome.
  4. Ejecuta npx hyperframes doctor e informa el resultado.

Consulta references/troubleshooting.md si la configuración falla.

Procedimiento

1. Planificar antes de escribir HTML

Antes de tocar el código, articula a alto nivel:

  • Qué — arco narrativo, momentos clave, ritmos emocionales
  • Estructura — composiciones, pistas (vídeo/audio/superposiciones), duraciones
  • Identidad visual — colores, fuentes, carácter de movimiento (explosivo / cinematográfico / fluido / técnico)
  • Fotograma héroe — para cada escena, el momento en que la mayoría de los elementos son visibles simultáneamente. Este es el diseño estático que construirás primero.

Puerta de Identidad Visual (BLOQUEO DURO). Antes de escribir CUALQUIER HTML de composición, se debe definir una identidad visual. NO escribas composiciones con colores predeterminados o genéricos (#333, #3b82f6, Roboto son señales de que este paso se omitió). Verifica en orden:

  1. ¿DESIGN.md en la raíz del proyecto? → Usa sus colores exactos, fuentes, reglas de movimiento y restricciones de "Qué NO Hacer".

  2. ¿El usuario nombró un estilo? (ej. "Swiss Pulse", "oscuro y tecnológico", "marca de lujo") → Genera un DESIGN.md mínimo con ## Style Prompt, ## Colors (3-5 hex con roles), ## Typography (1-2 familias), ## What NOT to Do (3-5 anti-patrones).

  3. ¿Ninguna de las anteriores? → Haz 3 preguntas antes de escribir cualquier HTML:

    • ¿Estado de ánimo? (explosivo / cinematográfico / fluido / técnico / caótico / cálido)
    • ¿Lienzo claro u oscuro?
    • ¿Algún color de marca, fuente o referencia visual?

    Luego genera un DESIGN.md a partir de las respuestas. Cada composición debe rastrear su paleta y tipografía hasta DESIGN.md o una dirección explícita del usuario.

2. Andamiar

npx hyperframes init my-video --non-interactive

Plantillas: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. Pasa --example <nombre> para elegir una, --video clip.mp4 o --audio track.mp3 para sembrar con medios.

3. Diseño antes de animación

Escribe el HTML+CSS estático para el fotograma héroe primero — sin GSAP todavía. El contenedor .scene-content debe llenar la escena (width:100%; height:100%; padding:Npx) con display:flex + gap. Usa padding para empujar el contenido hacia adentro — nunca uses position: absolute; top: Npx en un contenedor de contenido (el contenido se desborda cuando es más alto que el espacio restante).

Solo después de que el fotograma héroe se vea bien, añade entradas gsap.from() (anima hasta la posición CSS) y salidas gsap.to() (anima desde ella).

Consulta references/composition.md para el esquema completo de atributos data y reglas de composición.

4. Animar con GSAP

Cada composición debe:

  • Registrar su línea de tiempo: window.__timelines["<id-composición>"] = tl
  • Iniciar en pausa: gsap.timeline({ paused: true }) — el reproductor controla la reproducción
  • Usar valores repeat finitos (sin repeat: -1 — rompe el motor de captura). Calcula: repeat: Math.ceil(duration / cycleDuration) - 1.
  • Ser determinista — sin Math.random(), Date.now() ni lógica de reloj. Usa un PRNG con semilla si necesitas pseudoaleatoriedad.
  • Construirse sincrónicamente — sin async/await, setTimeout o Promesas alrededor de la construcción de la línea de tiempo.

Consulta references/gsap.md para la API principal de GSAP (interpolaciones, easing, escalonamiento, líneas de tiempo).

5. Transiciones entre escenas

Las composiciones de múltiples escenas requieren transiciones. Reglas:

  1. Usa siempre una transición entre escenas — sin cortes bruscos.
  2. Usa siempre animaciones de entrada en cada elemento de la escena (gsap.from(...)).
  3. Nunca uses animaciones de salida excepto en la escena final — la transición ES la salida.
  4. La escena final puede desvanecerse.

Usa npx hyperframes add <nombre-transición> para instalar transiciones de sombreado (flash-through-white, liquid-wipe, etc.). Lista completa: npx hyperframes add --list.

6. Audio, subtítulos, TTS, reactivo al audio, resaltado

  • Audio: siempre un elemento <audio> separado (el vídeo está muted playsinline).
  • TTS: npx hyperframes tts "Texto del guion" --voice af_nova --output narration.wav. Lista de voces con --list. La primera letra del ID de la voz codifica el idioma (a/b=Inglés, e=Español, f=Francés, j=Japonés, z=Mandarín, etc.) — la CLI infiere automáticamente la configuración regional del fonemizador; pasa --lang solo para anular. La fonemización en otros idiomas requiere espeak-ng instalado en todo el sistema.
  • Subtítulos: npx hyperframes transcribe narration.wav → transcripción a nivel de palabra. Elige un estilo según el tono de la transcripción (exagerado / corporativo / tutorial / narrativo / social — consulta la tabla en references/features.md). Regla de idioma: nunca uses modelos whisper .en a menos que el audio esté confirmado como inglés — .en traduce audio no inglés en lugar de transcribirlo. Cada grupo de subtítulos DEBE tener un tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) forzado después de su interpolación de salida — de lo contrario, los grupos se filtran visibles en los posteriores.
  • Visuales reactivos al audio: pre-extrae bandas de audio (bajos / medios / agudos) y muestra por fotograma dentro de la línea de tiempo con un bucle for de tl.call(draw, [], f / fps) — una sola interpolación larga NO reacciona al audio. Mapea bajos → scale (pulso), agudos → textShadow/boxShadow (brillo), amplitud general → opacity/y/backgroundColor. Evita los clichés de barras de ecualizador — deja que el contenido guíe lo visual y el audio impulse su comportamiento.
  • Resaltado tipo marcador: efectos de resaltado, círculo, estallido, garabato, contorno para énfasis de texto son CSS+GSAP deterministas — consulta references/features.md#marker-highlighting. Totalmente buscables, sin filtros SVG animados.
  • Transiciones de escena: cada composición de múltiples escenas DEBE usar transiciones (sin cortes bruscos). Elige entre primitivas CSS (deslizamiento de empuje, encadenado borroso, zoom a través, bloques escalonados) o transiciones de sombreado (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split, etc.) a través de npx hyperframes add. Las tablas de estado de ánimo y energía están en references/features.md#transitions. No mezcles transiciones CSS y de sombreado en la misma composición.

7. Lint, validar, inspeccionar, previsualizar, renderizar

npx hyperframes lint              # detecta data-composition-id faltantes, pistas superpuestas, líneas de tiempo no registradas
npx hyperframes validate          # auditoría de contraste WCAG en 5 marcas de tiempo
npx hyperframes inspect           # auditoría de diseño visual — desbordamiento, elementos fuera del cuadro, texto oculto
npx hyperframes preview           # previsualización en navegador en vivo
npx hyperframes render --quality draft --output draft.mp4    # iteración rápida
npx hyperframes render --quality high --output final.mp4     # entrega final

hyperframes validate muestrea los píxeles de fondo detrás de cada elemento de texto y advierte sobre relaciones de contraste por debajo de 4.5:1 (o 3:1 para texto grande). hyperframes inspect es el compañero del lado del diseño — ejecuta la página en múltiples marcas de tiempo y señala problemas que un lint estático no puede ver (un subtítulo que envuelve más allá del área segura solo a los 4.5 s, una tarjeta que se desborda cuando su título es la variante más larga, un elemento que termina detrás de un sombreado de transición). Ejecuta inspect especialmente en composiciones con bocadillos de diálogo, tarjetas, subtítulos o tipografía ajustada.

8. De sitio web a vídeo (si el usuario proporciona una URL)

Usa el flujo de trabajo de captura a vídeo en 7 pasos en references/website-to-video.md: captura → DESIGN.md → SCRIPT.md → storyboard → composición → renderizado → entrega.

Errores Comunes

  • HeadlessExperimental.beginFrame' wasn't found — Chromium 147+ eliminó este protocolo. Asegúrate de usar hyperframes@>=0.4.2 (detecta automáticamente y recurre al modo de captura de pantalla). Vía de escape: export PRODUCER_FORCE_SCREENSHOT=true. Consulta hyperframes#294 y references/troubleshooting.md.
  • Chrome del sistema (no chrome-headless-shell) — los renderizados se cuelgan durante 120 s y luego agotan el tiempo de espera. Ejecuta npx puppeteer browsers install chrome-headless-shell (setup.sh lo hace). hyperframes doctor informa qué binario se usará.
  • repeat: -1 en cualquier lugar — rompe el motor de captura. Siempre calcula un recuento de repeticiones finito.
  • gsap.set() en elementos de clip que entran más tarde — el elemento no existe al cargar la página. Usa tl.set(selector, vars, timePosition) dentro de la línea de tiempo en su lugar, en o después del data-start del clip.
  • <br> dentro del texto del contenido — los saltos forzados no conocen el ancho de fuente renderizado, por lo que el ajuste natural + <br> produce dobles saltos. Usa max-width para que el texto se ajuste. Excepción: títulos cortos donde cada palabra está deliberadamente en su propia línea.
  • Animar visibility o display — GSAP no puede interpolar estos. Usa autoAlpha (maneja tanto visibilidad como opacidad).
  • Llamar a video.play() o audio.play() — el framework posee la reproducción. Nunca llames a estos tú mismo.
  • Construir líneas de tiempo de forma asíncrona — el motor de captura lee window.__timelines sincrónicamente después de cargar la página. Nunca envuelvas la construcción de líneas de tiempo en async, setTimeout o una Promesa.
  • index.html independiente envuelto en <template> — oculta todo el contenido del navegador. Solo las subcomposiciones cargadas a través de data-composition-src usan <template>.
  • Usar video para audio — siempre <video> silenciado + <audio> separado.

Verificación

Antes y después del renderizado:

  1. Pasar lint + validación + inspección: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (lint detecta problemas estructurales, validación detecta contraste, inspección detecta diseño visual / desbordamiento — consulta troubleshooting.md si aparecen advertencias).
  2. Coreografía de animación — para composiciones nuevas o cambios de animación significativos, ejecuta el mapa de animación. npx hyperframes init copia los scripts de la habilidad en el proyecto, por lo que la ruta es local al proyecto:
    node skills/hyperframes/scripts/animation-map.mjs <directorio-composición> \
      --out <directorio-composición>/.hyperframes/anim-map
    
    Genera un único animation-map.json con resúmenes por interpolación, línea de tiempo ASCII Gantt, detección de escalonamiento, zonas muertas (>1 s sin animación), ciclos de vida de elementos y banderas (offscreen, collision, invisible, paced-fast <0.2 s, paced-slow >2 s). Escanea resúmenes y banderas — corrige o justifica cada una. Omite en ediciones pequeñas.
  3. Archivo existe + no nulo: ls -lh final.mp4.
  4. Duración coincide con data-duration: ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4.
  5. Verificación visual: extrae un fotograma medio de la composición: ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
  6. Audio presente si se espera: ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1.

Si hyperframes render falla, ejecuta npx hyperframes doctor y adjunta su salida al informar.

Referencias

  • composition.md — atributos data, contrato de línea de tiempo, reglas no negociables, reglas de tipografía/activos
  • cli.md — cada comando de la CLI (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
  • gsap.md — API principal de GSAP para HyperFrames (interpolaciones, easing, escalonamiento, líneas de tiempo, matchMedia)
  • features.md — subtítulos, TTS, reactivo al audio, resaltado tipo marcador, transiciones (carga bajo demanda)
  • website-to-video.md — flujo de trabajo de captura a vídeo en 7 pasos
  • troubleshooting.md — corrección de OpenClaw, variables de entorno, errores comunes de renderizado

Skills relacionados