用 Viggle-Remake MCP 端到端重制两分钟 MV:White House Funk 样例的完整复现与源码级解析
用 Viggle-Remake MCP 端到端重制两分钟 MV:White House Funk 样例的完整复现与源码级解析
White House Funk 是 Viggle-Remake MCP 仓库里唯一一个"整片跑完"的样例:一段 121.8 秒的 MV 被整体换角,八位演出者被替换成八位美国政治人物,而运镜、动作、剪辑点和音轨全部保留。本文以该样例的说明文档 mcp/examples/white-house-funk/README.md 为主线,逐项拆解它的文件构成、复现命令、任务书写法、角色库格式与实测代价,并结合 MCP 服务端源码说明每一步背后的机制与失败边界。读完后你应当能够:用自己的素材跑通同一条流水线、读懂 result.json 的每一项、并且在渲染窗口、种子与修复轮次上做出正确取舍。
这个样例到底在演示什么
按样例文档的定义,这是一次 swap(整人替换) 会话,而不是 edit(物体移除/替换、背景替换):被替换的是"整个人"——脸、头发、体型和整套服装都换,帽子和墨镜从每个被替换者身上去掉;其余路人、动作、镜头与配乐保持源片不动。
这一点在 MCP 主文档 中有对照说明:swap 是"一段视频里的人变成别的角色(虚构人物、动物、吉祥物),镜头、机位、运动和音轨不变",edit 则相反——人是留着的,被改的是物体或背景。理解这个二分很重要,因为两类会话在 MCP 里是互斥的:sheet、paint、paint_many、take_keyframe、pin_before_cuts、unpin 只接受 swap 会话,epaint 只接受 edit 会话(服务端用 need(d, "swap") / need(d, "edit") 断言,见 mcp/viggle_remake_mcp/server.py)。
样例的另一层价值是它记录了一次真实运行的账:86 分钟墙钟时间、81 次图片调用(预算 160)、250 K tokens、0 美元 API 支出,以及一个 BAD 的总评和它为什么是 BAD。这些数字在下面会逐一对应到仓库文件与源码行为。
目录清单:每个文件负责什么
样例文档用一张表交代了全部输入输出,这里沿用并补充用途说明:
| 文件 | 是什么 | 补充说明 |
|---|---|---|
| uptown_funk.mp4 | 源素材,121.8 s,24 fps 共 2923 帧 | 任务跨度 dur 121.83 s,且"结束在一个剪切点上" |
| task.txt | 交给 codex 的原始请求,逐字保存 | @SRC@ 是源路径的占位符,由 run.sh 用 sed 替换 |
| chars/ | 角色库:每个角色一张 sheet 和一张 photo,外加 lib_whf.json |
描述与服装在 JSON 里,可直接被 sheet(source="lib") 复用 |
| run.sh | 把 chars/ 拷进 $REMAKE_HOME/chars/,再用任务书调用 scripts/codex_exec.sh |
即"一键复现"入口 |
| white-house-funk.mp4 | 成片,1280×720,带源音轨 | 由 finish 产出 |
| result.json | codex 落盘的交付物:阵容、逐窗口评分与备注、选用的种子、遗留缺陷 | 由 save_result 写入 |
注意 chars/ 的实际内容不止"一张 sheet + 一张 photo":目录里有 Bessent_photo.png / Bessent_sheet.png 这样的成对文件,覆盖 Bessent、Hegseth、Leavitt、Musk、RFK、Rubio、Trump、Vance 八人,命名严格遵循 <Name>_sheet.png 与 <Name>_photo.png 约定——这是 $REMAKE_HOME/chars/ 的硬性格式(mcp/README.md)。
复现命令:从源码检出开始
样例文档给的命令只有两行,但每一行都有前提:
viggle-remake-worker & # one per GPU; see the main README
examples/white-house-funk/run.sh
前提一:渲染 worker 必须先起,且共享同一个 REMAKE_HOME。 文档原话是"Start render workers on the same REMAKE_HOME, then run the script from a source checkout(scripts/ 目录不会被 pip 安装)"。这一点在源码里是刚性约束:run.sh 最终 exec 的是 $EX/../../scripts/codex_exec.sh(mcp/examples/white-house-funk/run.sh),而 mcp/README.md 明确写了 scripts/codex_exec.sh 和 examples/ 属于源码树(hf download 拿到的目录),不在 pip 安装的包里。
前提二:REMAKE_HOME 必须与 worker 一致。 run.sh 第 6 行是 REMAKE_HOME=$(realpath -m "${REMAKE_HOME:-$HOME/.viggle-remake}"),即默认 ~/.viggle-remake,可用环境变量覆盖,并会被 export 出去。worker 侧则用同样的变量启动,例如 REMAKE_HOME=/shared/remake viggle-remake-worker --gpu 0(mcp/README.md)。服务端与 worker 之间只通过这个目录通信:会话、队列、心跳全在里面。
run.sh 的其余部分是四件小事:
EX=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)—— 无论从哪个目录调用都能定位样例目录;mkdir -p "$REMAKE_HOME/chars"—— 确保角色库目录存在;cp -n "$EX"/chars/* "$REMAKE_HOME/chars/"——-n表示不覆盖已有文件。这意味着重跑时若你改过$REMAKE_HOME/chars/里的同名文件,脚本不会帮你同步,需自行处理;exec "$EX/../../scripts/codex_exec.sh" exec -m gpt-6.1-terra -c 'model_reasoning_effort="high"' "$(sed "s#@SRC@#$EX/uptown_funk.mp4#" "$EX/task.txt")"—— 用gpt-6.1-terra、推理强度high、非交互exec模式,把task.txt中@SRC@替换成绝对路径后整段作为提示词传入。
codex_exec.sh 真正做了什么
这一步是理解"为什么复现要 86 分钟却几乎不需要人工干预"的关键。mcp/scripts/codex_exec.sh 做了五件事:
- 建一套独立的 codex home 与工作区:
CODEX_HOME=$DIR/codex_home、WS=$DIR/ws,其中DIR=${REMAKE_CODEX_DIR:-$REMAKE_HOME/codex}。脚本注释特别提醒:codex 的 sqlite 日志在网络文件系统上会损坏,必须放本地盘。 - 复制登录态:默认从
~/.codex/auth.json复制到$CODEX_HOME/auth.json(cp -u,以便刷新后的登录被带上);缺失则跳过,此时需手动CODEX_HOME=... codex login。这一份登录同时被 pool 模式的图片 helper 复用。 - 模板化配置:用
sed把 mcp/examples/codex_config.toml 里的@WS@、@CODEX_HOME@、@REMAKE_HOME@、@MCP@四个占位符替换成真实路径,写出config.toml。 - 拼装
AGENTS.md:把 mcp/viggle_remake_mcp/data/AGENTS.md(规则)+ mcp/viggle_remake_mcp/data/short_guide.md(提示词写作指南)+ 两个格式样例(example_prompt.txt、example_edit_prompt.txt)串成工作区的AGENTS.md。源码注释解释了原因:codex 在每次上下文压缩后会重读AGENTS.md,而工具返回值不会在压缩中存活,所以规则必须放进项目文档而不是靠首次工具输出。 - 两层自动续跑:
exec分支下,若日志尾部出现at capacity,就codex exec resume同一会话,最多 10 次;随后还有一层"结束但没写 result"的兜底——把本次运行触碰过、但没有在本次运行中写出result.json的会话找出来,再续两次,并在续跑提示中明确"这不是新的用户反馈,不要重做已完成步骤,先调status"。
第二层兜底直接来自实战:脚本注释写着"codex 有时会在一半就结束回合且什么都没保存(在一条两分钟片子上,约 8 次运行里有 3 次,都发生在一次 !! 警告或一个长待办列表之后)"。这解释了样例为什么强调"不要把 windows 的 !! 警告当成阻断"。
任务书:task.txt 的六层信息
样例文档说 task.txt 是"codex 收到的请求,逐字保存"。它其实是整条流水线的规格说明书,可拆成六层:
第一层,会话与跨度。 Session whf, kind swap. Source: @SRC@, span start 0, dur 121.83 s,并点明源片 2923 帧 @24 fps、结束在一个剪切点上。紧接着一句关键的覆盖声明:"Keep the whole 121.83 s span: do not shorten it(this overrides the 8-20 s guidance)"。这是因为默认规则建议短片长(mcp/viggle_remake_mcp/data/AGENTS.md:大约 8–20 秒,每个窗口都要花 GPU 时间,每条接缝都是风险),而本任务显式要求保留整段。
第二层,角色来源。 "all eight already have a library sheet and photo: for each character call sheet(source="lib", name=...) - no picture is painted for it." 即全部走免费路径,不消耗图片调用。任务书还顺带锁定了造型基调:西装一律海军蓝或炭灰,Musk 是黑 T 恤加黑牛仔裤。
第三层,选角映射。 九条人物到角色的对应,包括"一个人替换多个人"的克隆用法(Rubio 同时对应蓝虎纹夹克男子和年轻擦鞋童),以及一条例外(Leavitt 保留皮草外套穿在自己的海军蓝粗花呢连衣裙外)。同时给出覆盖规则:"The cast mapping overrides the 4-per-shot limit"——默认"无 cast 时每镜最多替换 4 人"的限制在这里失效,点名的人无论一镜几个人都要换。
第四层,预算。 "the operator set this session's limit to 160 image calls",并说明 pool image 模式下 paint_many 并行出图、无 API 支出。这个 160 是会话级上限:源码中 limit(d) 优先读取会话目录里的 paint_limit 文件,否则回落到 REMAKE_MAX_IMAGES,而 codex / pool 模式的默认值是 80(mcp/viggle_remake_mcp/paint.py)。样例最终用了 81 次,正好超过默认 80 一次——反过来说明 160 的覆盖确实生效了。
第五层,流程约束。 "Render every window with seed 0",审阅每个窗口的 strip,"do at most one fix round per window where AGENTS.md says it is worth it(a repaint, a new keyframe or seed 1)"。这正是 AGENTS.md 里"每窗口最多一轮修复"规则的任务级复述。
第六层,交付与兜底。 "Finish to case/final/full_720.mp4 and save_result. Do not stop before full_720.mp4 exists: if a window is truly impossible, keep it as source (rest_source) and say so." 最后还规定了最终消息要包含的六项:mp4 路径、用掉的图片调用数、渲染过的窗口与种子、重绘及原因、按时间区间列出的遗留缺陷、以及工具摩擦。
角色库:lib_whf.json 的结构与消费方式
mcp/examples/white-house-funk/chars/lib_whf.json 就是 MCP 主文档描述的 lib_*.json 格式:
{
"chars": {
"Trump": "Donald Trump, older man, heavy build, swept-back blond-orange hair and tanned face. Navy-blue suit, white shirt, long bright-red tie, small US-flag lapel pin, black shoes."
},
"outfits": {
"Trump": "Navy-blue suit, white shirt, long bright-red tie, small US-flag lapel pin, black shoes."
}
}
两个键各有分工,对应 AGENTS.md 里对 case 文件的定义:chars 是"身份句"(是谁、年龄、体型、发型、面部,外加服装),outfits 是"整套服装,直到鞋子"(mcp/viggle_remake_mcp/data/AGENTS.md)。文档还给了两条硬要求:服装必须彼此差异明显,否则人物会互换身份;名字只允许字母、数字、空格、-、_。
sheet(source="lib") 是这条链路上唯一免费的角色获取方式:它把 $REMAKE_HOME/chars/<Name>_sheet.png 拷进会话,并在 case.json 缺失时用 lib_*.json 里的字符串自动填充 chars/outfits(mcp/viggle_remake_mcp/server.py)。对比另外两条路径:source="photo" 从一张真实照片生成(花 1 次图片调用),source="text" 纯文本生成(同样 1 次)。样例的九个映射全部命中库里已有的八个人名,因此这一步的图片调用为 0。
值得注意 Leavitt 的词条写法:描述里明确写了"with the woman's fur coat over the dress",服装里也重复了一次。这是把任务书里"保留皮草外套"的例外固化进角色库,而不是靠提示词临场提醒——这也是样例可复现性的来源之一。
完整流水线:从 ingest 到 save_result
样例文档没有展开工具调用序列,但 MCP 的 AGENTS.md 给了按工作流排序的工具表,mcp/README.md 给了每个工具的一句话说明。把两者与样例结果对齐,一次完整 swap 运行是这样的:
| 阶段 | 工具 | 本例中的实际形态 |
|---|---|---|
| 建会话 | new_session(sid, "swap") |
sid = whf,与 result.json 的 "sid": "whf" 一致 |
| 看素材 | peek → ingest → strips / frames |
121.83 s 全部导入 case/,24 fps,含剪切点与闪光检测 |
| 写案子 | save_case(plan_grid, case, where, cuts) |
九条人物记录、八套服装、每个关键帧的"谁在哪" |
| 建角色 | sheet(source="lib") × 8 |
零成本,全部来自 chars/ |
| 切窗口 | windows |
22 个窗口(result.json 的 windows 数组长度) |
| 画关键帧 | paint / paint_many |
pool 模式批量出图,共 81 次调用(含失败重试与重绘) |
| 写提示词 | write_prompts → set_prompt |
服务端 REMAKE_LLM_MODEL=codex-pool,每窗口一个 helper codex 代写 |
| 提交渲染 | submit(seeds=[0]) |
720 画布、种子 0 |
| 等渲染 | wait |
单次最多阻塞 30 分钟,需反复调用 |
| 审片 | strip |
源片一行 + 每个 take 一行,逐列对比 |
| 修复 | submit(seeds=[1]) / pin_before_cuts / take_keyframe |
窗口 17 换种子 1;窗口 18 定点钉帧后重渲种子 0 |
| 合成 | finish(picks) |
输出 case/final/full_720.mp4,窗口接缝处的 1–2 帧闪光会在内部修掉 |
| 交付 | save_result |
写 result.json |
其中"窗口"的划分不是随意切的。按源码,窗口必须落在剪切点上,长度取自模型可渲染的帧数集合,并且单镜头超过一个窗口时不做独立切分(那会让接缝处人脸跳变),而是变成 hop——下一窗口把上一窗口 take 的第 prefix_at 帧起的 17 帧作为自己的前 17 帧(mcp/viggle_remake_mcp/kit.py)。result.json 里没有 hop 记录,说明本例 22 个窗口都落在剪切点上,没有跨越长镜头的续接。
窗口长度还受在线 worker 的实际能力约束:windows 会读心跳里的 max_frames,取所有该模式在线 worker 的最小值(mcp/viggle_remake_mcp/jobs.py),无 worker 时退回 345 帧并给警告。这解释了一个容易困惑的数字:121.83 s 为什么切成 22 段?按主文档的硬件表,起始空闲显存 94 GiB(96 GB 卡)的 worker 只能渲染 124 帧(5.2 s) 的 final,而 121.83 / 5.2 ≈ 23——22 个窗口正好落在这个量级。换句话说,是显卡决定窗口数,而不是导演决定。
一次真实运行的账:读懂 result.json
样例文档把这次运行的代价写成了一小段文字,逐项都能在 result.json 里找到字段支撑。
运行配置。 codex gpt-6.1-terra、推理强度 high、pool image 模式、两个渲染 worker。每个 worker 需要约 94 GiB 空闲显存(bf16),小于该值的卡需要自行 offload 或量化。这正是 mcp/examples/codex_config.toml 里 REMAKE_PAINT = "pool"、REMAKE_LLM_MODEL = "codex-pool"、REMAKE_POOL_N = "8" 那行 env 的含义。
时间 86 分钟 / 22 个窗口。 文档说"大部分时间在等渲染"。这与流水线的结构性事实一致:wait 单次上限 30 分钟,渲染期间 agent 应当继续画下一批关键帧。
图片调用 81 / 160。 其中 13 次失败:一部分是政治人物触发的图像安全拒绝,另一部分是合影被返回成错误宽高比。result.json 的 problems 字段原话是"Some early keyframe attempts returned incorrect aspect ratio or transient refusals; failed attempts were retried within the rules." 关于宽高比,源码里有直接的对应实现:paint_many 会把"两帧一组、且接近正方形"的组拆成两次单帧调用,注释写得很直白——"a 2-frame grid here is near 1:1, which the image model returns at 5:4"(mcp/viggle_remake_mcp/server.py)。关于安全拒绝,仓库的规则是自动重试一次、间隔 45 秒,且不允许改写措辞绕过(mcp/README.md、AGENTS.md);本例的做法是"agent repainted around them",即绕开被拒的帧,改用同镜头的另一帧。
250 K tokens、$0。 图片来自 ChatGPT 订阅的图片额度,池模式下没有 API 计费。这与成本章节一致:池模式除 codex 套餐外无额外费用;只有 images API 模式才按 gpt-image 列表价估算,并由 REMAKE_MAX_USD 兜底。
种子策略。 22 个窗口里有 20 个是种子 0;窗口 17 是种子 1 且选用了种子 1 的 take;窗口 18 是"钉帧后重渲种子 0"。picks 字段把它们写成 {"17": 1, ...},其余全 0。
总评 BAD,但只因为一个窗口。 windows[3] 的评分为 BAD,备注是"12.6–13.1 s 路过的女人皮草外套消失;14.9–16.1 s 闪光灯的交替时序有漂移"。overall 的定义见 AGENTS.md:取所有 pick 里最差的等级。因此总评 BAD 并不代表整片失败——其余 16 个窗口是 OK,5 个是 MINOR。
MINOR 的四类典型缺陷。 逐条读 windows 数组很有教学价值:
w2:"快速剪辑用了四个 setup 参考;有些相似度漂移"——对应"快速剪辑按机位(setup)而非按镜头布光"的规则;w8:"约 47.2 s 处残留一小段白袖子"——典型的"原服装元素泄漏",属于没有换干净的整人替换;w12:"约 64–68 s 部分西装上仍留金项链"——同一类泄漏,出现在饰品上;w13:"背景人物数量可能漂移"——背景群演计数不稳定;w17:"种子 1 恢复了约 90.4 s 的短镜头;有轻微服装漂移"——说明这是一次"漏镜头"修复。
修复手法:种子、钉帧与"从 take 里取关键帧"
样例记录了三类修复,恰好覆盖了 AGENTS.md 里的三条不同规则,值得单独讲清楚,因为它们决定了你能不能在有限预算里救回一个窗口。
换种子(seed 1)。 适用于镜头被整段"吞掉"或剪切点晚到的情况。文档明确:cut f1529 dropped(take 把上一个镜头继续播过了剪切点)意味着漏了一个镜头,属于 BAD,处理方式是种子 1;剪切点晚 8 帧以上也用种子 1。窗口 17 的"恢复约 90.4 s 的短镜头"就是这一类。
钉帧(pin_before_cuts)。 适用于剪切点提前——而且这是"换种子无效"的场景。AGENTS.md 给的实测数据是:4 个剪切点 × 2 个种子,8 次里有 5 次在种子 1 上仍然提前。做法是在剪切点前 6 帧为"即将结束的那个镜头"补一个关键帧,让模型把该镜头撑到剪切点;实测均值从提前 14 帧降到 2.75 帧,8 次全部落在 5 帧以内。源码层面,它会把该镜头的 where 文案复制到新帧并改写其中的帧号,把同镜头 72 帧内的旧关键帧移出,最多 4 个关键帧,超预算直接断言失败(mcp/viggle_remake_mcp/server.py)。如果钉帧后反而更差,unpin 能恢复钉帧前的关键帧和提示词,让之前渲出的 take 重新计入——这是"修复本身有风险"的对冲设计。
take_keyframe。 适用于"关键帧里看不到的部位被画错":腿、鞋、裙长、随身包。它不是换种子,而是从已完成的 take 里切一帧当关键帧,并且可以只在一个 box 区域内修复——box 之外直接沿用 take 自己的像素,因此不会产生贴片接缝。源码同样强制 frame 落在窗口 own 区间内、关键帧间隔 ≥72 帧、数量 ≤4,并会检查同一条 where 文案是否已经出现在 3 个关键帧里(第 4 次会被 save_case 拒绝)(mcp/viggle_remake_mcp/server.py)。
样例在窗口 18 用的是钉帧路线,结果 windows[18] 的备注是"Pinned early cut at 99.7 s and rerendered; timing check passes."——即 99.7 s 处的提前剪切点是这一窗口的主要问题。
复现前必须确认的五件事
1)显存与硬件档位。 按主文档的硬件表,起始空闲显存低于 86.4 GiB(80 GB 卡)时,drafts 与 finals 都渲染不了;94 GiB 档位能渲 345 帧 draft 与 124 帧 final;113 GiB 以上才能 345 帧 final。每个 worker 还要在主机内存里常驻文本编码器,约 58 GiB RAM。worker 不做 offload 也不做量化——需要小卡方案时应改用 ComfyUI worker。样例本身在单张 RTX 5090(32 GB)上也能端到端跑完,耗时 2 小时 58 分(mcp/README.md),代价是 int8 权重与逐层流式加载。
2)预算会硬停。 REMAKE_MAX_IMAGES(codex/pool 默认 80,本例由任务的 160 覆盖)与 REMAKE_MAX_USD(默认 10)是硬闸。任何"额度/计费"错误、PAINT STOPPED、budget reached 都会写出 $REMAKE_HOME/STOP 文件,在此文件存在期间所有会话都拒绝出图;删除它才会恢复(mcp/README.md)。规则手册要求遇到这类错误"立刻停止出图,不要重试或绕过"。
3)配置里的两个非显然参数。 mcp/examples/codex_config.toml 中 project_doc_max_bytes = 65536 是因为拼装后的 AGENTS.md 约 60 KB,而默认 32 KiB 会静默截断;NUMPY_MADVISE_HUGEPAGE = "0" 是因为 finish 要构建数 GB 的帧数组,THP 的 madvise 碎片整理会让缺页在内存压缩里卡住(注释记录了实测:单独跑 78 s,在任务里到了 590 s)。
4)超时设置。 wait 最多阻塞 30 分钟,paint 可能花几分钟,所以 config 把 tool_timeout_sec 设为 4200.0;用 Claude Code 时官方建议 MCP_TOOL_TIMEOUT=4200000(毫秒)。
5)文件系统。 codex home 与 REMAKE_POOL_DIR 都要放本地盘(前者是 sqlite 日志限制,后者注释中直接写了 "keep it on a local disk")。而 REMAKE_HOME 本身可以放共享文件系统——server 与 worker 只共享这个目录,因此可以跨机器。
这个样例暴露的边界
样例文档自己给出了结论:codex 给整片打 BAD,因为有一个窗口。这份坦诚比数字更有价值,它标注了当前流水线的能力边界:
- 快速剪辑是薄弱环节。
w2与w11都是"快速蒙太奇 + 相似度漂移"。规则手册的判断是"480p 下人脸小于约 50 px 会漂成陌生人;一个窗口里 5 个以上快切,哪个都跟不好"。 - 整人替换的"泄漏"是常态缺陷。 白袖子、金项链都是原片服装元素残留。规则要求重绘时在
note里点名部位和颜色,而不是笼统说"重画"。 - 时序类缺陷需要另一套工具。 闪光交替漂移(
w3)属于节奏问题,既不是身份问题也不是构图问题;strobe 在ingest阶段就会被检测(源码里find_strobes与find_cuts并列),但检测到不等于能修好。 - 可复现的是流程,不是像素。 文档明确写下"A second run will differ in detail, since codex paints fresh keyframes each time"。想拿到完全一致的成片,只能靠固定的关键帧与种子,而这套系统不保证这一层。
最后要说清合规边界。样例的任务书把真实政治人物指定为替换对象,而成片里的安全拒绝(13 次失败中的一部分)正是图像模型上游防护的体现。模型本身不做身份或授权校验——mcp/README.md 的原话是"身份来自你画的关键帧",任何图像编辑器的防护都在这个模型的上游,而模型内部没有。把它用于服务时,应遵守相应的许可条款,并对生成内容做 AI 生成标注。这条限制同样适用于 agent:MCP 会画出任务点名的任何人,并且不对"这是谁"做任何检查。
小结
White House Funk 之所以值得作为范例精读,是因为它把一个看似"魔法"的端到端重制拆成了可验证的工程链条:run.sh 固定住环境与模型参数,task.txt 固定住跨度、选角、预算与交付标准,chars/lib_whf.json 用结构化描述固定住人物一致性,AGENTS.md 与两个格式样例固定住提示词与关键帧的纪律,而 result.json 把代价与缺陷一并落盘。真正决定成片质量的三个变量是:显卡决定的窗口长度、关键帧的覆盖完整性、以及修复轮次的正确选型(种子、钉帧还是 take 关键帧)。把这三点想清楚,再去读源码里的 windows、pin_before_cuts 与 take_keyframe,样例里那些数字就不再是结论,而是可推导的结果。