LTX25 Reference Params

Here's the problem this node solves. LTX25 Ultimate Upscale samples each time chunk independently, which is how it fits long clips in VRAM - but every chunk is a fresh roll of the dice. The character's face, the scene's look, they can drift from chunk to chunk. That's LTX's weakest axis in general (identity consistency across shots), and chunking makes it worse. LTX25 Reference Params is the answer: you hand it a few reference stills, it encodes them into guide latents, and the main node appends them to every chunk as near-clean conditioning tokens. Same identity, every chunk, without re-encoding.

The inputs

• ref_images - your reference stills. Each item in the batch is one reference, and order matters: it maps to MSR slot order (see the loader below). This is a load-once deal - encoding happens here, and the main node just reuses the result.
• ref_vae - the LTX2.5 video VAE, used to encode the references. The audio VAE won't work here; you'll get a shape mismatch.
• ref_strength (default 1.0) - how hard the guides are pinned. The noise mask value is 1 - strength, so 1.0 keeps the guides fully clean/frozen and 0.5 lets them drift halfway. Lower it if your references are fighting the motion.
• ref_frames (default "33") - how many pixel frames each still is repeated to before encoding. 25 gives 4 latent frames per reference, 33 gives 5. More frames = sturdier conditioning, slightly more compute per chunk.

Optional but the real power move: MSR

The msr_parameters input is optional and takes the output of an MSR IC-LoRA loader - either this pack's LTX25 IC-LoRA Loader (MSR) or the ComfyUI-LTX2.5-MSR package's, since they share a wire type. Wire it in and each reference gets a learned slot embedding (from the LoRA's trained Fourier-MLP) plus consecutive negative temporal offsets, matching the MSR training layout - that's the multi-subject-reference setup that lets one LoRA hold several characters and keep each in its own slot. Leave it unconnected and you get plain guides at offset 0, which is still a solid identity anchor, just not character-aware.

How it works under the hood

Each still is center-cropped to the target grid, repeated to ref_frames pixel frames (snapped to LTX's 8k+1 grid), and run through the video VAE. The encoded guide is then appended to every chunk's latent as extra tokens at the end, with their keyframe positions restored by RoPE inside the model - this is the native LTXVAddGuide mechanism ComfyUI ships, not a custom trick. The output, reference_guides, goes into the main node's reference_guides input. With spatial tiling enabled the guides are appended per tile (after the crop), so coordinates always match the tile's own grid.

One thing to know: the main node resizes each guide to the chunk's grid, so reference resolution is flexible, and the guides are stripped from the output afterward - you're not baking them into the final video, just steering it.

Installing

Part of the bbaudio-2025/Comfyui-MMH3-UltimateUpscale pack. ComfyUI Manager (search "Comfyui-MMH3-UltimateUpscale") or:

cd ComfyUI/custom_nodes
git clone https://github.com/bbaudio-2025/Comfyui-MMH3-UltimateUpscale

Restart. No pip deps, but this node needs a ComfyUI build that exposes comfy_extras.nodes_lt (the LTX guide support) - otherwise it raises a RuntimeError telling you exactly that.

Troubleshooting

• "ref_images must contain at least one image" - obvious but common when a batch got zeroed somewhere upstream.
• "MSR slot embedding dim != latent channels" - the LoRA's slot embedding doesn't match the latent's channel count; you're likely loading a LoRA trained for a different LTX version.
• "reference_downscale_factor != 1 … not supported" - the chunked pipeline only handles factor-1 MSR checkpoints. The loader's own metadata flags this; pick a different MSR LoRA.
• Faces still drift - raise ref_strength toward 1.0 or ref_frames to 33, and make sure the stills actually match the subject (garbage in, garbage out - LTX will anchor to whatever you give it).