ComfyUI CineStyle

ComfyUI_CineStyle 是一组为ComfyUI 视频工作流开发的，更易于使用的自定义节点。 本项目是为轻量级视频处理而设定，不能替代专业视频编辑软件。

安装插件

• 使用ComfyUI Manager，搜索"ComfyUI_CineStyle"，安装插件。
• 或者在CompyUI插件目录(例如“CompyUI\custom_nodes\”)中打开cmd窗口，键入

git clone https://github.com/chflame163/ComfyUI_CineStyle.git

如何找到本节点组

• 在ComfyUI画布点击右键 - Add Node, 找到 "😺dzNodes/CineStyle"。

  

• 或者在ComfyUI画布双击, 在搜索框输入"cinestyle"。

  

示例工作流

workflow JSON 和示例素材位于插件的 workflows 子目录。本文档图片仅为示意。

更新说明

• 添加 CS VideoMaMa 节点，将逐帧二值 Mask 精修为时序 alpha matte。
• 添加 CS ProPainterX Inpaint 节点，用 ProPainterX 配合 MemFOF 光流擦除视频中被 mask 标记的对象，按空闲显存自动分批并交叉淡化拼接，结果贴回源分辨率。
• 添加 CS Image Composite 节点，将layer 序列帧通过可视化 Timeline 变换编辑器合成到 background 序列帧，支持可选mask输入，支持多种图层混合模式。
• 添加 CS Video Timeline Edit 节点，用于在双轨时间线上编辑标准视频片段，可自动检测片段，手动修剪/合并/移动/删除片段，对片段进行缩放/旋转/镜像/位移等变形操作。
• 添加 CS MatAnyone2 节点，将 Mask 转换为单目标人物或 union 前景的时序 alpha matte，支持单帧或连续mask，支持在任意位置定义锚定帧，支持多个锚点帧。
• 添加 CS Spatial Stabilize 和 CS Spatial Restore 节点，从视频 Mask 稳定并裁切局部区域，处理后可恢复到源视频位置。
• 添加 CS Color Match 节点，使用参考图自动匹配 IMAGE 帧批次的整体色调，支持多种颜色传递方法。
• 添加 CS Compare Any 节点，对两个相同类型的输入进行媒体画面对比或文本差异比较。
• 添加 CS Preview Any 节点，自动识别并预览 ComfyUI 的常见图像、视频、音频和数据类型。
• 添加 CS Mask Grow 节点，较官方Grow Mask节点运算速度大幅提升，并能更好的保持轮廓特征。
• 添加 CS Color Grade 节点，提供 HEX 白点、色温/色调、基础调色、RGB 通道控制、RGB多通道曲线和LUT加载，对视频进行专业级调色。
• 添加 CS Video Subtitle 节点，将 SRT 字幕渲染到标准 ComfyUI VIDEO，并提供字幕时间线编辑器。
• 添加 CS MOSS Audio Transcribe 节点，将标准 ComfyUI AUDIO 转写为带时间戳的 SRT。
• 添加 CS VFX Beauty 节点，自动估算视频片段肤色并执行皮肤磨皮美化处理。
• 添加 CS Video Segment (SAM3.1) 节点，在锚点帧用 Semantic、粗略 Mask、Point 或 BBox 定义对象，并自动传播 mask。
• 添加 CS Video Segment (SeC-4B) 节点，使用 SeC-4B 的概念理解和 LongSAM2.1 记忆传播 mask。
• 添加 CS SeC-4B Model Loader 节点，用于加载和复用 SeC-4B 推理模型。
• 添加 CS Load Video 节点，用于加载视频，支持出入点设置、更改画面尺寸和帧率。
• 添加 CS Save Video 节点，支持可选 metadata 写入、符合行业惯例的 H.264 目标码率控制。

节点说明

CS Video Timeline Edit

在标准 ComfyUI VIDEO 上进行双视频轨、双音频轨的非破坏式时间线编辑。节点支持片段裁切、移动、分轨、静音、A/V 链接、上下层合成，以及缩放、旋转、平移和镜像等画面变换。

使用流程

1. 将 VIDEO 输出连接到节点 video输入。节点支持接入官方或第三方 Load Video 节点；直连 CS Load Video 时可直接回溯来源，其他上游输入可通过 wait_for_input_cache 建立共享预览缓存。
2. 点击节点上的 Edit Timeline，在时间线中拖动片段边缘调整 In/Out，或使用右键菜单执行切分、合并和删除。
3. 在 Video1/Video2 和 Audio1/Audio2 轨道之间移动片段；选中视频片段后可调整缩放、旋转、平移和镜像。
4. 使用 Set In、Set Out 和 Play 检查选定范围，确认后点击 Apply to node 保存编辑结果。
5. 执行工作流得到最终 VIDEO。如果输入来自上游运行后才生成的视频，首次打开时间线前可开启 wait_for_input_cache 并运行一次工作流来建立预览缓存。

节点选项说明

• width：输出画布宽度；-1 使用输入尺寸，正数会按 multiple 向上取整。
• height：输出画布高度；-1 使用输入尺寸，正数会按 multiple 向上取整。
• multiple：输出宽高取整倍数，默认 32。
• fit_mode：片段适配输出画布的方式，可选 letterbox、crop 或 fill。
• fill_color：留边、空轨道和空白时间线区域使用的十六进制颜色。
• in_frame：输出时间线范围的起点帧；0 表示时间线首帧。
• out_frame：输出时间线范围的结束帧；-1 表示时间线尾帧。
• shot_detect_threshold：自动检测镜头切点的阈值。
• shot_detect_min_scene_sec：自动检测镜头切点的最短镜头时长。
• wait_for_input_cache：布尔开关，默认关闭。开启后执行节点时，将当前输入节点及其全部上游节点的链路指纹写入公共 Preview cache，然后中断本次 ComfyUI 执行。
• timeline_json：由 Edit Timeline 保存的时间线描述，一般无需手动编辑。

Edit Timeline 界面

时间线界面包含视频预览、In/Out 控件、当前帧指针、镜头检测、双视频轨、双音频轨、输出画布设置和片段变换参数。编辑操作使用低分辨率缓存提供快速反馈；点击 Play 时会在后台生成当前时间线的合成代理视频，执行节点时才进行全分辨率离线渲染。

预览与 In/Out

• 时间线上方的蓝色三角形是当前帧指针。单击或拖动指针可以定位到时间线中的任意帧，|< 和 >| 用于向前或向后移动一帧。
• Set In 和 Set Out 使用当前帧设置 In/Out。In/Out 同时控制 Play 的预览区间和节点的最终输出区间；out_frame 是不包含在输出内的结束边界，因此最后一帧为 out_frame - 1。
• 点击 Play 为当前编辑结果建立预览视频，并播放 In/Out 区间；再次点击可以暂停。

Detect Shots

• 点击 Detect Shots 自动分析输入视频的镜头切点，并按照检测结果把视频裁成连续片段。生成的画面片段和关联声音默认放在下层的 Video2 与 Audio2。
• Threshold 对应节点的 shot_detect_threshold。数值越高，切点判定越严格，通常得到的片段越少；数值越低，对画面变化越敏感，通常得到的片段越多。
• Min scene seconds 对应节点的 shot_detect_min_scene_sec。短于该时长的检测结果会与相邻镜头合并；设置为 0 表示不按最短时长合并。
• 自动检测会使用新的镜头片段替换当前时间线片段，并把 In/Out 恢复为检测后的完整时间范围。如需恢复检测前的编辑，可使用 Undo。

时间线轨道与缩放

• Video1 是上层视频轨，Video2 是下层视频轨。两轨同时有画面时，Video1 覆盖 Video2；同一轨道的片段重叠时，后放置的片段覆盖先放置的片段。两条视频轨均为空白的区域使用 Fill color填充。
• Audio1 和 Audio2 是两条音频轨。重合的声音会叠加，两条音频轨均为空白的区域输出静音。
• 按住片段主体并拖动，可以改变片段在时间线中的位置。视频片段可以在 Video1 与 Video2 之间移动；默认关联的音频会同步移动到对应的 Audio1 或 Audio2。
• 拖动片段左边缘或右边缘，可以逐帧缩短片段，也可以恢复或延长片段使用的源内容。延长不能越过输入源视频的首帧或尾帧，不会生成源范围以外的帧。
• + 和 - 分别用于放大和缩小时间线显示范围；鼠标滚轮也可以围绕鼠标所在帧进行缩放。Fit 恢复显示完整时间线，使时间线首尾与窗口左右两侧对齐；处于 Fit 状态时不能继续缩小。
• 放大时间线后，可以在轨道空白处按住鼠标左键并左右拖动，以平移当前显示的时间区间。

时间线右键菜单

在时间线的任意帧位置单击鼠标右键，可以使用以下命令：

• Split at this frame：在右键所在帧切开当前片段。切点必须位于片段内部。
• Merge Clip to Next：把当前片段与同轨道的下一个片段合并。两个片段必须在时间线上首尾相接、源帧连续，并使用相同的画面变换。
• Delete Clip：删除当前片段。删除视频片段时，其关联的音频内容也会一并删除。
• Reset Clip Transform：把当前片段的缩放、旋转、位移和镜像恢复为默认状态。

Output canvas

• Width / Height：设置最终输出画布宽度和高度。-1 表示使用输入视频对应边的源尺寸；输入正数时会按照 Multiple 向上取整。右侧的复位按钮可恢复默认值。
• Multiple：指定输出宽高必须满足的整数倍数，默认 32。例如输入 100 且 Multiple 为 32 时，实际尺寸向上取整为 128。
• Fit：设置片段适配输出画布的方式。letterbox 保持比例并用 Fill color 填充空边；crop 保持比例放大并裁去超出画布的部分；fill 不保持原比例，直接拉伸至整个画布。
• Fill color：设置 letterbox 的色条颜色，以及两条视频轨均无画面时的空白区域颜色。可以使用取色器或输入 #RRGGBB 十六进制色值。
• Output canvas 的修改会被 Undo / Redo 记录，最终在节点执行时应用于全部片段。

Selected clip

先在时间线上单击一个视频片段，再在 Selected clip 区域调整该片段的画面变换：

• Scale X / Scale Y：分别控制水平和垂直缩放，范围为 0.1–4，默认 1。中间的 Sync 按钮默认开启，开启时两项会同步变化；关闭后可以分别调整宽高比例。
• Translate X / Translate Y：控制片段相对输出画布中心的水平和垂直位移，范围为 -1~1，默认 0。
• Rotation：控制片段旋转角度，范围为 -90~90 度，默认 0。
• Mirror：镜像模式可选 none、horizontal 或 vertical，分别表示不镜像、水平镜像和垂直镜像。
• Scale、Translate 和 Rotation 同时提供滑块与数值输入框。拖动滑块时更新数值，松开后生成当前帧预览；每项右侧的复位按钮可单独恢复默认值。

Undo、Redo、Cancel 与 Apply

• Undo / Redo：撤销或恢复片段切分、移动、边缘修剪/延长、合并、删除、Transform 调整、Detect Shots 和 Output canvas 设置。当前帧移动、In/Out 设置和播放操作不进入历史记录。也可以使用 Ctrl+Z 撤销、Ctrl+Shift+Z 恢复。
• 编辑历史保存在 ComfyUI/temp 中，供当前节点回溯使用。
• Cancel：关闭窗口，放弃本次打开窗口后尚未应用的修改，并清除本次编辑历史。窗口右上角的关闭按钮行为相同。
• Apply to node：把当前时间线、In/Out、镜头检测参数和 Output canvas 设置写回节点并关闭窗口。再次打开 Edit Timeline 时会恢复已经应用的编辑结果；随后执行工作流才会生成最终全分辨率 VIDEO、IMAGE 和 audio 输出。

输出说明

• video：完成时间线合成、画布适配和 In/Out 裁切的标准 ComfyUI VIDEO。
• IMAGE：最终输出视频的 RGB 帧批次。
• frame_count：实际输出帧数。
• audio：按时间线轨道混合后的音频；没有音频时为空。
• video_info：包含源视频元数据、时间线范围、输出尺寸、帧率、帧数和时长。
• fps：实际输出帧率。

CS Image Composite

将一个 IMAGE layer 合成到 background IMAGE 上，适合静态图片和视频帧批次。节点使用 GPU 批处理执行图像变换和混合，支持 layer 位置、缩放、旋转、透明度和 Blend Mode。layer_image 与 background_image 的 batch 数量不一致时，layer 会按 ComfyUI 的单帧广播规则重复或截断到背景帧数。

使用流程

1. 将背景单帧或序列帧，例如 CS Load Video 的 IMAGE 输出连接到 background_image。输出的图片序列帧长度将与此处输入一致。
2. 将需要叠加的图片单帧或序列帧连接到 layer_image。
3. 可选地将标准 ComfyUI MASK 连接到 layer_mask。 mask 白色部分将作为显示区域，黑色作为隐藏区域。
4. 选择 blend_mode，设置固定的 opacity，然后直接执行节点；也可以点击节点上的 Edit Timeline 编辑 layer 的位置、缩放和旋转。
5. 在 Timeline 中确认预览结果后点击 Apply to Node，再执行工作流得到最终的 IMAGE 和透明 MASK 输出。
6. 如果输入来自上游运行后才生成的图像或视频，首次打开 Edit Timeline 前开启 wait_for_input_cache 并运行一次工作流，建立 Preview cache。

节点输入

• background_image：背景 IMAGE，作为最终输出画布。支持单张图片或视频帧 batch；输出帧数以 background batch 为准。
• layer_image：要合成的 layer IMAGE。支持单张图片或视频帧 batch；batch 为 1 时会广播到所有背景帧。
• layer_mask：可选标准 ComfyUI MASK。白色区域显示 layer，黑色区域隐藏 layer，灰度区域按覆盖率混合；mask 尺寸会自动适配 layer 尺寸。
• blend_mode：LayerStyle ImageBlendAdvance V2 风格的混合模式。可选 normal、dissolve、darken、multiply、color burn、linear burn、darker color、lighten、screen、color dodge、linear dodge(add)、lighter color、dodge、overlay、soft light、hard light、vivid light、linear light、pin light、hard mix、difference、exclusion、subtract、divide、hue、saturation、color、luminosity、grain extract 和 grain merge。
• opacity：layer 混合透明度，范围 0–100，默认 100。
• X：layer 中心点相对 background 画布的 X 坐标归一化位置，默认为 0.5。
• Y：layer 中心点相对 background 画布的 Y 坐标归一化位置，默认为 0.5。
• Scale_X：相对于 letterbox 适配基准的水平缩放，默认为 1.0。
• Scale_Y：相对于 letterbox 适配基准的垂直缩放，默认为 1.0。
• Sync_Scale：是否同步 Scale X 和 Scale Y，默认开启。
• Rotation：layer 旋转角度，单位为度，默认 0。
• wait_for_input_cache：布尔开关，默认关闭。开启后执行节点时，会把当前输入及其完整上游链路写入共享 Preview cache，然后中断本次执行，供 Edit Timeline 回溯查看。

节点输出

• image：合成后的 RGB IMAGE batch，尺寸和帧数以 background image 为输出基准。
• composit_mask：合成后的 MASK。

Edit Timeline 界面

Edit Timeline 只针对节点输入的 layer 图层，无关键帧。无论当前位于时间线的哪一帧，调整位置、缩放或旋转都应用到整个 layer 序列。

时间线、当前帧和 In/Out

• 时间线上方的蓝色三角形是当前帧指针。拖动指针或点击轨道可以定位到任意帧。
• |< 和 >| 用于前进或后退一帧。
• Set In 和 Set Out 使用当前帧设置预览范围。Play 只播放 In/Out 区间。
• 点击 Play 为当前区间生成逐帧合成预览缓存。
• 修改 In/Out、位置、缩放、旋转、opacity 或 blend mode 后，旧 playback cache 会失效，下次播放时自动重新生成。

Blend Mode、Opacity 与变换参数

• Blend Mode：选择 layer 混合模式，整段 layer 序列使用同一个模式。可选项为 LayerStyle ImageBlendAdvance 风格的混合模式。可选 normal、dissolve、darken、multiply、color burn、linear burn、darker color、lighten、screen、color dodge、linear dodge(add)、lighter color、dodge、overlay、soft light、hard light、vivid light、linear light、pin light、hard mix、difference、exclusion、subtract、divide、hue、saturation、color、luminosity、grain extract 和 grain merge。
• Sync Scale：默认开启。开启时 Scale X 和 Scale Y 同步，保持 layer 的宽高比例；关闭后可分别改变两个方向的缩放。
• Opacity：整段序列固定的 layer 透明度，范围 0–100。滑块右侧的数值框和复位按钮可进行精确输入或恢复默认值。
• Rotation：layer 旋转角度，支持滑块、数值输入和复位按钮。也可以拖动 layer 上方的旋转控制点。
• X / Y：layer 中心点相对 background 画布的归一化位置。0.5, 0.5 表示画布中心；支持滑块、数值输入和复位按钮。
• Scale X / Scale Y：相对于 letterbox 适配基准的水平/垂直缩放。默认基准为 1.0，即 layer 按宽高比适配 background 后的尺寸。

预览视口中的拖动操作

• 拖动 layer 主体可以实时调整 X/Y 位置。
• 拖动四角控制点可以调整 Scale X/Scale Y；Sync Scale 开启时保持宽高比，关闭时允许两个方向独立变化。
• 拖动顶部旋转控制点可以实时调整 Rotation。

Apply、Cancel 与恢复默认

• Reset Transform：恢复 X、Y、Scale X、Scale Y 和 Rotation 的默认状态。
• 每个参数右侧的复位按钮只恢复对应参数；Sync Scale 开启时，恢复任一缩放参数会同时恢复两个缩放轴。
• Apply to Node：将当前 Timeline 变换、Blend Mode、Opacity 和 Sync Scale 状态写回节点。
• Cancel 或右上角关闭按钮：关闭窗口并放弃本次尚未应用的修改。

CS VFX Beauty

为视频优化的皮肤磨皮美化处理节点。节点优先使用输入的 MASK；没有连接 MASK 时，自动使用 BiSeNet 估算目标肤色。

部署 BiSeNet 权重

权重文件 parsing_bisenet.pth放置于：

ComfyUI/models/facexlib/parsing_bisenet.pth

首次运行且本地不存在权重时，节点会自动从 FaceXLib 上游官方的 GitHub Release 下载地址 或者 Hugging Face 上的 parsing_bisenet.pth 镜像 下载权重。 也可以手动下载后放置到 ComfyUI/models/facexlib/parsing_bisenet.pth。

使用流程

1. 将视频帧批次连接到 image。节点也支持接入官方或第三方 Load Image 节点；直连 CS Load Video 或 Load Image 时可直接回溯来源，其他上游输入可通过 wait_for_input_cache 建立共享预览缓存。
2. 如果有现成的皮肤区域，将标准 ComfyUI MASK 连接到 mask；没有 mask 时，首次自动估色会使用 BiSeNet 临时生成皮肤区域。
3. 保持 colour=auto 使用整段输入的自动肤色估计，或输入合法的 #RRGGBB 颜色跳过自动估色。
4. 点击节点底部的 VFX Preview，在当前帧调整参数并实时预览；确认后点击 Apply to Node 保存预览参数。
5. 如果输入来自上游运行后才生成的图像或视频，首次打开 VFX Preview 前先设置wait_for_input_cache 为 ture 并运行一次工作流，建立 Preview cache。

节点选项说明

• image：标准 ComfyUI IMAGE，支持 [batch, height, width, channels] 的单张图片或视频帧批次。直连 CS Load Video 或 Load Image 时可直接回溯来源；其他上游输入可通过 wait_for_input_cache 建立共享预览缓存后使用。
• mask：可选标准 ComfyUI MASK。连接后自动作为皮肤处理区域，也作为自动肤色估计区域。
• colour：字符串，默认 auto。auto 使用自动估色；输入 #RRGGBB 时直接使用指定 RGB 颜色。
• weights：HSV Key 权重字符串，默认 6.0, 0.0, 3.0。在 VFX Preview 中会拆分为 Hue、Saturation、Value 三个独立输入，Apply 时保存参数。
• blur_m / Soften：皮肤 Matte 的柔化半径，默认 10.0。
• sigma / Amount：边缘保持模糊强度，默认 10.0。
• threshold / Preserve Edges：边缘保护阈值，默认 15.0。
• r_spots_blend / Dark Spots：暗斑修复混合比例，默认 0.8。
• r_h_blend / Highlights：高光修复混合比例，默认 0.5。
• strength / Restore Detail：高频细节恢复强度，默认 0.0。
• blur_h / Detail Soften：恢复细节的柔化半径，默认 0.0。
• blur_s / Blur Shine：皮肤高光柔化半径，默认 30.0。
• o_amount / Shine Amount：高光恢复量，默认 0.2。
• sat_amount / Saturation：最终肤色饱和度缩放，范围 0–300，默认 100.0。
• hue_amount / Hue Shift：最终肤色色相偏移，范围 -360–360 度，默认 0.0。
• wait_for_input_cache：布尔开关，默认关闭。开启后执行节点时，将当前输入节点及其全部上游节点的链路指纹写入公共 Preview cache，然后中断本次 ComfyUI 执行。

VFX Preview 界面

• 双视口：左侧 Original 显示原始帧，右侧 Result 显示当前参数的处理结果。Result 中央的对比条默认在最左侧，因此打开窗口时完整显示 Result；左右拖动对比条可比较 Original 和 Result。
• 缩放和平移：点击 50%、100%、200% 或 Fit 调整显示比例，也可以在任一视口滚动鼠标滚轮缩放。缩放超过 Fit 后，在任一视口按住鼠标左键拖动，两个视口会同步平移。
• 时间线：拖动底部时间线快速定位帧，输入帧号可直接跳转，|< 和 >| 用于单帧步进。切换帧后只重新计算当前帧的预览结果。
• Colour：输入 auto 使用自动肤色；预览首次计算出的颜色会显示在右侧色块和 Hex 数值中。点击色块可以打开标准 RGB 取色器，选择颜色后会切换为固定 #RRGGBB。
• Weights：Hue、Saturation、Value 分成三个数值栏，分别控制 HSV 色键对色相、饱和度和明度的敏感度。
• 参数滑块：每个滑块下方显示简短说明和默认值，右侧复位按钮可以单独恢复初始值。调整滑块后，Result 会实时重新处理当前帧。

自动肤色估计

当 colour=auto 时，节点将加载 BiSeNet并计算皮肤区域的目标颜色。在colour选项输入 Hex 颜色字符串#RRGGBB将跳过自动检测肤色流程。

输出说明

• IMAGE：RGB 处理结果，不包含 Alpha，可直接连接下游图像或视频节点。
• MASK：皮肤处理遮罩输出。

CS Color Grade

提供 HEX 白点、色温/色调、基础调色、RGB 通道控制、RGB多通道曲线和LUT加载，对视频进行专业级调色。

使用流程

1. 将图片节点或 CS Load Video 的 IMAGE 输出连接到 image。CS Load Video 输入可以为视频帧批次，节点会按帧批次逐块处理。
2. 将可选的 MASK 连接到 mask。黑色区域保持原图，白色区域应用完整调色，灰度区域按遮罩值线性混合。
3. 将 .cube 文件放入 ComfyUI/models/luts/，在 Load LUT 中选择文件；不需要外部 LUT 时选择 None。使用 LUT Strength 控制外部 LUT 的混合强度，0 为不应用 LUT，1 为完整应用。
4. 直接执行节点得到 RGB IMAGE，或先点击 Grade Preview 调整当前帧，再点击 Apply to Node 将预览参数写回节点。
5. 如果输入来自上游运行后才生成的图像或视频，首次打开 Grade Preview 前先设置wait_for_input_cache 为 ture 并运行一次工作流，建立 Preview cache。

节点输入

• image：标准 ComfyUI IMAGE。直连 CS Load Video 或 Load Image 时可直接回溯来源；其他上游输入可通过 wait_for_input_cache 建立共享预览缓存后使用。
• mask：可选标准 ComfyUI MASK。
• Load LUT：加载外部LUT文件，默认 None。支持 1D LUT、3D LUT，以及带 1D Shaper 的 1D+3D LUT。新增文件后需要刷新节点列表或重启 ComfyUI 才会出现在选项中。
• LUT Strength：外部 LUT 的混合强度，范围 0–1，默认 1。0 保持应用其它调色参数后的结果，0.5 为一半 LUT 效果，1 为完整 LUT 效果。
• White Point：#RRGGBB 格式的颜色字符串，默认 #FFFFFF对应中性白点。
• Color Temperature：范围 -1–1，默认 0。与 Tint 一起参与白平衡计算。
• Tint：白平衡中的绿色/洋红偏移，范围 -1–1，默认 0。
• Offset：三个通道同时增加的整体偏移，范围 -1–1，默认 0。
• Multiply：三个通道同时使用的整体增益，范围 0–2，默认 1。
• Gamma：三个通道同时使用的 Gamma，范围 0–10，默认 1；实际计算使用 1 / Gamma 指数，并保留负值的符号。Gamma 必须大于 epsilon。
• Brightness：Gamma 后的整体加法偏移，范围 -1–1，默认 0。
• Contrast：以 0.5 为中心的线性对比度，范围 -1–1，默认 0。0 不改变对比度，-1 将所有值压到 0.5，正值提高对比度。
• Saturation：基于 Rec.709 亮度权重的饱和度，范围 0–10，默认 1。0 为灰度，1 保持原饱和度，大于 1 会增强色彩。
• RGB Offset：分别作用于 R、G、B 的偏移数组，默认 [0.0,0.0,0.0]。
• RGB Multiply：分别作用于 R、G、B 的增益数组，默认 [1.0,1.0,1.0]。
• RGB Gamma：分别作用于 R、G、B 的 Gamma 数组，默认 [1.0,1.0,1.0]；每个通道必须大于 epsilon。
• curves：RGB 主曲线和 R/G/B 独立曲线的 JSON 字符串。该输入属于高级参数，通常通过 Grade Preview 编辑，不建议手动修改。
• wait_for_input_cache：布尔开关，默认关闭。开启后执行节点时，将当前输入节点及其全部上游节点的链路指纹写入 Preview cache，然后中断本次 ComfyUI 执行。

输出

• IMAGE：调色后的 RGB 图像。

外部 LUT

LUT 文件必须放在 ComfyUI/models/luts

Grade Preview

Preview 窗口包含当前帧预览、对比层、缩放、时间线和调色参数区：

• 预览视口显示 Result / Original。拖动中间的对比条可以在原图和结果之间进行左右比较。
• 50%、100%、200% 和 Fit 用于设置缩放；放大后按住鼠标左键拖动可以平移画面，鼠标滚轮也可以调整缩放比例。
• 时间线支持拖动定位、帧号输入，以及 |< / >| 单帧前进和后退。视频帧批次会显示总帧数。
• 点击 White Point 的色块打开取色器，旁边的文本框接受严格的 #RRGGBB 格式。
• LUT Strength、Color Temperature、Tint、Brightness、Contrast 和 Saturation 使用滑块，并保留数值输入框和单项重置按钮；拖动 LUT 强度会实时更新当前帧预览。
• Offset、Multiply 和 Gamma 包含整体滑块、RGB 色轮以及 R/G/B 数值。在色轮上拖动鼠标改变对应的 RGB 通道参数，数值框可进行精确调整。
• 曲线可分别调整 RGB、R、G、B 四个通道；Reset 重置当前曲线。在曲线编辑器单击空白处添加点，按住拖动控制点，右键删除点；端点不可删除。
• Reset All 重置所有参数、RGB 数组、LUT 选择和曲线。
• 点击 Apply to Node 把当前参数写回节点；点击 Close 关闭窗口并放弃未应用的修改。

CS Color Match

将源 IMAGE 帧批次的整体色调、色相和色度匹配到参考图，保留明暗关系、对比度和纹理细节。

使用流程

1. 将图片节点或 CS Load Video 的 IMAGE 输出连接到 image。
2. 将色调参考图片连接到 reference_image。如果输入的是 batch ，只使用第一张图片。
3. 选择颜色传递方法和颜色空间。默认组合为 Optimal Transport + OKLab，适合大部分视频色调匹配。
4. 调整匹配强度、亮度/对比度/饱和度保护以及色相/色度强度，然后直接执行工作流，或点击 Match Preview 预览当前帧的匹配效果。
5. 在预览窗口中调整参数后，点击 Apply to Node 将参数写回节点，再执行工作流得到完整输出。
6. 如果输入来自上游运行后才生成的图像或视频，首次打开 Match Preview 前先开启 wait_for_input_cache 并运行一次工作流，建立 Preview cache。

节点输入

• image：标准 ComfyUI IMAGE，支持 [batch, height, width, 3 or 4]`。输出为 RGB 三通道，源帧尺寸和帧顺序保持不变。
• reference_image：标准 ComfyUI IMAGE。只使用第一张参考图；参考图最长边超过 2048时，仅在统计阶段缩小到最长边2048`，不会影响源帧输出分辨率。
• Method`：颜色传递方法。
  • Optimal Transport：使用正则化的高斯最优传输映射，默认方法。
  • Reinhard：匹配颜色通道的均值和标准差，效果保守、速度快。
  • LHM：使用颜色协方差进行线性匹配，适合整体色彩风格迁移。
  • PCCM：使用主成分轴和方差匹配，色彩变化更明显。
  • PDF：使用多次投影的分布匹配，适合复杂或多峰色板，但计算时间更长。
• Color Space：颜色空间，可选 Lab 或 OKLab。通常推荐 OKLab，其亮度、色相和色度控制更适合保持原视频结构。
• Match Strength：整体匹配强度，范围 0–1，默认 0.75。0 返回原图，1 完整应用匹配后的亮度、色相和色度目标。
• Preserve Luminance：亮度保护，范围 0–1，默认 1。1 保留源图的感知亮度，适合不希望改变视频明暗关系的场景。
• Preserve Contrast：对比度保护，范围 0–1，默认 1。用于恢复源图的亮度对比度分布；节点不会对帧进行空间模糊或重采样。
• Preserve Saturation：饱和度/色度保护，范围 0–1，默认 0。1 保留源图的色度大小，但不阻止色相匹配。
• Hue Strength：色相匹配强度，范围 0–1，默认 1。低色度区域会自动降低色相变化，减少中性区域的色偏噪声。
• Chroma Strength：色度匹配强度，范围 0–1，默认 1。
• wait_for_input_cache：布尔开关，默认关闭。开启后执行节点时，将 image 和 reference_image 的输入链路写入共享 Preview cache，然后中断本次 ComfyUI 执行，供 Match Preview 使用。

输出

• IMAGE：完成颜色匹配的 RGB 图像。

Match Preview

Preview 窗口上半部分为当前帧的匹配对比视口，下半部分为颜色匹配参数：

• 预览视口显示 Result / Original。拖动中间的对比条可以在原图和匹配结果之间进行左右比较。
• 50%、100%、200% 和 Fit 用于设置缩放；放大后按住鼠标左键拖动可以平移画面，鼠标滚轮也可以调整缩放比例。
• 时间线支持拖动定位、帧号输入，以及 |< / >| 单帧前进和后退。输入为视频帧批次时会显示总帧数。
• Method 和 Color Space 可以在预览窗口中切换颜色传递方法与颜色空间，初始值与节点当前参数一致。
• Match Strength、Preserve Luminance、Preserve Contrast、Preserve Saturation、Hue Strength 和 Chroma Strength 均提供滑块、数值输入框和单项重置按钮；调整后会重新渲染当前帧预览。
• Reset All 将预览参数恢复为节点默认值：Optimal Transport、OKLab、Match Strength 0.75 以及其余参数的默认值。
• 点击 Apply to Node 将当前预览参数写回节点；点击 Close 关闭窗口并放弃未应用的修改。

CS SeC-4B Model Loader

加载SeC-4B 模型，为 CS Video Segment (SeC-4B) 节点和 Selector Preview 提供可复用的模型实例。节点扫描 ComfyUI/models/sams/SeC-4B 目录下的单文件权重。

节点选项说明

• model_file：支持 SeC-4B-bf16.safetensors 和 SeC-4B-fp16.safetensors，节点按文件原生精度加载。
• device：运行设备，auto 自动选择 CUDA，cpu 使用 CPU，也可选择具体的 gpu0、gpu1 等设备。
• 选择 cpu 时，BF16/FP16 权重会自动转换为 float32。
• use_flash_attn：高级选项，默认开启。环境没有 FlashAttention 时会回退到标准注意力。
• allow_mask_overlap：高级选项，默认开启，允许多个对象的 Mask 重叠。
• SEC_MODEL：输出的 SeC-4B 模型连接到 Video Segment 节点的 model。

首次执行 Loader 或首次进行 SeC Preview 时，如果选择的权重文件不存在，节点会自动从 Hugging Face 下载对应的单文件权重到 ComfyUI/models/sams/SeC-4B。默认 BF16 文件约 7.35 GiB。自动下载需要当前环境可以访问 Hugging Face；失败时可手动下载：

BF16 权重下载地址

FP16 权重下载地址

将所选文件放置到：

ComfyUI/models/sams/SeC-4B

配置和 tokenizer 已随插件放在 py/sec_model_config，依赖声明位于项目根目录 requirements.txt，推理代码和 SAM2 配置位于 py/sec_inference 与 py/sec_configs。

CS Video Segment (SeC-4B)

使用 OpenIXCLab SeC-4B 模型，在锚点帧用多个 BBox、多个正负 Point 和粗略 Mask 定义对象，并传播到整段视频。

使用流程

1. 先执行 CS SeC-4B Model Loader，再把输出的 SEC_MODEL 连接到节点的 model。
2. 将 CS Load Video 的 IMAGE 或 VIDEO 输出连接到节点。images 与 video_input 同时连接时，节点优先使用 images；其他上游输入可通过 wait_for_input_cache 建立共享预览缓存。
3. 点击 Open Selector，在锚点帧中定义一个或多个对象的提示。
4. 点击 Preview Current Frame 检查 SeC-4B 的当前帧分割结果，确认后点击 Apply to Node。
5. 执行节点，得到整段视频的 mask。默认情况下，节点执行结束会卸载 SeC-4B 的推理子模型以释放显存。
6. 如果输入来自上游运行后才生成的图像或视频，首次打开 Open Selector 前先设置wait_for_input_cache 为 ture 并运行一次工作流，建立 Preview cache。

节点选项说明

• model：CS SeC-4B Model Loader 输出的 SEC_MODEL，必需输入。
• images：可选 IMAGE 帧批次。直连 CS Load Video 时可直接回溯来源；其他上游输入可通过 wait_for_input_cache 建立共享预览缓存后使用。
• video_input：可选 VIDEO 输入，仅在 images 未连接时使用。
• anchor_frame：锚点帧在当前输入帧批次中的本地编号，从 0 开始，通常由 Selector 自动写入。
• prompt_data：Selector 序列化的多对象 Mask、BBox 和 Point 提示数据，不建议手动编辑。
• tracking_direction：传播方向，bidirectional 双向传播，forward 向后传播，backward 向前传播。
• max_frames_to_track：每个方向最多传播的帧数，-1 表示直到视频边界。
• mllm_memory_size：场景变化时用于提取对象概念的历史关键帧数量，默认 12。
• offload_video_to_cpu：将视频推理状态尽可能放到 CPU，以降低显存占用，但会降低速度。
• auto_unload_model：默认开启。节点执行结束后卸载 SeC-4B 子模型；下次执行或 Preview 时会自动重载。
• wait_for_input_cache：布尔开关，默认关闭。开启后执行节点时，将当前输入节点及其全部上游节点的链路指纹写入公共 Preview cache，然后中断本次 ComfyUI 执行。
• Open Selector：打开交互式提示编辑器。

输出说明

• mask：形状为 [帧数, 高, 宽] 的整段视频 mask。
• anchor_mask：锚点帧的合并分割 mask。
• video_info：包含帧数、尺寸、锚点帧、传播方向和对象数量。

CS Video Segment (SAM3.1)

使用 ComfyUI 官方 SAM3/SAM3.1 模型和推理内核，把 Selector 中定义在锚点帧的多个对象提示传播到整段视频。 SAM3.1 官方权重下载地址：Comfy-Org/sam3.1。下载后放入 ComfyUI 的 models/checkpoints

使用流程

1. 使用官方 CheckpointLoaderSimple加载 SAM3/SAM3.1 模型，并连接节点的 model。
2. 将 CS Load Video 的 IMAGE 或 VIDEO 输出连接到节点。images 与 video_input 同时连接时，节点优先使用 images；其他上游输入可通过 wait_for_input_cache 建立共享预览缓存。
3. 点击节点上的 Open Selector，在实际输入视频的帧上定义提示。
4. 点击 Selector 的 Preview Current Frame 检查当前帧分割结果，确认后点击 Apply to Node。
5. 执行节点，得到整段视频的 mask。
6. 如果输入来自上游运行后才生成的图像或视频，首次打开 Open Selector 前先设置wait_for_input_cache 为 ture 并运行一次工作流，建立 Preview cache。

节点选项说明

• model：官方 SAM3/SAM3.1 模型，必需输入。
• images：可选 IMAGE 帧批次。直连 CS Load Video 时可直接回溯来源；其他上游输入可通过 wait_for_input_cache 建立共享预览缓存后使用。
• video_input：可选 VIDEO 输入，仅在 images 未连接时使用。直连 CS Load Video 时可直接回溯来源；其他上游输入可通过 wait_for_input_cache 建立共享预览缓存后使用。
• anchor_frame：锚点帧在当前输入帧批次中的本地编号，从 0 开始。通常由 Selector 自动写入。
• prompt_data：Selector 序列化的 Mask、BBox、Point 和对象列表，不建议手动编辑。
• propagation_direction：传播方向，both 双向传播，forward 向后传播，backward 向前传播。
• max_objects：SAM3.1 的最大对象槽数量，默认 16。
• wait_for_input_cache：布尔开关，默认关闭。开启后执行节点时，将当前输入节点及其全部上游节点的链路指纹写入公共 Preview cache，然后中断本次 ComfyUI 执行。
• Open Selector：打开交互式提示编辑器。

输出说明

• mask：分割的视频 mask。
• anchor_mask：锚点帧的分割 mask。
• video_info：包含帧数、尺寸、锚点帧、传播方向和对象数量。

Selector 使用说明

SAM3.1 和 SeC-4B 共用同一个 Selector 框架。两者都支持多对象；SAM3.1 由官方模型批量处理对象，SeC-4B 会逐对象建立跟踪条件后合并结果。Semantic 选项卡仅对 SAM3.1 显示，SeC-4B 使用 Draw Mask、Edit BBox 和 Edit Point。

如果输入来自上游运行后才生成的图像或视频，首次打开 Open Selector 前先设置wait_for_input_cache 为 ture 并运行一次工作流，建立 Preview cache。

时间控制和锚点帧

• 时间线上方的 |< 和 >| 用于逐帧移动，滑杆和帧号输入框用于快速定位。
• 只允许一个锚点帧存在。第一次在某帧产生有效的 Mask、BBox 或 Point 后，该帧成为锚点。
• 已存在编辑数据时切换帧，会提示“当前已存在编辑数据，切换锚点帧将自动清除，是否继续？”。确认后会清除全部对象提示和 Undo/Redo 历史。
• 切换到新帧后，只有重新添加提示，该帧才会成为新的锚点。
• 已经点击 Apply to Node 的工作流再次打开 Selector 时，会自动跳转到保存的锚点帧并恢复提示。
• anchor_frame 是当前输入帧批次的本地帧号。

Draw Mask

• 进入 Draw Mask 后，鼠标光标显示当前画笔大小的半透明空心圆。
• Brush/Eraser 切换键在画笔和橡皮擦之间切换；画笔状态为绿色，橡皮擦状态为红色。
• Brush Size 范围为 2–100。拖动滑杆或在视频画布上滚动鼠标滚轮快速调整；按住 Shift 滚轮可大步调整。
• Clear Mask 清除当前对象的粗略 Mask。
• 粗略 Mask 只作为模型提示，点击 Preview 后画布会隐藏粗略笔迹，仅显示模型返回的分割结果。

Edit BBox

• 点击 Add BBox 后，在视频画布上拖出一个新框；松开鼠标后自动退出添加状态。
• 鼠标移到四角时可拖拽调整宽高，移到水平或垂直边时可单独调整对应边的位置。
• 鼠标移到框内部时显示手形光标，拖拽可移动整个框。
• 在框内部点击右键，选择“删除BBox”删除当前对象的框。
• 使用公共的 Add Object 创建更多对象，再为每个对象添加自己的 BBox。
• Clear All BBox 清除所有对象的 BBox，但不会清除 Point 或粗略 Mask。

Edit Point

• 空白处左键添加 positive point。
• 空白处右键添加 negative point。
• 已有 Point 左键按住并拖动可移动；如果没有实际移动，释放鼠标不会新增或修改 Point。
• 已有 Point 右键打开菜单，可删除 Point，或在 positive/negative 之间切换。
• Clear All Point 清除所有对象的 Point，但不会清除 BBox 或粗略 Mask。

对象和公共按钮

• Object 下拉框选择当前编辑对象。
• Add Object 增加对象；Delete Object 删除当前对象。
• Undo / Redo 撤销或恢复最近一次提示编辑。
• Clear All Prompt 清除所有对象的 Mask、BBox 和 Point。
• Preview Current Frame 只运行当前锚点帧的模型分割，结果用于检查提示是否合理，不会替代最终整段视频执行。
• Cancel 关闭窗口并放弃本次未应用的修改。
• Apply to Node 将提示数据和锚点帧写入节点。

CS MatAnyone2

将与视频逐帧匹配的 MASK 转换为 MatAnyone2 的浮点 alpha matte。节点面向单目标人物或单个 union 前景。

工作流程与注意事项

1. 将 IMAGE 和 MASK 连接到 CS MatAnyone2。
2. 如果是单帧 mask 输入，则在Anchor frames中填入该帧对应的序号，首帧为0。例如 mask 是第10帧，则填入[9]。
3. 如需手动选择锚点帧，先启用 wait for input cache 执行一次，再打开 Matte Preview 编辑锚点帧，可定义多个锚点帧。
4. Apply 后关闭 wait for input cache，再次执行得到整段 alpha matte。

锚点帧最小间距、滞回和上限只影响候选分析： 最小间距过小会产生过多候选并增加推理开销，过大会漏掉运动或镜头变化； 滞回过小会对 mask 噪声敏感，过大会抹平真实变化； 上限过小可能遗漏关键变化，过大会增加显存和处理时间。 overlap 过小可能使 Anchor 接缝更明显，过大则会增加重复计算； 节点会在必要时自动缩小 overlap。 锚点帧过密仍然可以执行，但可能显著增加耗时和显存使用。

节点按锚点帧切分区间，执行双向传播，并在 overlap 区域使用距离启发式余弦权重融合。反向传播和多锚点拼接是节点层工程扩展，不同方向的结果可能存在差异。

权重与运行

权重目录为 ComfyUI/models/matanyone/matanyone2.pth。首次执行时如果文件不存在，节点会从官方 Release 自动下载并校验 MD5。MatAnyone2 使用 NTU S-Lab License 1.0，商业使用或再分发前请确认上游许可。

输入与输出

• image：标准 ComfyUI IMAGE 帧批次。
• mask：标准 ComfyUI MASK 帧批次，支持单帧 mask 和多帧 mask 输入；单帧 mask 可以是任意一帧的遮罩，多帧 mask 应与image大小和数量完全对应。
• 输出 mask：标准 ComfyUI MASK。
• 输出 info：运行状态字典，包含帧数、源/推理尺寸、Anchor、实际 overlap 等信息。

Matte Preview

点击节点底部的 Matte Preview 打开时间线窗口。预览画面将 IMAGE 与 mask 叠加显示，时间线可以逐帧浏览并添加、删除锚点帧。

首次打开窗口时：

1. 读取节点已经缓存的 IMAGE/MASK。
2. 对 mask 做稀疏/逐帧变化分析，显示候选锚点帧。

点击 Apply to Node 后，Anchor 和预览参数会写回节点并关闭窗口。以后再次打开窗口只读取节点已保存的 Anchor，不会重复自动改写；如需重新分析，可手动点击 Re-analyse。如果手动删除全部锚点帧，Apply 时会自动恢复第 0 帧作为唯一 Anchor。不打开预览时，节点默认使用第 0 帧。

参数说明

• Max inference size (MPixels)：推理像素上限，默认 2.1（即1920 x 1080）。超过上限时缩小推理，完成后恢复到源尺寸。
• Anchor frames：锚点帧列表，支持 JSON（例如 [0,48,96]）或逗号分隔文本。用户可以手动输入任意帧；越界值会自动裁剪到有效范围。
• Anchor minimum spacing：候选锚点帧的最小间距，默认 48。只影响自动候选稀疏分析，不限制手动设置锚定帧。
• Anchor hysteresis：候选分数平滑滞回，默认 3。只影响自动候选分析，运行时会自动限制到安全范围。
• Anchor limit：自动候选锚点帧数量上限，默认 12。只影响自动候选分析，不限制手动设置锚定帧数量。
• overlap：相邻锚点帧区间的重叠帧数，默认 12。如果大于最小锚定帧间隔允许的安全范围，会自动缩小。
• Analysis stride：自动分析采样步长，默认 1；数值越大分析越快，但可能漏掉短暂变化。
• Anchor sensitivity：自动候选阈值，默认 0.35。
• Mask threshold：粗 mask 二值化阈值，默认 0.5。
• Seed morphology：锚点帧种子形态学调整；正值膨胀，负值腐蚀，默认 0。
• Warmup iterations：锚点帧初始化 warm-up 次数，默认 10。
• Memory interval / Memory frames：MatAnyone2 工作记忆参数，默认分别为 5 和 5。
• Use long-term memory：启用长时记忆，适合较长或变化较大的片段，但会增加显存和推理时间。
• Device：auto、cpu 或可用 GPU。
• Model file：从 models/matanyone 中选择 checkpoint。
• Auto unload model：执行完成后将模型移出显存，默认开启。
• wait for input cache：先缓存输入并暂停执行，使 Matte Preview 前端可以预览视频。

CS VideoMaMa

将与视频逐帧匹配的二值粗 MASK 精修为 8-bit 时序 alpha matte，补回软边缘与半透明过渡。
本节点逻辑源自 github.com/cvlab-kaist/VideoMaMa 并进行了部分修改。

工作流程与注意事项

1. 将源视频帧批次连接到 image，把与视频逐帧对应的粗 mask 连接到 mask；单帧 mask 会广播到整段。
2. mask 在 0.5 处二值化，接入前不要做羽化或模糊，中间灰度会被丢弃。需要更大的遮罩范围时先用 CS Mask Grow 处理。
3. 节点按当前空闲显存与推理尺寸自动决定单批次帧数；帧数超出预算时分成多批推理，相邻批次的接缝帧由上一批的软 alpha 结果回灌作为条件重预测，再线性交叉淡化以消除接缝。
4. 推理在所有帧 mask 并集包围盒内进行，完成后贴回源分辨率；包围盒已接近整帧时自动改为整帧推理。
5. 输出 MASK 的帧数、帧序和尺寸与输入 image 完全一致，不裁剪、不补帧、不改序。
6. 全空或全满的帧不参与推理，直接输出 0 或 1。
7. 显存估算偏乐观时不会中断执行：节点会清理缓存、把批次减半并从整段开头重跑，最多重试两次。

Max working resolution 是速度与质量的第一杠杆：送入模型的像素数直接决定单批次能装下多少帧，批次越少总耗时越低。Batch overlap 的代价同样直接，以 350 帧、单批次 10 帧为例，overlap 取 0 / 2 / 4 分别需要 35 / 44 / 58 个批次。overlap 超过单批次长度的一半时，一个批次重预测的帧数会多于新推进的帧数，节点会自动收窄。

在 mask 包围盒内推理能显著降低小主体的开销（1920x1080 中一个 200x200 的主体，加缓冲后只占约 3.5% 像素），但会改变模型看到的画面宽高比。竖窄主体如出现边缘质量下降，可提高 Max working resolution 或改用整帧推理。

权重与运行

权重目录 ComfyUI/models/videomama/，需要 4 个文件：unet/config.json、unet/diffusion_pytorch_model.safetensors、vae/config.json、vae/diffusion_pytorch_model.fp16.safetensors，合计约 5.9 GB。
首次执行时如果文件缺失或 MD5 不符，节点会从官方源自动下载：UNet 来自 SammyLim/VideoMaMa，VAE 来自 stabilityai/stable-video-diffusion-img2vid-xt。可用环境变量 VIDEOMAMA_MODEL_DIR 指定其他目录，VIDEOMAMA_HF_ENDPOINT 或 HF_ENDPOINT 设置 Hugging Face 镜像。

VideoMaMa 权重与 SVD 底座各有上游许可，商用或再分发前请自行确认。

输入与输出

• image：标准 ComfyUI IMAGE 帧批次。
• mask：标准 ComfyUI MASK 帧批次，支持单帧 mask 广播到整段；多帧 mask 的数量和尺寸需与 image 一致。
• 输出 mask：标准 ComfyUI MASK 帧批次，帧数、帧序与尺寸与 image 一致，启用包围盒推理时框外区域为 0。

节点选项说明

• Device：auto、cpu 或可用 GPU。
• Seed：随机种子，默认 42。同时驱动 UNet 噪声和 VAE 后验采样，同一 seed 可逐位复现结果；节点会先快照再还原全局随机状态，不影响工作流中的其他节点。
• Batch overlap：相邻批次共享的接缝帧数，默认 2，范围 0-32。接缝帧只作为上下文重预测、不产出新结果，随后与上一批已提交的结果交叉淡化。因为有软 alpha 回灌，2 通常已经足够；设为 0 时各批次完全独立，接缝会可见。实际取值不会超过单批次长度的一半。
• Max working resolution：送入模型区域的长边上限，默认 1280，范围 256-2048。这是主要的速度控制项：像素越多，单批次帧数越少、总批次越多。输出始终恢复到源分辨率，该参数只影响内部推理精度。
• Motion bucket：SVD 的运动条件强度，默认 127，范围 1-255，与素材真实运动量无关。偏低（50-100）更平滑保守，偏高（150-200）允许更大的时序变化，边缘抖动时可尝试调低。
• CPU offload weights：默认关闭。开启后权重常驻内存、按阶段搬运到 GPU，可省约 3 GiB 显存，但每个批次都要搬运一次，批次数多时得不偿失，仅在显存极度紧张时开启。
• Force unload model：默认关闭。开启后本次执行结束（含出错与取消）即释放模型并清理显存，便于后续大模型节点接管；代价是下次执行需重新加载约 6 GB 权重。

CS ProPainterX Inpaint

将 IMAGE 帧批次中被 MASK 标记的区域擦除。
本节点推理逻辑来源自 github.com/Zarxrax/ProPainterX，沿用原始项目 github.com/sczhou/ProPainter 推理代码和权重，用 MemFOF 取代原版的 RAFT 光流，在 24GB 级别显卡上以更高的工作分辨率完成移除。

工作流程与注意事项

1. 将源视频帧批次连接到 image，把与视频逐帧对应的移除区域 mask 连接到 mask；也支持单帧 mask 广播到整段。
2. Mask dilation参数可以扩大mask 标记的移除范围。如需要更大的移除范围，可以先用 CS Mask Grow 放大 mask区域。
3. 节点按当前空闲显存自动决定单批次处理的帧数；帧数超出预算时自动分多批次推理，并在 overlap 区间做线性交叉淡化以消除接缝。
4. 推理在源画面尺寸进行（仅向下对齐到 8 的倍数）。

权重与运行

权重目录 ComfyUI/models/ProPainter/，包含 ProPainter.pth、recurrent_flow_completion.pth 以及 memfof/config.json、memfof/model.safetensors。
首次执行时会从官方源自动下载权重：下载来源分别来自 sczhou/ProPainter v0.1.0 Release 和 egorchistov/optical-flow-MEMFOF-Tartan-T-TSKH。

ProPainter 许可证为 Apache-2.0，MemFOF 为 BSD-3-Clause，商用或再分发前请确认上游许可。

输入与输出

• image：标准 ComfyUI IMAGE 帧批次。
• mask：标准 ComfyUI MASK 帧批次。
• 输出 image：标准 ComfyUI IMAGE帧批次，与输入帧数和尺寸一致。

节点选项说明

• Device：auto、cpu 或可用 GPU。
• Sub-video length：一次推理处理的帧数，默认 80。峰值显存主要由它决定（约 neighbor_length + subvideo / ref_stride 帧），与总帧数无关；显存不足时节点会自动下调，遇到 OOM 优先降低它。
• Neighbor length / Reference stride：推理参考的邻帧数量与参考帧采样间隔，默认 10 / 10。
• Mask dilation：ProPainterX 内部对移除区域的膨胀，默认 4。
• Batch overlap：相邻批次交叉淡化的帧数，默认 4。只有帧数超过单批次数量分成多批推理时才起作用。
• Force unload model：默认关闭；开启后本次执行结束即释放显存，便于与其他大模型节点交替使用。

CS MOSS Audio Transcribe

使用 MOSS-Transcribe-Diarize 模型，将 AUDIO 转写为带时间戳的 SRT 文本。 首次运行会自动下载模型。或者从OpenMOSS-Team/MOSS-Transcribe-Diarize/ 手动下载模型，然后放到ComfyUI/models/moss目录。

使用流程

1. 将标准 ComfyUI AUDIO 输出连接到 audio。
2. 选择语言模式和字幕分行长度。
3. 执行节点，获得 SRT 文本，可直接连接到 CS Video Subtitle 的 srt 输入。

节点选项说明

• audio：标准 ComfyUI AUDIO 输入，支持单声道或多声道音频。
• language：语言模式，可选 auto、中文 或 English。
• max_chars_per_line：每行最大字符数，0 表示不主动分行。
• auto_unload_model：默认开启。执行完成后释放 MOSS 推理运行时和 CUDA 显存。

输出说明

• srt：标准 SRT 格式的 STRING 文本，包含序号、起止时间和字幕正文。

CS Video Subtitle

将 SRT 字幕渲染到标准 ComfyUI VIDEO，并提供可交互的 Subtitle Timeline。字幕样式包括字体、字号、颜色、渐变、对齐、斜体、字距、位置、描边和阴影。 节点从ComfyUI/models/fonts 目录扫描并加载字体。请提前将字体放置到此目录。

使用流程

1. 将 CS Load Video 或其他兼容节点的 VIDEO 输出连接到 video。直连 CS Load Video 时可直接使用其预览缓存；其他上游输入可通过 wait_for_input_cache 建立共享预览缓存。
2. 将 SRT 文本连接到 srt；如果不连接 srt，节点会自动使用 edited_srt 中保存的字幕。
3. 点击 Edit Timeline 编辑字幕时间、样式和位置。
4. 点击 Apply 保存字幕设置，再执行节点得到最终视频。
5. 如果输入来自上游运行后才生成的图像或视频，首次打开 Edit Timeline 前先设置wait_for_input_cache 为 ture 并运行一次工作流，建立 Preview cache。

节点选项说明

• video：兼容 ComfyUI VIDEO 类型的输入。直连 CS Load Video 时可直接回溯来源；其他上游输入可通过 wait_for_input_cache 建立共享预览缓存后使用。
• srt：可选 STRING。只要该输入已连接，节点始终以 srt 为准。如果无法从上游节点回溯srt，则时间线为空。
• edited_srt：经Timeline 编辑保存的 SRT 文本；可在 Timeline 中通过Load Edited SRT按钮加载到时间线，或在 srt 输入未连接时自动使用。
• preview_in / preview_out：字幕 Timeline 的预览范围，分别表示起始帧和结束帧。
• font：字幕字体。
• font_size：字体大小，范围 8–200。
• primary_color：字幕主色。
• secondary_color：字幕渐变辅助色。
• gradient：是否启用垂直渐变填充。
• text_align：文本对齐方式，可选 left、center、right。
• italic：是否使用斜体。
• letter_spacing：字距，范围 -10–50。
• position_x：字幕位置的X坐标，范围 0–1。
• position_y：字幕位置的Y坐标，范围 0–1。
• outline_size：描边大小。
• outline_color：描边颜色。
• shadow_size：阴影大小。
• shadow_color：阴影颜色。
• wait_for_input_cache`：布尔开关，默认关闭。开启后执行节点时，将当前输入节点及其全部上游节点的链路指纹写入公共 Preview cache，然后中断本次 ComfyUI 执行。

输出说明

• video：渲染字幕后的标准 ComfyUI VIDEO，保留输入视频帧率、音频和时间范围。
• srt：当前节点最终采用的 SRT 文本，可连接到其他字幕或文本节点。

Edit Timeline 界面

Subtitle Timeline 前端界面由视频预览、时间线、字幕样式编辑和位置调整区域组成。

• 预览区域显示当前视频帧和字幕效果。可播放、暂停和拖动查看画面，预览中的字幕会随当前帧更新。
• 时间线包含 Subtitles 和 Audio 两条轨道。字幕轨道显示每条字幕的时间范围，音频轨道显示声音波形；拖动当前帧指针或使用播放、前进、后退按钮可以定位画面。
• Load Edited SRT：手动加载节点中保存的 edited_srt，用于在获得新的上游 SRT 后恢复之前的编辑结果；不会改变节点的 srt 输入优先级。
• 使用 Set In 和 Set Out 设置字幕 Timeline 的预览起止帧。
• 在字幕轨道中双击字幕片段，或使用右键菜单，可以编辑、复制、粘贴或删除字幕内容；字幕片段可在时间线上拖动调整时间范围。
• Text Style 区域用于设置字体、字号、斜体、字距、主色、渐变色、描边和阴影。
• Position 区域用于设置文字对齐方式以及规范化的 X/Y 位置。也可以直接在预览画面中拖动字幕，使用边角控制点调整文字区域大小。
• 点击 Apply 将当前时间范围、字幕文本、样式和位置写回节点；点击 Cancel 放弃本次编辑。

注意：如果想强制使用节点内已编辑的字幕时间线edited_srt，请断开str的输入，否则渲染时edited_srt不会生效，仍然使用srt输入的内容。

CS Compare Any

对 source_a 和 source_b 两个输入进行比较。支持 Image、Mask、Video、文本、浮点、整数、布尔值、List、Dict 等类型的比较。 IMAGE（包括 RGB、RGBA 等不同通道数图像）与 MASK 可以混合对比，其他数据类型需要保持类型一致。 view_port_layout 用于选择 single、horizontal 或 vertical 布局。执行后在节点界面中显示比较结果。

使用流程

1. 将两个需要比较的节点输出分别连接到 source_a 和 source_b；RGB/RGBA 图像与 MASK 可以混合连接，其他类型比较则需要两个输入的类型保持一致。
2. 选择 view_port_layout：single 只显示 A/B 对比视口，horizontal 显示横向排列的source_a和source_a/b对比双视口，vertical 显示纵向排列双视口。
3. 执行工作流，节点会根据输入类型自动选择 media 或 text 模式。

节点输入

• source_a：任意类型输入。
• source_b：第二个任意类型输入。普通数据类型必须与 source_a 类型相同；RGB、RGBA 等 IMAGE 与 MASK 允许互相对比。
• view_port_layout：视口布局，可选 single、horizontal 或 vertical，默认 single。

Media 模式

适用于 VIDEO、IMAGE 和 MASK。其中 RGB、RGBA 等不同通道数的 IMAGE 与 MASK 可以互相对比。节点会根据两个输入的画幅比例设置视口；比例不一致时使用较宽的画幅比例，并在视口内部用黑色填充不足区域。

• 对比视口显示 source_b，并叠加 source_a 作为对比层。
• 拖动对比条可以查看 A/B 画面的差异；single 模式默认居中，horizontal 和 vertical 模式默认位于最左侧。视频输入还支持同步播放、逐帧定位、时间线、音频选择、缩放和平移。
• horizontal 时两个视口左右排列，vertical 时上下排列；节点外框调整大小时，视口保持输入画幅比例。

Text 模式

适用于 STRING、BOOL、INT、FLOAT、LIST 和 DICT 等文本/数据类型。节点在 A/B 对比视口中显示逐行和行内差异高亮。

• single 时只显示 A/B 对比视口；horizontal 时 A、B 两个完整文本面板左右排列；vertical 时 A 在上、B 在下。
• 删除内容、插入内容和替换内容分别使用差异颜色标记；两个面板支持同步滚动。

CS Preview Any

自动识别输入数据类型并提供统一的多视口预览节点。节点包含画面视口和文本视口：画面视口用于显示图片、Mask、视频或音频波形，文本视口用于显示类型、尺寸、批次和调试信息。节点同时提供 output 输出，将接入 source 的原始值透传到下游节点。

使用流程

1. 将任意 ComfyUI 节点的输出连接到 source。source 接受任意类型，不需要预先指定输入类型。
2. 执行工作流，节点会根据实际输入自动选择预览方式。
3. 将 output 连接到下游节点时，节点会返回与 source 相同的数据内容，不执行额外转换。

支持的类型

• VIDEO：使用临时 Preview Cache 生成保持宽高比的预览视频，预览像素数上限为 1 Mpixels，预览帧率上限为 25 fps，并保留完整输入时长。注意预览视频的画面大小和质量经过处理，并非原始精度。保存原始精度的视频文件请使用 CS Save Video 节点。
• IMAGE：按 ComfyUI 原生图片预览方式显示图片，可以在列表和单张显示之间切换。文本视口显示 Tensor 形状、图片尺寸、批次和通道模式。
• MASK：按 ComfyUI 原生 mask 预览显示 Mask，并显示对应的形状、尺寸和批次信息。
• AUDIO：画面视口显示音频波形；文本视口显示波形形状、采样率、声道、时长、峰值和 RMS 等信息。
• STRING、BOOL、INT、FLOAT：在文本视口显示类型和值。
• LATENT：在文本视口显示 latent 的形状、dtype、device、批次、通道、维度、统计值、keys、noise mask 和 batch index 等元数据。
• LIST、DICT：在文本视口显示长度以及调试信息。数值 item 显示值，非数值对象只显示类型。

其他无法预览的对象只显示数据类型；无法识别的数据会显示 Unable to parse data type。

输出

• output：通配类型输出，返回接入 source 的原始值。

CS Mask Grow

使用精确离散欧氏圆盘算法， 对MASK 进行精确欧氏距离的膨胀或收缩。较官方Grow Mask节点运算速度大幅提升，并避免了大 grow 值下产生菱形轮廓的曼哈顿距离问题，能更好的保持轮廓特征。

节点输入

• mask：标准 ComfyUI MASK。
• grow：以像素为单位；正值向外膨胀，负值向内收缩，0 不改变尺寸。
• Preserve Soft Edges：默认关闭。关闭时先以灰度值 128 为阈值将输入二值化，输出仅包含 0/1；开启时保留输入 Mask 的灰度 alpha 过渡。

输出

• MASK：与输入帧数和画面尺寸相同的标准 ComfyUI MASK。

CS Spatial Stabilize

根据 MASK 稳定目标区域的位置和面积，并裁切为统一尺寸的 IMAGE 和 MASK 批次。稳定后的局部帧可连接修复或特效节点进行处理，再通过 CS Spatial Restore 恢复到源视频位置。

使用流程

1. 将源视频帧批次连接到 image，将与视频帧对应的 Mask 批次连接到 mask。
2. 节点自动选择 Mask 面积最大的一帧作为锚点；其他帧与其对齐，并缩放稳定目标大小。
3. 将输出的 IMAGE 送入局部处理流程，同时将 STABLE_DATA 连接到 CS Spatial Restore；需要按目标 Mask 回贴时，再将输出的 MASK 连接到恢复节点。

节点选项说明

• image：标准 ComfyUI IMAGE，通常为按时间顺序排列的视频帧批次。
• mask：与 image 空间尺寸一致的标准 ComfyUI MASK 批次。
• multiple：整数，默认 32。输出裁切画面的宽度和高度向上取整为该数值的整数倍。
• Crop Margin Per Side (%)：浮点数，默认 30.0。在基础扩展之外，按锚点帧遮罩区域最大宽度和高度分别为每一侧增加百分比边距。
• Average Frames：整数，默认 8。对补全后的 X、Y 和 Scale 做连续端点约束的滑动平均，以减少逐帧抖动；首尾帧保持原始值。1 表示关闭平均。
• Mask Blur Sigma：浮点数，默认 6.0。预模糊高斯模糊 Sigma，可过滤远离主体的少量 Mask 漏点；0 表示关闭预模糊。

输出说明

• IMAGE：位置和大小稳定后、统一裁切尺寸的视频帧批次。
• STABLE_DATA：用于 CS Spatial Restore 节点恢复裁切画面的数据。
• MASK：与输出 IMAGE 对应的裁切后 Mask 批次。

CS Spatial Restore

使用 CS Spatial Stabilize 输出的 STABLE_DATA，把处理后的局部视频帧逆变换并合成回源视频。恢复结果保持源视频的批次数和画面尺寸。

使用流程

1. 将与 CS Spatial Stabilize 输入相同的源视频帧连接到 source_image。
2. 将经过局部处理的稳定帧连接到 stabilized_image。处理过程必须保持帧数、宽度和高度不变。
3. 将对应的 STABLE_DATA 连接到 stable_data。
4. 需要只恢复 Mask 区域时，将与 stabilized_image 对应的 Mask 连接到可选的 mask；不连接 Mask 时，节点恢复整个 crop，并使用 Soft Border 在 crop 四边创建羽化过渡。

节点选项说明

• source_image：原始标准 ComfyUI IMAGE 批次，必须与 CS Spatial Stabilize 使用的源视频帧尺寸和批次数一致。
• stabilized_image：经过局部处理的稳定帧，尺寸和批次数必须与 CS Spatial Stabilize 的 IMAGE 输出一致。
• stable_data：匹配的 CS Spatial Stabilize 输出数据。
• mask：可选标准 ComfyUI MASK。连接后按 Mask 合成局部结果，并忽略 Soft Border；Mask 的尺寸和批次数必须与 stabilized_image 一致。
• Soft Border (crop px)：整数，默认 32。未连接 Mask 时，在稳定 crop 四边使用的羽化宽度，单位为 crop 空间像素；0 表示不羽化。

CS Load Video

把视频文件加载到 ComfyUI，并提供一个可交互的时间线编辑窗口。节点执行时会读取视频帧、音频和帧率，根据工作流中保存的设置截取和调整内容，然后输出给下游节点。

1. 从节点直接选择和上传视频。
2. 加载视频后，width 和 height 会自动初始化为源视频宽高，并分别按 multiple 四舍五入。
3. 直接修改 width 或 height 时，另一项会根据源视频宽高比自动联动回填；修改 multiple 时两项会重新取整。
4. 视频预览上方的蓝色指示条标记视频输出的出入点范围。
5. 点击节点上的Edit Timeline按钮进入时间线界面： 通过时间线拖动入点和出点，支持逐帧定位。 通过 Set In 和 Set Out 按钮，把视频预览窗口的当前帧快速设为入点或出点。 使用蓝色当前帧指针，在时间线上拖动即可同步预览对应视频帧。 出入点设置按钮组的 Play 只播放已设置的入点到出点范围。 视频预览窗口的白色播放键仍然播放完整视频，不受入出点限制。

预览 Cache

每个 CS Load Video 节点都自动为下游预览提供 Preview Cache 并缓存在 ComfyUI 临时目录中，随ComfyUI启动自动清除上次残余缓存。 Preview Cache 只用于前端窗口播放、预览和波形显示。

节点选项说明：

• video： 选择choose file to upload 按钮手动加载视频，或拖动视频文件放到节点以加载视频。
• multiple：整数，默认 32。 输出尺寸的取整倍数。宽度和高度会按最近的倍数四舍五入。
• start_frame： 整数，默认 0。 起始帧，使用从 0 开始的帧编号。
• end_frame：整数，默认-1 |。 结束帧，-1 表示使用视频最后一帧。
• width： 整数，输出宽度。加载视频后会按源视频宽度和 multiple 自动初始化；手动修改时高度会按源视频宽高比联动计算，并始终按 multiple 取整。
• height： 整数，输出高度。加载视频后会按源视频高度和 multiple 自动初始化；手动修改时宽度会按源视频宽高比联动计算，并始终按 multiple 取整。
• fps： 浮点数，默认 0。 输出帧率。0 表示保留源视频帧率；输入其他数值时会按目标帧率重新采样帧。
• choose file to upload：点击按钮从本地加载视频。
• Edit Timeline：进入时间线界面。 其中 start_frame、end_frame、width、height 和 fps 可通过 Edit Timeline 窗口设置或在节点控件中直接编辑。

Edit Timeline 时间线界面

时间线界面从上到下依次包含视频预览、原视频信息、时间读数、当前帧指针、入出点标记栏、时间线操作按钮和输出参数。视频预览上方有一条 4 像素高的 In/Out 区间指示条：灰色表示完整视频范围，蓝色表示当前入点到出点范围。

入点和出点标记

标记栏中的两个白色手柄分别表示入点和出点：

• 左侧手柄是入点。
• 右侧手柄是出点。
• 可以直接拖动手柄调整范围。

时间线按钮

• Set In：将视频预览当前帧设为入点。如果当前帧晚于出点，会自动修正出点。
• 入点指示：显示当前入点帧号，点击可跳转到入点。
• |<： 跳转到上一帧。只受视频首帧限制，不受入点限制。
• Play: 只播放从入点到出点的内容，播放到出点后自动暂停。再次播放时，如果当前帧不在范围内，会从入点重新开始。
• >|: 跳转到下一帧。只受视频尾帧限制，不受出点限制。
• 出点指示：显示当前出点帧号，点击可跳转到出点。
• Set Out： 将视频预览当前帧设为出点。如果当前帧早于入点，会自动修正入点。

时间线参数

• multiple：整数，默认 32。 输出尺寸的取整倍数。宽度和高度会按最近的倍数四舍五入。
• width： 整数，输出宽度。修改时高度会按源视频宽高比联动计算，并始终按 multiple 取整。
• height： 整数，输出高度。修改时宽度会按源视频宽高比联动计算，并始终按 multiple 取整。
• fps： 浮点数，默认是源视频编码的帧率。手动改变将保持至节点作为输出帧率；保持不变则返回节点时仍为0，表示原始帧率。

输出说明

• video：标准 ComfyUI VIDEO 类型，包含时间线选段、尺寸、帧率和音频，可直接连接官方视频节点。
• IMAGE: 输出的video图像帧批次。
• frame_count: 实际输出帧数。修改 FPS 后，该数值可能与源视频选段帧数不同。
• audio: 选定时间范围内的音频。没有音频轨道时输出为空。
• video_info: 包含源视频和输出视频的 FPS、帧数、时长、宽高、入点和出点等信息，以及 loader 标识。
• fps：浮点数，实际输出视频的帧率。未设置目标 FPS 时为源视频帧率，设置目标 FPS 后为重新采样后的输出帧率。

CS Save Video

基于 ComfyUI 官方 Save Video 节点，增加 save metadata 和符合行业惯例的 H.264 目标码率控制选项。video 为可选输入，也可以只连接 image 或 mask 生成视频。
画面输入优先级：video > image > mask。至少需要连接一个画面输入。

• video：可选的标准 ComfyUI VIDEO 输入。如果存在其他输入时，优先使用 video，并保留视频自身的内置帧率。
• image：可选的标准 ComfyUI IMAGE 批次输入。没有连接 video 时可单独使用。
• mask：可选的标准 ComfyUI MASK 批次输入。仅在没有连接 video 和 image 时使用。
• audio：可选的标准 ComfyUI AUDIO 输入。使用 image 或 mask 生成视频时写入音频；使用 video 时忽略此输入。
• FPS：使用 image 或 mask 生成视频时的帧率，默认 30.0。使用 video 时忽略此参数并使用视频内置帧率。
• filename_prefix：输出文件名前缀，支持官方的日期和节点控件格式化语法。
• format：输出容器格式，默认 auto。
• codec：视频编码方式，默认 h264。选择 H.264 时显示码率控件。
• H.264 bitrate (Mbps)：H.264 目标码率，浮点数保留 1 位小数，范围 1.0–160.0 Mbps，默认 8.0 Mbps。范围覆盖官方建议的低分辨率到 8K 高帧率视频；常见 1080p 视频可从 8.0 Mbps 开始，高帧率 1080p 可提高到约 12.0 Mbps。
• save_metadata：默认关闭。开启后保存的文件将写入工作流和源视频 metadata。

声明

ComfyUI_CineStyle节点遵照MIT开源协议，有部分功能代码和模型来自其他开源项目。如果作为商业用途，请查阅原项目授权协议使用。