# ComfyUI-CaptureVideoFrame

**Repository Path**: alizeegod/ComfyUI-CaptureVideoFrame

## Basic Information

- **Project Name**: ComfyUI-CaptureVideoFrame
- **Description**: ComfyUI插件，截取视频关键帧
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-04
- **Last Updated**: 2026-01-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ComfyUI-CaptureVideoFrame

ComfyUI自定义节点插件，用于从视频中提取关键帧。支持通过进度条手动选择帧，默认选择视频的最后一帧，并支持关键帧图片下载和传递给下一个节点。

## 功能特性

- ✅ 支持从视频文件路径或视频帧序列输入
- ✅ 通过进度条手动选择关键帧
- ✅ 默认选择视频的最后一帧
- ✅ 支持关键帧图片下载（保存到ComfyUI输出目录或自定义路径）
- ✅ 支持将关键帧传递给下一个节点进行处理
- ✅ 友好的用户界面，实时显示当前选中的帧索引

## 安装

### 方法1：使用Git克隆

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/yourusername/ComfyUI-CaptureVideoFrame.git
cd ComfyUI-CaptureVideoFrame
```

### 方法2：手动安装

1. 将整个 `ComfyUI-CaptureVideoFrame` 文件夹复制到 `ComfyUI/custom_nodes` 目录下
2. 安装依赖：

```bash
pip install -r requirements.txt
```

## 依赖项

- `opencv-python>=4.8.0` - 用于视频处理
- `Pillow>=10.0.0` - 用于图像保存
- `numpy>=1.24.0` - 用于数组处理

## 使用方法

### 基本使用

1. 在ComfyUI界面中，找到 `Video Keyframe Extractor` 节点
2. 连接视频输入：
   - **方式1**：使用 `video_path` 输入，提供视频文件的完整路径
   - **方式2**：使用 `video_frames` 输入，连接其他视频处理节点的输出
3. 使用进度条选择要提取的帧：
   - 拖动进度条选择帧索引（0到总帧数-1）
   - 默认值为-1，表示选择最后一帧
   - 界面会实时显示当前选中的帧索引
4. 配置保存选项：
   - `save_path`：可选，自定义保存路径（留空则使用ComfyUI输出目录）
   - `download_enabled`：是否启用下载功能（默认启用）
5. 运行工作流，节点会：
   - 提取选中的关键帧
   - 保存关键帧图片（如果启用下载）
   - 输出关键帧图像和保存路径

### 节点输入

- **frame_index** (INT, 必需): 要提取的帧索引
  - `-1`: 默认值，选择最后一帧
  - `0` 到 `总帧数-1`: 选择指定索引的帧
  - 可通过进度条拖动选择

- **video_path** (STRING, 可选): 视频文件路径
  - 如果提供，将从该路径读取视频
  - 支持常见视频格式（mp4, avi, mov等）

- **video_frames** (IMAGE, 可选): 视频帧序列
  - 如果提供，将直接使用这些帧
  - 优先级高于 `video_path`

- **save_path** (STRING, 可选): 自定义保存路径
  - 留空则使用ComfyUI的默认输出目录
  - 如果指定，必须是一个有效的目录路径

- **download_enabled** (BOOLEAN, 可选): 是否启用下载
  - `True`: 保存关键帧图片到文件
  - `False`: 不保存文件，仅输出图像数据

### 节点输出

- **keyframe_image** (IMAGE): 选中的关键帧图像
  - 可以直接连接到其他图像处理节点
  - 格式：ComfyUI标准IMAGE类型

- **keyframe_path** (STRING): 关键帧保存路径
  - 如果启用了下载，返回保存的文件路径
  - 如果未启用下载，返回空字符串

## 使用示例

### 示例1：从视频文件提取最后一帧

```
[Load Video] -> [Video Keyframe Extractor] (frame_index=-1) -> [其他图像处理节点]
```

### 示例2：提取指定帧并保存

1. 连接视频文件路径到 `video_path`
2. 拖动进度条选择帧索引（例如：100）
3. 设置 `save_path` 为自定义目录（可选）
4. 启用 `download_enabled`
5. 运行工作流，关键帧将保存到指定位置

### 示例3：从视频帧序列提取关键帧

```
[视频处理节点] -> [Video Keyframe Extractor] (video_frames输入) -> [图像处理节点]
```

## 文件结构

```
ComfyUI-CaptureVideoFrame/
├── __init__.py                 # 节点注册入口
├── nodes/
│   └── video_keyframe.py      # 主节点实现
├── web/
│   └── video_keyframe.js      # 前端UI交互（进度条）
├── requirements.txt            # Python依赖
├── README.md                   # 使用说明
└── LICENSE                     # 许可证
```

## 注意事项

1. **内存使用**：对于大视频文件，加载所有帧到内存可能会消耗大量内存。建议：
   - 使用较小的视频文件
   - 或者先使用其他节点进行视频预处理（如降采样）

2. **视频格式**：支持OpenCV能够读取的所有视频格式，包括：
   - MP4, AVI, MOV, MKV等常见格式

3. **帧索引**：
   - 帧索引从0开始
   - 最后一帧的索引 = 总帧数 - 1
   - 默认值-1会自动选择最后一帧

4. **保存路径**：
   - 如果指定的保存路径不存在，会自动创建
   - 文件名格式：`keyframe_{timestamp}_{frame_index}.png`

## 故障排除

### 问题：无法打开视频文件

**解决方案**：
- 检查视频文件路径是否正确
- 确保视频文件格式受支持
- 检查文件权限

### 问题：进度条不显示

**解决方案**：
- 刷新ComfyUI页面
- 检查浏览器控制台是否有JavaScript错误
- 确保 `web/video_keyframe.js` 文件存在

### 问题：内存不足

**解决方案**：
- 使用较小的视频文件
- 先对视频进行降采样或裁剪
- 考虑使用流式处理方式（需要修改代码）

## 许可证

Apache License 2.0

## 贡献

欢迎提交Issue和Pull Request！

## 更新日志

### v1.0.0
- 初始版本
- 支持视频关键帧提取
- 支持进度条手动选择帧
- 支持关键帧下载和传递