Communitygithub.com

GanQiao1990/skills_2026

Crie composições de vídeo, animações, cartelas de título, sobreposições, legendas, narrações, visuais reativos a áudio e transições de cena em HTML HyperFrames.

O que é skills_2026?

Este skill capacita agentes de IA a atuarem como autores completos de vídeo baseados em HTML usando o framework HyperFrames. Ele abrange todo o fluxo de produção de vídeo — desde a estrutura da composição e temporização até animações, identidade visual, legendas sincronizadas, efeitos visuais reativos a áudio (como batida sincronizada e pulsação), sobreposições animadas de texto (marcadores, círculos desenhados à mão) e transições de cena (crossfade, wipe, revelação). O skill é compatível com qualquer agente que opere plataformas de edição de vídeo baseadas em HTML (como Claude Code, Cursor ou Codex) e fornece regras rígidas para garantir saídas determinísticas e de alta qualidade. Ele exige que uma identidade visual (DESIGN.md) seja definida antes de escrever qualquer HTML, prioriza o layout estático antes da animação, e impõe um 'contrato de timeline' usando GSAP com construção síncrona, proibindo aleatoriedade, repetições infinitas e manipulação direta de mídia. Cenários de erro comuns (como cenas ocultas por display: none em vez de opacidade) são explicitamente documentados para depuração.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GanQiao1990/skills_2026/tree/HEAD/openclaw-imports/hyperframes

Perguntar na sua IA favorita

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

Prévia

Do README da skill

Documentação

HyperFrames

HTML é a fonte da verdade para o 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 a visibilidade dos clipes, a reprodução de mídia e a sincronização da timeline.

Escopo geral e fluxos de trabalho estreitos absorvidos

Este skill é o guarda-chuva de nível de classe para a autoria HyperFrames. Ele abrange estrutura de composição, temporização, animação, identidade visual, legendas, visuais reativos a áudio e construção de cena com qualidade de produção. Use o skill hyperframes-cli para referência de comandos, e use website-to-hyperframes quando o material de origem for um site existente. Notas estreitas de produção/depuração de sessão única foram rebaixadas para referências de suporte aqui.

Subseção: armadilhas do fluxo de produção

Notas históricas de produção enfatizaram algumas armadilhas de ambiente que permanecem úteis:

  • Prefira caminhos de projeto/saída apenas ASCII ao renderizar; caminhos não ASCII podem quebrar o Chrome headless ou subprocessos do renderizador.
  • Se a codificação MP4 falhar sob o Conda FFmpeg, force o FFmpeg do sistema com export PATH=/usr/bin:$PATH ou renderize WebM como fallback.
  • Quando objetos de timeline personalizados são usados em vez de GSAP, eles devem expor métodos compatíveis com GSAP duration(), pause() e seek(time).
  • Se o vídeo final parecer preto ou vazio, verifique primeiro se um contêiner .clip com temporização foi ocultado enquanto apenas seus filhos foram animados. Uma classe utilitária como .hidden { display: none; } em wrappers de cena produz o modo de falha clássico: o áudio renderiza, o fundo renderiza, mas nenhum texto/cartela aparece porque a cena pai nunca entra em layout/paint. Para wrappers de cena com temporização, oculte com opacity: 0 ou opacidade controlada por timeline em vez de display: none.
  • Para JS crítico em tempo de execução, como GSAP, prefira manter uma cópia local no projeto (por exemplo assets/gsap.min.js) em vez de depender de buscas ao CDN ao vivo durante a renderização.
  • Adicione <link rel="icon" href="data:,"> a composições independentes para suprimir o ruído de favicon 404 do navegador headless quando nenhum favicon fizer parte do projeto.
  • Verifique visualmente extraindo quadros com FFmpeg e inspecionando capturas de tela, não apenas confiando em um código de saída de renderização bem-sucedido.

Referências de suporte rebaixadas

  • references/hyperframes-video-production.md
  • references/hyperframes-workflow.md

Abordagem

Antes de escrever HTML, pense em alto nível:

  1. O quê — o que o espectador deve experimentar? Identifique o arco narrativo, os momentos-chave e os batimentos emocionais.
  2. Estrutura — quantas composições, quais são subcomposições vs inline, quais faixas carregam o quê (vídeo, áudio, sobreposições, legendas).
  3. Temporização — quais clipes conduzem a duração, onde as transições caem, qual é o ritmo.
  4. Layout — construa o estado final primeiro. Veja "Layout Antes da Animação" abaixo.
  5. Animar — então adicione movimento usando as regras abaixo.

Para pequenas edições (corrigir uma cor, ajustar temporização, adicionar um elemento), pule direto para as regras.

Portal de Identidade Visual

Verifique nesta ordem:

  1. DESIGN.md existe no projeto? → Leia-o. Use suas cores exatas, fontes, regras de movimento e restrições do "O que NÃO Fazer".
  2. visual-style.md existe? → Leia-o. Aplique seu style_prompt_full e 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.)
  3. 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 antipadrões).
  4. Nada disso? → Faça 3 perguntas antes de escrever qualquer HTML:
    • Qual é o clima? (explosivo / cinematográfico / fluido / técnico / caótico / acolhedor)
    • Tela clara ou escura?
    • Alguma cor, fonte ou referência visual de marca específica? Em seguida, gere um DESIGN.md mínimo a partir das respostas.

Cada composição deve rastrear sua paleta e tipografia de volta a um DESIGN.md, visual-style.md ou direção explícita do usuário. Se você estiver recorrendo a #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 estilo da casa 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 entrou completamente, está posicionado corretamente e ainda não está saindo. Escreva isso como HTML+CSS estático primeiro. Ainda sem GSAP.

Por que isso importa: Se você posicionar elementos em seu estado inicial animado (fora da tela, escalado para 0, opacidade 0) e interpolar para onde acha que eles devem pousar, você está adivinhando o layout final. Sobreposições são invisíveis até que o vídeo seja renderizado. Ao construir o estado final primeiro, você pode ver e corrigir problemas de layout antes de adicionar qualquer movimento.

O processo

  1. Identifique o quadro heroico para cada cena — o momento em que mais elementos estão simultaneamente visíveis. Este é o layout que você constrói.
  2. Escreva CSS estático para esse quadro. O contêiner .scene-content DEVE preencher a cena inteira usando width: 100%; height: 100%; padding: Npx; com display: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Use padding para empurrar o conteúdo para dentro — NUNCA position: absolute; top: Npx em um contêiner de conteúdo. Contêineres de conteúdo posicionados absolutamente transbordam quando o conteúdo é mais alto que o espaço restante. Reserve position: absolute apenas para elementos decorativos.
  3. Adicione entradas com gsap.from() — anime DE fora da tela/invisível PARA a posição CSS. A posição CSS é a verdade fundamental; o tween descreve a jornada para chegar lá.
  4. Adicione saídas com gsap.to() — anime PARA fora da tela/invisível A PARTIR 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;
}
/* Contêiner preenche qualquer tamanho de cena (1920x1080, 1080x1920, etc).
   Padding posiciona o conteúdo. Flex + gap lidam 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 DENTRO dessas 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 heroicos. 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 cartelas, camadas de profundidade) são intencionais. A etapa de layout é para detectar sobreposição não intencional — dois títulos caindo 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

AtributoObrigatórioValores
idSimIdentificador único
data-startSimSegundos ou referência de ID de clipe ("el-1", "intro + 2")
data-durationObrigatório para img/div/compositionsSegundos. Vídeo/áudio padrão para duração da mídia.
data-track-indexSimInteiro. Clipes na mesma faixa não podem se sobrepor.
data-media-startNãoDeslocamento de corte na origem (segundos)
data-volumeNão0-1 (padrão 1)

data-track-index não afeta a camada visual — use CSS z-index.

Clipes de Composição

AtributoObrigatórioValores
data-composition-idSimID de composição único
data-startSimTempo de início (composição raiz: use "0")
data-durationSimTem precedência sobre a duração da timeline GSAP
data-width / data-heightSimDimensões em pixels (1920x1080 ou 1080x1920)
data-composition-srcNãoCaminho 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 o div data-composition-id diretamente no <body>. Usar <template> em um arquivo independente oculta todo o conteúdo do navegador e quebra a renderização.

Estrutura de 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 e Áudio

O vídeo deve estar muted playsinline. O áudio é sempre um elemento <audio> separado:

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

Contrato da Timeline

  • Todas as timelines começam { paused: true } — o reprodutor controla a reprodução
  • Registre cada timeline: window.__timelines["<composition-id>"] = tl
  • O framework aninha automaticamente subtimelines — NÃO as adicione manualmente
  • A duração vem de data-duration, não do comprimento da timeline GSAP
  • Nunca crie tweens vazios para definir duração

Regras (Não Negociáveis)

Determinístico: Sem Math.random(), Date.now() ou lógica baseada em tempo. Use um PRNG com semente se precisar de valores pseudo-aleatórios (ex.: mulberry32).

GSAP: Anime apenas propriedades visuais (opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, transformações). NÃO anime visibility, display ou chame video.play()/audio.play().

Conflitos de animação: Nunca anime a mesma propriedade no mesmo elemento de múltiplas timelines simultaneamente.

Sem repeat: -1: Timelines de repetição infinita quebram o mecanismo de captura. Calcule a contagem exata de repetições a partir da duração da composição: repeat: Math.ceil(duration / cycleDuration) - 1.

Construção síncrona da timeline: Nunca construa timelines dentro de async/await, setTimeout ou Promises. O mecanismo de captura lê window.__timelines de forma síncrona após o carregamento da página. As fontes são incorporadas pelo compilador, portanto estão disponíveis imediatamente — não há necessidade de esperar pelo carregamento de fontes.

Nunca faça:

  1. Esquecer o registro de window.__timelines
  2. Usar vídeo para áudio — sempre vídeo mudo + <audio> separado
  3. Aninhar vídeo dentro de um div com temporização — use um wrapper sem temporização
  4. Usar data-layer (use data-track-index) ou data-end (use data-duration)
  5. Animar dimensões do elemento de vídeo — anime um div wrapper
  6. Chamar play/pause/seek na mídia — o framework controla a reprodução
  7. Criar um contêiner de nível superior sem data-composition-id
  8. Usar repeat: -1 em qualquer timeline ou tween — sempre repetições finitas
  9. Construir timelines de forma assíncrona (dentro de async, setTimeout, Promise)
  10. Usar gsap.set() em elementos de clipe de cenas posteriores — eles não existem no DOM no carregamento da página. Use tl.set(selector, vars, timePosition) dentro da timeline no momento ou após o tempo data-start do clipe.
  11. Usar <br> no texto do conteúdo — quebras de linha forçadas não levam em conta a largura real da fonte renderizada. Texto que quebra naturalmente + um <br> produz uma quebra extra indesejada, causando sobreposição. Deixe o texto quebrar via max-width. Exceção: títulos de exibição curtos onde cada palavra está deliberadamente em sua própria linha (ex.: "THE\nIMMORTAL\nGAME" a 130px).

Transições de Cena (Não Negociáveis)

Toda composição com múltiplas cenas DEVE seguir TODAS estas regras. Violar qualquer uma delas é uma composição quebrada.

  1. SEMPRE use transições entre cenas. Sem cortes secos. Sem exceções.
  2. SEMPRE use animações de entrada em cada cena. Cada elemento anima ENTRANDO via gsap.from(). Nenhum elemento pode aparecer totalmente formado. Se uma cena

Habilidades Relacionadas