Remotion CLI
A ferramenta é remotion, do pacote @remotion/cli. Cada comando é executado através de npx remotion <comando>, e todos eles empacotam o projeto primeiro, para que um erro de tipo ou uma importação ruim apareça como uma falha de empacotamento, e não como uma falha de renderização.
npx remotion --help e npx remotion <comando> --help são a autoridade máxima sobre flags. As flags mudam entre versões; leia a saída de ajuda em vez de confiar em uma lista, inclusive esta. O que está abaixo é o ciclo e os modos de falha, não uma referência de flags.
O ciclo
| Etapa | Comando | Por quê |
|---|---|---|
| Scaffold | npx create-video@latest --blank | escreve um package.json, remotion.config.ts, tsconfig compatíveis |
| Verificar tipos | npx tsc --noEmit | a verificação mais barata; captura drift de esquema/prop antes da render |
| Listar | npx remotion compositions | confirme que o id que você está prestes a renderizar realmente existe |
| Sondar um frame | npx remotion still <id> out/probe.png --frame=<n> | segundos, não minutos; o cavalo de batalha da iteração |
| Revisar | npx remotion studio | entregue ao usuário; ele navega e edita props por conta própria |
| Renderizar | npx remotion render <id> out/video.mp4 | somente após a aprovação do usuário |
| Enviar remoto | npx remotion bundle → npx remotion lambda render <url> <id> | renderização distribuída; precisa de infraestrutura AWS implantada |
Sondar stills antes de renderizar
Uma renderização completa de uma composição de 45 segundos em 1080p leva minutos. Um still leva segundos e responde à maioria das perguntas: o texto está dentro do quadro, o asset carregou, a cor está certa. Sondar o ponto médio de cada cena, olhar para cada imagem, e só então renderizar.
npx remotion still launch out/s1.png --frame=45
npx remotion still launch out/s2.png --frame=180
Nunca relate que uma composição está funcionando com base em um empacotamento bem-sucedido. Olhe para os pixels.
O Studio é a superfície de revisão, não seu depurador
npx remotion studio serve o projeto com uma linha do tempo, um editor de props orientado pelo esquema Zod e navegação quadro a quadro precisa. Entregue ao usuário para aprovação. Para sua própria verificação, prefira as sondagens com still: elas são programáveis e você pode olhar a saída sem pedir ao usuário para descrever o que vê.
Passando props
--props aceita uma string JSON ou um caminho para um arquivo JSON e substitui defaultProps:
npx remotion render launch out/video.mp4 --props='{"productName":"Acme"}'
Uma prop que falha no esquema Zod da composição falha a renderização de forma ruidosa. Esse é o objetivo de declarar o esquema, então mantenha-o preciso.
Renderização em lote
Não há subcomando de lote. Faça um loop no shell sobre ids ou cargas de props:
for id in $(npx remotion compositions --quiet); do
npx remotion render "$id" "out/$id.mp4"
done
Para muitas renderizações de uma composição sobre um conjunto de dados, prefira renderMedia() do pacote @remotion/renderer em um script Node: ele empacota uma vez em vez de uma vez por renderização, o que domina o tempo real.
Performance de renderização
--concurrency=<n>define o número de workers paralelos. O padrão é metade dos núcleos da CPU, limitado a 8; o máximo é o número de núcleos, e pedir mais é um erro, não um ajuste. Em uma máquina com pouca memória, reduzi-lo corrige travamentos que parecem bugs do renderizador.--jpeg(em vez do formato de quadro PNG padrão) é uma grande aceleração quando a composição não tem transparência para preservar.npx remotion benchmarkmede uma renderização real, então use-o para justificar uma mudança de concorrência ou codec em vez de adivinhar.npx remotion gpuinforma o que o navegador realmente irá acelerar. Vale a pena verificar antes de culpar um shader ou um filtro pesado por uma renderização lenta.
Diagnosticando falhas
| Sintoma | Causa provável |
|---|---|
| Empacotamento falha | Um erro de tipo ou uma importação ruim. Execute npx tsc --noEmit para a versão legível do mesmo erro. |
| "Nenhuma composição com id …" | O id em Root.tsx difere daquele que você passou. npx remotion compositions resolve. |
| Renderização trava e depois expira | Um delayRender() sem um continueRender() correspondente. Cada handle de atraso deve ser liberado. |
| Todo quadro parece o quadro 0 | Uma animação/transição CSS, ou requestAnimationFrame. O renderizador não avança o relógio do navegador. |
| Animação pisca ou tremula quadro a quadro | Math.random() sem semente. Use random(seed). |
| Movimento funciona ao avançar, mas quebra em um salto | Animação orientada por estado. Derive de useCurrentFrame(). |
| Asset 404 apenas em Lambda ou renderização empacotada | Um caminho fixo em vez de staticFile(). |
| Erro de versões sem sentido | Pacotes Remotion incompatíveis. npx remotion versions relata a divergência. |
| Falta de memória durante a renderização | Concorrência muito alta para a máquina. Reduza --concurrency. |
Mostre a saída de erro real ao relatar uma falha. Não parafraseie um stack trace.
Para onde foram as capacidades do antigo CLI HyperFrames
O antigo CLI hyperframes agrupava comandos de autoria, mídia e controle de qualidade que o CLI do Remotion não possui. Nada abaixo é um comando do Remotion, então não tente executá-los:
| Comando retirado | Onde a capacidade está agora |
|---|---|
init | npx create-video@latest --blank, depois /hyperframes-core → references/project-structure.md |
lint, check, layout, validate | npx tsc --noEmit mais sondagens still. O contrato data-* que essas verificações impunham não existe mais. |
snapshot, compare, grade-compare | npx remotion still nos quadros escolhidos; compare os PNGs com suas próprias ferramentas. |
preview, play, present | npx remotion studio |
add, catalog | /hyperframes-registry |
capture | /product-launch-video (captura de site) e /media-use |
tts, transcribe, remove-background | /media-use |
beats, keyframes | /hyperframes-creative (planejamento de batidas), /hyperframes-keyframes |
cloud, publish | npx remotion bundle + remotion lambda / remotion cloudrun, ou sua própria hospedagem |
skills, docs, upgrade, doctor | estas skills são fornecidas neste repositório; npx remotion upgrade e npx remotion versions |
Se um arquivo de skill ou referência de workflow ainda instruir você a executar npx hyperframes <qualquer-coisa>, essa instrução está desatualizada. Faça o equivalente no Remotion da tabela acima e diga em seu resumo que encontrou um ponteiro desatualizado, para que possa ser corrigido.