REMOÇÃO MOTION DESIGN — Skill de Implementação
1. Revisão antes de codificar
- Leia
CLAUDE.md,MASTER_PROMPT.mde os documentos de arquitetura. - Verifique as versões reais do Remotion/React/TypeScript e o gerenciador de pacotes.
- Encontre o ponto de entrada existente e o registro de composições.
- Siga as convenções do repositório; não troque dependências sem necessidade.
- Use a saída de
beyond-video, o roteiro, o storyboard e a Bíblia de Estilo como especificação de produção. - Verifique as APIs que você usa com a fonte do Remotion da versão instalada
(ex.:
packages/core/srcem um clone de referência) antes de confiar na memória.
2. Perfil da composição
Padrões:
- largura: 1080
- altura: 1920
- fps: 60
- proporção: 9:16
- duração: inteiro positivo em frames
Toda composição precisa de um ID único e metadados explícitos. Não armazene diferentes valores de FPS em várias camadas sem motivo.
<Composition> aceita id, fps, width, height, durationInFrames,
defaultProps e, opcionalmente, calculateMetadata (duração/metadados dinâmicos a partir de props) e schema. durationInFrames deve ser positivo.
3. Engenharia da linha do tempo
- Mantenha durações e frames de início em dados/config centralizados.
- Use uma única convenção de intervalo de frames;
[start, end)é recomendado. - A
durationInFramesda cena deve ser positiva. - Garanta que a duração total da composição contenha cada cena mais o final/fechamento.
- Valide sobreposições e lacunas; sobreponha apenas quando intencional para uma transição/composição.
- Não confie em ponto flutuante para o limite final do frame.
4. Animação determinística — APIs de tempo/frame (Remotion 4.x)
Fontes de tempo:
useCurrentFrame()— o frame atual, indexado a partir de 0. Só pode ser usado dentro de um componente de composição; fora de uma composição, lança erro.useVideoConfig()— retorna{width, height, fps, durationInFrames, id, defaultProps, defaultVideoImageFormat, ...}; lança erro fora de uma composição.
Interpolação e molas:
interpolate(input, inputRange, outputRange, options?)— sobrecargas para saída numérica, string, booleana e array. Opções:easing,extrapolateLeft/extrapolateRight('extend' | 'identity' | 'clamp' | 'wrap'),output,outputType,posterize. Use extrapolaçãoclampquando o movimento não deve ultrapassar o intervalo.spring({frame, fps, config?, from=0, to=1, durationInFrames?, durationRestThreshold?, delay=0, reverse=false}).SpringConfig:damping(padrão 10),mass(1),stiffness(100),overshootClamping(false).damping <= 0faz a animação nunca estabilizar (erro de loop infinito).measureSpring({fps, config?, threshold=0.005})— número de frames até a mola estabilizar;threshold=0resulta emInfinity.
Regras:
- O movimento deve ser uma função do frame e das props.
- Valores de semente para partículas/ruído/aleatórios.
- Evite
setInterval,setTimeout,requestAnimationFrame,Date.now()e keyframes CSS autoexecutáveis como fonte principal de movimento de vídeo. - Não busque dados de rede enquanto a composição renderiza.
- Não inclua áudio/vídeo de URLs instáveis ou que exijam login.
delayRender(label?, options?)segura a renderização até quecontinueRender(handle)seja chamado (ex.: assets assíncronos); seu timeout é definido com o CLI--timeout.
5. Sequence, Series, e frames locais vs globais
Esta é a regra mais frequentemente errada — um bug real já aconteceu porque um componente calculou o frame global dentro de um Series.Sequence:
- Dentro de uma
<Sequence>,useCurrentFrame()retorna o frame RELATIVO ao início da Sequence:(frame - (cumulatedFrom + relativeFrom)) * playbackRate. Componentes dentro de uma Sequence NÃO veem o frame global. - Props de
<Sequence>:from?,name?,durationInFrames?(deve ser positivo; necessário ao usarloop),layout('absolute-fill'|'none'),premountFor,loope props de corte (apenas comlayout="absolute-fill"). <Series.Sequence>só pode ser usado dentro de<Series>; umSeries.Sequencefora de<Series>lança "This component must be inside a<Series />component."- Dois padrões de roteamento válidos — escolha um e mantenha-se consistente:
- Roteador de frame global (usado no projeto de vídeo): um componente roteador
usa
useCurrentFrame()global e seleciona o beat por seu intervalo[start, end); componentes do beat calculam a partir do frame global. - Series: cada
Series.Sequencecontém um beat; componentes do beat calculam a partir do frame local (0 no início da Sequence).
- Roteador de frame global (usado no projeto de vídeo): um componente roteador
usa
- Não misture ambos os padrões em uma composição sem um motivo explícito.
6. Estrutura de cena/componente
- Uma cena tem uma responsabilidade narrativa/visual.
- As props da cena são definidas em TypeScript.
- Componentes reutilizáveis resolvem uma tarefa visual clara.
- Evite um único arquivo contendo todo o vídeo.
- Separe configuração de conteúdo, renderizador, tokens de estilo e referências de assets.
- Adicione fallbacks projetados para assets opcionais; nunca esconda um asset crítico ausente.
7. Componentes de mídia e assets
<Img src>— uma imagem que falha ao carregar semonErrorcancela a renderização (cancelRender). Sempre forneçaonErrorpara assets críticos, ou garanta que o asset exista antes de renderizar.staticFile(path)— mapeia um arquivo empublic/; use para todo asset local (imagens, áudio, vídeo).<Audio>— vejasound-designpara mapear uma folha de dicas para props (trimBefore/After— alias antigostartFrom/endAt—volume,playbackRate). A posição de uma dica na linha do tempo é definida por<Sequence from>; as props de corte apenas cortam qual parte do arquivo é reproduzida.<Audio>não tem propmuted; mudo é uma flag do CLI (--muted).<Video>/<OffthreadVideo>e<Still>seguem as mesmas regras de frame; a duração da mídia deve ser agendada a partir de frames, não de metadados de arquivo.
8. Movimento 2D
Use SVG/formas/CSS/rasters conforme necessário. Preste atenção a âncoras, origens de transformação, anti-aliasing, camadas, recorte e à área segura. Toda transformação deve ser orientada por frames.
9. Suporte a pixel art e boneco palito
Pixel art:
- trave a tela lógica e a escala de pixels;
- use nearest-neighbor ao escalar sprites;
- prenda posições à grade quando necessário;
- trave a paleta e as dimensões do sprite;
- evite desfoque e cintilação de subpixel.
Boneco palito:
- mantenha proporções e pivôs consistentes;
- use uma biblioteca de pose/rig quando a escala do projeto justificar;
- anime silhueta e gesto para que sejam legíveis;
- sincronize expressões/poses com os beats da história.
Para ciclos de caminhada, follow-through e movimento ocioso, veja character-animation.
10. Movimento 3D
- Adicione 3D apenas quando trouxer valor criativo.
- Verifique as versões de
three,@react-three/fiber,@remotion/threee suas documentações. - Para integração com ThreeCanvas do Remotion, siga a abordagem orientada por frames da versão da API instalada; não assuma que padrões R3F em tempo real são automaticamente determinísticos.
- Direcione câmera, transformações, materiais, iluminação e partículas a partir do frame.
- Considere compatibilidade com renderizador/headless, tamanho de textura, geometria e custo computacional.
- Separe a camada 3D de tipografia/overlays 2D quando isso ajudar na legibilidade e manutenibilidade.
- Para dirigir cenas 3D em detalhes, veja
3d-scene-director.
11. Tipografia e transições
- Priorize hierarquia e legibilidade.
- Nunca cubra texto importante com uma transição.
- Toda transição conecta dois beats; não adicione efeitos sem função.
- Mantenha curvas de movimento e intensidade consistentes de acordo com a Bíblia de Estilo.
- Equacione a duração do texto às necessidades de leitura.
12. Implementação do encerramento
Implemente o logotipo de encerramento + CTA de acordo com a planilha beyond-video. O logotipo deve vir de um asset oficial ou de um placeholder aprovado. Cópia, tempo, motivo e composição devem parecer feitos para o vídeo em questão.
13. QA antes da entrega
Verifique ID da composição, metadados, intervalos de frame, imports, tipos, assets estáticos, fontes, consistência de estilo, área segura, encerramento e licenças de assets. Execute os lint/typecheck/testes disponíveis. Não renderize MP4. Não faça commit/push.
Formato de saída
- Registro de composição: ID, 1080×1920, 60 FPS, durationInFrames, lista de cenas + intervalos de frame.
- APIs usadas: nome da API + assinatura relevante + onde foi verificada (versão instalada do Remotion).
- Padrão de roteamento de frame: global ou Series — uma escolha, consistente em toda a composição.
- Registro de assets: arquivo,
staticFile, fallback/onErrorpor asset crítico. - Checklist de QA + resultados de typecheck/lint.
Mini exemplo
Roteador de frame global (padrão do projeto de vídeo):
const frame = useCurrentFrame();
const beat = BEATS.find((b) => frame >= b.start && frame < b.end);
return (
<AbsoluteFill>
{beat?.id === 'S01-B01' && <Hook />}
{beat?.id === 'S01-B02' && <Problem />}
</AbsoluteFill>
);
Mola com duração medida:
const settle = measureSpring({fps, config: {damping: 12}});
const progress = spring({frame, fps, config: {damping: 12}});
Modos de falha
- Um componente dentro de
Series.Sequencecalcula o frame global → beat errado, cenas aparecem no momento errado. Correção: calcule a partir do frame local, ou mude para um roteador de frame global. Series.Sequenceusado sem<Series>→ lança erro ao renderizar. Envolva-o em<Series>, ou use<Sequence>diretamente (nãoSeries.Sequence).springcomdamping <= 0→ a animação nunca estabiliza. Mantenhadamping > 0.- Imagem ausente sem
onError→ a renderização é cancelada. AdicioneonErrorou garanta que o asset exista antes de renderizar. useCurrentFrame()/useVideoConfig()fora de uma composição → lança erro. Chame-os apenas dentro de componentes de composição.