WanVideo Control Embeds

This node builds the image-embeds object that feeds Wan's "Fun"-family control models - Alibaba PAI's Wan2.1-Fun and Wan2.2-Fun-Control checkpoints, the same lineage that later produced the Fun ControlNet unions for Z-Image and Flux 2. Those models can take a control video (or, via fun_ref_image, a reference image) and steer generation with it, and this node is where you wire a raw latent control signal into the embeds format the sampler expects, with control over which portion of the clip's timeline it actually applies to.

How it works

Feed it your control latents and it wraps them into a WANVIDIMAGE_EMBEDS object, scoped to a window of the generation defined by start_percent and end_percent. That windowing pattern shows up all over this ecosystem - LoRAs, ControlNets, and caching nodes alike often take a start/end percent range rather than applying uniformly - because different parts of the denoising schedule do different jobs. Early steps lay down composition and motion; late steps refine detail. Scoping your control signal to the right window means it influences the part of generation it's actually meant to influence, instead of fighting the model across the whole schedule.

The optional fun_ref_image input is specific to the Fun-Control model family: a reference image latent that anchors appearance (a face, an outfit, a scene) separately from the motion/structure control coming through latents. That mirrors the split Wan2.2-Fun-Control exposes elsewhere - first/last frame, a reference image, and a controlnet-style video, all as independent conditioning channels rather than one blended input.

The inputs and output that matter

latents (LATENT, required) - your control signal, already VAE-encoded to latent space. start_percent (default 0) and end_percent (default 1) - the window of the denoising schedule this control is active over, as a 0–1 fraction of total steps; leave them at the defaults for "the whole generation," narrow them if you only want control active for part of the clip. fun_ref_image (LATENT, optional) - a separate reference-image latent for appearance conditioning, when you're using a Fun-Control checkpoint that supports it.

Output is a single image_embeds (WANVIDIMAGE_EMBEDS), ready to hand to your Wan sampler alongside your text embeds and model.

How to install it

Via ComfyUI Manager, search WanVideoWrapper and install, or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/kijai/ComfyUI-WanVideoWrapper

then restart. This node itself needs no separate download, but it's only useful paired with a Fun-Control checkpoint - those are separate downloads from alibaba-pai on HuggingFace, distinct from the standard Wan T2V/I2V weights, and go in your usual Wan diffusion-model folder.

Common issues & troubleshooting

Control has no visible effect. Check start_percent/end_percent first - a badly scoped window (accidentally set to a sliver near the end of the schedule, for instance) will make control latents feel like they're doing nothing even though the node ran correctly.

You're not running a Fun-Control checkpoint. This node's output is specifically shaped for that model family. Feeding its embeds to a standard Wan T2V/I2V model, or to a VACE-based pipeline (Wan's other, more commonly used control route per the wider ecosystem), won't do what you expect - check which control path your loaded model actually supports before debugging this node.

Latents that don't match your source video's frame count or resolution are a common source of shape-mismatch errors here, same as anywhere latents get merged in this pack. Confirm whatever encoded latents came from is aligned with the rest of your pipeline before assuming the control node itself is at fault.