making-promo-videos

Criando vídeos promocionais em código

Visão geral

Um filme promocional feito em código (Remotion: componentes React renderizados quadro a quadro). Ele opera com quatro princípios:

1. Um mapa de sincronia rege tudo. A imagem, a câmera, a música e os efeitos sonoros leem eventos nomeados, de modo que reajustar um reajusta todos.
2. Elenco antes do corte. O diretor ouve e vê as opções antes de o filme mudar.
3. Prévias antes dos finais.
4. Toda afirmação é verdadeira em relação ao produto.

Regras da casa primeiro: leia as regras do próprio repositório de vídeo antes de qualquer outra coisa: seu README, seu CLAUDE.md, ou um arquivo house-rules.md na raiz do repositório. Elas substituem os padrões abaixo. house-rules.example.md nesta pasta é um modelo para criar um.

Configurando um novo filme

• Um filme por branch ou worktree, em um repositório apenas de vídeo, nunca dentro do aplicativo do produto. Cada filme recebe sua própria pasta: src/videos/<nome>/.
• Copie templates/ desta skill para essa pasta:
  • sections.ts: o mapa de sincronia, HITS, TRACK_BPM
  • film-camera.tsx: a câmera 2.5D
  • shots.ts: a lista de planos
  • Film.tsx: o esqueleto da composição, com o registro Root.tsx no cabeçalho
• Copie templates/render.sh e scripts/*.py para a pasta scripts/ do repositório.
• Dependências, fixadas em uma versão exata juntas: remotion, @remotion/cli, @remotion/motion-blur. Para os scripts de áudio: ffmpeg, além de numpy e soundfile.
• Uma composição renderiza ambos os formatos a partir de uma propriedade format (horizontal 1920x1080, vertical 1080x1920). Cada formato é diagramado independentemente e nunca com letterbox.

Fluxo de trabalho

1. Especificação do storyboard (use a skill superpowers:brainstorming se estiver instalada). Escreva em docs/.../AAAA-MM-DD-<nome>-design.md. Verifique cada afirmação na tela em relação ao código do produto e flags ativas, e redija da mesma forma que o produto.
2. Quadro de elenco antes de qualquer edição do filme. Apresente vozes (com as falas lidas em voz alta), sons de digitação, várias opções de música e rascunhos de aparência ou personagens, cada um com um código (A1, B4, M1…). Renderize os rascunhos visuais como pequenas composições de quadro, publique a página de forma privada e aguarde as escolhas do diretor. Nunca escolha uma voz, faixa ou aparência silenciosamente.
3. Construção.
   • Cópia e temporização residem na configuração.
   • Cenas, planos e sons referenciam nomes de HITS, nunca números brutos.
   • Trabalho de câmera: leia camera.md.
4. Prévia em 720p (scripts/render.sh <Comp> <formato> preview <nome>-preview-vN-720p). Relate o que você verificou, o que não pôde testar e qualquer coisa que tenha alterado além da solicitação.
5. Finais somente após aprovação: tamanho completo, ambos os formatos. Renders longos morrem se a máquina dormir, então verifique a energia primeiro.
6. Commit no branch do filme. Faça merge ou push apenas quando solicitado. Filmes anteriores devem manter os renders inalterados.

Regras de áudio

Regra	Motivo
Renderize a imagem sem áudio, depois um WAV separado com --codec=wav, e então scripts/mux.py (-15 LUFS com um limitador).	O AAC integrado do Remotion coloca toda a trilha sonora 43 ms atrasada.
A música é licenciada comercialmente ou gerada, e cada arquivo é registrado em um CREDITS.md.	Alguns pacotes de SFX "gratuitos" não são licenciados para uso comercial.
Para ajustar uma faixa escolhida: scripts/beatgrid.py track [compassos] [arco] fornece o BPM e o tempo forte. Defina TRACK_BPM, então corte a faixa com music-edit.py (compassos inteiros, com crossfade no tempo forte) ou fit-track.py (uma janela reta).	O filme se reajusta à faixa, não o contrário.
Vozes vêm apenas de um TTS com licença comercial (Kokoro-82M é Apache-2.0). Nunca use o say do macOS.	A licença do say é pessoal e não comercial.
SFX são gerados deterministicamente. Adicione cada novo som ao final com seu próprio PRNG.	Caso contrário, cada arquivo posterior muda.
Nunca chame Math.random() em um render. Use hash() de film-camera.tsx.	Um quadro deve renderizar igual a cada vez.

QA antes de entregar qualquer coisa

• Verificação de tipos.
• Loudness em cerca de -15 LUFS e pico verdadeiro abaixo de -1 dBTP (ffmpeg -af ebur128). O pico do WAV bruto permanece abaixo de 0,99, para que nada sature.
• SFX acertam seus quadros de evento.
• Qualquer QR code decodifica tanto em 1080p quanto em 720p.
• Renderize stills de cada seção alterada em ambos os formatos (Remotion renderStill) e olhe para eles você mesmo. Agentes de revisão perdem bordas cortadas, e uma revisão por um modelo pequeno e rápido não é uma revisão oficial.

Erros comuns

Erro	Correção
Movimento vinculado a um quadro, batida ou segundo bruto	Adicione um evento nomeado em sections.ts e referencie-o.
Uma rotação ou inclinação de câmera vazando para planos posteriores	As chaves persistem, então redefina o campo (roll: 0).
Finais renderizados antes da aprovação	Envie uma prévia em 720p primeiro.
Uma voz, faixa ou aparência que o diretor nunca ouviu ou viu	Coloque no quadro de elenco primeiro.
Um mp4 de passagem única com áudio	Imagem sem áudio, depois WAV, depois mux.
Trabalho temporário em /tmp para um filme de vários dias	O sistema o limpa. Use uma pasta de worktree real.
One-liners de shell com $(...) ou loops recusados em modo automático	Coloque a lógica em um arquivo de script.