cinematic-3d-video

Vídeo Cinematográfico 3D

O Claude não pode gerar pixels de vídeo diretamente, mas pode escrever uma cena 3D como código, renderizá-la um quadro de cada vez e codificar os quadros. Esta habilidade é essa pipeline.

cena (HTML + Three.js)  -- window.seek(t) -->  scripts/render.mjs  -->  screenshots do Chrome headless  -->  ffmpeg  -->  MP4

render.mjs avança um relógio virtual em vez de gravar em tempo real. O resultado é o mesmo em qualquer máquina, e uma cena pesada não gagueja; apenas renderiza mais lentamente. É por isso que uma cena deve ser uma função pura do tempo (veja "Regras da cena").

1. Verifique as ferramentas primeiro

node -v        # 22 ou mais novo (render.mjs usa o WebSocket nativo)
ffmpeg -version

Chrome, Edge ou Chromium devem estar instalados (encontrados automaticamente; defina CHROME_PATH para substituir). Three.js é carregado de um CDN pela cena, então a máquina que renderiza precisa de acesso à internet, a menos que Three.js seja fornecido localmente (veja references/troubleshooting.md). Se alguma ferramenta estiver faltando, diga exatamente ao usuário o que instalar e pare de adivinhar soluções alternativas. Blender é necessário apenas para o caminho fotorrealista.

Execute o teste de fumaça sem dependências uma vez quando uma máquina for nova. Ele prova que Chrome, WebGL e ffmpeg funcionam, então qualquer problema posterior está na cena e não na configuração:

node <skill-dir>/scripts/render.mjs <skill-dir>/templates/smoke-test.html --out smoke.mp4 --duration 2 --width 640 --height 360

2. Fluxo de trabalho

1. Defina o briefing em uma ou duas frases: assunto, clima, duração, proporção, qualquer texto, áudio. Quando o usuário deixar questões em aberto, escolha padrões e diga o que escolheu: 1920x1080, 30 fps, 8-12 s, fundo escuro, um objeto principal, um movimento de câmera, um título. Vertical (TikTok/Reels/Shorts) é 1080x1920. Fazer mais de uma pergunta curta antes de começar raramente vale a pena; um primeiro render é a melhor pergunta.
2. Comece pelo starter. Copie templates/starter/ para o diretório de trabalho (cp -r) e edite index.html. Ele já possui o renderizador, mapeamento de tom, reflexos de estúdio, bloom, sombras, partículas semeadas, um caminho de câmera, uma sobreposição de título em HTML e o gancho da linha do tempo. Substitua o objeto principal, paleta, caminho de câmera e texto; mantenha a estrutura.
3. Veja stills antes de renderizar o vídeo. Renderize um punhado de quadros no tamanho máximo nos momentos mais movimentados e abra-os (Leia os PNGs):

   node <skill-dir>/scripts/render.mjs my-video/index.html --stills 0,2,4,6,7.5 --out my-video/stills
   

   Corrija composição, exposição, cor e legibilidade do texto aqui. Um still leva um ou dois segundos; um render completo leva minutos.
4. Renderize uma vez. Escolha as configurações e renderize o vídeo inteiro:

   node <skill-dir>/scripts/render.mjs my-video/index.html --out my-video/video.mp4 --width 1920 --height 1080 --fps 30 --scale 2
   

   --scale 2 renderiza em 2x e reduz a amostragem, o que remove bordas cintilantes (vale a pena apenas para o render final). Renders longos devem ficar em segundo plano com progresso verificado, para que o usuário nunca fique olhando para um terminal silencioso.
5. Verifique o arquivo, não o log. ffprobe para duração, tamanho e fps; extraia dois ou três quadros do MP4 (ffmpeg -ss 3 -i video.mp4 -frames:v 1 check.png) e olhe para eles. Em seguida, entregue o MP4 junto com a pasta da cena para que o usuário possa ajustá-la.
6. Revisões alteram a cena e re-renderizam. Use --start/--end para re-renderizar apenas um intervalo enquanto itera em um momento.

3. Regras da cena (e por quê)

• Tudo animado é uma função pura de t segundos, definida dentro de update(t). Sem Math.random() (use o rng() com semente), sem Date.now(), sem clock.getDelta(), sem estado acumulado entre quadros. O renderizador pode chamar seek com qualquer tempo em qualquer ordem, e uma prévia no navegador deve corresponder exatamente ao vídeo.
• O contrato da página é window.seek(t) (desenhar síncrono), window.__duration (segundos) e window.__ready = true assim que os ativos forem carregados. installTimeline() em lib/stage.js faz todos os três. Detalhes em references/contract.md.
• Cores HDR acima de 1.0 fazem as coisas brilharem. O bloom só capta pixels mais brilhantes que seu limiar, então partes emissivas usam new THREE.Color(hex).multiplyScalar(3..6); superfícies comuns permanecem abaixo do limiar.
• Texto é HTML/CSS sobre o canvas (a captura de tela inclui a página). Ele é nítido em qualquer resolução, não precisa de arquivos de fonte e anima com mudanças simples de estilo dentro de update(t).
• Carregue ativos com await antes de definir __ready (modelos GLTF, texturas, fontes). Um quadro renderizado antes da chegada de um ativo é uma falha permanente no vídeo.
• Mantenha uma história de luz: uma luz principal, uma ou duas luzes de borda coloridas e reflexões baseadas em imagem. Materiais reflexivos (metal, vidro, verniz) em um piso escuro e levemente reflexivo são o que se lê como "animação 3D" em vez de "demo web". references/cinematography.md tem as receitas para movimentos de câmera, ritmo, easing, iluminação e cor.

4. Várias cenas, áudio, outros formatos

• Vídeos com várias cenas: renderize cada cena em seu próprio MP4 com tamanho, fps e configurações de codificador idênticos, depois junte sem recodificar: escreva um list.txt com linhas file 'a.mp4' e execute ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4. Coloque crossfades dentro da própria linha do tempo de uma cena (o último segundo de uma cena e o primeiro segundo da próxima ambos desaparecem através de preto/cor) em vez de misturar arquivos finalizados, o que codificaria tudo duas vezes.
• Áudio: --audio track.mp3 multiplexa e corta para o vídeo. Para alterar apenas o som depois: ffmpeg -i video.mp4 -i new.mp3 -map 0:v -map 1:a -c:v copy -shortest out.mp4.
• GIF / WebM / cópia menor: recodifique o MP4 finalizado com ffmpeg; nunca re-renderize para uma mudança de formato.
• Alterar uma cena significa re-renderizar o arquivo dessa cena (e o próximo apenas se um crossfade estiver nele).

5. Quando usar Blender em vez disso

Use Blender (references/blender.md, templates/blender/render_blender.py) apenas quando o briefing precisar do que um motor em tempo real não consegue simular bem: vidro com traçado de raios e causticas, luz volumétrica, pele com subsuperfície, simulação de fluído/tecido/fumaça ou fotos de produtos totalmente fotorrealistas. É muito mais lento por quadro e precisa do Blender 4+ instalado; para todo o resto, Three.js chega a um bom resultado em uma fração do tempo e itera mais rápido.

Arquivos de referência

Arquivo	Leia quando
references/contract.md	escrevendo uma cena do zero, carregando modelos/texturas ou depurando "nunca definiu __ready"
references/cinematography.md	fazendo o resultado parecer bom: câmera, luz, materiais, easing, ritmo, cor, texto, partículas
references/troubleshooting.md	quadros pretos, renders lentos, configuração de CDN/sem internet, peculiaridades do Windows/macOS/Linux, tamanhos ímpares
references/blender.md	trabalho fotorrealista ou simulação
scripts/render.mjs	todas as opções: node scripts/render.mjs --help