CLI de HyperFrames
Todo se ejecuta a través de npx hyperframes a menos que las instrucciones del proyecto especifiquen un envoltorio local. Obedece exactamente el envoltorio local. Requiere Node.js >= 22 y FFmpeg.
Flujo de trabajo
- Andamiar —
npx hyperframes init my-video(ocapturedesde una URL).inittambién verifica las habilidades instaladas contra las últimas versiones en GitHub y actualiza el conjunto global si alguna está desactualizada. La bandera--skip-skillsactualmente está neutralizada (temporalmente, mientras el registro skills.sh se pone al día), por lo que cadainitejecuta esta comprobación y obtiene nuestras últimas habilidades independientemente. - Escribir — redacta la composición HTML (consulta la habilidad
hyperframes-core) - Lint —
npx hyperframes lint(estático, rápido — ejecútalo temprano mientras iteras) - Check —
npx hyperframes check(la puerta de enlace del navegador; añade--snapshotspara fotogramas anotados + recortes por hallazgo) - Previsualizar / editar —
npx hyperframes previewabre Studio, el editor de línea de tiempo donde el usuario puede editar manualmente cualquier cosa (no solo mirar). Revisa allí, luego pregunta antes de renderizar. - Renderizar — elige la variante:
- Iterar:
npx hyperframes render --quality draft - Entregar:
npx hyperframes render --quality high --output out.mp4 - CI / reproducción cruzada:
npx hyperframes render --docker --strict --output out.mp4 - Nube, sin infraestructura:
npx hyperframes cloud render(HeyGen aloja el renderizado; sin Chrome/FFmpeg/AWS local, ver Nube abajo) - Nube, trae tu propio AWS:
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(ver Lambda abajo)
- Iterar:
- Reportar feedback — después de verificar la salida,
npx hyperframes feedback --rating <1-5> --comment "..."una vez por tarea (ver Convenciones del Agente).
Ejecuta check antes de la previsualización. Primero ejecuta el linter (y salta el navegador por completo si hay errores de lint), luego hace todo lo que la secuencia anterior validate → inspect → snapshot hacía en una sesión de navegador y una pasada de búsqueda: errores de consola en tiempo de ejecución y solicitudes fallidas, defectos de diseño (texto saliendo de burbujas/contenedores o fuera del lienzo, superposiciones retenidas, oclusión), verificación del sidecar de movimiento (*.motion.json — entradas bajo búsqueda, orden de escalonamiento, dentro del fotograma, vivacidad) y contraste WCAG. Los fallos de contraste son errores y llevan los colores fg/bg muestreados, la relación medida vs requerida y un color sugerido compatible, por lo que la mayoría de las correcciones de contraste no necesitan captura de pantalla. Cada hallazgo lleva un selector, identidad data-*, archivo fuente de composición, bbox y tiempo de muestra — salta directamente al HTML. Los transitorios de una sola muestra se degradan a información; los hallazgos mantenidos entre muestras bloquean el código de salida (--strict también bloquea advertencias). validate, inspect y layout aún funcionan pero son alias obsoletos de partes de check.
Para trabajos con mucho movimiento, prefiere la iteración basada en instantáneas y un sidecar *.motion.json — consulta references/lint-validate-inspect.md para la disciplina y especificación de verificación de movimiento. Para comparar variantes candidatas creadas por el agente, usa npx hyperframes compare <path...> [--at <sec>] [--labels a,b,c] [--out compare.png] [--cols n] [--json] para renderizar cada composición a través de su propio tiempo de ejecución, ensamblar una hoja etiquetada, inspeccionarla lado a lado y elegir. Para selección de gradación de color, usa el hermano específico de color npx hyperframes grade-compare --for <frame> --grades grades.json (o --luts a.cube,b.cube) para renderizar cada candidato de gradación a través del tiempo de ejecución de gradación WebGL real en un PNG etiquetado antes de elegir el ganador.
Convenciones del Agente
Reglas transversales que se aplican a cada comando:
--jsonestá disponible en todos los comandos excepto en los modos servidor derender,previewyplay. Úsalo para cualquier invocación de agente / CI de los comandos compatibles; la salida incluye un sobre_meta(versión de CLI, última disponible, consejo de actualización).renderinforma el estado a través de stdout + código de salida solamente — verifica el éxito con la comprobación posterior al renderizado a continuación.preview --selection --jsonypreview --context --jsonson las excepciones de preview: no inician un servidor, consultan la sesión de Studio en ejecución del usuario y salen.doctor --jsonsiempre sale con 0, incluso cuando el entorno está roto. Verifica el campookdel payload:npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Esto aísla los pipelines de la rotación de versiones de CLI.- El modo no TTY se detecta automáticamente. Cuando
stdoutno es una TTY (CI, agentes, salida canalizada) la CLI cambia automáticamente a modo no interactivo;initentonces requiere--example. Pasa--non-interactivepara forzar este modo incluso en una TTY. - CI gating en render:
--strictfalla en errores de lint,--strict-allfalla también en advertencias,--strict-variablesfalla en claves--variablesno declaradas. - Correlaciona un bucle de verificación con
HYPERFRAMES_RUN_ID. Los orquestadores que impulsan la CLI por tarea/elemento de diseño deben establecer esta variable de entorno una vez por unidad de trabajo; cada invocación de comando la adjunta a la telemetría, ycheckemite un desglose por puerta, haciendo medibles los viajes de ida y vuelta por tarea. - Las rutas en
--jsonestán redactadas —$HOMEse convierte en el literal$HOMEpara que la salida sea segura para pegar en informes de errores y contextos de agente. - Render está controlado por el usuario. Nunca renderices automáticamente una vez que las comprobaciones pasen. Pausa en
preview, dile al usuario que el video se puede editar en Studio, y renderiza solo después de que lo apruebe. - Usa el contexto de Studio para ediciones dirigidas por el usuario. Cuando el usuario diga "este elemento seleccionado", "lo que hice clic", "selección actual" o similar, pídele que lo seleccione en Studio, luego ejecuta
npx hyperframes preview --context --json --context-fields selection. Usaselection.target.hfId/selector,selection.sourceFile,selection.currentTimeyselection.thumbnailUrldevueltos para anclar la edición. Siselectionesnullyerrors.selection.codeesno-selection, pídele al usuario que haga clic en el elemento y vuelva a ejecutar; no adivines a partir de capturas de pantalla. - Mantén el contexto de Studio compacto.
preview --context --jsondevuelve selección compacta por defecto. Añade--context-fields selection,--context-fields selection,linto--context-fields lintpara evitar inflar el contexto del agente. Usa--context-detail fullsolo cuando necesites campos pesados como estilos calculados, estilos en línea o metadatos de campo de texto. - Verificación posterior al renderizado. Después de que
renderdevuelva el código de salida 0, confirma que el archivo de salida existe y tiene un tamaño plausible antes de reportar éxito:[ -s "$OUTPUT" ] || echo "el renderizado no produjo salida". La CLI imprime◇ <path>en caso de éxito; para renderizados largos, también verifica la duración conffprobe -i "$OUTPUT" -show_format -v error. - Reporta feedback después de un renderizado exitoso. Una vez que se verifique la salida, ejecuta
npx hyperframes feedback --rating <1-5> --comment "..."una vez por tarea para reportar cómo fue la ejecución —5limpio, más bajo cuando encuentres fricción. Pon cualquier error, solución alternativa, característica faltante o comportamiento confuso que encontraste en--comment. Esta es la principal señal del proyecto; los renderizados que quedan en silencio dejan ciegos a los mantenedores. Salta solo cuando la telemetría esté deshabilitada o el usuario haya optado por no participar.- Para un error reproducible, añade
--file-issue— publica una reproducción mínima del proyecto en una URL pública y abre un issue de GitHub pre-rellenado con tu comentario + entorno. Un comentario solo casi nunca permite que un mantenedor reproduzca; la composición publicada es lo que hace que el informe sea procesable. Apunta--dir <project>a la composición fallida si no es el directorio actual. - Escribe comentarios de error que un mantenedor pueda reproducir — una paráfrasis en la que no puedan actuar desperdicia el informe. La CLI ya adjunta os/arch/mem/ffmpeg/CLI-version, así que no repitas eso; gasta el comentario en lo que solo tú viste. Para un error, incluye cada uno de estos que apliquen:
- Cadena de error exacta, textual (cópiala, no la resumas) — y si el renderizado aún produjo un archivo de salida, retrocedió silenciosamente (busca una línea de registro
[Render] … re-rendering via screenshot/falling back), o el proceso salió forzosamente sin error (Killed: 9,FATAL … heap,Target closed). "Qué timeout / qué modo de falla" es el hecho más útil. - Una reproducción mínima: la composición más pequeña (o solo el elemento ofensivo + su CSS) que aún lo muestra — ponla en línea en el comentario o menciona el archivo. Nombra el desencadenante que aíslaste (ej. "solo cuando el nodo de texto usa
font-family: 苹方", "solo a 4K", "solo con un<video>presente"). - El comando exacto + las banderas que ejecutaste, y cualquier variable de entorno establecida (
HF_*/PRODUCER_*). - Qué está mal y dónde: el número de fotograma o la marca de tiempo, y el defecto visual (texto en blanco, banda negra en la parte inferior, glifos incorrectos, lienzo congelado) vs. lo que esperabas. Una ruta de captura de pantalla si guardaste una.
- Si se reproduce solo a veces, dilo y da la tasa de aciertos.
- Cadena de error exacta, textual (cópiala, no la resumas) — y si el renderizado aún produjo un archivo de salida, retrocedió silenciosamente (busca una línea de registro
- Para un error reproducible, añade
Enrutamiento
| ¿Quieres… | Lee |
|---|---|
Andamiar un proyecto (init, capture, skills) | references/init-and-scaffold.md |
Verificar corrección (lint, check, snapshot, obsoletos validate/inspect) | references/lint-validate-inspect.md |
Previsualizar o renderizar (preview, play, render, publish) | references/preview-render.md |
Diagnosticar el entorno (doctor, browser) | references/doctor-browser.md |
Renderizar en la nube, sin infraestructura alojado por HeyGen (cloud render / list / get / delete, auth) | references/cloud.md |
Renderizar en la nube en tu propio AWS Lambda (lambda deploy / sites / render / progress / destroy / policies) | references/lambda.md |
Parametrizar / renderizar con plantillas (--variables, --variables-file, --strict-variables, --batch) | references/cloud.md + hyperframes-core (variables-and-media.md) |
Todo lo demás (info, upgrade, compositions, docs, benchmark, telemetry, preprocesamiento de activos) | references/upgrade-info-misc.md |
Transferencias entre Habilidades
- Proyectos Tailwind (
init --tailwind) → usahyperframes-core(referencia de Tailwind) antes de editar clases o tokens de tema. - Bloques/componentes del registro (
hyperframes add,hyperframes catalog) → usahyperframes-registrypara rutas de instalación, cableado de subcomposiciones y fusión de fragmentos. - Preprocesamiento de activos (
tts,transcribe,remove-background) → usamedia-usepara selección de voz, reglas del modelo Whisper, subtítulos y cadena TTS a subtítulos. - Renderizados parametrizados (
--variables) → declarados a través dedata-composition-variablesen<html>; consultahyperframes-corepara el esquema completo.
Nube (renderizado alojado por HeyGen)
hyperframes cloud render es la ruta de renderizado sin infraestructura: la CLI comprime tu proyecto, lo sube, renderiza en la nube de HeyGen y descarga el mp4. Sin Chrome, sin FFmpeg, sin AWS, y pagas por crédito. Esta es la respuesta predeterminada a "renderiza esto en la nube"; recurre a Lambda solo cuando ya posees AWS y necesitas renderizado distribuido/por fragmentos.
npx hyperframes auth login # inicio de sesión único (compartido con la CLI `heygen`)
npx hyperframes cloud render # comprimir, subir, renderizar, descargar a renders/<id>.mp4
Banderas comunes: --composition <html>, --output <path>, --quality draft|standard|high, --fps, --resolution 1080p|4k, --format mp4|webm|mov, --aspect-ratio (detectado automáticamente de data-width/data-height). Dispara y olvida con --no-wait + --callback-url; haz que los reintentos sean seguros con --idempotency-key "$(uuidgen)". Gestiona trabajos con cloud list / cloud get <id> / cloud delete <id>.
El flujo de trabajo de plantilla idiomática es subir una vez, renderizar muchas: renderiza un proyecto local una vez para obtener su asset_id, luego vuelve a enviarlo contra ese activo con diferentes --variables (salta la compresión y subida). Consulta references/cloud.md para el conjunto completo de banderas, el modelo de autenticación, los webhooks y el bucle de plantillas.
Variables (renderizados parametrizados / con plantillas)
Cualquier renderizado (local, nube o Lambda) puede llenar las ranuras de plantilla declaradas en el momento del renderizado. Las declaraciones viven en la composición (data-composition-variables); la superficie de CLI es:
npx hyperframes render --variables '{"title":"Q4 Recap","theme":"dark"}' --output q4.mp4
npx hyperframes render --variables-file ./vars.json --output out.mp4
npx hyperframes render --batch rows.json --output "renders/{name}.mp4" --strict-variables
npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Ada"}'
--strict-variables falla el renderizado en cualquier clave no declarada o discrepancia de tipo (úsalo en CI). --batch <rows.json> renderiza una salida por fila de datos con marcadores de posición de ruta {key}/{index} y escribe un manifest.json. Para el esquema completo (declarar tipos, enlaces declarativos data-var-src/data-var-text, data-variable-values por instancia para subcomposiciones y precedencia) usa la habilidad hyperframes-core (references/variables-and-media.md). El bucle de plantillas en la nube vive en references/cloud.md.
Lambda (Renderizado en la Nube)
hyperframes lambda despliega renderizado distribuido en AWS Lambda y maneja los renderizados desde tu laptop o CI. De extremo a extremo son tres comandos:
npx hyperframes lambda deploy # aprovisionar pila SAM (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy # desmantelar (el bucket S3 no se elimina a menos que se use `--force`)
La pila despliega recursos de Lambda para el renderizado, Step Functions para la orquestación, S3 para el objeto de encargo y salida. Las funciones de Lambda se ejecutan en Amazon Linux 2023 y contienen Chromium, FFmpeg y Node.js, por lo que los renderizados son idénticos a los locales. La salida se descarga una vez que --wait detecta la finalización o el fallo.
Banderas de render: --width, --height, --fps, --composition, --quality, --format, --variables, --variables-file, --batch, --strict, --strict-all, --strict-variables, --no-wait (sondeo con lambda progress <id>), --output (para renombrar la descarga). lambda sites gestiona sitios web estáticos de salida; lambda policies imprime la política IAM de la pila para auditoría.
Activos (preprocesamiento)
Comandos de preprocesamiento de activos autónomos que producen archivos listos para composición:
- TTS:
npx hyperframes tts "<text>" [--voice <id>] [--output <path>]— sintetiza voz usando la API de voz de HeyGen (requiere autenticación). Sin banderas de salida, imprime la ruta del archivo de salida en JSON. - Transcripción:
npx hyperframes transcribe <audio-file> [--output <path>] [--lang <code>] [--format srt|vtt|json|txt]— transcribe con Whisper; por defecto aclosed-captions.jsonen el directorio de activos del proyecto. Usa--format srtcuando quieras subtítulos para un editor de video. - Eliminación de fondo:
npx hyperframes remove-background <image-file> [--output <path>]— elimina el fondo de una imagen usando segmentación de IA. - Carga:
npx hyperframes upload <file-or-dir> [--to <path>]— sube activos no preprocesados al almacenamiento de activos del proyecto.
Doctor / Diagnóstico
npx hyperframes doctor # comprobación interactiva (imprime tabla de estado con consejos de reparación)
npx hyperframes doctor --json # para agentes /CI — verifica .ok, inspecciona .checks[]
Comprueba: versión de Node, FFmpeg, Chrome/Chromium accesible, GPU/WebGL (vendedor, renderizador, límites), espacio en disco, memoria, zona horaria, configuración de proxy, conexión a la API de HeyGen, habilidades instaladas (contra el registro, con consejos de actualización).
Solución de problemas de navegador: Si check o preview fallan pero doctor --json muestra chrome: ok, force el lanzamiento de Chrome por ruta con HYPERFRAMES_CHROME_PATH=/ruta/a/chrome. Para abordar problemas de WebGL/GPU directamente, usa npx hyperframes browser --headless para abrir una sesión de Chrome depurable.
Comandos de información y actualización
npx hyperframes info # versión del proyecto, habilidades, registros de cambios, créditos
npx hyperframes upgrade # actualiza la CLI global
npx hyperframes compositions # enumera/administra composiciones (list, use, rename, delete)
npx hyperframes docs # abre la documentación en el navegador
npx hyperframes benchmark # puntos de referencia del rendimiento de renderizado local
npx hyperframes telemetry # ver opciones de telemetría (enable, disable, status)
Notas de versiones anteriores
- La telemetría ahora requiere confirmación explícita (ya no se activa en
init). --non-interactiveestá disponible en todos los comandos (no solo eninit).checkahora emitelintprimero, y salta la fase de navegador si hay errores de lint (para ahorrar tiempo de arranque). Las advertencias de lint permiten que el navegador se ejecute.- El campo
_metaestá ahora presente en cada comando que soporta la bandera--json, reportandoversion,latestVersionyupdateAvailable. Se utiliza para informes de estado del agente.