MediaPipe Face Composite Options

UC_MediaPipeFaceCompositeOptions is a settings node - it doesn't touch a single pixel itself. What it does is bundle six knobs into one little object that you feed into UC_MediaPipeFaceComposite, the face-compositing node that actually does the work. Same idea as an options struct in code: keep the main node clean, and let you tune the swap without a wall of sliders on every instance.

This pattern is worth understanding because it's how the pack keeps the composite node tidy. You wire this into the options input of the composite node, and if you don't bother, the composite node runs on sensible defaults (which match this node's defaults exactly). It only matters when you want the swap tuned - and for a face swap, you usually do.

What's on the node

All six inputs are required, so the node always hands back a complete options object, but only a few are worth your attention on a normal day:

• score_thresh (default 0.25) - minimum confidence for a face to count as a face. Lower it if faces are being missed, raise it if wrong things are being picked up. This is the first knob to turn when the node grabs the wrong face or nothing at all.
• target_warp_strength (default 1.0, range 0–2) - how hard the source face is warped to match the target's shape. 1.0 is the "fit it properly" default; below 1 keeps more of the source's natural geometry (less believable but more recognizable), above 1 pushes the warp further and can distort. The "face swap looks like a mask" complaint usually lives here.
• bbox_expansion (default 64) - how much extra room around the detected face box gets carried into the crop before warping. Too small and you clip hair/ears; too big and you pull in background that fights the warp.
• mask_expansion (default 0) - grows or shrinks the face mask itself after detection. Negative values trim the mask inward so less background sneaks into the swap.
• feather_radius (default 8) - softens the mask edge so the seam blends instead of slicing.
• warp_decay_radius (default 64) - how far from the face center the warp fades out, so the effect is strongest on the face and relaxes into the surrounding area instead of shearing the whole head.

Outputs

One output: UC_FACE_COMPOSITE_OPTIONS, which is the custom type the composite node consumes. Nothing else.

Installing it

It ships with the pack:

• ComfyUI Manager: search "ComfyUI-UtilsCollection".
• Or:

cd ComfyUI/custom_nodes
git clone https://github.com/silveroxides/ComfyUI-UtilsCollection

Restart ComfyUI. No models needed for this node itself - the models live on the composite node it feeds.

Gotchas

The settings only take effect if the options object actually reaches the composite node's options socket; disconnect the wire and you silently get defaults again, which can be confusing if you've tuned everything and "nothing changed." Also, bbox_expansion and mask_expansion are in pixels, not percentages, so their useful range depends on your image resolution - on a 512px crop, 64 pixels is a lot of headroom; at 4K it's almost nothing. There's no one right value, just "tune per resolution." If you're iterating on a swap and it never quite fits, this is the node to fiddle with - the composite node itself is deliberately boring.