ComfyUI-LTX23-MotionCache

LTX-2.3 video workflows for ComfyUI, accelerated with a MotionCache-style sampling path.

This is a standalone ComfyUI custom node package. Its acceleration design is inspired by MAC-AutoML/MotionCache.git, with the implementation rebuilt for LTX-2.3, ComfyUI node types, LTX sampling flows and SamplerCustomAdvanced workflows.

It does not modify source code from other LTX node packages. Compatibility is based on ComfyUI type names and runtime object attributes:

• LTX_TRANSFORMER
• LTX_VIDEO_VAE_ENCODER
• LTX_VIDEO_VAE_DECODER
• LTX_SAMPLING_CONFIG
• Native ComfyUI MODEL pipeline

Features

• MotionCache-style denoising loop for LTX-2.3 modular sampling.
• Drop-in MODEL -> MODEL patch node for existing SamplerCustomAdvanced workflows.
• T2V, I2V, image conditioning, reference video, mask edit and optional audio path compatibility.
• Configurable warmup, refresh interval, motion threshold and update-ratio bounds.
• Optional reuse of CFG/STG deltas on non-refresh steps.
• Runtime stats output for quick speed/quality tuning.

Nodes

Ltx23MotionCache

Builds a LTX23_MOTION_CACHE_CONFIG object.

| Input | Default | Description | | --- | ---: | --- | | enabled | true | Enable or disable MotionCache behavior. | | warmup_steps | 2 | Full-update steps before cache reuse starts. | | refresh_interval | 3 | Force a full update every N steps. | | motion_threshold | 0.08 | Normalized token-difference threshold. | | min_update_ratio | 0.15 | Minimum active token update ratio. | | max_update_ratio | 0.85 | Maximum active token update ratio. | | cache_cfg_delta | true | Reuse CFG delta between refresh steps. | | cache_stg_delta | true | Reuse STG delta between refresh steps. | | log_stats | true | Return a text summary of cache statistics. |

Ltx23SampleVideoMotionCache

Sampler replacement for compatible LTX-2.3 modular workflows.

Inputs:

• transformer: LTX_TRANSFORMER
• vae_decoder: LTX_VIDEO_VAE_DECODER
• config: LTX_SAMPLING_CONFIG
• motion_cache: LTX23_MOTION_CACHE_CONFIG
• optional vae_encoder: LTX_VIDEO_VAE_ENCODER

Outputs:

• sampled_video: LTX_SAMPLED_VIDEO
• motioncache_stats: STRING

Use this node when your workflow already decodes LTX_SAMPLED_VIDEO later.

Ltx23GenerateVideoMotionCache

Runs generation and returns ComfyUI frames directly.

Outputs:

• frames: IMAGE
• audio: AUDIO
• motioncache_stats: STRING

Use this node when you want to connect generated frames directly to nodes such as VHS_VideoCombine.

Ltx23MotionCacheModelPatch

Patches an existing ComfyUI MODEL with native EasyCache-style wrappers.

Recommended connection:

LTX model / LoRA / NAG -> Ltx23MotionCacheModelPatch -> Guider / SamplerCustomAdvanced

This is the safest choice for workflows that already use MODEL -> GUIDER -> SamplerCustomAdvanced, because it does not replace the whole sampler.

Inputs:

| Input | Default | Description | | --- | ---: | --- | | model | required | ComfyUI MODEL object. | | reuse_threshold | 0.20 | EasyCache reuse threshold. Higher values reuse more aggressively. | | start_percent | 0.15 | Sampling progress where cache reuse can begin. | | end_percent | 0.95 | Sampling progress where cache reuse stops. | | subsample_factor | 8 | Subsampling factor used by the cache wrapper. | | verbose | false | Print cache debug details. |

Installation

Clone this repository into ComfyUI's custom_nodes directory:

cd ComfyUI/custom_nodes
git clone <your-repo-url> ComfyUI-LTX23-MotionCache

Restart ComfyUI after installation.

For local development inside an existing ComfyUI checkout, this folder can also be copied or symlinked to:

ComfyUI/custom_nodes/ComfyUI-LTX23-MotionCache

Runtime Requirements

This project does not bundle LTX-2.3 model loaders or model weights. It expects an existing ComfyUI environment with compatible LTX-2.3 nodes/runtime already installed.

The standalone sampler nodes need these imports at runtime:

• ltx_core
• ltx_trainer

If your LTX-2.3 source tree is not installed as Python packages, set LTX2_REPO_ROOT:

export LTX2_REPO_ROOT=/path/to/LTX-2

The path must contain:

packages/ltx-core/src
packages/ltx-trainer/src
packages/ltx-pipelines/src

The Ltx23MotionCacheModelPatch node uses ComfyUI's built-in EasyCache wrappers and works through the standard ComfyUI MODEL path.

Recommended Workflows

Sampler replacement path:

LTX config + Ltx23MotionCache -> Ltx23SampleVideoMotionCache -> LTX decode -> VHS_VideoCombine

Direct frame path:

LTX config + Ltx23MotionCache -> Ltx23GenerateVideoMotionCache -> VHS_VideoCombine

Existing advanced sampler path:

LTX model -> Ltx23MotionCacheModelPatch -> Guider -> SamplerCustomAdvanced -> Decode / VideoCombine

Included Workflow

This repository includes a ready-to-import ComfyUI workflow:

workflow/LTX-2.3-MotionCache.json

The included workflow demonstrates the Ltx23MotionCacheModelPatch path for existing MODEL -> Guider -> SamplerCustomAdvanced pipelines. Import it from the ComfyUI workflow loader, then adjust model filenames, image inputs, prompts, resolution, frame count and output settings to match your local environment.

The workflow may reference external LTX-2.3, video helper, upscaler or utility nodes that are not bundled in this repository. Missing node warnings in ComfyUI mean those dependencies need to be installed separately.

Starting Parameters

These values are conservative starting points:

warmup_steps: 2
refresh_interval: 3
motion_threshold: 0.08
min_update_ratio: 0.15
max_update_ratio: 0.85
cache_cfg_delta: true
cache_stg_delta: true

For higher speed, increase refresh_interval, increase motion_threshold, or lower max_update_ratio.

For higher fidelity, decrease refresh_interval, decrease motion_threshold, or raise min_update_ratio.

Implementation Notes

This is not a line-by-line port of the original MotionCache implementation. It is an LTX-2.3-oriented engineering adaptation:

1. It uses patchified latent denoised x0 differences as a motion proxy inside the denoising loop.
2. It reuses previous denoised x0 values for low-motion tokens.
3. It can reuse CFG/STG deltas between forced refresh steps.
4. It keeps reference, mask and image-conditioning branches aligned with LTX-2.3 modular sampler behavior.
5. The MODEL patch node delegates to ComfyUI native EasyCache wrappers.

Validation

From this directory:

python -m py_compile nodes.py __init__.py
python -m pytest -q

Release Checklist

• Update version in pyproject.toml and comfy-node.json.
• Replace <your-repo-url> in this README with the final GitHub URL.
• Keep generated caches such as __pycache__/ and .pytest_cache/ out of git.
• Test the included workflow and at least one existing SamplerCustomAdvanced workflow before tagging a release.