KeySync Model Loader

KeySync Model Loader has no inputs, does no math, and touches no GPU. It looks like a placeholder, and honestly it kind of is - but it's the most useful placeholder in this pack, because it's the node that tells you whether the hard part of the KeySync install actually worked.

KeySync is a real lip-sync model - the "leakage-free" two-stage diffusion approach from Imperial College (arXiv 2505.00497) that re-renders the mouth of an existing video to match new audio. This wrapper doesn't ship KeySync's weights or code; it shells out to the official repo. That means a lot has to be in the right place before any LipSync node can run. The loader is your check.

How it works

The node resolves two fixed paths and verifies both, then packages what it found:

• the official KeySync repo, which must be cloned inside the wrapper at custom_nodes/ComfyUI-Keysync-wrapper/keysync, with its scripts/infer_raw.sh present
• the model directory, models/keysync, with checkpoints/keyframe_dub.pt and checkpoints/interpolation_dub.pt

If everything's there, it returns a KEYSYNC_MODEL object - a little config bundle holding the repo path, model dir, both checkpoint paths, and the inference script. That handle is the only input the LipSync nodes need from it.

The errors are the feature

Run it green-first and you get three possible failures, each one telling you the exact fix:

KeySync repo path does not exist        → clone antonibigata/keysync into the wrapper folder
scripts/infer_raw.sh not found          → same thing; the clone is incomplete
keyframes_ckpt does not exist           → models aren't downloaded
interpolation_ckpt does not exist

You don't get friendly errors like this from the LipSync node, because by the time it runs, the repo is gone mid-pipeline. Loading first means failing on a dry run instead of after fifteen minutes of inference.

The gotcha: hardcoded Windows paths

Here's where people actually get burned. The wrapper checks fixed paths - D:/ComfyUI/custom_nodes/ComfyUI-Keysync-wrapper/keysync and D:/ComfyUI/models/keysync - and deliberately hides the path fields from the UI. On Linux or WSL2 the code maps D:/ to /mnt/d/, so it only works if your ComfyUI actually lives under /mnt/d/ComfyUI (i.e. a Windows drive mounted in WSL). On a pure-Linux box, every run fails with "KeySync repo path does not exist."

The fix is editing two constants at the top of custom_nodes/ComfyUI-Keysync-wrapper/nodes.py - DEFAULT_KEYSYNC_REPO_PATH and DEFAULT_MODELS_DIR - then restarting ComfyUI. It's a five-minute edit, no env var override exists, and it's the single most common reason this pack "doesn't work" for people not on the author's exact setup.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/magicwang1111/ComfyUI-Keysync-wrapper
cd ComfyUI-Keysync-wrapper
git clone https://github.com/antonibigata/keysync

Then restart ComfyUI. The wrapper's own requirements (opencv, moviepy, soundfile, huggingface_hub) are light, but the upstream KeySync repo needs its own conda environment - get that right first (see the LipSync article). The loader is the proof you did.