HyperFrames CLI
Todo se ejecuta a través de npx hyperframes. Requiere Node.js >= 22 y FFmpeg.
Flujo de trabajo
- Scaffold —
npx hyperframes init my-video - Escribir — autor de composición HTML (consulta la habilidad
hyperframes) - Lint —
npx hyperframes lint - Previsualizar —
npx hyperframes preview - Renderizar —
npx hyperframes render
Ejecuta lint antes de previsualizar: detecta data-composition-id faltante, pistas superpuestas, líneas de tiempo no registradas.
Scaffolding
npx hyperframes init my-video # asistente interactivo
npx hyperframes init my-video --example warm-grain # elige 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 --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 adecuada, copia medios, transcribe audio con Whisper e instala habilidades de codificación de IA. Úsalo en lugar de crear archivos a mano.
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
Verifica index.html y todos los archivos en compositions/. Reporta errores (debes corregir), advertencias (deberías corregir) e información (con --verbose).
Previsualización
npx hyperframes preview # servir directorio actual
npx hyperframes preview --port 4567 # puerto personalizado (predeterminado 3002)
Recarga automáticamente al cambiar archivos. Abre el estudio en tu navegador automáticamente.
Renderizado
npx hyperframes render # MP4 estándar (salida automática a renders/)
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 | Predeterminado | 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 | desactivado | Salida reproducible |
--gpu | indicador | desactivado | Codificación acelerada por GPU |
--strict | indicador | desactivado | Fallar en errores de lint |
--strict-all | indicador | desactivado | Fallar en errores Y advertencias |
Recomendación de calidad: usa draft mientras iteras, standard para revisión, high para la 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 existente
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 falla el renderizado. Problemas comunes: falta FFmpeg, falta Chrome, poca memoria.
Errores comunes
La ruta --out debe ser un directorio, no un nombre de archivo
npx hyperframes render --out renders/output.mp4 → ✗ error: "No es un directorio"
npx hyperframes render → ✅ sale automáticamente a renders/nombre_timestamp.mp4
Usa --output (no --out) para especificar una ruta de archivo con nombre.
La línea de tiempo raíz de index.html debe coincidir con data-composition-id de la subcomposición
Si index.html solo contiene una referencia data-composition-src (sin contenido en línea), aún necesitas un registro window.__timelines que coincida con un data-composition-id real. Buena práctica: registra window.__timelines['<id-subcomp>'] = gsap.timeline({paused:true}) — pero como las subcomposiciones registran sus propias líneas de tiempo, el bloque de script en index.html solo es necesario para pasar el lint. Usa el id de la subcomposición (no 'root').
El <div> de la subcomposición necesita data-start="0" y data-duration
El <div data-composition-id="..."> dentro de <template> debe tener data-start="0" y data-duration="N" o el lint mostrará advertencias y la reproducción podría no iniciar.
Otros
npx hyperframes compositions # listar composiciones en el proyecto
npx hyperframes docs # abrir documentación
npx hyperframes benchmark . # evaluar rendimiento de renderizado