remotion-best-practices

Overview

What is the remotion-best-practices skill?

A skill remotion-best-practices é um conjunto curado de guias e regras para criar vídeos com Remotion, o framework de criação de vídeos baseado em React. Ela reúne padrões específicos de domínio para animações, áudio, legendas, uso de FFmpeg, assets, cenas 3D e mais em arquivos de regras focados dentro de rules/.

Em vez de ter que montar exemplos do zero, esta skill oferece orientações opinativas sobre como estruturar código Remotion para renderizar de forma confiável, escalar para projetos complexos e continuar fácil de manter com o tempo.

Who is this skill for?

Instale esta skill se você:

• Cria vídeos de marketing, produto ou social usando Remotion e React
• Precisa gerar vídeos de forma programática (por exemplo, conteúdo data-driven ou baseado em templates)
• Trabalha com conteúdo fortemente baseado em áudio, como podcasts, audiograms ou visualizers de música
• Quer padrões claros para legendas, subtitles e fluxos de trabalho com SRT
• Está adicionando conteúdo 3D ou Three.js às suas composições Remotion

Ela é útil para engenheiros frontend, motion designers que programam e times que querem padronizar como escrevem projetos em Remotion.

What problems does it solve?

A skill Remotion best-practices ajuda a resolver problemas práticos que aparecem em projetos reais de Remotion, como:

• Controlar todas as animações por frame para que os renders sejam estáveis e determinísticos
• Importar e referenciar imagens, vídeos, áudio e fontes corretamente via pasta public/ e staticFile()
• Criar composições de vídeo limpas com timing, transições e parâmetros consistentes
• Tratar áudio (camadas, cortes, atrasos, volume, velocidade, loops, SFX)
• Gerar visualizações de áudio (barras de espectro, waveforms, efeitos reativos ao grave)
• Trabalhar com legendas e subtitles, incluindo importação de SRT e transcrição
• Usar FFmpeg para tarefas como cortar, extrair frames ou detectar silêncio
• Integrar 3D com Three.js e React Three Fiber via @remotion/three
• Calcular dinamicamente metadados da composição (duração, dimensões, props) antes do render
• Validar compatibilidade de mídia com Mediabunny antes de renderizar

Se você está construindo algo além de um demo trivial em Remotion, essas regras fornecem padrões testados em cenários reais de produção.

When is this skill a good fit?

Use a skill remotion-best-practices quando:

• Seu projeto já usa Remotion ou você está avaliando Remotion para geração de vídeo
• Você quer diretrizes consistentes para animações, assets, áudio, legendas e 3D
• Precisa de exemplos em nível de código, e não apenas documentação conceitual

Ela não substitui a documentação principal do Remotion nem é um tutorial completo de React. Parte do pressuposto de que você já está à vontade com React básico e ao menos deu uma olhada na documentação do Remotion.

How to Use

1. Installation and setup

Install the skill into your agent environment

Use o gerenciador de skills para adicionar a skill Remotion best-practices a partir do repositório upstream:

npx skills add https://github.com/remotion-dev/skills --skill remotion

Isso torna o conhecimento de remotion-best-practices disponível para o seu agente, para que ele possa consultar os arquivos de regras ao ajudar no seu projeto Remotion.

Review the core documentation files

Depois de instalar, abra primeiro estes arquivos:

• SKILL.md – Descrição geral, quando usar e links para os principais arquivos de regras
• rules/animations.md – Como dirigir animações com useCurrentFrame() e useVideoConfig()
• rules/assets.md – Como importar imagens, vídeos, áudio e fontes corretamente
• rules/audio.md – Como trabalhar com áudio, cortes, delays e camadas
• rules/audio-visualization.md – Dados de áudio, waveforms e visualizações de espectro
• rules/3d.md – Cenas 3D usando Three.js e React Three Fiber via @remotion/three

Essas regras dão a base para a maioria dos fluxos de edição de vídeo com Remotion.

2. Core concepts and best practices

Drive all animations by frame

Veja rules/animations.md para o princípio central de animação no Remotion:

• Use useCurrentFrame() para ler o frame atual
• Use useVideoConfig() para obter o fps
• Calcule o tempo das animações em segundos e depois converta para frames (seconds * fps)
• Use helpers como interpolate() para mapear frames para posições, opacidade ou outras propriedades
• Evite transitions e animações em CSS, bem como classes de animação do Tailwind; elas não renderizam de forma confiável no Remotion

Essa abordagem orientada por frame garante saída consistente, independentemente da velocidade de playback ou ambiente.

Manage assets via public/ and staticFile()

O arquivo rules/assets.md define como lidar com mídia:

• Coloque toda mídia estática (imagens, fontes, áudio, vídeo) na pasta public/
• Use staticFile("my-file.ext") para referenciar assets dentro de public/
• Combine staticFile() com componentes Remotion como <Img>, <Video>, <Audio>
• Use URLs remotas diretamente quando o arquivo estiver hospedado na web

Esse padrão evita caminhos quebrados, cuida de encoding de URLs e funciona em diferentes setups de deploy.

Build robust audio and sound design

O arquivo rules/audio.md cobre fluxos de trabalho específicos de áudio:

• Importe áudio com <Audio> de @remotion/media
• Corte trechos de áudio com trimBefore e trimAfter (baseados em frame)
• Atrasar o áudio ou sincronizá-lo com o vídeo usando wrappers <Sequence>
• Criar camadas com múltiplos componentes <Audio> para música, narração e SFX

Para visuais guiados por áudio, combine com rules/audio-visualization.md para:

• Instalar @remotion/media-utils
• Usar useWindowedAudioData() para ler amostras de áudio em uma janela de tempo
• Usar visualizeAudio() para produzir dados de frequência para barras de espectro

Isso facilita a criação de audiograms, títulos reativos ao beat e visualizações de música.

Handle captions and subtitles

O SKILL.md principal aponta para as regras relacionadas a legendas:

• rules/subtitles.md – Padrões de uso de subtitles
• rules/display-captions.md – Renderização de legendas na tela
• rules/import-srt-captions.md – Importação de arquivos de legendas SRT
• rules/transcribe-captions.md – Fluxos de trabalho de transcrição

Use esses arquivos quando precisar de:

• Legendas gravadas no vídeo para conteúdo social
• Faixas de legenda específicas por idioma
• Fluxos de legendagem automatizados ou semi-automatizados

Use FFmpeg for advanced video operations

O guia rules/ffmpeg.md mostra quando usar FFmpeg junto com Remotion para operações como:

• Cortar ou concatenar vídeos de origem
• Detectar silêncio em faixas de áudio
• Extrair frames ou criar GIFs

Remotion foca em composição e render; o FFmpeg cuida do trabalho pesado nos arquivos de mídia brutos. Combinar os dois costuma ser a abordagem mais eficiente em pipelines de vídeo para produção.

Bring in 3D with Three.js and React Three Fiber

Se você quer cenas 3D nos seus vídeos Remotion, leia rules/3d.md:

• Instale o pacote @remotion/three com o comando recomendado npx remotion add @remotion/three (ou equivalente do seu gerenciador de pacotes)
• Envolva o conteúdo 3D em <ThreeCanvas> e passe width e height a partir de useVideoConfig()
• Configure iluminação básica (por exemplo, ambientLight e directionalLight)
• Controle todas as animações 3D usando useCurrentFrame() em vez de useFrame() de @react-three/fiber

Isso garante que o conteúdo 3D seja renderizado corretamente frame a frame, sem flicker ou dessincronização.

3. Dynamic compositions and metadata

Calculate duration and dimensions dynamically

O arquivo rules/calculate-metadata.md mostra como usar calculateMetadata em uma <Composition> para:

• Ajustar durationInFrames com base em dados externos (por exemplo, o tamanho de um vídeo de entrada)
• Fazer as dimensões da composição baterem com um vídeo de entrada ou outros valores dinâmicos
• Transformar props antes do início do render

Em conjunto com helpers como rules/get-video-duration.md e rules/get-video-dimensions.md, isso permite:

• Redimensionar automaticamente a composição para conteúdo enviado pelo usuário
• Garantir que intros/outros combinem exatamente com a duração da mídia

Isso é especialmente útil em sistemas de vídeo com conteúdo gerado pelo usuário ou baseados em templates.

4. Media validation and compatibility

Check if a video can be decoded

O guia rules/can-decode.md apresenta o Mediabunny para checagens de compatibilidade:

• Instale o Mediabunny com npx remotion add mediabunny
• Use o helper canDecode() para verificar se um vídeo de origem em URL pode ser decodificado pelo navegador
• Use a variação canDecodeBlob() para fontes enviadas como Blob

Isso é útil ao construir fluxos de upload em que você precisa validar a mídia antes de iniciar um render caro.

5. Additional focused rules

Além dos tópicos principais, rules/ inclui guias especializados que você pode usar conforme necessário:

• rules/compositions.md – Como estruturar e gerenciar suas composições Remotion
• rules/timing.md, rules/sequencing.md, rules/transitions.md, rules/text-animations.md – Controle fino de movimento e timing
• rules/fonts.md, rules/measuring-text.md, rules/measuring-dom-nodes.md – Tipografia e precisão de layout
• rules/gifs.md, rules/images.md, rules/videos.md, rules/transparent-videos.md, rules/trimming.md, rules/extract-frames.md – Trabalho com diferentes formatos e operações de mídia
• rules/maps.md, rules/charts.md, rules/lottie.md, rules/light-leaks.md – Padrões visuais específicos de domínio
• rules/voiceover.md, rules/sfx.md – Fluxos de trabalho para narração e efeitos sonoros
• rules/tailwind.md – Como usar Tailwind de forma compatível com Remotion (sem as classes de animação proibidas)

Você pode consultar esses arquivos seletivamente, conforme os recursos que seu projeto exigir.

6. Workflow tips for using this skill

With an AI agent

Se você estiver usando um assistente de IA com esta skill instalada:

• Peça para abrir um arquivo de regra específico (por exemplo, rules/audio.md) quando precisar de exemplos mais detalhados
• Deixe-o gerar trechos de código que sigam as regras (sem CSS transitions, todas as animações via useCurrentFrame(), uso correto de staticFile(), etc.)
• Use a skill como checklist ao revisar ou refatorar seu código Remotion

In a team setting

Para times, padronize o uso desta skill assim:

• Compartilhe links para os arquivos rules/*.md relevantes na sua documentação interna
• Adote os padrões da skill nas suas diretrizes de código
• Use-a como referência ao onboarding de desenvolvedores em projetos Remotion

FAQ

Is this skill the same as the Remotion framework?

Não. Remotion é o framework base para criar vídeos com React. A skill remotion-best-practices é uma coleção de boas práticas e arquivos de regras que ficam por cima do Remotion, orientando como estruturar o código, tratar mídia e evitar armadilhas comuns.

Do I need to know React to benefit from this skill?

Sim. Todo o ecossistema Remotion é baseado em React, e os exemplos nos arquivos de regras assumem que você entende componentes, props e hooks. A skill se concentra em questões específicas do Remotion, não em ensinar React do zero.

How do I install the Remotion best-practices skill?

Instale no seu agente ou ambiente de skills com:

npx skills add https://github.com/remotion-dev/skills --skill remotion

Depois abra SKILL.md e a pasta rules/ para explorar os tópicos disponíveis.

Can I use this skill without a Remotion project yet?

Você pode ler o conteúdo e os exemplos mesmo sem um projeto existente, mas ela é muito mais útil quando você já tem um workspace Remotion. Muitas regras fazem referência a pacotes como @remotion/media, @remotion/media-utils, @remotion/three ou Mediabunny, que você vai querer instalar diretamente no seu projeto.

Does this skill cover 3D content with Three.js?

Sim. O arquivo rules/3d.md é dedicado a 3D em Remotion usando Three.js e React Three Fiber via @remotion/three. Ele explica como instalar o pacote, envolver o conteúdo em <ThreeCanvas> e controlar animações com useCurrentFrame().

Where do I find guidance on audio visualizations and audiograms?

Use rules/audio-visualization.md. Ele mostra como instalar @remotion/media-utils, buscar dados de áudio com useWindowedAudioData() e transformá-los via visualizeAudio() para construir barras espectrais e waveforms para audiograms.

What if I need to work with captions and subtitles?

Comece por SKILL.md, que aponta para:

• rules/subtitles.md para padrões gerais de subtitles
• rules/display-captions.md para renderização de legendas na tela
• rules/import-srt-captions.md para importação de arquivos SRT
• rules/transcribe-captions.md para fluxos de trabalho de transcrição

Esses guias cobrem a maior parte das necessidades de legendagem em vídeos baseados em Remotion.

When should I use FFmpeg instead of pure Remotion code?

Use FFmpeg quando você precisar de operações em arquivos de mídia brutos, como cortes precisos, concatenação, detecção de silêncio ou extração de frames. Remotion é excelente para compor e renderizar cenas em React. O rules/ffmpeg.md explica como e quando integrar FFmpeg ao seu pipeline Remotion.

Can this skill help me avoid performance and rendering issues?

Sim. Muitas regras existem justamente para evitar problemas comuns, como:

• Cenas 3D com flicker quando se usa useFrame() em vez de useCurrentFrame()
• Animações que não renderizam por dependerem de CSS transitions
• Caminhos de assets quebrados e URLs codificadas incorretamente
• Mídia que falha no render porque não pode ser decodificada

Seguir os padrões em rules/animations.md, rules/assets.md, rules/3d.md e rules/can-decode.md ajuda a criar projetos Remotion mais confiáveis.

How do I explore all available rule files?

Depois da instalação, abra o diretório rules/ no seu ambiente. Arquivos principais incluem:

• rules/3d.md
• rules/animations.md
• rules/assets.md
• rules/audio-visualization.md
• rules/audio.md
• rules/ffmpeg.md
• rules/compositions.md
• rules/timing.md
• rules/subtitles.md
• rules/voiceover.md

Use a aba de arquivos ou seu editor para navegar pelo restante e encontrar tópicos mais especializados, como charts, maps, GIFs e Tailwind.