CLI HyperFrames
Execute comandos como npx hyperframes ... a menos que as instruções do projeto forneçam um wrapper. Obedeça ao wrapper quando presente. O CLI requer Node.js 22 ou superior e FFmpeg.
Ciclo de desenvolvimento
- Estruturar:
npx hyperframes init <projeto>(em branco centralizado). Ou capture um site. Passe--example=<nome>apenas para começar a partir de um exemplo nomeado. - Encontrar o movimento: se a solicitação nomear um ativo, som, imagem, voz ou edição visual rápida, resolva-a através de
/media-useantes de propor um plano. Caso contrário, antes de criar movimento manualmente, pesquise uma primitiva que já o faça:npx hyperframes catalog --query "revelar um título uma linha de cada vez". Peça o efeito que você deseja, não o mecanismo que você tem em mente. Instale comnpx hyperframes add <nome>(veja/hyperframes-registry). Crie manualmente apenas quando nada se encaixar. - Autorar: escreva a composição usando
/hyperframes-core. Para saber o que está na linha do tempo de um projeto (faixas, clipes, inícios, fins, o que toca), executenpx hyperframes timeline --jsonem vez de lerindex.htmle cada arquivo de subcomposição: linhas aninhadas carregamabsStart/absEndabsolutos da linha do tempo principal e seufileproprietário, não apenas seu tempo local por subcomposição. Prefira--jsonem vez da forma textual; custa menos tokens para a mesma ou melhor precisão. Vejareferences/upgrade-info-misc.mdpara dicas que respondem perguntas comuns sem ler toda a saída. - Obter feedback rápido durante a edição: execute
npx hyperframes lintapós a primeira passagem de HTML e após mudanças estruturais. - Executar o portal final: execute
npx hyperframes check; ele executa lint novamente antes de abrir o navegador. Não adicione uma chamada lint redundante e separada. Adicione--snapshotspara quadros de visão geral anotados e encontrar cortes. - Inspecionar subcomposições: quando
index.htmlmontadata-composition-src, capture snapshots intermediários e inspecione cada cena montada. - Abrir a pré-visualização final do Studio: execute
npx hyperframes preview --background, verifique se a URL retorna HTTP 200, entregue o URL do projeto de linha do tempo ao usuário e pergunte se deve revisar ou renderizar. Mantenha-o ativo até o final da revisão. - Renderizar apenas após aprovação: use
--quality draftdurante a iteração,--quality lookspara a primeira codificação real (padrão do CLI) e--quality deliverypara entrega final. - Verificar a saída: confirme que o arquivo existe e não está vazio. Leia a segunda linha do resumo da renderização (
beginframevsscreenshot, GPU, tempos de estágio).screenshot+software gpuno Linux é o caminho lento. Useffprobe -v error -show_format -show_streamse compare a duração (e fps, se o briefing definiu) com odata-durationraiz.
Referências obrigatórias de edição do criador
- Antes de criar ou diagnosticar um zoom, punch-in/punch-out, reframe, movimento de câmera ou qualquer movimento com keyframe, leia
/hyperframes-keyframesprimeiro. - Antes de
hyperframes keyframes, leia/hyperframes-keyframes; o comando exibe trajetórias de animação e não diagnostica cortes de clipe. - Para um corte, trim, splice, reordenação ou edição de tempo de origem, leia
/hyperframes-coree use seu contrato de clipe/linha do tempo. - Para fade-in/fade-out, crossfade, ganho de faixa, automação de volume, ducking, corte de narração ou FX em áudio colocado, leia
/hyperframes-audio. Carregue o core junto quando o posicionamento do clipe ou o tempo da imagem também mudar. - Uma solicitação nomeando um ativo, som, imagem, voz ou edição visual rápida é resolvida através de
/media-useantes que um plano seja proposto. Copie a marcação de edição do criador de/hyperframes-core→references/creator-editing-recipes.md.
# Verificação rápida de iteração; repita durante a criação conforme necessário.
npx hyperframes lint
# Portal final obrigatório; inclui lint.
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4
check executa lint primeiro, depois usa uma sessão de navegador e uma passagem de busca para auditar erros de tempo de execução, solicitações com falha, layout, asserções de *.motion.json e contraste WCAG. Problemas persistentes bloqueiam o código de saída; problemas transitórios de entrada ou saída são informativos. Use --strict para bloquear avisos. validate, inspect e layout permanecem como aliases para compatibilidade, mas não devem aparecer em novas instruções ou scripts.
Pré-visualizar antes de renderizar
Abra a pré-visualização da composição final (#project/<nome>) apenas após check passar, para revisar a linha do tempo montada. O plano no chat e a folha de esboço storyboard.html não são aprovação do vídeo final. A renderização sempre requer a aprovação final definida por hyperframes/references/review-loop.md.
Teste de fumaça de subcomposição
Auditorias estáticas não podem capturar todas as falhas de montagem. Quando o projeto usa subcomposições, capture pelo menos um ponto intermediário visível para cada slot hospedeiro:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Trate conteúdo pequeno sem estilo, ícones do tamanho da tela, elementos de herói ausentes ou timeouts de registro de linha do tempo como defeitos de montagem que bloqueiam a renderização. Veja hyperframes-core/references/sub-compositions.md para as correções correspondentes.
Convenções do agente
-
Pesquise o catálogo antes de escrever movimento manualmente.
npx hyperframes catalog --query "<o ritmo, em inglês claro>". A pesquisa é inteiramente local: não há camada hospedada, nenhuma conta e o texto da consulta nunca é enviado a lugar nenhum. Por padrão, classifica com base no vocabulário compartilhado com o nome, título, descrição e tags do item, o que perde qualquer frase que não reutilize a redação do próprio catálogo. Adicione--on-devicepara classificar por significado (veja a camada offline abaixo). -
Consulte em inglês mesmo quando o vídeo não for. Ambas as camadas indexam um catálogo em inglês, portanto, uma consulta em outro script não produz termos pesquisáveis e retorna nada. Descreva o movimento em inglês; o texto na tela permanece no idioma que o vídeo precisar.
Nenhuma palavra pesquisável na consultasignifica exatamente isso e não é um componente ausente, portanto, não o relate como uma lacuna no catálogo. -
Leia qual camada respondeu; nunca deduza dos resultados que aparecem. Com
--json, o envelope carregaquery,tier(on-deviceouwords),tier_detail,dropped,unindexed,shown,totaleresults, além detop_scorequando a camada respondente produz um ewarningsquando uma camada foi solicitada e não pôde ser executada, ou quando uma pesquisa não retornou nada e uma camada melhor ainda está aguardando o consentimento de alguém. Um resultado fraco emwordsé esperado; o mesmo resultado emon-deviceé um bug.top_scoreé apenas no dispositivo e não tem limite por trás: o classificador retorna todo o catálogo em alguma ordem para cada consulta, portanto, leia-o como evidência, não como aprovação ou reprovação. -
droppedeunindexedsão distorções opostas entre o registro e o índice no dispositivo, e reformular a consulta não corrige nenhum dos dois.droppedconta nomes classificados que este registro não pode instalar, portanto, as correspondências mais fortes são as que estão sendo perdidas.unindexedconta movimentos do registro que o índice não pode ver, que nenhuma consulta jamais poderá retornar. Atualizar o registro não é a resposta para nenhum dos dois: seu manifesto carrega um TTL de 24h e se cura sozinho, enquanto os vetores são um artefato publicado separadamente, buscado em~/.hyperframes/catalog/. Reexecutar com--on-devicebusca novamente esse índice quandounindexedestá acima de zero, então esse é o remédio para entregar ao usuário. Uma distorção pura de sobrecobertura (droppedacima de zero enquantounindexedé zero) não aciona a nova busca; limpar~/.hyperframes/catalog/é a única saída. Ambas as contagens são de nomes em vez de resultados, portanto, qualquer uma pode excedertotal. -
Quando uma pesquisa não retorna nada que valha a pena instalar, diga isso.
npx hyperframes feedback --search-miss "<a consulta que você executou>" --wanted "<o movimento que você precisava>" --tier <a camada que respondeu>. Você não precisa montar essa linha:catalog --querya imprime pré-preenchida, e todo envelope de pesquisa--jsona carrega comoreport_gapcom consulta e camada já corretas — preencha--wantede envie. Este é o único caminho que envia uma consulta a algum lugar, e é um comando deliberado separado precisamente para que o simplescatalog --querymantenha sua promessa de não enviar nada. Relate em qualquer uma das camadas, sempre que os resultados não fizerem o que é necessário; não espere pela camada no dispositivo, que precisa de um download consentido de 33 MB e, portanto, está desligada na maioria das execuções de agente — esperar por ela significa nunca relatar. A camada acompanha o relatório, portanto, uma falta de vocabulário permanece distinguível de uma falta de significado sem que você precise julgar qual delas encontrou. O que retorna é uma lista de movimentos que o catálogo ainda não possui, lida diretamente em vez de adivinhada a partir de contagens de instalação, portanto, a frase que importa é o efeito que você deseja, não o nome do item que imaginou. Não carrega classificação e nunca chega à métrica de avaliação. -
Ofereça a camada offline; nunca a ative silenciosamente. Um download único de ~33 MB (uma compilação ONNX quantizada de
bge-small-en-v1.5mais seu tokenizador, fixada a uma revisão fixa) e os vetores do catálogo do registro, ambos armazenados em cache em~/.hyperframes/, nenhum adicionado ao projeto ou a qualquer pacote. Uma vez armazenado em cache, classifica por significado sem enviar nada. Diga o tamanho em voz alta e deixe a pessoa decidir, então passe--on-device(com-ypara pular o prompt) assim que ela concordar. A oferta interativa só é acionada em um TTY. Em--jsonnão há prompt, mas uma pesquisa que não encontrou nada coloca a mesma pergunta emwarnings, então leia essa matriz e coloque a decisão para o usuário você mesmo. Quando a pessoa perguntar o que é o download, por que este modelo, ou o que sai da máquina, aponte-a para https://hyperframes.heygen.com/developers/catalog-search. -
Prefira
--jsonpara chamadas de agente e CI.render,previeweplayem modo servidor não fornecem saída JSON comum;preview --selection --jsonepreview --context --jsonsão exceções do modo de consulta. -
doctor --jsonsempre sai com zero. Verifique sua carga útil:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
O modo não TTY é automático e estrutura o espaço em branco centralizado. Passe
--exampleapenas para começar a partir de um exemplo nomeado. Use--non-interactivepara forçar o modo somente de flag em um TTY. -
Use um
HYPERFRAMES_RUN_IDpara todos os comandos no mesmo loop de verificação. -
Use
--strict,--strict-alle--strict-variablesquando os avisos, variáveis ou condições de CI correspondentes devem bloquear a renderização. -
Caminhos JSON redigem o diretório inicial como
$HOME; não tente reverter a redação. -
Quando um projeto de nuvem hospedado se aproxima ou excede o limite de upload de 200 MB, use
cloud render --dry-run --jsone siga a investigação de.hyperframesignoreemreferences/cloud.md. Nunca ignore um ativo simplesmente por ser grande. -
Nunca renderize apenas porque as verificações passam. Pause na pré-visualização final e aguarde a aprovação.
Edições orientadas pelo Studio
Quando o usuário se referir a "este elemento" ou à seleção atual, consulte o Studio em vez de adivinhar:
npx hyperframes preview --context --json --context-fields selection
Use selection.target.hfId quando disponível, caso contrário, seu seletor e arquivo de origem. Se o resultado relatar no-selection, peça ao usuário para clicar no elemento e executar novamente. Solicite apenas as fatias de contexto que você precisa; use --context-detail full apenas para estilos computados ou metadados de texto editável. O comportamento completo e os códigos de falha estão em references/preview-render.md.
Escolhas de renderização
| Necessidade | Comando |
|---|---|
| Iteração local rápida | npx hyperframes render --quality draf (draft) |
| Primeira codificação real | npx hyperframes render --quality looks --output out.mp4 |
| Entrega local final | npx hyperframes render --quality delivery --output out.mp4 |
| Renderização reproduzível em contêiner | npx hyperframes render --docker --strict --output out.mp4 |
| Renderização em lote local orientada por variáveis | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| Renderização HeyGen sem infraestrutura | npx hyperframes cloud render |
| Renderização AWS distribuída autogerenciada | npx hyperframes lambda render <projeto> --width 1920 --height 1080 --wait |
| Renderização GCP distribuída autogerenciada | npx hyperframes cloudrun render <projeto> --width 1920 --height 1080 --wait |
A atribuição de skill é automática — os exemplos acima não precisam de --skill. Um projeto estruturado por um workflow (hyperframes init --skill=<workflow>) registra sua skill proprietária em hyperframes.json, e toda renderização posterior a herda na telemetria anônima: re-renderizações, npm run render e --batch da mesma forma. Passe --skill=<slug> explicitamente apenas para carimbar um projeto que não foi criado através de um workflow (sua primeira renderização o persiste).
Use renderização em nuvem quando o usuário quiser renderização hospedada sem Chrome, FFmpeg ou AWS local. Use Lambda apenas quando a propriedade da AWS for um requisito. Use Cloud Run apenas quando a propriedade do GCP for um requisito. Leia a referência correspondente antes de executar qualquer caminho de nuvem.
Após verificar uma renderização bem-sucedida, envie um relatório de feedback, a menos que a telemetria esteja desabilitada ou o usuário tenha optado por sair:
npx hyperframes feedback --rating <0-10> --comment "<resultado ou atrito específico>"
Mantenha o feedback de execução limpa conciso. Para qualquer bug ou atrito, capture um pacote de reprodução antes de enviar; não envie apenas um resumo do sintoma. Inclua o comando reexecutável (relativo ao diretório do projeto — o feedback é enviado a um canal público, portanto, não cole caminhos absolutos, prefixos de diretório inicial ou identificadores de usuário/máquina), comportamento esperado versus real, erro exato (também remova quaisquer caminhos absolutos ou dados pessoais) e qualquer outro estado que alguém precise reproduzir (argumentos de linha de comando, variáveis de ambiente relevantes, versão do Node.js, sistema operacional, saída de npx hyperframes doctor --json). Envie o pacote para o relatório de bug no repositório HyperFrames ou através de npx hyperframes feedback --bug. Se o atrito for uma falha de CLI (comando que falha, mensagem de erro confusa, comportamento inesperado), prefira --bug para que a equipe do HyperFrames possa rastreá-lo. Para lacunas ou solicitações de recursos, use --rating com um comentário descritivo.