ComfyUIRHFlashHead

ComfyUI custom nodes for SoulX-FlashHead — generate real-time streaming talking head videos from a reference image and audio.

✨ Features

• Talking Head Video Generation — Generate high-quality talking head videos driven by audio input
• Two Model Modes — Support both pro (higher quality) and lite (faster, real-time capable) models
• ComfyUI Native — Seamless integration with ComfyUI's IMAGE and AUDIO types, outputs standard VIDEO
• Streaming Architecture — Chunk-based audio processing for efficient long-form generation

🛠️ Installation

Method 1: ComfyUI Manager (Recommended)

Search for ComfyUI_RH_FlashHead in ComfyUI Manager and install.

Method 2: Manual Installation

cd ComfyUI/custom_nodes
git clone https://github.com/HM-RunningHub/ComfyUI_RH_FlashHead.git
cd ComfyUI_RH_FlashHead
pip install -r requirements.txt

Dependencies

This node requires the following system-level dependency:

• FFmpeg — Required for merging video and audio

# Ubuntu / Debian
apt-get install ffmpeg

# CentOS / RHEL
yum install ffmpeg ffmpeg-devel

# Conda (no root required)
conda install -c conda-forge ffmpeg==7

📦 Model Download & Installation

Model Directory Structure

All models must be placed under ComfyUI/models/ with the following structure:

ComfyUI/
└── models/
    ├── Soul-AILab/
    │   └── SoulX-FlashHead-1_3B/     # FlashHead model checkpoint
    │       ├── config.json
    │       ├── model_lite/
    │       └── model_pro/
    └── wav2vec/
        └── facebook/
            └── wav2vec2-base-960h/    # Audio encoder

Download Methods

Method 1: Download from HuggingFace (Recommended)

pip install "huggingface_hub[cli]"

# Download FlashHead model
huggingface-cli download Soul-AILab/SoulX-FlashHead-1_3B \
    --local-dir ComfyUI/models/Soul-AILab/SoulX-FlashHead-1_3B

# Download wav2vec2 audio encoder
huggingface-cli download facebook/wav2vec2-base-960h \
    --local-dir ComfyUI/models/wav2vec/facebook/wav2vec2-base-960h

Method 2: Download from HuggingFace Mirror (For China users)

export HF_ENDPOINT=https://hf-mirror.com
pip install "huggingface_hub[cli]"

huggingface-cli download Soul-AILab/SoulX-FlashHead-1_3B \
    --local-dir ComfyUI/models/Soul-AILab/SoulX-FlashHead-1_3B

huggingface-cli download facebook/wav2vec2-base-960h \
    --local-dir ComfyUI/models/wav2vec/facebook/wav2vec2-base-960h

Method 3: Manual Download

Model	Link	Description
SoulX-FlashHead-1_3B	HuggingFace	FlashHead 1.3B model (pro + lite)
wav2vec2-base-960h	HuggingFace	Facebook wav2vec2 audio encoder

Model Selection Guide

Your GPU VRAM	Recommended Model	Performance
≥ 24GB	pro	Higher quality, ~10.8 FPS on RTX 4090
≥ 8GB	lite	Real-time capable, ~96 FPS on RTX 4090

🚀 Usage

Nodes

This package provides two ComfyUI nodes:

RunningHub SoulX-FlashHead Loader

Loads the FlashHead pipeline into memory.

Parameter	Type	Default	Description
model_type	pro / lite	lite	Model variant to load

Output: FlashHead Pipeline object

RunningHub SoulX-FlashHead Sampler

Generates a talking head video from a pipeline, reference image, and audio.

Parameter	Type	Default	Description
pipeline	FlashHead Pipeline	—	Pipeline from Loader node
ref_audio	AUDIO	—	Driving audio
avatar_image	IMAGE	—	Reference face image
seed	INT	42	Random seed
width	INT	512	Output video width
height	INT	512	Output video height

Output: VIDEO — Generated talking head video with audio

Example Workflow

Download the example workflow from workflows/example_workflow_api.json and import it into ComfyUI.

The workflow demonstrates:

1. Load Image — Load a reference face image
2. Load Audio — Load a driving audio file
3. FlashHead Loader — Initialize the pipeline (lite mode)
4. FlashHead Sampler — Generate talking head video
5. Save Video — Save the output video

📄 License

This project is licensed under the Apache License 2.0.

🔗 Links

• RunningHub
• SoulX-FlashHead (Original Project)
• SoulX-FlashHead Technical Report (arXiv)
• SoulX-FlashHead-1_3B Model

🙏 Acknowledgements

This project is based on SoulX-FlashHead, developed by Soul-AILab.

We also acknowledge the foundational work from:

• Wan — Base model
• LTX-Video — VAE for Lite model
• Self-Forcing — Codebase foundation