Communitygithub.com

remotion-topic-explainer

Mostra como planejar, construir ou editar um "remotion topic explainer" para que o resultado concreto seja um vídeo finalizado. O procedimento percorre a Habilidade de Vídeo Explicativo Remotion (60-90s), 1. Estrutura e Temporização do Vídeo (60-90s / 1800-2700 quadros @ 30fps), 2. Geração de Narração TTS (`edge` | `cit`). Use quando uma nova tarefa exigir essa técnica.

O que é remotion-topic-explainer?

Esta habilidade orienta o agente (como Claude Code, Cursor ou Codex) na criação de vídeos explicativos curtos de 60 a 90 segundos no formato vertical (1080x1920 @ 30fps), adequados para TikTok, YouTube Shorts ou Reels. Ela combina animações precisas em Spring do ecossistema `remotion-dev/skills` (com interpolações fixas, sequências e hierarquia tipográfica) com síntese de voz via TTS usando os provedores `edge` (online, gratuito) ou `cit` (estúdio de voz vietnamita offline). A sincronização exata é obtida mapeando a duração do áudio diretamente nos quadros do Remotion. O fluxo segue a estrutura gancho-problema-solução-valor-encerramento com 6 cenas, cronometradas entre 1800 e 2700 quadros. Também inclui regras detalhadas de codificação Remotion, geração de scripts TTS e efeitos sonoros (SFX). É útil sempre que um agente precisar produzir um vídeo explicativo curto e polido, garantindo que o resultado final seja entregue como um arquivo de vídeo renderizado.

Funciona com✓Claude Code✓Codex CLI~Cursor✓Antigravity
npx skills add https://github.com/hoangtuanqn/remotion-template/tree/HEAD/.agents/skills/remotion-topic-explainer

Perguntar na sua IA favorita

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

Documentação

Habilidade de Vídeo Explicativo Remotion (60-90s)

Esta habilidade orienta você a criar vídeos explicativos curtos de alta qualidade, com 60–90 segundos (formato TikTok / YouTube Shorts / Reels: 1080x1920 @ 30fps) a partir de qualquer tópico.

Ela combina:

  1. Melhores Práticas Visuais de remotion-dev/skills (springs precisas ao quadro, interpolações fixas, composição de sequências, hierarquia tipográfica).
  2. Síntese de Voz (TTS) via TTS_PROVIDER no .env: edge (edge-tts-universal, online, gratuito) ou cit (CIT Voice Studio, estúdio de voz vietnamita offline – baixe em github.com/Cuongyd196/cit-voice-studio, docs da API: docs/cit-voice-studio.md).
  3. Sincronização Exata de Temporização mapeando a duração da narração diretamente nas sequências de quadros do Remotion.

1. Estrutura e Temporização do Vídeo (60-90s / 1800-2700 quadros @ 30fps)

Um vídeo curto cativante segue o framework Gancho-Problema-Solução-Valor-Encerramento:

CenaNomeDuraçãoFaixa de Quadros (@ 30fps)Propósito e Elementos Visuais
1Gancho0s – 6s~180 quadrosUma promessa ou pergunta curiosa com números, falada nos primeiros 2 segundos. Título grande, efeito de gancho do video-style.
2Contexto / Ponto de Dor6s – 17s~330 quadrosApresenta o problema ou contexto de por que o tópico é importante. Dois cartões opostos deslizam de lados opostos.
3Conceito Central Parte 117s – 32s~450 quadrosPrimeiro princípio central: cartão fosco, palavras-chave em destaque.
4Conceito Central Parte 232s – 48s~480 quadrosMecanismo de funcionamento: processo de 3 etapas, linhas de conexão animadas.
5Impacto no Mundo Real48s – 64s~480 quadrosAplicação prática, conselho ou contagem de números.
6Encerramento e CTA64s – 75s~330 quadrosConclusão com uma frase impactante, botão de seguir o canal.

Se precisar de até 90s, adicione 1-2 cenas extras (exemplos concretos, observações) antes do Encerramento. Cenas com mais de 13s devem ser divididas em duas.

Duração total: 1800 – 2700 quadros (aproximadamente 60 – 90 segundos).


2. Geração de Narração TTS (edge | cit)

2.1 Configuração de Voz via .env

Garanta que o arquivo .env esteja configurado (veja .env.example para detalhes):

TTS_PROVIDER=edge                    # edge | cit
TTS_OUTPUT_DIR=public/audio

# Edge TTS (TTS_PROVIDER=edge)
EDGE_TTS_VOICE=vi-VN-HoaiMyNeural    # ou vi-VN-NamMinhNeural, en-US-ChristopherNeural
EDGE_TTS_RATE=+10%                   # +10% a +15% ajuda vídeos curtos a terem um ritmo rápido e envolvente

# CIT Voice Studio (TTS_PROVIDER=cit)
CIT_TTS_BASE_URL=http://127.0.0.1:8001
CIT_TTS_VOICE=Hải Đăng               # lista de vozes: docs/cit-voice-studio.md ou GET /voices
CIT_TTS_SPEED=1.1                    # 0.5 - 2.0

Quando TTS_PROVIDER=cit:

  • O aplicativo CIT Voice Studio deve estar aberto. O script chama GET /health automaticamente antes de gerar áudio; se relatar falha de conexão, peça ao usuário para abrir o aplicativo (ou baixe em github.com/Cuongyd196/cit-voice-studio).
  • O texto pode incluir tags de emoção [cair], [suspirar], [pigarrear] e tags de pausa [pausa 0.5s] (que não são faladas). Não abuse: máximo de 1 tag/cena.
  • Erro 400 Voice not found = nome de voz incorreto (diferencia acentos). Verifique CIT_TTS_VOICE.

2.2 Processo de Geração de Arquivo de Áudio

Ao receber um tópico, crie o diretório src/<NomeDoTopico>/ primeiro, pois src/<NomeDoTopico>/audioData.ts só é gerado quando este diretório já existe. Em seguida, crie scripts/generate-<topic>-audio.ts e execute para gerar o áudio:

import { generateTopicVoices } from "./generate-tts";

const scenes = [
  {
    id: "scene1_hook",
    text: "Você sabia o que Docker realmente é e por que todo programador precisa dele?",
  },
  {
    id: "scene2_problem",
    text: "Antigamente, a frase 'funciona na minha máquina' era um pesadelo na entrega de produtos.",
  },
  {
    id: "scene3_concept1",
    text: "Docker resolve isso com Contêineres - empacotando todo o código e ambiente em um único bloco.",
  },
  {
    id: "scene4_concept2",
    text: "Ao contrário de máquinas virtuais pesadas, o Docker compartilha o kernel do sistema operacional, iniciando em um piscar de olhos.",
  },
  {
    id: "scene5_impact",
    text: "Com isso, você faz deploy de aplicativos sem problemas em qualquer servidor, da AWS, GCP até VPS baratos.",
  },
  {
    id: "scene6_outro",
    text: "Siga o canal para dominar conhecimentos de tecnologia de forma concisa todos os dias!",
  },
];

generateTopicVoices("DockerShort", scenes).catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

O arquivo de áudio será salvo automaticamente em public/audio/<NomeDoTopico>/<sceneId>.<ext> (.mp3 com edge, .wav com cit) junto com um arquivo manifest.json registrando o número exato de quadros (durationInFrames) e o audioPath para cada cena.

  • Opcional por cena: voice (voz do provedor selecionado), rate/pitch/volume (apenas edge), speed 0.5-2.0 (apenas cit).
  • Arquivos já existentes são reutilizados (cache). Para regerar após alterar o texto ou mudar de voz, exclua o arquivo de áudio correspondente antes.

3. Regras de Codificação Remotion (de remotion-dev/skills)

Ao escrever código-fonte Remotion, é OBRIGATÓRIO seguir estas regras:

3.1 Uso de Animações Spring

Não use keyframes/transitions CSS ou easing linear sem vida. Use spring():

import { spring, useCurrentFrame, useVideoConfig } from "remotion";

const frame = useCurrentFrame();
const { fps } = useVideoConfig();

// Spring suave para Card/Icon
const scale = spring({
  frame,
  fps,
  config: {
    damping: 12,    // Abaixo de 15 cria um反弹自然
    stiffness: 100,  // Tensão
    mass: 0.8,
  },
});

const entrance = spring({
  frame: frame - 10, // Atraso de 10 quadros
  fps,
  from: 50,
  to: 0,
});

3.2 Interpolação Segura (Sempre Fixar)

Sempre forneça extrapolateLeft: "clamp" e extrapolateRight: "clamp" para evitar valores fora do intervalo quando a linha do tempo ultrapassar os limites:

import { interpolate } from "remotion";

const opacity = interpolate(frame, [0, 15], [0, 1], {
  extrapolateLeft: "clamp",
  extrapolateRight: "clamp",
});

3.3 Incorporação de Áudio e Sincronização de Sequência

Cada cena na Composição use <Sequence> ou <Series> para gerenciar o tempo com precisão:

import { Audio, staticFile, Sequence } from "remotion";

// No componente da cena - pegue o caminho do manifest, NÃO hardcode a extensão .mp3 (provedor cit gera .wav):
<Sequence from={0} durationInFrames={sceneDuration}>
  <Audio src={staticFile(audioManifest.scenes[0].audioPath)} />
  <SceneContent />
</Sequence>
  1. Buffer de Transição Enxuto (Snappy Transition Buffer):
    • O intervalo entre cenas deve ser de apenas +3 a +4 quadros (aproximadamente 0,1s) após o término da fala.
    • Evite buffers muito longos (+15 a +20 quadros) que criam silêncios/mortes de ritmo entre as cenas. A próxima cena deve aparecer assim que a frase anterior terminar para manter um ritmo intenso e envolvente para vídeos curtos.
// Exemplo de cálculo de duração das cenas no Series
// O valor no manifest já inclui 10 quadros de buffer, então subtraia antes de adicionar o buffer.
const d1 = audioManifest.scenes[0].durationInFrames - 10 + 3;
const d2 = audioManifest.scenes[1].durationInFrames - 10 + 3;
// ...

3.4 Padrões de Design Visual (Vertical 1080x1920)

Todo o estilo (fundo, cartões foscos, marca, tamanhos de fonte, layout, legendas, movimento, gancho) segue a habilidade video-style. Copie theme.ts e components/ de src/ClaudeBugHunterRepo/. Não use emoji ou ícones decorativos no texto.


4. Processo Passo a Passo de Criação de Vídeo para Antigravity / Codex

Ao receber a solicitação: "Criar vídeo explicativo sobre [Tópico X]":

Passo 1: Roteirização (Scripting)

  1. Defina as 6 cenas (Gancho, Problema, Conceito 1, Conceito 2, Impacto, Encerramento).
  2. Escreva o texto em vietnamita natural, conciso, com frases curtas (total 260-330 palavras, 35-50 palavras por cena). A cena 1 deve abrir com uma promessa ou resultado concreto; veja a seção Gancho e Texto de video-style.

Passo 2: Geração de Voz (TTS Generation)

  1. Leia TTS_PROVIDER no .env para saber se está usando edge ou cit.
  2. Crie o diretório src/<NomeDoTopico>/, depois crie o script scripts/generate-<topic>-audio.ts chamando generateTopicVoices, execute npx tsx scripts/generate-<topic>-audio.ts.
  3. Obtenha a lista de durações reais de quadros do manifest.json / src/<NomeDoTopico>/audioData.ts.

Passo 3: Criação do Diretório de Código src/<NomeDoTopico>/

Estrutura de diretório padrão:

src/<NomeDoTopico>/
├── <NomeDoTopico>.tsx          # Composição principal que reúne as Series.Sequence
├── types.ts                    # Schema e Props
├── audioData.ts                # Metadados de duração do áudio
└── scenes/
    ├── Scene1Gancho.tsx
    ├── Scene2Problema.tsx
    ├── Scene3Conceito1.tsx
    ├── Scene4Conceito2.tsx
    ├── Scene5Impacto.tsx
    └── Scene6Encerramento.tsx

Efeitos sonoros: use <SfxTrack cues={...} /> de src/sfx/SfxTrack.tsx, colocado no componente principal. Arquivos de som em public/sfx/, regerados com npx tsx scripts/generate-sfx.ts.

QuandoSom
No início de cada cena, 3 quadros antes para cair no silêncio antes da nova frase (cena 1 no quadro 0)mallet
Cartão ou item aparecepop ou tick
Destaque, conclusãoding
Chamada para seguirchime
  • O frame de cada cue é o número do quadro a partir do início do vídeo, coincidindo com o momento em que o componente aparece.
  • Não é necessário evitar sobreposição manualmente: SfxTrack automaticamente descarta cues a menos de 0,4s da anterior e reduz o volume quando um som se repete logo após ele mesmo.
  • Não baixe sons de myinstants ou sites de licença duvidosa. Se precisar de um novo som, adicione-o em scripts/generate-sfx.ts.

Passo 4: Registrar a Composição em src/Root.tsx

Adicione uma nova Composição em src/Root.tsx:

<Composition
  id="<NomeDoTopico>"
  component={<NomeDoTopico>}
  durationInFrames={totalFrames}
  fps={30}
  width={1080}
  height={1920}
  defaultProps={{}}
/>

Passo 5: Verificação e Relatório

  1. Execute npm run lint para verificar erros de TypeScript/ESLint.
  2. Relate ao usuário o link para abrir a Composição no Remotion Studio (http://localhost:3000) ou o comando para renderizar MP4:
    npx remotion render <NomeDoTopico> out/<NomeDoTopico>.mp4
    

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas