Communitygithub.com

scott-fryxell/brayness

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 HyperFrames HTML.

O que é brayness?

Esta skill capacita agentes de IA (como Claude Code) a criar vídeos inteiros usando HTML como fonte da verdade. Ela define uma metodologia rigorosa: começar com um sistema de design (definido por um arquivo design.md ou por escolha do usuário), expandir o prompt para um plano intermediário consistente e, em seguida, construir a composição cena por cena. O fluxo de trabalho é único: primeiro, o layout estático (a posição final visível de cada elemento) é construído com CSS, e só depois a animação (entradas com gsap.from()) é adicionada. As regras são inflexíveis: todas as cenas devem usar transições, nenhuma animação de saída é permitida, exceto na cena final, e as linhas do tempo devem ser sincronizadas e determinísticas (sem Math.random()). A skill também cobre o ciclo de desenvolvimento completo: pré-processamento de assets (TTS, transcrição, remoção de fundo), lint, preview, render e contribuição de blocos de registro. As referências são extensas, cobrindo desde tipografia e motion design até técnicas de legenda dinâmica e efeitos reativos a áudio.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/scott-fryxell/brayness/tree/HEAD/skills/hyperframes

Perguntar na sua IA favorita

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

Documentação

HyperFrames

O HTML é a fonte da verdade para o vídeo. Uma composição é um arquivo HTML com atributos data-* para temporização, uma linha do tempo 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 linha do tempo.

API de atributos, estrutura de composição/modelo, variáveis e regras de mídia: references/authoring.md. Leia antes de escrever sua primeira composição HTML em uma sessão.

Abordagem

Descoberta (apenas para solicitações exploratórias)

Para solicitações abertas ("faça um vídeo de lançamento de produto") onde o usuário não se comprometeu com uma direção, entenda a intenção antes de escolher cores: público, plataforma, prioridade (qualidade do movimento vs. precisão vs. velocidade) e se ele deseja variações. Se houver variações, ofereça 2-3 que difiram em ritmo ou estrutura - uma segura, uma ambiciosa - não apenas trocas de cores.

Para solicitações específicas ("adicione uma cartela de título", "corrija o tempo da cena 3"), pule a descoberta.

Etapa 1: Sistema de design

Se design.md ou DESIGN.md existir, leia primeiro (ambas as capitalizações - são arquivos diferentes no Linux). É a fonte da verdade para cores da marca, fontes e restrições - use seus valores exatos. Se nomear fontes sem arquivos .woff2 em fonts/ e sem correspondência integrada, avise o usuário antes de escrever HTML.

Se não existir design.md, ofereça uma escolha:

  1. O usuário nomeou um estilo ou clima? Leia visual-styles.md (8 predefinições nomeadas), escolha a mais próxima.
  2. Navegar visualmente? Execute o seletor de design - references/design-picker.md.
  3. Ir rápido? Pergunte o clima, claro/escuro, cores/fontes da marca; escolha uma paleta de house-style.md.

design.md define a marca, não as regras de composição de vídeo. Essas vêm de references/video-composition.md e house-style.md. Cores da marca em escala de vídeo, não opacidade de interface web.

Etapa 2: Expansão do prompt

Execute em todas as composições, exceto em peças de cena única e edições triviais - funda a intenção contra design.md/house-style.md em um intermediário consistente. Processo e formato: references/prompt-expansion.md.

Etapa 3: Planejar

  1. O quê - arco narrativo, momentos-chave, batidas emocionais.
  2. Estrutura - quantas composições, subcomposições vs. inline, quais trilhas carregam o quê.
  3. Ritmo - declare o ritmo da cena antes de implementar (rápido-rápido-LENTO-rápido-SHADER-pausa). Modelos: references/beat-direction.md.
  4. Tempo - quais clipes determinam a duração, onde as transições aterrissam.
  5. Layout - construa o estado final primeiro (próxima seção).
  6. Animar - depois adicione movimento.

Construa o que foi solicitado. "Uma cartela de título" não é "uma cartela de título + 3 cenas de apoio + música + legendas." Proponha extras; não os adicione.

Para edições pequenas, vá direto para as regras.

Layout Antes da Animação

Posicione cada elemento onde ele deve estar em seu momento mais visível - completamente entrado, colocado corretamente, ainda não saindo. Escreva isso como HTML+CSS estático primeiro. Sem GSAP ainda.

Por quê: se você posicionar os elementos em seu estado inicial animado (fora da tela, opacidade 0) e animar em direção a onde você acha que eles pousam, você está adivinhando o layout final, e sobreposições permanecem invisíveis até a renderização. Construa o estado final primeiro e os bugs de layout são visíveis antes do movimento existir.

  1. Identifique o quadro herói por cena - o momento em que a maioria dos elementos está simultaneamente visível. Construa esse layout.
  2. Escreva CSS estático para ele. .scene-content DEVE preencher a cena: width: 100%; height: 100%; padding: Npx; com display: flex; flex-direction: column; gap: Npx; box-sizing: border-box. O padding empurra o conteúdo para dentro - NUNCA use position: absolute; top: Npx em um contêiner de conteúdo (ele transborda quando o conteúdo cresce). Reserve o posicionamento absoluto para elementos decorativos.
  3. Entradas com gsap.from() - anime DE fora da tela PARA a posição CSS. O CSS é a verdade fundamental; a animação é a jornada. (Subcomposições carregadas via data-composition-src: prefira gsap.fromTo() - veja references/motion-principles.md.)
  4. Apenas na cena final: saídas com gsap.to(). Todas as outras cenas terminam totalmente visíveis - a transição É a saída (regra de transição 3 abaixo).

Se o elemento A sair antes do elemento B entrar na mesma área, dê a ambos as posições CSS corretas para seus próprios quadros heróis - a linha do tempo os impede de coexistir, e a etapa de layout captura a sobreposição acidental de erros de cronometragem. Sobreposição intencional (brilho atrás do texto, pilhas de cartões) é aceitável; a etapa existe para capturar sobreposição não intencional - dois títulos colidindo, uma estatística cobrindo um rótulo, conteúdo fora do quadro.

Contrato da Linha do Tempo

  • Todas as linhas do tempo começam { paused: true } - o player controla a reprodução
  • Registre cada linha do tempo: window.__timelines["<composition-id>"] = tl
  • O framework aninha automaticamente as sublinhas do tempo - NÃO as adicione manualmente
  • A duração vem de data-duration, não do comprimento da linha do tempo GSAP
  • Nunca crie animações vazias para definir a duração

Regras (Inegociáveis)

Determinístico: sem Math.random(), Date.now() ou lógica baseada em tempo. PRNG com semente (ex.: mulberry32) para pseudoaleatório.

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

Conflitos de animação: nunca anime a mesma propriedade no mesmo elemento de várias linhas do tempo simultaneamente.

Sem repeat: -1: repetições infinitas quebram o motor de captura. Calcule repeat: Math.ceil(duration / cycleDuration) - 1.

Construção síncrona da linha do tempo: nunca construa linhas do tempo dentro de async/await, setTimeout ou Promises - o motor de captura lê window.__timelines de forma síncrona após o carregamento. As fontes são incorporadas pelo compilador; sem espera por carregamento de fonte.

Nunca faça:

  1. Esqueça o registro de window.__timelines
  2. Use vídeo para áudio - sempre vídeo mudo + <audio> separado
  3. Aninhe vídeo dentro de uma div com tempo - use um wrapper sem tempo
  4. Use data-layer (use data-track-index) ou data-end (use data-duration)
  5. Anime dimensões do elemento de vídeo - anime uma div wrapper
  6. Chame play/pause/seek na mídia - o framework controla a reprodução
  7. Crie um contêiner de nível superior sem data-composition-id
  8. Use repeat: -1 em qualquer linha do tempo ou animação
  9. Construa linhas do tempo de forma assíncrona
  10. Use 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) em ou após o data-start do clipe.
  11. Use <br> no texto do conteúdo - ele empilha com a quebra natural de linha e causa sobreposição; use max-width. Exceção: títulos de exibição curtos deliberadamente uma palavra por linha.

Transições de Cena (Inegociáveis)

Toda composição com várias cenas DEVE seguir todas as quatro. Violar qualquer uma é uma composição quebrada.

  1. SEMPRE use transições entre cenas. Sem cortes secos.
  2. SEMPRE anime CADA elemento ENTRANDO via gsap.from(). Nada aparece totalmente formado. Cinco elementos significam cinco animações de entrada.
  3. NUNCA use animações de saída exceto na cena final. Sem gsap.to() desbotando a opacidade, movendo para fora da tela ou escalando para 0 antes de uma transição - a transição É a saída, e a cena de saída deve estar totalmente visível quando ela disparar. Uma animação de saída antes de uma transição entrega uma transição com um quadro vazio.
  4. Apenas na cena final pode desbotar elementos.

Seleção e implementação de transição: references/transitions.md.

Diretrizes de Animação

  • Desloque a primeira animação em 0,1-0,3s (não t=0)
  • Varie as atenuações - pelo menos 3 atenuações diferentes por cena, sem padrão de entrada repetido dentro de uma cena
  • Evite gradientes lineares em tela cheia em fundos escuros (bandeamento H.264) - gradientes radiais ou sólidos + brilho localizado
  • Títulos de 60px+, corpo de 20px+, rótulos de dados de 16px+
  • font-variant-numeric: tabular-nums em colunas de números

Editando Composições Existentes

  • Leia os arquivos reais, não adivinhe. A composição É a especificação - extraia códigos hex, fontes e padrões de atenuação exatos da fonte, não da memória.
  • Altere apenas o que foi solicitado; preserve o tempo dos clipes não relacionados.

Lista de Verificação de Saída

Rápido (execute imediatamente, bloqueie nos resultados):

  • npx hyperframes lint e npx hyperframes validate passam
  • Aderência ao design verificada se design.md existir

Lento (execute em paralelo enquanto apresenta a pré-visualização):

  • npx hyperframes inspect passa, ou cada estouro reportado está intencionalmente marcado
  • Avisos de contraste resolvidos
  • Coreografia de animação verificada (script animation-map)

Como executar e corrigir cada verificação: references/quality-checks.md.

Índice de Referência

Sempre leia para qualquer nova composição:

ArquivoAbrange
references/authoring.mdAtributos data, estrutura de modelo, variáveis, vídeo/áudio, fontes/assets
references/video-composition.mdRegras de meio de vídeo - essas substituem instintos da web
references/typography.mdPares de fontes, OpenType, ajustes de fundo escuro
references/motion-principles.mdDesign de movimento, movimento de imagem, regras GSAP de suporte de carga

Também leia sempre para composições com várias cenas:

ArquivoAbrange
references/beat-direction.mdModelos de ritmo, verbos de coreografia, camadas de profundidade
references/transitions.mdSeleção de transição; catálogo roteia para implementações; transições de shader vivem no pacote npm @hyperframes/shader-transitions (leia sua fonte em node_modules)

Leia quando a tarefa exigir:

ArquivoLeia quando
references/quality-checks.mdExecutando verificações inspect/contrast/design/animation-map
references/cli.mdQualquer comando CLI; solução de problemas de build/render
references/captions.mdQualquer texto sincronizado com o tempo do áudio
references/transcript-guide.mdManipulação de transcrição do lado da legenda (a invocação da CLI vive em media.md)
references/dynamic-techniques.mdAnimação de legenda dinâmica (karaokê, slam, dispersão)
references/audio-reactive.mdVisuais respondendo à música/voz
references/css-patterns.mdDestaque de marcador (destaque, círculo, explosão, rabisco)
references/techniques.mdTécnicas de planejamento por batida (11 padrões com código)
references/narration.mdNarração/TTS: ritmo e estrutura do roteiro
references/media.mdTTS (Kokoro), transcrição (Whisper), remoção de fundo
references/prompt-expansion.mdEtapa 2 da abordagem
references/design-picker.mdCriando um design.md visualmente
references/from-website.mdTransformando um site em um vídeo
references/registry.mdInstalando/contribuindo blocos de registro (hyperframes add)
visual-styles.mdUsuário nomeia um estilo; gerando design.md
house-style.mdPadrões estéticos quando não há design.md
patterns.mdPiP, cartelas de título, apresentações de slides
data-in-motion.mdDados, estatísticas, infográficos

Adaptadores de runtime (leia quando a composição usa esse runtime em vez de GSAP): waapi, lottie, three, animejs, css-animations, typegpu.

Habilidades Relacionadas