vikramdevesh/3d-ani-lcs

Vídeo com código e 3D (vídeos e Shorts)

Cada quadro é uma função pura do tempo, escrita como HTML/CSS/three.js. A mesma página é o editor ao vivo (toca instantaneamente, nada é salvo) e a fonte de renderização (Chromium captura quadro a quadro, ffmpeg une). O usuário é o diretor; você faz o trabalho. Nada é renderizado até que eles tenham assistido à versão ao vivo.

O fluxo de trabalho tem sete etapas. Faça-as em ordem e não pule a etapa 5.

#	Etapa	O que você produz
1	Configuração	pasta do projeto copiada de template/, servidor rodando
2	Roteiro	script.md, depois um plano de planos: uma frase = um plano
3	Voz	voiceover.mp3 + tempos das palavras, ou tempos estimados se a voz vier depois
4	Estilo	a aparência escrita como números em STYLE.md e construída no mundo 3D
5	Correção	revisão no editor ao vivo, anotações aplicadas, erros repetidos adicionados a references/lessons.md
6	Renderização	renderização em blocos, unida com áudio
7	Upload	opções de título, descrição, capítulos, sugestão de thumbnail

1. Configuração

• As ferramentas ficam em ~/.youtube-video-editor/venv (Playwright Chromium, imageio-ffmpeg, pillow, faster-whisper). Se estiver faltando, execute ~/.claude/skills/youtube-video-editor/scripts/setup.sh. Sempre chame como ~/.youtube-video-editor/venv/bin/python -I. Não há ffmpeg ou node no sistema do usuário (Mac).
• Copie template/ para <projeto>/ dentro de uma pasta que o usuário possa ver (normalmente trabalham em ~/Downloads). Vídeo 16:9 → index.html + scenes.js. Short vertical → short.html + scenes-short.js (stage 1080×1920).
• Sirva-o: python3 -m http.server 8766 --bind 127.0.0.1 a partir da pasta do projeto (execute com nohup … &), depois abra http://localhost:8766/index.html no painel do Navegador. Uma página file:// aparece como uma foto morta, e preview_start com um launch.json não iniciou o servidor neste Mac, então inicie-o do Bash.

2. Roteiro

• O roteiro decide o vídeo. Escreva-o na voz do usuário: frases curtas e faladas, palavras simples, sem tom de livro didático. O público deles são iniciantes não técnicos (Low Code Studio). ~150 palavras por minuto; um Short tem 60–110 palavras.
• Depois planeje os planos antes de animar: uma frase = uma cena, e para cada uma uma linha dizendo o que a câmera vê. Mudar um plano é grátis, mudar uma animação não é.
• Inspirado por outro vídeo? Mantenha a estrutura e a lição, mude todos os exemplos, elementos visuais e falas. Nunca reutilize as filmagens, palavras, thumbnails ou personagens deles.

3. Voz

• O usuário grava a própria voz (é parte da marca) e adiciona um headshot depois. Portanto, a primeira passagem não tem áudio: a duração de cada cena é estimada a partir da contagem de palavras do seu vo (WPS/PAD no engine.js).
• Quando voiceover.mp3 existir: converta para wav mono 16 kHz, execute ~/.claude/skills/youtube-video-editor/scripts/transcribe.py para os tempos das palavras, defina o dur de cada cena como o intervalo entre sua primeira palavra e a primeira palavra da próxima cena, e ajuste os valores data-in para as palavras-chave. Os tempos dentro da cena se esticam automaticamente com a duração da cena (ritmo escrito → ritmo real), então a maioria das cenas precisa apenas de dur. Passe --audio voiceover.mp3 na renderização.
• Neste Mac i3, o whisper small pode ficar lento quando a máquina está ocupada. base, beam_size=1, sem timestamps de palavras é cerca de 5× mais rápido e serve para ler uma referência; use small + timestamps de palavras apenas para a sincronia final.

4. Estilo: números, não adjetivos

"Cinematográfico" não significa nada; cada cena adivinharia diferente. Escreva STYLE.md no projeto com regras que você possa verificar, depois construa-as no mundo uma vez. Comece de references/style-rules.md (o visual 3D padrão: ângulos de câmera, lente, valores de iluminação, paleta, movimento, legendas). Se o usuário fornecer imagens de referência, leia-as e transforme o que você vê nesses mesmos números. Referências próprias deles, não uma cópia do vídeo de outro criador.

Motion graphics 2D custam muito menos tokens e quebram menos que 3D. Use 3D para planos onde espaço, escala ou uma jornada importam (o gancho, os planos de "mundo") e cartões 2D para prompts, listas, comparações e cartões de capítulo. Uma boa média é aproximadamente um plano 3D a cada três ou quatro cenas. Um Short pode ser 3D do início ao fim porque são apenas poucos planos.

5. Correção: o editor ao vivo (nunca pule)

• Abra o editor para o usuário e pare por aí. Eles pediram isso explicitamente: revisão no editor ao vivo antes de qualquer renderização completa. O painel lateral mostra a narração de cada cena, permite alterar sua duração (±0,5 s) e escrever uma nota; Copiar minhas notas de revisão coloca tudo na área de transferência para eles colarem de volta para você.
• Antes de entregar, verifique seu próprio trabalho: render.py --sheet sheet.jpg dá um quadro por cena. Olhe para ele (divida uma folha alta em 3 recortes para que fique legível), corrija o que está errado, repita. Falhas comuns da primeira passagem estão em references/lessons.md. Leia esse arquivo antes de construir.
• Quando a mesma nota aparecer em mais de uma cena, corrija o vídeo e adicione uma linha a references/lessons.md, para que o próximo vídeo comece com ela resolvida. Este é o objetivo principal da skill.

6. Renderização

• Somente após o usuário aprovar a versão ao vivo. render.py --chunks out/chunks --chunk-len 60 depois render.py --join out/chunks final.mp4 [--audio voiceover.mp3]. Para Shorts adicione --size 1080x1920 e a URL short.html?render. Uma cena errada depois → exclua esse chunk_NNN.mp4 e execute novamente; apenas ele é re-renderizado.
• Velocidade no i3 (medida): cerca de 1 s por quadro para uma cena 3D em tela cheia a 1080p, porque o WebGL headless roda em software. Um vídeo de 10 minutos a 30 fps são 18.000 quadros, então planeje de 3 a 5 horas e avise o usuário antes de começar. Use --fps 24 se o usuário concordar, execute com nohup em segundo plano, mantenha o Mac acordado (request_keep_awake) e renderize no máximo dois processos de chunk por vez (divida o intervalo com --start/--end em pastas diferentes).
• Chromium headless precisa de --use-angle=swiftshader --enable-unsafe-swiftshader para WebGL (já está no render.py).
• Re-corte sem reconstruir: as cenas são um array, então reordenar ou descartar cenas é uma lista de edição. Se a abertura estiver lenta, mova o plano mais forte para o índice 0.

7. Upload

Você conhece o roteiro, então escreva 5 opções de título (recomende uma), uma descrição, capítulos a partir dos tempos iniciais das cenas e tags. Siga ~/.claude/skills/youtube-video-editor/references/youtube-metadata.md. A thumbnail é o único lugar onde um modelo de imagem ajuda: renderize um still forte (render.py --stills), escreva o prompt e deixe que o usuário o gere ou componha. Todas as afirmações na thumbnail devem ser verdadeiras para o vídeo.

Formato da cena (engine.js)

SCENES.push({
  id: 'esteira', chapter: '2 · Roteiro', title: 'Caixa na esteira',   // mostrado no editor
  vo: `Sua caixa viaja em uma esteira.`,                                // fala; define o comprimento até o áudio existir
  dur: 4,                                                              // duração fixa opcional em segundos
  cls: 'z',                                                            // opcional: plain | grad | paper | z | z1 (scale-up)
  html: `<div class="three abs" style="inset:0"></div>
         <div class="h1" data-in="0.4" data-a="pop">Olá</div>`,
  tick: (t, root) => K.draw3d(root.querySelector('.three'), 1920, 1080, t, 'esteira'),
});

• Declarativo: data-in / data-out (segundos), data-a (up down left right pop fade drop zoom), data-d, data-type (máquina de escrever), data-count="0,2400000", data-w="0,80" (largura %), data-draw (traço SVG).
• tick(t) é para qualquer coisa personalizada. Deve depender apenas de t: sem Date.now(), sem Math.random() (use E.rnd(i)), sem animações ou transições CSS. Caso contrário, a renderização não corresponderá à prévia.
• Kit: K.chat() caixa de prompt estilo Claude, K.track() rastreador de etapas, K.chapter() cartão de capítulo com sangria total, K.wave() + K.waveTick(), K.draw3d(holder, w, h, t, mode) para uma vista 3D, K.snap(canvas, t, mode) para mostrar várias vistas de câmera em uma cena (um renderizador WebGL compartilhado; nunca crie um renderizador por cena).
• O mundo 3D é K.world() no kit.js: construído uma vez, update(t, mode) move objetos e posiciona a câmera. Para um novo filme, substitua os objetos e modos de câmera lá; mantenha o padrão. examples/workflow-video/ é um vídeo completo de 10 minutos (45 cenas) feito com esta skill. Leia-o para padrões antes de escrever novas cenas.

Duas aparências: diorama de brinquedo e mundos narrativos

• kit.js K.world() é o diorama simples com sombra plana (rápido de construir, bom para explicadores e fundos).
• template/worlds.js é a aparência narrativa mais rica que o usuário preferiu depois de chamar o diorama de "não muito realista": personagens suaves tipo brinquedo (person() com cabeça, braços, pernas animáveis, mais walk()), uma cúpula de céu gradiente, mapeamento de tom fílmico ACES, um sol baixo e quente mais luzes internas quentes, sprites de brilho aditivos para lâmpadas, vapor e feixes, janelas com textura de tela, neblina para profundidade. Três mundos de 6 segundos completos estão nele (barraca de chá ao amanhecer, entregador noturno, faroleiro); examples/story-samples/ mostra como colocá-los em uma página. Carregue worlds.js após kit.js e desenhe com K.drawStory(holder, w, h, t, nome).
• Código 3D não pode ser fotorrealista. Se o usuário pedir "ultra realista", diga isso claramente e ofereça a escolha: vídeo de IA (custa créditos, e o vídeo não pode mais afirmar "todo código") ou a aparência narrativa. Depois dê 2-3 pequenos clipes de amostra para escolher antes de construir o filme inteiro em uma única aparência.
• Dê a cada plano narrativo um personagem fazendo algo com um início e um fim dentro do plano (entra, para, acena; levanta uma lanterna), uma etiqueta de nome e uma fonte de luz em movimento. É isso que é lido como "uma história".

Checklist de Shorts

1080×1920, 20–45 s, uma ideia. Gancho visível e falado em até 2 segundos, começando em movimento. Legendas de 2–5 palavras sobre uma pílula escura (texto diretamente sobre um céu 3D brilhante é ilegível), dentro da área segura: nada importante nos 220 px superiores ou 420 px inferiores. Use modos de câmera mais fechados (belt, follow, hero) porque planos abertos ficam minúsculos na vertical. Termine com a recompensa mais uma linha pedindo um follow; corte qualquer encerramento.

Arquivos empacotados

• template/: index.html, short.html, engine.js, kit.js, worlds.js, style.css, render.py, cenas iniciais, lib/three.min.js
• examples/story-samples/: a página com os três clipes de amostra dos personagens
• examples/workflow-video/: a construção completa "Como uso Claude Code para vídeo" (scenes-1/2/3.js + index.html); copie-os ao lado dos arquivos do template para executá-lo (as thumbnails em seu 0:21 não estão incluídas)
• references/style-rules.md: a aparência 3D padrão em números
• references/lessons.md: erros já pagos (leia antes de construir, acrescente após cada revisão)