CLI de HyperFrames
Todo se ejecuta a través de npx hyperframes. Requiere Node.js >= 22 y FFmpeg.
Flujo de trabajo
- Scaffolding —
npx hyperframes init my-video - Escribir — autorizar la composición HTML (ver el skill
hyperframes) - Lint —
npx hyperframes lint - Inspección visual —
npx hyperframes inspect - Vista previa —
npx hyperframes preview - Renderizar —
npx hyperframes render
Ejecuta lint e inspect antes de la vista previa. lint detecta data-composition-id faltantes, pistas superpuestas y líneas de tiempo no registradas. inspect abre la composición renderizada en Chrome sin interfaz gráfica, recorre la línea de tiempo y reporta texto que se sale de burbujas/contenedores o del lienzo.
Scaffolding
npx hyperframes init my-video # asistente interactivo
npx hyperframes init my-video --example warm-grain # elegir un ejemplo
npx hyperframes init my-video --video clip.mp4 # con archivo de video
npx hyperframes init my-video --audio track.mp3 # con archivo de audio
npx hyperframes init my-video --example blank --tailwind # con Tailwind v4 runtime del navegador
npx hyperframes init my-video --non-interactive # saltar indicaciones (CI/agentes)
Plantillas: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.
init crea la estructura de archivos correcta, copia medios, transcribe audio con Whisper e instala skills de codificación AI. Úsalo en lugar de crear archivos manualmente.
Al usar --tailwind, invoca el skill tailwind antes de editar clases o tokens de tema. El scaffold usa Tailwind v4.2 a través del runtime del navegador, no la configuración Tailwind v3 de Studio.
Linting
npx hyperframes lint # directorio actual
npx hyperframes lint ./my-project # proyecto específico
npx hyperframes lint --verbose # hallazgos a nivel de información
npx hyperframes lint --json # legible por máquina
Analiza index.html y todos los archivos en compositions/. Reporta errores (deben corregirse), advertencias (deberían corregirse) e información (con --verbose).
Inspección visual
npx hyperframes inspect # inspeccionar layout renderizado a lo largo de la línea de tiempo
npx hyperframes inspect ./my-project # proyecto específico
npx hyperframes inspect --json # hallazgos legibles por el agente
npx hyperframes inspect --samples 15 # barrido más denso de la línea de tiempo
npx hyperframes inspect --at 1.5,4,7.25 # marcas de tiempo explícitas del fotograma principal
Úsalo después de lint y validate, especialmente para composiciones con burbujas de diálogo, tarjetas, subtítulos o tipografía ajustada. Reporta:
- Texto que se extiende fuera del contenedor visual o burbuja más cercano
- Texto recortado por su propia caja de ancho/alto fijo
- Texto que se extiende fuera del lienzo de la composición
- Hijos que escapan de contenedores con recorte
Los errores deben corregirse antes del renderizado. Las advertencias se muestran para revisión del agente; añade --strict para fallar también en advertencias. Los problemas estáticos repetidos se colapsan por defecto para que la salida JSON se mantenga compacta para los contextos de ventana de los LLM. Si el desbordamiento es intencional para una animación de entrada/salida, marca el elemento o ancestro con data-layout-allow-overflow. Si un elemento decorativo nunca debe auditarse, márcalo con data-layout-ignore.
npx hyperframes layout sigue disponible como alias de compatibilidad para la misma pasada de inspección visual.
Vista previa
npx hyperframes preview # servir directorio actual
npx hyperframes preview --port 4567 # puerto personalizado (por defecto 3002)
Recarga en caliente al cambiar archivos. Abre el estudio en tu navegador automáticamente.
Al devolver un proyecto al usuario, usa la URL del proyecto de Studio, no la ruta del archivo index.html fuente:
http://localhost:<port>/#project/<project-name>
Usa el puerto real de la salida de vista previa y el nombre del directorio del proyecto. Por ejemplo, después de npx hyperframes preview --port 3017 en codex-openai-video, reporta http://localhost:3017/#project/codex-openai-video.
Trata index.html solo como contexto de código fuente. Está bien vincularlo como archivo de implementación, pero no lo etiquetes como el proyecto o la superficie de vista previa.
Renderizado
npx hyperframes render # MP4 estándar
npx hyperframes render --output final.mp4 # salida con nombre
npx hyperframes render --quality draft # iteración rápida
npx hyperframes render --fps 60 --quality high # entrega final
npx hyperframes render --format webm # WebM transparente
npx hyperframes render --docker # idéntico byte por byte
| Flag | Opciones | Por defecto | Notas |
|---|---|---|---|
--output | ruta | renders/nombre_timestamp.mp4 | Ruta de salida |
--fps | 24, 30, 60 | 30 | 60fps duplica el tiempo de renderizado |
--quality | draft, standard, high | standard | draft para iterar |
--format | mp4, webm | mp4 | WebM soporta transparencia |
--workers | 1-8 o auto | auto | Cada uno ejecuta Chrome |
--docker | flag | off | Salida reproducible |
--gpu | flag | off | Codificación acelerada por GPU |
--strict | flag | off | Fallar en errores de lint |
--strict-all | flag | off | Fallar en errores Y advertencias |
--variables | objeto JSON | — | Sobrescribir valores de variables declaradas en data-composition-variables |
--variables-file | ruta | — | Archivo JSON con valores de variables (alternativa a --variables) |
--strict-variables | flag | off | Fallar renderizado en claves no declaradas o tipos incorrectos en --variables |
Guía de calidad: draft mientras iteramos, standard para revisión, high para entrega final.
Renderizados paramétricos: la composición declara sus variables en la raíz <html> con data-composition-variables — un array de declaraciones JSON ({id, type, label, default} por entrada) que define el esquema. Los scripts internos leen los valores resueltos mediante window.__hyperframes.getVariables(). El CLI --variables '{"title":"Q4 Report"}' es un objeto JSON con clave id que sobrescribe los valores por defecto declarados para un renderizado; las claves faltantes usan los valores por defecto, por lo que la misma composición se ejecuta sin cambios tanto en la vista previa de desarrollo como en producción. (Los hosts de subcomposiciones también pueden sobrescribir por instancia con data-variable-values — misma forma de objeto, con alcance a una única carga de la subcomposición. Consulta el skill hyperframes para el patrón completo.)
Preprocesamiento de assets
npx hyperframes tts, transcribe, y remove-background producen assets (audio de narración, transcripciones palabra por palabra, video transparente) que se insertan en una composición. Cada uno descarga su propio modelo en la primera ejecución. Para la selección de voz, las reglas del modelo whisper (el detalle de que .en traduce no-inglés), la elección del formato de salida (WebM alfa VP9 vs ProRes) y la cadena TTS → transcribir → subtítulos, invoca el skill hyperframes-media.
Solución de problemas
npx hyperframes doctor # verificar entorno (Chrome, FFmpeg, Node, memoria)
npx hyperframes browser # gestionar Chrome incluido
npx hyperframes info # versión y detalles del entorno
npx hyperframes upgrade # buscar actualizaciones
Ejecuta doctor primero si el renderizado falla. Problemas comunes: FFmpeg faltante, Chrome faltante, poca memoria.
Otros
npx hyperframes compositions # listar composiciones en el proyecto
npx hyperframes docs # abrir documentación
npx hyperframes benchmark . # comparar rendimiento de renderizado