ak:hyperframes
Envuelve la CLI hyperframes de HeyGen para generación programática de videos basada en HTML. Esta skill es solo documentación y envoltura — no incluye fuente de HeyGen ni skills de agente de HeyGen copiadas. Cada comando ejecuta el paquete npm publicado a través de npx, anclado a una versión conocida.
Cuándo usarla
- Videos verticales/cortos para redes sociales (1080×1920, 9:16) renderizados desde HTML/CSS.
- Clips de lanzamiento de productos, bucles promocionales, gráficos en movimiento creados como composición HTML en lugar de componentes React o editores de línea de tiempo.
- Cualquier tarea donde la fuente de verdad de la composición sea marcado HTML con atributos
data-composition-id/data-start(ver references/composition-basics.md).
No es adecuada para composiciones basadas en React, curvas de interpolación precisas por fotograma o el ecosistema de audio/subtítulos de Remotion — ver también la skill remotion instalada para esa alternativa (video programático basado en React). Tampoco es adecuada para tareas puras de codificación con FFmpeg/ImageMagick — ver la skill ak-media-processing.
Requisitos previos
- Node.js 22+
- FFmpeg en
PATH - Opcional: una clave de API de HeyGen cloud/lambda (
HEYGEN_API_KEY) para renderizado remoto; el renderizado local funciona sin ella.
Ejecuta el verificador incluido antes de comenzar cualquier trabajo de renderizado:
node scripts/verify-prereqs.mjs
# o, para salida legible por máquina:
node scripts/verify-prereqs.mjs --json
Consulta references/env-and-deps.md para instrucciones de instalación por plataforma y la nota de verificación de versión anclada.
Versión CLI anclada
Cada invocación a continuación ancla [email protected] — la última versión publicada al 2026-08-07 (npm view hyperframes version). Actualiza este anclaje en un solo lugar (este archivo + references/render-workflow.md) al actualizar; no ejecutes npx -y hyperframes ... sin anclar en scripts o documentación.
Flujo de trabajo
El bucle estándar es init → editar HTML → preview → lint → render. Invocaciones concretas completas para cada etapa están en references/render-workflow.md; la forma abreviada:
# 1. Crear un nuevo proyecto de composición.
npx -y [email protected] init mi-composicion --resolution portrait
# 2. Editar la composición HTML generada (ver composition-basics.md para el
# contrato de data-composition-id / data-start / data-width / data-height).
# 3. Previsualizar en un servidor de desarrollo local.
npx -y [email protected] preview mi-composicion
# 4. Verificar (lint) la composición antes de renderizar (detecta atributos de temporización mal formados).
npx -y [email protected] lint mi-composicion
# 5. Renderizar a MP4.
npx -y [email protected] render mi-composicion --output ./assets/videos/mi-composicion.mp4
Ejecuta siempre lint antes de render — una composición que pasa lint sin errores falla en el paso de renderizado con mucha menos frecuencia que una que salta directamente al renderizado.
Contrato de composición
Las composiciones de HyperFrames son archivos HTML simples anotados con los atributos data-composition-id, data-start, data-width y data-height en los elementos raíz. Consulta references/composition-basics.md para la referencia completa de atributos y un ejemplo vertical completo de 1080×1920.
Material de referencia
- references/heygen-skills.md — las 25 skills de agente de HeyGen a las que este envoltorio delega en lugar de reimplementar; instálalas mediante
npx -y [email protected] skillscuando se necesite experiencia más profunda específica de HyperFrames (animación, fotogramas clave, subtítulos, plantillas de lanzamiento de productos, etc.). - references/composition-basics.md — contrato de atributos de composición HTML con un ejemplo completo de preset vertical.
- references/render-workflow.md — el flujo completo
init → edit → preview → lint → rendercon cada invocación anclada. - references/env-and-deps.md — configuración de Node/FFmpeg/clave de API por plataforma.
Solución de problemas
| Síntoma | Acción |
|---|---|
command not found: ffmpeg | Ejecuta node scripts/verify-prereqs.mjs para la solución exacta para tu plataforma. |
npx hyperframes reporta una bandera desconocida | La versión anclada en este archivo podría estar desactualizada; ejecuta npx -y [email protected] --help para confirmar las banderas actuales antes de actualizar el anclaje. |
render falla con un MP4 en blanco/corto | Ejecuta lint primero; la mayoría de los fallos de renderizado son atributos data-start/data-composition-id mal formados detectados por lint. |
| Se necesita renderizado remoto/en la nube | Configura HEYGEN_API_KEY según references/env-and-deps.md, luego usa hyperframes cloud render (un comando de nivel superior independiente, no una bandera de render) — consulta references/render-workflow.md. |
Ver también
- La skill remotion instalada (
ak-remotion) — generación de video programática basada en React; úsala cuando la composición sea naturalmente un árbol de componentes React en lugar de marcado HTML. - La skill ak-html-video — un envoltorio HTML-a-MP4 separado (
nexu-io/html-video) con su propio flujo de trabajo de plantillas/Studio; usa ak-hyperframes específicamente cuando la tarea sea una composición de HeyGen HyperFrames. - La skill ak-motion-graphics — enrutador entre todas las skills de video/animación del repositorio más paquetes externos de skills de motion.