HyperFrames
HTML es la fuente de verdad para el video. Una composición es un archivo HTML con atributos data-* para la sincronización, una línea de tiempo de GSAP para la animación y CSS para la apariencia. El motor de HyperFrames captura la página fotograma a fotograma y la codifica a MP4/WebM con FFmpeg.
Complemento de manim-video: Usa manim-video para explicaciones matemáticas/geométricas (ecuaciones, estilo 3B1B). Usa hyperframes para gráficos en movimiento, personas hablando con subtítulos, recorridos de productos, superposiciones para redes sociales, transiciones con shaders y cualquier cosa impulsada por medios de video/audio reales.
Cuándo usarlo
- El usuario pide un video renderizado a partir de texto, un guión o un sitio web
- Tarjetas de título animadas, tercios inferiores o intros tipográficas
- Video narrado con subtítulos (TTS + subtítulos sincronizados con la forma de onda)
- Visuales reactivas al audio (sincronización de ritmo, barras de espectro, resplandor pulsante)
- Transiciones entre escenas (fundido cruzado, barrido, deformación con shader, fundido a blanco)
- Superposiciones para redes sociales (estilo Instagram/TikTok/YouTube)
- Pipeline de sitio web a video (capturar una URL, producir un promocional)
- Cualquier animación HTML/CSS/JS que deba renderizarse de forma determinista a un archivo de video
No uses este skill para:
- Animaciones de matemáticas/ecuaciones puras (→
manim-video) - Generación de imágenes o memes (→
meme-generation, modelos de imagen) - Videoconferencias o transmisiones en vivo
Referencia rápida
npx hyperframes init mi-video # crear un proyecto
cd mi-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
Banderas 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 (una vez)
bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"
El script:
- Verifica que Node.js >= 22 y FFmpeg estén instalados (imprime instrucciones de corrección si no).
- Instala la CLI de
hyperframesglobalmente (npm install -g hyperframes@>=0.4.2). - Precarga
chrome-headless-shella través de Puppeteer — requerido para renderizado de mejor calidad mediante la ruta de capturaHeadlessExperimental.beginFramede Chrome. - Ejecuta
npx hyperframes doctore informa el resultado.
Consulta references/troubleshooting.md si la configuración falla.
Procedimiento
1. Planificar antes de escribir HTML
Antes de tocar código, articula a alto nivel:
- Qué — arco narrativo, momentos clave, golpes emocionales
- Estructura — composiciones, pistas (video/audio/superposiciones), duraciones
- Identidad visual — colores, fuentes, carácter del 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 (HARD-GATE). 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:
-
¿
DESIGN.mden la raíz del proyecto? → Usa sus colores, fuentes, reglas de movimiento y restricciones de "Qué NO Hacer". -
¿El usuario nombró un estilo? (p. ej., "Swiss Pulse", "oscuro y técnico", "marca de lujo") → Genera un
DESIGN.mdmínimo con## Style Prompt,## Colors(3-5 hex con roles),## Typography(1-2 familias),## What NOT to Do(3-5 anti-patrones). -
¿Ninguno de los 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.mda partir de las respuestas. Cada composición debe rastrear su paleta y tipografía hastaDESIGN.mdo una dirección explícita del usuario.
2. Crear proyecto
npx hyperframes init mi-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 primero el HTML+CSS estático para el fotograma héroe — 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, agrega entradas gsap.from() (anima hacia la posición CSS) y salidas gsap.to() (anima desde ella).
Consulta references/composition.md para el esquema completo de atributos de datos y reglas de composición.
4. Animar con GSAP
Cada composición debe:
- Registrar su línea de tiempo:
window.__timelines["<id-de-composición>"] = tl - Iniciar en pausa:
gsap.timeline({ paused: true })— el reproductor controla la reproducción - Usar valores
repeatfinitos (sinrepeat: -1— rompe el motor de captura). Calcula:repeat: Math.ceil(duracion / duracionDelCiclo) - 1. - Ser determinista — sin
Math.random(),Date.now()ni lógica de reloj. Usa un PRNG con semilla si necesitas pseudoaleatoriedad. - Construirse de forma síncrona — sin
async/await,setTimeoutni Promesas alrededor de la construcción de la línea de tiempo.
Consulta references/gsap.md para la API central de GSAP (tweens, eases, stagger, timelines).
5. Transiciones entre escenas
Las composiciones con múltiples escenas requieren transiciones. Reglas:
- Siempre usa una transición entre escenas — sin cortes abruptos.
- Siempre usa animaciones de entrada en cada elemento de la escena (
gsap.from(...)). - Nunca uses animaciones de salida excepto en la escena final — la transición ES la salida.
- La escena final puede desvanecerse.
Usa npx hyperframes add <nombre-de-transición> para instalar transiciones con shader (flash-through-white, liquid-wipe, etc.). Lista completa: npx hyperframes add --list.
6. Audio, subtítulos, TTS, reactividad al audio, resaltado
- Audio: siempre un elemento
<audio>separado (el video esmuted playsinline). - TTS:
npx hyperframes tts "Texto del guión" --voice af_nova --output narracion.wav. Lista de voces con--list. La primera letra del ID de 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--langsolo para sobrescribir. La fonemización en idiomas distintos al inglés requiereespeak-nginstalado en todo el sistema. - Subtítulos:
npx hyperframes transcribe narracion.wav→ transcripción a nivel de palabra. Elige el estilo según el tono de la transcripción (hype / corporativo / tutorial / narrativo / social — consulta la tabla enreferences/features.md). Regla de idioma: nunca uses modelos whisper.ena menos que el audio sea confirmadamente inglés —.entraduce audio no inglés en lugar de transcribirlo. Cada grupo de subtítulos DEBE tener una muerte duratl.set(el, { opacity: 0, visibility: "hidden" }, group.end)después de su tween de salida — de lo contrario, los grupos se filtran visibles a los posteriores. - Visuales reactivas al audio: preextrae bandas de audio (bajo / medio / agudo) y muestra por fotograma dentro de la línea de tiempo con un bucle
fordetl.call(draw, [], f / fps)— un solo tween largo NO reacciona al audio. Mapea bajo →scale(pulso), agudo →textShadow/boxShadow(resplandor), amplitud general →opacity/y/backgroundColor. Evita los clichés de barras de ecualizador — deja que el contenido guíe lo visual, el audio impulse su comportamiento. - Resaltado estilo marcador: efectos de resaltado, círculo, explosión, garabato, boceto para énfasis de texto son CSS+GSAP deterministas — consulta
references/features.md#marker-highlighting. Totalmente buscable, sin filtros SVG animados. - Transiciones de escena: cada composición con múltiples escenas DEBE usar transiciones (sin cortes abruptos). Elige entre primitivas CSS (deslizamiento, fundido cruzado borroso, zoom a través, bloques escalonados) o transiciones con shader (
flash-through-white,liquid-wipe,cross-warp-morph,chromatic-split, etc.) mediantenpx hyperframes add. Las tablas de estado de ánimo y energía viven enreferences/features.md#transitions. No mezcles transiciones CSS y shader en la misma composición.
7. Lint, validar, inspeccionar, previsualizar, renderizar
npx hyperframes lint # detecta data-composition-id faltantes, pistas superpuestas, timelines 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 ocluido
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 se envuelve más allá del área segura solo en 4.5s, una tarjeta que se desborda cuando su título tiene la variante más larga, un elemento que termina detrás de un shader de transición). Ejecuta inspect especialmente en composiciones con burbujas de diálogo, tarjetas, subtítulos o tipografía ajustada.
8. Sitio web a video (si el usuario da una URL)
Usa el flujo de trabajo de 7 pasos de captura a video en references/website-to-video.md: capturar → DESIGN.md → SCRIPT.md → storyboard → composición → renderizar → entregar.
Errores comunes
HeadlessExperimental.beginFrame' wasn't found— Chromium 147+ eliminó este protocolo. Asegúrate de estar enhyperframes@>=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) — las renderizaciones se cuelgan durante 120s y luego expiran. Ejecutanpx puppeteer browsers install chrome-headless-shell(setup.sh lo hace).hyperframes doctorinforma qué binario se usará. repeat: -1en 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 en la carga de la página. Usatl.set(selector, vars, timePosition)dentro de la línea de tiempo en su lugar, en o después deldata-startdel 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. Usamax-widthpara que el texto se ajuste. Excepción: títulos de visualización cortos donde cada palabra está deliberadamente en su propia línea.- Animar
visibilityodisplay— GSAP no puede hacer tween de estas. UsaautoAlpha(maneja tanto visibilidad como opacidad). - Llamar a
video.play()oaudio.play()— el framework posee la reproducción. Nunca los llames tú mismo. - Construir timelines asincrónicamente — el motor de captura lee
window.__timelinesde forma síncrona después de la carga de la página. Nunca envuelvas la construcción de la línea de tiempo enasync,setTimeouto una Promesa. index.htmlindependiente envuelto en<template>— oculta todo el contenido del navegador. Solo las subcomposiciones cargadas mediantedata-composition-srcusan<template>.- Usar video para audio — siempre
<video>silenciado +<audio>separado.
Verificación
Antes y después de renderizar:
- 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 problemas de diseño visual/desbordamiento — consulta troubleshooting.md si aparecen advertencias). - Coreografía de animación — para composiciones nuevas o cambios significativos de animación, ejecuta el mapa de animación.
npx hyperframes initcopia los scripts del skill en el proyecto, por lo que la ruta es local al proyecto:
Genera un úniconode skills/hyperframes/scripts/animation-map.mjs <directorio-de-composición> \ --out <directorio-de-composición>/.hyperframes/anim-mapanimation-map.jsoncon resúmenes por tween, línea de tiempo ASCII Gantt, detección de escalonamiento, zonas muertas (>1s sin animación), ciclos de vida de elementos y banderas (offscreen,collision,invisible,paced-fast<0.2s,paced-slow>2s). Escanea resúmenes y banderas — corrige o justifica cada uno. Omite en ediciones pequeñas. - El archivo existe y no es cero:
ls -lh final.mp4. - La duración coincide con
data-duration:ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4. - Verificación visual: extrae un fotograma intermedio de la composición:
ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png. - 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 de datos, contrato de línea de tiempo, reglas no negociables, reglas de tipografía/activos
- cli.md — todos los comandos CLI (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
- gsap.md — API central de GSAP para HyperFrames (tweens, eases, stagger, timelines, matchMedia)
- features.md — subtítulos, TTS, reactividad al audio, resaltado tipo marcador, transiciones (bajo demanda)
- website-to-video.md — flujo de trabajo de 7 pasos de captura a video
- troubleshooting.md — corrección de OpenClaw, variables de entorno, errores comunes de renderizado