Modelos (Templates)
Um modelo é um design reutilizável. Ele lê props de cena e tokens resolvidos, e nada mais. Leia motion-style antes de escolher temporizações ou easing. Para detalhes da API Remotion, use as skills do Remotion se instaladas (npx remotion skills add) ou https://www.remotion.dev/docs.
Onde colocar
- Específico do cliente: comece com
pnpm mg new-template <cliente> <nome>. Ele cria um starter funcional emclients/<cliente>/templates/<nome>/index.tsx(id<cliente>/<nome>) que segue o contrato abaixo; substitua seu design. - Casa (todos os clientes):
templates/<nome>/index.tsxno repositório motion-toolkit, registrado emtemplates/index.ts, liberado com uma nova versão do toolkit. Não escreva emnode_modules.
Antes de escrever código de animação, proponha o esquema (as props que o usuário poderá alterar sem um agente) e confirme com o usuário.
Contrato
import { interpolate, useCurrentFrame } from "remotion";
import { z } from "zod";
import { color, defineTemplate, font, motion, px, safeArea } from "motion-toolkit/engine";
const schema = z.object({
headline: z.string().min(1).default("Headline"),
holdSeconds: z.number().positive().default(3),
accent: z.string().default("accent").describe("Nome do token de cor ou #hex"),
});
export const template = defineTemplate({
title: "Cartão de título",
schema,
durationSeconds: ({ props, tokens }) => {
const m = motion(tokens, 1);
return m.seconds("enter") + props.holdSeconds + m.seconds("exit");
},
check: ({ props, tokens }) => {
color(tokens, props.accent); // lança erro em nomes de token desconhecidos; é executado em `mg check`
},
component: ({ props, tokens, video }) => {
const frame = useCurrentFrame();
const m = motion(tokens, video.fps);
// ...
},
});
Requisitos:
- Exporte
template(modelos de cliente) construído comdefineTemplate. - Todo campo do esquema deve ter um
.default()para que novas cenas e o Studio iniciem válidos. Adicione.describe()para o formulário do Studio. - Cores através de
color(tokens, nomeOuHex), fontes através defont(tokens, papel), durações e easing através demotion(tokens, fps), posições dentro desafeArea(tokens, video), tamanhos através depx(tamanhoEm1080, video). - Anime apenas a partir de
useCurrentFrame()cominterpolate/spring. Sem transições CSS,setTimeout,Date.now()ouMath.random()(userandom(semente)do remotion). As renderizações devem ser idênticas a cada execução. - Deixe o fundo transparente a menos que o modelo seja em tela cheia; barras inferiores e sobreposições renderizam com alpha. Todo elemento deve desaparecer no último quadro.
- Falhe ruidosamente: lance um
Errorcom uma dica de correção quando o texto não couber ou algum token estiver ausente. UseassertFits/wrapLinesdo motor; eles medem com a fonte carregada e lançam erro em estouro. - Props que nomeiam tokens (cores, logotipos, fontes, sons) são validadas em
checkcomcheckRefs, para quemg checkpegue erros de digitação antes de renderizar. durationSecondsechecksão executados no Node (mg check) e antes das fontes carregarem: nunca meça texto lá.- Imagens e logotipos:
<Img src={staticFile(tokens.logos[nome])} />oustaticFile(props.algumAsset). Sons:<Html5Audio src={staticFile(arquivo)} />dentro de<Sequence from={frame}>, arquivos detokens.sounds[nome]. O CLI prepara os arquivos.
Aparências (Looks)
Modelos da casa, e modelos de cliente que devem combiná-los, recebem look: lookSchema e o resolvem com resolveLook(props.look, tokens). Construa-os a partir dos helpers compartilhados para que todas as três aparências permaneçam consistentes (veja motion-style):
choreo(tokens, look, fps)fornecebeat(frame, index, exitStart, steps)→{ inP, outP }para cada elemento na ordem de entrada;choreoSeconds(...)fornece a duração correspondente.reveal(look, beat, video)é o estilo de entrada da aparência para um elemento (envolva emoverflow: hiddenparacorporate).typo(tokens, look, "display" | "title" | "body" | "label", tamanho)é o estilo tipográfico da aparência;onColor(hex)escolhe texto legível sobre um bloco de cor;cornerPlacement(canto, margem)posiciona gráficos de canto.
Leia um modelo da casa como node_modules/motion-toolkit/templates/title-card/index.tsx como exemplo prático.
Verificar
pnpm mg new-shot <cliente>/<projeto> <cena> --template <cliente>/<nome>em um projeto de teste, mais uma segunda cena com o texto realista mais longo.pnpm mg check <cliente>/<projeto>.pnpm mg still <cliente>/<projeto> <cena>e olhe os quadros. Depoispnpm mg render.- Siga
motion-qa.
Trabalhando a partir de um clipe de referência
Quando o usuário fornecer um vídeo de referência, extraia quadros antes de projetar. Crie renders/reference/ primeiro; o ffmpeg incluído é uma build mínima sem filtros, então use -r para a taxa de quadros:
pnpm mg ffmpeg -i reference.mp4 -r 10 renders/reference/f_%03d.png
Descreva a partir dos quadros o que se move, em qual ordem, quanto tempo cada fase leva (conte quadros a 10 fps) e a sensação do easing. Confirme essa análise com o usuário, então mapeie para tokens: durações para motion.durations, curvas para motion.easings.