cumalibilgic/cinematic-3d-video

Video 3D Cinemático

Claude no puede generar píxeles de video directamente, pero puede escribir una escena 3D como código, renderizarla cuadro a cuadro y codificar los fotogramas. Esta habilidad es ese pipeline.

escena (HTML + Three.js)  -- window.seek(t) -->  scripts/render.mjs  -->  capturas de pantalla de Chrome sin interfaz gráfica  -->  ffmpeg  -->  MP4

render.mjs avanza un reloj virtual en lugar de grabar en tiempo real. El resultado es el mismo en cualquier máquina, y una escena pesada no se traba; solo se renderiza más lentamente. Por eso una escena debe ser una función pura del tiempo (ver "Reglas de la escena").

1. Verifica las herramientas primero

node -v        # 22 o más reciente (render.mjs usa el WebSocket incorporado)
ffmpeg -version

Chrome, Edge o Chromium deben estar instalados (se encuentran automáticamente; establece CHROME_PATH para anular). Three.js se carga desde un CDN mediante la escena, por lo que la máquina que renderiza necesita acceso a internet a menos que Three.js esté incluido localmente (ver references/troubleshooting.md). Si falta una herramienta, dile al usuario exactamente qué instalar y deja de adivinar soluciones. Blender solo es necesario para la ruta fotorrealista.

Ejecuta la prueba de humo sin dependencias una vez cuando la máquina sea nueva. Esto prueba que Chrome, WebGL y ffmpeg funcionan, por lo que cualquier problema posterior está en la escena y no en la configuración:

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

2. Flujo de trabajo

1. Define el briefing en una o dos oraciones: tema, ambiente, duración, relación de aspecto, texto, audio. Cuando el usuario deje cosas abiertas, elige valores predeterminados y di lo que elegiste: 1920x1080, 30 fps, 8-12 s, fondo oscuro, un objeto principal, un movimiento de cámara, un título. Vertical (TikTok/Reels/Shorts) es 1080x1920. Hacer más de una pregunta corta antes de empezar rara vez vale la pena; un primer render es la mejor pregunta.
2. Comienza desde el iniciador. Copia templates/starter/ al directorio de trabajo (cp -r) y edita index.html. Ya tiene el renderizador, mapeo de tonos, reflejos de estudio, bloom, sombras, partículas con semilla, una ruta de cámara, una superposición de título HTML y el enlace de la línea de tiempo. Reemplaza el objeto principal, la paleta, la ruta de la cámara y el texto; mantén la infraestructura.
3. Mira fotogramas fijos antes de renderizar el video. Renderiza un puñado de fotogramas a tamaño completo en los momentos más activos y ábrelos (Lee los PNGs):

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

   Arregla la composición, exposición, color y legibilidad del texto aquí. Un fotograma fijo toma uno o dos segundos; un render completo toma minutos.
4. Renderiza una vez. Elige la configuración y luego renderiza el video completo:

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

   --scale 2 renderiza al doble y reduce la muestra, lo que elimina bordes brillantes (vale la pena solo para el render final). Los renders largos deben ir en segundo plano con el progreso consultado, para que el usuario nunca se quede mirando una terminal silenciosa.
5. Verifica el archivo, no el registro. ffprobe para duración, tamaño y fps; extrae dos o tres fotogramas del MP4 (ffmpeg -ss 3 -i video.mp4 -frames:v 1 check.png) y míralos. Luego entrega el MP4 junto con la carpeta de la escena para que el usuario pueda ajustarla.
6. Las revisiones cambian la escena y vuelven a renderizar. Usa --start/--end para renderizar solo un rango mientras iteras en un momento.

3. Reglas de la escena (y por qué)

• Todo lo animado es una función pura de t segundos, establecida dentro de update(t). Sin Math.random() (usa la rng() con semilla), sin Date.now(), sin clock.getDelta(), sin estado acumulado entre fotogramas. El renderizador puede llamar a seek con cualquier tiempo en cualquier orden, y una vista previa en el navegador debe coincidir exactamente con el video.
• El contrato de la página es window.seek(t) (dibujar sincrónicamente), window.__duration (segundos) y window.__ready = true una vez que los activos estén cargados. installTimeline() en lib/stage.js hace las tres cosas. Detalles en references/contract.md.
• Los colores HDR por encima de 1.0 hacen que las cosas brillen. El bloom solo captura píxeles más brillantes que su umbral, por lo que las partes emisivas usan new THREE.Color(hex).multiplyScalar(3..6); las superficies ordinarias se mantienen por debajo del umbral.
• El texto es HTML/CSS sobre el lienzo (la captura de pantalla incluye la página). Es nítido en cualquier resolución, no necesita archivos de fuente y se anima con cambios de estilo simples dentro de update(t).
• Carga activos con await antes de establecer __ready (modelos GLTF, texturas, fuentes). Un fotograma renderizado antes de que llegue un activo es un error permanente en el video.
• Mantén una sola historia de iluminación: una luz principal, una o dos luces de borde coloreadas y reflejos basados en imágenes. Los materiales reflectantes (metal, vidrio, capa transparente) sobre un piso oscuro y ligeramente reflectante son lo que se lee como "animación 3D" en lugar de "demo web". references/cinematography.md tiene las recetas para movimientos de cámara, ritmo, easing, iluminación y color.

4. Varias escenas, audio, otros formatos

• Videos multiescena: renderiza cada escena a su propio MP4 con tamaño, fps y configuración de codificador idénticos, luego únelos sin recodificar: escribe un list.txt con líneas file 'a.mp4' y ejecuta ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4. Pon las transiciones dentro de la línea de tiempo de una escena (el último segundo de una escena y el primer segundo de la siguiente ambos se desvanecen a negro/color) en lugar de mezclar archivos terminados, lo que codificaría todo dos veces.
• Audio: --audio track.mp3 lo multiplexa y lo recorta al video. Para cambiar solo el sonido más tarde: ffmpeg -i video.mp4 -i new.mp3 -map 0:v -map 1:a -c:v copy -shortest out.mp4.
• GIF / WebM / copia más pequeña: recodifica el MP4 terminado con ffmpeg; nunca vuelvas a renderizar para un cambio de formato.
• Cambiar una escena significa volver a renderizar el archivo de esa escena (y la siguiente solo si contiene una transición).

5. Cuándo usar Blender en su lugar

Usa Blender (references/blender.md, templates/blender/render_blender.py) solo cuando el briefing necesite lo que un motor en tiempo real no puede simular bien: vidrio con trazado de rayos y causticas, luz volumétrica, piel con subsuperficie, simulación de fluidos/tela/humo, o tomas de producto completamente fotorrealistas. Es mucho más lento por fotograma y necesita Blender 4+ instalado; para todo lo demás, Three.js llega a un buen resultado en una fracción del tiempo e itera más rápido.

Archivos de referencia

Archivo	Léelo cuando
references/contract.md	escribas una escena desde cero, cargues modelos/texturas, o depures "nunca se estableció __ready"
references/cinematography.md	quieras que el resultado se vea bien: cámara, luz, materiales, easing, ritmo, color, texto, partículas
references/troubleshooting.md	tengas fotogramas negros, renders lentos, configuración CDN/sin conexión, peculiaridades de Windows/macOS/Linux, tamaños extraños
references/blender.md	trabajo fotorrealista o de simulación
scripts/render.mjs	todas las opciones: node scripts/render.mjs --help