KeySync Download Models

KeySync Download Models is a single boolean wearing a trench coat. Set download to true, run it, and it pulls the official KeySync weights from Hugging Face into your models/keysync folder using huggingface_hub's snapshot_download. When it's done it hands you the models_dir path as a string - which, to be honest, you mostly ignore. The node exists so a broken model install can fix itself from inside the graph instead of you fighting with Git LFS in a terminal.

The catch: it's a 24 GB download

This is the thing to know before you click. The node doesn't grab just the two checkpoints the wrapper actually needs - it downloads everything in the checkpoints/ folder of toninio19/keysync:

keyframe_dub.pt         ~6.4 GB   ← required
interpolation_dub.pt    ~6.4 GB   ← required
svd_no_emb.safetensors  ~9.6 GB   ← extra
sam2.1_hiera_large.pt   ~0.9 GB   ← occlusion (SAM2) support
vsr_trlrs2lrs3vox2avsp… ~1.0 GB   ← extra
WavLM-Base+.pt          ~0.4 GB   ← audio encoder for the pipeline

Roughly 24 GB total, and KeySync's full pipeline does use several of those extras - WavLM feeds the audio embeddings and SAM2 drives the occlusion path - so it's not pure waste. But if you only want the basic LipSync node and never plan to touch occlusion, you can place just the two _dub.pt checkpoints manually and skip ~11 GB. The node will happily accept that; only the two are required.

What it actually does

With download = false (the default) it does nothing but validate: if models/keysync is missing you get a "models_dir does not exist" error telling you to either flip download to true or grab the files manually. If the two required checkpoints are missing, it names them precisely. So like the Model Loader, it's half downloader, half health check.

The manual equivalent, if you'd rather not burn 24 GB through ComfyUI's queue:

git lfs install
git clone https://huggingface.co/toninio19/keysync D:/ComfyUI/models/keysync

That lands the same files in the same place. It also has the same hardcoded-path quirk as the rest of the pack - the models folder is D:/ComfyUI/models/keysync, which maps to /mnt/d/ComfyUI/models/keysync on Linux/WSL2. On a plain Linux box, edit DEFAULT_MODELS_DIR in nodes.py before you run this, or it will download 24 GB to a path nobody's looking at.

When to reach for it

After you've cloned the official KeySync repo and the wrapper, this is the smoothest way to finish the model half of the install. Run it once, let the queue sit for a while, then wire the Model Loader in. Don't run it per-workflow - a 24 GB pull isn't something you want to retrigger by accidentally leaving download true in a saved workflow.