Communitygithub.com

LingoJack/jcli

Crie composições de vídeo, animações, cards de título, sobreposições, legendas, narrações, visuais reativos a áudio e transições de cena em HyperFrames HTML. Use quando solicitado a criar qualquer conteúdo de vídeo baseado em HTML, adicionar legendas sincronizadas com áudio, gerar narração de texto para fala, criar animação reativa a áudio (sincronização de batida, brilho, pulsação guiada por música), adicionar destaque de texto animado (varreduras de marcador, círculos desenhados à mão, linhas de explosão, rabiscos, esboços) ou adicionar transições entre cenas (crossfades, cortinas, revelações, transições de shader). Abrange criação de composição, temporização, mídia e o fluxo de trabalho completo de produção de vídeo. Para comandos CLI do loop de desenvolvimento (init, lint, inspect, preview, render), veja a skill hyperframes-cli; para comandos de pré-processamento de assets (tts, transcribe, remove-background), veja a skill hyperframes-media.

O que é jcli?

A skill **LingoJack/jcli** capacita agentes de IA (como Claude Code, Cursor ou Codex) a atuarem como ferramentas completas de produção de vídeo, usando HTML como fonte única da verdade. Ela permite criar composições de vídeo inteiramente em HTML, com temporização precisa (`data-start`, `data-duration`, `data-track-index`), animações GSAP e design responsivo baseado em CSS. A skill segue um fluxo de trabalho estruturado em três etapas: primeiro, estabelece um sistema de design (lendo `design.md` ou oferecendo a escolha de estilos visuais); segundo, expande o prompt do usuário para garantir alinhamento com a marca; terceiro, planeja e executa a composição, priorizando o layout final antes da animação para evitar sobreposições acidentais. Ela suporta composições aninhadas e parametrizadas via `data-composition-src` e variáveis, permitindo gerar múltiplas variações de um mesmo template sem editar o HTML fonte. Para trabalhos que exigem pré-processamento de mídia (TTS, transcrição, remoção de fundo) ou comandos CLI de build/renderização, ela depende de skills complementares, mas cobre completamente a criação de qualquer elemento visual narrativo: desde títulos e legendas até transições complexas e visuais reativos a áudio. Esta skill é ideal para desenvolvedores e criadores de conteúdo que desejam controlar cada frame de seus vídeos com código, mantendo um fluxo de trabalho eficiente e evitando edições manuais.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/LingoJack/jcli/tree/HEAD/.jcli/skills/hyperframes

Perguntar na sua IA favorita

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

Documentação

HyperFrames

HTML é a fonte 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 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") nas quais o usuário ainda não se comprometeu com uma direção, entenda a intenção antes de escolher as cores:

  • Público — quem assiste? Desenvolvedores? Executivos? Consumidores em geral?
  • Plataforma — onde será exibido? Redes sociais (15s), hero do site, 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 uma única melhor versão?

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

Para solicitações exploratórias, considere oferecer de 2 a 3 variações que diferem significativamente — não apenas trocas de cor, mas ritmo, 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 grafias — são arquivos diferentes no Linux). Ele é 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, não é uma fonte embutida), avise o usuário antes de escrever o HTML: "design.md especifica [nome da fonte] mas nenhum arquivo de fonte foi encontrado. Adicione arquivos .woff2 em fonts/ ou usarei a alternativa embutida mais próxima."

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

  1. O usuário mencionou um estilo ou clima? → Leia visual-styles.md para os 8 predefinições nomeadas. Escolha a que mais se aproxima.
  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 visual de seleção. 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, alguma cor/fonte da marca? Depois escolha uma paleta de 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 as cores da marca em escala apropriada para vídeo — não na opacidade de 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 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: Planejamento

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 sub-composições vs. inline, quais faixas carregam o quê (vídeo, áudio, sobreposições, legendas).
  3. Ritmo — declare o ritmo da cena antes de implementar. Quais cenas são impactos rápidos, quais são pausas, onde os shaders chegam, 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 acontecem, qual é o ritmo.
  5. Layout — construa o estado final primeiro. Veja "Layout Antes da Animação" abaixo.
  6. Animar — depois adicione movimento usando as regras abaixo.

Construa o que foi solicitado. Um pedido de "um card de título" não é um pedido de "um card 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 melhorarem 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 frame em que ele entrou completamente, está colocado corretamente 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 de animação (fora da tela, dimensionados para 0, opacidade 0) e aplicar tween para onde acha que eles devem chegar, você está adivinhando o layout final. Sobreposições ficam 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 frame 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 frame. 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 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 absoluta; o tween descreve a jornada para chegar lá. (Em sub-composições carregadas via data-composition-src, prefira gsap.fromTo() — veja regras GSAP críticas 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;
}
/* O contêiner preenche qualquer tamanho de cena (1920x1080, 1080x1920, etc).
   O padding posiciona o conteúdo. Flex + gap cuidam do 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 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 frames hero. 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 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 padrão é 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 CSS z-index.

Clipes de Composição

AtributoObrigatórioValores
data-composition-idSimID único da composição
data-startSimTempo inicial (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-composição

No elemento raiz <html>:

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

Estrutura da Composição

Sub-composiçõ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 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 fonte.

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 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 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>
# Preview 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 a partir de um arquivo JSON
npx hyperframes render --variables-file ./vars.json

Valores por instância de 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>

Animações GSAP

Use gsap.from() para entradas e gsap.to() para saídas. A timeline deve ser construída como paused: true e registrada em window.__timelines[compId].

Regras Gerais

  • CSS posiciona, GSAP anima. O estado final de cada elemento deve ser seu layout CSS estático.
  • Use gsap.from() para entradas — anime de um estado inicial (fora da tela, invisível) para a posição CSS.
  • Use gsap.to() para saídas — anime da posição CSS para um estado final (fora da tela, invisível).
  • Evite gsap.fromTo() a menos que seja necessário para sub-composições com estados iniciais e finais não determinados pelo CSS.
  • Use labels ou deslocamentos relativos para temporização (ex.: 0, 0.2, "+=0.2").
  • Prefira ease: "power3.out" para entradas e "power2.in" para saídas.
  • Anime propriedades de transformação (x, y, scale, rotation, opacity) — não left, top, width ou height.

Exemplo

const tl = gsap.timeline({ paused: true });

// Entradas (anime PARA a posição CSS)
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);

// Saídas (anime PARA FORA da posição CSS)
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);

window.__timelines["my-scene"] = tl;

Temas de Cor (Casa & Estilo)

Consulte house-style.md para paletas de cores predefinidas e regras de estilo. Use-as quando o usuário não tiver um design.md ou quando o projeto pedir consistência visual sem uma marca definida.

Regras de Temporização

  • data-start aceita segundos ("3.5") ou referências a IDs de clipes ("el-1", "intro + 2").
  • data-duration é obrigatório para clipes de imagem, div e composição. Para clipes de vídeo/áudio, o padrão é a duração da mídia.
  • Clipes na mesma data-track-index não podem se sobrepor. Use faixas diferentes para paralelismo (ex.: fundo e narração).
  • Transições são tratadas como clipes de composição com duração e efeito visual (crossfade, wipe, shader).

Mídia

  • Formatos suportados: MP4, WebM para vídeo; MP3, WAV, AAC para áudio; PNG, JPG, WebP para imagens.
  • Use data-media-start para cortar o início de um arquivo de mídia.
  • Use data-volume para controle de volume (0-1).
  • As dimensões da composição são fixas em data-width / data-height (ex.: 1920x1080 para paisagem, 1080x1920 para retrato).

Scripts e Comportamento Personalizado

Adicione <script> dentro da composição para lógica personalizada (carregar dados, manipular DOM, interagir com a timeline). A timeline deve ser registrada em window.__timelines para que o framework a consuma.

<script>
  // Aguarde o DOM carregar
  document.addEventListener("DOMContentLoaded", () => {
    const tl = gsap.timeline({ paused: true });
    // configure a timeline aqui
    window.__timelines["my-comp"] = tl;
  });
</script>

Composições Inline vs. Externas

  • Inline: a composição está no mesmo arquivo HTML que a timeline principal. Use data-composition-id diretamente em <body>.
  • Externa: carregue um arquivo HTML separado com data-composition-src. Use um <template> wrapper para manter o escopo.

Ambos os casos exigem que a timeline seja registrada em window.__timelines[compId].

Transições

Transições entre cenas podem ser:

  • Crossfade: sobreposição de saída e entrada com opacidade.
  • Wipe: um clipe de composição que mascara a transição (ex.: um gradiente se movendo).
  • Shader: use um efeito baseado em WebGL (via biblioteca externa se necessário).
  • Revelação: um elemento (como um círculo que se expande) revela a próxima cena.

Implemente transições como composições separadas com data-start e data-duration específicos.

Carregamento de Dados

Composições podem carregar dados de arquivos JSON via fetch() ou referências a APIs. Use getVariables() para injetar dados parametrizados.

<script>
  fetch("data.json")
    .then((res) => res.json())
    .then((data) => {
      document.querySelector(".title").textContent = data.title;
    });
</script>

Boas Práticas

  • Sempre leia design.md primeiro se existir.
  • Ofereça variações apenas quando apropriado e solicitado de forma exploratória.
  • Construa o layout final primeiro (CSS) antes de animar (GSAP).
  • Use nomes de classes CSS descritivos e evite IDs genéricos.
  • Mantenha a timeline enxuta — anime apenas elementos que mudam visivelmente.
  • Teste o preview com npx hyperframes preview antes de renderizar.
  • Para sub-composições parametrizadas, declare variáveis com data-composition-variables e leia com getVariables().

Resolução de Problemas

  • A composição fica em branco: verifique se o <template> não está sendo usado em uma composição independente.
  • Sobreposições: certifique-se de que o layout final (CSS) foi construído primeiro e que a animação (GSAP) não está causando sobreposições não intencionais.
  • Timeline não encontrada: verifique se window.__timelines[compId] está definido com paused: true.
  • Variáveis não resolvidas: verifique se o JSON em data-composition-variables é válido e se getVariables() é chamado após o carregamento.

Referências


Esta skill cobre a criação e manipulação de composições de vídeo em HyperFrames HTML. Para pré-processamento de assets (TTS, transcrição, remoção de fundo) e comandos CLI de build, veja as skills complementares hyperframes-media e hyperframes-cli.

Habilidades Relacionadas