Zura · Load File-Backed Wan Motion

Nearly the same node as Zura · Load Wan Motion and Character - same single cache_key widget, same four outputs, same ZURA_FOOTAGE payload out. The difference is how it reads.

The class docstring says it exactly: "Exact file-backed preparation for the VIDEO-only streaming sampler." Instead of torch.load-ing a whole preparation file into RAM, it memory-maps it. That's the version you want when the shot is long enough that "load the preparation" means "all your RAM is gone before the sampler gets a turn."

Why streaming changes the loader

The sampler that pairs with this node is Zura · Wan Video Render, which writes video out to a file as it goes instead of accumulating an IMAGE batch in memory. That delivery route demands a preparation cache that can be read window by window, so the pair is deliberate: file-backed preparation in, file-backed delivery out, nothing holding the full clip in RAM.

Requirements follow from that. The provenance has to be intact - the payload must record torch_zip_mmap_float32 or torch_zip_readonly_windows_float32 storage, the right frame count and a 24 fps timeline, a 64-hex cache key and a matching SHA-256. Every tensor also has to be exact CPU float32, strided, with values in range, and the mask has to cover the full source timeline with at least some non-zero coverage. This is stricter than the standard loader on purpose: an mmap read is only safe if the file is genuinely the shape it claims, and a partially-validated memory-mapped tensor is a segfault waiting to happen rather than a Python exception.

There's a path check too - the resolved cache file must sit inside ComfyUI's output directory and be named <cache_key>.pt. A cache that lives outside the output folder is rejected as "Wan preparation cache leaves the Comfy output folder."

Outputs

footage (to the streamed sampler), character_view, width, height. Nothing else. It does no inference, touches no models, and the pack is explicit that preparing the shot is a separate, earlier step.

Install

It's in the pack, so:

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

Manager: Zura Nodes, publisher ZURAVFX, restart after. The mmap route reads standard torch.save archives with weights_only=True, so you don't need anything extra installed - but the file has to have been written by the bounded/streaming preparation path in the first place. A whole-shot cache from the non-streaming preparation will not satisfy the provenance check, and pretending otherwise is the kind of shortcut that ends with a 20-minute sampling run failing at the last decode.

Common issues

"Wan preparation is missing footage metadata" / "unsupported streaming cache version." You handed it a cache prepared before the streaming format existed, or by a different build. Re-run the bounded preparation and use the new key.

"Wan preparation cache leaves the Comfy output folder." Someone moved or symlinked the .pt out of output/genj/wan_conditioning/. Put it back where the pack expects; the containment check exists because mmapping an arbitrary path is a genuinely bad idea.

"Wan streaming requires a non-empty approved performer mask." The mask is all zeros across the sampled blocks. Nothing to replace, so nothing to stream.

"Restore the global soundtrack after streamed Wan delivery." This is the streamed sampler's error, not the loader's, but you'll meet it on the same graph: file-backed delivery refuses to carry a keep_audio payload. Put the original soundtrack back with the pack's soundtrack-restore node at the end instead of asking the render to carry it.

RAM is fine but you're out of VRAM. Different problem entirely. The mmap loader solves host memory, not device memory; a 16 GB card running Wan Animate 14B at 1080p is going to want careful sizing regardless of how the conditioning is loaded.