CLI de HyperFrames
Envuelve npx hyperframes para el pipeline del motor de marketing. Requiere Node.js >= 22 y FFmpeg en PATH (npx hyperframes doctor verifica). Todos los comandos se ejecutan en modo seguro DRY_RUN por defecto: los pases lint/inspect no realizan llamadas externas; solo render escribe un MP4.
Cuándo invocar
- Inmediatamente después de que
hyperframes-prompt-buildergenere un proyecto enoutputs/<cliente>/<fecha>/<id-pieza>/. - Siempre que una composición necesite validación antes de publicarse (
lint+inspect). - Para previsualización local durante la iteración de una pieza (
preview). - Para el renderizado final que produce el artefacto recogido por el paso de publicación (
render). - Para solucionar problemas del entorno cuando el renderizado falla (
doctor,browser,info).
Entradas
project_path: string. Ruta al proyecto HyperFrames (debe contenerindex.htmlycomposition.json).mode:"lint" | "inspect" | "preview" | "render" | "doctor".render_opts: objeto, opcional, solo paramode = "render". Claves reconocidas:fps: 24 | 30 | 60 (por defecto 30).quality:"draft" | "standard" | "high"(por defecto"standard"; usa"draft"mientras iteras).format:"mp4" | "webm"(por defecto"mp4").variables: objeto. Objeto JSON clave-valor por id de variable, sobrescribe los valores por defecto dedata-composition-variables.strict: booleano. Se asigna a--strict. Por defectotrueen el pipeline: falla el renderizado si hay errores de lint.strict_variables: booleano. Se asigna a--strict-variables. Por defectotruepara ejecuciones de piezas.workers: entero 1-8 o"auto". Por defecto"auto".output: string. Ruta del archivo de salida dentro deoutputs/<cliente>/<fecha>/<id-pieza>/.
Proceso
- Verificar entorno en la primera ejecución de una sesión:
npx hyperframes doctor. Informa la falta de FFmpeg o Chrome como un bloqueo duro: no intentes renderizar. - Lint.
npx hyperframes lint <project_path> --json. Trata todos los hallazgos de nivelerrorcomo bloqueantes. Los avisos se muestran al orquestador; deja que el operador decida. - Inspect.
npx hyperframes inspect <project_path> --json. Resuelve cualquier desbordamiento de texto o escape del lienzo reportado antes de renderizar. Si el desbordamiento es intencional para una entrada/salida, marca el elemento condata-layout-allow-overflow(o el ancestro condata-layout-ignorepara elementos decorativos); no silencies la regla globalmente. - Preview (solo operador).
npx hyperframes preview <project_path> --port <port>. Devuelve la URL del proyecto Studio (http://localhost:<port>/#project/<nombre-proyecto>), no la rutaindex.htmlfuente. - Render.
npx hyperframes render <project_path>con las banderas resueltas derender_opts. Construye el argumento--variablesa partir derender_opts.variablesusando una cadena JSON de una sola línea. Siempre pasa--stricty--strict-variablespara ejecuciones de piezas. - Verificar salida. Después del renderizado, comprueba que el MP4 existe y no es cero. Registra en
data/video-usage.jsonlcon{ ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms }.
Salidas
lint:{ pass: booleano, errors: [...], warnings: [...] }.inspect:{ pass: booleano, findings: [...] }.render:{ artifact_path: string, duration_s: número, file_bytes: número, render_ms: número }.preview:{ url: string }.
Hoja de referencia de comandos
npx hyperframes init <nombre> # andamiaje (usado una vez por pieza por el constructor de prompts)
npx hyperframes lint <ruta> # validar marcado
npx hyperframes inspect <ruta> # auditoría de diseño/desbordamiento
npx hyperframes preview <ruta> --port 3017 # desarrollo local
npx hyperframes render <ruta> \
--fps 30 --quality standard --strict --strict-variables \
--variables '{"leads":42,"delta_pct":12}' \
--output outputs/<cliente>/<fecha>/<id-pieza>/final.mp4
npx hyperframes doctor # verificación del entorno
npx hyperframes info # detalles de versión/entorno
Reglas innegociables
- Nunca renderices sin un pase exitoso de
linteinspect. El pipeline no tiene ruta de recuperación para una composición mal formada. - Nunca silencies un hallazgo de lint o inspect globalmente: corrige el marcado o incluye en lista blanca el elemento específico con
data-layout-allow-overflow/data-layout-ignore. - Para piezas con variables declaradas, siempre pasa
--strict-variables. Un error tipográfico en un id de variable debe fallar de forma audible, no pasar silenciosamente al valor por defecto. - Para renderizados de entrega final,
--quality high. Para bucles de iteración,--quality draftpara ahorrar cómputo. - El preprocesamiento de activos (
tts,transcribe,remove-background) está fuera del alcance de este skill: invócalos a través de un futuro skillhyperframes-mediaen lugar de incluirlos aquí.
Modos de fallo
doctorreporta falta de FFmpeg o Chrome: instala según las instrucciones de configuración del proyecto; no hagas soluciones alternativas.renderfalla conunknown variable: una clave pasada mediante--variablesno está declarada endata-composition-variables. Corrige el marcado o elimina la sobrescritura.renderexcede el tiempo máximo: baja--qualityastandard, o divide la composición en subcomposiciones y paraleliza mediante--workers.- El MP4 de salida tiene cero bytes: vuelve a ejecutar
doctor; casi siempre es un cierre de Chrome durante la captura.
Skills relacionados
hyperframes: reglas de autoría de composiciones; produce el proyecto que este skill valida y renderiza.hyperframes-prompt-builder: brief → especificación de composición; se ejecuta antes de este skill.qa-tech-specs: se ejecuta después de este skill contra el MP4 renderizado para validar especificaciones de plataforma.
Referencia upstream
Skill upstream completo (cada bandera, matriz de resolución de problemas, renderizados parametrizados): https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli