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 mi-video - Escribir — redactar la composición HTML (consulta la skill
hyperframes) - Lint (linting) —
npx hyperframes lint - Inspección visual —
npx hyperframes inspect - Previsualización —
npx hyperframes preview - Renderizado —
npx hyperframes render
Realiza lint e inspección 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 headless, recorre la línea de tiempo e informa si el texto se sale de burbujas/contenedores o del lienzo.
Andamio (scaffolding)
npx hyperframes init mi-video # asistente interactivo
npx hyperframes init mi-video --example grano-calido # elegir un ejemplo
npx hyperframes init mi-video --video clip.mp4 # con archivo de video
npx hyperframes init mi-video --audio pista.mp3 # con archivo de audio
npx hyperframes init mi-video --example blank --tailwind # con Tailwind v4 runtime en navegador
npx hyperframes init mi-video --non-interactive # omitir 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 el material multimedia, transcribe el audio con Whisper e instala las skills de codificación de IA. Úsalo en lugar de crear archivos manualmente.
Al usar --tailwind, invoca la skill tailwind antes de editar clases o tokens de tema. El andamio usa Tailwind v4.2 mediante el runtime del navegador, no la configuración de Tailwind v3 del Estudio.
Linting
npx hyperframes lint # directorio actual
npx hyperframes lint ./mi-proyecto # proyecto específico
npx hyperframes lint --verbose # hallazgos a nivel informativo
npx hyperframes lint --json # legible para máquina
Realiza linting sobre 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 el diseño renderizado a lo largo de la línea de tiempo
npx hyperframes inspect ./mi-proyecto # proyecto específico
npx hyperframes inspect --json # hallazgos legibles para 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 globos de diálogo, tarjetas, subtítulos o tipografía ajustada. Reporta:
- Texto que se extiende fuera del contenedor visual o globo más cercano
- Texto recortado por su propia caja de ancho/alto fijo
- Texto que se extiende fuera del lienzo de la composición
- Elementos secundarios que escapan de contenedores con recorte
Los errores deben corregirse antes de renderizar. Las advertencias se muestran para revisión del agente; añade --strict para que también fallen con advertencias. Los problemas estáticos repetidos se colapsan por defecto para que la salida JSON sea compacta en ventanas de contexto de 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.
Previsualización
npx hyperframes preview # servir directorio actual
npx hyperframes preview --port 4567 # puerto personalizado (por defecto 3002)
Se recarga automáticamente con los cambios en archivos. Abre el estudio en tu navegador automáticamente.
Al devolver un proyecto al usuario, usa la URL del proyecto del Estudio, no la ruta del archivo index.html:
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 del código fuente. Está bien enlazarlo como 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 con transparencia
npx hyperframes render --docker # salida byte-idéntica
| Bandera | Opciones | Por defecto | Notas |
|---|---|---|---|
--output | ruta | renders/nombre_timestamp.mp4 | Ruta de salida |
--fps | 24, 30, 60 | 30 | 60fps duplica tiempo de render |
--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 | bandera | off | Salida reproducible |
--gpu | bandera | off | Codificación acelerada por GPU |
--strict | bandera | off | Fallar en errores de lint |
--strict-all | bandera | off | Fallar en errores Y advertencias |
Guía de calidad: draft mientras se itera, standard para revisión, high para entrega final.
Transcripción
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt # importar existentes
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
Texto a voz
npx hyperframes tts "Texto aquí" --voice af_nova --output narracion.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list # mostrar todas las voces
Solución de problemas
npx hyperframes doctor # verificar entorno (Chrome, FFmpeg, Node, memoria)
npx hyperframes browser # gestionar Chrome empaquetado
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 . # evaluar rendimiento del renderizado