Prismer-AI/PrismerCloud

Remotion

Construa e mantenha projetos Remotion preservando as alterações do usuário. Se um arquivo mudou inesperadamente, trate como intencional a menos que o usuário confirme o contrário.

Fluxo de Trabalho

1. Inspecione package.json, o arquivo de bloqueio, as composições existentes, o diff atual e npx remotion versions. Reutilize o gerenciador de pacotes e a estrutura do projeto; mantenha todos os pacotes remotion / @remotion/* em uma versão exata.
2. Confirme a saída solicitada: alterações de composição/fonte, preview no Studio, mídia renderizada, um Player incorporado ou um serviço de renderização.
3. Implemente visuais determinísticos e orientados por quadro e mantenha as entradas de renderização serializáveis.
4. Preview no Studio. Renderize apenas quando o usuário solicitar um arquivo de mídia.
5. Verifique a mídia renderizada com ffprobe e inspecione quadros representativos.
6. Relate arquivos alterados, evidências de preview/renderização e o recibo de entrega. No Prismer, um caminho de sandbox solto não é um resultado entregue.

Contrato de artefato e entrega do Prismer

Quando o usuário solicitar mídia renderizada, escreva o arquivo final sob $PRISMER_ARTIFACTS_DIR (o <artifacts_dir> do despacho). Coloque scaffolds de projeto, quadros, sondagens e outros intermediários sob $PRISMER_SCRATCH_DIR ou a árvore do projeto existente. Em seguida, entregue cada arquivo final solicitado exatamente uma vez:

cloud deliver "$PRISMER_ARTIFACTS_DIR/launch-video.mp4"

Escrever ou renderizar um arquivo não o anexa. Um recibo bem-sucedido de cloud deliver é o oráculo de entrega. Não entregue quadros de preview, áudio temporário ou codificações duplicadas a menos que o usuário os tenha solicitado. Se nenhum diretório de artefato de despacho existir, mantenha o resultado no caminho de saída do projeto aprovado pelo usuário e relate que a entrega não estava disponível, em vez de inventar um recibo.

Criação de projetos e composições

Não faça scaffold sobre um projeto não vazio. Quando nenhum projeto adequado existir, confirme que Node.js e Git estão disponíveis, então execute:

npx create-video@latest --yes --blank --no-tailwind my-video
cd my-video
npm install

Use um nome de diretório significativo. Adicione Tailwind apenas quando o usuário solicitar ou o projeto já o utilizar. Inspecione o manifesto gerado, config e CSS global antes de continuar: as versões do generator ainda podem emitir dependências e importações do Tailwind mesmo quando --no-tailwind foi solicitado. Remova-as apenas quando o projeto não as usar e mantenha as versões do pacote Remotion alinhadas.

Em imagens de sandbox do Prismer, use um cache npm gravável com escopo de comando para cada comando que possa instalar ou invocar um pacote ausente, incluindo scaffolding, npm ci, remotion add, sondagens e renderizações:

npm_config_cache="${PRISMER_SCRATCH_DIR:-/tmp}/npm-cache" npm ci

Não altere a configuração global do npm do usuário para contornar uma incompatibilidade de propriedade do sandbox.

Mantenha metadados de composição estáticos inline:

<Composition
  id="LaunchVideo"
  component={LaunchVideo}
  durationInFrames={300}
  fps={30}
  width={1920}
  height={1080}
  defaultProps={{title: 'Dia do lançamento'}}
/>

Use calculateMetadata() apenas quando duração, dimensões ou props dependerem genuinamente de entradas, dados remotos ou inspeção de mídia. Mantenha defaultProps inline para que o Studio possa salvar edições de props de volta no código. Para vídeos com várias cenas, use limites nomeados de <Sequence> e derive toda a temporização de um plano ciente de fps.

Animação orientada por quadro

Dirija a animação renderizada a partir de useCurrentFrame(), interpolate(), molas ou easing. Não use transições CSS, animações CSS, temporizadores de relógio ou utilitários de animação do Tailwind; eles não são renderizações determinísticas.

import {
  AbsoluteFill,
  Easing,
  Interactive,
  interpolate,
  useCurrentFrame,
  useVideoConfig,
} from 'remotion';

export const Hero = () => {
  const frame = useCurrentFrame();
  const {fps} = useVideoConfig();

  return (
    <AbsoluteFill style={{justifyContent: 'center', alignItems: 'center'}}>
      <Interactive.Div
        name="Título do herói"
        style={{
          opacity: interpolate(frame, [0, fps], [0, 1], {
            extrapolateLeft: 'clamp',
            extrapolateRight: 'clamp',
            easing: Easing.bezier(0.16, 1, 0.3, 1),
          }),
          scale: interpolate(frame, [0, fps], [0.9, 1], {
            extrapolateLeft: 'clamp',
            extrapolateRight: 'clamp',
            easing: Easing.spring({damping: 200}),
            output: 'perceptual-scale',
          }),
          fontSize: 88,
        }}
      >
        Dia do lançamento
      </Interactive.Div>
    </AbsoluteFill>
  );
};

Prefira as propriedades CSS individuais scale, translate e rotate em vez de uma string transform composta. Prenda ambas as extremidades de animações finitas a menos que a extrapolação seja intencional.

Marcação editável no Studio

Use Interactive.* para elementos HTML e SVG que devem ser selecionáveis, arrastáveis, redimensionáveis, rotacionáveis, estilizados ou com keyframes no Studio. <Img> já é interativo.

• Dê a cada elemento interativo um nome descritivo curto e codificado.
• Mantenha texto único diretamente dentro do elemento.
• Mantenha objetos de estilo, intervalos de interpolate(), saídas, easing e extrapolação inline quando a escrita de volta no Studio for importante.
• Desestruture apenas valores suportados como fps, width, height e durationInFrames de useVideoConfig().
• Evite constantes de estilo extraídas, espalhamento de objetos, arrays de efeito computados e variáveis arbitrárias dentro de intervalos de keyframe editáveis.

Para componentes personalizados, consulte a API atual make-component-interactive na documentação oficial do Remotion antes de implementá-la.

Ativos, mídia e temporização

Coloque ativos locais em public/ e referencie-os com staticFile():

import {Audio, Video} from '@remotion/media';
import {AnimatedImage, CanvasImage, staticFile} from 'remotion';

export const MediaLayer = () => (
  <>
    <Video src={staticFile('clip.mp4')} />
    <Audio src={staticFile('music.mp3')} />
    <CanvasImage src={staticFile('logo.png')} />
    <AnimatedImage src={staticFile('sticker.gif')} />
  </>
);

Use @remotion/gif quando o caminho da imagem animada baseada em Chrome não for adequado. Instale pacotes do ecossistema com npx remotion add <package> para que as versões do pacote Remotion permaneçam alinhadas.

Prefira mídia local ou endereçada por conteúdo para renderizações de sandbox reproduzíveis. Não incorpore cookies, tokens de portador, URLs assinados ou credenciais de mapa no código-fonte ou nas props da composição. Para ativos assíncronos, fontes, legendas e tiles de mapa, emparelhe delayRender() / continueRender() com cancelRender() em caso de falha para que uma dependência ausente falhe explicitamente em vez de travar até o timeout.

Use from, durationInFrames e trimBefore em componentes suportados. Envolva componentes não suportados em <Sequence>:

<Sequence name="Demonstração do produto" from={2 * fps} durationInFrames={6 * fps}>
  <Video src={staticFile('demo.mp4')} trimBefore={1 * fps} />
</Sequence>

Corresponda a duração da mídia ao segmento utilizável pretendido. Mantenha a temporização da cena em um plano para que as transições não se sobreponham acidentalmente nem deixem quadros em branco.

Para efeitos, use a técnica menos complexa que produza o shot:

1. HTML, SVG e CSS.
2. Um efeito Remotion no elemento ou um wrapper HtmlInCanvas.
3. Um efeito personalizado ou shader apenas quando os dois primeiros não conseguirem produzi-lo.

Mantenha os arrays de efeito estáveis. Renderize elementos separados em vez de mudar condicionalmente a forma de um array de efeito.

Legendas e inspeção multimídia

Normalize legendas para a forma Caption[] do Remotion e mantenha timestamps de ingestão em milissegundos:

import type {Caption} from '@remotion/captions';

const caption: Caption = {
  text: 'Olá',
  startMs: 0,
  endMs: 800,
  timestampMs: null,
  confidence: null,
};

Converta milissegundos para quadros apenas no limite da composição usando o fps da composição. Preserve a temporização de palavras quando disponível, agrupe legendas em páginas legíveis, anime a partir do clock de quadro e verifique a quebra de linha e áreas seguras nas dimensões reais de saída.

Use o parser atual @remotion/captions para SRT em vez de escrever um parser de timestamp. Antes de implementar legendas, confirme as APIs atuais para parse-srt, createTikTokStyleCaptions e o provedor de transcrição escolhido.

Para visualização de áudio, use @remotion/media-utils com dados de áudio em janela de quadro; nunca dirija barras ou formas de onda a partir de um analisador de tempo real. Para gráficos e animação de texto, compute a geometria final primeiro e revele-a com clipping, opacidade ou transformações baseadas em quadro para que barras, rótulos e layout de glifos permaneçam estáveis.

Use Mediabunny para duração, dimensões, corte, cropping, metadados e manuseio de contêiner no lado do navegador. Leia https://mediabunny.dev/llms.txt antes de usar APIs desconhecidas. Mantenha mediabunny e @mediabunny/* compatíveis com a versão do Remotion do projeto.

Mapas

Escolha uma técnica para o shot:

Técnica	Use quando
Raster preparado	Imagens estáticas/de satélite determinísticas com sobreposições animadas são suficientes.
Mapbox	Estilos polidos, renderização de globo ou edifícios 3D são necessários.
MapLibre	Um runtime vetorial de código aberto sem uma chave de API do Mapbox é preferido.
MapTiler	Estilos hospedados ou anotações geográficas se adequam ao projeto.
CesiumJS	Terreno, 3D em escala de globo ou movimento de câmera de voo são necessários.

Nunca confirme credenciais de mapa. Confirme licenciamento e atribuição para imagens, tiles e estilos. Antes da captura de quadro, aguarde tiles, imagens, fontes e inicialização da câmera. Dirija o movimento da câmera a partir do clock de quadro do Remotion, mantenha entradas geográficas locais ou endereçadas por conteúdo quando a repetibilidade for importante e verifique Chromium/WebGL headless no ambiente de renderização real.

Studio, renderização e verificação

Inicie o Studio sem abrir um navegador externo:

npx remotion studio --no-open

Use a URL impressa. Abra uma composição diretamente em /<composition-id>, por exemplo http://localhost:3000/LaunchVideo.

Flags úteis do Studio:

Argumento	Propósito
--log=<level>	Defina error, warn, info ou verbose.
--port=<number>	Solicite uma porta específica.
--force-new	Inicie outra instância para o mesmo projeto e porta.

Para uma verificação rápida de layout determinística, renderize um quadro:

npx remotion still LaunchVideo out.png --scale=0.25 --frame=30

A 30 fps, o quadro 30 é um segundo. Pule isso quando um teste visual existente já fornecer evidências suficientes.

Antes de renderizar, verifique se a CLI vê a composição pretendida:

npx remotion versions
npx remotion compositions

Deixe o Remotion gerenciar seu navegador compatível por padrão. Uma imagem Prismer também pode carregar um navegador Playwright, mas sua presença não é uma garantia de compatibilidade: o binário completo do Chrome pode falhar sob política de crashpad do sandbox, enquanto um Headless Shell mais novo pode passar em uma renderização de still mas falhar em uma renderização de múltiplos quadros. Passe --browser-executable apenas para um executável de propriedade da imagem e emparelhado por versão que tenha passado em um teste de renderização de quadros adjacentes. Nunca pesquise em todo o sistema de arquivos por um navegador ou trate um lançamento bem-sucedido como evidência de compatibilidade.

Renderize apenas quando o usuário solicitar um arquivo de mídia:

npx remotion render LaunchVideo out.mp4 --codec=h264
npx remotion still LaunchVideo out.png --frame=0

O sandbox Prismer fornece Node e FFmpeg, e o Remotion gerencia um navegador compatível no cache do projeto. Prefira H.264 mais áudio AAC em MP4 para reprodução ampla, a menos que transparência ou saída sem perdas seja necessária. Mantenha a substituição do cache npm gravável com escopo para cada comando:

npm_config_cache=/tmp/npm-cache npx remotion render LaunchVideo out.mp4 --codec=h264

Para conteúdo CJK, carregue e aguarde explicitamente uma fonte fixada; não confie apenas na presença de uma família de fallback do sistema. Inspecione quadros codificados adjacentes, bem como stills isolados: um renderizador headless pode produzir um still correto enquanto uma fonte de fallback pisca ou perde glifos durante uma renderização completa.

Trate a inspeção de mídia como o oráculo de entrega:

ffprobe -v error \
  -show_entries format=duration:stream=codec_name,width,height \
  -of compact out.mp4

Confirme duração, dimensões, codecs e o fluxo de áudio esperado. Inspecione quadros representativos, incluindo vários quadros adjacentes em seções animadas ou com muito texto, ou reproduza o resultado quando possível. Um comando de renderização bem-sucedido sozinho não é evidência de entrega. Se stills isolados estiverem corretos, mas a renderização codificada tiver quadros parciais ou piscando, use a API programática renderStill() com uma URL de serve agrupada e uma instância de navegador para emitir a sequência de quadros verificada e, em seguida, monte-a com o FFmpeg do sandbox. Não faça loop na CLI e reagrupe uma vez por quadro; relate o fallback e sonda o arquivo montado novamente.

Players, editores e serviços de renderização

Use o <Player> do Remotion para um preview React interativo. Mantenha a composição utilizável tanto pelo Player quanto pelos caminhos de renderização; não bifurque a lógica visual.

Escolha a arquitetura de renderização pela carga de trabalho:

• Renderização no navegador/cliente para trabalho limitado e local do usuário.
• Um worker Node e fila para um servidor controlado.
• Remotion Lambda para renderização elástica nativa da AWS.
• A integração oficial atual com Vercel ou Cloudflare quando corresponder à plataforma de hospedagem e à versão instalada do Remotion.

Renderização não trivial deve ser assíncrona: retorne um ID de job, exponha progresso e falha, armazene a saída de forma durável e torne as tentativas idempotentes.

Para editores, modele props de composição e estado da timeline explicitamente. Mantenha entradas de renderização serializáveis e versionadas, valide props não confiáveis, limite o acesso a ativos remotos e separe o estado de preview do estado durável do projeto.

A superfície de renderização do Remotion é React. Para hosts Vue, Angular ou Svelte, use a integração oficial atual e mantenha o limite da composição React explícito, em vez de confiar em um starter memorizado.

Documentação atual e atualizações

Prefira a documentação oficial atual em vez de APIs memorizadas. Acrescente .md a uma URL da documentação do Remotion para buscar Markdown, por exemplo:

https://www.remotion.dev/docs/sequence.md

A pesquisa da documentação do Remotion pode

…

[truncado para tradução]