# ComfyUI-H3-LongVideo

**Repository Path**: chen-leisures/ComfyUI-H3-LongVideo

## Basic Information

- **Project Name**: ComfyUI-H3-LongVideo
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-05
- **Last Updated**: 2026-10-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ComfyUI H3 Long Video

用于 MiniMax H3 的长音频分段生成插件，支持唱歌数字人与口播数字人。导入音频后，插件自动分析分段、安排镜头，提供试听和编辑界面；确认后依次生成各段视频，并配回原音频合成为完整成片。

本次更新重点：**唱歌视频的不同分段可上传不同参考图，每段最多 6 张**；也可共用项目默认图。配套示例已接好逐段素材、多图提示词扩写与 24fps 合成链路。更新内容见 [更新记录](CHANGELOG.md)。

## 主要功能

- **自动分段**：根据音频分析结果和目标时长划分片段，支持试听与调整切点。
- **逐段多图素材**：项目默认图与本段自定义图独立管理，每段最多 6 张，可调整顺序并填写用途。
- **两种表演模式**：唱歌模式安排运镜和景别变化；口播模式以参考构图与固定机位为提示词目标，不保证连续一镜到底。
- **导演简报编辑**：逐段查看、修改画面任务、声音关系、构图、主体动作和镜头运动。
- **双提示词通道**：默认使用多图扩写，也可逐段填写手写提示词并从 `segment_prompt` 原样直连 H3。
- **顺序生成**：自动提交各段任务，支持暂停、继续和失败重试。
- **局部重做与合成**：单独重生成某段、恢复上一版，或使用现有片段重新合成。

## 安装

1. 将本仓库克隆或解压至 `ComfyUI/custom_nodes/ComfyUI-H3-LongVideo`。
2. 在 ComfyUI 使用的 Python 环境中安装本插件的 `requirements.txt` 依赖，并确保 `ffmpeg`、`ffprobe` 可用。
3. 重启 ComfyUI，导入 [一体化示例工作流](examples/04_H3长视频_单节点一体化.json)。
4. 安装示例所需的外部节点：`comfyui-vrgamedevgirl`、`ComfyUI-VideoHelperSuite`、`ComfyUI-KJNodes`。
5. 在工作流中选择已安装的 MiniMax H3 Ref2VA、LoRA、VAE 和 CLIP 权重，并在插件的“API 设置与模型选择”中配置分镜提示词生成器使用的服务。

示例将长视频节点的 `segment_material`、六路图片和 `fps` 分别接到分镜提示词生成器、H3 视频参考和视频合成节点。分镜提示词生成器默认使用 `vision` 模式；先配置可处理多图的模型服务，再开始顺序生成。示例使用 Ref2VA 配合 Turbo LoRA，采样配置为 `euler / beta / 10 步`；实际尺寸由 ResolutionSelector 的 `16:9 / 0.4 MP / 32 倍数` 设置决定，覆盖 H3 节点里保存的宽高值。请按本机权重名称重新选择模型，并根据素材方向和显卡条件调整尺寸。

首次音频分析会按需下载语音识别模型。唱歌模式未连接独立人声时，还会下载约 319 MiB 的人声分离模型。模型下载完成后保存在本地，后续分析优先复用。

### 从旧版升级

更新插件后重启 ComfyUI，并刷新浏览器页面。建议重新导入本仓库的新版示例：旧示例的输出槽位与扩写节点不适用于当前接口，仅替换插件文件不会自动修好旧画布。保留旧工作流副本，不要直接覆盖自己的采样设置。

项目与成片保存在 `ComfyUI/output/H3LongVideo`，API 设置和导演规则保存在 ComfyUI 用户目录下的 `H3LongVideo`，模型在 ComfyUI 模型目录中。重新安装插件时保留这些数据；不要同时在 `custom_nodes` 留下多份本插件副本。

## 快速开始

### 1. 准备素材

加载完整歌曲或口播音频，将其连接到 **H3 长视频 · 音频分析与顺序生成** 节点的 `audio`。已有分离人声时，可连接可选输入 `vocals`。

先设置 `mode`、`target_seconds` 与 `max_seconds`，再点击 ComfyUI 的“运行”，完成音频分析并打开分段审核面板。下文的图片上传和逐段编辑都在这个面板中进行。

在分段审核面板上传参考图，并按图片顺序填写素材说明。示例已把长视频节点的图片输出接到 **MiniMax H3 Reference To Video**；无需另接“加载图像”节点。例如：

| 素材组合 | 素材说明示例 |
| --- | --- |
| 一张带背景的人物图 | 图1是人物和背景的完整参考图。 |
| 人物图＋场景图 | 图1是人物，图2是场景。 |
| 人物三视图＋场景图 | 图1是同一个人物的三视图，图2是场景。 |

每段只提供实际需要的图片即可；顺序生成会移除空图片槽位。需要全身镜头时，建议提供包含完整服装与双脚的人物参考。

### 2. 设置项目默认图与本段自定义图

1. 在审核面板的“项目默认参考图”中上传最多 6 张图片并填写用途说明。默认图只需上传一次；该区域可以收起，收起不影响分段控件。
2. 每段选择“使用项目默认”或“本段自定义”。选择自定义时，为该段单独上传、排序最多 6 张图并填写素材说明，例如“图1是人物，图2是场景。”；图号按该段缩略图顺序排列。
3. 点击“保存并确认”后，顺序生成只向 H3 提交当前段实际存在的图片，并移除未使用的参考图输入。修改默认图只影响继承默认的分段，不会覆盖本段自定义图；修改有效素材会使受影响片段等待重新生成。

### 3. 设置模式与镜头

| 参数 | 作用 |
| --- | --- |
| `mode` | `singing` 为唱歌；`speaking` 为口播。 |
| `target_seconds` | 每段的目标时长，实际切点根据音频调整。 |
| `max_seconds` | 单段允许的最长时长。 |

唱歌模式每段安排一种主要运镜，人物可随表演和镜头移动偏离画面中心。口播模式的提示词要求沿用参考画面的人物位置、尺度和裁切范围；实际是否保持固定构图仍由模型生成结果决定。

“运镜规则：查看与修改”用于调整唱歌模式允许的景别、机位角度和不同音频能量下的运镜候选，以及口播模式的固定构图规则；多图提示词扩写节点负责将导演简报、音频阶段和分段素材转换成视频提示词。

### 4. 分析并确认

首次点击 ComfyUI 的“运行”，插件会分析音频并打开分段审核面板。

1. 顶部“当前试听”可在 **原曲 / 人声** 之间切换，试听当前选中的分段；每段卡片上的播放器播放该段原曲，前奏、间奏和伴奏段也能正常试听。两个播放器都可以拖动进度条，用来检查切点是否落在气口或句尾。
2. 查看“本段画面”类型，以及导演简报中的画面任务、声音关系、开场构图、主体动作、镜头运动和结束构图，按需修改。
3. 点击“保存并确认”。
长音频可先点击波形选中分段，再点“当前段”或“切点附近”放大。拖动彩色切点线调整时间，用下方滑条横向浏览，点“全曲”恢复总览。也支持双击局部放大、Ctrl / ⌘ + 滚轮缩放和 Shift + 滚轮横移。放大至单段时长范围内会加载原曲与人声的精细波形；已有项目无需重新分析。点击波形不会自动滚动到分段卡片。

修改模式、分段时长或运镜规则后，点击节点上的 **“重新分析并分段”**，让新设置生效。

### 5. 生成与导出

确认分段后，点击审核面板的 **“开始顺序生成”**，或运行整张工作流。插件依次生成各段视频，完成后自动合成并配回原音频。

最终成片保存在：

```text
ComfyUI/output/H3LongVideo/final_videos
```

项目音频和分段视频保存在：

```text
ComfyUI/output/H3LongVideo/projects
```

## 暂停与修改

- **暂停／停止后续生成**：当前片段完成后暂停提交新任务。
- **继续生成**：生成设置未变时复用已完成片段；改变生成工作流参数后，顺序生成会将受影响的旧结果标记为待重生成。
- **重新生成本段**：使用当前画布设置重做所选片段；新版本成功前保留旧版本。
- **恢复上一版**：恢复该段上一次成功的视频。
- **仅重新合成**：使用现有片段合成成片，无需重新生成视频。

修改某段导演简报或手写提示词会将该段标记为待重生成；调整切点会影响切点两侧的片段，需要重新确认分段。需要重新划分段数时，调整时长参数后重新分析。

## 提示词扩写

示例工作流的文本连接为：

```text
导演简报与多图素材 → H3LVPromptExpand → PreviewAny → H3 视频提示词
```

唱歌和口播的镜头规划来自本地导演规则；`H3LVPromptExpand` 按当前段素材、导演简报和所选 `vision`／`text`／`manual` 模式生成提示词。模型服务设置保存在本机用户目录，密钥不进入工作流或项目快照。扩写结果可在分段预览中检查，必要时逐段编辑。

自行搭建工作流时，将 `segment_material` 接入插件的“H3 长视频 · 分镜提示词生成器”，再把生成结果接入 H3 提示词输入。若使用外部工具写提示词，可在分段界面填写“手写提示词”，将长视频节点末尾的 `segment_prompt` 直接接入 H3 `prompt`；该接口不会改写、校验或回退。H3 的 `prompt` 同时只能选择一条连线。将节点末尾的 `fps` 接入 VHS Video Combine 的 `frame_rate`，使分段输出始终按 24fps 编码。顺序生成工作流需保留一个 `H3LVUnified` 节点和一个 VHS Video Combine 输出节点。

## 使用建议

- 当前面向单人口播和单人唱歌；建议先生成少量片段，确认素材与模型配置合适。
- 唱歌识别可能出现错字或切点偏差，生成前应试听分段。
- 参考图尽量提供清晰、完整的人物与场景信息。上半身参考中的下装可能由模型补全。
- 景别、运镜幅度、服装和场景保持由生成模型实际执行，需检查成片。片段之间采用剪辑衔接，不保证无缝长镜头。
- 保留项目文件夹可继续重做片段和重新合成；只需交付成片时，导出最终 MP4 即可。

## 开发与测试

```bash
python -m unittest discover -s tests -p "test_*.py" -v
node --test tests/test_timeline.mjs tests/test_material_mentions.mjs
```

测试范围及生成样本记录见 [验证记录](VERIFICATION.md)。

## 许可证

当前仓库未附开源许可证。公开可见不代表自动授权再分发或商用。