Extensions/MiniMaxRefDirector-ComfyUI
ComfyUI Extension

MiniMaxRefDirector-ComfyUI

MiniMax Reference Director — ComfyUI custom nodes for subject management, timeline editing, and VLM-enhanced prompt generation.

By eaglering·Created about a month ago·Updated 6 days ago· 37
eaglering/MiniMaxRefDirector-ComfyUI
Nodes11
On cloudLocal install
Categoryminimaxrefdirector, MiniMax Ref Director/Utils
Stars37
Updated6 days ago

Nodes (11)

MiniMax Ref Combine

The save node that hands your H3 clip to the next shot

minimaxrefdirector
MiniMax Reference Director

Storyboard your whole H3 video in one node instead of a spreadsheet

minimaxrefdirector
MiniMax Ref Ext Manager

No sockets, no outputs — this node is a button that fixes your missing nodes

MiniMax Ref Director/Utils
MiniMax Ref Guide

The loop body that turns one H3 timeline into N finished clips

minimaxrefdirector
MiniMax Ref Hybrid Loader

Steal the good parts of fl2va for ref2va

model/loaders
MiniMaxRef Join Strings

A tiny template node that saves you a pile of text-edit nodes

minimaxrefdirector
Merge Videos From Paths

Stitch your H3 segments back into one film, in the order you picked

minimaxrefdirector
MiniMaxRef Pure VRAM

A big red button that unloads every model when H3 starts eating your card

minimaxrefdirector
MiniMaxRef Save Audio

Get H3's generated audio out of the graph as a real file

minimaxrefdirector
MiniMaxRef Save Image

A save node that respects loops, batches, and changing filenames

minimaxrefdirector
MiniMax Reference Subject

Name your characters once, and the VLM stops forgetting who's who

minimaxrefdirector
Readme

MiniMaxRefDirector-ComfyUI

v3.1.9 — 面向 MiniMax H3 Reference-to-Video 的「导演式」多段分镜工作流。

ComfyUI 自定义节点包：在时间线上编排多段镜头，用 VLM 自动撰写分镜提示词，绑定参考图 / 参考视频 / 参考音频，逐段生成视频并跨段衔接（motion context），最终按顺序合并输出。

特性

  • 时间线导演（Timeline Editor）：在 Director 节点内直接编排多段时间线，每段独立设置提示词、时长、镜头、参考素材，所见即所得。
  • VLM 智能提示词写作：可选多种 VLM 服务（API 或本地 llama-cpp），根据画面描述自动生成分镜提示词；输出语言跟随你的输入（中文输入出中文，英文输入出英文）。
  • 导演向快捷控件：分镜编辑器一键多选运镜 / 景别 / 构图 / 微表情，随生成请求注入提示词；运镜支持时间线级全局默认与分段继承 / 覆盖，空选择即交由模型自由书写。
  • MiniMax H3 Reference-to-Video：为 H3 视频生成提供 reference 条件（参考图 / 参考视频 / 参考音频）。
  • Hybrid Loader：fl2va（高质量基底）+ ref2va（参考条件覆盖）混合加载，兼顾质量与参考跟随。
  • 视频素材条：
    • 生成视频自动回填到素材条；
    • 拖拽上传本地文件；
    • 多选后按选中顺序合并视频；
    • 多 Tab / 多工作流互不干扰（按节点隔离存储）。
  • API 配置面板：在 ComfyUI Settings 中可视化配置多家服务商。

安装

cd ComfyUI/custom_nodes
git clone https://github.com/<your-repo>/MiniMaxRefDirector-ComfyUI.git
cd MiniMaxRefDirector-ComfyUI
pip install -r requirements.txt   # 仅 av 一个额外依赖，其余由 ComfyUI 自带

重启 ComfyUI 后即可在节点列表中看到本包全部节点。

提示：前端 JS 改动后需强制刷新浏览器（Ctrl+F5）；后端 Python 改动需重启 ComfyUI；prompt/ 下的提示词模板每次调用时读取，即时生效。

节点

| 节点类名 | 功能 | | --- | --- | | MiniMaxRefDirector | 时间线导演：管理多段分镜时间线，汇总参考素材与全局配置，输出 guide_data | | MiniMaxRefGuide | 分镜引导：在循环（如 Easy-Use forLoop）中逐段取出 guide_data，构建 H3 的 positive conditioning 与 latent | | MiniMaxRefSubject | 主体分析：配置 VLM，分析/绑定视频中的主体，输出 subject 参考数据 | | MiniMaxRefJoinString | 字符串拼接 / 模板占位符替换，用于组装提示词模板 | | MiniMaxRefMergeVideosFromPaths | 按给定顺序合并多个视频文件（ffmpeg 拼接） | | MiniMaxRefSaveImage | 保存图像到输出目录 | | MiniMaxRefSaveAudio | 保存音频到输出目录 | | MiniMaxRefHybridLoader | fl2va + ref2va 混合加载器：加载基底模型并叠加参考条件覆盖 | | MiniMaxRefPureVRAM | 清理 VRAM / 卸载模型，防止长时间批量生成导致显存耗尽 |

使用流程

  1. 打开示例工作流 workflow/MinimaxH3 V3 示例.json（或从节点列表手动搭建）。
  2. 在 MiniMaxRefDirector 中打开时间线编辑器：添加素材（拖拽或上传）、编排分段、设置时长与镜头语言。
  3. 在 MiniMaxRefSubject 中配置主体分析与 VLM（如需自动生成提示词）。
  4. MiniMaxRefGuide 置于循环内，逐段取出 guide_data 构建 conditioning，送入 H3 采样器生成视频。
  5. 生成结果自动回填 Director 素材条；多选素材后可按选中顺序合并，得到完整成片。

推荐搭配 ComfyUI-H3-Motion-Context-MultiRef 使用，以实现跨段 motion context 衔接（相邻段尾部画面作为下一段参考）。v3.1.1 起仅依赖 MultiRef 变体，旧版 ComfyUI-H3-Motion-Context 需从 custom_nodes 中移除或改名为 .disable。

提示词模板

| 文件 | 说明 | | --- | --- | | prompt/minimaxh3_custom_ref2v_prompt_writing.txt | 自定义写作提示词：交给 VLM 按给定结构生成分镜 JSON | | prompt/minimaxh3_official_ref2v_prompt_writing.txt | 官方写作提示词：使用官方推荐的提示词策略 |

模板为纯文本，可在不改代码的前提下调整提示词策略（输出语言跟随用户输入、标点跟随输出语言等规则已内建）。

API 配置

进入 ComfyUI Settings → 打开「API Manager / API 配置」面板：

  • 选择服务商（智谱 GLM、Moonshot、通义 Qwen、豆包 Doubao、OpenAI 兼容等），填写 API Key。
  • 节点侧 api_provider 下拉会自动同步已配置的服务商。
  • VLM 模式可选：
    • API：走云端 VLM 服务；
    • llama-cpp / transformers：本地部署视觉模型（需自备模型文件）。

目录结构

MiniMaxRefDirector-ComfyUI/
├── __init__.py            # 节点注册
├── director.py            # 时间线导演节点
├── guide.py               # 分镜引导节点
├── subject.py             # 主体分析节点
├── server.py              # 后端 API（素材上传、视频合并、VLM 分析等）
├── api_config.py          # API 服务商配置
├── lib/                   # 辅助节点与核心逻辑（prompt / h3 / video / audio / image / llm / hybrid / utils）
├── js/                    # 前端 UI（时间线编辑器、素材条、API 配置面板等）
├── prompt/                # 提示词模板
├── workflow/              # 示例工作流
├── requirements.txt       # 依赖（av）
└── pyproject.toml

更新日志

v3.1.9

  • 插件 / LoRA 依赖管理节点（MiniMax Ref Ext Manager）：新增工具节点（MiniMax Ref Director/Utils），节点体上「打开管理面板」按钮弹出可拖拽/缩放面板，展示当前工作流用到的全部自定义节点归属插件与 LoRA 引用：
    • 已安装插件按目录列出并标注「工作流用到」，git 仓库型插件可一键 git pull 更新；
    • 工作流用到但本地缺失的插件：后端经 ComfyUI-Manager 数据库（custom-node-list.json + node_db/*，惰性读取 + 进程级缓存）给出候选仓库，选中后一键 git clone 到 custom_nodes；
    • LoRA：比对 models/loras 目录（名称 / 子目录 / 去扩展名 stem 匹配）；缺失引用可经 ModelScope（填 owner/name 或模型页链接 → 列出模型文件 → 选择下载）落盘到 models/loras；
    • 安装 / 更新完成后需重启 ComfyUI 生效（面板内有提示）。后端路由挂载于 server.py 现有 /minimax_ref/api/ext/* 组，逻辑见 ext_mgmt.py / ext_node.py。
  • 片段级「降噪」开关：分镜编辑器「引导强度」控件下方新增「降噪」开关与可折叠参数（起始α / 末端α / 斜坡 / 随机种子）。开启后 Guide 在 motion-context 路径内嵌调用 ComfyUI-H3-Context-Noise 注入锥形噪声（tail_frames 自动取该段引导强度吸附后的合法 H3 run）：
    • prev_tail / frames 路径：MiniMaxH3ContextTaperNoise；
    • 该插件未安装或调用失败时自动降级跳过（告警日志，行为等同未开启），不阻断执行。

v3.1.8

  • 优化主体参考绑定：
    • 绑定链路收敛到后端统一服务 /h3/build_subject_bindings：subject 定义（subject_definition）、保留分析（retention_analysis）与图片 / 音频 / 视频媒体清单由后端一次生成，前端（画布与分镜编辑器）直接消费结果，替代原先各处的本地拼装，多段复用与结果一致性更稳。
    • 描述区输入 @ 唤起主体选择器，快速插入 <@主体> 引用并自动完成绑定；引用类子主体按类型自动命名（图片 1 / 视频 1 / 音频 1）并回收复用，音频引用自动回写父主体的音轨绑定（audioRef）。
    • 保留描述支持段级覆盖：编辑器中针对某段手动指定的 retention 优先于主体卡片默认值。
    • 生成前对「被 @ 提及 / 已添加但未定义」的主体给出未匹配提醒，避免绑定静默丢失。
  • 提示词导演向快速功能：
    • 分镜编辑弹窗新增导演控制列：运镜 / 景别 / 构图 / 微表情 均为一键多选快捷标签（chip），点选即随该段生成请求注入；音频段自动隐藏运镜与表演控件。
    • 运镜支持时间线级「全局默认」（设置菜单），未单独设置的段自动跟随；任一段可点选覆盖为自定义，或一键清除回到「跟随默认 / 自由」，空选择即交由模型自由书写，避免技术标签污染正文。
    • 微表情内置表演提示词库（抿唇 / 转瞬微笑 / 视线游移等），支持从本地 JSON 导入自定义词库扩充；选中后由 LLM 按各镜头情绪织入克制写实的表演描写，中文输出下自然意译为中文。
    • 生成结果支持一键复制完整 H3 提示词（带剪贴板反馈）。
  • 翻译链路运镜保真：中 → 英翻译时把镜头运动改写为 camera motion, ... 触发短语并保护引号内容，确保下游运镜 LoRA 精确触发、台词/标语不被改写。
  • 片段级「双采」输出（Second Pass）：任一片段右键菜单可标记「Second Pass / 二次采样 X2」，片段右上角即时显示 #2 角标；Director 将 secondPass（可与 Flash VSR 的 upscale 叠加）逐段写入 guide 时间线，Guide 在循环中按段以布尔输出 secondPass，下游采样链路据此对该片段单独执行第二遍采样精修——逐段独立开关，不影响其他片段。
  • 分镜编辑器左侧面板支持分栏拖动调整宽度；LLM 生成任务改由后端统一调度处理；随版本更新示例工作流 workflow/MinimaxH3 V3.1.8.json。

v3.1.6

  • 时间线支持批量导出 Excel：一键将全部片段与主体导出为 .xlsm 文件（含 Timeline 与 Subjects 两个工作表，H3PromptJson / GuideStrength 等字段完整保留，片段列、主体关联关系列带下拉校验）。
  • 时间线支持导入 Excel：从 .xlsm（需为 Excel 另存的 XML 表格格式）还原全部片段与主体；片段 H3PromptJson 缺失时自动调用 VLM 生成；导入片段开始时间重叠时自动延后排序，并带导入进度动画。

v3.1.3

  • 修复 LLM 生成中文提示词偶发报错：parse_generated_json 改为 json.loads(..., strict=False)，允许 JSON 字符串值内出现未转义的控制字符（模型直接写原始换行/制表符），不再报 Invalid control character at: ...。
  • 中文提示词输出语言强制：生成 prompt 末尾追加 ## Output Language 强制指令（中/英文模板分别约束），中文模板的示例与语言规则同步改为中文，避免模型被模板中的英文正文/示例带偏——点「中」按钮后仍输出英文的问题。

v3.1.2

  • 提示词输入框关键词高亮：时间线编辑器与主体卡片的全部 prompt textarea（Segment Prompt、summary / detailed_description / overall_soundscape / non_diegetic_music、保留描述、H3 预览）支持 <@主体>、<#主体:对白>、<d>...</d> 彩色高亮，所见即所得。
  • 保留描述（段级覆盖）弹窗允许引用 relation:none（仅引用）的主体；左右 prompt 中仍保持禁用。
  • 生成提示词时间戳位置规则强化：At MM:SS.mmm 必须紧跟所属 [Shot N] 标记之后，禁止前置，避免模型生成"时间戳在镜头标记前"的错误写法。
  • 翻译保护增强：
    • 双引号（含全角 "…" / '…'）包裹的内容在翻译时保持原语言，不做占位掩码，杜绝改写（单引号 ' 不参与保护，避免与英文撇号冲突）。
    • 翻译模板明确：引号内台词/标语/歌名等逐字保留。
  • 视频素材去除"下载/投屏"按钮：controlsList="nodownload noremoteplayback" + disablePictureInPicture；并隐藏 360 等浏览器视频扩展注入的悬浮操作层。

v3.1.1

  • 修复 motion context 模块误命中：_get_motion_context_module() 此前按目录名前缀匹配，可能加载旧版 ComfyUI-H3-Motion-Context，其 MiniMaxH3MotionContext.apply() 缺少 encode_mode 参数，运行时报 TypeError: apply() got an unexpected keyword argument 'encode_mode'。
  • 现在仅匹配 ComfyUI-H3-Motion-Context-MultiRef（其 apply() 支持 encode_mode / anchor_mode / crop 显式参数），MultiRef 不存在时抛出明确错误提示，不再尝试兼容旧版。

v3.1.0

  • 修复音频链路误判：当时间线音频段越界、全为补白空白段、或源音频文件加载失败时，不再合成全零静音音轨，正确视为「无音频」——避免生成结果出现「无声 + 被标记无损（image_latent）」的错误分支。
  • 修复 master_audio 缓存误命中：缓存键由对象 id 改为内容指纹（sha1），消除 forLoop / 跨 prompt 场景下复用旧音频合成的隐患。
  • 新增轻量诊断日志：Guide / Director 输出 audio_segments 段数，便于排查音频链路。

v3.0.0

  • 全面重构为 MiniMax H3 Reference-to-Video 流程：
    • 新增时间线导演（Timeline Editor），多段分镜编排。
    • 新增 Hybrid Loader（fl2va + ref2va 混合加载）。
    • 新增视频素材条：生成视频自动回填、拖拽上传、按选中顺序合并。
    • 新增 subject 主体分析与 VLM 提示词写作。
    • 提示词输出语言跟随用户输入（中文/英文）。
    • 多 Tab / 多工作流素材隔离，互不干扰。
    • 节点 API 收敛为 MiniMaxRef* 系列，配置集中于 Settings 面板。

v2.1.0

  • 早期版本：基于 MiniMax 早期参考视频流程的导演节点与配置面板（已被 v3 取代，历史代码见 .bk 备份文件）。

免责声明

本项目为社区开源实现，与 MiniMax 官方无关联。使用请遵守各服务商 API 服务条款与相关法律法规。