Viggle/Viggle-Animate · Hugging Face 来源：https://huggingface.co/Viggle/Viggle-Animate ### https://huggingface.co/Viggle/Viggle-Animate#character-replacement-in-video-from-a-single-repainted-frame从单帧重绘实现视频角色替换 试用演示 (https://huggingface.co/spaces/Viggle/viggle-animate) · 研究文章 (https://viggle.ai/research/viggle-animate-character-replacement-from-a-repainted-frame?utm_source=huggingface&utm_medium=social&utm_campaign=viggle-animate&utm_content=viggle/viggle-animate) · ComfyUI 节点 (https://github.com/Saganaki22/ComfyUI-Viggle-Animate-H3) · viggle.ai/h3 (https://viggle.ai/h3) · 基于 MiniMaxAI/MiniMax-H3 (https://huggingface.co/MiniMaxAI/MiniMax-H3) @cocktailpeanut 在 X 上：两位 AI CEO 借 Viggle-Animate 介入电影场景——150 万播放，1.4 万点赞 (https://x.com/cocktailpeanut/status/2097332291844399514) 由 @cocktailpeanut 使用 Viggle-Animate (https://x.com/cocktailpeanut/status/2097332291844399514) 制作，非我方出品。点击查看原视频。Viggle-Animate 可替换视频中的角色，仅需你重绘其自身某一帧画面——动作、镜头和时序均保持不变。你使用图像编辑器准备这一帧；之后视频生成阶段无需运行姿态估计器、分割器、人脸追踪器或文本编码器。两个输入，三次前向传播，单 GPU 每镜头处理 26 秒。**其在替换难度最高的场景表现最强：快速运动，且姿态转移足够精准以跟随运动。**甩头、全踢、跳跃——逐帧追踪，无涂抹模糊。 ## https://huggingface.co/Viggle/Viggle-Animate#abstract摘要 可控的角色替换通常依赖中间表征——姿态骨架、分割掩码、背景板、人脸裁剪。每种都需要专用提取器，每个提取器都是需要运行的模型，也是信息可能丢失的一环。近期工作摒弃了骨架但保留掩码通道。Viggle-Animate 两者皆不用。其两个输入是驱动视频和该视频自身重绘了角色的一帧，其唯一任务是将此编辑传播至整个镜头。由于参考帧是片段的原始一帧，其姿态、镜头、构图和光照已与画面一致，下游无需再次对齐。模型无需被告知新角色是什么：无类别、无身份编码器，也无用户提供的文本提示。Viggle-Animate 是基于 MiniMax-H3 ref2va transformer 的 331 亿参数全量微调模型，并与 DMD 联合蒸馏至三次前向传播。在相同机器与 B200 GPU 上的匹配对比中，使用相同源视频、输出分辨率和帧数，其渲染 124 帧需 26 秒，每片段速度比 Wan2.2-Animate-14B 快 6.1 倍。 ## https://huggingface.co/Viggle/Viggle-Animate#method方法 角色替换同时涉及两个问题：新角色的外观是什么，以及它如何在这个镜头中运动。基于独立角色照片进行条件的系统必须同时解决这两点，而调和一张从未出现在画面中的照片与实际画面，正是现有辅助框架存在的原因。前沿图像模型已完成此任务。给 gpt-image 一帧和一条指令，它即可精确按照提示替换角色——转移姿态、匹配光照、保留背景。这个困难的调和问题已在单一图像上一次性解决。本模型是该流程的第二部分，而非全部。两个输入——一个驱动视频及其自身任意图像编辑器重绘的一帧——进入 Viggle-Animate。无姿态骨架、分割掩码、人脸裁剪、背景板、深度图或用户提供的文本提示进入视频模型。外观仅通过重绘帧输入；几何信息仅通过驱动视频输入。文本编码器从未加载。条件是一个随权重固定（assets/fixed_prompt.txt (https://huggingface.co/Viggle/Viggle-Animate/blob/main/assets/fixed_prompt.txt)）的冻结嵌入，每次渲染均相同。左栏为驱动视频，右栏为本模型输出： 它具备双重高效性。一旦重绘帧存在，无需运行其他任何组件——无姿态估计器、分割器、人脸追踪器或文本编码器。且采样器经过蒸馏，因此一个完整片段仅需三次前向传播而非三十次。两者叠加：一个模型，一块 GPU，无需出错的流程编排。蒸馏是联合进行的，由两个噪声水平不同的教师模型分担。我们的微调监督调度的高噪声端，即替换决策发生的地方——这是确保替换正确的模型。原始 MiniMax-H3 监督低噪声端，即细节和纹理决定的地方——这是拥有更好图像质量的模型。针对各自所属的教师模型进行蒸馏，使学生模型兼具两者特性，而非继承微调模型的视觉退化问题。其泛化能力超越人类，因为流程中无任何假设角色必须是人。姿态骨架有颈部和双臂；掩码有一个人形洞。我们两者皆无，因此模型不持有角色必须为人的表征。其可动画的对象受限于你能绘制的内容。 ## https://huggingface.co/Viggle/Viggle-Animate#efficiency效率 26 秒 每次渲染 124 帧，24 fps，480×832，单块 B200 3 前向传播 --steps 4 指定四个 sigma 边界，故为三次传播 2 输入 一个片段及其自身重绘的一帧 0 其他模型 在视频阶段——无姿态估计器、分割器、人脸追踪器或文本编码器 单块 B200，480×832，124 帧 24 fps，bf16，无编译，无卸载。Wan 运行其文档化替换方案——20 步，sample_shift 5.0，--refert_num 1 --replace_flag --use_relighting_lora，--w_len 1 --h_len 1——并在其自身预处理过程之后。 Viggle-AnimateWan2.2-Animate-14B输入驱动视频 + 一帧重绘帧驱动视频 + 角色图像，然后一次预处理过程生成姿态、人脸、掩码和背景轨迹渲染，权重加载后26 秒160 秒——其中采样13.6 秒140 秒前向传播340（20 步 × 2 块）参数33.1 B17.3 B **每次渲染快 6.1 倍，仅采样快 10.3 倍。**Wan 的预处理过程未计入其 160 秒。 ### https://huggingface.co/Viggle/Viggle-Animate#qualitative-comparison定性比较 每组四幅：重绘参考帧 · 驱动视频 · 本模型 · Wan2.2-Animate-14B，最后者使用其文档化替换设置。差距在快速运动时最为明显：对比模型出现涂抹，而本模型保持清晰，并在正确帧定位姿态。 ## https://huggingface.co/Viggle/Viggle-Animate#generalization泛化 模型从不被告知动画的对象是什么，因此角色能偏离人类多远是一个经验问题，而非预设类别列表。每组三幅：**重绘参考帧 · 驱动视频 · 本模型。**以下每个片段均使用默认设置进行一次绘制和一次渲染，--seed 42——无最优选择。 **动物。**耳朵、眼罩和鳍状肢移动在驱动片段不存在的肢体上——绘制将其放置，渲染将其动画化，仿佛它们一直是手臂和头部。 **非人形。**客机是我们面临的最困难案例：绘制将机翼绑定至手臂，起落架绑定至腿部，模型的任务是维持此绑定 124 帧。机器人需要在转动时重新照亮镜面金属。 **风格化。**粘土人物在整个片段保持其风格边界。 **多角色。**工作进入绘制提示，必须将每个角色绑定至一个位置——“左边的那个”。最后一个片段是广角场景，每个角色仅几十像素高。 ## https://huggingface.co/Viggle/Viggle-Animate#limitations局限性 **其继承图像编辑。**绘制未展示的内容，模型不会添加，且绘制与视频不一致时，视频胜出。外观来自绘制，形状来自驱动姿态：一个乐高小人保留了其配色和黄色爪形手，却恢复了人类解剖结构——客机保持成功，因为绘制将其机翼绑定至真实手臂。 **口型同步较弱。**在特写镜头中，口型不紧密追踪语音。身份和表情保持；是同步滞后，我们相信这是训练数据限制，而非结构性限制。 已撤回——且已改进。更广泛的用户测试已将口型同步和面部表情提升至超乎我们最初预期。其余部分最终也并非训练数据限制。模型根据其自身音频轨道动画化口型，而固定提示要求该轨道为静音——因此在交付配置中，口型无同步对象。提供真实音轨代替：使用音频 VAE 编码驱动片段的音频，并在目标音频行中保持其为整个去噪过程的干净潜在表示（H3 的流惯例是反转的，因此干净状态为 t = 1）。音频行从模型预测的内容变为条件依据，口型则追踪语音。这仅是推理时更改——无需重新训练，无需新权重——且带噪视频行与干净音频行的配对并非模型训练时的状态，但在我们运行的片段上表现稳定。传递 --audio 在此使用；托管演示 (https://huggingface.co/spaces/Viggle/viggle-animate) 在上传片段包含声音时自动执行。 **请开启这两个片段的声音。**驱动片段，然后同一镜头由不同演员出演，说出她的台词：这三个文件均随权重交付——驱动片段、用于动画化的重绘静帧（audio-pin-ref.png (https://huggingface.co/Viggle/Viggle-Animate/blob/main/examples/media/audio-pin-ref.png)），以及上述录制——因此第二个片段是命令而非声明。同一文件传递两次，一次用于运动，一次用于音轨： python inference/sample.py --model-dir ./MiniMax-H3 \ --cond examples/media/audio-pin-driving.mp4 \ --ref examples/media/audio-pin-ref.png \ --audio examples/media/audio-pin-driving.mp4 \ --out audio-pin-out.mp4 其他均为默认设置：124 帧 832x480，四步，--seed 42；权重加载后 B200 上渲染耗时 51 秒，输出与原文件对比达 46 dB。返回的音轨是驱动片段音频经音频 VAE 编码后再次解码——相同电平，峰值平滑（此处从 0.95 降至 0.76）；此往返证实音频行确实被固定。去掉 --audio，相同命令写出的文件音轨为数字静音，逐样本对应，口型移动但不发声。 **复杂场景比单一主体更困难。**多个角色同时出现、角色间密切交互、镜头剪辑等情况均会导致质量下降——下降程度足以让我们认为尚未解决。 我们正在训练一个显著更优的模型，专门针对剩余问题。本次发布是我们今天能交付的版本，而非上限。 ## https://huggingface.co/Viggle/Viggle-Animate#what-this-repository-contains此仓库包含内容 两部分，均源自 MiniMaxAI/MiniMax-H3 (https://huggingface.co/MiniMaxAI/MiniMax-H3) 的 ref2va transformer： transformer/ 33.1 B 参数，bf16 格式，14 个分片。一个针对角色替换目标的 全量微调。 lora/ 覆盖 302 个线性层的 128 秩 LoRA，2.5 GB。一个基于该微调的 DMD2 蒸馏增量——正是它将采样器压缩至三次前向传播。LoRA 是 微调后 transformer 的增量——将其加载至原始 transformer_ref 会产生无意义输出。 ## https://huggingface.co/Viggle/Viggle-Animate#quickstart快速入门 此仓库仅包含 transformer 和 LoRA——VAE、音频 VAE 和调度器从你本地的基础模型副本加载。推理仅使用其 269 GB 中的 11 GB： hf download MiniMaxAI/MiniMax-H3 --local-dir ./MiniMax-H3 \ --include "modular_model_index.json" "vae/*" "audio_vae/*" \ "scheduler/*" "audio_scheduler/*" "assets/ref2va.mp4" hf download Viggle/Viggle-Animate --local-dir ./Viggle-Animate pip install torch "git+https://github.com/huggingface/diffusers@d6726f3" av python Viggle-Animate/inference/sample.py \ --model-dir ./MiniMax-H3 \ --cond driving.mp4 --ref ref.png --out swapped.mp4 d6726f3 是经过测试的 diffusers 提交；上游的 minimax_h3 模块化管道已足够，无需分支或补丁。最后一个 --include 是示例 demo.sh (https://huggingface.co/Viggle/Viggle-Animate/blob/main/examples/demo.sh) 所需的片段。 单张 80 GB 显卡在 bf16 模式下不足——transformer 常驻内存 62 GiB，480×832 / 124 帧渲染峰值分配达 80.1 GiB。请使用 ≥ 96 GB 的显卡，或传递 --offload 从 CPU 流式加载块（常驻约 12 GB，速度更慢）。 **它也可在消费级硬件上量化运行。**我们在单张 RTX 5090 (32 GB) 上部署：NVFP4 权重——4.5 位/参数，调度至实际 sm_120 cutlass 块缩放内核，每个编译线性层速度是 bf16 的 2.70 倍——加上低秩 adaln_proj 和 torch.compile。仅量化不足以适配 32 GB：33.1 B 参数中有 13.0 B 位于 adaln_proj，线性层量化器无法触及。此部署路径未包含在本仓库中。默认值为评估配置：--steps 4 --flow-shift 3 --num-frames 124（约 5.2 秒，24 fps）--seed 42。输出几何遵循驱动片段，两个轴必须为 32 的倍数。权重加载约需 21 秒，每个进程一次。四步是工作点，而非捷径——蒸馏模型已比其教师渲染更清晰，增加步骤会导致过度锐化。--steps 4 指定四个 sigma 边界，因此为三次前向传播。sample.py 在输入时丢弃驱动片段音频，模型生成自身音轨，而固定提示要求其为静音。--audio 覆盖此设置并固定真实音轨，正是它使口型追踪语音——参见局限性 (https://huggingface.co/Viggle/Viggle-Animate#limitations)。使用 ffmpeg -ss 1.5 -i driving.mp4 -frames:v 1 ref.png 提取一帧并以相同分辨率编辑。**它不必是第一帧。**静帧传递给模型时不带帧索引，因此下游无从知晓其在片段中的位置——选择角色最清晰、正面且无遮挡的帧。命名更改，并固定不能更改的内容：姿态、手部、道具、构图、背景、光照。悄然重构镜头的编辑器会与驱动运动冲突。优先选择保持一侧面向镜头的片段，并将任何新肢体绑定至真实肢体。 examples/demo.sh (https://huggingface.co/Viggle/Viggle-Animate/blob/main/examples/demo.sh) 在随基础模型交付的片段上端到端运行替换，因此无需你提供任何媒体——这也是检查 LoRA 是否加载的最快方式。 ## https://huggingface.co/Viggle/Viggle-Animate#citation引用 @misc{viggle2026animate, title = {Viggle-Animate: Character Replacement in Video from a Single Repainted Frame}, author = {Viggle Research}, year = {2026}, url = {https://huggingface.co/Viggle/Viggle-Animate} } ## https://huggingface.co/Viggle/Viggle-Animate#license许可证 权重是 MiniMax H3 的模型衍生品，因此 MiniMax H3 社区许可证 (https://huggingface.co/Viggle/Viggle-Animate/tree/main/LICENSE) 适用——在重新分发或基于其发布产品前请阅读该许可证。我们的修改列于 MODIFICATIONS.md (https://huggingface.co/Viggle/Viggle-Animate/blob/main/MODIFICATIONS.md)。