Masking & compositing

Swap the face, keep everything else

The swapper only touches the mask region. How that mask is computed - a box, an occlusion-aware cutout, or a fine per-feature map - decides whether the swap looks glued on or genuinely blends with the frame.

The three mask types

box

A simple rectangle around the detected/landmarked face. Fast, but includes background inside the box.

occlusion

Uses segmentation to carve out objects that occlude the face (hands, glasses, hair). The go-to for preserving hands/objects covering the face.

region

A fine per-feature mask (eyes, brows, lips, nose, hair, neck, ...) from a 19-class segmentation, so you can keep or exclude specific features.

Preserving hands, glasses & hair: use occlusion masking. It runs a segmentation model that carves out whatever sits in front of the face - hands, glasses, strands of hair - so the swap doesn't smear across them. The region mask goes further and lets you keep or drop specific features (eyes, lips, nose, hair, neck).

Feathering the edge

--face-mask-blur blurs the mask, so the swap dissolves into the surrounding skin instead of ending at a hard line.

--face-mask-blur

0 - 100 (version-dependent default)

Feathers the mask edge so the swap blends instead of showing a hard boundary.

Padding - expand or contract

--face-mask-padding takes four values (top right bottom left (px)) and resizes the mask by pixels.

Positive padding

expand

Enlarges the swap region - useful to cover the jawline and hairline that a tight mask misses.

Negative padding

contract

Shrinks the swap region - pulls the edit back under hair or a chin so it doesn't spill onto the neck.

Per-feature region mask

When using the region mask type, --face-mask-regions selects which segmentation classes are included (comma-separated):

skin, left_eyebrow, right_eyebrow, left_eye, right_eye, eye_glasses, inner_lip, mouth, upper_lip, lower_lip, nose, hair, neck, clothes, ...

Masking example

occlusion mask, feathered & slightly contractedbash

ff-run \
  --processors face_swapper,face_enhancer \
  --face-mask-types occlusion \
  --face-mask-blur 0.5 \
  --face-mask-padding -5 -5 -10 -5 \
  --source <source> --target <target> --output <out>

Padding values here are illustrative. Positive expands, negative contracts - dial them per clip, and preview the result with face_debugger to confirm the hair and hands are actually excluded.

face_masker.py