KeySync LipSync Advanced

KeySync LipSync Advanced is the plain LipSync node plus three extra fields, and the reason they exist is one of the ugliest real-world problems in lip sync: when something - a hand, a microphone, a coffee cup - passes in front of the face, a lip-sync model usually makes the mouth and the occluder fight, or worse, renders the object's motion wrong. KeySync's answer is an occlusion path built on SAM2 that masks out the blocking object and keeps it out of the regenerated mouth region. This is the node that exposes it.

Everything else is identical to the simple node: same keysync_model, images, audio, input_fps, compute_until inputs, same outputs (images, audio, frame_rate, output_video_path), same fixed 25 fps / 16 kHz normalization, same subprocess + log behavior. If you've got a clean clip, don't pay the Advanced tax - the three extra fields are genuinely fiddly.

The three extra inputs

• fix_occlusion (boolean, default false) - turns the SAM2-based occlusion handling on. Off by default for a reason: it adds a whole segmentation/tracking stage to an already slow pipeline.
• position (string, default "None") - a SAM2 point prompt as pixel coordinates, format x,y, e.g. "450,450". It tells the tracker where the occluding object is. This is the awkward part: it's a text field, so you're eyeballing coordinates off a frame, and they're resolution-dependent. The upstream docs suggest the object's location in the frame; if you leave it "None", you haven't actually pointed SAM2 at anything.
• start_frame (integer, default 0) - the frame index where that position applies. KeySync's authors say the first frame typically works best, so default 0 is usually right; you'd raise it only if the object appears partway through.

What it needs under the hood

The occlusion path only works if the upstream KeySync environment has SAM2 installed - that's the optional step in the official KeySync README (git clone https://github.com/facebookresearch/sam2 + pip install -e .). The wrapper won't install it for you, and it won't warn you either; it just passes --fix_occlusion True down to scripts/infer_raw.sh and hopes SAM2's there. The sam2.1_hiera_large.pt checkpoint should also be present in your model folder - it's part of the full ~24 GB download from the Download Models node, so if you manually pruned your checkpoints to just the two _dub.pt files to save bandwidth, this path will break in unhelpful ways.

How to actually use it

Run it once with occlusion off to confirm the clip itself is fine, then enable fix_occlusion, set position to real coordinates ("450,450" style, quoted), keep start_frame at 0, and re-run. Expect the run to take noticeably longer - SAM2's tracking work is on top of KeySync's two diffusion stages. If the result looks fine with occlusion off, leave it off; the whole point of hiding this from the simple node was that a point prompt typed into a text box is a fiddly way to do something simple.

One more thing worth knowing: this pack is Linux/WSL2 territory (it needs bash and a working python on PATH), and the same hardcoded D:/ComfyUI/... path defaults apply here as to every node in the pack. Get the Model Loader green first - it validates the repo and both required checkpoints before you ever reach for the SAM2 knobs.