kinema-depth

name	kinema-depth
description	把一段实拍视频的人物运动复刻到本项目的角色身上。用户提到照着这段视频动、复刻动作、翻跳同一支舞、让我的角色跳这个、把实拍运动迁移到 AI 片段，或手上有参考视频想让角色照做时使用；引擎在本机把源片处理成人物深度与骨骼的控制视频，绑到分镜后作参考视频发出——运动来自源片，外观来自分镜图。
metadata	{"kinema-managed-by":"agent/manifest.json","kinema-kind":"capability","kinema-status":"stable","kinema-version":"2.0.0","kinema-owner":"Kinema","kinema-source":"workspace","kinema-trust":"first-party","kinema-digest":"sha256:ae2c0326b304837d8366d353b1261fd606f63a69ae64eb9f13c1e22b410ff0c4"}

kinema-depth · 深度捕捉（实拍运动 → 你自己的角色）

运动来自源片，外观来自你自己的设定。 拿一段实拍表演片当运动源，让你这个项目的 角色把同一套动作演一遍：引擎在本机把源片处理成只含人物深度浮雕与 OpenPose 骨骼的 控制视频（去场景、去人脸、去服装，多人各自成骨），按镜长裁段绑到分镜上，gen-video 时作 reference_video 发出。外观那一路发什么随画风档变——缺省是分镜图领衔， 写实人物档走设定图领衔（见铁律②），两种都不取自源片。

成本口径：处理全程本机 CPU，不花 API 的钱（每源秒约十几秒）。付费只在 gen-video 那一步，且输入视频秒数叠加在输出秒数之上——5 镜 × 12 秒就是 60 输出秒 + 60 输入秒。

本 skill 不进 project.skill。 它是能力工法包，与画风 skill 并肩调用： 项目照常 --profile <画风> --skill <该画风的 route skill>，深度捕捉在章节里按需用。

直接启动整套流程（/kinema-depth <源片或主题> 即可）

1. Read ../kinema/SKILL.md —— 立项、设定、分镜、生图、 合成的全部通用节点都在那里，本文只写与它不同的部分。

2. 立项照常，画风由用户的题材决定，不由本 skill 决定：

   python3 -m kinema project new --title "X" --id x --profile <画风> --skill <画风 route skill>
   

3. 设定集先行，--skip-design 禁用——理由见「铁律②」。

4. 每章对应一段源片，按下面这条顺序走。顺序本身是省钱与省时的：贵的、慢的、 一错就得全推倒的都排在前面，两条互不依赖的长任务并起来跑。

 ① character/scene add            ─┐ 零成本，先把设定集立齐
 ② project refs（逐张人工审）      │ 每张约 1.5 分钟；错了改 desc 重出，别往下走
 ③ control build（同时开跑）       ─┘ 每源秒约十几秒 CPU，与 ② 互不依赖
 ④ control list 体检 people/tracks   幽灵轨迹与人数不符在这里拦掉，别等到出图
 ⑤ ChapterPlan 一次写齐            characters/scenes/face_visibility + 两档 PromptSpec
 ⑥ lint --strict 清零              零成本，把 camera/双语/代词这几条一次扫掉
 ⑦ gen-image 首镜 + 差异最大的一镜   ★人工审外观锁死，再出其余
 ⑧ control bind 框区间             dur 随之对齐，改区间会让已出的片段过期；有 beats 的镜再 sketch use --guide control
 ⑨ gen-video --dry-run             ★审路线（写实档看是不是降级形态）与报价
 ⑩ 出片 → control compare 三列对照

三个「别走反」的点：② 与 ③ 并起来跑（一个是 API 等待、一个是本机 CPU，串行 白等一倍）；⑥ 在 ⑦ 之前（lint 零成本，出图之后再改提示词就是重出一轮）； ⑧ 在 ⑦ 之后（分镜图是对位的参照，先有图才知道景别与站位往哪对；绑定与改区间只让 已出的片段过期，不动分镜图）。

两条硬前置

第一次跑之前必须落实，缺一条就是在花钱那一步才失败：

1. 参考视频要先上云。 Seedance 的 reference_video 只收公网 URL，gen-video 在发请求前 把控制段按需上传；上云能力（provider、桶、区域、密钥）没配齐时直接报错、一帧不发。判据是 能力齐备而不是 media.backend: oss——backend 留 local，storage.yaml 的 media 段只选 provider，桶、区域与密钥走 secrets（KINEMA_OSS_BUCKET / KINEMA_OSS_REGION / KINEMA_OSS_ACCESS_KEY / KINEMA_OSS_SECRET_KEY），其余媒体照常留在本地。
2. 感知栈与权重要显式装。 pip install -e "engine[control]" 之后再跑一行 pip install --no-deps rtmlib，然后 python3 -m kinema control fetch 拉约 115MB 权重。 权重不静默下载，就绪状态只在 doctor 的「可选依赖 control」一行——setup --check 的 ready=true 不包含它。

核心工法

① 处理源片（零 API 花费）

cd engine
python3 -m kinema control build --chapter x/ch01 --source dance.mp4
python3 -m kinema control list --chapter x/ch01

产物三条视频：control.mp4 是发给模型的纯控制视频，compare.mp4 是源片与深度的 二合一对照（竖片左右并排、横片上下叠放），审看只看它——单看深度判不出骨骼有没有 跟住动作；styled.mp4 是白色浮雕精细版，只给人看，--no-styled 可跳过、省约三成时间。

几条处理期的规矩：重传同一源片得新素材（id 是文件名加内容指纹，撞了缀 -2）， 要就地重建须显式 --asset <既有 id>；同一章的 build 走 .build.lock 互斥，多条源片 串行处理；--bind-shot N 处理完直接绑到镜 N（区间从 0 起按镜秒数），Studio 走的就是它。

处理完先体检再绑，control list --json 逐条读三个数：

• people 比画面里的真人多 ＝ 有幽灵轨迹（背景里的车、反光被当成了人）， 成片里会多出一条乱挥的肢体。看 tracks[].frames：真人那条接近总帧数， 几十帧的短轨就是幽灵。实测一条 15 秒的多人街舞出了 14 条轨迹、其中 8 条不足 40 帧——这种素材直接换，救不回来；
• 真人那条 frames 远小于总帧数 ＝ 大量帧检不出骨架（运动模糊/光线太暗）， 做出来骨骼一闪一闪；
• people 与你这一镜的出场角色数对不上 ＝ 先解决人数（见「对位纪律」）。

源片准入与切口判断见 references/source-and-cut.md。 上传与预览走 Studio 控制台时，按 ../kinema/references/studio-handoff.md 先启动或复用控制台再提示用户操作。

② 框区间：起点与终点都由你定

绑定收 --start 与 --end，框多长这一镜就多长——引擎按 round(终点-起点) 定段， 并把该镜 dur 对齐过去（控制段与成片 1:1 是运动不被拉伸的前提）。源片前后不要的 几秒直接框掉，不必先拿 ffmpeg 剪一遍。

control list 给出素材总长；strip.png 是每半秒一格的缩略条，切口在它上面定。 段长恒 4~15 秒（见铁律③），落在区间外直接拒绝、不静默钳。一段 60 秒的舞 = 5 镜 × 12 秒。

切口位置是唯一能软化观感的杠杆：落在动作停顿、重心交换、转身的那一刻， 不要落在时钟整数上。

Studio 的「◇ 绑定分镜」把这件事做成了可视的：缩略条上拖双把手，右边同步播 二合一（左源片、右深度），松手即可确认这一段的骨骼贴不贴得住动作。

③ 一份 ChapterPlan 建齐所有镜

{"op": "add", "id": 1, "fields": {"dur": 12, "narration": ""},
 "prompt_spec": {"subject": "…", "action": "…", "composition": "…"}}

同一份计划里的章级字段：motion: "native"（强制显式，见铁律①）、 voiceover: "none"、control_video: true、control_bgm: true（成片配乐取源片 同区间音轨，见「声音设计」）。

narration: "" 合法——纯画面镜是本工法的常态。image 档 PromptSpec 写该段首帧上 角色的姿态，不写运动：运动由控制视频给。

④ 出图 → 绑定 → 审报价

python3 -m kinema lint --chapter x/ch01 --strict
python3 -m kinema gen-image --chapter x/ch01 --only 1        # 首镜试拍，★人工审
python3 -m kinema gen-image --chapter x/ch01                 # 审过再出全章
python3 -m kinema control bind --chapter x/ch01 --shot 1 --asset <素材id> --start 2 --end 14
python3 -m kinema gen-video --chapter x/ch01 -m b --control --dry-run

run 一条龙不吃 --control，只认章级 control_video: true。要用 Seedance 2.5 出片就 gen-video --video-provider seedance-2.5（或 chapter set --video-provider 持久点名）： 1080p 只在 2.5，单价按档计；点名 2.5 不改变段长上限，参考视频输入侧仍恒 4~15 秒。

控制视频替代的是运动编排，不是画面；分镜图的角色随画风档变（见铁律②）： 非写实档走路线 A，分镜图是请求里的外观锚，gen-image 不可跳过；写实档 closeup 镜的分镜图整个不进请求，引擎在降级路线上也不要求它在盘，出它只为 人工对位与首镜审看——可以只出首镜。

铁律

① motion: "native" 必须显式写

无对白章的 motion 缺省是 dubbed，而参考视频只在 native 生效。不写就是： 控制视频一帧都不发、还买了一整章静音占位配音与强制曲库 BGM。这是本功能最贵的 静默失败。零成本的 lint 会点名（control_inert），但要在花钱之前跑。

② 顺序倒置：设定集与设定图先于任何分镜图

V2V 分支不发首/末帧，图一律挂 role=reference_image。官方的互斥规则拦的是 首/末帧与参考媒体混发，不是「图与视频不能同发」——参考图 09 张、参考视频 03 段可以自由组合（火山方舟 Seedance 2.0 文档）。所以设定图在这条路上有通道， 而且是承重的通道：

画风档	请求里的外观锚
非写实档（缺省路线 A）	分镜图领衔 + 设定图随发
写实档 · 标了 face_visibility: closeup	场景基准图 + 身份图 + 俯视图，分镜图整个不进请求

第二行是写实人物复刻的唯一可行形态。写实档下分镜图是挂着设定图生成的（图生图）， 人脸受信豁免天然不成立，路线 A 必被建任务时拒（HTTP 400、不计费）；能把受信身份图 （纯文生图、sheet_origin: t2i）送进请求的只有降级路线。判据与阶梯的实现真源在 docs/agents/photoreal-face.md。

所以：角色/道具/场景先立，project refs 出设定图并逐张人工审，首镜出图后再停一次， 确认外观锁死，再绑控制视频、再出其余镜。--skip-design 在本工法下禁用。

写实档的三件必做，缺一条整章发不出去：

1. 身份图必须是 sheet_origin: t2i（project refs 直出即是；refine 局改会把它 变成图生图、当场失去受信）；
2. 主场景基准图必须在盘——降级路线拿它顶 image 位；
3. 有可辨识正脸的镜标 face_visibility: closeup，直接从降级形态起步，省一次 注定被拒的往返。

②b 场景基准图在这条路上是取景地权威，出图后必须审

路线 A 下分镜图压着它、错了也不显形；一进降级形态它就是 @图片1，整镜的陈设、 材质与光线都以它为准。而一句宽泛的场景描述很容易被模型加戏——实测「浅灰色无缝 背景纸的摄影棚、画面内不出现道具」出来的是一面米色墙加一个拱形壁龛。

写死结构名词与否定项（「cyclorama 无缝背景棚，背景纸从后墙弯折延伸到地面， 除这面纸外没有任何墙体结构、拱门、隔断、家具」），并在 desc 里钉死时段与主光 （lint scene_daypart_missing 只提醒没表态的，不判对错）。改了 desc 要重出： project refs <项目> --only scene:<取景地> --force。

③ 段长 4~15 秒，seedance-2.5 也不例外

参考视频的服务端上限恒是 15 秒，与别名的 max_duration 无关（2.5 允许 30 秒 输出，参考视频仍只收 15）。control bind 对超出的镜直接拒绝并要求拆镜——静默截断 是拿 15 秒的运动去演 20 秒的镜。

④ 三路运动预演一镜只生效一条，绑了控制视频的镜不写 sketch.beats

3D 预演、控制视频、简笔板互斥，缺省仲裁按 previz > control > sketch，显式 shots[].guide 恒赢（sketch use --shot N --guide control 表态）。绑着控制视频的镜 不接受 previz 登记，有 previz 的镜要绑控制视频须 --replace-previz——两边都是 显式动作，不靠仲裁悄悄压掉另一路。写了 beats 不会顶掉控制视频，但通用 playbook 的 「秒级规划先行」在这一档不适用——运动已经逐帧给定，拍表是多余的第二套说法；而且 被压掉的拍表会触发 sketch_shadowed，lint --strict 下非零退出，要么 sketch use --guide control 表态，要么删掉 beats。

⑤ 出片后看三列对照

python3 -m kinema control compare --chapter x/ch01 --shot 1

源片段与控制段按素材画幅拼一条——竖片左右并排、横片上下叠放；成片段与素材同画幅时 接在后面，画幅取向相反（竖拍素材配 16:9 成片）时另起一行或一列；三路同一区间逐帧 对拍，control compare 顺带报成片相对控制段的偏移。Studio 里点分镜卡的 「◆ 深度」角标同样是它（第一次点会现拼几秒）。运动跟没跟住、外观有没有跑偏， 这一条比来回切三个窗口快得多。

提示词分工：控制视频带不动的那几样，正文必须补上

控制视频是黑底的深度浮雕 + 骨骼线。它带得动的只有三样：骨架的逐帧姿态、 人物的体积远近、以及人在画面里的位置与大小。除此之外它一无所有——

控制视频里没有	谁来给
头发、衣料的形态与惯性	secondary_motion
材质、皮肤、光的响应	creative_notes
机位怎么走	camera（必写，见下）
动作的力度与速度曲线	action_delta，写质地不写序列
声音	sound

所以 V2V 的 video 档 PromptSpec 与普通镜反着写：引擎已经在提示词开头发了 「严格跟随@视频1的运镜、走位与动作节奏」，action_delta 再复述一遍动作序列 是第二套运动权威，与控制视频逐帧打架。正确写法是只定质地：

"action_delta": "动作序列本身跟随参考视频，这里只定动作的质地：重心转移干脆，
                 每一次落点都有明确的制动而不是滑过去；发力顺序自髋而肩再到指尖，
                 收势时速度自然衰减、不做突然的硬停"
"secondary_motion": "高马尾随头颈转向甩出半拍滞后的弧线、末端有回弹；长袖袖口与
                     裤脚在急停时出现顺惯性的抖动褶皱；衣料贴身，不产生夸张飘动"

camera 必写，且多半是「机位固定」。 空着等于把运镜交给模型随机发挥，而它 手上正拿着一段有自己机位的参考视频——两边一撞，人物运动跟住了、画面却在莫名其妙 地推拉。源片是三脚架固定的就写死固定（lint 的 motion=5 也会点名缺 camera）。

对位纪律

控制视频与分镜图的人物比例、站位、朝向、景别不一致时，模型会在两者之间折中， 出来的既不是你的构图也不是源片的运动。引擎不自动对位——对位需要视觉理解， 这是指挥层的活。

按该段控制视频的首帧对齐这四项，落点随画风档变：非写实档写进 image_prompt （分镜图进请求）；写实档 closeup 镜的分镜图不进请求，对位改落在 video 档 PromptSpec 的 subject / composition——同一张表，换个落点：

项	怎么对
景别	源片全身入画就写全身，别写半身特写——模型会为了凑特写把动作裁掉
人物比例	人在画面里占多高，分镜图就画多高
站位	源片人偏左就写偏左；居中的写居中
朝向	正面/侧身/背身要一致，否则第一帧就要转体，动作从头错位

画幅取向要在立项时就对上。 裁段按章节画布贴合（那是承重的，不贴合成片会跟着 参考视频的几何走），于是一段竖拍装进 16:9 的章节后，cropdetect 量出来只有 608/1920 是画面、其余 68% 是补出来的黑边——发给模型的运动信息只占画面三分之一宽， 出来的人也就那么小一条。竖拍源片就把章节做成 9:16，或者绑定时用 --fit crop 填满（代价是切掉头顶脚底，全身舞蹈通常不划算）。混着来时以源片为准 改画布，比每镜去救构图便宜得多。

| 人数 | 出场角色必须与轨迹条数对上。三条骨架配一个已登记角色，模型得凭空造两张脸； 想要伴舞就在提示词里把他们写成逆光剪影（面部不可辨），或干脆各自登记角色 |

机体角色先登记 --subject-kind robot。 设定图模板缺省按人写（五官、瞳色、发际线、 肤质），一台机甲套上去会画成戴头盔的人；登记为 robot 后肖像区改成头部正面大特写、 头部正对镜头、无皮肤头发五官的机械口径。外貌描述里也把「纯机械构造、不是穿着装甲的人」 写在最前面。

平台版权审核是硬墙。 火山方舟对输出图与输出视频做版权识别，像已有 IP 就拒、不计费， 且设定图、分镜图、视频三级各判各的——上一级过了不代表下一级过。实测：接近某部作品配色与 天线组合的机甲，设定图连拒三次，换配色后设定图通过、同一机体进场景的分镜图仍被拒；一台 原创黑金机体图像两级都过、视频又被拒；仙侠人物三级一次通过。被拒的处置是改设计的辨识点， 不是同参数重跑。

声音设计

源片自己的音轨不进请求——盘上的控制段带源片同区间的音轨（审看用，@视频1 点开 即它），发给模型的是它的无声副本：模型的原生音是生成的、不会复现参考音频，把音乐塞进 参考只会给它加戏的机会。但那段音乐正是这支舞最对拍的配乐：控制段与 成片 1:1，章级 control_bgm: true 让合成用每个绑定镜的源片同一区间音轨作这一章的 主音乐：本地 ffmpeg 零成本，入轨响度与曲库同一口径，母线上不让路不闪避，模型原生音 退到环境床；未绑定的镜与源片无音轨的镜留静音。它与 native_bgm 同占母线且优先。复刻 舞蹈的章缺省就该写它；成片里的音乐来自 assemble，gen_clips/ 里的片段本身只有模型原生音。

配乐与成片动作的对拍由引擎量：music 阶段拿成片与控制段的运动能量做互相关，量出整体 偏移就平移那一镜的配乐起点（记在 gen.control.sync；control compare 与 Studio 对照片的信息栏都能看到）。它只救整体的早晚：模型在镜内忽快忽慢时相关会偏低、配乐不动， 那一镜只能重生成。

不要源片音乐时另两条路：章级 native_bgm: true + 曲库，或 audio_mode: "scored"

• 音频剧本（转 kinema-audio）。三者都与配音混烧互斥。这一步要主动带用户走—— assemble 前的曲库闸只在「曲库为空」或「native 从没表过态」时才发问。

重做意见词典

现象	根因	改法
动作跟不上源片	段落与镜长不是 1:1	control compare 出三列对照逐帧比；control list 看有没有「时长已变」，重新 bind 重裁
音乐比动作早或晚几拍	模型整体滞后或超前	music --force 重量对拍再 assemble；报「相关不足」则是镜内忽快忽慢，重生成这一镜
前几秒是废镜头	区间没框	bind --start --end 直接框掉，不必先剪源片
人物比例不匹配	分镜图与控制视频没对位	改 image_prompt 的景别/站位，重出这一镜的图
段落接缝跳	切口落在动作中途	重定切口到动作停顿处，omit 旧镜 + 追加新镜
换手换脚	源片是自拍镜像	先 ffmpeg -i 源片 -vf hflip 翻转.mp4，拿翻转后的片子重新 build
背景乱入	分镜图背景太强	控制视频只给运动，背景全靠分镜图——改图不改控制视频
成片没带控制视频	motion 不是 native、章级开关没开、provider 不支持参考视频，或这一镜被 previz / 显式 guide 压掉	lint --strict 会点名（control_inert / control_binding）；前两处都要显式，后者 sketch use --guide control
设定图或成片被平台以版权拒绝	设计落到了某部作品的辨识组合上	改设计（配色、天线、面甲这类识别点），不同参数重跑；拒绝不计费

何时不用

• 有走位调度要排、但没有实拍源——用 3D 导演台（previz）。
• 只要卡动作节奏、不需要复刻具体运动——用 kinema-sketchboard 的逐秒 beats。
• 纯氛围空镜或口播——两条都不需要，直接走 kinema 的缺省档。
• 源片是多机位剪辑过的片段——段内有剪辑点的源片处理出来是跳变的骨架， 先剪成单镜头的连续片段再来。