Facefusion_comfyui

FaceFusion ComfyUI (Unofficial)

Advanced face swapping for ComfyUI with local ONNX inference - no API required!

🚀 Quick Start

Installation

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

Restart ComfyUI. Nodes will appear under FaceFusion and FaceFusion API.

Basic Usage

1. Add "Load Image" nodes for source (face) and target (body) images
2. Add "FF: Advanced Swap Face (Image)" node
3. Connect images and set api_token to -1 (local mode - default)
4. Choose model: hyperswap_1c_256 (recommended)
5. Connect to "Preview Image" and run!

First run downloads models (~200MB), then everything runs locally.

---

📋 Main Nodes

Face Swapping

• SwapFaceImage - Basic image face swap
• AdvancedSwapFaceImage ⭐ - Full control with all options (recommended)
• AdvancedSwapFaceVideo - Video face swapping with parallel processing
• FaceSwapApplier - Swap specific detected faces

Detection & Tools

• FaceDetectorNode - Detect and analyze faces
• FaceDataVisualizer - Debug tool showing detected faces
• PixelBoostNode - Configure pixel boost settings

---

⚙️ Key Parameters

api_token

• -1 = Local inference (default) ✅ No internet required
• your_token = API mode (requires internet)

face_swapper_model

13 models available - All auto-download on first use:

• hyperswap_1c_256 ⭐ Recommended - best quality/speed
• hyperswap_1a_256, hyperswap_1b_256 - HyperSwap variants
• ghost_1_256, ghost_2_256, ghost_3_256 - Apache-2.0 license (commercial OK)
• hififace_unofficial_256 - High fidelity faces
• inswapper_128_fp16 ⚡ Fastest for RTX GPUs
• inswapper_128 - Standard InsightFace
• blendswap_256 - Good blending quality
• simswap_256, simswap_unofficial_512 - SimSwap variants
• uniface_256 - Uniform face handling

pixel_boost

• 256x256 - Fast, basic quality
• 512x512 ⭐ Recommended - good balance
• 768x768 - Better quality, slower
• 1024x1024 - Best quality, slowest

face_mask_blur

• 0.0-1.0 - Controls edge blending
• 0.3 ⭐ Default - natural blending

Face Mask Types (Multi-Select)

You can enable multiple mask types at once! Masks are combined to create precise face boundaries.

| Mask Type | Option | Description | |-----------|--------|-------------| | Box | use_box_mask ✅ | Rectangular mask with blur around face edges (default ON) | | Occlusion | use_occlusion_mask | Detects occlusions (hands, hair, objects covering face) - requires face_occluder_model | | Area | use_area_mask | Masks specific face areas using landmarks | | Region | use_region_mask | Semantic segmentation of face parts - requires face_parser_model |

face_mask_areas (for Area mask)

Comma-separated list of areas:

• upper-face - Forehead and upper face
• lower-face - Chin and jaw area
• mouth - Mouth region only
• Example: upper-face,lower-face,mouth (default - full face)

face_mask_regions (for Region mask)

Comma-separated list of regions:

• skin - Face skin only
• left-eyebrow, right-eyebrow - Eyebrows
• left-eye, right-eye - Eyes
• glasses - Glasses area
• nose - Nose
• mouth - Mouth area
• upper-lip, lower-lip - Lips
• Example: skin,nose,mouth,upper-lip,lower-lip (default)

face_mask_padding

Edge padding for box mask: top,right,bottom,left

• Example: 5,5,5,5 - 5% padding on all sides
• Default: 0,0,0,0

Recommended Mask Combinations

| Use Case | Masks | Notes | |----------|-------|-------| | Standard swap | Box only ✅ | Fast, good for most cases | | Hands/objects near face | Box + Occlusion | Preserves hands covering face | | Precise face boundary | Box + Region | Better edge handling with hair | | Mouth preservation | Box + Region (skin,nose) | Keeps original mouth | | Full quality | Box + Occlusion + Region | Best quality, slower |

face_selector_mode

• one - Single face (use face_position to select)
• many - All detected faces
• reference - Match faces similar to reference image

sort_order

• large-small ⭐ Biggest face first
• left-right, top-bottom - Spatial sorting
• best-worst - By detection confidence

---

🎯 Example Workflows

Simple Swap

Source Image → Advanced Swap Face ← Target Image → Preview
             (api_token: -1)

Batch Processing (Multiple Images)

Source Image → Advanced Swap Face ← Load Image Batch → Preview
             (automatically processes all)

With Face Detection

Target → Face Detector → Visualize (debug)
              ↓
Source → Face Swap Applier → Preview

Video Swap

Source Image → Advanced Swap Video ← Target Video
             (max_workers: 8)
                    ↓
               Save Video

Smart Batch Handling

All image swapper nodes automatically detect and handle:

• ✅ Single image (shape: [1, H, W, 3])
• ✅ Batch of images (shape: [N, H, W, 3])
• ✅ Image lists from Load Image Batch nodes
• ✅ Returns same format as input

Example: Feed 10 images → Get 10 swapped images back!

---

🔧 Common Settings

For Speed

• Model: inswapper_128_fp16
• Pixel Boost: 256x256 or 512x512
• GPU with CUDA enabled

For Quality

• Model: hyperswap_1c_256 or simswap_unofficial_512
• Pixel Boost: 768x768 or 1024x1024
• Blur: 0.3-0.5

For Video

• Model: hyperswap_1c_256
• Pixel Boost: 512x512
• Max Workers: 4-8

---

🛠️ Troubleshooting

No Faces Detected

• Lower score_threshold to 0.3-0.4
• Check image quality and lighting
• Ensure face is clearly visible

Out of Memory

• Lower pixel_boost (256×256 or 512×512)
• Use smaller model (inswapper_128_fp16)
• Process fewer faces (mode='one')

Slow Performance

• Enable GPU/CUDA
• Use faster model (inswapper_128_fp16)
• Lower pixel boost resolution

Models Won't Download

• Check internet connection
• Verify disk space (~500MB per model)
• Manual download: https://github.com/facefusion/facefusion-assets/releases/

---

📦 Models

Models auto-download to: custom_nodes/Facefusion_comfyui/models/

Available models (~100-500MB each):

• hyperswap_1a/1b/1c_256
• inswapper_128, inswapper_128_fp16
• blendswap_256, simswap_256, simswap_unofficial_512
• uniface_256

Face detection: scrfd_2.5g (~3MB), arcface_w600k_r50 (~166MB)

---

🎓 Tips

• Start with defaults - They work well for most cases
• Use local mode (api_token: -1) - It's faster and private
• GPU makes a huge difference - 10-50× faster than CPU
• Adjust blur - Higher values (0.4-0.6) for smoother blending
• Match angles - Source and target faces should face similar directions
• Batch processing - Feed multiple images at once, get all results automatically
• Use Load Image Batch - Perfect for processing folders of images

Mask Selection Tips

• Hands near face? → Enable use_occlusion_mask with face_occluder_model: xseg_1
• Hair blending issues? → Enable use_region_mask with face_parser_model: bisenet_resnet_34
• Want original mouth? → Use Region mask with face_mask_regions: skin,nose,left-eye,right-eye
• Processing speed priority? → Use only Box mask (default)

---

📝 Local vs API

| Feature | Local (api_token: -1) | API (with token) | |---------|----------------------|------------------| | Internet | Not required | Required | | Speed | Fast with GPU | Depends on connection | | Privacy | Complete | Processed remotely | | Cost | Free | May have limits/costs | | Quality | Full pixel boost | Limited options |

Recommendation: Use local mode (default) for best results!

---

🔗 Links

• FaceFusion: https://github.com/facefusion/facefusion
• Models: https://github.com/facefusion/facefusion-assets/releases/
• API: https://facefusion.io (optional)

---

📄 License

Respect model licenses:

• InsightFace models: Non-commercial use
• Face swapper models: Check vendor licenses

---

🆘 Support

• Report issues on GitHub
• Check console output for errors
• Enable debug mode by uncommenting print statements in code

---

Happy Face Swapping! 🎭✨