Sticky Director

Sticky Director — Manual del Director de Cine IA

Este repositorio es un motor de animación y cine mudo local. Un personaje de silueta negra con sudadera gris actúa frente a fotos (por ejemplo, imágenes de Google Flow), con música, sonido ambiental, movimientos de cámara y subtítulos. Lo diriges a través de herramientas MCP (.mcp.json registra sticky-studio → node mcp-server.js) o mediante la CLI (node cli.js …). Ambos inician server.js automáticamente, y las acciones de canvas abren el estudio (Chromium sin cabeza cuando no hay pantalla).

Siempre usa rutas de archivo absolutas. Cada ID a continuación se valida. Los valores desconocidos vuelven como warnings y no se aplican, así que lee las advertencias.

Ejecutando desde Antigravity: si las herramientas MCP de sticky-studio no están disponibles, usa la CLI desde la raíz del repositorio. Cada herramienta MCP tiene un gemelo CLI (tabla más abajo); node cli.js snapshot <t> <abs.png> escribe un PNG que puedes abrir con visión. Todos los comandos inician el servidor del estudio automáticamente.

---

Herramientas (MCP) ↔ CLI

Herramienta MCP	CLI	Qué hace
sticky_status	node cli.js status	Modo, aspecto, duración, BPM / número de pulsos, pestaña conectada, lista de escenas
sticky_get_project	node cli.js get-project [out.json]	Proyecto completo en formato plano de agente (escenas, fxMarkers, mediaCards, audio.beats/strongBeats, fondos + lightProfile)
sticky_load_audio	node cli.js load-audio <path> --mode silent	Carga música/voz → {duration, bpm, beats[], strongBeats[]}
sticky_import_photos	node cli.js import-photos <p1> <p2> … [--auto-build]	Registra fotos → [{bgId, name, path, width, height, lightProfile}]
sticky_apply_template	node cli.js template <id> [--no-photos]	Carga un storyboard de cine mudo ajustado al audio y las fotos
sticky_set_project	node cli.js set-project <file.json | '{…}'>	Envía un storyboard completo o parcial (solo se aplican las claves que envías)
sticky_update_scene	node cli.js update-scene <index|id> '{…}'	Parchea una escena
sticky_split_scene	node cli.js split <timeSec> [--no-snap]	Divide en un tiempo, ajustando al pulso más cercano (±0.35 s)
sticky_add_fx	node cli.js add-fx <type> <timeSec> [--duration s]	Golpe de cámara / SFX / card
sticky_render_frame	node cli.js snapshot <timeSec> [out.png]	Fotograma exacto como PNG (MCP también lo devuelve como imagen)
sticky_export_mp4	node cli.js export	Renderizado en tiempo real → exports/sticky_video_*.mp4 (60 fps H.264 + AAC)

get_status, get_project, set_project y update_scene también funcionan sin una pestaña abierta del estudio: leen y escriben projects/live_state.json, y el estudio lo carga cuando se conecta.

---

IDs de referencia

Emociones (10)

id	usar para
neutral	por defecto, calmado
happy	calidez, alivio, pequeñas victorias
tired	3 AM, agotamiento, cansancio extremo
crying	duelo, derrumbarse (combinar con silentMouth: quiver)
angry	frustración
shocked	pánico, darse cuenta
skeptical	duda, mirada de reojo
confused	momentos de "¿?"
excited	hype (ojos de estrella)
deadpan	vacío, entumecimiento

Gestos (18) — gesture

id	descripción	mejor vista
pocket	manos en los bolsillos de la sudadera (tranquilo por defecto)	cualquiera
idle	brazos relajados (balanceo al caminar)	cualquiera
talking	golpes de mano reactivos al audio (voz en off)	frente
explain	ambas palmas hacia afuera	frente
point_screen	apunta hacia un lado (a una tarjeta multimedia)	frente
point_viewer	apunta a la cámara	frente / 3/4
crossed	brazos cruzados	frente
facepalm	mano sobre la cara	frente
hands_head	manos en la cabeza (pánico)	frente
shrug	encogimiento de hombros, palmas arriba	frente
wave	saludar con la mano	frente
typing	se sienta en un escritorio y escribe (se dibujan escritorio + taburete)	automático 3/4–lateral
slouch_lonely	profunda inclinación, cabeza colgando, respiración lenta y pesada	frente / 3/4
heavy_sigh	ciclo de 4.5 s: inhalar → mantener → hundirse (foley de respiración automática)	frente / 3/4
check_phone_dark	sostiene un teléfono brillante; cono de luz azul en la cara y sudadera	frente / 3/4
sit_curb_hug_knees	se sienta en el suelo abrazando las rodillas, cabeza baja	automático 3/4
look_back_horizon	de pie mirando el paisaje, viento en la sudadera	back / 3/4
pull_hood_up	acción: lleva la mano atrás y se sube la capucha (~2.3 s desde el inicio de la escena)	frente

Claves de cuerpo y pose

clave	valores
pose	rig (articulado, por defecto) · sprites v1: front, bust, side, back
view	front, threeQuarter, side, back
hoodUp	true / false (la capucha se dibuja en cada vista; la vista trasera por defecto está arriba)
walkSpeed	0 quieto · 0.1–1.0 caminar · 1.1–2.5 trote → sprint
walkDir	left, right
walkInPlace	true (cinta de correr) / false (se desplaza por el encuadre, se envuelve)
wind	0..1 (dobladillo, cordones, capucha)
silentMouth	closed (por defecto) · sigh · quiver (llanto / ansiedad)
handLeft, handRight	auto, relaxed, open_palm, pointing, fist, holding_prop, in_pocket
prop	none, phone, mug, mic, controller, book
spineLean, headTilt, headNod	grados (≈ −25…25; headNod + = mirar hacia abajo)
ikPins	{ rightHand|leftHand|rightFoot|leftFoot|head: {x, y} } en unidades del rig (origen = suelo entre los pies, +x = dirección de la mirada, arriba es negativo y; la cabeza está cerca de y ≈ −300, las manos cuelgan cerca de y ≈ −130). {} limpia
x, y, scale, flipX	posición 0..1 (x 0.5 = centro; y ≈ 0.55 = de pie en el tercio inferior), tamaño (1 = por defecto), espejo
motion	breathe (por defecto para mudo), talk_bounce, walk, shake (temblor), float, none
emotion	ver la tabla anterior

Fondos — background

Integrados: paper_sketch, cozy_night, rainy_window, streetlight (lámpara de medianoche), classroom (escritorio al atardecer), dark_spotlight, rooftop_dusk, green_screen. Fotos: usa el bgId devuelto por sticky_import_photos, o simplemente pon la ruta absoluta de la foto en background (se importa automáticamente).

Cámara de foto y profundidad

clave	valores
kenBurns	none, push_in, pull_out, drift_left, drift_right, breathing (la foto se mueve al 100%, el personaje al 30% → paralaje)
foreground	none, bokeh, rain_streaks, window_reflection
camera	static, zoom_in, zoom_out, pan_right, handheld (se aplica sobre kenBurns)
atmosphere	dust (brilla con el ritmo de la música), rain, none
dutchScene / spotlightScene	horizonte inclinado en toda la escena / fondo atenuado al 60%

Coincidencia de luz (armonización de fotos) — lightMatch

true = recomendado (tint 0.35, rim 0.55, exposure 0.5) · false = desactivado · un número 0..1 = fuerza general · o { tint, rim, exposure, side } con side = auto (desde la foto) | left | right | back (contraluz, ambos bordes). Usa true en cada escena de foto. Aumenta rim (0.7–0.9) para atardeceres y horizontes con contraluz; usa side: "back" para look_back_horizon.

Transiciones (cómo ENTRA una escena) — transitionType, transitionDur (0–2 s)

cut · dissolve (ambos planos se renderizan en vivo y se mezclan) · fade_black (paso del tiempo, soledad) · fade_white (flashback, realización, esperanza). La escena 0 con dissolve o fade_black aparece desde negro. fadeOutEnd: true funde la película a negro al final.

Capas ambientales (continuas, por escena) — ambientBed, ambientVol 0..1

id	ambiente
none	—
rain_window	lluvia suave + truenos lejanos (también moja las pisadas)
night_wind	viento solitario de medianoche
vinyl_crackle	polvo lo-fi cálido
clock_ticking	tic reverberante a 60 BPM: 3 AM, insomnio, vacío
heartbeat	latido profundo y apagado: ansiedad, pánico
crowd_muffle	murmullo filtrado paso bajo: solo en una habitación llena

Marcadores FX — sticky_add_fx / fxMarkers: [{type, timeSec, …}]

• Golpes de cámara: snap_zoom (1.0→1.25× muelle en la cara), dutch_tilt, shake, spotlight (+ duration, intensity 0..3, dir ±1 para holandés)
• SFX / foley (10): whoosh, pop, vine_boom, record_scratch, shutter, typing, footstep_wet, heavy_sigh_breath, phone_vibrate, door_close_echo (+ volume)
• Las escenas también pueden establecer transitionSfx (un SFX reproducido en el corte) y foley: true (pisadas automáticas en cada golpe de talón + respiraciones de suspiro; activado por defecto en modo mudo)
• Tarjetas multimedia: type: "card" con card: {kind: image|meme|post|note, text, imagePath, side: auto|left|right, hold, size}

Claves a nivel de proyecto (sticky_set_project)

clave	valores
mode	silent (solo música, la boca nunca sincroniza labios) · voiceover
aspectRatio	16:9 · 16:9-letterbox (barras de cine 2.35:1) · 9:16 (Shorts / Reels / TikTok, 720×1280)
fadeOutEnd	true o segundos
masterAmbientVol	0..1
captionStyle	cinematic (serifa de cine mudo), pop, karaoke, classic, off, o {mode, highlight, position: bottom|middle|top, chunk, uppercase, size}
snapToBeats	por defecto true: los cortes se ajustan al pulso más cercano
scenes	objetos de escena planos. Temporización: proporciona start/end en todas las escenas, o ninguna y usa duration / weight (distribuido sobre la música)
fxMarkers	ver arriba
mediaCards	[{sceneIndex | timeSec, kind, text, imagePath, appear, hold, side}]

Plantillas — sticky_apply_template

loneliness_3am (teléfono en la oscuridad → caminata bajo la lluvia con capucha → abrazando rodillas en el bordillo → amanecer en el horizonte) · social_anxiety (encorvado en una esquina + murmullo de multitud → pánico con latido del corazón → salir al viento → suspiro de alivio) · burnout (escribir en el escritorio → mirada vacía con reloj → fundido a negro → caminata bajo la lluvia) · discipline (despertar cansado → subir la capucha → trote a 1.2× → sprint a 2.0× hacia el amanecer).

---

Flujo de trabajo de dirección

1. Mira y escucha. Mira las fotos del usuario con visión (lee los archivos de imagen) y decide el arco emocional (p. ej., aislamiento → punto de quiebre → liberación → esperanza). Carga la música con sticky_load_audio {path, mode: "silent"} y anota duration, bpm y strongBeats (los mejores puntos de corte).
2. Importa y mapea fotos. sticky_import_photos {paths: [...]} en orden de la historia. Usa cada lightProfile (tone cálido/frío, brightness, lightFrom) para elegir el pulso. Las habitaciones oscuras y frías son adecuadas para check_phone_dark / slouch_lonely + clock_ticking. Las calles lluviosas son adecuadas para caminatas con capucha pocket + rain_window + rain_streaks. Los atardeceres y horizontes urbanos son adecuados para look_back_horizon (vista trasera, lightMatch {rim: 0.8, side: "back"}) + night_wind.
3. Construye el storyboard con una sola llamada sticky_set_project: mode: "silent", captionStyle: "cinematic", fadeOutEnd: true, y una escena por foto. Dale a cada escena background (la ruta o bgId), gesture, emotion, view, hoodUp, kenBurns, lightMatch: true, ambientBed, transitionType (primera escena fade_black, principalmente dissolve 1.0–1.5 s, fade_black para saltos temporales, fade_white para el giro hacia la esperanza), subtitles poéticos cortos (≤ 8 palabras, o vacío), y weight para énfasis. Añade algunos fxMarkers (phone_vibrate, door_close_echo, un snap_zoom en el pico emocional). Comprueba los warnings en el resultado.
4. Inspecciona visualmente. sticky_render_frame en 2–3 momentos clave: dentro de la primera escena (después de su fundido, ~1.5 s), a mitad de la película, y en el clímax. Verifica que el personaje esté completamente en el encuadre y apoyado (ajusta y, scale, x), que el borde y el tinte coincidan con la foto (ajusta lightMatch), que los subtítulos sean legibles y no estén tapados, y que las caras no estén ocultas por tarjetas. Corrige con sticky_update_scene y vuelve a renderizar.
5. Exporta con sticky_export_mp4 cuando el usuario esté listo. Tarda aproximadamente la duración de la película más la codificación. Informa el mp4Path.

Guía de gusto para cortos mudos emocionales

• Menos, pero más largos planos (4–8 s). Corta en strongBeats. Deja que heavy_sigh y slouch_lonely respiren durante al menos un ciclo completo (≥ 4.5 s).
• hoodUp: true = retraimiento / lluvia / ansiedad; capucha abajo = apertura, alivio.
• Mantén walkSpeed 0.4–0.6 para caminatas melancólicas, 1.2 para un trote decidido, 2.0+ solo para sprints culminantes.
• Empareja emoción y boca: crying + quiver, tired + sigh. En modo mudo nunca uses talking.
• Usa una capa ambiental por escena al volumen 0.4–0.8. Cambia las capas en los cortes para marcar un nuevo lugar.
• Para 9:16, mantén x ≈ 0.5 y scale 0.9–1.1. Los subtítulos y tarjetas se reposicionan automáticamente.

Ejemplo de storyboard

{
  "mode": "silent", "aspectRatio": "16:9-letterbox", "captionStyle": "cinematic", "fadeOutEnd": true,
  "scenes": [
    { "title": "3 AM", "background": "/abs/photos/bedroom.jpg", "gesture": "check_phone_dark", "emotion": "tired",
      "kenBurns": "push_in", "lightMatch": true, "ambientBed": "clock_ticking", "transitionType": "fade_black", "transitionDur": 1.2, "subtitle": "3:07 AM." },
    { "title": "Caminata bajo la lluvia", "background": "/abs/photos/street.jpg", "gesture": "pocket", "view": "threeQuarter", "hoodUp": true,
      "walkSpeed": 0.55, "walkInPlace": false, "x": 0.25, "foreground": "rain_streaks", "ambientBed": "rain_window",
      "lightMatch": true, "transitionType": "dissolve", "transitionDur": 1.2, "weight": 1.2 },
    { "title": "Amanecer", "background": "/abs/photos/sunset.jpg", "gesture": "look_back_horizon", "view": "back", "wind": 0.6,
      "lightMatch": { "rim": 0.8, "side": "back" }, "kenBurns": "pull_out", "ambientBed": "night_wind",
      "transitionType": "fade_white", "subtitle": "Pero el sol seguía saliendo." }
  ],
  "fxMarkers": [ { "type": "phone_vibrate", "timeSec": 0.8 } ]
}