Zura · Cache Wan Motion and Character

ZuraWanSavePreparation is plumbing, and it's worth understanding anyway, because it's where most of the pack's "why is this slow" story is decided. Its display name is Zura · Cache Wan Motion and Character, and that's literal: you hand it a driving performance you've already approved, it validates the whole thing on the CPU, writes it to a single .pt file, and hands back a cache key string. Nothing here touches the GPU or calls a model.

Why the pack does it this way

Wan 2.2 Animate workflows are expensive in two currencies. The preprocessing side - pose and face detection, drawing a ViTPose skeleton for every frame - is ONNX and Python work that runs on CPU. The sampling side is a 14B model that will take your whole 16 GB. The pack's docstring says the quiet part out loud: these adapters cache their CPU outputs before the diffusion model is loaded, because you don't want a pose pass sitting in VRAM next to a Wan Animate UNet.

So this node is the checkpoint in between: the one Studio writes for you when you open the Wan motion stage (More controls > Open in graph view, or Edit motion from the section controls). You rarely place it by hand - but if you're editing that graph, this is the wire that carries your approved take forward.

What it validates before it writes anything

This is the good part, and the reason a bad take fails here rather than eleven minutes into sampling:

• The mask has to match the frames exactly - same frame count, height and width - and be a real mask: values in [0,1] with at least one pixel above 0.5. An all-black mask throws instead of quietly producing a "replace nothing" render.
• Pose and face must cover every selected frame, not a sample of them, and every tensor must be finite.
• The reference must be exactly one image - batch size 1, or Wan requires one isolated character view.

Then it writes output/genj/wan_conditioning/<cache_key>.pt atomically, so an interrupted save can't leave a half-written cache.

The inputs you actually care about

frames, mask, pose, face and reference are wiring, not thinking: the native preprocessing outputs (PoseAndFaceDetection and DrawViTPose from ComfyUI-WanAnimatePreprocess), your approved mask, and a plain LoadImage. Two fields need a decision:

• cache_key - a 64-character hex SHA-256. Studio generates it; if you're hand-wiring, take it from the section controls rather than typing one. Anything that isn't 64 hex characters gets you Invalid Wan preparation cache key.
• scope - person or head, mapping onto the pack's mask vocabulary (Whole character / Whole head). It has to agree with the mask you actually approved.

The optional speech_guide_key and speech_guide_sha strings are for the speech route. Leave both empty for normal motion transfer. Fill them in and you bind this cached motion to a specific verified speech performance, which is what lets the speech guard later prove the face motion belongs to the audio you're about to render. Supply one without the other, or anything that isn't a 64-hex digest, and it refuses with Prepare a verified native speech guide before caching its face motion.

The output is a single STRING: the cache key, unchanged. It's an output node, so it runs even when nothing downstream consumes it - which is how you can prepare a section and come back later. That string is what ZuraWanLoadPreparation takes.

Install

Manager → search Zura Nodes (publisher ZURAVFX) → install → restart. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/ZURAVFX/ComfyUI_zura_nodes
python -m pip install -r ComfyUI_zura_nodes/requirements.txt

That file is heavier than the README's summary implies - it pulls requests, yt-dlp[default], ultralytics, face-alignment==1.4.1 (pinned; don't let anything upgrade it), soundfile, av, aiohttp and Pillow into ComfyUI's own Python.

For the pose and face inputs you also need ComfyUI-WanAnimatePreprocess (PoseAndFaceDetection, DrawViTPose), detection/vitpose-l-wholebody.onnx and detection/yolov10m.onnx in your model folders, and ffmpeg/ffprobe on PATH.

Where people get burned

The surprise is memory on the other side. This node stores the whole take as CPU float tensors - frames, mask, pose and face batches - so a long 1080p clip eats system RAM before the GPU is involved. That's why the pack splits long takes into bounded sections (max 81 frames per part, 41 at 1920) instead of caching one giant file, and why feeling that pain is your cue to use ZuraWanSavePreparationPart per window.

Also: because validation happens at save time, a mismatched mask or a stale key fails here, in a message that names the wrong input.

One caveat: this pack has no community footprint - searching for "Zura Nodes" or "ZURAVFX" turns up nothing - so there's no forum thread for an odd error. The repo docs and these messages are the documentation.