FF: Advanced Swap Face (Image)

If SwapFaceImage is the "just do it" node, this is the one where every decision that node made silently for you gets turned into a field you can touch. The pack's own README marks it with a star and calls it "Full control with all options (recommended)" - and once you've fought a plain swap node's default choices for ten minutes, you'll see why. This is the node most people should actually be using for anything beyond a one-off test.

How it works

Same core pipeline as the basic node - detect the source face, embed it, detect the target face, run a swapper model, blend the result back in - but every stage of that pipeline is now a parameter instead of a hard-coded default. The two things that make the real difference are face selection (which face gets swapped, when there's more than one in frame) and masking (how the swapped region blends into the rest of the image).

Selection has three modes: one (pick a single face by position, sorted by sort_order), many (swap every detected face), or reference (feed a reference_image and it matches faces similar to it, using reference_face_distance to control how strict the match is - lower is stricter, higher pulls in more matches). Reference mode is the one to reach for whenever positional sorting isn't reliable, which is most photos with more than one person in them.

Masking is a build-your-own system - you can enable more than one mask type at once and they combine:

• Box (use_box_mask, on by default) - a rectangular mask with blurred edges. Fast, fine for most single-face swaps.
• Occlusion (use_occlusion_mask) - detects things covering the face (hands, hair, objects) so they don't get swapped over. Needs face_occluder_model set to something other than none.
• Area (use_area_mask) - masks by facial region using landmarks, controlled by the face_mask_areas string.
• Region (use_region_mask) - semantic segmentation of face parts (skin, eyes, lips, and so on), controlled by face_mask_regions. Best for tricky hairlines.

Inputs a beginner actually sets

• face_swapper_model (default hyperswap_1c_256, 13 choices) and pixel_boost (default 512x512, 4 choices) - the quality/speed knobs. 512x512 is the pack's own recommended middle ground; drop to 256x256 if you're memory-constrained, push to 1024x1024 for stills where quality matters more than time.
• face_selector_mode + either (face_position, sort_order) or (reference_image, reference_face_distance) - how the right face gets picked.
• score_threshold (default 0.3) - lower it toward 0.1–0.2 if faces aren't being detected on a dim or angled photo.
• The four use_*_mask toggles above.

Everything else - face_mask_blur, the face_mask_areas/face_mask_regions/face_mask_padding strings, face_occluder_model, face_parser_model - ships with sensible defaults and is worth touching only once the basics are working. Output is a single IMAGE.

Worth knowing before you build a product on top of this: the swapper models here, inswapper in particular, trace back to InsightFace's face-swap pipeline, and InsightFace licenses those specific weights for non-commercial research only. Doesn't affect personal or hobby use at all - just something to check before selling anything built on it.

Installing it

ComfyUI Manager: search Facefusion_comfyui, install, restart. Manually:

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

Full restart required - a browser refresh won't pick up new nodes. First run downloads whichever swapper, occluder, and parser models you've selected into custom_nodes/Facefusion_comfyui/models/.

Common issues

Hands or objects near the face get swapped too. Enable use_occlusion_mask with face_occluder_model: xseg_1. This is directly from the author's own advice when someone asked about exactly this on the pack's launch thread.

Hair or hairline blending looks off. Enable use_region_mask with bisenet_resnet_34 - region masking handles hair-adjacent skin far better than a plain box.

Wrong face gets swapped in a multi-person photo. Switch face_selector_mode to reference and feed a clear crop of the person you want as reference_image. Positional sorting (large-small, left-right, etc.) is a coin flip once faces are similar in size.

Out of memory. Drop pixel_boost to 256x256 or 512x512, or switch to inswapper_128_fp16, which is the lightest model on the list.

Install issues (missing nodes, ONNX load failures). Make sure pip install -r requirements.txt ran inside ComfyUI's actual Python (portable installs need python_embeded's pip), then fully restart. A model that won't load is almost always a partial or locked download - delete it under custom_nodes/Facefusion_comfyui/models/ and let it re-fetch.