在 ComfyUI 中通过 JSON 配置 ffmpeg 输出自定义编码格式视频

方案简介

ComfyUI-VideoHelperSuite（VHS）是一个面向 ComfyUI 的视频工作流节点套件，专注于在 ComfyUI 节点图中完成视频与图像序列的相互转换、批处理以及带音频的视频合成。其中一项核心能力是允许用户通过往 video_formats 文件夹中添加 JSON 配置文件，为 Video Combine 节点扩展任意自定义的视频输出格式（如 av1-webm）。这套配置方案把 ffmpeg 命令行参数化、模块化，使得熟悉 ffmpeg 的用户无需修改插件源码即可自定义视频编码器、像素格式、音频编码等参数。适合在 ComfyUI 中处理 AI 生成视频（如 AnimateDiff 输出）、需要特定编码格式（av1、hevc、nvenc 硬件编码）或对输出质量与体积有精细控制需求的用户。

亮点与能力

• 通过在 video_formats 目录放置 JSON 文件即可为 Video Combine 节点新增自定义输出格式
• main_pass 配置项作为参数列表原样透传给 ffmpeg，可指定视频编码器（如 libsvtav1、av1_nvenc）
• audio_pass 配置项在传入音频时作为额外参数传递给 ffmpeg，可指定音频编码器（如 libopus）
• 通过 extension 字段指定输出文件扩展名
• 通过 environment 字段向编码器注入环境变量（如 SVT_LOG: "1"）
• 在 Video Combine 节点 UI 上会基于 JSON 中声明的参数（如 crf）动态暴露可调节控件（含默认值与最小/最大值/步长）

组成与分工

• ComfyUI VideoHelperSuite (Video Combine 节点)：节点图中执行视频合成的入口，读取 video_formats 下的 JSON 配置文件生成 UI 选项，并负责调度 ffmpeg 子进程
• ffmpeg：实际执行音视频编码的命令行工具，所有 main_pass 与 audio_pass 参数最终由其消费
• JSON 配置文件：用户放入 video_formats/ 的描述文件，作为 ffmpeg 参数与节点 UI 控件的声明式载体
• SVT-AV1 (libsvtav1)：示例中选用的 AV1 编码器，相对 libaom-av1 编码速度更快
• libopus：示例 audio_pass 中指定的音频编码器
• 外部环境对象 environment：在编码器启动前注入的环境变量集合（如 SVT_LOG）

前置要求

• 已安装 ComfyUI 及 ComfyUI-VideoHelperSuite 插件
• 系统已安装 ffmpeg，且版本需要支持所选编码器（README 提示 SVT-AV1 在较旧版本的 ffmpeg 中可能不存在）
• 若选用 NVIDIA 硬件编码（av1_nvenc），需较新的 NVIDIA 显卡与对应驱动
• 在 ComfyUI/custom_nodes/ComfyUI-VideoHelperSuite/video_formats/ 目录下拥有写权限以新增 JSON 配置

实施步骤

1. 定位 video_formats 目录

进入 ComfyUI-VideoHelperSuite 插件目录下的 video_formats 子目录，准备新增 JSON 配置。

2. 创建 JSON 配置文件

为新格式创建 JSON 文件，示例文件名 av1-webm.json。文件内容（逐字复制材料原文）：

{
    "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"}
}

3. 在 ComfyUI 中使用新格式

重启 ComfyUI（或刷新节点），在 Video Combine 节点的 format 下拉中即可看到新加入的 av1-webm 选项；UI 上会自动出现 crf 等可调控件（默认 23，范围 0–100，步长 1）。

使用与配置要点

• 选择新格式后，按需调节 Video Combine 节点上动态出现的参数（如 crf），数值越低画质越高、文件越大（README 提示视觉无损通常在 20 附近）
• 如需将工作流嵌入输出视频以便日后通过拖拽还原，可在节点上启用 save_metadata
• 通过 pix_fmt 选择像素格式，yuv420p10le 提供更高色彩质量但并非所有设备都支持
• 输出文件名可通过 filename_prefix 与 %date:yyyy-MM-ddThh:mm:ss% 占位符控制，并支持 subfolder/video 子目录语法
• 想用 GPU 编码可将 -c:v 改为 av1_nvenc（README 明确提及该替代项）

注意事项与常见问题

• 编码器可用性：libsvtav1 在较旧版本 ffmpeg 中可能不存在；可改用 av1_nvenc（NVIDIA 较新显卡）做 GPU 编码
• 像素格式：必须显式指定 -pix_fmt，否则可能使用不可配置的输入像素格式
• 覆写保护：参数中保留 -n 可保证同名文件已存在时命令失败，避免意外覆盖其他文件
• AV1 编码速度权衡：SVT-AV1 比 libaom-av1 更快，但兼容性/质量取舍需自行评估

优缺点

• ✓ 可灵活扩展任意编码格式
• ✓ 音视频 pass 分开配置
• ✕ 需熟悉 ffmpeg 命令行
• ✕ SVT-AV1 在旧版 ffmpeg 中

出处

本方案挖掘自开源项目 Kosinkadink/ComfyUI-VideoHelperSuite，方案内容与实施命令均来自其 README 原文。