AIBit-探索开源项目 AIBit-探索开源项目

用于长视频的 ComfyUI MiniMax H3 时间线导演

构建可编辑的参考媒体时间线，并通过直接潜变量延续、音频锁定和自适应接缝控制，生成长篇 MiniMax H3 视频。

用于长视频的 ComfyUI MiniMax H3 时间线导演

从参考图像生成短片相对简单。但要生成时长一分钟甚至更久、连贯且同步的视频，就困难得多：角色身份会漂移，音频接缝会变得明显，而且每次延长通常都需要重新手工搭建一套采样器链。

ComfyUI-MiniMaxH3-TimelineDirector 通过为 ComfyUI 原生 MiniMax H3 Reference to Video 流程提供可编辑的时间线导演，解决了这一工作流问题。它将参考图像、视频、配对音轨、引导素材、提示词和生成窗口整合到一个界面中，然后把时间线展开为分段生成图。

该项目采用 GPL-3.0 发布；在本文所参考的版本中，项目拥有 275 个 stars、31 个 forks，并且只有一位贡献者。0.6.0 版本专注于轻量级无限时长生成，并新增了带锁定源音频的长篇数字人和角色歌唱功能。

为什么时间线很重要

该插件将生成视为一个排列问题，而不是一组互不相连的输入。你可以定位、裁剪、拆分片段，定义数值范围，并建立青色生成窗口。只有与当前生成范围相交的媒体，才会被纳入当前的 H3 Reference 或 Guide 计划。

这使得同一工作流可以处理多种原本不同的任务：

  • 不上传媒体的文生视频。
  • 单片段和多片段的图像参考生成。
  • 音频驱动视频和数字人唇形同步。
  • 角色替换和动作迁移。
  • 可编辑的视频参考。
  • 手动分段的长视频生成。
  • 使用不变音轨的长篇角色歌唱。

时间线状态会被序列化到 ComfyUI 工作流 JSON 中，因此项目可以保存、重新打开并复现，无需手动重新排列媒体。

核心功能：分段、无限时长生成

该插件将目标时长划分为相互重叠的片段，并在一次 ComfyUI 执行中完成整个流程。它不依赖通用 Loop 节点或重复的采样器链，而是使用有限展开图执行以下步骤：

  1. 使用一个共享种子进行逐片段生成。
  2. 从前一片段采样得到的 AV 潜变量尾部直接延续。
  3. 使用自适应 Drift-Control 视频掩码。
  4. 实现 Soft AV 音频连续性。
  5. 移除重叠部分。
  6. 最终进行同步组装。

实际时长上限由本地显存、内存、磁盘容量和 ComfyUI 执行限制决定，而不是由硬编码的片段数量决定。仓库中包含两个在一次执行中生成的示例，每个示例约 52.625 秒，包含 1,263 帧，帧率为 24 fps。

为什么直接延续潜变量很有用

传统方法可能会先将前一片段解码为 RGB，将结果传入下一阶段，再重新编码。这会引入不必要的解码/重新编码往返，并可能放大视觉不连续。有限片段采样会将前一片段采样得到的 AV 潜变量尾部直接传入下一片段的开头。

请求的重叠长度会向下对齐到 MiniMax H3 合法的时间网格。例如，请求重叠 24 帧可能变为 22 帧，而 48 帧可能变为 39 帧。对齐后的数值会统一用于潜变量传递、解码裁剪和最终组装，避免不同阶段对接缝长度产生不一致。

Drift-Control 会根据对齐后的重叠区域对应的视频 token 数量，以及连接采样器的 sigma 调度，自适应调整掩码。这也包括加速的四步和八步调度。只有可舍弃的视频前缀会被动态重新加噪，而接缝一侧的潜变量保持干净。

对于音频延续，被传递的重叠部分会一直保持精确，直到最后八个音频潜变量 tick。随后，半余弦 Soft AV 掩码会逐渐将重叠区域释放到新生成的音频中。在组装期间，输入的 Soft AV 重叠部分会替换前一段音频的尾部，从而使过渡保留在最终音轨中。

每个片段都会使用采样节点上显示的确切种子。旧版通用循环辅助节点以及对 PR #15923 的依赖已被移除。

用于长篇数字人的锁定音频

最实用的新功能之一，是支持一条必须在多个生成窗口之间保持不变的长音轨。参考图像用于保持角色身份，而锁定音轨只需解码一次，然后按精确的采样位置切片，并注入每个片段的 AV 潜变量中。

锁定源音频的音频去噪掩码被设为零，使原始信号能够直接通过，而不是为每个片段独立重新生成。片段组装完成后，最终输出会恢复连续的音轨。

自动适配消除了常见的失败原因：

  • 如果时间线短于源音频，则截断源音频。
  • 如果时间线长于源音频，则保留所有可用音频，只对超出部分填充静音。
  • 用户无需手动匹配 MP3 元数据、H3 有效时长或编解码器预延迟。

这使长篇唇形同步和角色歌唱工作流更易于控制，相比于为每个片段独立生成音频更加可靠。绑定的源音频可以跟随视频剪辑，也可以单独禁用。

参考模式

每个视频片段都可以被指定为以下三种用途之一：

Fixed Guide

该片段会在其生成帧位置锚定重叠区域。当源运动或构图应被视为强结构引导时，这种模式非常有用。

Editable Reference

该片段会作为编号后的 H3 视频参考传入，但不会硬锁定原始主体。对于角色替换和灵活的参考驱动生成，这通常是首选模式。

Boundary Only

仅使用重叠区域的第一帧和最后一帧作为锚点。当端点需要保持稳定、但希望生成的中间内容可以变化时，这种模式很有用。

视频音轨可以独立启用或禁用。也支持独立的图像和音频文件，并且从 UI 到 H3 输入都会保持稳定的 <Picture N>、<Video N> 和 <Audio N> 顺序。

提示词行为与规划

主要工作流同时提供 Global Prompt 和逐片段提示词。只有当所有片段提示词都为空时，才会复用全局提示词。一旦输入了任意片段提示词，每个片段都必须填写提示词，同时全局提示词会被禁用。

这一规则可以避免一种容易被忽略的歧义：部分片段继承全局指令，而其他片段则悄然覆盖它。对于长篇生成尤其重要，因为每个片段都应将重叠部分描述为开场镜头，然后再引入新内容。

项目还包含一个可选的 Omni 提示词桥接器。MiniMax H3 Omni Media-Bundle Prompt Bridge 会将经过排序的图像、视频和音频媒体包发送到已安装的 Prompt Rewriter Omni 后端，并且只返回 rewritten_prompt。当需要在 H3 提示词扩展前进行多模态素材理解时，这一变体非常有用。它需要 MiniMax-H3-Prompt-Rewriter-ComfyUI 及其对应的模型、量化配置和显存环境。

核心节点

推荐架构使用两个主要节点：

  • MiniMax H3 Material Planner — 编辑媒体，并生成紧凑的 H3 计划以及有序的 Omni 媒体包。
  • MiniMax H3 Finite Segment Sampling — 将计划展开为延续、掩码、采样、去重和组装操作。

可选的 MiniMax H3 Omni Media-Bundle Prompt Bridge 负责提示词重写。MiniMax H3 Timeline Director (Compatibility) 保留原始的一体化工作流，并支持较早保存的工作流。

长视频生成只需要：

Material Planner Segment Plan -> Finite Segment Sampling

Plan Encoder 仍作为隐藏的内部节点注册，用于展开的执行图和向后兼容。这种拆分式架构还可以避免 ComfyUI 依赖循环。

安装

将仓库克隆到 ComfyUI 的自定义节点目录中：

cd ComfyUI/custom_nodes
git clone https://github.com/Songssx/ComfyUI-MiniMaxH3-TimelineDirector.git

重启 ComfyUI，然后搜索 MiniMax H3。

源代码 UI 为英文。简体中文通过 ComfyUI 官方本地化系统提供，并跟随 ComfyUI 设置中选择的语言。更改区域设置后，请重新加载或重启前端。

环境要求

你需要：

  • 支持原生 MiniMax H3 节点的近期 ComfyUI 构建版本。
  • 使用 Guides 时需要 MiniMaxH3AddGuide。
  • MiniMax H3 Ref2VA 模型、CLIP、视频 VAE 和音频 VAE。
  • Python 3.10 或更高版本。
  • ComfyUI 的 imageio-ffmpeg 包，用于生成低分辨率预览代理。

项目没有声明额外的 pip 依赖。插件依赖兼容的 ComfyUI 安装中通常已有的包，包括 PyAV、Pillow、NumPy、PyTorch、torchaudio、aiohttp 和 imageio-ffmpeg。

为了保护显存，预览代理可以静默生成，最高支持 480×270 和 12 fps。解码时的缩放也会将输出调整为节点配置的宽度和高度。

实用工作流

  1. 打开 All-in-One Full Timeline Director 工作流。
  2. 设置宽度、高度和 generation_seconds。
  3. 从工具栏添加图像、视频和音频，或将文件拖入 UI。
  4. 根据需要移动、裁剪或拆分片段。
  5. 将青色范围拖到要生成的时间区间上。
  6. 为每个视频分配模式：Fixed Guide、Editable Reference 或 Boundary Only。
  7. 决定是否包含配对视频音频。
  8. 添加全局提示词，或为每个片段完整填写提示词。
  9. 对于长篇生成，创建相互重叠的 GEN 窗口，并选择所需的接缝重叠长度。
  10. 将 Material Planner 的 Segment Plan 直接连接到 Finite Segment Sampling。

插件会处理合法帧对齐、Drift-Control、Soft AV、重叠移除、尾部裁剪和最终 AV 组装。它不会根据参考时长自动分割媒体，也不会推断角色身份是否应当延续。片段范围、重叠区域和分配方式仍由用户明确决定。

对于长视频参考，可以将前一片段的最终镜头作为下一片段的开场 Guide。先将该重叠部分描述为 Shot 1，再引入新内容，然后在组装过程中从后续片段中移除重复的 Guide 区间。

相关工作与许可

Drift-Control AV 改编自 GPL-3.0 项目 ComfyUI-MiniMaxH3-Contex-Loop，目前仍处于实验阶段，尤其是在同一镜头的长链对比方面。Omni 桥接器和提示词生成工作流参考并改编了 pytraveler/MiniMax-H3-Prompt-Rewriter-ComfyUI。

项目还感谢 ComfyUI 原生 MiniMax H3 和 Guide 节点的维护者，并指向 MiniMax-AI/MiniMax-H3，供用户查看官方模型指南。

对于已经在使用 ComfyUI MiniMax H3 节点的开发者而言，Timeline Director 的价值在于，它将一次性参考图生视频图，转变为可复用的编辑和延续系统。它最重要的理念并不只是增加另一个节点，而是将媒体选择、片段边界、重叠策略、提示词范围、音频连续性和最终组装，明确地设为一个可复现工作流中的组成部分。

来源

Songssx/ComfyUI-MiniMaxH3-TimelineDirector: Editable reference-media timeline director for ComfyUI MiniMax H3 Reference to Video