Communitygithub.com

delorenj/skills

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

O que é skills?

Este skill capacita agentes de IA a produzirem vídeos completos utilizando HTML, CSS e JavaScript com a estrutura HyperFrames. Ele abrange todo o fluxo de produção de vídeo, desde a criação de composições individuais (cartões de título, animações, sobreposições) até a sincronização de múltiplas cenas com transições (crossfades, wipes, reveals) e efeitos avançados como legendas sincronizadas com áudio, narração por texto-para-fala, animações reativas a batidas musicais (beat sync, glow, pulse) e destaques de texto animados (marcadores, círculos desenhados à mão, rabiscos). O skill se integra perfeitamente com as ferramentas de linha de comando `hyperframes-cli` (para inicialização, lint, inspeção, pré-visualização e renderização) e `hyperframes-media` (para pré-processamento de ativos como TTS e remoção de fundo), oferecendo um ambiente completo e profissional para criação de conteúdo em vídeo diretamente no navegador ou em pipelines de automação.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/delorenj/skills/tree/HEAD/hyperframes-upstream-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. O framework 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 ("faça um vídeo de lançamento de produto", "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-alvo — quem assiste? Desenvolvedores? Executivos? Consumidores em geral?
  • Plataforma — onde será exibido? Rede social (15s), site principal, demonstração de produto, interno?
  • Prioridade — o que é mais importante? Qualidade do movimento? Precisão do conteúdo? Fidelidade à marca? Velocidade?
  • Variações — o usuário quer opções ou apenas a melhor versão?

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

Para solicitações exploratórias, considere oferecer 2-3 variações que diferem significativamente — não apenas trocas de cores, mas ritmos, níveis de energia ou abordagens estruturais diferentes. Uma segura/esperada, uma ambiciosa. Não é 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 grafias — 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 nem substitua fontes. Qualquer formato funciona (frontmatter YAML, prosa, tabelas — apenas extraia os valores).

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

Se design.md não existir, 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 visualmente pelas opções? → Execute o seletor de design: leia references/design-picker.md para o fluxo completo. Isso serve uma página seletora visual. O usuário configura clima, paleta, tipografia e movimento no navegador, então copia o design.md gerado e o cola de volta na conversa.
  3. Quer pular e ir rápido? → Pergunte: clima, claro ou escuro, alguma cor/fonte da marca? Então escolha uma paleta em house-style.md.

design.md define a marca. Ele não define regras de composição de vídeo. Essas vêm de references/video-composition.md e house-style.md. Use cores da marca em escala apropriada para vídeo — não na opacidade de uma UI 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 ancora a intenção do usuário em relação a design.md e house-style.md e produz um intermediário consistente que todos os agentes downstream leem da mesma forma.

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

Etapa 3: Planejamento

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

  1. O quê — o que o espectador deve experienciar? Identifique o arco narrativo, os momentos-chave e os batimentos emocionais.
  2. Estrutura — quantas composições, quais são sub-composições vs. inline, quais faixas carregam o quê (vídeo, áudio, sobreposições, legendas).
  3. Ritmo — declare seu ritmo de cena antes de implementar. Quais cenas são rápidas, quais são pausadas, onde os shaders se encaixam, onde a energia atinge o pico. Nomeie o padrão: rápido-rápido-LENTO-rápido-SHADER-pausa. Leia references/beat-direction.md para modelos de ritmo.
  4. Temporização — quais clipes determinam a duração, onde as transições se encaixam, qual é o ritmo.
  5. Layout — construa o estado final primeiro. Veja "Layout Antes da Animação" abaixo.
  6. Animar — então adicione movimento usando as regras abaixo.

Construa o que foi pedido. Uma solicitação para "um cartão de título" não é uma solicitação para "um cartão 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 melhorariam genuinamente a peça, proponha-os — não os adicione.

Para pequenas edições (corrigir uma cor, ajustar 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 em que ele entrou completamente, está corretamente posicionado e ainda não está saindo. Escreva isso como HTML+CSS estático primeiro. Sem GSAP ainda.

Por que isso importa: Se você posicionar elementos em seu estado inicial animado (fora da tela, escalados para 0, opacidade 0) e animá-los até onde você acha que devem chegar, você está adivinhando o layout final. Sobreposições são invisíveis até o vídeo ser 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 herói 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 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 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 absoluta; o tween descreve a jornada para chegar lá. (Em sub-composições carregadas via data-composition-src, prefira gsap.fromTo() — veja regras GSAP estruturais em references/motion-principles.md.)
  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.).
   O 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 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 no 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 coexistem visualmente — mas se você pular a etapa de layout, não perceberá o caso em que eles se sobrepõem acidentalmente 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 pegar 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 do clipe ("el-1", "intro + 2")
data-durationObrigatório para img/div/composiçõesSegundos. Vídeo/áudio assume a 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 z-index no CSS.

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 sub-comp

No elemento raiz <html>:

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

Estrutura de Composição

Sub-composições carregadas via data-composition-src usam um wrapper <template>. Composições independentes (o arquivo index.html principal) NÃO usam <template> — elas colocam a 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 de sub-composiçã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>

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>

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 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 via CLI.
  3. Substitua no tempo de renderização com npx hyperframes render --variables '{...}' (nível superior) ou com data-variable-values='{...}' no elemento host (por instância para sub-comps).
<!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>
# A pré-visualização de desenvolvimento usa os padrões declarados
npx hyperframes preview

# Renderize 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 sub-composição: o mesmo getVariables() funciona dentro de sub-comps 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"
  data-variable-values='{"title":"Enterprise","price":"$99"}'
></div>

Temporização e Duração

Como a duração é calculada

  1. Se data-duration estiver definido → use esse valor exato. Fim.
  2. Se for um elemento <video> ou <audio> → duração da mídia (ou data-media-start até o final).
  3. Se for uma composição (data-composition-id) → duração mais longa da timeline GSAP, a menos que data-duration o substitua.
  4. Se for um <img> → obrigatório data-duration.

data-start Sintaxe

  • Segundos absolutos: data-start="2.5"
  • Referência de ID de clipe: data-start="el-1" (começa quando o clipe el-1 começa)
  • Referência de ID com deslocamento: data-start="el-1 + 0.5" (meio segundo depois que el-1 começa)

Temporização de Sobreposição

Sobreposições (imagens, texto decorativo, elementos de UI) podem existir no mesmo intervalo de tempo que outros clipes na mesma faixa, desde que sejam visualmente separados por z-index ou posicionamento. Use data-track-index para faixas separadas para reprodução paralela; use espaçamento manual de tempo na mesma faixa para sequencial.

Áudio e Legendas

Faixas de Áudio

Cada composição pode ter múltiplas faixas de áudio. A maneira mais simples:

<audio class="clip" data-start="0" data-duration="10" data-track-index="1" src="music.mp3"></audio>

Use data-volume="0.5" para mixagem. Clipes de áudio podem se sobrepor em faixas separadas para criar camadas sonoras.

Texto-para-Fala (TTS) e Legendas

Use o arquivo script.json de saída do comando tts do hyperframes-media para gerar legendas. Estrutura:

{
  "language": "pt-BR",
  "segments": [
    {
      "start": 0.0,
      "end": 2.5,
      "text": "Bem-vindo ao nosso produto"
    }
  ]
}

Renderize legendas sincronizadas:

<div class="caption-container">
  <span id="caption-line-1" class="clip caption" data-start="0" data-duration="2.5">
    Bem-vindo ao nosso produto
  </span>
  <span id="caption-line-2" class="clip caption" data-start="2.5" data-duration="3.0">
    Esta é uma demonstração
  </span>
</div>

Efeitos de Destaque de Texto Animados

Para criar destaques de texto animados (varreduras de marcador, círculos desenhados à mão, linhas de explosão, rabiscos, contorno esboçado), use o helper JavaScript window.__hyperframes.highlightText():

// Destaque de marcador (varredura amarela)
window.__hyperframes.highlightText("#text-element", {
  type: "marker",
  color: "rgba(255, 230, 0, 0.4)",
  duration: 0.8,
  start: 1.0
});

// Círculo desenhado à mão
window.__hyperframes.highlightText("#text-element", {
  type: "circle",
  color: "#ff6b6b",
  duration: 1.2,
  start: 2.0
});

Para visuais reativos a áudio (sincronia de batida, brilho, pulso impulsionados por música), use o helper window.__hyperframes.audioReactive():

const audioCtx = new (window.AudioContext || window.webkitAudioContext)();
const analyser = audioCtx.createAnalyser();
analyser.fftSize = 256;

// Conecte sua fonte de áudio ao analisador...

// Função de loop para atualizar animações com base na frequência
function animateBeat() {
  const dataArray = new Uint8Array(analyser.frequencyBinCount);
  analyser.getByteFrequencyData(dataArray);
  
  // Use dataArray para impulsionar animações GSAP
  const bass = dataArray[0] / 255; // Faixa de baixa frequência
  gsap.to(".beat-glow", { opacity: 0.5 + bass * 0.5, scale: 1 + bass * 0.2, duration: 0.1 });
  
  requestAnimationFrame(animateBeat);
}
animateBeat();

Dicas de Comportamento do Agente

Quando chamar skills auxiliares

  • Configuração do projeto: se o usuário disser "inicie um projeto" ou a pasta atual não tiver package.json, execute npx hyperframes init (do hyperframes-cli).
  • Pré-processamento de mídia: se o usuário disser "gere narração para isso", "transcreva este áudio" ou "remova o fundo deste vídeo", delegue à skill hyperframes-media.
  • Pré-visualização local: execute npx hyperframes preview (do hyperframes-cli).
  • Renderização final: execute npx hyperframes render (do hyperframes-cli).

Gerenciamento de Erros

  • Se a renderização falhar com um erro de sintaxe HTML, itere: corrija o problema citado e tente novamente.
  • Se as fontes especificadas em design.md não forem encontradas, avise o usuário e use uma alternativa embutida próxima.
  • Se um caminho de mídia estiver quebrado (404), verifique a ortografia do arquivo e sugira o caminho relativo correto.

Composições Autônomas vs. Sub-composições

  • Composições autônomas (o arquivo index.html principal) colocam sua div de composição diretamente em <body> e NÃO usam <template>.
  • Sub-composições (arquivos HTML externos carregados via data-composition-src) SEMPRE usam um wrapper <template>.
  • Salve sub-composições em um diretório compositions/.

Variáveis de Ambiente

VariávelPropósito
HYPERFRAMES_API_KEYChave de API para serviços HyperFrames (se necessário)
HYPERFRAMES_OUTPUT_DIRDiretório de saída padrão para arquivos renderizados (padrão: ./output)

Exemplo de Fluxo de Trabalho Completo

  1. Configuração: npx hyperframes init --template blank
  2. Crie ativos de áudio: npx hyperframes tts --text "Bem-vindo" --voice pt-BR-Wavenet-A (hyperframes-media)
  3. Escreva a composição: crie index.html com elementos clipe e animações GSAP
  4. Pré-visualize: npx hyperframes preview
  5. Itere: ajuste temporização, estilo e animações
  6. Renderize: npx hyperframes render --output final.mp4

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

delorenj/skills

Plan and generate terminal ASCII animations/screensaver-style output (FPS, refresh rules, loop policy, low-flicker guidance), with a static poster frame and an optional local demo script.

delorenj/skills

ASCII video: convert video/audio to colored ASCII MP4/GIF.

delorenj/skills

Plan, build and quality-check a premium short commercial for a real business (roofing, property, ecommerce, B2B software) using AI-generated footage, code-built motion (HTML/GSAP), selective Three.js and an independent-critic "Gauntlet" loop. Use when asked to make a launch-style / SaaS-style video, business ad, explainer, sample reel or pitch video, or to review and improve one. Encodes motion principles distilled from 28 professional launch films, a quality bar, audio rules and a business-offer playbook.

delorenj/skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

delorenj/skills

Generate professional voiceovers using ElevenLabs AI. Use when the user needs to create voiceovers for videos, audio narration, or text-to-speech content. Supports multiple voices with character presets (narrator, salesperson, expert) for natural delivery. Includes single scene regeneration for fine-tuning.

delorenj/skills

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

delorenj/skills

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

delorenj/skills

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

delorenj/skills

Manim CE animations: 3Blue1Brown math/algo videos.

delorenj/skills

Join a Google Meet or Zoom call as a video meeting agent via PikaStreaming. Trigger: user drops a Google Meet or Zoom link, or asks to join a meeting.

delorenj/skills

Translate an existing Remotion (React-based) video composition into a HyperFrames HTML composition. Use ONLY when the user explicitly asks to port, convert, migrate, translate, or rewrite a Remotion composition as HyperFrames (e.g. "port my Remotion project to HyperFrames"). Do NOT use when (a) authoring a NEW HyperFrames composition (even if A/B-testing a Remotion video); (b) Remotion is mentioned in passing; (c) Remotion code is shared as reference, not for translation; (d) the user wants "the same video as my Remotion one" without explicitly asking to migrate the source — treat as a fresh HyperFrames build. When in doubt, default to the `hyperframes` skill. Detects unsupported patterns (useState, useEffect side effects, async calculateMetadata, third-party React component libraries, `@remotion/lambda`) and recommends the runtime interop escape hatch instead of a lossy translation.

delorenj/skills

Generate speech using the self-hosted voxxy (vox) TTS service at https://vox.delo.sh. Use when the user asks to speak, say, narrate, synthesize speech, clone a voice, create a voice, add or register a voice, pipe TTS, or control voice qualities by description (e.g. "a young woman with a cheerful voice"). Handles HTTP API usage, voice profile management, description-based voice design, cloning, MCP registration, and integration patterns for new platforms.

delorenj/skills

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

delorenj/skills

YouTube transcripts to summaries, threads, blogs.

Habilidades Relacionadas