Zura · Load H3 Character References

This is the read half of the H3 reference cache. GenjSaveH3Conditioning encoded your character reference, control and performance audio into H3's conditioning and a paired video/audio latent and wrote them to disk; GenjLoadH3Conditioning ("Zura · Load H3 Character References") pulls them back so a new take starts at the sampler instead of re-running the reference encoder.

It's the boring half of a very good trick. On a 16 GB card where H3 reference encoding is a real chunk of the wall-clock time, going from "make a coffee" to "try a different seed" is the whole point.

What it does when you run it

Required: cache_key (STRING, default empty) - the 64-character hex key the save node returned. Optional: cache_digest (STRING, default empty) - a sha256 of the cache file, which Studio fills in when it builds the graph.

The load path, in order:

1. Reads output/genj/h3_conditioning/<key>.pt with torch.load(..., weights_only=True). That's not decoration: weights_only means a corrupted or swapped file cannot execute arbitrary pickle code, and the pack says so in a comment. Treat these as tensors, and treat anything else claiming to be one with suspicion.
2. If cache_digest is set, it hashes the file and compares. Mismatch gives H3 character references changed after this take was prepared. - the digest was captured when the graph was built, so this catches a cache file that got rewritten between planning and execution.
3. Validates the structure again on read, exactly as the save side did: H3 reference blocks at the right shapes, the paired nested latent, an even canvas, a frame count on the 5/17 grid, and an audio latent of round(frames / 24 × 40). If any of that fails, every failure mode collapses into one deliberate message: H3's saved character references are damaged, incompatible or changed. Generate this take again in Zura Studio to rebuild them. Your approved shot and character look are kept.
4. Returns positive (CONDITIONING) and the same latent (LATENT).

Where the outputs go

CONDITIONING replaces the guider's conditioning input, and the LATENT replaces the sampler's latent_image - or the input of the background-preserve / reference-audio-lock node when one of those is in the chain. In the pack's H3 graph the cache branch is swapped in by rewiring those two sockets and pruning the now-unreachable reference-encoding nodes out of the graph, which is why an exported cached graph looks much shorter than an uncached one. That's expected, not a broken export.

IS_CHANGED hashes the cache file on every run, so rewriting the file with the same key does re-trigger the dependent nodes instead of serving stale latents.

Install

ComfyUI Manager → search Zura Nodes → install → restart ComfyUI.

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

No models, no ffmpeg - but it only has anything to load if the H3 stack has already produced a cache, which means the transformer, text encoder, both VAEs and the control patch from INSTALL_STUDIO.md need to be installed and the take needs to have run at least once.

Gotchas

• Invalid H3 reference cache key. - the key isn't 64 lowercase hex characters. Studio's keys are sha256 digests; a hand-typed friendly name won't work.
• Deleting output/genj/h3_conditioning/. Clean and rebuildable, but it invalidates every saved key at once. If a graph then throws the "damaged, incompatible or changed" error, that's the truth, not a red herring.
• Assuming a stale cache is why the output changed. It isn't - the key covers the model stamps, the reviewed shot, the character and opening hashes, the prompt, resolution, audio and lip-sync setting. If any of those moved, you're on a different key and looking at a genuinely different encode.
• Mixing caches across projects. Two projects with the same character but different prompt or resolution will hold two different keys; there's no cross-project reuse, and that's deliberate. The recipe is the identity.