Video por Código

Habilidad de Video por Código

Un conjunto de herramientas ejecutable y un flujo de trabajo de producción para equipos humano-agente que crean vídeos deterministas en código. Todo el código de escena permanece dentro del repositorio o espacio de trabajo del proyecto; todos los medios generados, tomas de audio, fotogramas y recibos de verificación viven en un directorio externo explícito $PROD.

Orden de trabajo: brief → audio y temporización → estilo y prompt → 3 fotogramas de diseño → código de escena → puerta de determinismo y límites de texto → renderizado completo → verificación y hoja de contacto → recibo de entrega

---

1. Entorno y Prueba de Humo

Antes de construir una nueva película, asegúrate de que las dependencias iniciales están instaladas y de que la prueba de humo de 4 segundos pasa desde la raíz del repositorio:

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

---

2. Directorio de Producción e Intención (RUNBOOK.md §1–2)

1. Elige un directorio de producción absoluto fuera del checkout del código:

   PROD="/ruta/absoluta/a/salidas-de-video/<slug-del-proyecto>"
   mkdir -p "$PROD"/{audio,analysis,stills,renders,checks}
   

2. Copia templates/brief.md a "$PROD/brief.md" y completa la audiencia, conclusión principal, relación de aspecto (1920x1080 horizontal o 1080x1920 vertical), duración, fuente de voz/música y márgenes de área segura.

---

3. Identidad de Audio y Temporización (docs/04-music-audio-and-timing.md, docs/05-narration-and-captions.md)

Nunca animes usando marcas de tiempo estimadas. Primero mide el archivo de audio real y registra su 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"

• Narración hablada:
  • Sintetiza mediante Kokoro ONNX TTS local (con fusión de fragmentos < 4 palabras y diccionario fonético --say say.json): uv run tools/timing/kokoro-narrate.py script.txt --out-dir "$PROD/audio" --voice af_heart --say say.json
  • Verifica el audio hablado de ida y vuelta mediante whisper-cli local: uv run tools/verify/verify-narration.py "$PROD/audio/narration.wav" "$PROD/audio/timing.json"
  • Comprueba que los guiones/letras no tengan levantamiento de n-gramas verbatim contra el texto de referencia: python3 tools/verify/check-lift.py candidate.txt reference.txt
• Pistas reactivas a música / letras / stems:
  • Separa 6 stems mediante Demucs (vocals, drums, bass, guitar, piano, other) y normaliza a WAV de 44.1 kHz: uv run --python 3.12 tools/timing/separate-stems.py "$PROD/audio/song.mp3" --out-dir "$PROD/analysis"
  • Extrae envolventes de stem a 120 Hz, tiempo musical monótono tau, fase de beat/compás, silencios, features.f32 y pitch/vibrato de guitarra a 100 fps: uv run --python 3.12 tools/timing/analyze-stems.py "$PROD/analysis" --fps 120 --stem-pitch
  • Alinea letras a nivel de palabra (whisper-cli, mlx-whisper, faster-whisper o warping de energía 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"
  • Señales ligeras de un solo archivo / cuadrícula de beats / envolvente 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. Selección de Estilo y Montaje de Prompt (prompts/README.md)

Navega por prompts/styles/INDEX.md (86 tarjetas de estilo visual creadas en 13 familias) y prompts/briefs/ (5 briefs de formato: explainer-voiceover, vertical-short, lyric-video, instrumental-visualizer, data-story).

Monta la especificación combinada para tu estilo y brief elegidos:

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

---

5. Contrato de Creación de Escenas (lib/API.md, docs/06-building-scenes.md, docs/12-advanced-engines-and-benchmarks.md)

Cada página HTML de escena carga lib/harness.js (window.H) y opcionalmente:

• lib/sound.js (window.SOUND) — síntesis de Web Audio procedural
• lib/features.js (window.FEATURES) — cursor de stem features.f32 binario a 120 Hz, pulso de inicio refractario, tau(t) monótono y búsqueda de letras words.json
• lib/ink-doodle.js (window.INK) — línea ondulada determinista a 8 fps, primitivas de doodle tambaleantes, escritura en MAYÚSCULAS anclada a la izquierda marker y cámara Ken Burns plate
• lib/webgl-post.js (createPost) — post-procesamiento Three.js de 4 etapas (FxOverShader, UnrealBloomPass, FinalGradeShader con ACES / paperMode, inversión de impacto solo de luminancia, glitch, shake, grano y superposición de UI nítida)

Cada página expone:

• <canvas id="c" width="1920" height="1080"></canvas> (o 1080 × 1920 para vertical)
• window.DURATION (segundos) y window.FPS (por defecto 30)
• window.__ready (Promise que se resuelve después de que las fuentes y los plates fuera de pantalla en caché estén listos)
• window.__renderFrame = (t) => { ... } — función pura de t en segundos.
  • Comienza cada fotograma con ctx.reset() (o save()/restore() equilibrados).
  • Usa H.rng(seed) y H.noise(seed) fuera del bucle de fotogramas; nunca avances el estado mutable entre fotogramas.
  • Almacena en caché las texturas de papel/superficie una vez mediante H.paperTexture(...) o H.offscreen(key, w, h, fn).
  • Expón window.__textBounds = () => [...] para el texto crítico de la historia ({text, critical: true, left, right, top, bottom}) para que las comprobaciones automatizadas de área segura puedan verificar cada fotograma.
• window.scoreSound = (k) => { ... } — programa eventos de sonido procedurales en marcas de tiempo fijas de la línea de tiempo (suprime automáticamente las bases/música cuando se proporciona --voice).

Reglas Clave de Producción de las Pruebas

• Márgenes de área segura y pesos de fuente: En macOS Chrome, Arial solo proporciona pesos 400 y 700 (600 salta a 700 Negrita y ensancha las líneas ~9%). Siempre audita measureText(s).actualBoundingBox* en todos los fotogramas (x: 80..960, y: 190..1640 para cortos verticales 1080x1920).
• Estilos de cámara continua (transit-map, pan-and-zoom): Inicia la interpolación de la cámara en beat[i].start (nunca beat[i].start - preRoll cuando i cambia en beat[i].start, lo que causa un salto de 1 fotograma), desvanece las superposiciones locales del beat en 0.20 s y protege las etiquetas del espacio mundial para que solo se dibujen cuando estén dentro de la ventana gráfica del mapa recortada.

---

6. Renderizar Fotogramas, Comprobar Determinismo y Renderizar Maestro (docs/07-rendering.md)

1. Puerta de Determinismo de Búsqueda:

   node starter/determinism.mjs ruta/a/film.html
   

2. Puerta de Fotogramas de Diseño (inspecciona los fotogramas de apertura, medio denso y final antes del renderizado completo):

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

3. Renderizado MP4 Completo:
   • Renderizador Playwright de referencia de un solo trabajador (por defecto 30 fps Canvas2D + audio procedural):

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

   • Renderizador WebSocket GPU de múltiples trabajadores (60 fps Three.js / WebGL / tipografía cinética):

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

   • Renderizador rawvideo sin navegador con Python + Pillow (libros de trabajo y tutoriales con subtítulos):

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

---

7. Puertas de Verificación Obligatorias (docs/08-verification.md)

Cada producción debe ejecutar y registrar estas comprobaciones en "$PROD/checks/" antes de la entrega:

1. Puerta de Flujo, Decodificación, Sincronización y Sonoridad:

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

2. Inspección Visual de la Hoja de Contacto:

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

   Inspecciona visualmente contact-sheet.jpg y los fotogramas de la escena para detectar recortes de texto, colisiones de etiquetas o fotogramas en blanco/congelados no intencionados.
3. Auditoría de Dureza de Transiciones y Cortes:

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

4. Diagnóstico de Aspecto y Paleta:

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

5. Auditoría de Límites de Texto en Todos los Fotogramas: Sigue el patrón en tests/layout.mjs para verificar los límites de tinta fillText y window.__textBounds() en cada fotograma 0 .. frames-1.

---

8. Empaquetado y Entrega (RUNBOOK.md §12)

Completa "$PROD/qa.md" (de templates/qa.md) y "$PROD/delivery.md" (de templates/delivery.md). Reporta las disposiciones de verificación de la máquina (PASS/WARN) por separado de la aprobación humana creativa de visualización y escucha.

Referencias Clave

• README.md — Inicio rápido e índice de capítulos
• RUNBOOK.md — Lista de verificación de producción humano-agente de 12 pasos
• lib/API.md — Contrato exacto de gráficos H y audio procedural SOUND
• examples/README.md — Ejemplos trabajados de paisaje, vertical y estudio de estilo
• docs/10-pitfalls.md — Tabla de síntoma → causa → reparación