🅛🅣🅧 MotionCache Config

This node does absolutely nothing by itself, and that's the point. Ltx23MotionCache is the config object for the whole pack - a bundle of settings you build once and feed into one of the two sampler nodes (Ltx23SampleVideoMotionCache or Ltx23GenerateVideoMotionCache). It doesn't load anything, doesn't sample anything, doesn't even touch the model. It's the dial, not the engine.

So why reach for it? Because it's where you trade quality for speed in a MotionCache-style LTX-2.3 workflow, and getting those knobs wrong is the difference between a clip that's 30% faster and one that looks like it was generated in a lava lamp.

How it works

The idea behind MotionCache (inspired by MAC-AutoML/MotionCache, rebuilt here for LTX-2.3) is that during denoising, most of the video's tokens barely change between steps. Why recompute them? The sampler reuses the previous step's denoised output for low-motion tokens, and reuses cached CFG/STG guidance deltas on the steps in between refreshes. This config node sets the rules for when that reuse happens and how aggressive it is. In the source it's a small dataclass - that's it. But the sampler reads it every step.

The inputs that matter

There are nine inputs and you will touch maybe four of them. The honest list:

• refresh_interval (default 3) - forces a full update every N steps. This is your main speed dial: smaller = safer and slower, larger = faster but riskier. Going below the defaults isn't where the speed is.
• motion_threshold (default 0.08) - how different a token's denoised output must be to count as "moving" and get updated. Raise it to reuse more aggressively; lower it to keep more tokens fresh.
• min_update_ratio / max_update_ratio (defaults 0.15 / 0.85) - the floor and ceiling on what fraction of tokens update each step. The floor is your safety net against the whole frame freezing; the ceiling stops the cache from collapsing to nothing.
• warmup_steps (default 2) - full-update steps at the start before any caching. Leave it alone until you know what you're doing.

The three toggles: enabled is the master switch for the token-level caching, and cache_cfg_delta / cache_stg_delta (both default true) control the bigger win - reusing the CFG and STG guidance deltas between refresh steps instead of recomputing them. One subtlety that has caught people out: enabled=false turns off the token reuse, but the delta toggles are independent. If you flip enabled off expecting fully vanilla sampling, the delta reuse is still active unless you also clear those two. log_stats (default true) just makes the sampler emit its stats string.

Output

One output, motion_cache (LTX23_MOTION_CACHE_CONFIG) - wire it into the motion_cache input of either sampler node. That's the whole job.

Installing and using it

It's part of starsFriday/ComfyUI-LTX23-MotionCache. Install via ComfyUI Manager (search "LTX23 MotionCache") or:

cd ComfyUI/custom_nodes
git clone https://github.com/starsFriday/ComfyUI-LTX23-MotionCache

Restart ComfyUI. Because this node is just a config dataclass, it's the one node in the pack with zero runtime dependencies - no ltx_core imports, no LTX2_REPO_ROOT needed. The sampler nodes it feeds are the ones with those requirements.

Tuning advice

The README's starting points (2 / 3 / 0.08 / 0.15 / 0.85) are genuinely conservative and worth starting from. For more speed: raise refresh_interval, raise motion_threshold, or lower max_update_ratio. For more fidelity: lower refresh_interval, lower motion_threshold, or raise min_update_ratio. Then read the motioncache_stats string on the sampler - if avg_update_ratio is hovering near the max, your cache is doing almost nothing and you can lean on it harder. If it's pinned at the bottom, back off before the video starts looking like a sequence of stills.