ComfyUI Extension: ComfyUI-FlashVSR_Stable

Authored by naxci1

Created 8 months ago

Updated 5 months ago

60 stars

Run ComfyUI workflows without the setup

No installs, no CUDA version roulette, no GPU sitting idle on your bill. Bring a workflow and run it in the browser.

High-performance Video Super Resolution for ComfyUI with VRAM optimization.

Looking for a different extension?

Custom Nodes (3)

README

ComfyUI-FlashVSR_Stable

High-performance Video Super Resolution for ComfyUI with VRAM optimization.

Run FlashVSR on 8GB-24GB+ GPUs without artifacts. Features intelligent resource management, 5 VAE options, and auto-downloading models.

Registry Link: https://registry.comfy.org/publishers/naxci1/nodes/ComfyUI-FlashVSR_Stable

✨ Key Features

🎬 Video Super Resolution: 2x or 4x upscaling using FlashVSR diffusion models
🧠 5 VAE Options: Choose from Wan2.1, Wan2.2, LightVAE, TAE variants for optimal VRAM/quality trade-off
📊 Pre-Flight Resource Check: Intelligent VRAM estimation with settings recommendations
⚡ Auto-Download: Models download automatically from HuggingFace if missing
🛡️ OOM Protection: Automatic recovery with progressive fallback (tiled VAE → tiled DiT → chunking)
🔧 Unified Pipeline: All modes share optimized processing logic

📋 Quick Links

Performance & VRAM Optimization

This node is optimized for various hardware configurations. Here are some guidelines:

VRAM Tiers & Settings

| VRAM | Mode | Tiling | Chunk Size | Precision | Notes | | :--- | :--- | :--- | :--- | :--- | :--- | | 24GB+ | full or tiny | Disabled | 0 (All) | bf16/auto | Max quality/speed. | | 16GB | tiny | tiled_vae=True | 0 or ~100 | bf16/auto | Enable keep_models_on_cpu. | | 12GB | tiny | tiled_vae=True, tiled_dit=True | ~50 | fp16 | Use sparse_sage attention. | | 8GB | tiny-long | Required | ~20 | fp16 | Must use tiling and chunking. |

Performance Enhancements

Attention Mode: Use sparse_sage_attention for the best balance of speed and memory. flash_attention_2 is faster but requires specific hardware/installation.
Precision: bf16 (BFloat16) is recommended for RTX 3000/4000/5000 series. It is faster and preserves dynamic range better than fp16.
Chunking: Use frame_chunk_size to process videos in segments. This moves processed frames to CPU RAM, preventing VRAM saturation on long clips.
Resize Input: If the input video is large (e.g., 1080p), use the resize_factor parameter to reduce input size to 0.5x before processing. This drastically reduces VRAM usage and allows for 4x upscaling of the resized result (net 2x output). For small videos, leave at 1.0.

Pre-Flight Resource Check (NEW)

Before processing, FlashVSR now performs an intelligent pre-flight check that:

Estimates VRAM Requirements: Calculates approximate VRAM needed based on resolution, frames, scale, and settings.
Checks Available Resources: Uses torch.cuda.mem_get_info() for accurate real-time VRAM availability.
Provides Recommendations: If OOM is predicted, suggests optimal settings.

Example console output:

============================================================
🔍 PRE-FLIGHT RESOURCE CHECK
💻 RAM: 15.4GB / 95.8GB
💾 VRAM Available: 14.2GB
📊 Estimated VRAM Required: 12.8GB
✅ Safe to proceed. Estimated ~12.8GB needed, 14.2GB available.
============================================================

If VRAM is insufficient:

⚠️ Current settings require ~18.5GB but only 8.0GB available.
💡 Recommended Optimal Settings:
  • chunk_size = 32
  • tiled_vae = True
  • tiled_dit = True
  • resize_factor = 0.6

🎨 VAE Model Selection

VAE Type Comparison

| VAE Type | VRAM Usage | Speed | Quality | Best For | | :--- | :--- | :--- | :--- | :--- | | Wan2.1 | 8-12 GB | Baseline | ⭐⭐⭐⭐⭐ | Maximum quality, 24GB+ VRAM | | Wan2.2 | 8-12 GB | Baseline | ⭐⭐⭐⭐⭐ | Improved normalization for Wan2.2 models | | LightVAE_W2.1 | 4-5 GB | 2-3x faster | ⭐⭐⭐⭐ | 8-16GB VRAM, speed priority | | TAE_W2.2 | 6-8 GB | 1.5x faster | ⭐⭐⭐⭐ | Temporal consistency priority | | LightTAE_HY1.5 | 3-4 GB | 3x faster | ⭐⭐⭐⭐ | HunyuanVideo compatible, minimum VRAM |

VAE Selection Guide

Auto-Download

All VAE models auto-download from HuggingFace if not found locally:

📖 Best Practices / Settings Guide

Low VRAM (8-12GB) Configuration

Mode: tiny-long
VAE: LightVAE_W2.1 or LightTAE_HY1.5
Tiled VAE: ✅ Enabled
Tiled DiT: ✅ Enabled
Chunk Size: 16-32
Resize Factor: 0.5-0.8
Keep Models on CPU: ✅ Enabled

Medium VRAM (16GB) Configuration

Mode: tiny
VAE: Wan2.1 or LightVAE_W2.1
Tiled VAE: ✅ Enabled
Tiled DiT: Optional
Chunk Size: 50-100
Resize Factor: 1.0
Keep Models on CPU: Optional

High VRAM (24GB+) Configuration

Mode: full or tiny
VAE: Wan2.1 or Wan2.2
Tiled VAE: ❌ Disabled
Tiled DiT: ❌ Disabled
Chunk Size: 0 (all frames)
Resize Factor: 1.0
Keep Models on CPU: ❌ Disabled

Processing Summary

At the end of each run, you'll see a summary:

============================================================
📊 PROCESSING SUMMARY
⏱️ Total Processing Time: 130.08s (1.54 FPS)
📥 Input Resolution: 276x206 (200 frames)
📤 Output Resolution: 552x412 (200 frames)
📈 Peak VRAM Used: 12.4 GB
============================================================

🔧 Node Parameters

Hover over any input in ComfyUI to see tooltips. Full parameter list:

💻 Command-Line Interface (CLI)

FlashVSR includes a full-featured CLI that mirrors all ComfyUI node parameters for standalone video upscaling.

Quick Start

# Basic 2x upscale
python cli_main.py --input video.mp4 --output upscaled.mp4 --scale 2

# 4x upscale with tiling for lower VRAM
python cli_main.py --input video.mp4 --output upscaled.mp4 --scale 4 \
    --tiled_vae --tiled_dit --tile_size 256 --tile_overlap 24

# Long video with chunking to prevent OOM
python cli_main.py --input long_video.mp4 --output upscaled.mp4 \
    --frame_chunk_size 50 --mode tiny-long

# Low VRAM mode (8GB GPUs)
python cli_main.py --input video.mp4 --output upscaled.mp4 --scale 2 \
    --vae_model LightVAE_W2.1 --tiled_vae --tiled_dit \
    --frame_chunk_size 20 --resize_factor 0.5

# Custom models directory
python cli_main.py --input video.mp4 --output upscaled.mp4 \
    --models_dir /path/to/your/models

CLI Arguments Reference

All arguments map 1:1 with ComfyUI node inputs. Run python cli_main.py --help for full details.

Required Arguments

Pipeline Initialization (from FlashVSRNodeInitPipe)

Processing Parameters (from FlashVSRNodeAdv)

Video I/O Parameters

🚀 Installation

Step 1: Install the Node

cd ComfyUI/custom_nodes
git clone https://github.com/naxci1/ComfyUI-FlashVSR_Stable.git
python -m pip install -r ComfyUI-FlashVSR_Stable/requirements.txt

📢 Turing architecture or older GPUs (GTX 16 series, RTX 20 series, and earlier): Install triton<3.3.0:
# Windows
python -m pip install -U triton-windows<3.3.0
# Linux
python -m pip install -U triton<3.3.0

Step 2: Download Models

Download the FlashVSR folder from HuggingFace:

ComfyUI/models/FlashVSR/
├── LQ_proj_in.ckpt
├── TCDecoder.ckpt
├── diffusion_pytorch_model_streaming_dmd.safetensors
└── Wan2.1_VAE.pth  (or auto-downloads)

💡 VAE files auto-download from HuggingFace if not present. Only the DiT model and other components need manual download.

Step 3: Custom Model Paths (Optional)

By default, FlashVSR looks for models in ComfyUI/models/FlashVSR/. To use a different location (e.g., models on another drive):

Edit model_paths.yaml in the ComfyUI-FlashVSR_Stable directory
Set flashvsr_model_path to your custom path
Restart ComfyUI

Example configurations:

# Windows (D: drive)
flashvsr_model_path: "D:/AI/Models/FlashVSR"

# Windows (alternative syntax)
flashvsr_model_path: "E:\\ComfyUI\\models\\FlashVSR"

# Linux/Mac
flashvsr_model_path: "/home/user/models/FlashVSR"
flashvsr_model_path: "/mnt/storage/AI/FlashVSR"

# Use default (leave empty)
flashvsr_model_path: ""

📂 Auto-Download Support: If model files don't exist, they will automatically download to the directory specified in model_paths.yaml. The custom path will be created if needed.

Example: If you set flashvsr_model_path: "D:/AI/Models", models will automatically download to D:/AI/Models/FlashVSR/ on first use.

🖼️ Preview

Workflow Preview

Sample Workflow

Download Workflow JSON

🏷️ Recent Changes

See CHANGELOG.md for full version history.

🙏 Acknowledgments

FlashVSR @OpenImagingLab
Sparse_SageAttention @jt-zhang
ComfyUI @comfyanonymous
Wan2.2 @Wan-Video
LightX2V @ModelTC
LightX2V Autoencoders @lightx2v

📄 License

MIT License - see LICENSE for details.

Run ComfyUI workflows without the setup

No installs, no CUDA version roulette, no GPU sitting idle on your bill. Bring a workflow and run it in the browser.

Learn more