Ponto de entrada do HyperFrames
HyperFrames renderiza vídeo a partir de HTML — uma composição é um arquivo HTML cujo DOM declara o tempo com atributos data-*, cujo tempo de execução da animação é buscável e cuja reprodução de mídia é gerenciada pelo framework. O contrato completo de autoria está em /hyperframes-core; leia-o antes de escrever HTML de composição.
1. Comece pelo estado do projeto
Aplique a primeira linha correspondente; não avalie linhas de estado inferiores:
| Estado | Ação |
|---|---|
| Porte explícito de fonte Remotion existente para HyperFrames | Leia references/routes/remotion-to-hyperframes.md, depois roteie diretamente para esse workflow. Pule a camada de intenção. |
| Operação específica em um projeto HyperFrames existente: inspecionar, diagnosticar, validar, visualizar, renderizar, publicar ou renderizar em lote | Execute apenas essa operação. Pule a intenção e o roteamento de workflow; carregue /hyperframes-cli e quaisquer skills de domínio necessárias. |
| Edição específica em um projeto existente | Faça a edição. Não execute a camada de intenção. |
BRIEF.md existe | Leia workflow e flow. Execute aquele workflow; flow: companion sempre executa em /general-video. Não faça perguntas sobre o brief. |
Sem brief, mas hyperframes.json ou STORYBOARD.md existe | Retome dos arquivos do projeto e das preferências registradas. Infira o workflow proprietário a partir dos artefatos existentes. Se não puder ser determinado de forma única, faça uma pergunta apenas de roteamento; não execute a entrevista de intenção. |
| Criação nova | Execute a camada de intenção — references/intent-interview.md — depois roteie uma vez usando a tabela da § 2. |
Se uma solicitação nova não identificar o assunto ou a entrada, pergunte sobre o que é o vídeo antes de rotear. Verifique preferências e receitas antes de perguntar qualquer coisa (references/intent-interview.md, passo 1). Uma entrada figma.com ou uma receita nomeada altera a ingestão, não o roteamento — a seção "Adaptar entradas ortogonais" da entrevida lida com ambos.
Mantenha o CLI do projeto atualizado
Um projeto scaffoldado fixa hyperframes@<version> em seus scripts package.json para que as renderizações permaneçam reproduzíveis; a fixação nunca avança sozinha, e uma execução fixada de um CLI mais antigo não imprime aviso sobre isso. Ao retomar um projeto cujos scripts carregam uma fixação, teste uma vez antes do primeiro comando que afeta a renderização:
npx hyperframes@latest upgrade --project . --check
O teste é somente leitura e relata a fixação contra o lançamento mais recente; mantenha o . explícito — em lançamentos mais antigos do CLI, um --project vazio seguido de outra flag consome essa flag como seu valor de diretório. Quando ele relatar que o projeto está atrás — ou qualquer saída do CLI já mostrar isso (o aviso stderr Este projeto fixa hyperframes@… (mais recente …), ou _meta.updateAvailable: true em um resultado --json de um script fixado) — aplique com npx hyperframes@latest upgrade --project ., depois verifique com npx hyperframes check. Uma verificação bem-sucedida confirma que as composições do projeto ainda validam na nova versão — não que a saída renderizada seja idêntica em quadros à fixação antiga — portanto, uma atualização bem-sucedida nunca é silenciosa: nomeie a versão antiga e a nova no resumo da execução. Um projeto sem composição ainda não precisa de verificação. Se a verificação falhar, reverta a alteração em package.json, continue na versão fixada e relate em qual versão o projeto permanece e por quê. Aja com base no sinal em vez de repassá-lo ao usuário; nunca deixe uma fixação atualizada sem verificação.
2. Roteie criação nova
Use a primeira linha correspondente. Corresponda ao entregável solicitado, não a uma palavra ou tipo de arquivo mencionado de passagem.
| Prioridade | Solicitação | Workflow |
|---|---|---|
| 1 | Portar explicitamente uma fonte Remotion existente | /remotion-to-hyperframes |
| 2 | Criar uma apresentação, pitch deck ou deck interativo navegável | /slideshow |
| 3 | Adicionar legendas ou subtítulos simples a filmagens existentes com fala (head) sem alterá-las | /embedded-captions |
| 4 | Adicionar sobreposições gráficas projetadas a filmagens existentes de cabeça falante, entrevista ou podcast sem alterar a filmagem | /talking-head-recut |
| 5 | Construir um vídeo sincronizado com batidas a partir de uma faixa de música, sem narração ou captura de site | /music-to-video |
| 6 | Criar uma unidade explicitamente curta, sem narração, focada em movimento, geralmente com menos de 10s | /motion-graphics |
| 7 | Explicar uma pull request do GitHub ou alteração de código a partir de uma referência de PR | /pr-to-video |
| 8 | Comercializar ou mostrar um site, site de produto, aplicativo ou empresa a partir de uma URL ou brief específico do site | /product-launch-video |
| 9 | Explicar um tópico, artigo ou notas com visuais inventados e sem captura de produto ou site | /faceless-explainer |
| 10 | Qualquer outro vídeo ou composição personalizada | /general-video |
Antes de finalizar a rota, leia references/routes/<workflow>.md — um arquivo pequeno por rota: o contrato canônico de entrada/saída/acionador (disponível antes que as skills de workflow instaladas de forma lazy estejam presentes) mais o ponto de entrada da entrevista para essa rota. Se o candidato não satisfizer seu contrato, continue roteando em vez de forçar a correspondência. Leia apenas o arquivo da rota correspondente.
Resolva ambiguidades comuns
- Um título animado curto, logotipo sting, impacto estatístico, impacto de gráfico, impacto de mapa ou terço inferior independente é
/motion-graphicsquando não é narrado e o movimento é a mensagem. Uma cartela de título estática, sequência narrada, montagem mais longa ou loop personalizado é/general-video. - Um motion graphic explicitamente curto pode usar uma URL, tweet, artigo ou captura de tela como material de origem. Uma solicitação genérica "faça um vídeo a partir deste site" é
/product-launch-video. - Filmagens existentes com legendas roteiam para
/embedded-captions; filmagens com cartelas de informação projetadas roteiam para/talking-head-recut. Re-temporizar, reordenar, recolorir, reenquadrar ou remixar filmagens é uma edição personalizada e cai em/general-video. - Um arquivo de música seleciona
/music-to-videoapenas quando sua grade de batidas impulsiona a peça. Música usada como fundo não substitui a rota correspondente ao assunto. - "Quero um storyboard" altera o processo de revisão, não o workflow. Sem outro sinal de roteamento, use
/general-video. Um storyboard esboçado confirmado pode ser ele próprio o entregável solicitado; o loop de revisão define esse ponto de parada. - Workflows narrativos especializados suportam até cerca de 3 minutos e são mais fortes em torno de 30–90s. Roteie uma peça claramente mais longa para
/general-video. A duração nunca substitui um porte explícito, deck, legenda, sobreposição ou entregável baseado em música.
3. Roteie uma vez, depois saia
Para criação nova, a camada de intenção (references/intent-interview.md) executa a conversa completa — memória, triagem, rodada de pitch, itens obrigatórios, formato da execução, entrega — e termina escrevendo BRIEF.md. O brief é o único artefato de roteamento que o workflow lê; nada mais tarde reabre esta skill ou a entrevista. Responda a qualquer pergunta posterior "o que a rota exigiu?" a partir de BRIEF.md.
4. Instale e entre no workflow
Antes de ler o workflow selecionado, instale ou atualize ele e as skills de domínio principais:
npx hyperframes skills update <workflow-name>
Use o nome simples sem /. Se o comando falhar, exiba o erro; não reconstrua o workflow a partir da memória. Todo o resto sobre instalação — a divisão core vs. lazy, o que init atualiza, diagnóstico, exclusão de CI e fallback sem CLI — está em references/skill-lifecycle.md.
5. Carregue skills de domínio sob demanda
| Necessidade | Skill |
|---|---|
| Estrutura de composição, atributos de tempo, faixas, variáveis, determinismo | /hyperframes-core |
| Regras de movimento, blueprints de cena, transições, adaptadores de runtime | /hyperframes-animation |
GSAP seguro para busca, CSS, Anime.js, WAAPI, FLIP, caminhos, máscaras, SVG, keyframes 3D ou diagnóstico hyperframes keyframes | /hyperframes-keyframes |
| Especificações de design, conceito, paleta, tipografia, narração, planejamento de batidas | /hyperframes-creative |
| Imagens, ícones, logotipos, áudio, legendas, ajustes, LUTs, mídia reutilizável | /media-use |
| Corte de locução, cadeias de efeitos de áudio, envelopes de automação, ou uma cadeia/fader em várias faixas (barramento submix) | /hyperframes-audio |
| Inicialização, lint, verificação, snapshots, comparação, renderização em lote, Studio, renderização, publicação ou diagnóstico | /hyperframes-cli |
| Blocos e componentes do registro | /hyperframes-registry |
| Ativos, tokens, componentes ou quadros de storyboard do Figma como movimento reconstruído | /figma |
Frases de edição de criador são solicitações de domínio cruzado. Carregue cada skill nomeada na linha correspondente:
| Solicitação do criador | Domínios necessários |
|---|---|
| "corte esta filmagem", corte seco, aparar, emendar, reordenar ou usar uma faixa de origem | /general-video + /hyperframes-core; core possui data-start, data-duration, data-media-start e layout de faixas. |
| zoom aqui, zoom in / zoom out, zoom multi-estado suave ou reenquadramento, Ken Burns ou movimento de câmera | /general-video + /hyperframes-core + /hyperframes-keyframes; anime o wrapper visual/interno de corte, não o clipe temporizado. |
| match cut ou transição de câmera com whip pan | /general-video + /hyperframes-animation + /hyperframes-keyframes + /hyperframes-registry; pesquise/instale uma primitiva de transição antes de criar manualmente. |
| fade, crossfade, ganho/volume de faixa, automação, duck/corte, efeitos de áudio ou um efeito em várias faixas | /general-video + /hyperframes-core + /hyperframes-audio; core coloca clipes, áudio mixa faixas colocadas — incluindo um barramento submix sobre um grupo delas. |
| edições de imagem e som que combinam cortes com movimento de câmera ou mixagem | /general-video + /hyperframes-core + /hyperframes-keyframes quando há movimento visual + /hyperframes-audio quando o som é esmaecido, mixado, duckado, automatizado ou processado. |
| originar ou gerar mídia, ou pré-processar uma rampa de velocidade não suportada/congelamento no meio da fonte | /media-use; apenas origem/geração/pré-processamento, nunca mixagem de faixas colocadas. |
A constante data-playback-rate é segura para renderização de imagem e som preservado em pitch. Ela não torna rampas de velocidade de fonte keyframeáveis; pré-processe rampas. Para contratos de edição copiáveis, carregue /hyperframes-core → references/creator-editing-recipes.md.
Feedback amplo sobre como mídia fotográfica...