TeaCache HunyuanVideo Sampler

HunyuanVideo is a genuinely big model - the 13B December 2024 original, or the smaller 1.5 rebuild - and every denoising step costs you a full pass through a multi-billion-parameter transformer. This node is the shortcut people actually use: it's a drop-in sampler that applies TeaCache, the temporal-caching trick from Alibaba's ali-vilab team, to HunyuanVideo. No new model, no LoRA, no distilled checkpoint. You swap one node in your existing native HunyuanVideo workflow, pick a speed level, and ComfyUI starts skipping the transformer passes that weren't going to change anything anyway. The README pitches it as a "seamless upgrade" for native workflows, and that's the honest description.

How it works

TeaCache is not distillation. A distilled model is trained to do fewer steps; TeaCache instead notices when two consecutive steps are operating on nearly identical latents and simply reuses the previous step's result instead of running the network again. The trick is deciding when - and that's the whole clever bit.

Dig into nodes.py and you can watch it: at each step the node computes only the cheap stuff - the modulation vector (time embedding plus text and guidance), then the first double block's normalization and modulation. It measures the relative L1 distance between that modulated input and the one from the previous step, feeds the distance through a polynomial rescaling function, and accumulates it. If the accumulated distance stays under a threshold, the transformer isn't called at all; the previous residual is returned as-is. When the distance finally crosses the line, the node runs the full transformer and resets the accumulator.

Those thresholds are the three speedup choices:

• Original (1x) - threshold 0.0. Never skips. Basically TeaCache disabled.
• Fast (1.6x) - threshold 0.1. The default.
• Faster (2.1x) - threshold 0.15. More aggressive skipping, more visible quality loss.

One honest caveat: those multiplier labels are the author's ballpark claims, not a benchmark. Real speedup depends on your step count and content - long videos with lots of similar frames skip more than short ones with constant motion. Also note the README's struck-through "only supports BF16" warning. It's crossed out because it was lifted, but this node was born in the BF16 era of HunyuanVideo, so if you're on a very old ComfyUI that predates the current loader stack, treat that as a hint about its age.

The inputs that matter

The five plumbing inputs are exactly the SamplerCustomAdvanced contract, so wiring is familiar: noise from RandomNoise, guider from BasicGuider (or FluxGuidance if you're using guidance embeddings), sampler from KSamplerSelect, sigmas from BasicScheduler, and latent_image from EmptyHunyuanLatentVideo. The repo's example_workflow.json shows precisely this chain.

The only TeaCache-specific input is speedup - the enum above. That's it; there's no threshold slider, no start_step, no knobs. Outputs are two LATENTs: output is the final denoised latent (wire it to VAEDecode), and denoised_output is the model's last-step clean prediction - handy if you want the x0 preview without a full extra pass.

Installing it

ComfyUI Manager, search ComfyUI-TeaCacheHunyuanVideo, install, restart. Or the manual route:

cd ComfyUI/custom_nodes
git clone https://github.com/facok/ComfyUI-TeaCacheHunyuanVideo

Then restart ComfyUI. There's no requirements.txt and no model download - it's pure torch + numpy monkeypatching over ComfyUI's native HunyuanVideo support. That's both the appeal and the risk.

Where people get burned

The failure mode worth knowing: these TeaCache-for-Hunyuan nodes work by reaching into guider.model_patcher.model.diffusion_model and wrapping its forward with a hand-written signature. When ComfyUI core changes HunyuanVideo's transformer signature, the wrappers break - the community's been hitting exactly this, with errors like teacache_hunyuanvideo_forward() got an unexpected keyword argument. This pack's wrapper accepts **kwargs, so it's more tolerant than some, but the class of problem is the same. If it errors after a ComfyUI update, update this node first.

Second: TeaCache trades quality for speed, and the skipped steps show up where you'd expect - motion and face consistency degrade first, a tradeoff the wider community has confirmed across Wan and Hunyuan packs alike. Start at Fast, save Faster for preview passes, and don't blame the node when your characters' faces drift. Also remember it's Hunyuan-specific: if you've moved on to Wan or LTX, this node does nothing for you.