/3d-video-studio
┌──────────────────────┐
│ "Por qué los conductores│ el título pregunta sobre un comportamiento, nunca nombra el invento
│ empezaron a filmar la carretera" │
│ ◕‿◕ ▶ 💥 │ gancho: la fechoría del tramposo, recompensa a los 4 segundos
│ laguna → avaricia │ escalada, oposición impasible, dos giros "Pero"
│ tipo tranquilo señala ▣ │ revelación a través de la propia vista del invento
│ "así es como se ___ │ la etiqueta responde al título, la última toma vuelve a la primera
│ inventó." │
└──────────────────────┘
Trabaja a través de los pasos en orden. ⏸ marca un punto de control: detente, muestra el resultado y espera la respuesta del usuario. En cada punto de control, di qué paso viene a continuación. Lee solo los archivos que enumera el paso actual.
SKILL_DIR="<directorio base de este skill>"; ENGINE="$SKILL_DIR/engine"
KIT="$SKILL_DIR/kit"; [ -d "$KIT/node_modules/playwright" ] || KIT="$HOME/.claude/kit"
PY="$KIT/.venv/Scripts/python.exe"; [ -x "$PY" ] || PY="$KIT/.venv/bin/python"
[ -d "$ENGINE/node_modules/three" ] && [ -x "$PY" ] || bash "$SKILL_DIR/setup.sh"
Necesita Node 18+, ffmpeg y Python 3.9+. bash "$SKILL_DIR/setup.sh" instala el resto una vez (three.js, Playwright +
Chromium, un entorno virtual de Python con el modelo de temporización de palabras Parakeet). Ejecuta cada herramienta Python a continuación con "$PY".
El perfil de referencia es el criterio para cada punto de control.
PROFILE="$SKILL_DIR/story/examples/dashcam"contiene los números medidos (profile.json), un fotograma por configuración (frames/) y cada fotograma de cada transición (transitions/).- Si el usuario trae una nueva referencia, primero construye su perfil ("Aprendiendo de una nueva referencia" más abajo) y apunta
PROFILEa él. - Los fotogramas no se incluyen en el repositorio público.
story/examples/dashcam/ystory/examples/cashier/contienen los números medidos (profile.json) y las hojas de ritmo escritas, pero no los fotogramas de la referencia (pertenecen al canal original). Si falta$PROFILE/frames, pide al usuario el vídeo de referencia (cualquier Short de este formato funciona) y ejecuta el paso 2 de "Aprendiendo de una nueva referencia" con$PROFILEcomo carpeta de salida, antes del paso 4. Si el usuario no tiene ningún vídeo de referencia, juzga solo contraprofile.jsony los ejemplos escritos, y díselo en cada punto de control. - Nunca juzgues solo nuestros fotogramas: cada hoja de revisión coloca la referencia al lado de la nuestra.
Paso 1 · Tema ⏸
Lee story/topic-bank.md. Utiliza el tema del usuario u ofrece tres. Realiza la prueba de cuatro preguntas y nombra la comprobación más débil.
Punto de control: el usuario elige un tema.
Paso 2 · Título y guion ⏸
Lee story/title-formula.md, story/formula.md, story/hook-rules.md, story/script-template.md, story/script-check.md.
También lee story/rig-check.md (lo que nuestros personajes planos pueden y no pueden hacer) y ejecuta "$PY" "$SKILL_DIR/tools/rig_check.py" <proyecto>/script.json
antes de puntuar; muestra cualquier indicador con su nota "Escenifícalo como". Una línea que el rig no puede mostrar debe corregirse antes de que se grabe la voz.
Escribe el título primero, luego el guion beat por beat. Puntúalo (reescribe por debajo de 9/10).
Muestra el título, el guion (una frase por línea, etiquetas de beat al lado), el recuento de palabras, la duración
estimada a 3.8 palabras por segundo y la puntuación.
Punto de control: el usuario aprueba o edita. Guarda las frases aprobadas como <proyecto>/script.json
(crea el proyecto con cp -r "$ENGINE/template" <proyecto> primero; <proyecto> no debe existir).
Paso 3 · Biblia visual ⏸
Lee look/style-guide.md (el aspecto de la casa: superficies lacadas brillantes, tinta en todo lo que está enfocado, luz natural,
fondos ligeramente desenfocados, decoración densa) y look/visual-bible.md (reglas y plantilla).
Genera los looks primero: node "$ENGINE/cast.mjs" new <proyecto> --chars <roles> --cars <roles>. Luego escribe
<proyecto>/visual_bible.md cubriendo:
- cada personaje (complexión, cabeza y cabello, capas de vestimenta en hexadecimal, accesorios, las caras que la historia necesita);
- cada entorno (diseño, superficies, fuentes de luz visibles, 4 a 8 elementos de decoración por pared, bromas de texto exactas, profundidad);
- los interiores (coches, cabinas, pantallas), los accesorios (el invento héroe completo) y los gráficos 2D;
- un plan de activos que marque cada elemento como
library + params,library + new textonew. Muestra la biblia con la salida del casting. Punto de control: el usuario aprueba, edita o pide una renovación.
Paso 4 · Hoja de look ⏸
Muestra el diseño visual construido en 3D antes de cualquier storyboard, con el detalle final. Lee look/setup-types.md.
lookdev.html,lookdev.jsysets.jsvinieron con la plantilla. Escribe el set más ocupado de la historia ensets.js(heroSet()es el ejemplo trabajado del aspecto de la casa: reemplázalo, mantén sus capas), siguiendo la biblia exactamente. El vídeo importa el mismosets.jsmás tarde, por lo que este trabajo no se desperdicia.lookdev.jsya hace las tarjetas:- cada personaje de
cast.json, en filas de tres con etiquetas; - las caras del protagonista;
- el set héroe: gran angular, medio con desenfoque de lente 10, y un primer plano de accesorio con desenfoque 14;
- el coche héroe.
Añade una tarjeta para el accesorio héroe, y para cualquier otro set que la biblia marque como
new.
- cada personaje de
- Una tarjeta por tipo de configuración que la historia utiliza (
interior,pov,tracking,house,twoshot,talker,device), cada una construida en su set real con su encuadre real, con cada "Debe tener" delook/setup-types.md. La POV del salpicadero, la pared del hablante y la vista del dispositivo son las que se suelen omitir; constrúyelas ahora. - Emparejalas con la referencia:
"$PY" "$SKILL_DIR/tools/sbs_sheet.py" <proyecto>/review/look_pairs.jpg --ours <tarjetas> --ref <los mismos tipos de $PROFILE/frames>. - Añade una tira de recortes de 400 px a 1:1 (indicadores, bromas de pared, carrocería, carretera), para que se vean los detalles faltantes y el desenfoque.
node "$ENGINE/film.mjs" check <proyecto> 0 <tarjetas> 0.5 --page lookdev.html, corrige cada FALLO (incluyendoclipped-art: el pelo, sombrero o arte de la cabeza de un personaje cortado plano en su borde), luegonode "$ENGINE/film.mjs" sheet <proyecto> <proyecto>/review/look.jpg 0.5 1.5 2.5 ... --page lookdev.html --w 360 --cols 4.- Puntúalo en código:
node "$ENGINE/film.mjs" lookcheck <proyecto> <proyecto>/review/lookcheck 0.5 1.5 ... --page lookdev.html(brillo, contornos, luz, profundidad, densidad, color, caras; 0 a 10 contralook/targets.json). Corrige cadaBAJO, luego mira la hoja una vez a ojo, para lo que los números no pueden juzgar (accesorios de la historia, atractivo). Muestra las puntuaciones con la hoja. Ejecutalookchecken los fotogramas de cada acto en el paso 8 también. Entregareview/look.jpgyreview/look_pairs.jpg. Punto de control: el usuario aprueba el aspecto de los personajes, el mundo y cada tipo de configuración, o enumera correcciones. Cada set en el vídeo está construido a este nivel de detalle.
Paso 5 · Storyboard + guion de voz ⏸
Dos documentos de una vez:
- Storyboard
<proyecto>/storyboard.md: una fila por configuración de cámara (18 a 21):# | frase(s) | beat | tipo de configuración | movimiento de cámara | acción y caras | gag de accesorio | transición de entrada (fotogramas) | acto/ambiente. Reglas destory/formula.md("Imagen y edición");story/examples/dashcam.mdmuestra uno completo.- Tipo de configuración es uno de los nombres en
look/setup-types.md; se convierte en eltypede la toma en código. - Acción y caras nombra una pose del engine (
stand,walk,sitOn,point,lean,armTo…) o un accesorio para cada acción; cualquier otra cosa fallastory/rig-check.mdy se reescribe antes de construir. - Movimiento de cámara: cada fila nombra su movimiento y velocidad (por ejemplo "push-in 6%/s", "pull-back a gran angular", "orbit 120°"); solo la vista del dispositivo puede decir "fija".
- Transición de entrada: las disolvencias son de 7 a 10 fotogramas (hasta 16 para la revelación), o nombra la transición en el mundo. Los sets, personajes y accesorios provienen de la biblia visual aprobada: nómbralos como lo hace la biblia. Debajo de la tabla, copia el plan de activos de la biblia con cualquier cosa que el storyboard haya añadido.
- Tabla de continuidad (debajo del storyboard): cada accesorio o personaje que cambia de lugar o estado recibe una línea,
cosa: estado → estado → estado, con el número de configuración de cada cambio (por ejemplollave: bolsillo (1) → suelo (3) → boca del perro (5)).- Cada cambio ocurre en pantalla en una configuración nombrada, o es mostrado por una acción en pantalla que el espectador puede leer (se tira, aterriza, se entrega).
- Ninguna configuración puede comenzar desde un estado que el espectador nunca vio ocurrir. Una acción posterior que depende de un cambio no visto (buscar algo que nadie vio caer) es un fallo del storyboard: añade la acción a una configuración, o añade una configuración. A través de un salto temporal narrado, se permiten pasos fuera de pantalla ordinarios (sacar un billete de su escondite).
- Etiqueta cada accesorio como objeto de la historia (viaja con la trama) o accesorio de gag (un escondite, contenedor u objeto de broma que se queda en su propio beat). Un accesorio de gag en una nueva ubicación falla a menos que la narración lo nombre allí.
- Debajo de la tabla, una línea de carga por ubicación: quién está allí, qué lleva cada uno y por qué.
- Comprobación de la vida real (
story/rig-check.md, última sección): cada acción y objeto llevado tiene una razón por la que una persona real lo tendría en ese momento. Si la única razón es la continuidad, reescribe la fila.
- Tipo de configuración es uno de los nombres en
- Guion de voz
<proyecto>/voice/cartesia.md: leestory/voice-cartesia.mdy escribe los bloques etiquetados (emoción por bloque, consejo de velocidad, pausas solo antes de los giros "Pero" y la etiqueta).
Muestra ambos. Punto de control: el usuario aprueba el storyboard. Luego pide la voz: "Genera los bloques en
voice/cartesia.md en Cartesia y coloca los archivos en <proyecto>/audio/ (vo_01.wav, vo_02.wav... o un vo.wav).
Construiré la vista previa de 5 segundos mientras tanto." No esperes a que el audio continúe con el paso 6.
Paso 6 · Vista previa de 5 segundos ⏸
Construye solo el gancho (los primeros 5 s, normalmente configuraciones 1 a 3) para que el usuario pueda juzgar el aspecto antes de la construcción larga.
Lee engine/API.md; copia bloques de engine/template/video.js (nunca abras engine/src). Construye cada personaje
y coche de cast.json (makeChar(CAST.characters.x), buildCar(CAST.cars.x)), y usa poses stand / sit.
- Temporización:
sentenceStarts/captionsFromWordscon la estimación (estimateWords), o el archivo de palabras real si el audio ya ha llegado (paso 7). - Importa los sets de
./sets.jsy usamakeStage({ mood: withLook(ambiente, 'indoor' | 'outdoor') }). - El aspecto a juzgar es la hoja de look aprobada: 3D limpio con superficies brillantes, tinta en todo lo que está enfocado,
luz natural, un fondo ligeramente desenfocado, y cada fotograma lleno de borde a borde. Si una cara está en blanco o muestra la
parte trasera de la cabeza, la cámara se colocó después de la pose (ver
engine/API.md, chars.js). - Dale a cada cara una
marky a cada toma sutype. Ejecutanode "$ENGINE/film.mjs" check <proyecto> 0 5 0.25; sale 1 en cualquier FALLO, así que corrígelos todos. - Una hoja:
node "$ENGINE/film.mjs" sheet <proyecto> <proyecto>/review/preview.jpg 0.2 0.8 1.6 2.6 3.6 4.6 --w 180 --cols 6. Mírala una vez; corrige lo que esté claramente mal. - Renderiza:
node "$ENGINE/film.mjs" render <proyecto> <proyecto>/review/preview.mp4 0 5(aproximadamente 1 minuto). Si la voz está disponible, añade los primeros 5 s de la misma:ffmpeg -i review/preview.mp4 -i audio/vo.wav -map 0:v -map 1:a -c:v copy -t 5 review/preview_vo.mp4. - Compara el gancho con el gancho de la referencia:
"$PY" "$SKILL_DIR/tools/compare_video.py" <proyecto>/review/preview.mp4 "$PROFILE" <proyecto>/review/cmp_preview --range 0 5;- coloca nuestra tira de salida junto a
$PROFILE/transitions/(la salida pasa el cristal en aproximadamente 4 fotogramas y aterriza en una toma gran angular). Corrige los FALLOS en movimiento, nitidez y detalle antes de mostrar la vista previa. Entrega la ruta del mp4 y la hoja de pares. Punto de control: el usuario aprueba el aspecto (personajes, colores, cámara, subtítulos) o pide cambios. Los cambios a personajes o estilo son baratos aquí y caros después.
Paso 7 · Voz dentro
Cuando el usuario dice que el audio está en <proyecto>/audio/: sigue "Cuando llega el audio" en story/voice-cartesia.md
(unir bloques, words.py, comprobar la duración y el ritmo).
- El ritmo es un punto de control estricto: fuera de 3.5 a 4.1 palabras por segundo (
film.mjs checkfalla), pide una nueva toma a otra velocidad y no construyas sobre la lenta. El último vídeo salió a 3.4 y duró 71 s contra los 62 de la referencia. - De lo contrario, continúa: la edición se basa en números de frase, por lo que se reajusta. Si la voz no ha llegado al final del paso 8, vuelve a preguntar; no renderices el final sin ella.
Paso 8 · Construye el resto, acto por acto
Para cada acto (1 día, 2 atardecer/noche, 3 lluvia), en orden:
- Nuevos sets y accesorios primero, en
sets.js, construidos al detalle de la hoja de look aprobada y la biblia (ver "No construido aún" enengine/API.md). - Bloques de toma para cada configuración en el acto, cada uno con su
type, transiciones como dice el storyboard (dissolvede 7 a 10 fotogramas,burstconcashBurst()/paperBurst(), un wipe, o un corte duro). film.mjs checkpara el rango de tiempo del acto debe salir 0 (sin FALLO). Los FALLOS que más importan:- una cámara más lenta que el límite
slow-camera(un push-in debe hacer zoom del 6 al 10% por segundo); - una cara héroe fuera del rango de tamaño de su tipo;
- una disolvencia fuera de 5 a 12 fotogramas;
- una etiqueta colgando del objeto al que está pegada (
decal-overhang): registra pegatinas y etiquetas conon: <superficie>; - texto clave cortado por el borde del fotograma, cubierto por una cabeza u oculto (
text-cut). Registra cada número, precio, pantalla y etiqueta de los que depende la broma conreadable(mesh, label, { key: true })cuando se construye el set o la toma.
- una cámara más lenta que el límite
- Hoja de pares del acto: nuestros centros de configuración en la fila inferior, las configuraciones de la referencia de los mismos beats en la superior
(
tools/sbs_sheet.py, fotogramas de$PROFILE/frames). Añade una tira de recortes de 400 px a 1:1 del acto. - Revisión de transiciones: renderiza cada transición en el acto como un clip corto (
film.mjs rendersobre aproximadamente 1 s alrededor de ella). Haz una tira fotograma a fotograma y colócala junto a la transición de referencia del mismo tipo en$PROFILE/transitions/. Comprueba que:- los cortes cambian en un fotograma limpio;
- las disolvencias siguen una curva suavizada mientras ambas tomas siguen moviéndose;
- un burst nunca cubre más de aproximadamente dos tercios del fotograma, y la siguiente toma se desvanece debajo de él;
- un wipe revela...