HyperFrames
Descripcion general
HyperFrames es un framework de codigo abierto (Apache-2.0) de HeyGen que convierte HTML, CSS, contenido multimedia y animaciones en videos MP4 deterministas (la misma entrada siempre produce la misma salida). Analiza composiciones HTML anotadas con atributos de temporizacion data-*, utiliza Chrome sin interfaz grafica para buscar y capturar cada fotograma, y codifica el resultado con FFmpeg. No requiere paso de compilacion, ni React, ni tarifa por renderizado. Esta disenado para ser amigable con agentes: la CLI no es interactiva por defecto, por lo que se integra limpiamente en pipelines automatizados de contenido.
Usa esta habilidad para crear proyectos, escribir composiciones HTML, previsualizarlas con recarga en vivo y renderizar video con precision de fotograma, incluyendo animaciones impulsadas por GSAP, CSS, Lottie, Three.js, Anime.js o la API de Animaciones Web.
Instrucciones
Requisitos previos
Confirma el entorno antes de comenzar:
- Node.js 22+ (
node --version) - FFmpeg en el PATH (
ffmpeg -version) - El motor descarga Chrome/Chromium sin interfaz grafica en la primera ejecucion.
Creacion de un proyecto
npx hyperframes init my-video # crea un proyecto (genera index.html + package.json)
cd my-video
Si trabajas dentro de un espacio de trabajo de agente de IA, la habilidad se puede instalar con
npx skills add heygen-com/hyperframes.
Creacion de una composicion
Las composiciones son archivos index.html simples. Un elemento raiz declara el lienzo y el id de la composicion; los elementos hijos declaran cuando aparecen y cuanto duran mediante atributos data-*. Los valores de tiempo estan en segundos.
| Atributo | Proposito |
|---|---|
data-composition-id | Nombra la composicion (destino para render/inspect) |
data-start | Cuando el elemento entra en la linea de tiempo (segundos) |
data-duration | Cuanto tiempo permanece el elemento en la linea de tiempo (segundos) |
data-width / data-height | Dimensiones del lienzo en pixeles (en el elemento raiz) |
data-track-index | Orden de capa/pista para audio o video apilado |
data-volume | Nivel de audio, 0.0–1.0 |
Previsualizacion y renderizado
npx hyperframes preview # previsualizacion en navegador con recarga en vivo mientras se crea
npx hyperframes render # busca cada fotograma en Chrome sin interfaz grafica, codifica a MP4 con FFmpeg
npx hyperframes lint # valida la estructura de la composicion antes de renderizar
npx hyperframes inspect # imprime metadatos de la composicion (duracion, pistas, dimensiones)
La resolucion proviene de data-width/data-height en el elemento raiz; la tasa de fotogramas, la ruta de salida y el codec son parametros de renderizado (consulta npx hyperframes render --help para las banderas exactas de tu version instalada, ya que los nombres de las banderas evolucionan). Como la salida es determinista, volver a renderizar una entrada sin cambios se puede cachear de forma segura.
Uso del catalogo de componentes
Bloques preconstruidos (transiciones, superposiciones, subtitulos, graficos animados, mapas, efectos) se instalan en el proyecto:
npx hyperframes add flash-through-white # una transicion
npx hyperframes add data-chart # un bloque de grafico animado
npx hyperframes add instagram-follow # una superposicion social
Explora el catalogo completo en hyperframes.heygen.com/catalog, luego agrega bloques por nombre.
Animaciones
Cualquier animacion con busqueda y precision de fotograma funciona porque el motor busca cada posicion de la linea de tiempo de forma determinista, en lugar de grabar en tiempo real. Adaptadores compatibles: GSAP, animaciones CSS, Lottie, Three.js, Anime.js, WAAPI y adaptadores personalizados. Evita la aleatoriedad basada en tiempo o el movimiento impulsado por Date.now()/reloj de pared; vincula el progreso de la animacion a la linea de tiempo de la composicion para que las busquedas sean reproducibles.
Pipelines de agente / CI
La CLI no es interactiva, por lo que un flujo automatizado tipico es: generar/plantillar el HTML → hyperframes lint → hyperframes render → recolectar el MP4. Para escalar, el paquete @hyperframes/aws-lambda permite el renderizado distribuido en Lambda.
Ejemplos
Ejemplo 1: Renderizar una composicion de lanzamiento de producto
index.html:
<div id="stage" data-composition-id="launch"
data-start="0" data-width="1920" data-height="1080">
<video data-start="0" data-duration="6" src="intro.mp4"></video>
<h1 id="title" data-start="1" data-duration="4">Dia de lanzamiento</h1>
<audio data-start="0" data-duration="6" data-volume="0.8" src="music.wav"></audio>
</div>
npx hyperframes inspect # confirma: launch, 6s, 1920x1080
npx hyperframes lint # valida antes de invertir tiempo de renderizado
npx hyperframes render # produce un MP4 1080p
Ejemplo 2: Una animacion de titulo con GSAP y busqueda
<div id="stage" data-composition-id="title-card"
data-start="0" data-width="1080" data-height="1080">
<h1 id="headline" data-start="0" data-duration="3">Resultados Q3</h1>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
// Vincula el progreso a la linea de tiempo (tween pausado que el motor busca), no al tiempo real.
const tl = gsap.timeline({ paused: true });
tl.from("#headline", { y: 80, opacity: 0, duration: 1 })
.to("#headline", { scale: 1.05, duration: 2 });
window.__seek = (t) => tl.seek(t); // el motor llama a esto por fotograma
</script>
</div>
npx hyperframes preview # itera en vivo, luego:
npx hyperframes render
Directrices
- Determinismo primero. Vincula todo el movimiento a la linea de tiempo de la composicion. Evita
Math.random(),Date.now(), bucles en tiempo real o llamadas de red durante el renderizado: rompen la reproducibilidad. - Lint antes de renderizar.
hyperframes lintdetecta errores estructurales/de temporizacion de forma economica; el renderizado es el paso costoso. - Establece el lienzo en el elemento raiz.
data-width/data-heightvan en el elemento raiz de la composicion; la temporizacion de los hijos (data-start/data-duration) va en cada elemento, en segundos. - Verifica la cadena de herramientas. La mayoria de los fallos se deben a falta de FFmpeg o Node < 22, o a una descarga de Chromium bloqueada por un cortafuegos.
- Usa
--helppara banderas exactas. Las opciones derender/addvarian segun la version; confirma las banderas de fps/salida/codec con la CLI instalada en lugar de asumir. - Prefiere bloques del catalogo.
hyperframes addinstala componentes mantenidos y con busqueda, en lugar de crear transiciones y graficos manualmente. - Escala con Lambda. Para trabajos por lotes/grandes, renderiza con
@hyperframes/aws-lambdaen lugar de un trabajo local largo. - Mantiene los medios locales y versionados. Referencia los activos con rutas estables; las descargas remotas durante el renderizado socavan el determinismo y la reproducibilidad.