Sticky Director — Manuel du réalisateur de films IA

Que fait Sticky Director — Manuel du réalisateur de films IA ?

Ce dépôt est un moteur d'animation et de film muet local. Un personnage rigide en silhouette noire portant un hoodie gris agit devant des photos (par exemple des images Google Flow), avec musique, son d'ambiance, mouvements de caméra et sous-titres. Vous le dirigez via les outils MCP (.mcp.json enregistre sticky-studio → node mcp-server.js) ou via la CLI (node cli.js …). Les deux démarrent server.js automatiquement, et les actions canvas ouvrent le studio (Chromium sans tête quand il n'y a pas d'affichage).

Passez toujours des chemins absolus. Chaque ID ci-dessous est validé. Les valeurs inconnues sont renvoyées comme warnings et ne sont pas appliquées, alors lisez les avertissements.

Exécution depuis Antigravity : si les outils MCP sticky-studio ne sont pas disponibles, utilisez la CLI depuis la racine du dépôt. Chaque outil MCP a un jumeau CLI (tableau ci-dessous) : node cli.js snapshot <t> <abs.png> écrit un PNG que vous pouvez ouvrir avec la vision. Toutes les commandes démarrent le serveur studio automatiquement.

---

Outils (MCP) ↔ CLI

Outil MCP	CLI	Ce qu'il fait
sticky_status	node cli.js status	Mode, aspect, durée, BPM / nombre de temps, onglet connecté, liste des scènes
sticky_get_project	node cli.js get-project [out.json]	Projet complet au format agent plat (scènes, fxMarkers, mediaCards, audio.beats/strongBeats, backgrounds + lightProfile)
sticky_load_audio	node cli.js load-audio <chemin> --mode silent	Charger musique/voix off → {duration, bpm, beats[], strongBeats[]}
sticky_import_photos	node cli.js import-photos <p1> <p2> … [--auto-build]	Enregistrer des photos → [{bgId, name, path, width, height, lightProfile}]
sticky_apply_template	node cli.js template <id> [--no-photos]	Charger un storyboard de film muet adapté à l'audio et aux photos
sticky_set_project	node cli.js set-project <fichier.json | '{…}'>	Pousser un storyboard complet ou partiel (seules les clés que vous envoyez sont appliquées)
sticky_update_scene	node cli.js update-scene <index|id> '{…}'	Modifier une scène
sticky_split_scene	node cli.js split <tempsSec> [--no-snap]	Couper à un instant, en s'accrochant au temps le plus proche (±0,35 s)
sticky_add_fx	node cli.js add-fx <type> <tempsSec> [--duration s]	Punch caméra / SFX / card
sticky_render_frame	node cli.js snapshot <tempsSec> [out.png]	Image exacte en PNG (MCP la renvoie aussi comme image)
sticky_export_mp4	node cli.js export	Rendu en temps réel → exports/sticky_video_*.mp4 (60 images/s H.264 + AAC)

get_status, get_project, set_project et update_scene fonctionnent également sans onglet studio ouvert : ils lisent et écrivent projects/live_state.json, et le studio charge cela quand il se connecte.

---

Identifiants de référence

Émotions (10)

id	utilisation
neutral	par défaut, calme
happy	chaleur, soulagement, petites victoires
tired	3h du matin, épuisement, fatigue
crying	chagrin, effondrement (associer à silentMouth: quiver)
angry	frustration
shocked	panique, prise de conscience
skeptical	doute, regard de côté
confused	moments "?"
excited	excitation (yeux étoilés)
deadpan	vide, engourdissement

Gestes (18) — gesture

id	description	meilleure vue
pocket	mains dans les poches du hoodie (défaut cool)	n'importe
idle	bras détendus (balancent en marchant)	n'importe
talking	mains réactives au rythme audio (voix off)	face
explain	deux paumes ouvertes	face
point_screen	pointe sur le côté (vers une carte média)	face
point_viewer	pointe vers la caméra	face / 3/4
crossed	bras croisés	face
facepalm	main sur le visage	face
hands_head	mains sur la tête (panique)	face
shrug	haussement d'épaules, paumes vers le haut	face
wave	faire signe	face
typing	assis à un bureau et tape (bureau + tabouret dessinés)	auto 3/4–côté
slouch_lonely	affalé, tête baissée, respiration lourde lente	face / 3/4
heavy_sigh	cycle de 4,5 s : inspire → retient → s'affaisse (soupir automatique)	face / 3/4
check_phone_dark	tient un téléphone lumineux ; cône de lumière bleue sur le visage et le hoodie	face / 3/4
sit_curb_hug_knees	assis par terre en serrant les genoux, tête baissée	auto 3/4
look_back_horizon	debout regardant le paysage, vent dans le hoodie	back / 3/4
pull_hood_up	action : attrape et remonte la capuche (~2,3 s depuis le début de la scène)	face

Corps et pose — clés

clé	valeurs
pose	rig (articulé, par défaut) · sprites v1 : front, bust, side, back
view	front, threeQuarter, side, back
hoodUp	true / false (capuche dessinée sur chaque vue ; la vue de dos la met par défaut)
walkSpeed	0 immobile · 0.1–1.0 marche · 1.1–2.5 jogging → sprint
walkDir	left, right
walkInPlace	true (tapis roulant) / false (se déplace dans le cadre, boucle)
wind	0..1 (ourlet, cordons, capuche)
silentMouth	closed (par défaut) · sigh · quiver (pleurs / anxiété)
handLeft, handRight	auto, relaxed, open_palm, pointing, fist, holding_prop, in_pocket
prop	none, phone, mug, mic, controller, book
spineLean, headTilt, headNod	degrés (≈ −25…25 ; headNod + = regarder vers le bas)
ikPins	{ rightHand|leftHand|rightFoot|leftFoot|head: {x, y} } en unités rig (origine = sol entre les pieds, +x = direction de face, vers le haut = y négatif ; la tête est près de y ≈ −300, les mains pendent près de y ≈ −130). {} efface
x, y, scale, flipX	position 0..1 (x 0,5 = centre ; y ≈ 0,55 = debout sur le tiers inférieur), taille (1 = défaut), miroir
motion	breathe (défaut pour le muet), talk_bounce, walk, shake (tremblement), float, none
emotion	voir le tableau ci-dessus

Arrière-plans — background

Intégrés : paper_sketch, cozy_night, rainy_window, streetlight (réverbère de minuit), classroom (bureau au coucher du soleil), dark_spotlight, rooftop_dusk, green_screen. Photos : utilisez le bgId retourné par sticky_import_photos, ou mettez simplement le chemin absolu de la photo dans background (elle est importée automatiquement).

Photo : caméra & profondeur

clé	valeurs
kenBurns	none, push_in, pull_out, drift_left, drift_right, breathing (la photo bouge à 100%, le personnage à 30% → parallaxe)
foreground	none, bokeh, rain_streaks, window_reflection
camera	static, zoom_in, zoom_out, pan_right, handheld (s'applique par-dessus kenBurns)
atmosphere	dust (luit au rythme de la musique), rain, none
dutchScene / spotlightScene	horizon incliné sur toute la scène / arrière-plan assombri de 60%

Correspondance lumineuse (harmonisation photo) — lightMatch

true = recommandé (tint 0.35, rim 0.55, exposure 0.5) · false = désactivé · un nombre 0..1 = intensité générale · ou { tint, rim, exposure, side } avec side = auto (depuis la photo) | left | right | back (contre-jour, les deux bords). Utilisez true sur chaque scène photo. Augmentez rim (0.7–0.9) pour les couchers de soleil et les horizons en contre-jour ; utilisez side: "back" pour look_back_horizon.

Transitions (comment une scène ENTRE) — transitionType, transitionDur (0–2 s)

cut · dissolve (les deux plans sont rendus en direct et mélangés) · fade_black (passage du temps, solitude) · fade_white (flash-back, prise de conscience, espoir). La scène 0 avec dissolve ou fade_black apparaît en fondu depuis le noir. fadeOutEnd: true fond le film en noir à la fin.

Ambiances sonores (continues, par scène) — ambientBed, ambientVol 0..1

id	ambiance
none	—
rain_window	pluie douce + tonnerre lointain (rend aussi les pas mouillés)
night_wind	vent solitaire de minuit
vinyl_crackle	poussière lo-fi chaleureuse
clock_ticking	tic-tac réverbérant à 60 BPM : 3h du matin, insomnie, vide
heartbeat	battement cardiaque sourd : anxiété, panique
crowd_muffle	murmure filtré : seul dans une foule

Marqueurs d'effets — sticky_add_fx / fxMarkers: [{type, timeSec, …}]

• Punches caméra : snap_zoom (1.0→1.25× ressort sur le visage), dutch_tilt, shake, spotlight (+ duration, intensity 0..3, dir ±1 pour le hollandais)
• SFX / bruitages (10) : whoosh, pop, vine_boom, record_scratch, shutter, typing, footstep_wet, heavy_sigh_breath, phone_vibrate, door_close_echo (+ volume)
• Les scènes peuvent aussi définir transitionSfx (un SFX joué au cut) et foley: true (pas automatiques sur chaque frappe de talon + soupirs ; activé par défaut en mode muet)
• Cartes média : type: "card" avec card: {kind: image|meme|post|note, text, imagePath, side: auto|left|right, hold, size}

Clés au niveau du projet (sticky_set_project)

clé	valeurs
mode	silent (musique uniquement, la bouche ne synchronise jamais les lèvres) · voiceover
aspectRatio	16:9 · 16:9-letterbox (barres cinéma 2.35:1) · 9:16 (Shorts / Reels / TikTok, 720×1280)
fadeOutEnd	true ou secondes
masterAmbientVol	0..1
captionStyle	cinematic (sérif film muet), pop, karaoke, classic, off, ou {mode, highlight, position: bottom|middle|top, chunk, uppercase, size}
snapToBeats	par défaut true : les cuts s'accrochent au temps le plus proche
scenes	objets de scène plats. Timing : donnez start/end sur toutes les scènes, ou aucune et utilisez duration / weight (réparti sur la musique)
fxMarkers	voir ci-dessus
mediaCards	[{sceneIndex | timeSec, kind, text, imagePath, appear, hold, side}]

Templates — sticky_apply_template

loneliness_3am (téléphone dans le noir → marche sous la pluie avec capuche → genoux serrés sur le trottoir → horizon de l'aube) · social_anxiety (affalé dans un coin + murmure de la foule → panique avec battement de cœur → sortir au vent → soupir de soulagement) · burnout (taper au bureau → regard vide avec l'horloge → fondu au noir → marche sous la pluie) · discipline (réveil fatigué → remonter la capuche → jogging 1,2× → sprint 2,0× dans le lever du soleil).

---

Flux de réalisation

1. Regarder et écouter. Regardez les photos de l'utilisateur avec la vision (lisez les fichiers image) et décidez de l'arc émotionnel (par ex. isolement → point de rupture → libération → espoir). Chargez la musique avec sticky_load_audio {path, mode: "silent"} et notez duration, bpm et strongBeats (les meilleurs points de coupe).
2. Importer et mapper les photos. sticky_import_photos {paths: [...]} dans l'ordre de l'histoire. Utilisez chaque lightProfile (tone chaud/froid, brightness, lightFrom) pour choisir le tempo. Les pièces sombres et froides conviennent pour check_phone_dark / slouch_lonely + clock_ticking. Les rues pluvieuses conviennent aux marches pocket avec capuche + rain_window + rain_streaks. Les couchers de soleil et les horizons conviennent pour look_back_horizon (vue de dos, lightMatch {rim: 0.8, side: "back"}) + night_wind.
3. Construire le storyboard avec un seul appel sticky_set_project : mode: "silent", captionStyle: "cinematic", fadeOutEnd: true, et une scène par photo. Donnez à chaque scène background (le chemin ou bgId), gesture, emotion, view, hoodUp, kenBurns, lightMatch: true, ambientBed, transitionType (première scène fade_black, principalement dissolve 1.0–1.5 s, fade_black pour les sauts temporels, fade_white pour le tournant vers l'espoir), des subtitles poétiques et courts (≤ 8 mots, ou vide), et weight pour l'emphase. Ajoutez quelques fxMarkers (phone_vibrate, door_close_echo, un snap_zoom sur le pic émotionnel). Vérifiez les warnings dans le résultat.
4. Inspecter visuellement. sticky_render_frame à 2–3 moments clés : dans la première scène (après son fondu, ~1,5 s), au milieu du film, et au climax. Vérifiez que le personnage est entièrement dans le cadre et au sol (ajustez y, scale, x), que le rebord et la teinte correspondent à la photo (ajustez lightMatch), que les sous-titres sont lisibles et non couverts, et que les visages ne sont pas cachés par des cartes. Corrigez avec sticky_update_scene et re-rendu.
5. Exporter avec sticky_export_mp4 quand l'utilisateur est prêt. Cela prend environ la durée du film plus l'encodage. Signalez le mp4Path.

Guide de style pour les courts muets émotionnels

• Peu de plans, plus longs (4–8 s). Coupez sur les strongBeats. Laissez heavy_sigh et slouch_lonely respirer pendant au moins un cycle complet (≥ 4,5 s).
• hoodUp: true = repli / pluie / anxiété ; capuche baissée = ouverture, soulagement.
• Gardez walkSpeed 0.4–0.6 pour les marches mélancoliques, 1.2 pour un jogging déterminé, 2.0+ seulement pour les sprints culminants.
• Associez émotion et bouche : crying + quiver, tired + sigh. En mode muet, n'utilisez jamais talking.
• Utilisez une ambiance sonore par scène à un volume de 0.4–0.8. Changez d'ambiance aux cuts pour marquer un nouveau lieu.
• Pour le 9:16, gardez x ≈ 0.5 et scale 0.9–1.1. Les sous-titres et les cartes se repositionnent automatiquement.

Exemple de storyboard

{
  "mode": "silent", "aspectRatio": "16:9-letterbox", "captionStyle": "cinematic", "fadeOutEnd": true,
  "scenes": [
    { "title": "3h du matin", "background": "/abs/photos/chambre.jpg", "gesture": "check_phone_dark", "emotion": "tired",
      "kenBurns": "push_in", "lightMatch": true, "ambientBed": "clock_ticking", "transitionType": "fade_black", "transitionDur": 1.2, "subtitle": "3:07 du matin." },
    { "title": "Marche sous la pluie", "background": "/abs/photos/rue.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": "Aube", "background": "/abs/photos/coucher_soleil.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": "Mais le soleil s'est quand même levé." }
  ],
  "fxMarkers": [ { "type": "phone_vibrate", "timeSec": 0.8 } ]
}

---