Decode Cache Helper

Every H3 Continuum chunked run spends real time on VAE decoding: H3's video and audio latents both have to be decoded before Finalize can assemble anything. The Decode Cache Helper sits between Sampler and Finalize and remembers decoded results, so that time isn't paid twice for the same latent.

The part the README leads with: this is not an unconditional generation speedup. It doesn't accelerate sampling by a single step. Generate a fresh random seed every run and you'll miss every run, pay hashing overhead you didn't have before, and possibly finish slower than if you'd never installed it.

How it works

On every entry it builds a content key from the latent: which stream it is (video or audio), dtype, shape and a byte-level digest, the latent's metadata (sample rate included), your reset_token, and a VAE identity signature. That signature isn't a model-file hash - it's structural: patcher version, the identity of the decode callables, VAE config, per-parameter version counters, torch flags. If the VAE can't be confidently fingerprinted (custom wrappers, hooks, object patches), it doesn't guess: it reports bypass and delegates to the native decoder.

A miss isn't a different decode path - it's ComfyUI's own VAEDecode (or the audio equivalent) under the hood, so the worst case is the stock decode plus a little bookkeeping.

Auto sends full video decodes to a private, process-local disk cache (overridable via the H3_DECODE_CACHE_TEMP_DIR env var) and keeps small audio decodes in bounded RAM. RAM mode never writes a cache file; Off clears the cache and delegates everything.

One mechanism explains a behaviour that looks wrong at first: IS_CHANGED returns float("NaN"), the standard trick for forcing a node to execute on every queue. So ComfyUI's own execution cache never skips this node - the content cache inside it is what saves your time. Which is exactly why it helps where a normal re-run doesn't: change something upstream and ComfyUI's cache is invalidated even though the latents are byte-identical.

The inputs and outputs

Required, and you'll mostly leave them alone:

• cache_mode - Auto, RAM, Off. Auto is the shipped default.
• ram_budget_mb (default 256) - additional private RAM retention, not total process memory. Tooltip: "Low headroom disables RAM retention."
• disk_budget_gb (default 8) - process-local quota. Set 0 for no cache file writes.
• reset_token (default 0) - bump it to discard this helper's cache.

Optional wiring:

• video_samples ← the Sampler's video_latents, with video_vae ← the same native Video VAE you'd give Core's decode.
• audio_samples ← the Sampler's audio_latents, with audio_vae ← the native Audio VAE (only needed if you connected audio samples).

Outputs: images and audio (both lists, one entry per physical group) go to Finalize's images and audio. report is a text diagnostic that tells you hit, miss, off or bypass - read it, don't wire it. Keep the Sampler's assembly_plan connected straight to Finalize, not through this node.

When it pays, and when it doesn't

It pays when unchanged latents get decoded again: adding chunks to a completed sequence, re-decoding retained chunks on Complete/Resume, regenerating part of a run, or retrying from decode onward after changing Finalize settings. The README's own numbers - ~24.5% less full-run total in one three-hit configuration, an A/B pair at ~26%, two Complete/Resume pairs averaging ~80% - are narrow observations the author explicitly refuses to sell as a universal "20% faster." And it does nothing for a re-watch of an already saved file.

Installing it, and the migration trap

It now ships inside the pack (it used to be a separate addon). Same install as everything else:

cd ComfyUI/custom_nodes
git clone https://github.com/ukr8b3g-cmyk/ComfyUI-H3-Continuum.git

Restart, then keep only one provider of the H3DecodeCacheHelper node ID - disable or remove the old standalone addon after confirming the built-in one loads. No extra pip dependencies; the pack declares none.

Where people get burned

Deleting the node doesn't rewire anything. The official V3.8X2 workflow contains no Core VAE Decode nodes at all. Pull the Helper out and you've got two dangling cables and nothing decoding - you have to add Core Video/Audio Decode back and reconnect Finalize.

The cache dies with the process. It's process-local and never survives a Python restart. Two ComfyUI instances don't share it either.

Changing settings wipes it. Mode, RAM budget, disk budget and reset_token are compared as a group; touch any of them and this helper's cache is cleared. That's why the shipped workflow pins Auto / 256 / 8 / 0, and why the frontend's Clear cache button (キャッシュをクリア in the Japanese UI) works by bumping reset_token. It discards on the next Queue, not immediately, and doesn't queue for you; API workflows and non-JavaScript frontends just edit the integer.

Cache failures fail open; OOM doesn't. A read or write error logs a warning and falls back to the native decoder, but an out-of-memory error or an interrupted queue is never retried - so in the log, a cache problem and a VRAM problem can look alike.