HyperFrames
HTML é a fonte única da verdade para vídeo. Uma composição é um arquivo HTML com atributos data-* para temporização, uma timeline GSAP para animação e CSS para aparência. O framework gerencia visibilidade de clipes, reprodução de mídia e sincronização de timeline.
Integração com Open Design (essencial para esta superfície)
Quando esta skill é executada dentro do Open Design (ou seja, $OD_PROJECT_DIR está definido), o fluxo de saída é fixo: apenas o .mp4 renderizado deve ir para a raiz do projeto. Os arquivos fonte da composição (hyperframes.json, meta.json, index.html, assets) devem ficar dentro de um diretório de cache oculto para não poluir o Visualizador de Arquivos do usuário ou os "arquivos produzidos" do chat.
Fluxo de renderização dentro do OD — caminho rápido:
Para a maioria das solicitações OD ("vídeo de teste", "revelação de produto de 5s", "demo clip"), NÃO escreva o HTML da composição do zero. Use o scaffold embutido do HyperFrames e edite apenas o que o prompt realmente altera. O caminho "criar do zero" custa minutos de saída do modelo e tempo silencioso de ferramenta de chat; o caminho do scaffold custa segundos.
# 1. Escolha um slot de cache oculto. Prefixo de ponto → a listagem de
# arquivos do projeto OD o ignora, então os arquivos fonte nunca
# poluem o chat.
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"
# 2. Obtenha um scaffold imediatamente renderizável (hyperframes.json,
# meta.json, index.html com CDN do GSAP + window.__timelines.main
# já registrado). Isso é executado no seu shell — cópia pura de
# arquivos, sem Chrome, sem rede além do cache npx.
npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive
# 3. Edite APENAS $COMP/index.html — altere `data-duration` na raiz se
# precisar de uma duração diferente, troque a paleta de placeholder
# em <style>, adicione 1–3 <div>s de clipe para texto/imagens e
# anexe os tweens GSAP correspondentes dentro do bloco existente
# `window.__timelines["main"] = gsap.timeline({paused:true})`.
# Mantenha as edições mínimas; o scaffold já é HF válido.
# 4. Despache a renderização através do daemon OD. NÃO execute `npx
# hyperframes render` deste shell — o daemon executa para você em um
# processo sem sandbox. (Muitos CLIs de agente, Claude Code em
# particular, envolvem o Bash no sandbox-exec do macOS, sob o qual o
# subprocesso Chrome do puppeteer trava no meio da captura de frames.
# O processo daemon não tem sandbox, então as renderizações são
# concluídas de forma confiável.)
#
# O despachante retorna em ~1s com um {taskId}; conduza a
# renderização até a conclusão fazendo um loop de chamadas `od media wait <taskId>`.
# Cada chamada faz long-poll de até 25s (bem abaixo do limite padrão
# de 30s da sua ferramenta shell) e sai com 0/2/5 para sinalizar
# concluído/executando/falhou.
out=$(node "$OD_BIN" media generate \
--project "$OD_PROJECT_ID" \
--surface video \
--model hyperframes-html \
--output "<nome-descritivo>.mp4" \
--composition-dir "$COMP_REL")
ec=$?
task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
out=$(node "$OD_BIN" media wait "$task_id" --since "$since")
ec=$?
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
done
[ "$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }
Cada chamada generate e cada wait duram no máximo ~25s, portanto o limite padrão de ~30s da ferramenta shell do agente nunca é acionado. As linhas de progresso do HF (Capturando quadro N/M) são transmitidas para stderr ao vivo durante todo o loop. Quando a renderização termina, a última linha de stdout é {"file": { "name": "<output>", "size": …, "kind": "video", … }} — cite file.name em sua resposta para que o usuário saiba o que foi produzido.
Pule o Portão de Identidade Visual dentro do OD. A seção HARD-GATE abaixo (em "Abordagem") diz para você ler DESIGN.md / visual-style.md ou parar e fazer 3 perguntas de estilo antes de escrever qualquer composição. Esse portão é para projetos HF independentes. Projetos OD já têm sua própria camada de sistema de design — o usuário escolheu sua direção visual na criação do projeto. Para um teste de renderização OD, use o padrão: canvas escuro (#0b0b0f), um acento quente (#ffb76b), um acento frio (#7da4ff), movimento contido. Só peça informações estilísticas se o prompt do usuário for muito vago para sequer escolher um assunto (muito raro).
Quando pular o scaffold e escrever do zero: apenas quando o usuário pedir explicitamente algo que o modelo em branco claramente não pode hospedar (ex. timelines de múltiplas composições, sobreposições reativas a áudio, legendas sincronizadas a uma faixa TTS que já geraram). Para todo o resto, init + editar é o caminho padrão.
Os subcomandos HF mais leves que você AINDA pode executar do seu próprio shell (eles não precisam iniciar o Chrome):
npx hyperframes lint "$COMP"— valida a composição antes do despachonpx hyperframes transcribe <audio>— gera legendasnpx hyperframes tts <texto>— gera narração
Reserve o despacho do daemon para render/inspect/preview (qualquer coisa dependente do Chrome).
NÃO chame od media generate --model hyperframes-html — esse caminho de despachante retorna um 400 (AGENT_RENDERED) de propósito. HyperFrames é renderizado por você diretamente via npx.
NÃO coloque hyperframes.json / meta.json / index.html na raiz do projeto; a listagem de arquivos do OD varre recursivamente e o usuário veria três arquivos não relacionados aparecerem no chat.
Para opções de CLI além de render (lint, preview, transcribe, tts, inspect, benchmark), chame-as diretamente de sua ferramenta shell quando a tarefa justificar (ex., gere áudio TTS no cache antes de referenciá-lo na composição).
Abordagem
Antes de escrever HTML, pense em alto nível:
- O quê — o que o espectador deve experimentar? Identifique o arco narrativo, os momentos-chave e as batidas emocionais.
- Estrutura — quantas composições, quais são subcomposições vs embutidas, quais trilhas carregam o quê (vídeo, áudio, sobreposições, legendas).
- Temporização — quais clipes determinam a duração, onde as transições ocorrem, qual é o ritmo.
- Layout — construa o estado final primeiro. Veja "Layout Antes da Animação" abaixo.
- Animar — depois adicione movimento usando as regras abaixo.
Para pequenas edições (corrigir uma cor, ajustar temporização, adicionar um elemento), vá direto para as regras.
Portão de Identidade Visual
Verifique nesta ordem:
- DESIGN.md existe no projeto? → Leia-o. Use suas cores, fontes, regras de movimento e restrições "O que NÃO fazer" exatas.
- visual-style.md existe? → Leia-o. Aplique seu
style_prompt_fulle campos estruturados. (Nota:visual-style.mdé um arquivo específico do projeto.visual-styles.mdé a biblioteca de estilos com 8 predefinições nomeadas — arquivos diferentes.) - Usuário nomeou um estilo (ex., "Swiss Pulse", "dark and techy", "luxury brand")? → Leia visual-styles.md para as 8 predefinições nomeadas. Gere um DESIGN.md mínimo com:
## Style Prompt(um parágrafo),## Colors(3-5 valores hex com funções),## Typography(1-2 famílias de fontes),## What NOT to Do(3-5 anti-padrões). - Nada do acima? → Faça 3 perguntas antes de escrever qualquer HTML:
- Qual é o clima? (explosivo / cinematográfico / fluido / técnico / caótico / quente)
- Canvas claro ou escuro?
- Alguma cor de marca, fonte ou referência visual específica? Em seguida, gere um DESIGN.md mínimo a partir das respostas.
Toda composição deve rastrear sua paleta e tipografia até um DESIGN.md, visual-style.md ou direção explícita do usuário. Se você está usando #333, #3b82f6 ou Roboto — você pulou esta etapa.
Para padrões de movimento, dimensionamento, padrões de entrada e easing — siga house-style.md. O house style lida com COMO as coisas se movem. O DESIGN.md lida com a APARÊNCIA das coisas.
Layout Antes da Animação
Posicione cada elemento onde ele deve estar em seu momento mais visível — o quadro onde ele está totalmente entrado, corretamente colocado e ainda não está saindo. Escreva isso como HTML+CSS estático primeiro. Ainda sem GSAP.
Por que isso é importante: Se você posicionar elementos em seu estado inicial animado (fora da tela, escalados para 0, opacidade 0) e fizer tween até onde você acha que eles devem chegar, você está adivinhando o layout final. Sobreposições são invisíveis até o vídeo renderizar. Construindo o estado final primeiro, você pode ver e corrigir problemas de layout antes de adicionar qualquer movimento.
O processo
- Identifique o quadro herói para cada cena — o momento em que a maioria dos elementos está simultaneamente visível. Este é o layout que você constrói.
- Escreva CSS estático para esse quadro. O contêiner
.scene-contentDEVE preencher a cena inteira usandowidth: 100%; height: 100%; padding: Npx;comdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Use padding para empurrar o conteúdo para dentro — NUNCA useposition: absolute; top: Npxem um contêiner de conteúdo. Contêineres de conteúdo com posicionamento absoluto transbordam quando o conteúdo é mais alto que o espaço restante. Reserveposition: absoluteapenas para elementos decorativos. - Adicione entradas com
gsap.from()— anime DE fora da tela/invisível PARA a posição CSS. A posição CSS é a verdade absoluta; o tween descreve a jornada para chegar lá. - Adicione saídas com
gsap.to()— anime PARA fora da tela/invisível DA posição CSS.
Exemplo
/* scene-content preenche a cena, padding posiciona o conteúdo */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* O contêiner preenche qualquer tamanho de cena (1920x1080, 1080x1920, etc.).
O padding posiciona o conteúdo. Flex + gap lida com o espaçamento. */
ERRADO — dimensões fixas e posicionamento absoluto:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// Etapa 3: Anime PARA essas posições
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// Etapa 4: Anime PARA FORA dessas posições
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
Quando elementos compartilham espaço ao longo do tempo
Se o elemento A sai antes do elemento B entrar na mesma área, ambos devem ter posições CSS corretas para seus respectivos quadros heróis. A ordenação da timeline garante que eles nunca coexistam visualmente — mas se você pular a etapa de layout, não perceberá o caso em que eles acidentalmente se sobrepõem devido a um erro de temporização.
O que conta como sobreposição intencional
Efeitos em camadas (brilho atrás do texto, elementos de sombra, padrões de fundo) e designs empilhados em z (pilhas de cartões, camadas de profundidade) são intencionais. A etapa de layout serve para capturar sobreposições não intencionais — dois títulos pousando um em cima do outro, uma estatística cobrindo um rótulo, conteúdo vazando para fora do quadro.
Atributos de Dados
Todos os Clipes
| Atributo | Obrigatório | Valores |
|---|---|---|
id | Sim | Identificador único |
data-start | Sim | Segundos ou referência de ID de clipe ("el-1", "intro + 2") |
data-duration | Obrigatório para img/div/composições | Segundos. Vídeo/áudio padroniza para duração da mídia. |
data-track-index | Sim | Inteiro. Clipes na mesma trilha não podem se sobrepor. |
data-media-start | Não | Deslocamento de corte na fonte (segundos) |
data-volume | Não | 0-1 (padrão 1) |
data-track-index não afeta a camada visual — use CSS z-index.
Clipes de Composição
| Atributo | Obrigatório | Valores |
|---|---|---|
data-composition-id | Sim | ID único da composição |
data-start | Sim | Tempo inicial (composição raiz: use "0") |
data-duration | Sim | Tem precedência sobre a duração da timeline GSAP |
data-width / data-height | Sim | Dimensões em pixels (1920x1080 ou 1080x1920) |
data-composition-src | Não | Caminho para arquivo HTML externo |
Estrutura da Composição
Subcomposições carregadas via data-composition-src usam um wrapper <template>. Composições independentes (o index.html principal) NÃO usam <template> — elas colocam a div data-composition-id diretamente no <body>. Usar <template> em um arquivo independente esconde todo o conteúdo do navegador e quebra a renderização.
Estrutura da subcomposição:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- conteúdo -->
<style>
[data-composition-id="my-comp"] {
/* estilos escopados */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// tweens...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
Carregue na raiz: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Vídeo
…
[truncado para tradução]