CLI de HyperFrames
Todo se ejecuta a través de npx hyperframes. Requiere Node.js >= 22 y FFmpeg.
Flujo de trabajo
- Andamio —
npx hyperframes init my-video - Escribir — redactar la composición HTML (ver el skill
hyperframes) - Lint —
npx hyperframes lint - Inspección visual —
npx hyperframes inspect - Previsualizar —
npx hyperframes preview - Renderizar —
npx hyperframes render
Ejecuta lint e inspect antes de previsualizar. lint detecta data-composition-id faltantes, pistas superpuestas y líneas de tiempo no registradas. inspect abre la composición renderizada en Chrome sin cabeza, recorre la línea de tiempo e informa de texto que se sale de burbujas/contenedores o del canvas.
Andamio
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 vídeo
npx hyperframes init my-video --audio track.mp3 # con archivo de audio
npx hyperframes init my-video --example blank --tailwind # con Tailwind v4 en tiempo de ejecución 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 los medios, transcribe el audio con Whisper e instala las habilidades de codificación de IA. Úsalo en lugar de crear archivos a mano.
Al usar --tailwind, invoca el skill tailwind antes de editar clases o tokens de tema. El andamio usa Tailwind v4.2 a través del tiempo de ejecución del navegador, no la configuración de 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/. Informa errores (deben corregirse), advertencias (deberían corregirse) e información (con --verbose).
Inspección visual
npx hyperframes inspect # inspeccionar el diseño 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 de fotogramas clave
Úsalo después de lint y validate, especialmente para composiciones con burbujas de diálogo, tarjetas, subtítulos o tipografía ajustada. Informa de:
- Texto que se extiende fuera del contenedor visual o burbuja más cercana
- Texto recortado por su propia caja de ancho/alto fijo
- Texto que se extiende fuera del canvas de la composición
- Elementos hijos que escapan de contenedores de recorte
Los errores deben corregirse antes de renderizar. Las advertencias se muestran para revisión del agente; añade --strict para fallar también con advertencias. Los problemas estáticos repetidos se colapsan por defecto para que la salida JSON se mantenga compacta para las ventanas de contexto 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 ser auditado, márcalo con data-layout-ignore.
npx hyperframes layout sigue estando disponible como alias de compatibilidad para la misma pasada de inspección visual.
Previsualización
npx hyperframes preview # servir el directorio actual
npx hyperframes preview --port 4567 # puerto personalizado (por defecto 3002)
Recarga en caliente con los cambios de archivo. Abre el estudio en tu navegador automáticamente.
Al devolver un proyecto al usuario, usa la URL del proyecto de Studio, no la ruta
index.html fuente:
http://localhost:<puerto>/#project/<nombre-del-proyecto>
Usa el puerto real de la salida de previsualización y el nombre del directorio del proyecto. Por
ejemplo, después de npx hyperframes preview --port 3017 en codex-openai-video,
informa http://localhost:3017/#project/codex-openai-video.
Trata index.html solo como contexto de código fuente. Está bien enlazarlo como un
archivo de implementación, pero no lo etiquetes como el proyecto o la superficie de previsualización.
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 # salida byte-idéntica
| Indicador | 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 admite transparencia |
--workers | 1-8 o auto | auto | Cada uno inicia Chrome |
--docker | indicador | off | Salida reproducible |
--gpu | indicador | off | Codificación acelerada por GPU |
--strict | indicador | off | Fallar en errores de lint |
--strict-all | indicador | 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 | indicador | off | Fallar el renderizado en claves no declaradas o discrepancias de tipo en --variables |
Guía de calidad: draft mientras iteras, standard para revisión, high para entrega final.
Renderizados parametrizados: 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(). La CLI --variables '{"title":"Q4 Report"}' es un objeto JSON indexado por id que sobrescribe esos valores predeterminados declarados para un renderizado; las claves faltantes se mantienen, por lo que la misma composición se ejecuta sin cambios en la vista previa de desarrollo y en producción. (Los hosts de sub-composición también pueden sobrescribir por instancia con data-variable-values — misma forma de objeto, con alcance en una sola montura de la sub-composición. Consulta el skill hyperframes para el patrón completo).
Preprocesamiento de activos
npx hyperframes tts, transcribe y remove-background producen activos (audio de narración, transcripciones a nivel de palabra, vídeo transparente) que se colocan 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 (la trampa de que .en traduce no-inglés), la elección del formato de salida (VP9 alpha WebM vs ProRes) y la cadena TTS → transcribir → subtítulos, invoca el skill hyperframes-media.
Solución de problemas
npx hyperframes doctor # comprobar el entorno (Chrome, FFmpeg, Node, memoria)
npx hyperframes browser # gestionar Chrome integrado
npx hyperframes info # detalles de versión y entorno
npx hyperframes upgrade # comprobar actualizaciones
Ejecuta doctor primero si falla el renderizado. Problemas comunes: falta FFmpeg, falta Chrome, poca memoria.
Otros
npx hyperframes compositions # listar composiciones en el proyecto
npx hyperframes docs # abrir documentación
npx hyperframes benchmark . # evaluar rendimiento de renderizado