hyperframes-cli

Instalação de plugins: Antes dos comandos de setup ou freshness, siga as regras de execução de plugins quando esta skill estiver dentro de um plugin HyperFrames. Instalações standalone mantêm as instruções de atualização abaixo.

HyperFrames CLI

Execute comandos como npx hyperframes ... a menos que as instruções do projeto forneçam um wrapper. Obedeça ao wrapper quando presente. A CLI requer Node.js 22 ou superior e FFmpeg.

Loop de desenvolvimento

1. Scaffold: npx hyperframes init <projeto> (em branco centralizado). Ou capture um site. Passe --example=<nome> apenas para começar a partir de um exemplo nomeado.
2. Encontre o movimento: se a solicitação nomear um asset, som, imagem, voz ou edição visual rápida, resolva-o através de /media-use antes 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 linha por linha". Peça o efeito que deseja, não o mecanismo que tem em mente. Instale com npx hyperframes add <nome> (veja /hyperframes-registry). Crie manualmente apenas se nada se encaixar.
3. Crie: 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 é reproduzido), execute npx hyperframes timeline --json em vez de ler index.html e cada arquivo de subcomposição: as linhas aninhadas carregam tempos absolutos da linha do tempo principal absStart/absEnd e seu arquivo de origem, não apenas o tempo local por subcomposição. Prefira --json ao formato de texto; custa menos tokens para a mesma ou melhor precisão. Veja references/upgrade-info-misc.md para respostas rápidas a perguntas comuns sem ler toda a saída.
4. Obtenha feedback rápido durante a edição: execute npx hyperframes lint após a primeira passagem HTML e após mudanças estruturais.
5. Execute o gate final: execute npx hyperframes check; ele executa lint novamente antes de abrir o navegador. Não adicione uma chamada de lint redundante separada. Adicione --snapshots para quadros de visão geral anotados e descoberta de cortes.
6. Inspecione subcomposições: quando index.html montar data-composition-src, capture snapshots de ponto médio e inspecione cada cena montada.
7. Abra a pré-visualização Studio final: execute npx hyperframes preview --background, verifique se a URL retorna HTTP 200, entregue a URL do projeto da linha do tempo ao usuário e pergunte se deseja revisar ou renderizar. Mantenha ativo até o fim da revisão.
8. Renderize apenas após aprovação: use --quality draft durante a iteração, --quality looks para a primeira codificação real (padrão da CLI) e --quality delivery para entrega final.
9. Verifique a saída: confirme se o arquivo existe e não está vazio. Leia a segunda linha do resumo da renderização (beginframe vs screenshot, GPU, tempos de estágio). screenshot + software gpu no Linux é o caminho lento. Use ffprobe -v error -show_format -show_streams e compare a duração (e fps, se o resumo definiu) com o data-duration raiz.

Histórico do projeto na sua vez

Cada escrita no projeto é mantida como uma entrada que pode ser desfeita. Use-a apenas em dois momentos, nunca em cada etapa:

• Início de uma iteração: npx hyperframes history begin --who <seu-nome> --label "<o que você está prestes a fazer>", então npx hyperframes history --since mine --who <seu-nome> para ver o que a pessoa mudou desde sua última iteração. Construa sobre as edições deles; nunca as sobrescreva.
• Uma verificação falhou, ou a pessoa disse que piorou: npx hyperframes history undo --who <seu-nome> desfaz sua iteração mais recente e deixa as edições da pessoa intactas. Não edite manualmente de volta. Em caso de conflito, sai com código 2 e imprime ambas as opções.

Termine cada iteração com npx hyperframes history end, para que suas escritas sejam lidas como suas, não como "Alterado fora do app". Enquanto uma iteração estiver aberta, cada escrita no projeto conta como sua até que 10 minutos passem sem uma; após isso, a iteração termina automaticamente.

Referências cruzadas obrigatórias de edição criador

• Antes de criar ou diagnosticar um zoom, entrada/saída, reenquadramento, movimento de câmera ou qualquer movimento de keyframe, leia /hyperframes-keyframes primeiro.
• Antes de hyperframes keyframes, leia /hyperframes-keyframes; o comando exibe trajetórias de animação e não diagnostica cortes de clipe.
• Para corte, trim, emenda, reordenação ou edição de timing de origem, leia /hyperframes-core e use seu contrato de clipe/linha do tempo.
• Para fade-in/fade-out, crossfade, ganho de faixa, automação de volume, ducking, narração sobreposta ou FX em áudio inserido, leia /hyperframes-audio. Carregue o core junto quando a colocação do clipe ou o timing da imagem também mudar.
• Uma solicitação nomeando um asset, som, imagem, voz ou edição visual rápida resolve-se através de /media-use antes de um plano ser proposto. Copie a marcação de edição criador de /hyperframes-core → references/creator-editing-recipes.md.

# Verificação rápida de iteração; repita enquanto cria, conforme necessário.
npx hyperframes lint

# Gate 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, requisições falhas, layout, asserções *.motion.json e contraste WCAG. Achados persistentes bloqueiam o código de saída; achados 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é-visualização 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. Renderizar 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 conseguem capturar todas as falhas de montagem. Quando o projeto usar subcomposições, capture pelo menos um ponto médio 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 na 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 "<a batida, em português claro>". A pesquisa é totalmente local: não há camada hospedada, nenhuma conta, e o texto da consulta nunca é enviado a lugar nenhum. Por padrão, ela ranqueia pelo vocabulário compartilhado com o nome, título, descrição e tags do item, o que perde qualquer frase que não reutilize a própria redação do catálogo. Adicione --on-device para ranquear por significado (veja a camada offline abaixo).

• Consulte em inglês mesmo quando o vídeo não estiver. Ambas as camadas indexam um catálogo em inglês, então uma consulta em outro script não produz termos pesquisáveis e não retorna nada. Descreva o movimento em inglês; o texto na tela permanece em qualquer idioma que o vídeo precisar. Nenhuma palavra pesquisável na consulta significa exatamente isso e não é um componente ausente, então não o reporte como uma lacuna do catálogo.

• Leia qual camada respondeu; nunca infira da aparência dos resultados. Com --json o envelope carrega query, tier (on-device ou words), tier_detail, dropped, unindexed, shown, total e results, além de top_score quando a camada respondedora produz um e warnings quando uma camada foi solicitada e não pôde executar, ou quando uma pesquisa não retornou nada e uma camada melhor ainda está aguardando o consentimento de alguém. Um resultado fraco em words é esperado; o mesmo resultado em on-device é um bug. top_score é apenas on-device e não tem limite por trás: o ranqueador retorna o catálogo inteiro em alguma ordem para cada consulta, então leia como evidência, não como aprovação ou falha.

• dropped e unindexed são distorções opostas entre o registro e o índice on-device, e reformular a consulta não corrige nenhum dos dois. dropped conta nomes ranqueados que este registro não pode instalar, então os matches mais fortes estão sendo perdidos. unindexed conta movimentos do registro que o índice não pode ver de jeito nenhum, que nenhuma consulta pode retornar. Atualizar o registro não é a resposta para nenhum dos dois: seu manifesto tem um TTL de 24h e se cura sozinho, enquanto os vetores são um artefato publicado separadamente, baixado para ~/.hyperframes/catalog/. Re-executar com --on-device rebaixa esse índice quando unindexed estiver acima de zero, então esse é o remédio para passar ao usuário. Uma distorção puramente de excesso de cobertura (dropped acima de zero enquanto unindexed é zero) não dispara o rebaixamento; limpar ~/.hyperframes/catalog/ é a única saída desse caso. Ambas as contagens são de nomes, não de resultados, então qualquer uma pode exceder total.

• Quando uma pesquisa não retornar 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 --query a imprime pré-preenchida, e todo envelope de pesquisa --json a carrega como report_gap com a consulta e camada já corretas — preencha --wanted e envie. Este é o único caminho que envia uma consulta para qualquer lugar, e é um comando deliberado separado precisamente para que o simples catalog --query mantenha sua promessa de não enviar nada. Reporte em qualquer camada, sempre que os resultados não fizerem o que você precisa; não espere pela camada on-device, que precisa de um download de 33 MB consentido e, portanto, está desligada na maioria das execuções de agente — esperar significa nunca reportar. A camada vem junto no relatório, então uma falha de vocabulário permanece distinguível de uma falha de significado sem que você precise julgar qual encontrou. O que retorna é uma lista de movimentos que o catálogo ainda não tem, lida diretamente em vez de adivinhada a partir de contagens de instalação, então a frase que importa é o efeito que você queria, não o nome do item que imaginou. Não carrega nenhuma classificação e nunca cai na 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.5 mais seu tokenizador, fixado a uma revisão específica) e os vetores do catálogo do registro, ambos em cache em ~/.hyperframes/, nenhum adicionado ao projeto ou a qualquer pacote. Uma vez em cache, ranqueia por significado sem enviar nada. Diga o tamanho em voz alta e deixe a pessoa decidir, então passe --on-device (com -y para pular o prompt) quando ela concordar. A oferta interativa só dispara em um TTY. Sob --json não há prompt, mas uma pesquisa que não encontrou nada coloca a mesma pergunta em warnings, então leia esse array e coloque a decisão para o usuário você mesmo. Quando a pessoa perguntar o que é o download, por que esse modelo, ou o que sai da máquina, aponte para https://hyperframes.heygen.com/developers/catalog-search.

• Prefira --json para chamadas de agente e CI. Modo servidor render, preview e play não fornecem saída JSON comum; preview --selection --json e preview --context --json são exceções de modo consulta.

• doctor --json sempre sai com código zero. Valide o payload:

  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
  

• O modo não TTY é automático e faz scaffold em branco centralizado. Passe --example apenas para começar a partir de um exemplo nomeado. Use --non-interactive para forçar modo apenas de flags em um TTY.

• Use um único HYPERFRAMES_RUN_ID para todos os comandos no mesmo loop de verificação.

• Quando o disco estiver cheio, execute npx hyperframes clean (--dry-run para listar antes); ele remove o que renderizações mortas deixaram e caches ociosos que se reconstroem sozinhos, nunca saídas, fontes ou qualquer coisa que uma renderização em uso utilize. Escreva quadros QC em um diretório temporário, não no projeto.

• Use --strict, --strict-all e --strict-variables quando os avisos, variáveis ou condições de CI correspondentes precisarem bloquear a renderização.

• Caminhos JSON redigem o diretório home como $HOME; não tente reverter a redação.

• Quando um projeto cloud hospedado se aproximar ou exceder o limite de upload de 200 MB, use cloud render --dry-run --json e siga a investigação de .hyperframesignore em references/cloud.md. Nunca ignore um asset meramente porque ele é grande.

• Nunca renderize meramente porque as verificações passaram. Pause na pré-visualização final e aguarde aprovação.

Edições direcionadas ao 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 de que você precisa; use --context-detail full apenas para estilos computados ou metadados de texto editável. Comportamento completo e 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 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 em contêiner reprodutível	npx hyperframes render --docker --strict --output out.mp4
Renderização em lote local orientada por variável	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 l ... (truncado)