CLI HyperFrames
Tudo é executado através de npx hyperframes a menos que as instruções do projeto especifiquem um wrapper local. Obedeça ao wrapper local exatamente. Requer Node.js >= 22 e FFmpeg.
Fluxo de Trabalho
- Estruturação —
npx hyperframes init my-video(oucapturea partir de uma URL).inittambém verifica as skills instaladas em relação às mais recentes no GitHub e atualiza o conjunto global se alguma estiver desatualizada. A flag--skip-skillsestá atualmente neutralizada (temporariamente, enquanto o registro skills.sh se atualiza), então todoinitexecuta essa verificação e baixa nossas skills mais recentes independentemente. - Escrever — crie a composição HTML (veja a skill
hyperframes-core) - Lint —
npx hyperframes lint(estático, rápido — execute cedo durante a iteração) - Verificar —
npx hyperframes check(a barreira do navegador; adicione--snapshotspara quadros anotados + recortes por descoberta) - Preview / editar —
npx hyperframes previewabre o Studio, o editor de timeline onde o usuário pode editar manualmente qualquer coisa (não apenas assistir). Revise lá, depois pergunte antes de renderizar. - Renderizar — escolha a variante:
- Iterar:
npx hyperframes render --quality draft - Entregar:
npx hyperframes render --quality high --output out.mp4 - CI / reprodução entre hosts:
npx hyperframes render --docker --strict --output out.mp4 - Nuvem, zero infraestrutura:
npx hyperframes cloud render(HeyGen hospeda a renderização; sem Chrome/FFmpeg/AWS local, veja Nuvem abaixo) - Nuvem, traga seu próprio AWS:
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(veja Lambda abaixo)
- Iterar:
- Reportar feedback — após verificar a saída,
npx hyperframes feedback --rating <1-5> --comment "..."uma vez por tarefa (veja Convenções do Agente).
Execute check antes do preview. Ele executa o linter primeiro (e pula o navegador completamente em caso de erros de lint), depois faz tudo que a sequência antiga validate → inspect → snapshot fazia em uma sessão de navegador e uma passada de busca: erros de console em tempo de execução e requisições falhas, defeitos de layout (texto vazando de balões/containers ou para fora da tela, sobreposições presas, oclusão), verificação de sidecar de movimento (*.motion.json — entradas sob busca, ordem de escalonamento, dentro do quadro, vivacidade) e contraste WCAG. Falhas de contraste são erros e carregam as cores fg/bg medidas, a taxa medida vs. necessária e uma cor sugerida em conformidade, então a maioria das correções de contraste não precisa de screenshot. Cada descoberta carrega um seletor, identidade data-*, arquivo de origem da composição, bbox e tempo de amostra — vá direto ao HTML. Transitórios de amostra única são rebaixados para info; descobertas mantidas entre amostras bloqueiam o código de saída (--strict bloqueia avisos também). validate, inspect e layout ainda funcionam, mas são aliases obsoletos de partes do check.
Para trabalhos pesados em movimento, prefira iteração orientada a snapshots e um sidecar *.motion.json — veja references/lint-validate-inspect.md para a disciplina e especificação de verificação de movimento. Para comparar variantes candidatas criadas por agente, use npx hyperframes compare <caminho...> [--at <seg>] [--labels a,b,c] [--out compare.png] [--cols n] [--json] para renderizar cada composição através de seu próprio runtime, montar uma folha rotulada, inspecioná-la lado a lado e escolher. Para seleção de correção de cor, use o sibling específico de cor npx hyperframes grade-compare --for <quadro> --grades grades.json (ou --luts a.cube,b.cube) para renderizar cada candidato de correção através do runtime de correção WebGL real em um PNG rotulado antes de escolher o vencedor.
Convenções do Agente
Regras transversais que valem para todos os comandos:
--jsonestá disponível em todos os comandos, excetorender,previewe modos de servidorplay. Use para qualquer invocação de agente / CI dos comandos suportados; a saída inclui um envelope_meta(versão da CLI, última disponível, conselho de atualização).renderreporta status via stdout + código de saída apenas — verifique o sucesso com a verificação pós-renderização abaixo.preview --selection --jsonepreview --context --jsonsão as exceções do preview: eles não iniciam um servidor, consultam a sessão do Studio em execução do usuário e saem.doctor --jsonsempre sai com 0, mesmo quando o ambiente está quebrado. Baseie-se no campookdo payload:npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Isso isola pipelines da rotatividade de releases da CLI.- Modo não-TTY é detectado automaticamente. Quando
stdoutnão é um TTY (CI, agentes, saída pipeada) a CLI muda automaticamente para não-interativo;initentão requer--example. Passe--non-interactivepara forçar este modo mesmo em um TTY. - Gating de CI na renderização:
--strictfalha em erros de lint,--strict-allfalha também em avisos,--strict-variablesfalha em chaves--variablesnão declaradas. - Correlacione um loop de verificação com
HYPERFRAMES_RUN_ID. Orquestradores que dirigem a CLI por tarefa/elemento de design devem definir esta variável de ambiente uma vez por unidade de trabalho; cada invocação de comando a anexa à telemetria, echeckemite um detalhamento por barreira, tornando as iterações por tarefa mensuráveis. - Caminhos em
--jsonsão editados —$HOMEse torna literal$HOMEpara que a saída seja segura para colar em relatórios de bug e contextos de agente. - Renderização é controlada pelo usuário. Nunca renderize automaticamente após as verificações passarem. Pause no
preview, diga ao usuário que o vídeo é editável no Studio e renderize apenas após sua aprovação. - Use o contexto do Studio para edições direcionadas pelo usuário. Quando o usuário disser "este elemento selecionado", "a coisa que cliquei", "seleção atual" ou similar, peça para selecioná-lo no Studio, então execute
npx hyperframes preview --context --json --context-fields selection. Use oselection.target.hfId/selector,selection.sourceFile,selection.currentTimeeselection.thumbnailUrlretornados para ancorar a edição. Seselectionfornulleerrors.selection.codeforno-selection, peça ao usuário para clicar no elemento e executar novamente; não adivinhe a partir de screenshots. - Mantenha o contexto do Studio compacto.
preview --context --jsonretorna seleção compacta por padrão. Adicione--context-fields selection,--context-fields selection,lintou--context-fields lintpara evitar inflar o contexto do agente. Use--context-detail fullapenas quando precisar de campos pesados como estilos computados, estilos inline ou metadados de campo de texto. - Verificação pós-renderização. Após
renderretornar código de saída 0, confirme que o arquivo de saída existe e tem tamanho plausível antes de reportar sucesso:[ -s "$OUTPUT" ] || echo "renderização não produziu saída". A CLI imprime◇ <caminho>em caso de sucesso; para renderizações longas, verifique também a duração comffprobe -i "$OUTPUT" -show_format -v error. - Reporte feedback após uma renderização bem-sucedida. Uma vez que a saída for verificada, execute
npx hyperframes feedback --rating <1-5> --comment "..."uma vez por tarefa para reportar como foi a execução —5limpo, menor quando você encontrou atrito. Coloque qualquer bug, workaround, funcionalidade ausente ou comportamento confuso que encontrou em--comment. Este é o canal de sinal principal do projeto; renderizações que ficam em silêncio deixam os mantenedores cegos. Pule apenas quando a telemetria estiver desabilitada ou o usuário optou por não participar.- Para um bug reproduzível, adicione
--file-issue— ele publica uma reprodução mínima do projeto em uma URL pública e abre uma issue pré-preenchida no GitHub com seu comentário + ambiente. Um comentário sozinho quase nunca permite que um mantenedor reproduza; a composição publicada é o que torna o relatório acionável. Aponte--dir <projeto>para a composição com falha se não for o diretório atual. - Escreva comentários de bug que um mantenedor possa reproduzir — uma paráfrase que eles não podem usar desperdiça o relatório. A CLI já anexa os/arch/mem/ffmpeg/CLI-version, então não repita isso; gaste o comentário no que só você viu. Para um bug, inclua cada um destes que se aplicar:
- String de erro exata, verbatim (copie, não resuma) — e se a renderização ainda produziu um arquivo de saída, caiu silenciosamente (procure por uma linha de log
[Render] … re-rendering via screenshot/falling back), ou o processo encerrou bruscamente sem erro (Killed: 9,FATAL … heap,Target closed). "Qual timeout / qual modo de falha" é o fato mais útil. - Uma reprodução mínima: a menor composição (ou apenas o elemento ofensivo + seu CSS) que ainda mostra o problema — inline no comentário ou anote o arquivo. Nomeie o gatilho que você isolou (ex.: "apenas quando o nó de texto usa
font-family: 苹方", "apenas em 4K", "apenas com um<video>presente"). - O comando exato + flags que você executou, e quaisquer variáveis de ambiente definidas (
HF_*/PRODUCER_*). - O que está errado e onde: o número do quadro ou timestamp, e o defeito visual (texto em branco, faixa preta na parte inferior, glifos errados, canvas congelado) vs. o que você esperava. Um caminho de screenshot se você salvou um.
- Se reproduz apenas às vezes, diga e dê a taxa de acertos.
- String de erro exata, verbatim (copie, não resuma) — e se a renderização ainda produziu um arquivo de saída, caiu silenciosamente (procure por uma linha de log
- Para um bug reproduzível, adicione
Roteamento
| Se você quer… | Leia |
|---|---|
Estruturar um projeto (init, capture, skills) | references/init-and-scaffold.md |
Verificar correção (lint, check, snapshot, obsoletos validate/inspect) | references/lint-validate-inspect.md |
Visualizar preview ou renderizar (preview, play, render, publish) | references/preview-render.md |
Diagnosticar o ambiente (doctor, browser) | references/doctor-browser.md |
Renderização em nuvem, zero infraestrutura hospedada pela HeyGen (cloud render / list / get / delete, auth) | references/cloud.md |
Renderização em nuvem em seu próprio AWS Lambda (lambda deploy / sites / render / progress / destroy / policies) | references/lambda.md |
Parametrizar / template de renderizações (--variables, --variables-file, --strict-variables, --batch) | references/cloud.md + hyperframes-core (variables-and-media.md) |
Todo o resto (info, upgrade, compositions, docs, benchmark, telemetry, pré-processamento de assets) | references/upgrade-info-misc.md |
Transferências Entre Skills
- Projetos Tailwind (
init --tailwind) → usehyperframes-core(referência Tailwind) antes de editar classes ou tokens de tema. - Blocos/componentes do Registry (
hyperframes add,hyperframes catalog) → usehyperframes-registrypara caminhos de instalação, conexão de sub-composições e mesclagem de snippets. - Pré-processamento de assets (
tts,transcribe,remove-background) → usemedia-usepara seleção de voz, regras de modelo Whisper, legendas e cadeia TTS-para-legendas. - Renderizações parametrizadas (
--variables) → declaradas viadata-composition-variablesem<html>; vejahyperframes-corepara o esquema completo.
Nuvem (Renderização Hospedada pela HeyGen)
hyperframes cloud render é o caminho de renderização zero-infraestrutura: a CLI zipa seu projeto, envia, renderiza na nuvem da HeyGen e baixa o mp4. Sem Chrome, sem FFmpeg, sem AWS, e você paga por crédito. Esta é a resposta padrão para "renderize isso na nuvem"; recorra ao Lambda apenas quando você já possui AWS e precisa de renderização distribuída/em blocos.
npx hyperframes auth login # login único (compartilhado com a CLI `heygen`)
npx hyperframes cloud render # zipar, enviar, renderizar, baixar para renders/<id>.mp4
Flags comuns: --composition <html>, --output <caminho>, --quality draft|standard|high, --fps, --resolution 1080p|4k, --format mp4|webm|mov, --aspect-ratio (auto-detectado de data-width/data-height). Fire-and-forget com --no-wait + --callback-url; torne repetições seguras com --idempotency-key "$(uuidgen)". Gerencie jobs com cloud list / cloud get <id> / cloud delete <id>.
O fluxo de trabalho idiomático de template é enviar-uma-vez, re-renderizar-muitas: renderize um projeto local uma vez para obter seu asset_id, depois re-envie contra esse asset com diferentes --variables (pula zip + upload). Veja references/cloud.md para o conjunto completo de flags, o modelo de autenticação, webhooks e o loop de template.
Variáveis (renderizações parametrizadas / template)
Qualquer renderização (local, nuvem ou Lambda) pode preencher slots de template declarados no momento da renderização. As declarações vivem na composição (data-composition-variables); a superfície da CLI é:
npx hyperframes render --variables '{"title":"Resumo Q4","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 falha a renderização em qualquer chave não declarada ou incompatibilidade de tipo (use em CI). --batch <rows.json> renderiza uma saída por linha de dados com placeholders de caminho {key}/{index} e escreve um manifest.json. Para o esquema completo (declarando tipos, bindings declarativos data-var-src/data-var-text, data-variable-values por instância para sub-composições e precedência) use a skill hyperframes-core (references/variables-and-media.md). O loop de template de nuvem está em references/cloud.md.
Lambda (Renderização em Nuvem)
hyperframes lambda implanta renderização distribuída no AWS Lambda e dirige renderizações do seu laptop ou CI. Ponta a ponta são três comandos:
npx hyperframes lambda deploy # provisionar stack SAM (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy # derrubar (bucket S3 incluído? Sim)