Communitygithub.com

KingBridgeSS/sakugacut

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. Use ao implementar um SakugaCut TimelinePlan congelado. Para inicialização, lint, verificação, snapshot e renderização de rascunho via CLI, carregue hyperframes-cli; para pré-processamento, carregue hyperframes-media.

O que é sakugacut?

Este skill capacita agentes de IA a criar e gerenciar composições de vídeo complexas usando HTML como fonte da verdade, com foco em animações, transições e elementos visuais reativos. Ele é projetado para plataformas como Claude Code, Cursor e Codex, fornecendo uma estrutura robusta baseada em HyperFrames. O skill guia o agente por um processo estruturado: primeiro, estabelecendo um sistema de design a partir de um arquivo `design.md` ou presets visuais; depois, expandindo o prompt do usuário para garantir consistência; e, por fim, planejando e implementando a composição com um layout estático antes de adicionar animações com GSAP. Ele suporta a criação de cartelas de título, sobreposições, legendas, narrações e visuais reativos a áudio, bem como transições de cena e composições parametrizadas com variáveis. O skill enfatiza a construção do estado final do layout primeiro para evitar sobreposições não intencionais e inclui regras rigorosas para o uso de atributos de dados para controle de tempo, faixas e mídia. É particularmente útil para agentes que precisam implementar planos de timeline congelados, como um 'SakugaCut TimelinePlan', garantindo que cada elemento seja intencional e que o design visual seja respeitado antes de qualquer animação.

Funciona com~Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/KingBridgeSS/sakugacut/tree/HEAD/hyperframes_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 timeline GSAP para animação e CSS para aparência. A estrutura gerencia a visibilidade dos clipes, a reprodução de mídia e a sincronização da timeline.

Abordagem

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

Para solicitações abertas ("crie um vídeo de lançamento de produto para mim", "crie algo para nossa marca") onde o usuário não se comprometeu com uma direção, entenda a intenção antes de escolher cores:

  • Público — quem assiste a isso? Desenvolvedores? Executivos? Consumidores em geral?
  • Plataforma — onde é reproduzido? Rede social (15s), hero do site, demonstração de produto, interno?
  • Prioridade — o que é mais importante? Qualidade do movimento? Precisão do conteúdo? Fidelidade da marca? Velocidade?
  • Variações — o usuário quer opções ou uma única melhor tentativa?

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

Para solicitações exploratórias, considere oferecer 2 a 3 variações que diferem significativamente — não apenas mudanças de cor, mas ritmos, níveis de energia ou abordagens estruturais diferentes. Uma segura/esperada, uma ambiciosa. Não torne isso obrigatório — é uma ferramenta disponível quando apropriado.

Etapa 1: Sistema de design

Se design.md ou DESIGN.md existir no projeto, leia-o primeiro (verifique 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 — não invente cores ou substitua fontes. Qualquer formato funciona (frontmatter YAML, prosa, tabelas — apenas extraia os valores).

Se mencionar fontes que você não encontra localmente (sem diretório fonts/ com arquivos .woff2, não é uma fonte integrada), avise o usuário antes de escrever HTML: "design.md especifica a fonte [nome da fonte], mas nenhum arquivo de fonte foi encontrado. Adicione arquivos .woff2 a fonts/ ou usarei a alternativa integrada mais próxima."

Se não existir design.md, ofereça ao usuário uma escolha:

  1. O usuário nomeou um estilo ou clima? → Leia visual-styles.md para os 8 presets nomeados. Escolha o mais próximo.
  2. Quer navegar pelas opções visualmente? → Execute o seletor de design: leia references/design-picker.md para o fluxo de trabalho completo. Isso exibe uma página de seletor visual. O usuário configura clima, paleta, tipografia e movimento no navegador, depois copia o design.md gerado e o cola de volta na conversa.
  3. Quer pular e ir rápido? → Pergunte: clima, claro ou escuro, cores/fontes da marca? Depois escolha uma paleta de house-style.md.

design.md define a marca. Não define regras de composição de vídeo. Essas vêm de references/video-composition.md e house-style.md. Use as cores da marca em escala apropriada para vídeo — não na opacidade da UI da web.

Etapa 2: Expansão do prompt

Sempre execute em cada composição (exceto peças de cena única e edições triviais). Esta etapa fundamenta a intenção do usuário em relação a design.md e house-style.md e produz um intermediário consistente que todo agente downstream lê da mesma forma.

Leia references/prompt-expansion.md para o processo completo e formato de saída.

Etapa 3: Plano

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. Ritmo — declare o ritmo da sua cena antes de implementar. Quais cenas são rápidas, quais são pausadas, onde os shaders aparecem, onde a energia atinge o pico. Nomeie o padrão: rápido-rápido-DEVAGAR-rápido-SHADER-pausa. Leia references/beat-direction.md para modelos de ritmo.
  4. Temporização — quais clipes impulsionam a duração, onde as transições ocorrem, qual é o ritmo.
  5. Layout — construa o estado final primeiro. Veja "Layout Antes da Animação" abaixo.
  6. Animação — depois adicione movimento usando as regras abaixo.

Construa o que foi solicitado. Um pedido de "uma cartela de título" não é um pedido de "uma cartela de título + 3 cenas de apoio + música ambiente + legendas." Cada cena, cada elemento, cada tween deve merecer seu lugar. Se cenas ou elementos adicionais realmente melhorariam a peça, proponha-os — não os adicione.

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

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á colocado corretamente e ainda não está saindo. Escreva isso como HTML+CSS estático primeiro. Ainda sem GSAP.

Por que isso é importante: Se você posicionar os elementos em seu estado inicial animado (fora da tela, dimensionados para 0, opacidade 0) e animá-los até onde você acha que devem chegar, você está adivinhando o layout final. Sobreposições ficam 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 hero para cada cena — o momento em que o maior número de elementos está simultaneamente visível. Este é o layout que você constrói.
  2. Escreva CSS estático para esse quadro. O contêiner .scene-content DEVE preencher toda a cena 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 use position: absolute; top: Npx em 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. 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á. (Em subcomposições carregadas via data-composition-src, prefira gsap.fromTo() — veja as regras GSAP estruturais em references/motion-principles.md.)
  4. 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 codificadas 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 os 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 hero. A ordem 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 cartas, camadas de profundidade) são intencionais. A etapa de layout é para detectar sobreposições não intencionais — 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 do clipe ("el-1", "intro + 2")
data-durationObrigatório para img/div/composiçõesSegundos. Vídeo/áudio usa a duração da mídia como padrão.
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 único da composição
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
data-variable-valuesNãoObjeto JSON de substituições de variáveis por instância em um host de subcomp

No elemento <html> raiz:

AtributoObrigatórioValores
data-composition-variablesNãoArray JSON de variáveis declaradas (id/tipo/rótulo/padrão) — orienta a UI de edição do Studio e fornece padrões para getVariables()

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 em <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 com escopo */
      }
    </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>

Carregamento 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>

Variáveis (Composições Parametrizadas)

Renderize a mesma composição com conteúdo diferente — título, cor do tema, preços, legendas — sem editar o HTML de origem.

Padrão de três etapas:

  1. Declare variáveis na raiz <html> da composição com data-composition-variables. Cada entrada precisa de id, type (um de string, number, color, boolean, enum), label e default. Entradas do tipo enum também precisam de options: [{value, label}, ...].
  2. Leia os valores resolvidos dentro do script da composição com window.__hyperframes.getVariables(). Retorna o resultado mesclado dos padrões declarados + substituições por instância + substituições da CLI.
  3. Substitua no momento da renderização com npx hyperframes render --variables '{...}' (nível superior) ou com data-variable-values='{...}' no elemento host (por instância para subcomps).
<!doctype html>
<html
  data-composition-variables='[
  {"id":"title","type":"string","label":"Título","default":"Olá"},
  {"id":"theme","type":"enum","label":"Tema","default":"light","options":[
    {"value":"light","label":"Claro"},
    {"value":"dark","label":"Escuro"}
  ]}
]'
>
  <body>
    <div data-composition-id="root" data-width="1920" data-height="1080">
      <h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
      <script>
        const { title, theme } = window.__hyperframes.getVariables();
        document.getElementById("hero").textContent = title;
        document.body.dataset.theme = theme;
      </script>
    </div>
  </body>
</html>
# Pré-visualização de desenvolvimento usa os padrões declarados
npx hyperframes preview

# Renderizar com substituições
npx hyperframes render --variables '{"title":"Relatório Q4","theme":"dark"}' --output q4.mp4

# Ou de um arquivo JSON
npx hyperframes render --variables-file ./vars.json

Valores por instância em subcomposições: o mesmo getVariables() funciona dentro de subcomps carregadas via data-composition-src. Cada elemento host passa seus próprios valores:

<div
  data-composition-id="card-pro"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"Pro","price":"$29"}'
></div>
<div
  data-composition-id="card-enterprise"
  data-composition-src="compositions/card.html"


…

[truncado para tradução]

Habilidades Relacionadas