# ComfyUI_RH_Helios

![License](https://img.shields.io/badge/License-Apache%202.0-green)

ComfyUI custom nodes for [Helios](https://github.com/PKU-YuanGroup/Helios) — a breakthrough 14B real-time long video generation model that achieves minute-scale, high-quality video synthesis at **19.5 FPS on a single H100 GPU**.

Supports **Text-to-Video**, **Image-to-Video**, and **Video-to-Video** generation within ComfyUI.

## ✨ Features

- **Text-to-Video (T2V)** — Generate videos from text prompts
- **Image-to-Video (I2V)** — Animate a static image into video with text guidance
- **Video-to-Video (V2V)** — Transform existing videos with text prompts
- **Low VRAM Mode** — Group offloading support, runs with as low as ~6GB VRAM
- **Pipeline Caching** — Automatic model caching to avoid redundant loading
- **Progress Bar** — Real-time ComfyUI progress tracking during generation

## 🛠️ Installation

### 1. Clone this repository into ComfyUI custom nodes directory

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/HM-RunningHub/ComfyUI_RH_Helios.git
```

### 2. Install dependencies

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

> **Note**: Requires PyTorch >= 2.7.1 with CUDA support. Make sure your PyTorch is installed with the correct CUDA version before installing requirements.

## 📦 Model Download & Installation

### Model Directory Structure

The Helios-Distilled model must be placed in `ComfyUI/models/Helios-Distilled/` with the following structure:

```
ComfyUI/
└── models/
    └── Helios-Distilled/
        ├── transformer/          # Transformer model weights
        ├── vae/                  # VAE model weights
        ├── scheduler/            # Scheduler configuration
        ├── tokenizer/            # Tokenizer files
        ├── text_encoder/         # Text encoder weights
        └── model_index.json      # Model index file
```

### Download Methods

#### Method 1: Download from HuggingFace (Recommended)

```bash
pip install "huggingface_hub[cli]"
huggingface-cli download BestWishYsh/Helios-Distilled --local-dir ComfyUI/models/Helios-Distilled
```

#### Method 2: Download from ModelScope (For China users)

```bash
pip install modelscope
modelscope download BestWishYSH/Helios-Distilled --local_dir ComfyUI/models/Helios-Distilled
```

#### Method 3: Manual Download

| Model | Link | Description |
|-------|------|-------------|
| Helios-Distilled | [HuggingFace](https://huggingface.co/BestWishYsh/Helios-Distilled) / [ModelScope](https://modelscope.cn/models/BestWishYSH/Helios-Distilled) | Best efficiency, x0-prediction with custom HeliosDMDScheduler. Recommended for ComfyUI. |
| Helios-Base | [HuggingFace](https://huggingface.co/BestWishYsh/Helios-Base) / [ModelScope](https://modelscope.cn/models/BestWishYSH/Helios-Base) | Best quality, v-prediction with standard CFG. |
| Helios-Mid | [HuggingFace](https://huggingface.co/BestWishYsh/Helios-Mid) / [ModelScope](https://modelscope.cn/models/BestWishYSH/Helios-Mid) | Intermediate checkpoint, may not meet expected quality. |

### Model Selection Guide

| Your GPU VRAM | Low VRAM Mode | Recommended Model | Notes |
|---------------|---------------|-------------------|-------|
| ≤ 8GB | ✅ Enable (leaf_level) | Helios-Distilled | ~6GB VRAM with group offloading |
| 8-16GB | ✅ Enable (block_level) | Helios-Distilled | Balanced speed and memory |
| ≥ 24GB | ❌ Disable | Helios-Distilled / Helios-Base | Full speed inference |

## 🚀 Usage

### Example Workflow

Download the example workflow from [`workflows/example_workflow.json`](workflows/example_workflow.json) and import it into ComfyUI.

The example demonstrates:
1. **Text-to-Video** — Generate a tropical fish video from a text prompt
2. **Image-to-Video** — Animate a reference image with a text description
3. **Video-to-Video** — Transform an input video with a new prompt

### Quick Start

1. Add a **RunningHub HeliosModelLoader** node to load the model
2. Connect it to a **RunningHub HeliosT2V** / **HeliosI2V** / **HeliosV2V** node
3. Connect the output to a **Save Video** node
4. Enter your prompt and run!

## 📝 Node Reference

### RunningHub HeliosModelLoader

Loads the Helios pipeline with configurable options.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| weight_dtype | bf16 / fp16 | bf16 | Model weight precision |
| enable_low_vram_mode | Boolean | True | Enable group offloading to save VRAM |
| group_offloading_type | block_level / leaf_level | block_level | Offloading granularity (leaf_level uses less VRAM) |

**Output**: `HELIOS_PIPE` — The loaded pipeline object

### RunningHub HeliosT2V

Generates video from a text prompt.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| prompt | String | — | Text description of the video to generate |
| width | Int | 640 | Video width (128-1920, step 16) |
| height | Int | 384 | Video height (128-1088, step 16) |
| num_frames | Int | 99 | Number of frames to generate (1-480) |
| num_inference_steps | Int | 50 | Denoising steps |
| guidance_scale | Float | 1.0 | Classifier-free guidance scale (0-20) |
| seed | Int | 42 | Random seed for reproducibility |
| is_enable_stage2 | Boolean | True | Enable pyramid stage2 acceleration |
| pyramid_steps | String | "2,2,2" | Comma-separated pyramid inference steps |
| is_amplify_first_chunk | Boolean | True | Amplify first chunk quality |
| negative_prompt | String | "" | (Optional) Negative prompt |

**Output**: `VIDEO`

### RunningHub HeliosI2V

Generates video from an image + text prompt. Same parameters as T2V plus:

| Parameter | Type | Description |
|-----------|------|-------------|
| image | IMAGE | Input reference image |

### RunningHub HeliosV2V

Transforms a video with text guidance. Same parameters as T2V plus:

| Parameter | Type | Description |
|-----------|------|-------------|
| video | VIDEO | Input video to transform |

### Frame Count Guide

Helios generates **33 frames per chunk**. For optimal results, use multiples of 33:

| num_frames | Actual Frames | Duration @24fps | Duration @16fps |
|------------|---------------|-----------------|-----------------|
| 99 | 99 (33×3) | ~4s | ~6s |
| 132 | 132 (33×4) | ~5.5s | ~8s |
| 264 | 264 (33×8) | ~11s | ~16s |

## 📄 License

This project is released under the [Apache 2.0 License](LICENSE.txt).

## 🔗 Links

- [RunningHub](https://www.runninghub.cn)
- [Original Helios Project](https://github.com/PKU-YuanGroup/Helios)
- [Helios Paper (arXiv)](https://arxiv.org/abs/2603.04379)
- [HuggingFace Models](https://huggingface.co/collections/BestWishYsh/helios)
- [ModelScope Models](https://modelscope.cn/collections/BestWishYSH/Helios)

## 🙏 Acknowledgements

This project is based on [Helios](https://github.com/PKU-YuanGroup/Helios), developed by PKU-YuanGroup. We thank them for their outstanding contribution to real-time long video generation.