marwanhattar94/remotion-motion-graphics

Remotion Motion Graphics

Remotion renderiza componentes React quadro a quadro em vídeo. A qualidade do código não é o gargalo — o ofício do motion design é. A geração não treinada produz easing linear, fades apenas com opacidade, entradas simultâneas, cores planas e sem textura. Esse é o visual de "vídeo IA genérico". Esta habilidade existe para evitá-lo.

Regras inegociáveis (aplicam-se a TODA composição)

1. NUNCA use interpolação linear. Cada interpolate() recebe uma curva de easing; cada entrada prefere spring(). Sempre extrapolateLeft/Right: "clamp".
2. Entradas animam 2–3 propriedades juntas (opacidade + translateY + escala). Um fade solitário é proibido.
3. Escalone tudo. Listas, palavras, raios, cartões: deslocamentos de 3–6 quadros. Nada entra simultaneamente.
4. Saídas existem e são mais rápidas que as entradas (~10 quadros vs ~20).
5. Pilha de cinco camadas em cada cena, de baixo para cima: malha de fundo → assets → gráficos/tipo → grade de cor → granulado + vinheta. Nunca um fundo sólido plano.
6. Toda imagem estática recebe Ken Burns (escala lenta 1→1,08 + panorâmica). Todo asset de vídeo usa <OffthreadVideo>, nunca <Video>.
7. Elementos ociosos respiram: qualquer coisa na tela por mais de 2s recebe micro-movimento em onda senoidal.
8. Todo tempo deriva de fps via useVideoConfig(). Sem números mágicos de quadro.
9. Um objeto de tema no topo do projeto (cores, easings, presets de spring, fontes). Nunca coloque inline um hex de cor ou easing em um componente.
10. Renderize, extraia quadros, OLHE para eles, corrija, re-renderize. Nunca entregue uma renderização não verificada. Este loop é obrigatório — veja Verificação abaixo.

Fluxo de trabalho

Passo 1 — Escopo

Determine: duração, fps (30 padrão; 60 apenas para movimento rápido intenso), dimensões (1080×1920 Reels/Shorts, 1920×1080 paisagem), quais assets existem (imagens, filmagens, áudio, logos), e se isso é uma nova composição ou uma edição de um projeto existente. Se editando um projeto existente: leia src/ completamente primeiro, encontre o tema (ou crie um), e refatore violações das regras acima antes de adicionar funcionalidades.

Passo 2 — Configuração

Novo projeto:

npm install remotion @remotion/cli react react-dom
# opcional: @remotion/transitions @remotion/motion-blur @remotion/google-fonts

Copie assets/theme.ts desta habilidade para src/theme.ts e ajuste a paleta para a marca do usuário. Estrutura: src/index.ts (registerRoot) → src/Root.tsx (Composition, duração/fps/tamanho) → src/scenes/*.tsx → src/components/*.tsx. Ativos do usuário vão em public/, carregados via staticFile().

Passo 3 — Construção

Leia references/motion-patterns.md para as implementações de componentes reutilizáveis (BgMesh, Grade, Grain, Vignette, KenBurns, WordReveal, Stagger, Counter, Spark, transições, paralaxe). Componha cenas a partir desses padrões. Para ritmo, pacing, tipografia, paletas de cores e regras de design de som, leia references/design-rules.md.

Ritmo de cena: HIT → pausa (15–20 quadros parados) → construção → HIT. Algo deve se mover nos primeiros 15 quadros. Nunca mais de 90 quadros sem um novo elemento visual.

Passo 4 — Renderização

npx remotion render src/index.ts <CompId> out/video.mp4 --codec h264 --crf 17

Remotion precisa de um binário Chromium. Se o download automático falhar (sandboxes, CI offline), encontre um e passe-o explicitamente:

which chromium chromium-browser google-chrome 2>/dev/null
ls /opt/pw-browsers 2>/dev/null   # As instalações do Playwright ficam aqui
npx remotion render ... --browser-executable=<caminho>

Se o Chrome completo gerar erro "Old Headless mode has been removed", use um binário headless_shell (Playwright envia um como chromium_headless_shell-*/chrome-linux/headless_shell).

Passo 5 — VERIFICAÇÃO (obrigatório, nunca pule)

Extraia quadros em momentos-chave e inspecione visualmente cada um. O método portátil — funciona em máquinas sem ffmpeg no sistema, renderiza o quadro exato:

for f in 15 45 90 150; do
  npx remotion still src/index.ts <CompId> out/check_$f.png --frame $f --overwrite
done

Se o ffmpeg do sistema estiver DISPONÍVEL, extrair do mp4 final também verifica a própria codificação (-ss seeking é mais portátil que filtros select=, cujas aspas quebram em alguns shells e no ffmpeg embutido do Remotion):

ffmpeg -v error -ss 1.5 -i out/video.mp4 -frames:v 1 check_1.png

Procure e corrija, em ordem de frequência:

• Bugs de espaçamento: gap/margin em em resolve contra o tamanho da fonte do PAI (geralmente 16px), não o tamanho do texto — use valores em px em contêineres flex ao redor de texto grande.
• Texto transbordando ou tocando as bordas do quadro (mantenha conteúdo crítico nos 75% centrais verticalmente para 9:16 — a UI da plataforma cobre topo/base).
• Elementos visíveis antes de sua entrada ou após sua saída (clamp ausente).
• Falhas de cor/contraste: cor herói em mais de 1 elemento por quadro, texto escuro ilegível sobre a grade.
• Erros de ordem de camada (granulado/vinheta devem estar no topo, grade acima do conteúdo). Corrija → re-renderize → re-extraia → re-inspecione. Só entregue após uma passagem limpa. Em seguida, execute a lista de verificação final no final de references/design-rules.md.

Editando a filmagem existente do usuário

Para melhorar um mp4 existente (legendas, grade, intro/outro) em vez de construir do zero: coloque o arquivo em public/, renderize-o como a camada de asset com <OffthreadVideo src={staticFile("clip.mp4")} />, defina a duração da composição a partir do comprimento do clipe, e empilhe gráficos/grade/granulado acima. Obtenha a duração e o fps do clipe com ffprobe antes de configurar a composição. Para legendas sincronizadas com palavras sobre fala, veja a seção de legendas em references/motion-patterns.md.

Arquivos de referência

• references/motion-patterns.md — biblioteca de componentes copiáveis: fundos, grade/granulado/vinheta, Ken Burns, revelações de texto, contadores, transições, paralaxe, sincronia de áudio, legendas. Leia antes de escrever componentes.
• references/design-rules.md — paletas, regras de tipografia, arquitetura de cena, design de som, lista de verificação pré-entrega. Leia antes de projetar cenas e antes da entrega final.
• assets/theme.ts — o modelo de tema para copiar em todo projeto.

Modos de falha comuns a evitar ativamente

• Emoji como ícones. Emoji renderizam como glifos de plataforma em cores (✳️ verde, 🌐 azul) que ignoram sua paleta e quebram silenciosamente a regra de uma cor herói, e ficam em qualquer fundo que você der (mascote laranja em bloco laranja = invisível). Desenhe glifos com CSS/SVG nas cores do tema, ou verifique cada emoji contra os quadros extraídos.
• Nenhum asset de SFX não é motivo para entregar silencioso. Sintetize um kit mínimo como WAVs de 16 bits a partir de um script Node (whoosh de explosão de ruído, pop de queda de tom, batida grave de seno, pad de seno desafinado) em public/sfx/ — veja examples/scripts/ no repositório. Zero downloads, totalmente determinístico.
• Gerar um componente gigante em vez de peças temáticas reutilizáveis.
• Incompatibilidade de durationInFrames entre Composition e conteúdo da cena (ar morto).
• Esquecer --overwrite em re-renderizações, e depois inspecionar o arquivo desatualizado.
• Fontes: nunca confie em padrões do sistema para texto heroico; carregue uma fonte de exibição via @remotion/google-fonts ou @font-face + staticFile.
• Tentar "descrever" o resultado para o usuário em vez de renderizar e verificar.