CLI do HyperFrames
Empacota o npx hyperframes para o pipeline do motor de marketing. Requer Node.js >= 22 e FFmpeg no PATH (npx hyperframes doctor verifica). Todos os comandos são executados em modo seguro DRY_RUN por padrão — as passagens de lint/inspect não fazem chamadas externas; apenas o render escreve um MP4.
Quando invocar
- Imediatamente após o
hyperframes-prompt-builderproduzir um projeto emoutputs/<cliente>/<data>/<id-da-peça>/. - Sempre que uma composição precisar de validação antes da publicação (
lint+inspect). - Para pré-visualização local durante a iteração de uma peça (
preview). - Para a renderização final que produz o artefato coletado pela etapa de publicação (
render). - Para solucionar problemas de ambiente quando a renderização falha (
doctor,browser,info).
Entradas
project_path: string. Caminho para o projeto HyperFrames (deve conterindex.htmlecomposition.json).mode:"lint" | "inspect" | "preview" | "render" | "doctor".render_opts: objeto, opcional, apenas paramode = "render". Chaves reconhecidas:fps: 24 | 30 | 60 (padrão 30).quality:"draft" | "standard" | "high"(padrão"standard"; use"draft"durante iteração).format:"mp4" | "webm"(padrão"mp4").variables: objeto. Objeto JSON chaveado por ID de variável, substitui os padrões dedata-composition-variables.strict: booleano. Mapeia para--strict. Padrãotrueno pipeline — falha na renderização com erros de lint.strict_variables: booleano. Mapeia para--strict-variables. Padrãotruepara execuções de peça.workers: inteiro 1-8 ou"auto". Padrão"auto".output: string. Caminho do arquivo de saída dentro deoutputs/<cliente>/<data>/<id-da-peça>/.
Processo
- Verificar ambiente na primeira execução de uma sessão:
npx hyperframes doctor. Reporte FFmpeg ou Chrome ausentes como bloqueio grave — não tente renderizar. - Lint.
npx hyperframes lint <project_path> --json. Trate todas as descobertas de nívelerrorcomo bloqueadoras. Avisos são reportados ao orquestrador; deixe o operador decidir. - Inspect.
npx hyperframes inspect <project_path> --json. Resolva qualquer relato de overflow de texto ou escape de canvas antes de renderizar. Se o overflow for intencional para uma entrada/saída, marque o elemento comdata-layout-allow-overflow(ou o ancestral comdata-layout-ignorepara elementos decorativos) — não silencie a regra globalmente. - Preview (apenas operador).
npx hyperframes preview <project_path> --port <port>. Devolva a URL do projeto Studio (http://localhost:<port>/#project/<nome-do-projeto>), não o caminho doindex.htmlfonte. - Renderizar.
npx hyperframes render <project_path>com as flags resolvidas derender_opts. Construa o argumento--variablesa partir derender_opts.variablesusando uma string JSON de linha única. Sempre passe--stricte--strict-variablespara execuções de peça. - Verificar saída. Após a renderização, verifique se o MP4 existe e não está com zero bytes. Registre em
data/video-usage.jsonlcom{ ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms }.
Saídas
lint:{ pass: boolean, errors: [...], warnings: [...] }.inspect:{ pass: boolean, findings: [...] }.render:{ artifact_path: string, duration_s: number, file_bytes: number, render_ms: number }.preview:{ url: string }.
Folha de dicas de comandos
npx hyperframes init <nome> # scaffold (usado uma vez por peça pelo prompt builder)
npx hyperframes lint <caminho> # validar marcação
npx hyperframes inspect <caminho> # auditoria de layout/overflow
npx hyperframes preview <caminho> --port 3017 # dev local
npx hyperframes render <caminho> \
--fps 30 --quality standard --strict --strict-variables \
--variables '{"leads":42,"delta_pct":12}' \
--output outputs/<cliente>/<data>/<id-da-peça>/final.mp4
npx hyperframes doctor # verificação de ambiente
npx hyperframes info # versão/detalhes do ambiente
Regras não negociáveis
- Nunca renderize sem uma passagem de
linteinspectaprovada. O pipeline não tem caminho de recuperação para uma composição malformada. - Nunca silencie uma descoberta de lint ou inspect globalmente — corrija a marcação ou coloque na lista de permissões o elemento específico com
data-layout-allow-overflow/data-layout-ignore. - Para peças com variáveis declaradas, sempre passe
--strict-variables. Um erro de digitação no ID da variável deve falhar ruidosamente, não cair silenciosamente no padrão. - Para renderizações de entrega final,
--quality high. Para loops de iteração,--quality draftpara economizar computação. - O pré-processamento de assets (
tts,transcribe,remove-background) está fora do escopo desta habilidade — invoque-os através de uma futura habilidadehyperframes-mediaem vez de inserir aqui.
Modos de falha
doctorreporta FFmpeg ou Chrome ausentes: instale através das instruções de configuração do projeto; não contorne.renderfalha comunknown variable: uma chave passada via--variablesnão está declarada emdata-composition-variables. Corrija a marcação ou remova a substituição.renderexcede o orçamento de tempo de execução: reduza--qualityparastandard, ou divida a composição em sub-composições e paralelize usando--workers.- MP4 de saída com zero bytes: execute
doctornovamente; quase sempre é uma falha do Chrome durante a captura.
Habilidades relacionadas
hyperframes: regras de criação de composição; produz o projeto que esta habilidade valida e renderiza.hyperframes-prompt-builder: briefing → especificação da composição; é executada antes desta habilidade.qa-tech-specs: é executada após esta habilidade contra o MP4 renderizado para validar especificações da plataforma.
Referência upstream
Habilidade upstream completa (todas as flags, matriz de solução de problemas, renderizações parametrizadas): https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli