HyperFrames: crea vídeos MP4 con HTML y agentes de IA (qué es, instalación y prueba real)

HyperFrames es un framework open source de HeyGen que convierte una página HTML en un vídeo MP4. Escribes la escena con HTML, CSS y animaciones (GSAP, CSS, Lottie, Three.js...), marcas los tiempos con atributos data-* y su CLI graba el resultado fotograma a fotograma con Chrome headless y FFmpeg. Está pensado para que lo use un agente de IA como Claude Code, Codex o Cursor, y se publica con licencia Apache 2.0.

Lo hemos instalado en Linux con la versión 0.8.170 (publicada el 18 de octubre de 2026) y hemos hecho dos vídeos reales para codigoagente, con voz femenina en español generada en local y música de fondo. Aquí tienes qué es, para qué sirve, cómo instalarlo, cómo hicimos los vídeos y los errores que nos encontramos.

Si es la primera vez que oyes hablar de skills para agentes, empieza por la guía de skills de Claude Code: HyperFrames se instala, sobre todo, como un paquete de skills.

Qué es HyperFrames y quién lo hace

El README lo resume en una línea: "Write HTML. Render video. Built for agents." Un vídeo es un archivo index.html. Cada elemento que aparece y desaparece lleva data-start y data-duration, las animaciones van en una línea de tiempo pausada que el motor puede buscar segundo a segundo, y el audio son etiquetas <audio> normales que el propio framework mezcla.

Datos que comprobamos en el repositorio heygen-com/hyperframes:

Lo usa HeyGen en producción y saca versiones casi a diario: la carpeta releases/ del repositorio guarda las notas desde la 0.6.52.

HyperFrames frente a Remotion

El propio proyecto dice que se inspira en Remotion. Los dos renderizan con Chrome headless y FFmpeg; cambia cómo se escribe el vídeo y la licencia:

Si tu equipo ya vive en React, Remotion sigue siendo una opción sólida. Si quieres que un agente genere vídeos sin montar un proyecto de React, HTML plano es más fácil de escribir y de revisar.

Para qué sirve HyperFrames

La lista del README coincide con lo que vimos en sus skills:

• Vídeos de lanzamiento de un producto o una web, a partir de su URL o de un guion.
• Explicaciones con gráficos, mapas y datos animados.
• Clips para redes con subtítulos dinámicos, overlays y música.
• Vídeos que resumen un pull request de GitHub, con el diff animado y narración.
• Piezas automáticas: el mismo HTML con otras variables genera otro vídeo, ideal para plantillas.

Lo que lo diferencia de un editor como Premiere o CapCut es que el vídeo es código: se versiona con Git, se revisa en un PR y se vuelve a renderizar idéntico ("mismo HTML, mismo vídeo"), algo útil en CI o en una tubería de contenido.

Cómo instalar HyperFrames

Hay dos caminos: con un agente de IA (el recomendado por el proyecto) o a mano con la CLI.

Con Claude Code u otro agente

Para Claude Code hay un plugin con todas las skills:

claude plugin marketplace add heygen-com/hyperframes
claude plugin install hyperframes@hyperframes

Después le pides el vídeo con /hyperframes:hyperframes. Para Codex, Cursor, Gemini CLI u OpenCode, las skills sueltas se instalan con:

npx skills add heygen-com/hyperframes

El selector se abre sin nada marcado: basta con el grupo Core Skills, porque el router /hyperframes instala cada flujo de trabajo cuando lo necesita. En ejecuciones no interactivas el README recomienda npx hyperframes skills update, que instala exactamente ese conjunto básico. Si te interesa cómo buscar más skills, lo explicamos en find-skills.

A mano con la CLI

npx hyperframes init mi-video
cd mi-video
npx hyperframes preview   # vista previa en el navegador
npx hyperframes render    # genera el MP4

Antes de renderizar conviene pasar el diagnóstico, que dice qué falta en tu equipo:

npx hyperframes doctor
npx hyperframes browser ensure   # descarga Chrome Headless Shell si no lo tienes

En nuestro servidor Linux doctor marcó tres faltas: el Chrome de render (lo resolvió browser ensure), la voz local (Kokoro) y la música generada (MusicGen). Las dos últimas son opcionales.

Prueba real: dos vídeos de codigoagente con voz y música

Queríamos comprobar si HyperFrames sirve para algo más que la demo. Hicimos dos vídeos 1920×1080 a 30 fps con la marca del blog:

1. Presentación de codigoagente (21 s): logo ~/, temas del blog y una terminal con "comandos exactos, versiones citadas, errores reales".
2. Para qué sirve HyperFrames (47 s): qué es, cómo funciona, casos de uso, el flujo con un agente y licencia. Las imágenes de este artículo son fotogramas de ese vídeo.

1. La voz femenina en español, generada en local

HyperFrames trae un comando de texto a voz que usa Kokoro-82M en tu equipo, sin API ni cuenta. Necesita Python con dos paquetes:

pip install kokoro-onnx soundfile
npx hyperframes tts --list

La primera ejecución descarga el modelo (unos 311 MB) y las voces (unos 27 MB) en ~/.cache/hyperframes/tts. Para español hay una voz femenina, Dora (ef_dora):

npx hyperframes tts "Hola, esto es código agente." -v ef_dora -o p1.wav

Generamos una frase por escena para poder sincronizar la imagen con la voz: cada archivo dura lo que dura la frase (entre 1,4 y 8,7 segundos en nuestro caso) y con ffprobe sacamos la duración exacta para colocar cada escena.

Dos trucos de pronunciación que nos funcionaron: el fonetizador lee las siglas y los nombres en inglés a la española, así que en el texto de la voz escribimos "Jáiper Freims", "hache te eme ele" o "Clod Coud" en lugar de los nombres reales (en pantalla sí aparecen bien escritos). Y "codigoagente" se lee mejor separado: "código agente".

La voz es sintética y se nota, pero se entiende bien y no cuesta nada por minuto. Si necesitas una voz más natural, el código de la CLI también admite ElevenLabs (con ELEVENLABS_API_KEY) y la voz de HeyGen si tienes cuenta.

2. La música de fondo

Para música, HyperFrames puede generarla en local con MusicGen (descarga el modelo desde Hugging Face) o usar Lyria de Google con GEMINI_API_KEY. Nosotros hicimos una base propia (acordes de La menor, Fa, Do y Sol a 96 BPM, con arpegio y bajo) con un script de Python y la colocamos con volumen bajo para que no tape la voz.

3. La composición

Cada vídeo es un único index.html. La parte que importa es esta (resumida):

<div id="root" data-composition-id="main" data-start="0" data-duration="21"
     data-width="1920" data-height="1080">
  <section id="s1" class="clip" data-start="0" data-duration="3">
    <div id="s1-mark" class="mark">~/</div>
    <span id="s1-typed" class="typed">codigoagente</span>
  </section>

  <audio id="music" src="assets/audio/musica.wav"
         data-start="0" data-duration="21" data-volume="0.3"></audio>
  <audio id="vo1" src="assets/audio/p1.wav"
         data-start="0.8" data-duration="1.75" data-volume="1"></audio>
</div>
<script>
  const tl = gsap.timeline({ paused: true });
  tl.fromTo("#s1-typed", { width: "0ch" },
            { width: "12ch", duration: 1.2, ease: "steps(12)" }, 0.6);
  window.__timelines["main"] = tl;
</script>

Las reglas que hay que respetar, sacadas de la skill hyperframes-core:

• Una sola línea de tiempo GSAP en pausa por composición, registrada en window.__timelines con el mismo id que data-composition-id.
• Todo <audio> necesita un id: sin él, el mezclador no lo encuentra y el vídeo sale mudo.
• No animes visibility ni autoAlpha en un elemento .clip (el framework controla cuándo se ve); anima sus hijos.
• Nada de Math.random(), Date.now() ni peticiones de red: el render tiene que ser determinista.
• Si usas una fuente con nombre, declárala con @font-face apuntando a un archivo local. Nosotros usamos Geist y Geist Mono, las mismas del blog.

4. Revisar y renderizar

npx hyperframes check                       # lint, runtime, layout, movimiento y contraste
npx hyperframes snapshot --at 2,8,14,18     # capturas PNG para revisar escenas
npx hyperframes render -o presentacion.mp4

check es la parte que más nos gustó: además de errores de sintaxis revisa textos que se salen de su caja y el contraste de cada texto con WCAG AA (pasaron 57 de 57 en el vídeo largo). snapshot genera además una hoja de contactos con todas las capturas, muy cómoda para que un agente revise su propio trabajo.

Tiempos reales en un servidor de 4 núcleos sin GPU:

Errores frecuentes y cómo los resolvimos

net::ERR_TUNNEL_CONNECTION_FAILED al cargar GSAP

✗ request_failed: Failed to load npm/gsap@3.14.2/dist/gsap.min.js: net::ERR_TUNNEL_CONNECTION_FAILED
✗ page_error: Cannot read properties of undefined (reading 'timeline')

La plantilla de init carga GSAP desde jsDelivr. Si tu máquina sale a internet por un proxy (una red de empresa, un contenedor en la nube), el Chrome headless del render no lo usa y no puede descargarlo. Solución: descarga gsap.min.js (por ejemplo con npm pack gsap@3.14.2), guárdalo en assets/vendor/ y cambia el <script src> a esa ruta local. De paso el vídeo deja de depender de la red, que es lo que pide la regla de determinismo.

duplicate_audio_track con varias pistas de voz

⚠ duplicate_audio_track: Multiple audible <audio>/<video> elements on track 6 overlap (assets/audio/p1.wav at 0.8-ends, assets/audio/p3.wav at 9.2-ends).

Pusimos un <audio> por frase sin data-duration, y el lint supone que cada uno dura hasta el final. Al añadir data-duration con la duración real de cada archivo, el aviso desaparece.

nested_structure_needs_subcomposition

Aparece cuando una escena <section class="clip"> tiene mucho contenido anidado. Es solo un aviso: el render sale bien. Para vídeos largos el proyecto recomienda mover cada escena a su propio archivo en compositions/ y montarlo con data-composition-src.

clipped_text durante un efecto de escritura

El efecto de máquina de escribir anima el ancho de un texto de 0ch a 12ch, así que a mitad de animación el texto está recortado a propósito. check lo marca como información, no como error.

El vídeo sale sin voz

Revisa que cada <audio> tenga id y src y que su data-start caiga dentro de la duración del vídeo. Para confirmar que hay audio sin escucharlo: ffprobe debe listar una pista aac, y ffmpeg -i video.mp4 -af volumedetect -f null - debe dar un volumen medio muy por encima de -60 dB.

Preguntas frecuentes

¿HyperFrames es gratis?

Sí. El código está bajo Apache 2.0 y el render local no tiene coste por vídeo ni límites por tamaño de empresa. HeyGen ofrece aparte un render en su nube (hyperframes cloud) que requiere cuenta.

¿Necesito saber programar?

Si lo usas con un agente, no mucho: describes el vídeo y el agente escribe el HTML, lo revisa y lo renderiza. Para retocar a mano sí ayuda saber HTML y CSS básicos.

¿Funciona en Windows?

La CLI tiene soporte para Windows en su código (rutas de extracción propias de Windows) y solo pide Node.js 22 o superior y FFmpeg. Nosotros lo probamos en Linux. La app de escritorio, por ahora, es para Mac y Linux.

¿Puedo poner mi propia voz o música?

Sí. Cualquier archivo WAV, MP3 o M4A entra con una etiqueta <audio>. La voz local con Kokoro es una opción gratuita, no una obligación.

¿HyperFrames envía datos?

La CLI tiene telemetría anónima de uso. Se consulta y se desactiva con npx hyperframes telemetry status y npx hyperframes telemetry disable.

Conclusión

HyperFrames cumple lo que promete: con HTML, una línea de tiempo de GSAP y dos comandos tienes un MP4 determinista, con voz y música, sin abrir un editor de vídeo. Donde más brilla es con un agente, porque check y snapshot le permiten revisar su propio vídeo antes de entregarlo. La voz local en español es correcta pero sintética; para un anuncio serio querrás una voz de pago o la tuya.

El siguiente paso: instala el plugin en Claude Code y pídele un vídeo corto de tu producto. Si quieres ver las mismas animaciones dentro de una página, mira las dos webs con motion graphics que hicimos con HyperFrames. Si quieres ver otras herramientas open source que sustituyen programas de pago, mira FigCraft, la alternativa a Figma, y para que tu agente trabaje con más método, Superpowers.