quyen2867/remotion-video-template

Skill de Vídeo Explicativo Remotion (50-60s)

Esta skill orienta você na criação de vídeos explicativos curtos e de alta qualidade, com 50–60 segundos, no formato vertical (TikTok / YouTube Shorts / Reels: 1080x1920 @ 30fps) a partir de qualquer tópico.

Ela combina:

1. Boas Práticas Visuais do remotion-dev/skills (springs com frame exato, interpolações com clamp, composição de sequências, hierarquia tipográfica).
2. Síntese de Voz por IA via TTS_PROVIDER no .env: edge (edge-tts-universal, online, gratuito) ou cit (CIT Voice Studio, vozes offline em vietnamita - baixe em github.com/quyen2867/cit-voice-studio, documentação da API: docs/cit-voice-studio.md).
3. Sincronização Exata de Temporização mapeando a duração do áudio diretamente nas sequências de quadros do Remotion.

---

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

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

Cena	Nome	Tempo	Faixa de Quadros (@ 30fps)	Propósito e Visuais
1	Gancho	0s – 5s	~150 quadros	Chamar atenção imediata: Título grande, pergunta que instiga curiosidade, badge flutuante.
2	Contexto / Ponto de Dor	5s – 15s	~300 quadros	Apresentar o problema ou contexto: por que este tópico é importante. Ícone de alerta/comparação.
3	Conceito Central Parte 1	15s – 28s	~390 quadros	Explicar o princípio central nº1: Card vítreo, ícone ilustrativo, palavras-chave em destaque.
4	Conceito Central Parte 2	28s – 42s	~420 quadros	Expandir detalhes ou mecanismo de funcionamento: Processo de 3 etapas, diagrama de fluxo suave.
5	Impacto no Mundo Real	42s – 52s	~300 quadros	Aplicação prática, conselho prático ou números impressionantes.
6	Encerramento e CTA	52s – 60s	~240 quadros	Resumo em uma frase marcante, chamada para Like/Share/Follow e marca pessoal.

Duração total: 1500 – 1800 quadros (aproximadamente 50 – 60 segundos).

---

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

2.1 Configuração de Voz via .env

Certifique-se de que o arquivo .env está 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 ritmo acelerado 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 automaticamente GET /health antes de gerar áudio; se não conseguir conectar, solicita que o usuário abra o app (ou baixe em github.com/quyen2867/cit-voice-studio).
• O texto pode incluir tags de emoção [rir], [suspirar], [pigarrear] e tags de pausa [pausa 0.5s] (que não são lidas em voz alta). Não abuse: no máximo 1 tag por cena.
• Erro 400 Voice not found = nome de voz incorreto (diferença de acentos). Verifique CIT_TTS_VOICE.

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

Ao receber um tópico, crie o arquivo de roteiro do voiceover e execute o script scripts/generate-tts.ts para gerar o áudio:

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

const scenes = [
  {
    id: "scene1_hook",
    text: "Você sabe o que é Docker e por que todo programador precisa dele?",
  },
  {
    id: "scene2_problem",
    text: "Antigamente, a frase 'na minha máquina funciona' era sempre um pesadelo na entrega de produtos.",
  },
  {
    id: "scene3_concept1",
    text: "O Docker resolve isso com Containers - empacotando todo o código e ambiente em um único bloco.",
  },
  {
    id: "scene4_concept2",
    text: "Diferente 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 aplicações de forma suave em qualquer servidor, da AWS, GCP até VPS baratos.",
  },
  {
    id: "scene6_outro",
    text: "Siga o canal para pegar todos os conhecimentos de tecnologia de forma resumida todo dia!",
  },
];

await generateTopicVoices("DockerShort", scenes);

Os arquivos de áudio serão salvos automaticamente em public/audio/<TopicName>/<sceneId>.<ext> (.mp3 com edge, .wav com cit) junto com um arquivo manifest.json que registra o número exato de quadros (durationInFrames) e 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 existentes são reutilizados (cache). Para regenerar após alterar o roteiro ou mudar de voz, exclua o arquivo de áudio correspondente primeiro.

---

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

Ao escrever código-fonte Remotion, é OBRIGATÓRIO seguir os seguintes princípios:

3.1 Usar Animações Spring

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

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

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

// Spring suave para Card/Ícone
const scale = spring({
  frame,
  fps,
  config: {
    damping: 12,    // Abaixo de 15 cria um bounce elástico natural
    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 Clamp)

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 Incorporar Áudio e Sincronizar Sequência

Cada cena na Composition usa <Sequence> ou <Series> para gerenciar a temporização com precisão:

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

// No componente da cena - obtenha 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>

4. Buffer de Transição Enxuto (Snappy Transition Buffer):
   • O buffer entre cenas deve ser de apenas +3 a +4 quadros (cerca de 0.1s) após o término da narração.
   • Evite buffers muito longos (+15 a +20 quadros) que causam silêncios/mortes de ritmo entre as cenas. A próxima cena deve aparecer assim que a frase anterior terminar para manter o ritmo intenso e envolvente dos vídeos curtos.

// Exemplo de cálculo de duração das cenas em Series
const d1 = audioManifest.scenes[0].durationInFrames + 3;
const d2 = audioManifest.scenes[1].durationInFrames + 3;
// ...

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

1. Fundo: Dark Mode sofisticado (bg-slate-950 ou gradiente from-slate-950 via-zinc-900 to-black) combinado com efeito de radial glow/grid suave.
2. Cards Glassmorphism:
   • backdrop-blur-xl bg-white/10 border border-white/20 rounded-3xl p-8 shadow-2xl
3. Marca do Canal no Topo (Brand Header):
   • Sempre exibir o componente de marca ⚡ [NOME_DO_CANAL] no topo centralizado (top: 150px, left: 50% translate-x) lido da variável de ambiente CHANNEL_NAME (padrão: "mquyen") para evitar que seja ocultado pela barra de busca e pelas abas Seguindo / Para você das plataformas (TikTok, Shorts, Reels).
4. Tipografia Otimizada para Mobile (1080x1920):
   • Título principal: 72px - 96px, negrito font-black, gradiente nítido.
   • Conteúdo do card / citação: 40px - 50px font-extrabold.
   • Texto secundário / explicação: 28px - 36px font-semibold.
   • Badge de categoria: 28px - 32px font-black uppercase.
5. Layout Centralizado e Legenda de Uma Linha (Single-Line Chunked Caption):
   • Layout principal: Todo o bloco de conteúdo importante DEVE estar no centro vertical da tela (justify-center).
   • Posição da Legenda: Abaixo do bloco central com espaçamento generoso (mt-64), sem ser coberta pela barra de ferramentas inferior do TikTok/Reels.
   • Formato de uma linha: A legenda aparece em apenas uma linha (cerca de 5-7 palavras), com fonte grande text-4xl font-black, cortada automaticamente por grupos de palavras e transicionando suavemente conforme o progresso da narração (durationInFrames). Use pill card rounded-full bg-slate-950/95 border-2 border-sky-400/50 px-10 py-5 com destaque de palavras-chave.

---

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. Identifique as 6 cenas (Gancho, Problema, Conceito 1, Conceito 2, Impacto, Encerramento).
2. Escreva o roteiro em vietnamita (ou português, conforme o caso), natural, conciso, com frases curtas (cada cena 15-30 palavras).

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 script scripts/generate-<topic>-audio.ts chamando generateTopicVoices, execute npx tsx scripts/generate-<topic>-audio.ts.
3. Obtenha a lista de durações reais em quadros de manifest.json / src/<TopicName>/audioData.ts.

Passo 3: Criar Pasta de Código src/<TopicName>/

Estrutura de pastas padrão:

src/<TopicName>/
├── <TopicName>.tsx          # Composição principal que reúne as Series.Sequence
├── types.ts                 # Schema & Props
├── audioData.ts             # Metadados de duração do áudio
└── scenes/
    ├── Scene1Hook.tsx
    ├── Scene2Problem.tsx
    ├── Scene3Concept1.tsx
    ├── Scene4Concept2.tsx
    ├── Scene5Impact.tsx
    └── Scene6Outro.tsx

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

Adicione a nova Composition em src/Root.tsx:

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

Passo 5: Verificar e Relatar

1. Execute npm run lint para verificar erros de TypeScript/ESLint.
2. Relate ao usuário o link para abrir a Composition no Remotion Studio (http://localhost:3000) ou o comando para renderizar MP4:

   npx remotion render <TopicName> out/<TopicName>.mp4