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、Pillow、color-matcher、nvidia-vfx、av、torchaudio、scenedetect（torch 由 ComfyUI 提供）；「Yuan 视频保存」还需要 FFmpeg，默认由 imageio-ffmpeg 提供，也可使用系统 ffmpeg 或环境变量 YUAN_FFMPEG_PATH

节点清单

图像（Yuan Tool/图像）

| 节点 | 说明 | | ---------- | ------------------------------------------------------- | | 多帧参考 | 将主体图/背景图扩展为带时间感知注意力的参考帧序列；无有效输入时兜底输出 1 张 64×64 空图 | | 筛选图像 | 按帧数+起始帧筛选图像列表，越界自动裁切；无有效输入时兜底空图 | | 加载批量图像 | 最多 20 轨批量图像加载器，中心裁切防失真，尺寸按 16 倍数对齐 | | 图像点处理 | 内嵌画布：点标注（左键正面、右键负面）与框标注（拖拽/缩放），多帧逐帧标注；输出坐标 JSON、边界框与帧索引 | | 图像网格拼接 | 批量图像按宽幅×高幅等间隔拼成网格图：图少时均匀铺开（空缺填黑），图多时等间隔抽取且首尾必留；统一缩放到首张尺寸；按「文件名前缀 + 编号」保存到 output 目录（前缀可含子目录，编号直接决定 _00001_ 段、重复运行覆盖） | | 加载输出图 | 按「文件名前缀 + 编号」从 output 目录读取图像（规则同保存图像 {前缀}_{编号:05}_.png），输出图像与遮罩；文件不存在时输出空图 | | 色彩匹配 | 参考图 → 待匹配图颜色迁移，可选掩码控制区域，多模式 | | 全景预览 | 交互预览 ERP 全景图（360°/180°），支持视频批次，可切换全景/裁剪视角输出 | | 全景接缝 | 对视频潜空间做时域接缝修补（掩码插值），消除全景拼接痕迹 |

画布（Yuan Tool/画布）

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

视频（Yuan Tool/视频）

| 节点 | 说明 | | ------------- | ---------------------------------------------------------------------------------- | | Yuan 加载视频 | 内置预览与时间轴裁剪：起止裁剪、交互裁剪框、最长边等比缩放、强制帧率；「智能分段输出」基于镜头检测自动分段，单段超 15 秒自动均分；输出图像/音频/帧数/分段总数 | | Yuan 视频保存 | 把图像序列保存为视频或动图：MP4（H.264/H.265）、WebM（VP9/AV1）、GIF、WebP、PNG 序列、ProRes、FFV1 与 NVIDIA 硬件编码；可选音频混流、循环与往返播放，并生成首帧元数据图片；「图像」为可选输入端口，未接入时节点直接跳过、不报错；内置播放预览（沿用「加载视频」的播放方式，声音跟随鼠标：节点内播放、移出静音；无法播放的格式回退首帧） |

文本（Yuan Tool/文本）

| 节点 | 说明 | | ---------- | -------------------------------------------------------------------------------------------------------------------- | | 文本处理 | 分割段落/时间标记，可选输出任一段落；选取段落 = -1 输出全部，留空时总段为空；「段落优化」是选取之后的后处理：开启时把空段落/空端口从「总段」结果里去掉，选取「段落x」用的端口/行序号在开启与关闭时完全一致；关闭时空行原样保留 | | 列表编号 | 逐行添加编号（支持后缀）；空输入返回 [""] 保证列表输出不断 | | 格式转换 | 任意输入统一转为字符串列表；空容器返回 [""] | | 长度 | 统计文本长度与行数，支持多行合并 | | 出场排序 | 按验证对象首次出现位置升序输出（去重、未出现跳过） | | 文本批量替换 | 多组查找替换，支持正则/通配符，最长匹配优先；台词保护开启时引号内内容不替换 | | JSON提取 | 从剧本 JSON 提取整体风格、档案（角色/音色/道具/场景）、分镜序列（内置分镜角色替换：名称→、说话者→，开头前置 retention\_analysis 定义块，武戏不加编号，BGM 可关闭）、角色/音色/道具/场景索引、分镜类型（按「索引」分镜的「类型」输出：文戏 0 / 武戏 1 / MV 2 / 其他 3）、场景衔接；八个选项开关（角色/音色/道具/场景/BGM/情节输出、台词保护、情节衔接）聚合为「开关配置」可选端口，由「JSON提取开关」子节点接入，未接入时按默认值执行（情节输出与情节衔接默认关闭、其余默认开启）；「情节衔接文本」可选输入端口接入外部文本，情节衔接开启时定义块在场景行之后新增一行「：该文本」（编号顺延，场景为则新增），关闭或未接入时不新增；「模式」开关切换端口：分镜模式 8 个输出（分镜类型/分镜序列/角色索引/音色索引/道具索引/场景索引/索引时长/场景衔接）；档案模式 4 个输出（档案编码/作品名/整体风格/档案），并隐藏开关配置/情节衔接文本输入；「索引」含义随模式变化：分镜模式为分镜编号，档案模式为所选档案的第几条（0 起），「档案」输出该条「全名称 + 描述」两行（描述内「；补充：」保留） | | JSON提取开关 | 「JSON提取」的选项开关子节点：集中提供角色/音色/道具/场景/BGM/情节输出、台词保护与情节衔接八个开关，聚合为单个「开关配置」端口输出，接「JSON提取」的同名可选端口一次性控制；未接入子节点时 JSON提取按默认值执行 | | 分段时间提取 | 从分镜策划 JSON 的「分镜情节」按编号 1-N 顺序提取各分镜「类型」时长：时长列表（逗号分隔，可直接接 Yuan 加载音频分段时长）、时长序列（列表）、分镜数量、总时长 | | 预览内容 | 预览/编辑任意内容（输出节点）：预览模式只读展示上游内容（JSON 序列化），编辑模式直接输出文本字符串 | | 图像文本标签 | 把文字绘制成标签拼接在图像上/下/左/右（「覆盖」为直接叠加在原图上）；文字色与标签色用取色器选择，字体取自节点 fonts 文件夹 |

音频（Yuan Tool/音频）

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

选项（Yuan Tool/选项）

| 节点 | 说明 | | ------ | ---------------------------------------------------------------------- | | 选项 | 前端虚拟节点，复刻原生 Primitive：连接任意输入后自动读回其 COMBO 类型与选项，并把选项展开为互斥开关按钮，点击即写回目标输入 | | 自定义选项 | 编辑模式填写各选项名称；选项模式显示互斥开关，输出当前选项的文本与位置索引 | | 组节点选择 | 前端虚拟节点，复刻 rgthree 的 Fast Groups Bypasser：自动收集当前工作流（含子图）中的全部组，为每组生成一行开关——点击行内任意位置即把组内节点切到旁路 / 启用，点击行尾箭头定位并缩放到该组；右键菜单可切排序（位置 / 名称 / 自定义字母）、按颜色或标题过滤、设置「最多一个」「始终一个」互斥限制 |

放大（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 运动上下文 | 取上一片段尾部连续帧作为不可去噪条件行，实现无缝衔接；「衔接模式」二选一：视频图像（解码→重编码，与官方 Add Guide 同路径）/潜空间（直接切片上一片段 AV 潜空间，无质量损失）；输出裁剪帧数「状态:长度」字符串；上下文来源三选一（上传/端口/自动索引），端口与参数随「模式」「衔接模式」切换显隐 | | H3 运动裁剪 | 按「衔接模式」处理 H3 AV 潜空间（三选一）：视频图像模式解码为图像+音频后按像素裁切、尾段存 mp4；解码模式只解码不裁切（移除「裁剪帧数」输入端口并隐藏「片段序号」「保存到本地」「存储位置」，输出整段图像+音频）；潜空间模式按整 VRF 组直接裁切、尾段存 safetensors。输出槽随模式切换（图像+音频 / 潜空间），尾部按「保存到本地」保存一段供下一片段衔接；「裁剪帧数」端口未接入时不裁切、不保存本地，也不报错 | | H3 渐进式采样器 | 先在空间降采样的 latent 上跑前段采样步，把干净端点提升到目标分辨率并在过渡 sigma 处重新加噪，再以全分辨率跑完剩余调度；仅使用正条件、不做 CFG；过渡点可选像素-VAE 锚点修正抑制提升伪影；支持双模型接入（低分辨率模型负责前段，可选高分辨率模型负责收尾，未接入时沿用低分辨率模型）；可选高分辨率分块与 Sigma 加密（来源见鸣谢 SelfLift） |

CLIP（Yuan Tool/CLIP）

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