Remotion
Remotion transforma componentes React em vídeos. Você escreve JSX, o Remotion chama seu componente uma vez por quadro a um fps fixo, e os quadros resultantes são unidos em um MP4 (ou outro formato).
Modelo mental central
Remotion fornece a você um número de quadro e uma tela em branco. Seu componente React decide o que renderizar naquele quadro.
Não há uma linha do tempo de animação no sentido imperativo. O tempo é um número (frame), e seu componente é uma função pura desse número mais as propriedades. É por isso que as animações devem ser conduzidas por useCurrentFrame() — transições CSS e setTimeout são não determinísticas durante a renderização e causarão cintilação ou dessincronização.
Quando usar esta habilidade
- O usuário tem um projeto Remotion (
remotion.config.tsou@remotion/*no package.json) e deseja construir, alterar ou depurar uma composição - O usuário diz "vamos fazer um vídeo com Remotion / com código / programaticamente"
- O usuário cola um erro do Remotion ou pergunta sobre
interpolate,spring,Sequence,useCurrentFrame,Composition, etc. - O usuário deseja renderizar um projeto Remotion existente ou configurar a renderização Lambda
Quando NÃO usar
- Gerar vídeo com modelos de IA (Veo, Sora, Runway, Kling, HeyGen) → use a habilidade video
- Editar arquivos de vídeo existentes (cortar/aparar/concatenar) → ffmpeg, não Remotion
- Transmissão ao vivo → Remotion é apenas renderização offline
Fluxo de trabalho
-
Detectar ou criar o projeto.
- Novo projeto:
npx create-video@latest(interativo — escolhe um template como Hello World, Blank, JavaScript, TikTok, etc.) - Existente: verifique se há
remotion.config.ts,src/Root.tsxe@remotion/clinopackage.json. Observe a versão principal do Remotion — as APIs evoluem, e a URL correta da documentação éhttps://www.remotion.dev/docs(mais recente) ou páginas com versão fixa.
- Novo projeto:
-
Localizar ou criar a composição. As composições são registradas em
src/Root.tsxvia<Composition id="..." component={...} durationInFrames={...} fps={30} width={1920} height={1080} defaultProps={{...}} />. Oidé o que a CLI renderiza pelo nome. -
Construir o componente usando
useCurrentFrame+useVideoConfigpara tempo e metadados. Componha o layout com<AbsoluteFill>, fatie o tempo com<Sequence>. -
Visualizar no Studio:
npx remotion studio(recarrega automaticamente). Não tente "testar" quadros isoladamente — abra o Studio. -
Renderizar:
npx remotion render <CompositionId> [output.mp4]. O codec padrão é H.264 / MP4. Consulte references/rendering.md para flags e API programática.
Referência rápida da API
Consulte os arquivos vinculados para mais profundidade — carregue-os apenas quando uma tarefa precisar deles.
| Tópico | Arquivo |
|---|---|
| Composition, hooks, Sequence, AbsoluteFill, layout | references/core-concepts.md |
interpolate, spring, Easing, escalonamento, padrões de animação comuns | references/animation.md |
Renderização: flags da CLI, @remotion/renderer, Lambda, codecs, props | references/rendering.md |
Áudio/vídeo/imagens: <Audio>, <Video>, <Img>, <OffthreadVideo>, legendas | references/media.md |
Configuração do projeto, convenções de arquivo, remotion.config.ts | references/project-setup.md |
| Padrões comuns: animações de digitação, terços inferiores, orientado a dados, parallax | references/patterns.md |
Regras rígidas
- Anime via
useCurrentFrame(). NuncasetTimeout,requestAnimationFrameoutransitionCSS. Eles cintilam durante a renderização porque cada quadro é renderizado independentemente em um navegador headless. durationInFramesé obrigatório e deve ser um número inteiro. Total de segundos =durationInFrames / fps.- Mantenha os componentes puros. Sem efeitos colaterais de nível superior, sem
Math.random()sem uma semente determinística — o mesmo quadro deve sempre produzir os mesmos pixels. - Não busque dados durante a renderização. Use
delayRender()/continueRender()para bloquear a prontidão do quadro enquanto os dados carregam, ou pré-busque e passe via props. - Use
<OffthreadVideo>em vez de<Video>quando possível para leituras de vídeo não bloqueantes durante a renderização (mais rápido, menos memória). - Passe dados dinâmicos via
--props(CLI) ouinputProps(Studio/programático), não editando arquivos.
Erros comuns
| Erro / sintoma | Causa | Correção |
|---|---|---|
| Cintilação / movimento incompatível no MP4 vs visualização do Studio | Usou transições CSS ou animação não baseada em quadro | Substitua por interpolate(frame, ...) ou spring({ frame, fps }) |
| "Composition not found" | Erro de digitação no ID ou registro de <Composition> ausente | Verifique src/Root.tsx |
| Renderização trava | delayRender() pendente nunca chamou continueRender() | Encontre a promise não resolvida; adicione try/finally |
| Falta de memória em vídeos longos | <Video> mantendo quadros na memória | Mude para <OffthreadVideo> |
| Áudio fora de sincronia | Incompatibilidade de fps do arquivo de áudio ou início no quadro errado | Envolva <Audio> em <Sequence from={...}> |
Verificação
Após fazer alterações, sempre:
- Execute
npx remotion studioe percorra a linha do tempo para confirmar se a alteração parece correta em vários quadros (início, meio, fim) - Para alterações programáticas, renderize um pequeno segmento de teste:
npx remotion render <id> out.mp4 --frames=0-60 - Verificação de tipo:
npx tsc --noEmitse o projeto for TypeScript
Não afirme sucesso sem uma destas etapas. Código que compila não é o mesmo que um vídeo que parece correto.