iamryoman/remotion-best-practices

Práticas Recomendadas para Remotion

Construa a saída do Remotion como uma função determinística do frame, das props de entrada e dos recursos declarados. Preserve as edições do usuário e o gerenciador de pacotes, arquitetura e estilo existentes do projeto, a menos que a tarefa exija uma alteração.

Comece com evidências

1. Leia as instruções do repositório e inspecione package.json, o arquivo de lock, a configuração do Remotion, o ponto de entrada, as composições registradas e os testes próximos.
2. Em um projeto existente, execute node <skill-directory>/scripts/audit-remotion-project.mjs <project-root>. Trate sua saída como evidência, não como permissão para fazer upgrade.
3. Registre a versão instalada do Remotion antes de escolher as APIs. Mantenha todos os pacotes remotion e @remotion/* na mesma versão exata. Não adicione um segundo arquivo de lock.
4. Identifique se a entrega é um vídeo, uma imagem estática única, um frame amostrado de um vídeo ou um lote de capturas de tela para loja.
5. Defina o ID da composição, dimensões, FPS, duração, props, caminho de saída e recursos necessários antes da implementação.

Carregue apenas a referência relevante

• Para <Composition>, <Still>, useCurrentFrame(), interpolate(), spring(), <Sequence> ou <Series>, leia composition-and-timing.md.
• Para staticFile(), mídia, fontes, dados de rede, useDelayRender(), delayRender() ou calculateMetadata(), leia assets-and-async.md.
• Para CLI, renderStill(), renderização no servidor ou Remotion Lambda, leia rendering-and-lambda.md.
• Para renderizações lentas, alto uso de memória, não determinismo ou estratégia de verificação, leia performance-and-testing.md.
• Para imagens da App Store ou Google Play, incluindo saída em 1284×2778 delegada pelo screenshot-studio, leia store-stills.md.
• Quando uma regra de API ou plataforma pode ter mudado, consulte a fonte primária ativa vinculada em sources.md antes de codificar.

Regras de implementação inegociáveis

• Derive o tempo de useCurrentFrame() e useVideoConfig(). Não use transições CSS, animações CSS com keyframes, temporizadores de relógio ou aleatoriedade não seedada para movimentos renderizados.
• Limite animações finitas, a menos que a extrapolação seja intencional. Expresse temporizações em segundos multiplicados por fps quando representarem tempo e centralize durações de cena compartilhadas.
• Lembre-se de que useCurrentFrame() é relativo dentro de um componente temporizado. Passe um frame absoluto da raiz da composição apenas quando a sincronização global for intencional.
• Use <Sequence> para posicionamento explícito na linha do tempo pai e <Series> para cenas contíguas. Dê a cada cena uma duração explícita.
• Coloque recursos locais em public/ e resolva-os com staticFile(). Use componentes de mídia do Remotion em vez de tags HTML brutas para que a renderização aguarde corretamente pela mídia.
• Prefira useDelayRender() dentro de componentes. Crie um handle uma vez, limpe-o exatamente uma vez e chame cancelRender(error) em caso de falha. Prefira calculateMetadata() para dados necessários para determinar props ou metadados uma vez por renderização.
• Mantenha o código em tempo de renderização livre de suposições específicas de navegador que não estão disponíveis no Chromium headless ou no Lambda. Nunca exponha credenciais AWS ou outros segredos ao bundle do navegador.
• Valide dimensões, formato de arquivo, política de canal alfa e regras específicas da plataforma independentemente para cada destino de loja. Nunca presuma que um tamanho de retrato é aceito tanto pela Apple quanto pelo Google.

Trabalhe em um loop de renderização restrito

1. Verifique tipos e execute testes focados.
2. Renderize frames estáticos representativos: o início, cada fronteira de cena, um ponto médio de movimento e o último frame.
3. Inspecione os pixels reais, não apenas a prévia do Studio. Verifique clipping, quebra de texto, margens seguras, recursos ausentes e fundos transparentes.
4. Renderize uma pequena faixa de frames ou um rascunho em escala reduzida antes de um vídeo completo e caro.
5. Avalie a concorrência na máquina de implantação em vez de maximizá-la cegamente.
6. Renderize o artefato final com um ID de composição, props, caminho de saída, dimensões e formato explícitos.
7. Verifique o status de saída, a existência do arquivo, as dimensões dos pixels, a duração/contagem de frames (quando relevante) e uma amostra visual final.

Faça alterações de forma conservadora

• Não faça upgrade do Remotion, reescreva a estrutura do projeto ou substitua componentes de mídia, a menos que seja exigido pela tarefa ou aprovado pelo usuário.
• Proteja APIs mais novas atrás da versão instalada; forneça um fallback compatível quando prático.
• Não esconda falhas de renderização com aumentos arbitrários de timeout. Primeiro identifique o handle não resolvido, requisição de rede, recurso, fonte ou decodificação de mídia.
• Não afirme melhoria de desempenho sem medições de renderizações comparáveis.