sijanpaudel6-hash/sticky-director

Sticky Director — AI导演操作手册

该仓库是一个本地动画和无声电影引擎。一个穿着灰色连帽衫的黑色剪影角色在照片（例如 Google Flow 图像）前表演，配有音乐、环境音、摄像机移动和字幕。你通过 MCP 工具（.mcp.json 注册 sticky-studio → node mcp-server.js）或通过 CLI（node cli.js …）进行导演。两者都会自动启动 server.js，并且画布操作会打开工作室（无显示时使用无头 Chromium）。

始终传递绝对文件路径。下面的每个 ID 都会经过验证。未知值会作为 warnings 返回，并且不会被应用，因此请阅读警告。

从 Antigravity 运行： 如果 sticky-studio MCP 工具不可用，请从仓库根目录使用 CLI。每个 MCP 工具都有一个 CLI 对等命令（下表）；node cli.js snapshot <t> <abs.png> 会写入一个 PNG 文件，你可以用视觉模型打开。所有命令都会自动启动工作室服务器。

---

工具 (MCP) ↔ CLI

MCP 工具	CLI	功能
sticky_status	node cli.js status	模式、画幅、时长、BPM / 节拍数、已连接的标签页、场景列表
sticky_get_project	node cli.js get-project [out.json]	以扁平代理格式获取完整项目（场景、特效标记、媒体卡片、音频节拍/强节拍、背景 + 光照配置文件）
sticky_load_audio	node cli.js load-audio <path> --mode silent	加载音乐/画外音 → {duration, bpm, beats[], strongBeats[]}
sticky_import_photos	node cli.js import-photos <p1> <p2> … [--auto-build]	注册照片 → [{bgId, name, path, width, height, lightProfile}]
sticky_apply_template	node cli.js template <id> [--no-photos]	加载一个适配音频和照片的无声电影故事板
sticky_set_project	node cli.js set-project <file.json | '{…}'>	推送完整或部分故事板（仅应用你发送的键）
sticky_update_scene	node cli.js update-scene <index|id> '{…}'	修补一个场景
sticky_split_scene	node cli.js split <timeSec> [--no-snap]	在指定时间分割，吸附到最近的节拍（±0.35 秒）
sticky_add_fx	node cli.js add-fx <type> <timeSec> [--duration s]	摄像机冲击 / SFX / card
sticky_render_frame	node cli.js snapshot <timeSec> [out.png]	以 PNG 格式获取精确帧（MCP 也将其作为图像返回）
sticky_export_mp4	node cli.js export	实时渲染 → exports/sticky_video_*.mp4（60 fps H.264 + AAC）

get_status、get_project、set_project 和 update_scene 在没有打开工作室标签页的情况下也能工作：它们读取和写入 projects/live_state.json，并且工作室在连接时会加载该文件。

---

参考 ID

情感 (10 种)

id	用途
neutral	默认，平静
happy	温暖，解脱，小胜利
tired	凌晨 3 点，倦怠，精疲力竭
crying	悲伤，崩溃（搭配 silentMouth: quiver）
angry	沮丧
shocked	恐慌，醒悟
skeptical	怀疑，斜眼
confused	“？”时刻
excited	兴奋（星星眼）
deadpan	空虚，麻木

手势 (18 种) — gesture

id	描述	最佳视角
pocket	双手插在连帽衫口袋里（默认放松状态）	任意
idle	手臂放松（走路时摆动）	任意
talking	音频反应式手部节拍（画外音）	正面
explain	双手掌心向外	正面
point_screen	侧向指点（指向媒体卡片）	正面
point_viewer	指向摄像机	正面 / 3/4
crossed	双臂交叉	正面
facepalm	手捂脸	正面
hands_head	双手抱头（恐慌）	正面
shrug	耸肩，掌心向上	正面
wave	挥手打招呼	正面
typing	坐在桌边打字（自动绘制桌子和凳子）	自动 3/4–侧面
slouch_lonely	深深瘫坐，头低垂，缓慢沉重呼吸	正面 / 3/4
heavy_sigh	4.5 秒循环：吸气 → 屏气 → 瘫软（自动呼吸音效）	正面 / 3/4
check_phone_dark	手持发光的手机；蓝色光锥照在脸和连帽衫上	正面 / 3/4
sit_curb_hug_knees	坐在地上抱膝，头低下	自动 3/4
look_back_horizon	站着凝视远方，风吹动连帽衫	back / 3/4
pull_hood_up	动作：伸手向后拉起兜帽（从场景开始约 2.3 秒）	正面

身体与姿势键

键	值
pose	rig（关节式，默认）· v1 精灵：front、bust、side、back
view	front、threeQuarter、side、back
hoodUp	true / false（兜帽在每个视角都绘制；背面视角默认为拉起）
walkSpeed	0 闲置 · 0.1–1.0 行走 · 1.1–2.5 慢跑 → 冲刺
walkDir	left、right
walkInPlace	true（原地踏步） / false（在画面中移动，循环环绕）
wind	0..1（衣摆、抽绳、兜帽）
silentMouth	closed（默认）· sigh · quiver（哭泣 / 焦虑）
handLeft、handRight	auto、relaxed、open_palm、pointing、fist、holding_prop、in_pocket
prop	none、phone、mug、mic、controller、book
spineLean、headTilt、headNod	角度（≈ −25…25；headNod + = 向下看）
ikPins	{ rightHand|leftHand|rightFoot|leftFoot|head: {x, y} }（以角色坐标系为单位；原点在双脚之间的地面，+x 为面向方向，向上为负 y；头部接近 y ≈ −300，手垂在 y ≈ −130 附近）。{} 清除
x、y、scale、flipX	位置 0..1（x 0.5 = 居中；y ≈ 0.55 = 站在下三分之一处）、大小（1 = 默认）、镜像
motion	breathe（无声默认）、talk_bounce、walk、shake（颤抖）、float、none
emotion	见上表

背景 — background

内置：paper_sketch、cozy_night、rainy_window、streetlight（午夜路灯）、classroom（夕阳下的桌子）、dark_spotlight、rooftop_dusk、green_screen。 照片：使用 sticky_import_photos 返回的 bgId，或直接将照片的绝对路径放在 background 中（它会自动导入）。

照片摄像机与深度

键	值
kenBurns	none、push_in、pull_out、drift_left、drift_right、breathing（照片移动 100%，角色移动 30% → 视差）
foreground	none、bokeh、rain_streaks、window_reflection
camera	static、zoom_in、zoom_out、pan_right、handheld（在 kenBurns 之上应用）
atmosphere	dust（随着音乐节拍发光）、rain、none
dutchScene / spotlightScene	整个场景倾斜地平线 / 背景变暗 60%

光照匹配（照片和谐） — lightMatch

true = 推荐（tint 0.35, rim 0.55, exposure 0.5）· false = 关闭 · 数字 0..1 = 整体强度 · 或 { tint, rim, exposure, side }，其中 side = auto（从照片推断）| left | right | back（背光，两个边缘）。 在每个照片场景上都使用 true。 对于日落和背光地平线，提高 rim（0.7–0.9）；对于 look_back_horizon，使用 side: "back"。

过渡（场景如何进入） — transitionType、transitionDur（0–2 秒）

cut · dissolve（两个镜头实时渲染并混合）· fade_black（时间流逝，孤独）· fade_white（闪回、醒悟、希望）。场景 0 使用 dissolve 或 fade_black 会从黑色淡入。fadeOutEnd: true 会在影片结束时淡出为黑色。

环境音床（持续，每场景） — ambientBed、ambientVol 0..1

id	情绪
none	—
rain_window	柔和雨声 + 远处雷声（也会让脚步声变得潮湿）
night_wind	孤独的午夜风声
vinyl_crackle	温暖的 lo-fi 灰尘声
clock_ticking	60 BPM 混响滴答声：凌晨 3 点、失眠、空虚
heartbeat	深沉低沉的心跳声：焦虑、恐慌
crowd_muffle	低通滤波的嗡嗡声：在拥挤的房间里独自一人

特效标记 — sticky_add_fx / fxMarkers: [{type, timeSec, …}]

• 摄像机冲击： snap_zoom（1.0→1.25× 弹性缩放到脸部）、dutch_tilt、shake、spotlight（+ duration、intensity 0..3、dir ±1 用于荷兰角）
• SFX / 拟音 (10 种)： whoosh、pop、vine_boom、record_scratch、shutter、typing、footstep_wet、heavy_sigh_breath、phone_vibrate、door_close_echo（+ volume）
• 场景也可以设置 transitionSfx（在剪辑点播放的 SFX）和 foley: true（每次脚跟落地时自动播放脚步声 + 叹息呼吸；在无声模式下默认开启）
• 媒体卡片： type: "card"，配合 card: {kind: image|meme|post|note, text, imagePath, side: auto|left|right, hold, size}

项目级键 (sticky_set_project)

键	值
mode	silent（仅音乐，嘴部从不唇形同步）· voiceover
aspectRatio	16:9 · 16:9-letterbox（2.35:1 影院黑边）· 9:16（Shorts / Reels / TikTok，720×1280）
fadeOutEnd	true 或秒数
masterAmbientVol	0..1
captionStyle	cinematic（无声电影衬线体）、pop、karaoke、classic、off、或 {mode, highlight, position: bottom|middle|top, chunk, uppercase, size}
snapToBeats	默认 true：剪辑吸附到最近的节拍
scenes	扁平场景对象。时间安排：在所有场景上给出 start/end，或都不给并使用 duration / weight（在音乐上分配）
fxMarkers	见上文
mediaCards	[{sceneIndex | timeSec, kind, text, imagePath, appear, hold, side}]

模板 — sticky_apply_template

loneliness_3am（黑暗中看手机 → 兜帽雨行 → 抱膝坐路边 → 黎明地平线）· social_anxiety（瘫坐角落 + 人群嗡嗡声 → 心跳加速恐慌 → 走到外面迎风 → 解脱叹息）· burnout（在桌前打字 → 空虚凝视时钟 → 淡出至黑 → 雨行）· discipline（疲惫起床 → 拉起兜帽 → 1.2× 慢跑 → 2.0× 冲刺冲入日出）。

---

导演工作流

1. 观察与聆听。 查看用户的照片（用视觉模型读取图像文件）并决定情感弧线（例如 孤立 → 临界点 → 释放 → 希望）。使用 sticky_load_audio {path, mode: "silent"} 加载音乐，并记录 duration、bpm 和 strongBeats（最佳剪辑点）。
2. 导入并映射照片。 按故事顺序使用 sticky_import_photos {paths: [...]}。利用每个 lightProfile（tone 暖/冷、brightness、lightFrom）来挑选节拍。黑暗凉爽的房间适合 check_phone_dark / slouch_lonely + clock_ticking。雨街适合兜帽 pocket 行走 + rain_window + rain_streaks。日落和天际线适合 look_back_horizon（背面视角，lightMatch {rim: 0.8, side: "back"}）+ night_wind。
3. 构建故事板，通过一次 sticky_set_project 调用：mode: "silent"、captionStyle: "cinematic"、fadeOutEnd: true，并且每张照片一个场景。为每个场景指定 background（路径或 bgId）、gesture、emotion、view、hoodUp、kenBurns、lightMatch: true、ambientBed、transitionType（第一个场景 fade_black，大部分使用 dissolve 1.0–1.5 秒，时间跳转用 fade_black，转向希望时用 fade_white）、简短诗意的 subtitle（≤ 8 个词，或留空）、以及用于强调的 weight。添加几个 fxMarkers（phone_vibrate、door_close_echo、在情感高峰处加一个 snap_zoom）。检查结果中的 warnings。
4. 视觉检查。 在 2–3 个关键时刻使用 sticky_render_frame：在第一个场景内部（淡入后，约 1.5 秒）、影片中间、以及高潮部分。检查角色是否完全在画面内并且接地（调整 y、scale、x）、边缘光与色调是否匹配照片（调整 lightMatch）、字幕是否可读且未被遮挡、以及面部是否未被卡片遮挡。使用 sticky_update_scene 修复并重新渲染。
5. 导出 当用户准备好时使用 sticky_export_mp4。导出时间大约等于影片长度加编码时间。报告 mp4Path。

情感无声短片品位指南

• 更少、更长的镜头（4–8 秒）。在 strongBeats 上剪辑。让 heavy_sigh 和 slouch_lonely 至少呼吸一个完整周期（≥ 4.5 秒）。
• hoodUp: true = 退缩 / 雨 / 焦虑；兜帽放下 = 开放、解脱。
• 忧郁行走时保持 walkSpeed 0.4–0.6，坚定慢跑时 1.2，2.0+ 仅用于高潮冲刺。
• 搭配情感与嘴部：crying + quiver、tired + sigh。在无声模式下切勿使用 talking。
• 每个场景使用一个环境音床，音量 0.4–0.8。在剪辑点更换音床以标记新地点。
• 对于 9:16，保持 x ≈ 0.5 和 scale 0.9–1.1。字幕和卡片会自动重新定位。

故事板示例

{
  "mode": "silent", "aspectRatio": "16:9-letterbox", "captionStyle": "cinematic", "fadeOutEnd": true,
  "scenes": [
    { "title": "凌晨 3 点", "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。" },
    { "title": "雨行", "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": "黎明", "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": "但太阳还是照常升起了。" }
  ],
  "fxMarkers": [ { "type": "phone_vibrate", "timeSec": 0.8 } ]
}

---