Communitygithub.com

HyperFrames CLI

Use o ciclo de desenvolvimento da CLI HyperFrames: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, render único ou em lote, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, auth, tts e remove-background. Também utilizado para diagnosticar falhas de build ou render. validate, inspect e layout são aliases obsoletos; use check. Abrange renderização local, em nuvem HeyGen, AWS Lambda e Google Cloud Run.

O que é HyperFrames CLI?

O HyperFrames CLI é uma ferramenta de linha de comando completa para criar, testar e renderizar composições baseadas em HyperFrames. Ele oferece um ciclo de desenvolvimento iterativo que inclui scaffolding inicial (scaffold), autoria, linting, verificação final (check), preview e renderização — tanto localmente quanto em plataformas de nuvem como HeyGen, AWS Lambda e Google Cloud Run. A ferramenta é especialmente útil para desenvolvedores e agentes de IA que precisam de feedback rápido durante a edição, garantindo que códigos de composição, layouts e padrões de acessibilidade sejam validados antes da renderização final. O HyperFrames CLI suporta renderização em lote baseada em variáveis, captura de snapshots para diagnóstico de subcomposições e preview interativo via Studio. Além disso, inclui comandos especializados como beats para grade de batidas, keyframes para animações e present para apresentações sincronizadas. A CLI exige Node.js 22 ou superior e FFmpeg, e pode ser executada via npx hyperframes ou através de um wrapper definido pelo projeto. O SKILL.md documenta convenções para agentes, como o uso de --json para integração, gerenciamento de IDs de execução e modos não interativos.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dbillion/hermes-skills-public/tree/HEAD/skills-external/hyperframes-cli

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que HyperFrames CLI faz?

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.

Ciclo de desenvolvimento

  1. Scaffold: npx hyperframes init <projeto> ou capture um site. Em modo não TTY, use --non-interactive --example=<nome>.
  2. Autoria: escreva a composição usando /hyperframes-core.
  3. Obtenha feedback rápido durante a edição: execute npx hyperframes lint após a primeira passagem de HTML e após mudanças estruturais.
  4. Execute o portão final: execute npx hyperframes check; ele reexecuta lint antes de abrir o navegador. Não adicione uma invocação redundante de lint separada. Adicione --snapshots para quadros de visão geral anotados e encontrar cortes.
  5. Inspecione subcomposições: quando index.html montar data-composition-src, capture snapshots de pontos médios e inspecione cada cena montada.
  6. Abra a prévia final do Studio: execute npx hyperframes preview, entregue a URL do projeto da linha do tempo ao usuário e pergunte se deseja revisar ou renderizar.
  7. Renderize somente após aprovação: use qualidade draft para iteração e qualidade alta para entrega.
  8. Verifique a saída: confirme que o arquivo existe, não está vazio e tem uma duração plausível.
# Verificação rápida de iteração; repita enquanto edita conforme necessário.
npx hyperframes lint

# Portão final obrigatório; inclui lint.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format 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 com falha, layout, asserções *.motion.json e contraste WCAG. Descobertas persistentes bloqueiam o código de saída; descobertas transitórias de entrada ou saída são informativas. 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.

Duas superfícies de prévia diferentes

Não confunda esses estados:

SuperfícieQuando pode abrirPropósito
Quadro de storyboardAntes das verificações de composição, apenas com storyboard: yesRevisar cartões de plano e esboços de wireframe. Abrir ?view=storyboard#project/<nome>.
Prévia final da composiçãoApós a aprovação do checkRevisar a linha do tempo montada antes da renderização. Abrir #project/<nome>.

O quadro inicial não é aprovação do vídeo final. A renderização sempre requer a aprovação final definida por hyperframes-core/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 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 herói ausentes ou timeouts de registro na linha do tempo como defeitos de montagem que bloqueiam a renderização. Consulte hyperframes-core/references/sub-compositions.md para as correções correspondentes.

Convenções para agente

  • Prefira --json para chamadas de agente e CI. Modos 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 zero. Avalie seu payload:

    npx hyperframes doctor --json | jq -e '.ok' >/dev/null
    
  • Modo não TTY é automático. init requer --example lá; use --non-interactive para forçar comportamento determinístico em um TTY.

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

  • 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.

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

Edições direcionadas 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 fonte. Se o resultado reportar no-selection, peça ao usuário para clicar no elemento e executar novamente. Solicite apenas as fatias de contexto necessárias; use --context-detail full apenas para estilos computados ou metadados de texto editável. O comportamento completo e códigos de falha estão em references/preview-render.md.

Opções de renderização

NecessidadeComando
Iteração local rápidanpx hyperframes render --quality draft
Entrega local finalnpx hyperframes render --quality high --output out.mp4
Renderização em contêiner reproduzívelnpx hyperframes render --docker --strict --output out.mp4
Renderização em lote local orientada por variávelnpx hyperframes render --batch rows.json --output "renders/{name}.mp4"
Renderização em nuvem HeyGen sem infraestruturanpx hyperframes cloud render
Renderização distribuída AWS autogerenciadanpx hyperframes lambda render <projeto> --width 1920 --height 1080 --wait
Renderização distribuída GCP autogerenciadanpx hyperframes cloudrun render <projeto> --width 1920 --height 1080 --wait

Use renderização em nuvem quando o usuário quiser renderização hospedada sem Chrome local, FFmpeg ou AWS. 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 desativada ou o usuário tenha optado por não participar:

npx hyperframes feedback --rating <0-10> --comment "<resultado específico ou atrito>"

Mantenha 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 e diretório de trabalho, comportamento esperado versus real, erro exato, se a saída foi concluída/fallback/falhou, solução alternativa e status do projeto de reprodução. Se o problema não se reproduziu novamente, informe e ainda inclua o último comando e logs que falharam. Use --file-issue apenas com consentimento: ele publica uma reprodução mínima em uma URL pública. O formato obrigatório do pacote e o aviso de privacidade estão em references/preview-render.md.

Leia a referência correspondente antes de executar um comando

As seguintes referências e habilidades proprietárias são contratos de comando obrigatórios, não leitura de fundo opcional. Antes de executar um comando na tabela, leia sua linha correspondente.

NecessidadeReferência
init, capture, skillsreferences/init-and-scaffold.md
lint, check, sidecars de movimento, snapshotreferences/lint-validate-inspect.md
compare, grade-compare, render --batch orientado por variávelreferences/compare-and-batch.md
beats para a grade de batidas do Studio de um projeto existentereferences/beats.md
preview, play, render, publish, contexto do Studio, feedbackreferences/preview-render.md
doctor, gerenciamento de navegadorreferences/doctor-browser.md
auth, renderização em nuvem HeyGen e variáveis de templatereferences/cloud.md
Implantação e renderização AWS Lambdareferences/lambda.md
Implantação e renderização Google Cloud Runreferences/cloudrun.md
info, upgrade, compositions, docs, benchmark, telemetria, pré-processamento de mídiareferences/upgrade-info-misc.md

Para variáveis de composição, leia também /hyperframes-core → references/variables-and-media.md. Para hyperframes add e hyperframes catalog, use /hyperframes-registry. Antes de hyperframes present, leia /slideshow; antes de hyperframes keyframes, leia /hyperframes-keyframes. Para TTS, transcrição, legendas ou opções de remoção de fundo, use /media-use.

Os comandos especializados estão documentados por seus fluxos de trabalho proprietários:

npx hyperframes present <diretório-do-projeto> --port 3004 --no-open
npx hyperframes beats <diretório-do-projeto> --json
npx hyperframes keyframes <diretório-do-projeto> --json

present serve um deck navegável com sincronização de apresentador e audiência. beats é o utilitário standalone da grade de batidas do Studio definido em references/beats.md. keyframes expõe diagnósticos de animação e caminho de movimento seguros para seek.

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

dbillion/hermes-skills-public

Edit an existing image based on a text prompt.

dbillion/hermes-skills-public

Add `flutter_localizations` and `intl` dependencies, enable "generate true" in `pubspec.yaml`, and create an `l10n.yaml` configuration file. Use when initializing localization support for a new Flutter project.

dbillion/hermes-skills-public

Expert in video composition, editing, and format conversion. Use when the user wants to generate high-quality video, overlay images on video, concatenate clips, create GIFs, or sync audio to video using mcp-avtool-go and mcp-veo-go.

dbillion/hermes-skills-public

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

dbillion/hermes-skills-public

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition HTML.

dbillion/hermes-skills-public

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

Habilidades Relacionadas