ComfyUI-VideoHelperSuite

与视频工作流相关的节点

I/O 节点

加载视频

将视频文件转换为一系列图像

• video: 要加载的视频文件
• force_rate: 根据需要丢弃或重复帧以达到目标帧率。设置为 0 时禁用此功能。这可用于快速匹配建议的帧率，例如 AnimateDiff 的 8 fps。
• force_size: 允许快速调整到若干建议尺寸。多个选项允许仅设置宽度或高度，并根据宽高比自动确定另一维度。
• frame_load_cap: 将返回的最大帧数。这也可视为最大批处理大小。
• skip_first_frames: 在应用强制帧率后，从视频开头跳过多少帧。通过将此值增加 frame_load_cap 的数量，可以轻松地分段处理较长的输入视频。
• select_every_nth: 允许跳过指定数量的帧，而不考虑基础帧率或导致帧重复。在处理动画 GIF 时通常很有用。 还存在一个路径版本的“加载视频”节点，可以从外部路径加载视频。 如果在 Web UI 的选项菜单中启用了高级预览，预览将反映节点上的当前设置。

加载图像序列

从子文件夹中加载所有图像文件。选项与“加载视频”类似。

• image_load_cap: 将返回的最大图像数。这也可视为最大批处理大小。
• skip_first_images: 跳过多少张图像。通过将此值增加 image_load_cap 的数量，可以轻松地将长序列的图像分成多个批次。
• select_every_nth: 允许在每两张返回的图像之间跳过指定数量的图像。 同样存在“加载图像序列”的路径版本。

视频合并

将一系列图像合并为输出视频
如果提供了可选的音频输入，它也会被合并到输出视频中

• frame_rate: 每秒显示的输入帧数。较高的帧率意味着输出视频播放得更快，持续时间更短。对于 AnimateDiff，通常应保持为 8，或与“加载视频”节点的 force_rate 匹配。
• loop_count: 视频应重复播放的次数。
• filename_prefix: 用于输出的基本文件名。
  • 可以将输出保存到子文件夹：subfolder/video
  • 类似于内置的“保存图像”节点，可以添加时间戳。%date:yyyy-MM-ddThh:mm:ss% 可能会变为 2023-10-31T6:45:25
• format: 使用的文件格式。有关配置或添加其他视频格式的高级信息，请参阅视频格式部分。
• pingpong: 使输入反向播放，以创建干净的循环。
• save_output: 是否应将图像保存到输出目录或临时目录。 返回值：一个 VHS_FILENAMES，包含一个布尔值，指示是否启用 save_output，以及按创建顺序排列的所有生成输出的完整文件路径列表。因此，output[1][-1] 将是最完整的输出。 根据所选格式，可能会出现其他选项，包括：
• crf: 描述输出视频的质量。数字越低，视频质量越高，文件越大；数字越高，视频质量越低，文件越小。具体比例因编解码器而异，但视觉上无损的输出通常在 20 左右。
• save_metadata: 在输出视频中包含工作流副本，可通过拖放视频加载，就像处理图像一样。
• pix_fmt: 改变像素数据的存储方式。yuv420p10le 具有更高的色彩质量，但并非所有设备都支持。

加载音频

提供一种加载独立音频文件的方式。

• seek_seconds: 音频文件的可选起始时间（以秒为单位）。

隐变量/图像节点

存在一些用于管理隐变量的实用节点。每个节点都有一个等效的图像处理节点。

分割批次

将隐变量分为两组。前 split_index 个隐变量进入输出 A，其余进入输出 B。如果输入的隐变量少于 split_index，则全部传递到输出 A，输出 B 为空。

合并批次

将两组隐变量合并为一个输出。输出顺序是先 A 组的隐变量，再 B 组的隐变量。
如果输入组的大小不同，该节点提供在合并前缩放隐变量的选项。

每隔 N 个选择

每 select_every_nth 个输入中，只传递第一个，其余丢弃。

获取数量

复制批次

视频预览

“加载视频（上传）”、“加载视频（路径）”、“加载图像（上传）”、“加载图像（路径）”和“视频合并”均提供动画预览。
带有预览的节点在右键单击时提供更多功能：

• 打开预览
• 保存预览
• 暂停预览：对于非常大的视频，可以提高性能
• 隐藏预览：可以提高性能、节省空间
• 同步预览：重新启动所有预览，以便进行并排比较

高级预览

高级预览必须手动启用，方法是点击队列提示旁边的设置齿轮，并勾选 VHS 高级预览复选框。
如果启用，UI 中显示的视频将按需使用 ffmpeg 进行转换。这具有多项优势：

• “加载视频”节点的预览将反映节点上的设置，如 skip_first_frames 和 frame_load_cap。
  • 这使得选择输入视频的确切部分并与输出同步变得容易。
• 如果远程运行服务器，可以显著减少带宽消耗。
• 通过将视频缩小到 UI 分辨率，可以大大提升浏览器性能，尤其适用于动画 GIF。
• 允许预览通常无法在浏览器中播放的视频。
• 如果设置了环境变量 VHS_STRICT_PATHS，则可限制为 ComfyUI 的子目录。

不过，由于存在一些缺点，此功能默认处于禁用状态：

• 视频在浏览器中显示会有延迟。如果输入视频较长，延迟可能会相当大。
• 预览视频的质量较低（原始视频始终可以通过右键单击 -> 打开预览来查看）。

视频格式

熟悉 FFmpeg 的用户可以将 JSON 文件添加到 video_formats 文件夹中，从而为 Video Combine 添加新的输出类型。 以下以 AV1-WebM 格式为例：

{
    "main_pass":
    [
        "-n", "-c:v", "libsvtav1",
        "-pix_fmt", "yuv420p10le",
        "-crf", ["crf","INT", {"default": 23, "min": 0, "max": 100, "step": 1}]
    ],
    "audio_pass": ["-c:a", "libopus"],
     "extension": "webm",
     "environment": {"SVT_LOG": "1"}
}

大部分配置都在 main_pass 中进行，它是一个传递给 FFmpeg 的参数列表。

• "-n" 表示如果目标文件已存在，则命令应失败。理论上这种情况不应发生，但若出现某种错误，此选项可确保不会覆盖其他文件。
• "-c:v", "libsvtav1" 指定使用新的 SVT-AV1 编码器对视频进行 AV1 编码。SVT-AV1 的编码速度远快于 libaom-av1，但可能在较旧版本的 FFmpeg 中不存在。此外，对于配备较新 NVIDIA 显卡的设备，也可以使用 av1_nvenc 进行 GPU 编码。
• "-pix_fmt", "yuv420p10le" 指定采用 10 位色深的标准像素格式。必须明确指定像素格式，以避免使用不可配置的输入像素格式。

audio_pass 包含一组参数，这些参数会在音频被传入 Video Combine 时传递给 FFmpeg。

extension 既指文件扩展名，也指所使用的容器格式。如果 main_pass 中省略了某些选项，可能会影响默认选项的选择。

environment 是可选字段，用于在执行过程中设置环境变量。对于 AV1 编码，此字段通常用于降低日志输出的详细程度，仅显示严重错误信息。

input_color_depth 决定像素以何种格式传递给 FFmpeg 子进程。当前有效的选项是 8bit 和 16bit。后者虽然能生成更高品质的输出，但目前仍处于实验阶段。

字段可以通过类似于创建自定义节点的格式，在 Web UI 中以小部件的形式暴露出来。在上述示例中，-crf 参数将在 Web UI 中以格式小部件的形式呈现。格式小部件由最多三个部分组成：

• 在 Web UI 中显示的小部件名称
• 原始数据类型，如 “INT” 或 “BOOLEAN”，或字符串选项列表
• 一个包含选项的字典

ComfyUI-VideoHelperSuite 快速上手指南

ComfyUI-VideoHelperSuite (VHS) 是 ComfyUI 中处理视频工作流的核心插件，提供视频加载、帧处理、音频合并及视频导出等功能。

环境准备

系统要求

• 操作系统: Windows, Linux, macOS
• 核心依赖: 已安装并配置好的 ComfyUI
• 外部依赖:
  • FFmpeg: 必须安装并添加到系统环境变量 PATH 中，用于视频编码、解码及预览生成。
    • Windows 用户: 推荐下载静态编译包，将 bin 目录路径加入环境变量。
    • Linux 用户: sudo apt install ffmpeg 或 sudo yum install ffmpeg
    • macOS 用户: brew install ffmpeg
  • Python: 与 ComfyUI 运行环境一致（通常建议 Python 3.10+）

前置检查

确保在终端输入 ffmpeg -version 能正常输出版本信息，否则插件的视频合成与高级预览功能将无法使用。

安装步骤

方法一：通过 ComfyUI Manager 安装（推荐）

如果你已安装 ComfyUI Manager：

1. 启动 ComfyUI，点击右侧菜单的 Manager 按钮。
2. 选择 Install Custom Nodes。
3. 搜索 VideoHelperSuite。
4. 点击 Install，安装完成后重启 ComfyUI。

方法二：手动源码安装

1. 进入 ComfyUI 的自定义节点目录：

   cd ComfyUI/custom_nodes
   

2. 克隆仓库（国内用户如遇连接问题，可使用镜像源或代理）：

   git clone https://github.com/Kosinkadink/ComfyUI-VideoHelperSuite.git
   

   备选镜像（若主库访问慢）:

   git clone https://ghproxy.com/https://github.com/Kosinkadink/ComfyUI-VideoHelperSuite.git
   

3. 安装 Python 依赖：

   cd ComfyUI-VideoHelperSuite
   pip install -r requirements.txt
   

4. 重启 ComfyUI。

基本使用

以下是一个最简单的“视频转图片处理再合成视频”的工作流示例：

1. 加载视频

添加节点 Load Video (Upload) 或 Load Video (Path)。

• video: 上传或填入本地视频路径。
• force_rate: 设置目标帧率（例如 AnimateDiff 常用 8），设为 0 则保持原帧率。
• frame_load_cap: 限制加载的最大帧数（即批次大小），防止显存溢出。
• 输出: 该节点会输出 IMAGE（图像帧）和 FRAME_RATE（帧率数据）。

2. 处理图像（可选）

将 Load Video 输出的 IMAGE 连接到你的生成模型（如 KSampler）或图像处理节点。

• 若需调整批次，可使用 Split Batch 分割潜空间/图像，或使用 Merge Batch 合并。

3. 合成视频

添加节点 Video Combine。

• images: 连接处理后的图像序列。
• frame_rate: 连接 Load Video 输出的 FRAME_RATE，或手动输入（需与加载时一致以保证速度正常）。
• audio: （可选）连接 Load Audio 节点的输出以保留原声或添加新音效。
• format: 选择输出格式（默认通常为 h264-mp4）。
• filename_prefix: 设置输出文件名，支持子文件夹（如 output/my_video）。
• save_output: 勾选后将视频保存至 output 目录，否则仅保存在临时目录。

4. 高级预览技巧

• 实时预览: 连接后节点窗口会自动播放视频预览。
• 开启高级预览: 点击界面右上角齿轮图标 (Settings)，勾选 VHS Advanced Previews。
  • 作用: 预览将根据节点的 skip_first_frames 或 frame_load_cap 设置实时裁剪显示，便于精确对齐片段，且能降低远程访问带宽消耗。
• 右键菜单: 右键点击视频预览窗口可选择 Pause preview（暂停以提升性能）或 Save preview（保存当前预览）。

5. 执行

点击 Queue Prompt，生成的视频将出现在 ComfyUI/output 目录下。