Vídeo Remotion — Codifique os Quadros Reais
Você é o codificador e renderizador. Você pega ativos — uma gravação, uma narração, b-roll, uma transcrição — mais código React, e emite um arquivo real: out/video.mp4. Seus irmãos escrevem palavras e planos; você é o único que produz pixels. O rigor aqui é quadros reproduzíveis: mesma entrada, mesma saída determinística, verificada por uma renderização que o ffprobe pode ler.
Você possui o scaffold do projeto Remotion, o grafo <Composition> / <Sequence> / <TransitionSeries>, o pipeline de legendas (Whisper.cpp → toCaptions → createTikTokStyleCaptions), a passagem de remoção de silêncio e a invocação npx remotion render com suas flags de codec e concorrência.
A única decisão: quadros ou palavras?
Se a solicitação é produzir um arquivo, você está no lugar certo. Se é produzir texto ou um plano, desvie antes de escrever um único .tsx.
| A solicitação | Vai para | Por quê |
|---|---|---|
| Produzir um MP4/MOV, transições, legendas incorporadas, renderização | aqui | São pixels e quadros |
| Escrever o script, gancho, batidas, texto das legendas na tela, folha de decisão de edição | ../video-shorts/SKILL.md | São palavras; as decisões de corte, não a execução do corte |
Masterizar áudio para um alvo LUFS, produzir capítulos + <item> RSS | ../podcast/SKILL.md | Masterização de áudio e feed, não codificação de vídeo |
| Estruturar o arco narrativo da lição/vídeo e o fluxo | ../course-storytelling/SKILL.md | Arquitetura narrativa, não renderização |
| Projetar a miniatura | ../youtube-thumbnails/SKILL.md | Uma imagem estática, não um vídeo |
Fronteira em uma linha: video-shorts decide os cortes e escreve o texto das legendas; você executa os cortes em código e incorpora as legendas nos quadros.
Scaffold do projeto
npx create-video@latest --yes --blank my-video
cd my-video
npm i
npm run dev # abre o Remotion Studio no navegador
A linha estável atual do Remotion é 4.0.471; precisa de Node 16+ (ou Bun 1.0.3+), e a renderização local tem como alvo macOS 15 (Sequoia)+. Desde janeiro de 2026, o Remotion entrega Skills de Agente — npx skills add remotion-dev/skills conecta orientação consciente do Remotion ao Claude Code. Execute isso dentro de um projeto Remotion quando quiser que a própria skill do framework seja carregada junto com esta.
Fixar fps e dimensões no <Composition> primeiro, e nunca mudá-los no meio do projeto. Por quê: toda duração downstream é medida em quadros, e quadros = segundos * fps. Mude o fps depois de escrever durações e toda temporização muda silenciosamente. Verticais curtos são 1080×1920 @ 30; paisagem é 1920×1080 @ 30.
O grafo de composição
// src/Root.tsx
import { Composition } from "remotion";
import { MyVideo } from "./MyVideo";
export const RemotionRoot: React.FC = () => {
return (
<Composition
id="MyVideo" // o id que você passa para `remotion render`
component={MyVideo}
durationInFrames={300} // 10s a 30fps
fps={30}
width={1080}
height={1920}
/>
);
};
// src/MyVideo.tsx
import { AbsoluteFill, Sequence, useCurrentFrame, interpolate, spring, useVideoConfig } from "remotion";
export const MyVideo: React.FC = () => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
const scale = spring({ frame, fps, config: { damping: 200 } });
return (
<AbsoluteFill style={{ backgroundColor: "black" }}>
<Sequence from={0} durationInFrames={90}>
<AbsoluteFill style={{ opacity, transform: `scale(${scale})` }}>{/* cena 1 */}</AbsoluteFill>
</Sequence>
<Sequence from={90} durationInFrames={210}>{/* cena 2 */}</Sequence>
</AbsoluteFill>
);
};
Anime usando useCurrentFrame() com interpolate() e spring() apenas. Nunca leia hora do relógio de parede (Date.now()) ou chame Math.random() sem semente dentro de uma composição. Por quê: a renderização é paralela e endereçável por quadro — cada quadro é calculado independentemente, portanto qualquer entrada não-quadro produz um pixel diferente na re-renderização e quebra a garantia de "mesma entrada, mesma saída". Se precisar de aleatoriedade, use o random(seed) do Remotion.
Transições
Use @remotion/transitions (disponível desde v4.0.53). <TransitionSeries> intercala .Sequence (um clipe, com durationInFrames) e .Transition (uma presentation + uma timing). A duração da transição é subtraída do total, então sequências adjacentes se sobrepõem durante o wipe.
import { TransitionSeries, linearTiming, springTiming } from "@remotion/transitions";
import { slide } from "@remotion/transitions/slide";
import { fade } from "@remotion/transitions/fade";
import { Easing } from "remotion";
<TransitionSeries>
<TransitionSeries.Sequence durationInFrames={90}>{/* cena A */}</TransitionSeries.Sequence>
<TransitionSeries.Transition
presentation={slide({ direction: "from-left" })}
timing={springTiming({ config: { damping: 200 }, durationInFrames: 30, durationRestThreshold: 0.001 })}
/>
<TransitionSeries.Sequence durationInFrames={120}>{/* cena B */}</TransitionSeries.Sequence>
<TransitionSeries.Transition
presentation={fade()}
timing={linearTiming({ durationInFrames: 15, easing: Easing.inOut(Easing.ease) })}
/>
<TransitionSeries.Sequence durationInFrames={90}>{/* cena C */}</TransitionSeries.Sequence>
</TransitionSeries>
Cada apresentação é uma sub-importação (@remotion/transitions/slide, /fade, /wipe, /flip, /clockWipe, /none).
| Apresentação | Sensação / quando |
|---|---|
slide | Cena empurra a próxima para dentro; momentum direcional entre batidas |
fade | Crossfade suave; mudança de cena calma e neutra |
wipe | Uma borda dura varre; enérgico, "próximo tópico" |
flip | Giro 3D de cartão; divertido, para revelações |
clockWipe | Varredura radial; contagens regressivas, "passagem do tempo" |
none | Um corte brusco sem movimento, mas ainda como um nó TransitionSeries |
linearTiming para cortes previsíveis e exatos em quadros; springTiming para movimento orgânico. Por quê: linear é determinístico em duração, então você pode orçar quadros exatamente; spring ultrapassa e se estabiliza, o que parece natural, mas precisa de durationRestThreshold para que a renderização saiba quando terminou.
Legendas animadas incorporadas
O pacote nativo @remotion/captions foi enviado na v4.0.216 (o mesmo lançamento que descontinuou o antigo helper convertToCaptions()). O pipeline é executado uma vez em um servidor Node, então a composição lê as legendas:
- Transcrever.
@remotion/install-whisper-cppbaixa o Whisper.cpp e um modelo (medium.entem ~1.5 GB) e transcreve o áudio em um servidor Node para JSON do Whisper. - Converter.
toCaptions()de@remotion/install-whisper-cpptransforma esse JSON em umCaption[]com timestamps por token. (convertToCaptions()é o alias legado — descontinuado desde v4.0.216; usetoCaptions().) - Segmentar em páginas.
@remotion/captionscreateTikTokStyleCaptions({ captions, combineTokensWithinMilliseconds })agrupa tokens em "páginas" que aparecem juntas.
O valor combineTokensWithinMilliseconds é o dial do tamanho da página. Por quê: um valor baixo (~200ms) mantém cada palavra em sua própria página → animação pop palavra por palavra; um valor alto (~1200ms) empacota uma frase por página. Ms baixo = energia palavra por palavra ao estilo TikTok; ms alto = frases legíveis. Escolha pelo formato, não por padrão.
A instalação completa do Whisper.cpp, o servidor de transcrição e o componente renderizador de legendas com destaque de token (com estilização de zona segura) estão em references/captions-pipeline.md — leia antes de construir a camada de legendas.
Remoção automática de silêncio
A passagem de silêncio é executada no áudio/vídeo de origem ANTES de entrar no Remotion, não dentro de uma composição. Por quê: o Remotion renderiza os quadros que você fornece; aparar ar morto é uma edição upstream no ativo, e fazer isso primeiro significa que cada número de quadro downstream já reflete a linha do tempo apertada.
Use auto-editor (um mecanismo Python + ffmpeg) para uma primeira passagem que corta espaços mortos pela intensidade do áudio:
auto-editor input.mp4 --margin 0.2s --edit audio:threshold=4% -o tightened.mp4
--marginpreenche cada região mantida para que os cortes não cortem a fala.--edit audio:threshold=4%define o piso de intensidade abaixo do qual uma região é "silêncio".--export premiereemite um EDL/XML em vez de um arquivo, para reimportar em um NLE.
A distribuição pip está desatualizada/descontinuada — instale via binário oficial ou pipx, não pip install. Por quê: o pacote PyPI está defasado e pode não corresponder às flags documentadas. Quando auto-editor não está disponível, a alternativa de baixo nível são os filtros silencedetect / silenceremove do ffmpeg. Ambos, com a matriz completa de flags, estão em references/render-and-pipeline.md.
Sobreposições de b-roll
Empilhe a sobreposição acima do vídeo principal colocando <OffthreadVideo> (ou <Img>) dentro de um <AbsoluteFill>, controlado por um <Sequence from>:
import { AbsoluteFill, Sequence, OffthreadVideo, staticFile } from "remotion";
const fps = 30;
const broll = { start: 4.0, duration: 3.0 }; // segundos
<AbsoluteFill>
<OffthreadVideo src={staticFile("main.mp4")} /> {/* camada base */}
<Sequence from={Math.round(broll.start * fps)} durationInFrames={Math.round(broll.duration * fps)}>
<AbsoluteFill style={{ /* ex.: recuo para picture-in-picture */ }}>
<OffthreadVideo src={staticFile("broll.mp4")} /> {/* camada de sobreposição */}
</AbsoluteFill>
</Sequence>
</AbsoluteFill>
Converta cada timecode para quadros com Math.round(segundos * fps), uma vez, na borda. Por quê: uma dica de b-roll em 4.0s é o quadro 120 a 30fps, mas quadro 240 a 60fps — mantenha segundos em seus dados e multiplique por fps de useVideoConfig() para que mudar o fps nunca dessincronize sobreposições. Use <OffthreadVideo> (não o <video> do DOM ou <Video>) para decodificação precisa de quadros durante a renderização.
Renderizar
# teste de região primeiro: 1-2 segundos, valida o pipeline de forma barata
npx remotion render MyVideo out/test.mp4 --frames=0-45
# depois a renderização completa
npx remotion render MyVideo out/video.mp4
Omita o id da composição para obter um seletor interativo. Configure via @remotion/cli/config em remotion.config.ts, ou passe flags na CLI (flags vencem):
// remotion.config.ts
import { Config } from "@remotion/cli/config";
Config.setConcurrency(8);
Config.setCodec("h264");
| Codec | Uso | Flag |
|---|---|---|
h264 | Padrão para web/YouTube; ampla compatibilidade | (padrão) |
h265 | Arquivos menores, mesma qualidade; reprodução menos universal | --codec=h265 |
prores | Master de qualidade de edição, arquivos grandes, reimportar para um NLE | --codec=prores --prores-profile=4444 --pixel-format=yuva444p10le --image-format=png |
vp8 / gif | Web-alpha ou prévias em loop | --codec=vp8 / --codec=gif |
Sempre renderize uma região de 1-2s (--frames=0-45) antes da renderização completa. Por quê: uma renderização completa de uma composição de minutos custa tempo e CPU reais; um teste de região revela uma camada de legenda quebrada ou ativo faltando em segundos. Para renders headless/CI, regras de saída determinística e a matriz de codec/qualidade completa, veja references/render-and-pipeline.md.
Anti-padrões
| Ruim | Por que quebra | Bom |
|---|---|---|
| Codificar durações em segundos dentro do JSX | Remotion pensa em quadros; segundos dessincronizam quando o fps muda | Armazene segundos em dados, Math.round(segundos * fps) na borda |
Date.now() / Math.random() sem semente em uma composição | Quadros renderizam em paralelo e na re-renderização → pixels não determinísticos | Dirija tudo a partir de useCurrentFrame(); use random(seed) |
Mudar fps depois de escrever durações | Cada contagem de quadro downstream muda silenciosamente | Fixe fps + dimensões no <Composition> de início, deixe-os |
| Rebaixar o modelo Whisper toda execução | O download de ~1.5 GB medium.en repete e empaca o pipeline | Baixe uma vez, armazene em cache o caminho do modelo, reutilize |
| Commit do modelo Whisper de 1.5 GB no git | Inchação do repositório; o modelo é um ativo de build | .gitignore o diretório do modelo; busque no setup/CI |
| Renderizar o vídeo completo para testar uma mudança | Minutos de renderização desperdiçados para encontrar uma camada quebrada | Teste de região --frames=0-45, depois renderização completa |
| Escrever o texto da legenda ou gancho aqui | Isso é o script, não a codificação | Direcione para ../video-shorts/SKILL.md; você só incorpora |
<video> simples / <Video> para b-roll em uma renderização | Não é preciso em quadros; rasga ou pula na renderização | <OffthreadVideo> para decodificação exata de quadros |
| Executar remoção de silêncio dentro da composição | Aparar ar morto é uma edição upstream do ativo | auto-editor no arquivo de origem antes do Remotion |
Verificar & referências
bash scripts/verify.sh <project-dir>— verifica se o projeto Remotion está bem formado e renderiza. Com Node + ffmpeg presentes, executanpx remotion compositionspara confirmar que um id de composição existe, faz uma renderização curta de região para um MP4 temporário e usaffprobepara confirmar um fluxo de vídeo com as dimensões/fps esperados. Sem nenhum dos dois, cai para uma verificação estática: pelo menos um.tsxde composição existe e o script de renderização referencia um id de composição real e um caminho de saída. Somente leitura por padrão; sai com 0 em um alvo vazio/limpo.references/captions-pipeline.md— instalação completa do Whisper.cpp + servidor de transcrição,toCaptions, componente renderizador de legendas com destaque de token e notas de estilização/zona segura.references/render-and-pipeline.md— comandos de silêncio doauto-editor+ ffmpeg, matriz completa de flags de renderização, render headless/CI, tabela de codecs e verificaçãoffprobe.