Video por Código

Habilidade de Video por Código

Um conjunto de ferramentas executável e um fluxo de trabalho de produção para equipes humano-agente criarem vídeos determinísticos em código. Todo o código de cena permanece dentro do repositório ou espaço de trabalho do projeto; toda a mídia gerada, takes de áudio, stills e recibos de verificação residem em um diretório externo explícito $PROD.

Ordem de trabalho: briefing → áudio e temporização → estilo e prompt → 3 stills de design → código da cena → portão de determinismo e limites de texto → renderização completa → verificação e folha de contato → recibo de entrega

---

1. Ambiente e Teste de Fumaça

Antes de construir um novo filme, garanta que as dependências iniciais estejam instaladas e que o teste de fumaça de 4 segundos passe a partir da raiz do repositório:

cd starter && npm ci && cd ..
node tests/runtime-contract.mjs

---

2. Diretório de Produção e Intenção (RUNBOOK.md §1–2)

1. Escolha um diretório de produção absoluto fora do checkout do código:

   PROD="/absolute/path/to/video-outputs/<project-slug>"
   mkdir -p "$PROD"/{audio,analysis,stills,renders,checks}
   

2. Copie templates/brief.md para "$PROD/brief.md" e preencha o público-alvo, mensagem principal, proporção de aspecto (1920x1080 paisagem ou 1080x1920 vertical), duração, fonte de voz/música e margens de área segura.

---

3. Identidade de Áudio e Temporização (docs/04-music-audio-and-timing.md, docs/05-narration-and-captions.md)

Nunca anime com base em carimbos de tempo adivinhados. Meça o arquivo de áudio real primeiro e registre seu hash SHA-256:

uv run tools/timing/audio-identity.py "$PROD/audio/source.wav" \
  --out "$PROD/analysis/identity.json" --copy-wav "$PROD/analysis/analysis.wav"

• Narração falada:
  • Sintetize via TTS ONNX Kokoro local (com mesclagem de fragmentos < 4 palavras e dicionário fonético --say say.json): uv run tools/timing/kokoro-narrate.py script.txt --out-dir "$PROD/audio" --voice af_heart --say say.json
  • Verifique ida e volta do áudio falado via whisper-cli local: uv run tools/verify/verify-narration.py "$PROD/audio/narration.wav" "$PROD/audio/timing.json"
  • Verifique scripts/letras para elevação de n-grama literal contra o texto de referência: python3 tools/verify/check-lift.py candidate.txt reference.txt
• Faixas reativas a música/letra/stem:
  • Separe 6 stems via Demucs (vocals, drums, bass, guitar, piano, other) e normalize para WAV 44.1 kHz: uv run --python 3.12 tools/timing/separate-stems.py "$PROD/audio/song.mp3" --out-dir "$PROD/analysis"
  • Extraia envelopes de stem de 120 Hz, tempo musical monotônico tau, fase batida/barra, silêncios, features.f32 e pitch/vibrato de guitarra a 100 fps: uv run --python 3.12 tools/timing/analyze-stems.py "$PROD/analysis" --fps 120 --stem-pitch
  • Alinhe palavras de letras em nível de palavra (whisper-cli, mlx-whisper, faster-whisper ou emaranhamento de energia de banda vocal acoustic): uv run tools/timing/align-words.py "$PROD/analysis/stems/vocals.wav" --script lyrics.txt --backend whisper-cli --out "$PROD/analysis/words.json"
  • Sinais de arquivo único leve / grade de batida / envelope de visualizador:
    • uv run tools/timing/cue-extract.py "$PROD/audio/song.mp3" --out "$PROD/analysis/cues.json"
    • uv run --python 3.12 tools/timing/beat-grid.py "$PROD/analysis/analysis.wav" --out "$PROD/analysis/beats.json"
    • python3 tools/build-visualizer.py "$PROD/analysis/analysis.wav" --out "$PROD/analysis/features.js"

---

4. Seleção de Estilo e Montagem do Prompt (prompts/README.md)

Navegue por prompts/styles/INDEX.md (86 cartões de estilo visual em 13 famílias) e prompts/briefs/ (5 briefs de formato: explainer-voiceover, vertical-short, lyric-video, instrumental-visualizer, data-story).

Monte a especificação combinada para seu estilo e brief escolhidos:

python3 tools/build-prompt.py <style-id> --brief <brief-id> --out "$PROD/style-prompt.md"

---

5. Contrato de Criação de Cena (lib/API.md, docs/06-building-scenes.md, docs/12-advanced-engines-and-benchmarks.md)

Cada página HTML de cena carrega lib/harness.js (window.H) e opcionalmente:

• lib/sound.js (window.SOUND) — síntese de áudio Web Audio procedural
• lib/features.js (window.FEATURES) — cursor binário features.f32 de stem a 120 Hz, pulso de início refratário, tau(t) monotônico e consulta de letras words.json
• lib/ink-doodle.js (window.INK) — primitivos de rabisco oscilantes com linha-fervura determinística a 8 fps, escrita marker em MAIÚSCULAS com âncora à esquerda e câmera Ken Burns plate
• lib/webgl-post.js (createPost) — pós-processamento Three.js de 4 estágios (FxOverShader, UnrealBloomPass, FinalGradeShader com ACES / paperMode, inversão de impacto apenas em luma, glitch, shake, grain e sobreposição de interface nítida)

Cada página expõe:

• <canvas id="c" width="1920" height="1080"></canvas> (ou 1080 × 1920 para vertical)
• window.DURATION (segundos) e window.FPS (padrão 30)
• window.__ready (Promise que resolve após fontes e placas offscreen em cache estarem prontas)
• window.__renderFrame = (t) => { ... } — função pura de t em segundos.
  • Comece cada quadro com ctx.reset() (ou save()/restore() balanceados).
  • Use H.rng(seed) e H.noise(seed) fora do loop de quadro; nunca avance estado mutável entre quadros.
  • Armazene texturas de papel/superfície em cache uma vez via H.paperTexture(...) ou H.offscreen(key, w, h, fn).
  • Exponha window.__textBounds = () => [...] para texto crítico da história ({text, critical: true, left, right, top, bottom}) para que verificações automatizadas de área segura possam verificar cada quadro.
• window.scoreSound = (k) => { ... } — agenda eventos de som processuais em carimbos de tempo fixos da linha do tempo (suprime automaticamente bases/música quando --voice é fornecido).

Regras Chave de Produção de Testes

• Margens de área segura e pesos de fonte: No Chrome macOS, Arial fornece apenas pesos 400 e 700 (600 é arredondado para 700 Negrito e alarga linhas em ~9%). Sempre audite measureText(s).actualBoundingBox* em todos os quadros (x: 80..960, y: 190..1640 para curtos verticais 1080x1920).
• Estilos de câmera contínua (transit-map, pan-and-zoom): Comece a interpolação da câmera em beat[i].start (nunca beat[i].start - preRoll quando i muda em beat[i].start, o que causa um salto de 1 quadro), desbote sobreposições locais de batida ao longo de 0.20 s e proteja rótulos em espaço do mundo para que desenhem apenas quando estiverem dentro da viewport do mapa recortada.

---

6. Renderizar Stills, Verificar Determinismo e Renderizar Mestre (docs/07-rendering.md)

1. Portão de Determinismo de Busca:

   node starter/determinism.mjs path/to/film.html
   

2. Portão de Stills de Design (inspecione quadros de abertura, meio denso e final antes da renderização completa):

   node starter/render.mjs path/to/film.html --stills 1.5,12.0,24.0 --outdir "$PROD/stills"
   

3. Renderização MP4 Completa:
   • Renderizador Playwright de referência de trabalhador único (padrão 30 fps Canvas2D + áudio procedural):

     node starter/render.mjs path/to/film.html \
       --out "$PROD/renders/master.mp4" --fps 30 --audio page \
       --voice "$PROD/audio/narration.wav"
     

   • Renderizador WebSocket GPU multi-trabalhador (Three.js / WebGL de 60 fps / tipografia cinética):

     node tools/render/parallel-ws-render.mjs \
       --url "http://127.0.0.1:5173/?capture=1" --duration <DURATION> --fps 60 --workers 4 \
       --audio "$PROD/analysis/analysis.wav" --out "$PROD/renders/master.mp4"
     

   • Renderizador rawvideo Python + Pillow sem navegador (livros de exercícios legendados e tutoriais):

     uv run tools/render/workbook-render.py \
       --spec workbook.json --audio "$PROD/audio/narration.wav" --out-dir "$PROD/renders"
     

---

7. Portões de Verificação Obrigatórios (docs/08-verification.md)

Toda produção deve executar e registrar essas verificações em "$PROD/checks/" antes da entrega:

1. Portão de Fluxo, Decodificação, Sincronia e Sonoridade:

   uv run tools/verify/verify-video.py "$PROD/renders/master.mp4" \
     --expect-seconds <DURATION> --fps 30 --width <W> --height <H> \
     --json "$PROD/checks/verify-video.json"
   

2. Inspeção Visual da Folha de Contato:

   uv run tools/verify/contact-sheet.py "$PROD/renders/master.mp4" \
     "$PROD/checks/contact-sheet.jpg" --n 16 --cols 4 --tile-width 270
   

   Inspecione visualmente contact-sheet.jpg e os stills da cena em busca de corte de texto, colisões de rótulos ou quadros em branco/congelados não intencionais.
3. Auditoria de Aspereza de Transição e Corte:

   uv run tools/verify/cut-harshness.py "$PROD/renders/master.mp4" \
     --top 15 --json "$PROD/checks/cut-harshness.json"
   

4. Diagnósticos de Aparência e Paleta:

   uv run tools/verify/measure-look.py "$PROD/renders/master.mp4" \
     --samples 16 --json "$PROD/checks/measure-look.json"
   

5. Auditoria de Limites de Texto em Todos os Quadros: Siga o padrão em tests/layout.mjs para verificar os limites de tinta fillText e window.__textBounds() em cada quadro 0 .. frames-1.

---

8. Empacotamento e Entrega (RUNBOOK.md §12)

Complete "$PROD/qa.md" (de templates/qa.md) e "$PROD/delivery.md" (de templates/delivery.md). Relate as disposições (PASS/WARN) da verificação da máquina separadamente da aprovação criativa humana de visualização e audição.

Referências Chave

• README.md — Início rápido e índice de capítulos
• RUNBOOK.md — Lista de verificação de produção humano-agente de 12 etapas
• lib/API.md — Contrato exato de gráficos H e áudio procedural SOUND
• examples/README.md — Exemplos trabalhados de paisagem, vertical e estudo de estilo
• docs/10-pitfalls.md — Tabela de sintoma → causa → reparo