ComfyUI-MiniMax-H3-MotionCache Introduction
ComfyUI-MiniMax-H3-MotionCache is a set of two independent ComfyUI nodes for MiniMax H3 video workflows:
- MiniMax H3 MotionCache can reduce the number of expensive model calculations during generation. It reuses a previous result when the estimated change in the video and audio data is small enough.
- MiniMax H3 Fast VAE Decode experiments with decoding several video tiles together. Despite its name, it is not guaranteed to be faster than ComfyUI’s standard
VAEDecodenode.
You can use either node on its own or include both in a workflow. MotionCache is an independent adaptation inspired by the MotionCache research and reference code; it is not an official MAC-AutoML or MiniMax implementation.
The extension is intended for workflows that already use a MiniMax H3 diffusion model and video VAE in ComfyUI. It does not provide or download those models, and it makes no network requests.
How ComfyUI-MiniMax-H3-MotionCache Works
Video generation takes a series of steps to turn an initial, noisy representation into finished frames and audio. Think of each step as asking the model to refine a draft. MotionCache watches how much that draft appears to change. After a short warm-up, it can reuse a previous model result when its motion-aware estimate says the change is small. When the change is too large, it asks the model to calculate a fresh result.
This reuse is an approximation: it saves some model calls, but a reused result may miss a detail the model would otherwise have calculated. Moving edges, faces, hands, fast camera moves, lip sync, and synchronized sound deserve particular attention when you review the output.
The Fast VAE Decode node handles a different stage. After generation, the video VAE converts the video’s internal representation into viewable image frames. H3 decodes the video in temporal chunks and spatial tiles, then blends the tiles together. This node groups multiple horizontal tiles into a GPU batch while preserving that chunking and blending process. Grouping tiles means fewer decoder invocations, but it does not remove most of the decoding work. Whether it saves time depends on your GPU and workflow.
ComfyUI-MiniMax-H3-MotionCache Features
Motion-aware reuse during sampling
Place MotionCache after the H3 model loader or attention patch and before the sampler:
MiniMax H3 model → MiniMax H3 MotionCache → sampler
The defaults are a sensible first test. Run the same workflow once with MotionCache and once with the node bypassed, then compare both the time taken and the details that matter to your project.
| Setting | Default | What it changes |
|---|---|---|
reuse_threshold | 0.15 | How much estimated change is allowed before a fresh calculation is needed. A higher value permits more reuse but can introduce more visible or audible errors. Lower it when details become unstable. |
motion_strength | 1.0 | How strongly moving regions influence the reuse decision. It helps the decision account for motion rather than treating every area alike. |
warmup_steps | 4 | The number of initial model calls that are always calculated. Reuse begins only after this warm-up. |
max_consecutive_skips | 2 | The most calls that can be reused in a row before a fresh call is required. |
start_percent | 0.15 | Where in the sampling process MotionCache may begin operating. |
end_percent | 0.95 | Where in the sampling process MotionCache stops operating. |
subsample_factor | 8 | Controls the subsampling used to estimate change. |
verbose | false | When enabled, logs each calculated and reused model call for closer inspection. |
For example, if a character’s face changes unexpectedly between frames, try a lower reuse_threshold and compare again with MotionCache bypassed. If your priority is testing how often reuse occurs, turn on verbose and inspect the log. The reported speedup concerns model calls, not necessarily the time taken by the entire workflow.
Batched video decoding
Use MiniMax H3 Fast VAE Decode in place of standard VAEDecode when decoding with the MiniMax H3 video VAE:
H3 video latent ─┐
├→ MiniMax H3 Fast VAE Decode → IMAGE frames
H3 video VAE ────┘
| Input | Default | What it does |
|---|---|---|
samples | — | Receives a MiniMax H3 video latent, or the video portion of a joint latent. |
vae | — | Receives the MiniMax H3 video VAE. |
tile_batch_size | 4 | Sets how many horizontal spatial tiles are decoded per GPU batch; accepts values from 1 to 8. |
Larger batches can use more VRAM and are not necessarily quicker. If batched decoding runs out of memory, the node clears its temporary cache and retries with batch size 1. The registered node ID is MiniMaxH3FastVAEDecode.
What the reported numbers mean
In one 20-step H3 denoising example, MotionCache calculated 14 model calls and reused 6. That is 30% fewer denoiser calls and an estimated 1.43× speedup for that part of the process, not a measured 1.43× speedup for the full video workflow.
In a separate test at 1344×768, batching four VAE tiles reduced 28 serial tile invocations per temporal chunk to 8 batched invocations. Even so, a same-setting five-second decode took 11.15 seconds with the batched node versus 10.36 seconds with standard VAEDecode; both reported 1.34 GB. For that tested case, standard VAEDecode is the better choice.
Your results may differ. For a useful comparison, keep the model, prompt, seed, resolution, frame count, sampler, data type, VRAM mode, and GPU the same.
ComfyUI-MiniMax-H3-MotionCache Models
This extension does not include additional model variants. Its two nodes work with different parts of an existing MiniMax H3 setup:
- MiniMax H3 MotionCache accepts MiniMax H3 diffusion models only. It affects the sampling calculations used to generate the video and audio representation.
- MiniMax H3 Fast VAE Decode accepts the MiniMax H3 video VAE only. It converts the generated video representation into image frames.
Neither node is a replacement for the H3 model or video VAE. If you want a reference result without MotionCache’s approximation, bypass MotionCache and decode with standard VAEDecode.
Troubleshooting ComfyUI-MiniMax-H3-MotionCache
Faces, hands, motion, or audio details look unstable
- Run the same workflow with MotionCache bypassed to establish a reference.
- If the issue appears only with MotionCache, lower
reuse_thresholdfrom its default of0.15. - Review the areas most sensitive to reuse: motion boundaries, faces, hands, fast camera movement, lip sync, and synchronized sound.
- If you need the unapproximated model result, leave MotionCache bypassed.
Fast VAE Decode is slower than standard decoding
- Compare it with standard
VAEDecodeusing the same video and settings. - Try a different
tile_batch_size; a larger batch does not automatically mean a shorter decode. - Use standard
VAEDecodeif it is faster on your GPU. Fewer decoder invocations alone are not a reliable measure of elapsed time.
Batched decoding runs out of GPU memory
- Try a smaller
tile_batch_size. - Run the workflow again and check the result. The node is designed to clear its temporary cache and retry with batch size
1after a batched out-of-memory error. - If the problem persists, compare against standard
VAEDecode.
Frequently asked questions
Can you use MotionCache and Fast VAE Decode separately?
Yes. They are independent nodes for different stages of the workflow.
Can you combine MotionCache with EasyCache on the same model?
No. Do not use both on the same model.
Does “skipped calls” tell you how much faster the finished video will be?
No. It estimates savings in denoiser calls. Other work, including decoding, still takes time.
Does Fast VAE Decode reduce image information to gain speed?
It does not deliberately discard information. Its experiment is batching spatial tiles while retaining H3’s temporal chunking and tile blending. You should still compare its output and elapsed time with standard decoding on your setup.
Which decode node should you choose first?
Start with standard VAEDecode as a reference. Use Fast VAE Decode when your own same-setting comparison shows a benefit.
Learn More about ComfyUI-MiniMax-H3-MotionCache
- Example MiniMax H3 image-to-video workflow: shows both nodes in a workflow derived from the native H3 image-to-video template. It also retains optional Video Helper Suite, ComfyUI-Easy-Use, and KJNodes utility nodes.
- MotionCache reference repository: background on the research that inspired this independent H3 adaptation.
- ComfyUI repository: the underlying application and a starting point for learning more about ComfyUI workflows.
The extension is released under the MIT License.
