%20(1).png)
ComfyUI-MotionCtrl 插件保姆级教程
1. 插件简介
插件原地址： https://github.com/chaojie/ComfyUI-MotionCtrl
这个插件是把 MotionCtrl 这个超厉害的视频生成控制工具包装成了 ComfyUI 里面可以用的小积木块（节点）。
它能干什么？
- 就像一个超级智能的视频导演，你可以控制视频中物体的运动轨迹
- 还可以控制摄像机的运动，比如推拉摇移、旋转等各种镜头效果
- 能同时控制物体运动和摄像机运动，制作出电影级别的视频效果
- 把静态图片变成动态视频，让图片里的东西按照你想要的方式动起来
能带来什么效果？
- 物体轨迹控制：让视频中的小狗沿着指定路径跑动，让花朵随风摆动
- 摄像机运动：制作电影般的推拉镜头、环绕拍摄、俯冲效果等
- 复合运动：同时控制物体和摄像机，创造复杂的视觉效果
- 轨迹可视化：在生成的视频上显示运动轨迹点，方便调试和预览
2. 如何安装
方法一：通过 ComfyUI 管理器安装（推荐）
- 打开 ComfyUI
- 点击右下角的"Manager"按钮
- 在搜索框输入"MotionCtrl"
- 找到这个插件后点击"Install"
方法二：手动安装
- 找到你的 ComfyUI 安装文件夹
- 进入
custom_nodes文件夹 - 在这个文件夹里打开命令行窗口
- 输入以下命令：
git clone https://github.com/chaojie/ComfyUI-MotionCtrl.git
安装依赖包
安装完插件后，还需要安装一些辅助工具包：
pip install -r ComfyUI/custom_nodes/ComfyUI-MotionCtrl/requirements.txt
下载模型文件
需要下载 MotionCtrl 模型文件：
- 从 HuggingFace 下载
motionctrl.pth - 将文件放到
ComfyUI/models/checkpoints文件夹中
3. 节点详解
3.1 Load Motionctrl Checkpoint 节点
这是插件的模型加载器，就像一个专业的视频制作设备启动器。它负责加载 MotionCtrl 的核心模型，为后续的视频生成做准备。
3.2 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| ckpt_name | ckpt_name | 模型文件列表 | motionctrl.pth | 就像选择不同的摄像设备，不同的模型有不同的能力 | 选择要加载的MotionCtrl模型检查点文件 | 选择下载好的motionctrl.pth文件 |
| frame_length | frame_length | 整数 | 16 | 决定生成视频有多少帧，就像决定视频有多长 | 设置生成视频的帧数长度 | 想要1秒视频设16，想要2秒设32 |
3.3 Motionctrl Cond 节点
这是插件的条件控制器，就像一个智能的导演助手。它接收你的指令（文字描述、摄像机运动、物体轨迹），然后转换成模型能理解的语言。
3.4 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| model | model | MOTIONCTRL类型 | 来自加载器 | 就像把专业摄像设备连接到控制台 | 从加载器节点接收的模型对象 | 连接Load Motionctrl Checkpoint的输出 |
| prompt | prompt | 文本输入 | a rose swaying in the wind | 告诉AI要生成什么内容的视频，就像给导演的剧本 | 文本提示词，描述要生成的视频内容 | 输入"一只小狗在草地上奔跑" |
| camera | camera | JSON格式文本 | [[1,0,0,0,0,1,0,0,0,0,1,0.2]] | 控制摄像机怎么运动，就像遥控摄像机的操作杆 | 摄像机运动参数的JSON数组 | 使用预设或自定义摄像机运动 |
| traj | traj | JSON格式文本 | [[117, 102]] | 控制物体运动轨迹，就像在屏幕上画运动路线 | 物体运动轨迹的坐标点数组 | 设置物体从左到右的运动路径 |
| infer_mode | infer_mode | 选择列表 | control both camera and object motion | 选择控制模式，就像选择拍摄方式 | 推理模式：仅控制摄像机、仅控制物体或同时控制 | 根据需求选择控制方式 |
| context_overlap | context_overlap | 整数 | 0 | 视频片段之间的重叠帧数，用于长视频生成 | 上下文重叠帧数，用于长序列生成的连续性 | 生成长视频时设置为4-8帧 |
3.5 Motionctrl Sample Simple 节点
这是插件的简化采样器，就像一个自动化的视频制作机器。它接收所有的控制信息，然后生成最终的视频。
3.6 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| model | model | MOTIONCTRL类型 | 来自加载器 | 连接专业的视频生成设备 | MotionCtrl模型对象 | 连接加载器节点的输出 |
| clip | clip | EMBEDDER类型 | 来自加载器 | 文字理解模块，把文字转换成图像语言 | 文本编码器，处理提示词 | 连接加载器节点的clip输出 |
| vae | vae | VAE类型 | 来自加载器 | 图像编解码器，负责图像的压缩和还原 | 变分自编码器，处理图像编解码 | 连接加载器节点的vae输出 |
| ddim_sampler | ddim_sampler | SAMPLER类型 | 来自加载器 | 采样器，控制视频生成的质量和速度 | DDIM采样器对象 | 连接加载器节点的采样器输出 |
| positive | positive | CONDITIONING类型 | 来自条件节点 | 正面条件，告诉AI要生成什么 | 正向条件编码 | 连接Motionctrl Cond的positive输出 |
| negative | negative | CONDITIONING类型 | 来自条件节点 | 负面条件，告诉AI不要生成什么 | 负向条件编码 | 连接Motionctrl Cond的negative输出 |
| traj_list | traj_list | TRAJ_LIST类型 | 来自条件节点 | 轨迹列表，用于可视化显示 | 轨迹点列表 | 连接条件节点的轨迹输出 |
| rt_list | rt_list | RT_LIST类型 | 来自条件节点 | 摄像机参数列表 | 摄像机变换矩阵列表 | 连接条件节点的摄像机输出 |
| traj | traj | TRAJ_FEATURES类型 | 来自条件节点 | 处理过的轨迹特征 | 轨迹特征编码 | 连接条件节点的轨迹特征 |
| rt | rt | RT类型 | 来自条件节点 | 处理过的摄像机特征 | 摄像机变换特征 | 连接条件节点的摄像机特征 |
| steps | steps | 整数 | 50 | 生成步数，就像画家画画的精细程度 | 扩散模型的采样步数 | 高质量用50-100，快速预览用20-30 |
| seed | seed | 整数 | 1234 | 随机种子，控制生成结果的随机性 | 随机数种子，控制生成的随机性 | 固定种子得到相同结果 |
| noise_shape | noise_shape | NOISE_SHAPE类型 | 来自条件节点 | 噪声形状信息 | 噪声张量的形状信息 | 连接条件节点的噪声形状 |
| context_overlap | context_overlap | 整数 | 0 | 上下文重叠帧数 | 长序列生成的重叠帧数 | 生成长视频时使用 |
| traj_tool | traj_tool | 字符串 | 网址链接 | 轨迹绘制工具的网址，方便绘制运动路径 | 轨迹绘制工具URL | 点击链接打开轨迹绘制工具 |
| draw_traj_dot | draw_traj_dot | 布尔值 | False | 是否在视频上显示轨迹点，就像显示运动路线图 | 是否在输出视频上绘制轨迹点 | 调试时开启，最终输出时关闭 |
| draw_camera_dot | draw_camera_dot | 布尔值 | False | 是否显示摄像机位置信息 | 是否在输出视频上绘制摄像机信息 | 调试摄像机运动时开启 |
3.7 Load Motion Camera Preset 节点
这是摄像机预设加载器，就像一个专业摄影师的动作库。它提供了各种预设的摄像机运动模式，让你不用手动设置复杂的参数。
3.8 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| motion_camera | motion_camera | 预设列表 | U | 选择摄像机运动类型，就像选择不同的拍摄手法 | 预定义的摄像机运动模式 | U=向上，D=向下，L=左移，R=右移，O=拉远等 |
3.9 Load Motion Traj Preset 节点
这是轨迹预设加载器，就像一个动画师的动作模板库。它提供了各种预设的物体运动轨迹，让物体能够按照经典的运动模式移动。
3.10 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| motion_traj | motion_traj | 预设列表 | curve_1 | 选择物体运动轨迹类型，就像选择不同的运动方式 | 预定义的物体运动轨迹模式 | curve_1=曲线运动，shake_1=摇摆运动等 |
| frame_length | frame_length | 整数 | 16 | 轨迹的帧数长度，决定运动持续时间 | 轨迹序列的帧数 | 与视频总帧数保持一致 |
3.11 Select Image Indices 节点
这是图像选择器，就像一个视频编辑器的帧选择工具。它可以从生成的视频序列中选择特定的帧，用于进一步处理或预览。
3.12 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| images | images | IMAGE类型 | 来自采样器 | 输入的图像序列，就像一卷胶片 | 输入的图像张量序列 | 连接采样器的输出 |
| selected_indexes | selected_indexes | 字符串 | 1,2,3 | 选择哪些帧，就像挑选照片 | 要选择的帧索引，支持范围选择 | "0,5,10"选择第1、6、11帧，"0:5"选择前5帧 |
3.13 Motionctrl Sample 节点
这是插件的完整采样器，就像一个专业的视频制作工作站。它集成了所有功能，可以一次性完成从参数设置到视频生成的全过程。
3.14 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| prompt | prompt | 文本输入 | a rose swaying in the wind | 视频内容描述，告诉AI要生成什么 | 文本提示词 | 描述想要的视频内容 |
| camera | camera | JSON文本 | [[1,0,0,0,0,1,0,0,0,0,1,0.2]] | 摄像机运动参数 | 摄像机变换矩阵的JSON格式 | 使用预设或自定义摄像机运动 |
| traj | traj | JSON文本 | [[117, 102]] | 物体运动轨迹坐标 | 轨迹点坐标的JSON数组 | 设置物体运动路径 |
| frame_length | frame_length | 整数 | 16 | 视频帧数长度 | 生成视频的总帧数 | 根据需要的视频长度设置 |
| steps | steps | 整数 | 50 | 生成质量控制，步数越多质量越好但越慢 | 扩散采样步数 | 平衡质量和速度 |
| seed | seed | 整数 | 1234 | 随机种子，控制结果的随机性 | 随机数生成种子 | 固定种子获得一致结果 |
| traj_tool | traj_tool | 字符串 | 网址链接 | 轨迹绘制工具链接 | 在线轨迹绘制工具URL | 用于绘制自定义轨迹 |
| draw_traj_dot | draw_traj_dot | 布尔值 | False | 是否显示轨迹点 | 在视频上绘制轨迹可视化 | 调试时开启 |
| draw_camera_dot | draw_camera_dot | 布尔值 | False | 是否显示摄像机信息 | 在视频上绘制摄像机可视化 | 调试摄像机运动时开启 |
| ckpt_name | ckpt_name | 模型文件 | motionctrl.pth | 选择使用的模型文件 | MotionCtrl模型检查点 | 使用下载的模型文件 |
4. 使用技巧和建议
4.1 摄像机运动技巧
- 基础运动：U(上移)、D(下移)、L(左移)、R(右移)适合简单的镜头移动
- 缩放效果：O系列(拉远)、I系列(推近)制作电影感的推拉镜头
- 旋转运动：Round系列制作环绕拍摄效果，SPIN系列制作旋转效果
- 速度控制：0.2x、0.4x、1.0x、2.0x控制运动速度
4.2 物体轨迹设计
- 自然运动：curve系列适合模拟自然的弧线运动
- 摇摆效果：shake系列适合花朵、树叶等摇摆运动
- 水平运动：horizon系列适合车辆、人物的水平移动
- 自定义轨迹：使用在线工具绘制复杂的运动路径
4.3 参数调节建议
- 新手设置：frame_length=16, steps=50, 使用预设运动
- 高质量设置：steps=100, 精心设计轨迹和摄像机运动
- 快速预览：steps=25, 开启轨迹和摄像机可视化
- 长视频生成：使用context_overlap=4-8，分段生成后拼接
4.4 工作流程建议
- 规划阶段：先确定视频内容和运动效果
- 预设测试：使用预设运动快速测试效果
- 精细调整：根据预览结果调整参数
- 最终渲染：关闭可视化，使用高质量设置生成
5. 常见问题解答
Q1：为什么生成的视频运动效果不明显？
A：
- 检查轨迹点之间的距离是否足够大
- 确认infer_mode选择了正确的控制模式
- 尝试增加frame_length让运动更明显
- 调整摄像机或物体的运动幅度
Q2：如何制作复杂的运动效果？
A：
- 使用在线轨迹绘制工具创建自定义路径
- 同时控制摄像机和物体运动
- 尝试不同的预设组合
- 调整context_overlap制作长序列视频
Q3：生成速度太慢怎么办？
A：
- 减少steps数量（25-30用于预览）
- 降低frame_length
- 使用简单的运动预设
- 关闭可视化选项
Q4：如何获得更好的视频质量？
A：
- 增加steps到50-100
- 使用详细的prompt描述
- 精心设计运动轨迹
- 确保摄像机运动平滑
Q5：轨迹绘制工具怎么使用？
A：
- 点击traj_tool链接打开在线工具
- 在画布上点击绘制运动路径
- 复制生成的坐标到traj参数
- 调整坐标范围适配1024x1024画布
6. 实用案例
案例1：花朵摇摆视频
- prompt: "a beautiful rose swaying gently in the breeze"
- camera: 使用预设"O_0.2x"制作缓慢拉远效果
- traj: 使用预设"shake_1"制作摇摆运动
- 效果: 制作出花朵在微风中摇摆的唯美视频
案例2：动物奔跑视频
- prompt: "a dog running across the grass field"
- camera: 使用预设"L"制作跟随拍摄
- traj: 使用预设"horizon_2"制作水平运动
- 效果: 制作出小狗奔跑的动态视频
案例3：环绕拍摄效果
- prompt: "a majestic mountain landscape"
- camera: 使用预设"Round-RI"制作环绕运动
- traj: 不设置物体运动
- 效果: 制作出环绕山景的电影级镜头
7. 注意事项
- 硬件要求：建议至少8GB显存，生成长视频需要更多显存
- 模型文件：确保正确下载并放置motionctrl.pth文件
- 坐标系统：轨迹坐标基于1024x1024画布，注意坐标范围
- 运动幅度：过大的运动可能导致视频不稳定
- 帧数限制：frame_length过大可能导致显存不足
8. 总结
ComfyUI-MotionCtrl 是一个功能强大的视频运动控制插件，它让普通用户也能制作出专业级的动态视频。通过简单的参数设置和预设选择，你可以轻松控制视频中的物体运动和摄像机运动，创造出各种令人惊叹的视觉效果。
记住最重要的几点：
- 从预设开始，逐步学习自定义设置
- 合理规划运动轨迹，避免过于复杂的运动
- 根据硬件能力调整参数，平衡质量和速度
- 善用可视化功能进行调试和预览
- 多尝试不同的组合，发现最佳效果
希望这个教程能帮助你快速掌握这个强大的视频生成工具！