webgl-scene-to-video

# WebGL / Three.js Scene → MP4 (headless capture) Convierte una escena **Three.js/WebGL animada** (no un slideshow de fotos) en un **MP4 vertical 9:16** sincronizado con voz. Vía: **Puppeteer (Chrome headless) captura frame a frame + ffmpeg**. Alternativa a `hyperframes-html-to-video` cuando la escena usa Three.js y quieres control total (o HyperFrames no está instalado). **No** es el pipeline de fotos/slides de `short-form-video-generation`. Aquí la escena es 3D real (objetos, cámara con dolly, partículas) renderizada a vídeo. ## When to Use - Cuando quieras un **vídeo vertical (Shorts/Reels/TikTok)** a partir de una **escena 3D/animada** (Three.js, WebGL, canvas) en vez de un carrusel de fotos. - Cuando un slideshow plano te parezca "flojo" y quieras **movimiento real de cámara** (dolly), objetos 3D y un look cinematográfico (p. ej. estética apocalíptica/Mad Max). - Cuando `hyperframes` no esté instalado o la escena use Three.js y prefieras control directo de la captura (frame a frame). - Requiere: Node ≥ 22, Chrome del sistema (o `puppeteer` descargado), `ffmpeg` en el PATH, y `edge_tts` (venv Hermes) para la voz. ## El patrón clave: escena SEEKABLE Para capturar frame a frame de forma determinista, la animación NO puede depender del reloj real (`performance.now` en un bucle). Debe ser una función `draw(t)` que se pueda fijar en un tiempo arbitrario: ```js function draw(t){ // TODO el estado depende de t (cámara, objetos, partículas, textos) renderer.render(scene, camera); } window.seek = t => draw(t); // fija y dibuja en el tiempo t window.play = () => { // para previsualización en vivo const s=performance.now(); (function f(now){ draw((now-s)/1000); requestAnimationFrame(f); })(); }; window.seek(0); // dibuja el primer frame ``` - Todo lo que se mueva (cámara, rotación de objetos, partículas, opacidad de textos) debe derivarse de `t` **de forma determinista**, nunca acumulativo. - Partículas: usar posición base + `(t*v % rango)`, NO `y += 0.01` en cada frame (eso se acumula y rompe el `seek`). - Textos superpuestos: controlar su `opacity`/`transform` desde `draw(t)` en vez de CSS keyframes, para que también sean seekables. ## Captura con Puppeteer ```js const puppeteer = require('puppeteer-core'); // usar el Chrome del sistema, no descargar otro const CHROME = 'C:/Program Files/Google/Chrome/Application/chrome.exe'; (async () => { const browser = await puppeteer.launch({ executablePath: CHROME, headless:'new', args:['--no-sandbox','--window-size=1080,1920','--use-gl=angle','--use-angle=swiftshader','--enable-unsafe-swiftshader'] }); const page = await browser.newPage(); await page.setViewport({ width:1080, height:1920, deviceScaleFactor:1 }); await page.goto('http://localhost:8123/teaser.html', { waitUntil:'networkidle2', timeout:60000 }); await page.waitForFunction('typeof window.seek === "function"', { timeout:30000 }); const DUR=14.2, FPS=15, n=Math.ceil(DUR*FPS); for(let i=0;i<n;i++){ await page.evaluate(tt => window.seek(tt), i/FPS); await page.screenshot({ path:`frames/f_${String(i).padStart(4,'0')}.png` }); } await browser.close(); })(); ``` Servir el HTML con un `python -m http.server 8123` en el directorio (el importmap/CDN de three.js funciona vía http; `file://` puede fallar para módulos). `npm i puppeteer-core` es suficiente — **no** hace falta `puppeteer` completo ni descargar Chrome. ## Montaje con ffmpeg ```bash ffmpeg -y -framerate 15 -i frames/f_%04d.png -i voice.mp3 \ -c:v libx264 -pix_fmt yuv420p -c:a aac -b:a 192k \ -shortest -movflags +faststart out/video.mp4 # fades cinematográficos (opcional): duración = duración del audio ffmpeg -y -i out/video.mp4 \ -vf "fade=t=in:st=0:d=0.5,fade=t=out:st=<DUR-0.5>:d=0.5" \ -af "afade=t=in:st=0:d=0.3,afade=t=out:st=<DUR-0.3>:d=0.3" \ -c:v libx264 -pix_fmt yuv420p -c:a aac -movflags +faststart out/final.mp4 ``` ## Pitfalls (verificados) - **El bucle `requestAnimationFrame` compite con `seek(t)`.** Si la página arranca un bucle con el reloj real, corre entre `seek(t)` y el screenshot y sobrescribe el estado → todos los frames salen iguales / el timing de los textos no sigue. **No arranques el bucle automáticamente**: deja `seek(t)` y `play()` como funciones, y usa `seek(t)` en la captura. - **GPU nativa vs SwiftShader:** `--use-angle=gl` (GPU nativa) dio `THREE.WebGLProgram: Shader Error ... VALIDATE_STATUS false` en Chrome headless. Usar **`--use-angle=swiftshader --enable-unsafe-swiftshader`** (software) — compila limpio. El rAF va a ~20 fps bajo SwiftShader, suficiente para la captura (la sincronización la da `seek(t)`, no el fps). - **Mostrar el fondo CSS detrás del canvas WebGL:** por defecto el canvas WebGL es opaco y tapa el gradiente CSS. Poner `alpha:true` en el `WebGLRenderer` + `renderer.setClearColor(0x000000, 0)` para que el gradiente de fondo se vea a través. - **Servir por HTTP** (`python -m http.server`), no `file://`, para los imports ES con importmap (CDN) en headless. ## Verificación - `ffprobe` el MP4: 1080×1920, H.264/AAC, duración ≈ voz. - Extraer 2-3 frames a distintos `t` (0.5s, mitad, final) y comprobar visualmente que **el timing de los textos cambia** y la **cámara hace dolly** (los objetos se ven más grandes al final). Solo mirar un frame no confirma la animación. ## Voz (edge-tts) — notas para vídeos con narración - El nombre de voz debe llevar el sufijo `Neural` (ej. `es-US-AlonsoNeural`), no `es-US-Alonso`. - `rate` y `pitch` requieren signo: `'+0%'`, `'-8Hz'`. `'0%'` falla con `ValueError`. - `rate='-15%'` alarga la duración (~22s un guion de 220 chars); para un teaser corto usar `rate='+0%'` y acortar el guion. - Elegir voz "de peli": generar 2-3 candidatas y comparar su **frecuencia fundamental (f0)** — la más baja (más grave) encaja en trailers apocalípticos. Método: ffmpeg a wav 16 kHz + autocorrelación (ver `references/kit72h-teaser-madmax.md`). ## Preferencia de David (no romper) - **Visual:** espectáculo primero; **NUNCA gradiente azul→naranja**. Usar monocromo ámbar/sepia cálido (fondo oscuro + un solo acento naranja `#f59e0b`-ish) — respetado en la estética Mad Max. - **Voz:** para TTS general la voz por defecto es `es-ES-AlvaroNeural`; para **spots/promos cinematográficos David está abierto a una voz más grave** (elegida por f0), como `es-US-AlonsoNeural`. ## Referencias - `references/kit72h-teaser-madmax.md` — receta completa del teaser Mad Max de kit72h: esqueleto `draw(t)`, render.js, ffmpeg, análisis de f0 para elegir voz, y los ajustes de la escena.