Extensions/ComfyUI-PhobosStream
ComfyUI Extension

ComfyUI-PhobosStream

Universal zero-VRAM diffusion streaming extension for ComfyUI. Enables running Wan2.1 (14B), FLUX.1 (12B), and HunyuanVideo (13B) on consumer Apple Silicon Macs (MLX) and NVIDIA RTX GPUs via 3-stage offloading and block-by-block NVMe streaming.

By martianacademy·Created 2 days ago·Updated about 24 hours ago· 0
martianacademy/ComfyUI-PhobosStream
Nodes—
On cloudLocal install
Stars0
Updatedabout 24 hours ago
Readme

ComfyUI-PhobosStream 🌌

License: MIT ComfyUI Backends

ComfyUI-PhobosStream is a zero-VRAM diffusion streaming custom node extension for ComfyUI. It enables consumer hardware — including 16GB/24GB Apple Silicon Macs and 8GB/12GB NVIDIA GeForce RTX GPUs — to generate professional-quality video and images with massive 12B–20B+ models without Out-Of-Memory (OOM) crashes.

🎯 Supported Models

  • Alibaba Wan2.1 (14B): 720p/1080p photorealistic text-to-video.
  • Black Forest Labs FLUX.1 (12B): SOTA photorealistic text-to-image.
  • Tencent HunyuanVideo (13B): Cinematic video generation.
  • THUDM CogVideoX (5B / 17B): Open-source video generation.

🚀 Installation

Option 1: Via ComfyUI Manager (Recommended)

  1. Open ComfyUI and open ComfyUI Manager.
  2. Click Install Custom Nodes.
  3. Search for ComfyUI-PhobosStream and click Install.
  4. Restart ComfyUI.

Option 2: Git Clone

cd ComfyUI/custom_nodes/
git clone https://github.com/martianacademy/ComfyUI-PhobosStream.git
cd ComfyUI-PhobosStream
pip install -r requirements.txt

🧩 Nodes & Workflow

graph LR
    L["🌌 PhobosStream Model Loader<br/>(Wan2.1 / FLUX.1 / Hunyuan)"] -->|"aether_model"| S["⚡ PhobosStream Diffusion Sampler<br/>(Prompt, Steps, Seed, Guidance)"]
    S -->|"images"| P["PreviewImage / SaveImage"]
    S -->|"latents"| V["🎞️ PhobosStream VAE Decoder"]
    V -->|"images"| VC["VHS_VideoCombine / Save"]

1. 🌌 PhobosStream Model Loader (Zero-VRAM)

  • Inputs:
    • model_name: Model identifier (e.g. wan2.1-14b, flux-schnell).
    • architecture: wan2.1, flux, hunyuan, cogvideox.
    • backend: auto (Apple Silicon Metal MLX / CUDA / GGUF).
    • num_blocks: Number of transformer blocks (e.g., 40 for Wan2.1).
    • hidden_size: Model hidden dimension (e.g., 4096).

2. ⚡ PhobosStream Diffusion Sampler (Disk-Stream)

  • Inputs:
    • aether_model: Connected from Loader.
    • prompt: Text description.
    • width & height: Resolution (e.g. 1280x720).
    • num_frames: Frames count (49 for video, 1 for image).
    • steps: Diffusion steps (20–30 recommended).
    • seed: Random seed.
  • Outputs:
    • images: Standard ComfyUI IMAGE tensor (Batch, H, W, 3).
    • latents: Raw spatio-temporal latent tensors.

3. 🎞️ PhobosStream VAE Decoder

  • Decodes latents to full-resolution RGB video frames.

📊 Empirical Benchmarks & VRAM Savings

| Model & Architecture | Baseline Full VRAM | ComfyUI-PhobosStream | VRAM Saved | Target Hardware | | :--- | :--- | :--- | :--- | :--- | | Alibaba Wan2.1 (14B Video) | ~38.4 GB (Weights + Act) | 788.11 MB | 97.9% Reduction | 8GB GPUs / Mac Mini (M1–M4) | | Z-Image-Turbo (11B DiT) | ~23.5 GB (18.8GB + Act) | ~920.00 MB | 96.1% Reduction | RTX 3060 / 4060 (8GB/12GB) | | FLUX.1 Schnell/Dev (12B) | ~24.8 GB | ~850.00 MB | 96.6% Reduction | 8GB-12GB GPUs / 16GB Macs | | SD-Turbo (Real-time) | ~2.8 GB | ~340.00 MB | 87.8% Reduction | Ultra Low-RAM Devices (<1GB) |

Live Measured Telemetry (Apple Silicon Metal GPU)

  • Text Encoding Stage:     2.47 ms (Sequential offload)
  • DiT Denoising Stage:     56.150 s (11.230 s/step @ 720p HD)
  • VAE Latent Decode Stage: 60.32 ms
  • Peak VRAM Consumption:   788.11 MB (Crash-Free Zero-VRAM Execution)

📜 License

MIT License — 100% Free & Open-Source.