ComfyUI-Yuan-Tool

ComfyUI 自定义节点集，面向 MiniMax H3 视频生成的时间轴工作流工具，含图像、文本、音频、CLIP 时间轴与引导注入等节点。

安装

cd ComfyUI/custom_nodes
git clone https://github.com/yuan-SiO2/ComfyUI-Yuan-Tool.git

依赖（requirements.txt）：opencv-python、numpy、torch、Pillow、color-matcher、nvidia-vfx、av

节点清单

图像（Yuan Tool/图像）

| 节点 | 说明 | | ---------- | ------------------------------------------------------- | | 多帧参考 | 将主体图/背景图扩展为带时间感知注意力的参考帧序列；无有效输入时兜底输出 1 张 64×64 空图 | | 筛选图像 | 按帧数+起始帧筛选图像列表，越界自动裁切；无有效输入时兜底空图 | | 加载批量图像 | 最多 20 轨批量图像加载器，中心裁切防失真，尺寸按 16 倍数对齐 | | 图像点处理 | 内嵌画布：点标注（左键正面、右键负面）与框标注（拖拽/缩放），多帧逐帧标注；输出坐标 JSON、边界框与帧索引 | | 色彩匹配 | 参考图 → 待匹配图颜色迁移，可选掩码控制区域，多模式 | | 全景预览 | 交互预览 ERP 全景图（360°/180°），支持视频批次，可切换全景/裁剪视角输出 | | 全景接缝 | 对视频潜空间做时域接缝修补（掩码插值），消除全景拼接痕迹 |

画布（Yuan Tool/画布）

| 节点 | 说明 | | ------------ | ----------------------------------------------------------- | | Yuan\_画布 | 基于 Fabric.js 的合成画布编辑器：背景 + 多图层/文字，可交互拖拽编辑并导出合成图（自动 16 倍数对齐） |

视频（Yuan Tool/视频）

| 节点 | 说明 | | ------------- | ---------------------------------------------------------------------------------- | | Yuan 加载视频 | 内置预览与时间轴裁剪：起止裁剪、交互裁剪框、最长边等比缩放、强制帧率；「智能分段输出」基于镜头检测自动分段，单段超 15 秒自动均分；输出图像/音频/帧数/分段总数 |

文本（Yuan Tool/文本）

| 节点 | 说明 | | ---------- | -------------------------------------------------------------------------------------------------------------------- | | 文本处理 | 分割段落/时间标记，可选输出任一段落；选取段落 = -1 输出全部，留空时总段为空 | | 列表编号 | 逐行添加编号（支持后缀）；空输入返回 [""] 保证列表输出不断 | | 格式转换 | 任意输入统一转为字符串列表；空容器返回 [""] | | 长度 | 统计文本长度与行数，支持多行合并 | | 出场排序 | 按验证对象首次出现位置升序输出（去重、未出现跳过） | | 文本批量替换 | 多组查找替换，支持正则/通配符，最长匹配优先；台词保护开启时引号内内容不替换 | | JSON提取 | 从剧本 JSON 提取整体风格、档案（角色/音色/道具/场景）、分镜序列（内置分镜角色替换：名称→、说话者→，开头前置 retention\_analysis 定义块，武戏不加编号，BGM 可关闭）、角色/音色/道具/场景索引、场景判断；七个选项开关（角色/音色/道具/场景/BGM/情节输出、台词保护）聚合为「开关配置」可选端口，由「JSON提取开关」子节点接入，未接入时按默认值执行（除情节输出默认整合格式外，其余默认开启） | | JSON提取开关 | 「JSON提取」的选项开关子节点：集中提供角色/音色/道具/场景/BGM/情节输出与台词保护七个开关，聚合为单个「开关配置」端口输出，接「JSON提取」的同名可选端口一次性控制；未接入子节点时 JSON提取按默认值执行 | | 分段时间提取 | 从分镜策划 JSON 的「分镜情节」按编号 1-N 顺序提取各分镜「类型」时长：时长列表（逗号分隔，可直接接 Yuan 加载音频分段时长）、时长序列（列表）、分镜数量、总时长 | | 预览内容 | 预览/编辑任意内容（输出节点）：预览模式只读展示上游内容（JSON 序列化），编辑模式直接输出文本字符串 |

音频（Yuan Tool/音频）

| 节点 | 说明 | | ------------- | ------------------------------------------------------- | | Yuan 音频列表 | 从 input 加载/上传音频（上限 30，支持视频提取音轨），按逗号索引输出 AUDIO 列表；留空输出全部 | | Yuan 音频分流 | 按索引顺序将音频列表分配到多个输出端口（输出数量 2\~30），不足输出 1ms 静音 | | Yuan 加载音频 | 内置播放器与时间轴裁剪：自定义裁切按起止时间截取；智能分段按「分段时长」切分并用「分段索引」选择输出；输出音频/时长/分段总数 |

选项（Yuan Tool/选项）

| 节点 | 说明 | | ------ | ---------------------------------------------------------------------- | | 选项 | 前端虚拟节点，复刻原生 Primitive：连接任意输入后自动读回其 COMBO 类型与选项，并把选项展开为互斥开关按钮，点击即写回目标输入 |

放大（Yuan Tool/放大）

| 节点 | 说明 | | ----------------- | ------------------------------------------------------------------------------------------------------ | | RTX 视频放大 (H3) | RTX 超分 + AV Decode Split + H3 Concat 一体节点，支持图像直连或 H3 联合 AV latent 输入，内置缓存；依赖 nvidia-vfx（NVIDIA RTX） | | H3 放大 | 纯 3D 卷积在 latent 空间放大 H3 视频（24 通道），跳过「解码→像素放大→再编码」；AV latent 仅放大视频流；模型放 models/latent_upscale_models/ | | 缩放Latent（比例） | 复刻原生 LatentUpscaleBy：按倍数/目标尺寸缩放，兼容 4D 常规 latent、5D H3 视频 latent（仅缩放空间）与 H3 联合 AV latent（仅缩放视频流、音频原样保留） |

MiniMax（Yuan Tool/MiniMax）

| 节点 | 说明 | | ------------------- | --------------------------------------------------------------------------------------------------------- | | MiniMax-H3 视频生成 | 调用 H3 生成视频+音频联合潜空间，输出正向条件与 AV 潜空间接采样器；支持图生视频（首/尾帧锚点）、参考图生视频（多路参考）、数字人三种模式 | | H3 运动上下文 | 取上一片段尾部连续帧作为不可去噪条件行，画面/声音直接从上一片段潜空间切片，实现无缝衔接；输出裁剪帧数「状态:长度」字符串；上下文潜空间可选，未连接时本地自动加载（存储位置随裁剪节点同步，片段 0 首片段直通） | | H3 运动裁剪 | 在 H3 AV 潜空间两段式裁切：头部按裁剪帧数整段裁掉（音视频共用切点、吸附 VRF 组边界），尾部按「保存到本地」保存一段供下一片段衔接 | | H3 渐进式采样器 | 先在空间降采样的 latent 上跑前段采样步，把干净端点提升到目标分辨率并在过渡 sigma 处重新加噪，再以全分辨率跑完剩余调度；仅使用正条件、不做 CFG；过渡点可选像素-VAE 锚点修正抑制提升伪影；可选高分辨率分块与 Sigma 加密（来源见鸣谢 SelfLift） |

CLIP（Yuan Tool/CLIP）

| 节点 | 说明 | | ---------------------------- | ------------------------------------------------------------ | | Yuan CLIP 时间轴 (Timeline) | 可视化时间轴编辑器，编排提示词与运动引导（详见下方工作流说明） | | Yuan 引导注入 (Guide) | 接收时间轴引导数据，编码构帧后拼接注入潜空间，实现时间感知注意力惩罚；可选 IC\_LORA 与 MSR LoRA 适配 |

时间轴工作流

时间轴节点编排各分镜的提示词、运动引导与音频，配合引导注入完成 H3 视频生成：

文本处理 → 时间轴 → 引导注入 → H3 视频生成
            ↑ 主体图 / 运动图像 / 音频

输入：模型/CLIP/音频VAE（可选）；全局提示词（支持 @图X=描述，@ 弹出已上传图像选择菜单）；文本输入（自动解析进时间轴，纯文本按时间轴长度均分）；最大帧数与宽/高/帧率；段落/运动图像与音频（自动生成对应轨段）；潜空间可选。

编辑器：主轨（提示词段）、IC-LoRA 轨（运动引导，支持图/视频上传）、音频轨（支持从视频提取音频）；工具栏「锁定」开启后全部只读仅可预览；右键/快捷键复制粘贴删除段，框选与属性面板联动。

输出：模型、正向条件、视频/音频潜空间、引导数据、运动引导数据、帧率、音频；其中引导数据接「Yuan 引导注入」，帧率/音频接 H3 视频生成。

更新记录

2026-09-11：补录遗漏节点：「H3 渐进式采样器」（采样来源见鸣谢 SelfLift）、「Yuan 加载音频」、「预览内容」；鸣谢新增 facok/comfyui-SelfLift。

2026-09-06：「分镜角色替换」并入「JSON提取」节点（分镜序列端口直接输出替换后文本，内置台词保护/音色输出开关，新增音色索引输出（位于角色与道具索引之间），移除角色道具场景输出端口；独立节点删除）；分镜序列开头（detailed\_description: 之前）前置 retention\_analysis 定义块（原「角色道具场景」端口输出内容，情节模式下前置档案描述纯文本）；新增「JSON提取开关」子节点（七个选项开关聚合为单个「开关配置」端口输出，接「JSON提取」的同名可选端口，未接入时按默认值执行：除情节输出默认整合格式外其余默认开启）。