163 lines
3.1 KiB
Markdown
163 lines
3.1 KiB
Markdown
# ComfyUI-FrameIO
|
||
|
||
High-performance frame input/output nodes for **AI video pipelines** in ComfyUI.
|
||
|
||
ComfyUI-FrameIO focuses on **efficient frame storage, loading, and reuse** for long video generation workflows, solving common problems like massive PNG sizes, duplicate frames, and fragile filename-based loading.
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
### 🧩 Frame Saving
|
||
- Save batch `IMAGE` tensors as **WebP**
|
||
- **Lossy or Lossless WebP**
|
||
- **Skip identical frames** using hash-based deduplication
|
||
- Massive disk space reduction vs PNG
|
||
- Returns **STRING_LIST** (ComfyUI list-native)
|
||
|
||
### 📥 Frame Loading
|
||
- Pattern-based frame loading
|
||
- **STRING_LIST → IMAGE loader** (no filename guessing)
|
||
- **Frame range selector** (`start`, `end`, `step`)
|
||
- **Auto-detect frame count**
|
||
- Safe with duplicate paths (from deduplication)
|
||
|
||
### ⚡ Optimized for AI Video
|
||
- Designed for **long sequences**
|
||
- Works with WebP / PNG / JPG
|
||
- Preserves exact frame ordering
|
||
- Compatible with FFmpeg / Video Combine nodes
|
||
|
||
---
|
||
|
||
## 📦 Included Nodes
|
||
|
||
### 🔹 Batch Save Image Sequence (WebP)
|
||
Save an image batch efficiently to disk.
|
||
|
||
**Inputs**
|
||
- `images` (IMAGE)
|
||
- `path_pattern` (STRING)
|
||
- `start_index` (INT)
|
||
- `lossless` (true / false)
|
||
- `quality` (INT)
|
||
- `skip_identical` (true / false)
|
||
- `overwrite` (true / false)
|
||
|
||
**Outputs**
|
||
- `paths` (STRING_LIST)
|
||
|
||
---
|
||
|
||
### 🔹 Batch Load Image Sequence
|
||
Load images from disk using a filename pattern.
|
||
|
||
**Inputs**
|
||
- `path_pattern` (STRING)
|
||
- `start_index` (INT)
|
||
- `frame_count` (INT)
|
||
- `ignore_missing_images` (true / false)
|
||
|
||
**Outputs**
|
||
- `images` (IMAGE)
|
||
|
||
---
|
||
|
||
### 🔹 Batch Load Image List (Advanced)
|
||
Load images directly from a `STRING_LIST`.
|
||
|
||
**Inputs**
|
||
- `paths` (STRING_LIST)
|
||
- `start` (INT, optional)
|
||
- `end` (INT, optional)
|
||
- `step` (INT, optional)
|
||
|
||
**Outputs**
|
||
- `images` (IMAGE)
|
||
- `frame_count` (INT)
|
||
|
||
> This is the **recommended loader** when using frame deduplication.
|
||
|
||
---
|
||
|
||
## 🧠 Why ComfyUI-FrameIO?
|
||
|
||
| Problem | Solution |
|
||
|------|------|
|
||
| PNG sequences too large | WebP (5–10× smaller) |
|
||
| Duplicate frames | Hash-based skip |
|
||
| Filename guessing | STRING_LIST loader |
|
||
| Partial re-render | Frame range selector |
|
||
| Long videos | Optimized IO |
|
||
|
||
---
|
||
|
||
## 🎬 Recommended Workflows
|
||
|
||
### 🔥 Best Practice (Long Videos)
|
||
```
|
||
|
||
KSampler
|
||
↓
|
||
Batch Save Image Sequence (WebP)
|
||
↓ STRING_LIST
|
||
Batch Load Image List (Advanced)
|
||
↓ IMAGE
|
||
Video Combine / FFmpeg
|
||
|
||
````
|
||
|
||
### 🎯 Partial Reload
|
||
- `start = 300`
|
||
- `end = 900`
|
||
- `step = 2`
|
||
|
||
Perfect for re-encoding or post-processing sections.
|
||
|
||
---
|
||
|
||
## ⚙️ Recommended Settings
|
||
|
||
| Use Case | Settings |
|
||
|-------|---------|
|
||
| Final video | Quality 95, Skip Identical = true |
|
||
| Iteration | Quality 90 |
|
||
| Dataset / archival | Lossless = true |
|
||
| Static shots | Skip Identical = true |
|
||
|
||
---
|
||
|
||
## 📥 Installation
|
||
|
||
```bash
|
||
cd ComfyUI/custom_nodes
|
||
git clone https://github.com/<yourname>/ComfyUI-FrameIO.git
|
||
````
|
||
|
||
Restart ComfyUI.
|
||
|
||
Nodes will appear under:
|
||
|
||
```
|
||
FrameIO
|
||
```
|
||
|
||
---
|
||
|
||
## 🔮 Roadmap (Planned / Ideas)
|
||
|
||
* FFmpeg encode node (no frame storage)
|
||
* AVIF support
|
||
* 10-bit video output
|
||
* Keyframe detection
|
||
* Frame cache / reuse
|
||
* Timeline tools
|
||
|
||
Contributions and suggestions welcome.
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT
|