metehan2236/3d-animator

3D Animador

"Haz un video 3D genial" produce una escena gris, con luz plana y cámara estática, porque el modelo cae en valores predeterminados sin tomar decisiones cinematográficas. Este skill obliga a tomar esas decisiones antes de codificar y proporciona la infraestructura para implementarlas.

Objetivo: Una película que se entregue sin errores técnicos en la primera versión y que se pueda finalizar con unas pocas revisiones. No se busca la perfección, sino un punto de partida sólido y editable. Lo que lo garantiza no es la infraestructura, sino el siguiente orden; no saltar pasos.

El formato del proyecto es HyperFrames. Para las reglas de composición, aplica hyperframes-core.

Con qué ejemplo comenzar

Solicitud	Inicio	Leer
Movimiento de personas, vehículos, objetos, acción, historia	assets/example-street-film/	references/motion.md
Narración en off, explicación de conceptos, presentación	assets/example-chip-film/	references/film-grammar.md
Ambas	Toma la película de calle, añade el lenguaje narrativo	Ambos

Leer siempre: references/materials.md, references/craft.md, references/sound.md.

Conserva la estructura, reescribe el contenido según el tema. No transportes la calle, la pelota o el chip del ejemplo a nuevos trabajos. Si se proporciona un video de referencia, aprende su técnica, no copies el texto ni el montaje. Secciones de scene.js: set, actores, coreografía, cámara, look.

Requisitos de la película

Si falta alguno, se verá como una "demo 3D", no como una película:

1. Escala real: 1 unidad = 1 metro. El desenfoque de lente, las sombras y las texturas funcionan correctamente con esto.
2. Espacio lleno y profundo: Fondo, plano medio, primer plano y más allá. Al menos 25 objetos. El protagonista se modela pieza por pieza.
3. Luz natural: Luz principal motivada + skyDome. Un objeto sin sombra parece flotar.
4. Textura correcta: Cada superficie usa M.* o el mismo rigor. Ninguna superficie es de un solo color.
5. Una historia y una razón: Cada movimiento tiene un motivo. Aproximadamente cada 3 segundos ocurre un nuevo evento.
6. Autoría de cámara: Cada plano tiene un único propósito. La lente y el movimiento sirven a ese propósito.
7. Sonido: Grabaciones reales, música, voz en off. Cada sonido está ligado a una causa en la imagen.

Flujo

1. Plan (shot-plan.md)

Antes de escribir código: mensaje de una frase, protagonista, lista de espacios, idea de iluminación, paleta, lista de texturas y tabla de planos.

Duración	Evento	Cámara (lente, movimiento)	Sonido	Subtítulo
9.1–10.2	La pelota se escapa de la mano del niño	46mm, contrapicado, f/3.2	Respiración breve	Nobody's watching the ball.

Si no se especifica formato, usar 16:9 1920×1080. Para Reel vertical, configurar 1080×1920 y replanificar los encuadres. Si el usuario ha dado el tema, no esperar aprobación, mostrar el plan brevemente y continuar. Si una decisión cambia radicalmente la película (formato, idioma, exigencia de humanos realistas), preguntar desde el principio.

2. Configurar el proyecto

npx hyperframes init <nombre> --resolution landscape --non-interactive

Copiar todos los archivos de assets/rig/ y los del ejemplo seleccionado a la raíz del proyecto.

3. Sonido, luego imagen

Las duraciones provienen del diálogo; los tiempos de cámara dependen de ello. Configurar primero el sonido.

node <carpeta-del-skill>/scripts/make-sfx.mjs assets/sfx <duración-seg>

node <carpeta-del-skill>/scripts/build-audio.mjs .

El script escribe voiceToMusicDb, overrun, voiceClash, overlap y el nivel de mezcla. Si termina con código de error, corregir los tiempos. Para obtener fuentes, licencias y mezcla, ver references/sound.md. Si no se encuentra música o la licencia no es compatible, scripts/make-music.mjs genera una base desde código. Las grabaciones de la película de calle no están en el skill; la lista está en assets/example-street-film/SOURCES.md. En la primera configuración:

py -3.12 -m venv "%USERPROFILE%\.cache\3d-animator-venv"

"%USERPROFILE%\.cache\3d-animator-venv\Scripts\python" -m pip install kokoro-onnx soundfile faster-whisper "av<16"

Dirigir la variable de entorno HYPERFRAMES_PYTHON a este archivo python. Kokoro no sabe turco: para turco, con permiso del usuario, generar voz con otro proveedor, colocarla como voice/NN.wav y el mismo texto como voice/NN.txt. El script no regenera este par.

4. Escena

Herramienta	Función
createFilm({canvas, width, height, fps, samples, bloom, environment, background})	Cadena de renderizado
film.setShots([...])	Lista de tomas; cada at es un corte. track: (t) => ({pos, look, lens, fstop, focus, roll}) sigue un sujeto en movimiento
film.setKeys([...])	Cámara única sin cortes
film.onUpdate(t => ...)	Movimiento de objetos y personajes. Se llama por cada subfotograma
film.onFrame(T => ...)	Luz, look, decisiones de modo. Se llama una vez por fotograma
film.look	exposure, saturation, contrast, blackPoint, lift, shadowTint, midTint, highlightTint, flash, grain, vignette, aberration, fade, invert, bloom, stylize
film.skyDome, film.softLight, film.skyBackdrop, film.bakeEnvironment	Luz natural y reflejos
film.mirrorFloor(mesh)	Reflejo real para suelo mojado y agua
film.sunThroughBlinds, film.shaft, film.dust, film.burst, film.sparks, film.screen, film.wire	Efectos y detalles
M.*, skinned, boxUV	Texturas (references/materials.md)
createCharacter, walker, createCar, driver, createBicycle, rider, loadRigged	Actores (references/motion.md)
speedProfile, groundPath, bounces, springTrack, track, noise1, rng, EASE	Ayudantes de movimiento
addCaptions(tl, el, LINES)	Subtítulos palabra por palabra

Regla inmutable: Todo lo visible es función pura del tiempo. No escribas rotation.y += 0.01, escribe rotation.y = t * 0.6. Los fotogramas se solicitan en orden aleatorio y varias veces. No uses Date.now(), performance.now(), requestAnimationFrame ni Math.random sin semilla.

5. Prueba de aspecto

Pon SAMPLES = 4 y toma fotogramas en cada golpe de la película. No tomes menos de 15 fotogramas. setTextureScale(SAMPLES < 16 ? 0.5 : 1) acorta mucho los tiempos de prueba, porque cada trabajador de renderizado regenera todas las texturas desde cero:

npx hyperframes check

npx hyperframes snapshot --at <t1>,<t2>,... --timeout 240000

Usa --angle top para detectar colisiones. Con SAMPLES 1–4, la luz del cielo y el enfoque engañan: las sombras se ven duras y el enfoque parece puntual. Toma decisiones de textura e iluminación con 16 samples.

Abre los fotogramas y revisa. Texturas: ¿el relieve es exagerado?, ¿hay estiramientos?, ¿cada superficie tiene textura? Encuadre: ¿se corta el sujeto o la cabeza?, ¿se lee el propósito de cada plano? Iluminación: dirección, sombra de contacto, reventón. Movimiento: ¿deslizamiento de pies?, ¿atravesamiento?, ¿objeto suspendido en el aire? Texto: ¿los subtítulos se leen sobre un fondo claro?

Si hay un video de referencia, pon los mismos momentos lado a lado (scripts/look-stats.mjs da una comparación numérica de tonos); el método de desglose de la referencia está en references/film-grammar.md.

6. Borrador, escaneo, corrección

npx hyperframes render --quality draft --output draft.mp4

node <carpeta-del-skill>/scripts/qa-film.mjs draft.mp4 --script script.json --whisper <python> --earshot <python>

El escáner genera fotogramas como qa/sheet-*.jpg (4 fotogramas por segundo) e informa sobre fotogramas negros, congelamientos, destellos de un solo fotograma, nivel de sonido, palabras inaudibles y la tarjeta de earshot. Revisa todas las páginas una por una. Incluso si la máquina dice que está limpio, los errores se ven allí. Luego abre cada primer plano a tamaño completo (references/materials.md, revisión fotograma a fotograma): un fotograma que se ve limpio en una página pequeña, a menudo no lo está a tamaño completo. En esta película, la mayoría de los errores solo se ven así.

Corrige cada hallazgo antes de pasar a alta calidad. Renderiza solo la parte dañada:

npx hyperframes render --quality draft --start 18 --end 21 --output parte.mp4

7. Final

SAMPLES 24–32. La escala de la película de calle, una escena, tarda unos minutos en una RTX 4060; si en la línea de resumen aparece software gpu, tardará mucho más; avisa al usuario desde el principio.

npx hyperframes render --quality delivery --output final.mp4

Repite el escaneo en la película final, porque los SAMPLES bajos ocultan errores de enfoque. Si no hay earshot, pide permiso para instalarlo (aproximadamente 1–3 GB). El earshot en PyPI es otro paquete; la fuente correcta es github.com/Leonxlnx/earshot. En Windows, instala el entorno virtual en una ruta corta, porque torch falla con rutas largas.

Entrega

Di lo siguiente: qué hiciste, qué revisaste, qué no pudiste revisar y qué falta todavía. Enumera las fuentes de sonido y música utilizadas con sus licencias. Incluso si la tarjeta de launch-grade es alta, eso no significa que la película sea bonita. El gusto y la naturalidad de la voz en off son responsabilidad del usuario.

Revisión

Cuando el usuario solicite una revisión:

1. Convierte la nota en un plan: En qué plano, qué, cómo debería verse. Si es ambiguo, haz la interpretación más probable y dilo; no hagas preguntas por cada nota.
2. Cambia el lugar correcto: Textura M.*, cámara setShots, temporización una sola constante (BRAKE_T), tono film.look, sonido script.json. Todo lo que depende de una constante se desplaza junto con ella.
3. Renderiza solo esa parte: Con --start y --end. Si solo cambió el sonido, no renderices la imagen (references/sound.md).
4. Muestra la parte junto a su versión anterior, y solo después de la aprobación haz el render completo.
5. Escribe la lección permanente en el skill: Si un tipo de error aparece por segunda vez, añádelo a este archivo o a la referencia correspondiente.

Humano realista: referencia + video IA

Esta película sirve como referencia para una herramienta de video IA; la imagen final la produce esa herramienta. La configuración aún no se ha probado de extremo a extremo; en el primer uso, pruébala con un solo plano y muestra el resultado al usuario.

1. Configura solo el bloqueo: Encuadre, movimiento de cámara, quién está dónde, cuándo. No pierdas tiempo en detalles del personaje ni en texturas finas.
2. Entrega cada plano por separado: Las herramientas de IA son más consistentes con clips cortos. Renderiza plano por plano con --start y --end. Desactiva los subtítulos; pon a cero los valores de grain, aberration y vignette. La herramienta confunde los textos y efectos con imagen real.
3. Fija el aspecto: Primero convierte el primer fotograma del plano en una imagen realista. Mantén las referencias de personaje y escenario iguales en todos los planos; después de la aprobación, pasa al video.
4. Di el costo de antemano: Indica qué herramienta, para cuántos planos y el crédito estimado; pide aprobación. Verifica las herramientas disponibles en ese momento; no las des por sentadas de antemano.
5. Revisa: Fotogramas a tamaño completo y puntos de corte: rostro, mano, texto en placas y letreros, cambio de vestuario entre planos. Si el movimiento se aleja de la coreografía, reduce la potencia de transformación.
6. Termina el sonido aquí: El sonido y los subtítulos se quedan en esta línea con script.json. Verifica la duración de los clips resultantes; si se desplazan, ajusta los tiempos de sonido a la nueva duración.

Limitaciones

Dilo al principio, no al final:

• Humanos estilizados: Calidad de película de animación. No hay fotorrealismo, actuación facial ni bocas parlantes. En primer plano, se ven rígidos. Si se necesitan humanos realistas, usa la ruta de referencia a continuación; en películas sin humanos, haz que el protagonista sea un objeto o vehículo, y mantén a los humanos en la distancia.
• La física está dirigida artísticamente: Se escribe según la historia, no es una simulación real. No hay simulación de tela, cabello ni fluidos; el agua se imita con partículas.
• El sonido sintético suena a sintético si se genera con código. Las grabaciones reales requieren permiso.
• La voz en off en turco requiere voz externa.