WanVideo Add Lynx Embeds

Lynx is ByteDance's identity-preservation adapter for Wan - high-fidelity personalized video from a single face image, built on the Wan 2.1 DiT. Think of it as the video equivalent of what PuLID/InstantID do for stills: feed it one photo of a person and it keeps that face across the whole generated clip. This node is the business end of the Lynx pipeline in the WanVideoWrapper. It takes the identity and reference signals Lynx produces and injects them into your image-embeds bundle, with separate strength dials for the two things Lynx tracks: identity and reference detail.

Under the hood Lynx uses two adapters - an ID-adapter that turns an ArcFace face embedding into compact identity tokens, and a Ref-adapter that injects fine-grained detail from the reference image. This node exposes both as scales, which is why it has an ip_scale and a ref_scale.

How it works

The identity path (from a cropped face) and the reference path (from the fuller reference) get folded into the WANVIDIMAGE_EMBEDS object the sampler uses. During denoising, Wan is steered to reproduce that identity. ip_scale governs how hard the ArcFace identity is pushed; ref_scale governs how much of the reference's finer detail comes along. You balance the two so you get the right person without over-copying the reference pose or lighting.

The inputs and outputs that matter

• embeds (WANVIDIMAGE_EMBEDS, required) - the bundle you're adding Lynx conditioning to.
• ip_scale (default 1) - identity strength. This is the main "make it look like them" knob. Too low and the face drifts; too high and every frame stiffens toward the reference.
• ref_scale (default 1) - reference-detail strength. Controls how much fine appearance detail rides along with the identity.
• lynx_cfg_scale (default 1) - guidance specific to the Lynx conditioning.
• start_percent / end_percent (0 / 1) - the denoise window Lynx is active over.

The optional inputs are where the pipeline actually connects: lynx_ip_embeds (LYNXIP, the processed identity embeds from the resampler), ref_image (IMAGE), ref_text_embed (WANVIDEOTEXTEMBEDS), vae (WANVAE), and ref_blocks_to_use (which transformer blocks the reference injects into). Output is the updated image_embeds.

How to install it

Ships in the WanVideoWrapper. ComfyUI Manager: search ComfyUI-WanVideoWrapper, install, restart. Manual:

cd ComfyUI/custom_nodes
git clone https://github.com/kijai/ComfyUI-WanVideoWrapper
pip install -r ComfyUI-WanVideoWrapper/requirements.txt

then restart. Lynx is a multi-part setup: you need the Lynx weights (including the resampler, loaded via LoadLynxResampler) and a working InsightFace install for the ArcFace face embedding - InsightFace is the notoriously fiddly dependency behind nearly every identity tool, so if the face crop step fails, that's usually why. This node is the last stage; it expects LynxInsightFaceCrop and LoadLynxResampler feeding it.

Common issues & troubleshooting

Face isn't holding. Raise ip_scale. And check the crop - Lynx keys off a clean, front-ish face; a bad crop from LynxInsightFaceCrop starves the identity path.

Output looks frozen or pose-locked. ref_scale (or ip_scale) too high - you're copying the reference too hard. Ease them down so the model has room to actually animate.

Nothing plugs in. This node is stage three of a chain. Without lynx_ip_embeds from the resampler and a face from the crop node, it has nothing to inject. Wire the full Lynx pipeline, not just this node.