ComfyUI Extension: MiniMax Video Object Remover Suite
Professional video object removal suite using MiniMax optimization. Includes BMO-enhanced nodes with VAE normalization, temporal preservation, and 6-step inference. Complete video inpainting solution for ComfyUI.
Custom Nodes (0)
README
๐ฏ MiniMax-Remover for ComfyUI
High-quality video object removal with automatic model management and universal resolution support
<p align="center"> <a href="https://huggingface.co/zibojia/minimax-remover"><img alt="Huggingface Model" src="https://img.shields.io/badge/%F0%9F%A4%97%20Huggingface-Model-brightgreen"></a> <a href="https://github.com/zibojia/MiniMax-Remover"><img alt="Github" src="https://img.shields.io/badge/MiniMaxRemover-github-black"></a> <a href="https://arxiv.org/abs/2505.24873"><img alt="arXiv" src="https://img.shields.io/badge/MiniMaxRemover-arXiv-b31b1b"></a> </p>๐ Major Improvements & Features
โจ Latest Enhancements
- โ Auto-Download Models: Zero-configuration setup - models download automatically on first use
- โ Universal Resolution Support: Works with ANY resolution input (480p to 4K+)
- โ Smart VAE Compatibility: Automatic dimension adjustment for perfect compatibility
- โ OpenCV Conflict Resolution: No more OpenCV reinstallation issues
- โ DW Preprocessor Compatibility: Works seamlessly with DWPose and other preprocessors
- โ Tensor Dimension Fixes: Eliminates all dimension mismatch errors
- โ Professional Quality: Proper VAE normalization for natural, high-quality results
๐ฎ Core Features
- Fast: Only 6-12 inference steps, highly optimized
- Robust: Handles any mask/video resolution combination automatically
- Plug-and-Play: Install and use immediately - no manual setup required
- Production Ready: Comprehensive error handling and diagnostics
๐ฅ Installation
Method 1: ComfyUI Manager (Recommended)
- Open ComfyUI Manager
- Click "Install Custom Nodes"
- Search for "MiniMax-bmo"
- Click Install and restart ComfyUI
Method 2: Manual Installation
cd ComfyUI/custom_nodes
git clone https://github.com/CasterPollux/MiniMax-bmo.git
cd MiniMax-Remover
# Install with CUDA support (recommended)
pip install -r requirements.txt
Method 3: Automatic Setup Script
# Run the setup script for automatic ComfyUI integration
python setup_comfyui_integration_bmo.py
๐ค Model Management - Auto-Download System
Zero-Configuration Experience (Default)
When you first use the node:
๐ Checking for MiniMax-Remover models...
๐ฅ Models not found locally. Starting automatic download...
๐ Downloading MiniMax-Remover models to: ./models
๐ Expected download size: ~25-30 GB
โณ This may take several minutes depending on your connection...
๐ Models downloaded successfully!
โ
Processing your video...
Model Download Details
- Total Size: ~2-3 GB (one-time download)
- Components:
- VAE (~500mb) - Video encoding/decoding
- Transformer (~2GB) - Main diffusion model
- Scheduler (~1KB) - Denoising control (json only)
- Source: HuggingFace: zibojia/minimax-remover
Storage Locations (Auto-Detected)
The system automatically tries these locations in priority order:
Option 1: Custom Node Directory (Default)
ComfyUI/custom_nodes/MiniMax-Remover/models/
โโโ minimax_vae/ (VAE encoder/decoder)
โโโ minimax_transformer/ (main diffusion model)
โโโ minimax_scheduler/ (denoising scheduler)
Option 2: ComfyUI Models Directory
ComfyUI/models/
โโโ minimax_vae/ (MiniMax VAE models)
โโโ minimax_transformer/ (MiniMax Transformer models)
โโโ minimax_scheduler/ (MiniMax Scheduler configs)
Option 3: User Cache Directory (Fallback)
~/.cache/minimax-remover/models/
โโโ minimax_vae/
โโโ minimax_transformer/
โโโ minimax_scheduler/
Windows: C:\Users\[Username]\.cache\minimax-remover\models\
Manual Download Options
If auto-download fails or you prefer manual control:
# Option 1: Use built-in script
python download_models.py
# Option 2: Direct HuggingFace download
huggingface-cli download zibojia/minimax-remover --local-dir ./models --local-dir-use-symlinks False
# Then rename folders for clarity:
mv ./models/vae ./models/minimax_vae
mv ./models/transformer ./models/minimax_transformer
mv ./models/scheduler ./models/minimax_scheduler
# Option 3: Download to ComfyUI models directory
huggingface-cli download zibojia/minimax-remover --local-dir ComfyUI/models --local-dir-use-symlinks False
# Then rename folders for clarity:
mv ComfyUI/models/vae ComfyUI/models/minimax_vae
mv ComfyUI/models/transformer ComfyUI/models/minimax_transformer
mv ComfyUI/models/scheduler ComfyUI/models/minimax_scheduler
๐ For detailed setup instructions, see AUTO_DOWNLOAD_GUIDE.md
๐ฏ Universal Resolution Support
ANY Resolution Now Supported!
The node now handles any resolution input with automatic compatibility:
- โ Any input resolution - 480p, 720p, 1080p, 4K, custom resolutions
- โ Mixed mask/image sizes - automatically handles different resolution inputs
- โ VAE compatibility - dimensions automatically adjusted for perfect compatibility
- โ No configuration needed - works automatically
Example Resolution Fixes
| Input Resolution | Problem | Auto-Fixed To | Result |
|------------------|---------|---------------|--------|
| 1000x1778
| 125x222.25 latent | 1008x1784
| 126x223 โ
|
| 720x480
| No issue | 720x480
| 90x60 โ
|
| 1920x1080
| 240x135 | 1920x1088
| 240x136 โ
|
๐ For technical details, see TENSOR_DIMENSION_FIX_GUIDE.md
๐ ๏ธ Compatibility Fixes
OpenCV Conflict Resolution โ
Problem Solved: Users were experiencing OpenCV reinstallation prompts and conflicts.
Root Cause: Multiple conflicting OpenCV version requirements across different files:
requirements.txt
:opencv-python==4.5.5.64
(exact old version)requirements_bmo.txt
:opencv-python>=4.8.0
(newer minimum)pyproject.toml
:opencv-python>=4.7.0
(different minimum)
Solution Applied:
- โ
Standardized OpenCV requirements to
opencv-python>=4.5.0,<5.0.0
across all files - โ Safe installation procedures that don't break existing OpenCV installations
- โ Recovery scripts for users with broken installations
Result: No more OpenCV reinstallation prompts or conflicts!
DW Preprocessor Compatibility โ
Problem Solved: Conflicts between MiniMax-Remover and DWPose/DW preprocessors.
Root Cause: Multiple compatibility issues:
- PyTorch version conflicts (
torch==2.6
vs DWPose requirement<2.4
) - Segment Anything model loading conflicts
- ONNX runtime conflicts
- CUDA memory issues from simultaneous GPU usage
Solution Applied:
- โ
Compatible PyTorch range:
torch>=2.0.0,<2.5.0
for DWPose compatibility - โ TorchVision compatibility: Proper version alignment
- โ Memory management: Smart GPU memory handling
- โ Model isolation: Prevents loading conflicts
Result: MiniMax-Remover now works seamlessly with DWPose and other preprocessors!
๐ For detailed compatibility info, see DW_PREPROCESSOR_COMPATIBILITY.md
๐ Usage
In ComfyUI
-
Add the Node: Look for "MiniMax-Remover (BMO)" in the MiniMax-Remover category
-
Connect Inputs:
images
: Your video frames as IMAGE typemasks
: Your binary masks as MASK type
-
Configure (Optional):
num_inference_steps
: 12 (default, optimal quality/speed balance)iterations
: 6 (mask expansion, default works for most cases)seed
: Any number for reproducible resultsauto_download
: True (default, enables automatic model management)
-
Run: Perfect results with any resolution combination!
Node Parameters
Core Settings
auto_download
:True
(default) - Automatic model managementnum_inference_steps
:12
(default) - Quality/speed balanceiterations
:6
(default) - Mask expansion iterationsseed
:42
(default) - Random seed for reproducible results
Advanced Settings (Auto-Detected)
vae_path
:"auto"
(default) - Auto-detected VAE pathtransformer_path
:"auto"
(default) - Auto-detected Transformer pathscheduler_path
:"auto"
(default) - Auto-detected Scheduler path
What You'll See
First Use (Auto-Download)
๐ง Using BMO MiniMax-Remover Pipeline (Flexible Resolution)
๐ Input Analysis:
Images: torch.Size([165, 1920, 1080, 3])
Masks: torch.Size([165, 1024, 576, 1])
Using input dimensions as target: 1920x1080
๐ง Auto-resizing for compatibility to 1920x1080
VAE-compatible target: 1920x1088
Resizing masks: 1024x576 -> 1920x1088
๐ Models downloaded successfully with descriptive names!
๐ MiniMax VAE: D:\ComfyUI\custom_nodes\MiniMax-Remover\models\minimax_vae
๐ MiniMax Transformer: D:\ComfyUI\custom_nodes\MiniMax-Remover\models\minimax_transformer
๐ MiniMax Scheduler: D:\ComfyUI\custom_nodes\MiniMax-Remover\models\minimax_scheduler
โ
Processing complete - perfect results!
Subsequent Uses (Instant)
๐ Checking for MiniMax-Remover models...
โ
Found existing models at: D:\ComfyUI\custom_nodes\MiniMax-Remover\models (descriptive names)
VAE: D:\ComfyUI\custom_nodes\MiniMax-Remover\models\minimax_vae
Transformer: D:\ComfyUI\custom_nodes\MiniMax-Remover\models\minimax_transformer
Scheduler: D:\ComfyUI\custom_nodes\MiniMax-Remover\models\minimax_scheduler
โ
BMO MiniMax-Remover models loaded successfully!
๐ Processing your video...
๐ง Troubleshooting
Common Issues & Solutions
Models Not Downloading
# Check internet connection and try manual download
python download_models.py
# Or use HuggingFace CLI
huggingface-cli download zibojia/minimax-remover --local-dir ./models
PyTorch CUDA Issues
# If PyTorch gets downgraded to CPU version during installation:
# 1. Reinstall PyTorch with CUDA support first
pip install torch>=2.0.0,<2.8.0 torchvision>=0.15.0,<0.20.0 --index-url https://download.pytorch.org/whl/cu121
# 2. Then install other dependencies
pip install -r requirements.txt --no-deps --force-reinstall diffusers transformers accelerate
OpenCV Conflicts
# Install with compatible versions
pip install -r requirements.txt
# If issues persist, see INSTALLATION_GUIDE_OPENCV_FIX.md
DW Preprocessor Conflicts
# Use compatible PyTorch version
pip install "torch>=2.0.0,<2.5.0" "torchvision>=0.15.0,<0.20.0"
# See DW_PREPROCESSOR_COMPATIBILITY.md for details
Memory Issues
- Use smaller input resolutions
- Enable model offloading in ComfyUI settings
- Close other GPU-intensive applications
Poor Quality Results
- Ensure you're using the latest BMO version
- Try different seeds (use seed parameter)
- Adjust mask expansion (iterations parameter: 6-10)
- Check that masks are clean and binary
๐ Project Structure
The MiniMax-Remover models can be stored in two different locations. Check both locations to find your models:
MiniMax-Remover/
โโโ ๐ README.md (this file)
โโโ ๐ง minimax_mask_node_bmo.py (main ComfyUI node)
โโโ ๐ง pipeline_minimax_remover_bmo.py (processing pipeline)
โโโ ๐ง transformer_minimax_remover.py (model architecture)
โโโ ๐ฆ requirements.txt (dependencies)
โโโ ๐ models/ (auto-downloaded models with descriptive names)
โ โโโ minimax_vae/ (VAE encoder/decoder)
โ โโโ minimax_transformer/ (main diffusion model)
โ โโโ minimax_scheduler/ (denoising scheduler)
โโโ ๐ Documentation/
โ โโโ AUTO_DOWNLOAD_GUIDE.md
โ โโโ TENSOR_DIMENSION_FIX_GUIDE.md
โ โโโ DW_PREPROCESSOR_COMPATIBILITY.md
โ โโโ INSTALLATION_GUIDE_OPENCV_FIX.md
โ โโโ OPENCV_FIX_SUMMARY.md
โโโ ๐ ๏ธ Scripts/
โโโ download_models.py
โโโ setup_comfyui_integration_bmo.py
โโโ fix_comfyui_diffusers.py
Option 2: ComfyUI Models Directory Structure (Alternative)
ComfyUI/
โโโ models/
โ โโโ checkpoints/ (Stable Diffusion models)
โ โโโ vae/ (Standard VAE models)
โ โโโ loras/ (LoRA models)
โ โโโ minimax_vae/ (๐ฏ MiniMax VAE - auto-downloaded here)
โ โโโ minimax_transformer/ (๐ฏ MiniMax Transformer - auto-downloaded here)
โ โโโ minimax_scheduler/ (๐ฏ MiniMax Scheduler - auto-downloaded here)
โโโ custom_nodes/
โโโ MiniMax-Remover/
โโโ ๐ README.md
โโโ ๐ง minimax_mask_node_bmo.py
โโโ ๐ง pipeline_minimax_remover_bmo.py
โโโ ๐ฆ requirements.txt
๐ก Tip: When the node runs, it will display the actual local paths where your models are found, so you'll know exactly which location is being used.
๐ Documentation
Complete Guides Available
AUTO_DOWNLOAD_GUIDE.md
- Model download and managementTENSOR_DIMENSION_FIX_GUIDE.md
- Resolution compatibility detailsDW_PREPROCESSOR_COMPATIBILITY.md
- DWPose integration guideINSTALLATION_GUIDE_OPENCV_FIX.md
- OpenCV issue resolutionOPENCV_FIX_SUMMARY.md
- Complete fix summary
Support Resources
- GitHub Issues: Report bugs and request features
- Documentation: Comprehensive guides for all features
- Community: Share workflows and tips
Before vs After
โ Old Experience
- Manual model download required (25GB)
- Resolution errors with non-standard sizes
- OpenCV conflicts breaking installations
- DW preprocessor incompatibility
- Complex setup and configuration
โ New Experience
- Plug-and-play: install and use immediately
- Works with ANY resolution automatically
- No OpenCV conflicts or reinstallations
- Perfect DW preprocessor compatibility
- Professional-quality results every time
๐ Links & Resources
Official Project
- Original Paper - Technical details and methodology
- Official Repository - Original implementation
- HuggingFace Models - Pre-trained models
- Demo Page - Live demonstrations
ComfyUI Integration
- ComfyUI - Main ComfyUI project
- ComfyUI Manager - Node management tool
๐ง Contact & Support
- Issues: GitHub Issues
- Email: [email protected]
- Documentation: All guides included in repository
๐ License
This project is licensed under the terms specified in the LICENSE file.
๐ Credits
Original Authors
Bojia Zi*, Weixuan Peng*, Xianbiao Qiโ , Jianan Wang, Shihao Zhao, Rong Xiao, Kam-Fai Wong
*Equal contribution. โ Corresponding author.
ComfyUI Integration & Enhancements
- Auto-download system implementation
- Universal resolution support
- OpenCV & DW preprocessor compatibility fixes
- Comprehensive documentation and guides
๐จ Happy Video Inpainting! โจ
Experience professional-quality video object removal with zero configuration required.