ComfyUI-LTX2.5-MSR Introduction
ComfyUI-LTX2.5-MSR brings multi-reference image guidance and optional audio-reference guidance to LTX-2.5 workflows in ComfyUI. You can supply up to five reference images, allowing the model to draw on several visual sources during video generation rather than relying on a single image.
With a compatible AVref LoRA, you can also connect two audio references, paired with the first two image references.
For AI artists, this provides a way to bring multiple visual references into the same generation—for example, several subjects or visual details alongside a background reference. These inputs guide the model; they are not a guaranteed way to copy every detail or place subjects precisely.
The extension provides two main nodes:
- ComfyUI-LTX2.5-MSR IC-LoRA Loader: Loads a compatible MSR or AVref LoRA and extracts the reference information it contains.
- ComfyUI-LTX2.5-MSR Multi-Reference Guide: Prepares your reference images and optional audio references for the video-generation workflow.
What it helps you do
- Use one to five independently encoded reference images.
- Keep reference ordering consistent with the way compatible MSR LoRAs were trained.
- Add optional audio-reference guidance without switching to a separate set of AVref nodes.
- Use references in either a single generation pass or a two-stage latent-upscale workflow.
- Continue using native ComfyUI nodes for sampling, text encoding, audio handling, decoding, and video output.
The extension contains its own complete MSR loader and guide implementation. It does not require LTX-MSR-Multi-Reference-Guide or another custom MSR node package.
Important: This is a reference-conditioning extension, not a complete video-generation system. You still need the appropriate LTX-2.5 models and a compatible workflow. Model weights are not included.
How ComfyUI-LTX2.5-MSR Works
1. A compatible LoRA provides the reference rules
A LoRA is a set of additional model weights that changes how a base model behaves. For this extension, the LoRA must also contain learned reference-slot embeddings.
You can think of these embeddings as learned labels attached to reference inputs. They help the model distinguish one reference slot from another instead of treating all references as an undifferentiated collection.
The loader performs two related tasks:
- Applies the compatible LoRA to your LTX-2.5 model.
- Passes its slot embeddings and reference metadata to the Guide through the
msr_parametersconnection.
An ordinary LoRA without these embeddings cannot replace an MSR-compatible checkpoint.
2. Each image is prepared separately
The Guide encodes each connected reference image independently using the video VAE.
A VAE converts images into a compressed representation called a latent. You can think of a latent as the model’s working version of an image: it contains visual information in a form suited to generation, rather than ordinary displayable pixels.
Reference preparation includes automatic resizing, center cropping, and white-padding behavior. This adapts images to the reference format without requiring a separate preprocessing workflow for every input.
3. References receive consistent slots
The Guide processes image inputs in this order:
pic1pic2pic3pic4background
Each reference receives its learned slot information. The extension also preserves the reference layout expected by MSR training, including prepended reference tokens and consecutive negative temporal positions.
In simpler terms, the references are placed in dedicated positions before the generated video timeline, rather than being treated as ordinary output frames.
4. Optional audio references keep their assigned windows
With a compatible AVref LoRA, you can pair:
audio_ref1withpic1audio_ref2withpic2
Audio references use fixed, absolute time windows. If an audio reference is missing, its window remains empty; later references do not slide forward to fill the gap. The extension does not insert silence to replace the missing reference.
For example, connecting only audio_ref2 does not move it into the first audio-reference window. Its corresponding image inputs must still follow the audio-reference rules described below.
5. The workflow samples, removes guide slots, and decodes
The Guide prepares reference conditioning, but native ComfyUI nodes perform the actual sampling.
After sampling, the temporary reference slots must be removed with LTXVCropGuides before decoding the generated video.
Think of the references as a mood board attached to the working canvas: they help create the result, but they should not remain as extra frames in the exported video.
ComfyUI-LTX2.5-MSR Features
Unified MSR and AVref LoRA loader
Node: ComfyUI-LTX2.5-MSR IC-LoRA Loader
Registration ID: ComfyUILTX25MSRICLoRALoader
The same loader handles both image-reference MSR checkpoints and compatible AVref checkpoints.
| Input | What it does |
|---|---|
model | Accepts an LTX-2.5 model from a native ComfyUI model loader. |
lora_name | Selects a compatible checkpoint from ComfyUI/models/loras. |
strength_model | Controls the strength at which the LoRA is applied to the model. |
The loader outputs:
model: The native ComfyUI model with the LoRA applied.msr_parameters: The learned reference-slot weights and metadata needed by the Guide.
AVref checkpoints are detected from their audio weights and metadata, validated, and configured for absolute audio-slot positioning.
One to five image references
Node: ComfyUI-LTX2.5-MSR Multi-Reference Guide
Registration ID: ComfyUILTX25MSRMultiReferenceGuide
Use pic1 as your first reference, then add optional inputs as needed:
| Input | Role |
|---|---|
pic1 | First image reference. |
pic2–pic4 | Additional image references. |
background | Optional background reference; counts toward the five-slot total. |
For image-only workflows, missing optional inputs are skipped and the connected references receive consecutive image slot IDs.
For workflows with audio references, numbered picture inputs must be contiguous: use pic1, then pic2, and so on without gaps. Each connected audio_refN also requires its matching picN.
The input names establish order and pairing. They do not, by themselves, guarantee exact visual composition.
Adjustable reference conditioning
The Guide’s strength setting controls reference-conditioning strength.
This is separate from the loader’s strength_model:
strength_modelchanges how strongly the LoRA is applied.strengthchanges the Guide’s reference conditioning.
These controls affect different parts of the workflow. When comparing results, change one setting at a time so you can identify which adjustment produced the difference.
The author does not specify a universal best value; the appropriate balance depends on your checkpoint and workflow.
Selectable reference length
The reference_frames setting offers:
2533— the default
Both options are available for MSR and AVref checkpoints. Compare them with your chosen LoRA rather than assuming one is always better.
This is a reference-conditioning setting, not a replacement for the workflow’s generated-video length setting.
Native audio-reference inputs
The main Guide accepts audio latents from native ComfyUI audio encoding:
LoadAudio
→ LTXVAudioVAEEncode
→ Guide.audio_ref1 or Guide.audio_ref2
The two visible audio inputs are optional. A third audio input remains hidden.
AVref handling preserves its dedicated slot embeddings, length truncation, and sparse absolute time windows. Audio references require a compatible AVref checkpoint; an image-only MSR checkpoint does not automatically gain audio-reference support.
See the AVref connection guide for additional wiring details.
Automatic image preparation and tiled encoding
The Guide provides automatic reference resizing, center cropping, and white-padding behavior.
It also includes:
use_tiled_encodetile_sizetile_overlap
Tiled encoding lets the VAE process reference images in smaller, overlapping sections rather than as one full image. It is an option to consider when reference encoding is constrained by available memory, although the author does not provide universal tile settings or memory-saving guarantees.
Compatibility with native ComfyUI workflows
The extension works alongside native ComfyUI model, conditioning, latent, VAE, sampler, and audio/video nodes.
It also supports checkpoint metadata such as reference_downscale_factor, allowing compatible reference-preparation information to come from the LoRA rather than being assumed externally.
ComfyUI-LTX2.5-MSR Models and Compatibility
Supported checkpoint types
The extension does not distribute model weights or provide a named catalogue of downloadable checkpoints. It supports these checkpoint categories:
| Checkpoint type | Purpose | When to use it |
|---|---|---|
| MSR LoRA | Multi-reference image conditioning with learned slot embeddings. | Use when your workflow needs image references without AVref audio guidance. |
| AVref LoRA | Compatible image-and-audio reference conditioning. | Use when you want to connect the Guide’s optional audio-reference inputs. |
Both types support reference_frames values of 25 and 33.
Other models used by the workflow
Your overall LTX-2.5 workflow uses separate model components:
| Component | Purpose | Standard folder |
|---|---|---|
| LTX-2.5 transformer | Main generation model. | ComfyUI/models/diffusion_models |
| LTX-2.5 Gemma text encoder | Encodes your text prompts. | ComfyUI/models/text_encoders |
| Video and audio VAEs | Encode and decode visual and audio data. | ComfyUI/models/vae |
| MSR or AVref LoRA | Adds compatible reference behavior. | ComfyUI/models/loras |
| Optional LTX-2.5 latent upscaler | Supports spatial latent upscaling in a two-stage workflow. | ComfyUI/models/latent_upscale_models |
Technical compatibility details
A compatible LoRA must contain these learned slot-embedding tensors:
reference_slot_embedding.frequencies
reference_slot_embedding.net.0.weight
reference_slot_embedding.net.0.bias
reference_slot_embedding.net.2.weight
reference_slot_embedding.net.2.bias
The loader also accepts the diffusion_model.reference_slot_embedding.* prefix.
Supported metadata conventions include:
reference_token_order=prepend
reference_slot_time_offsets=pic1_based_negative_time
reference_downscale_factor
For ComfyUI compatibility, the Guide uses a temporal scale factor of 1 while preserving the learned slot embeddings and consecutive negative positions.
You usually do not need to edit these details yourself. They explain why choosing a genuinely compatible checkpoint matters.
ComfyUI-LTX2.5-MSR Workflow Guide
Basic workflow
Use the loader’s model output for your native sampling setup:
Native LTX-2.5 model loader
→ ComfyUI-LTX2.5-MSR IC-LoRA Loader
→ native guider / sampler model input
Prepare reference conditioning through the Guide:
Positive + negative conditioning
Video VAE
Empty video latent
Reference images
MSR parameters from the loader
Optional encoded audio references
→ ComfyUI-LTX2.5-MSR Multi-Reference Guide
Continue through the native audio/video sampling path:
Guide video latent
→ LTXVConcatAVLatent
→ native LTX-2.5 sampler
→ LTXVSeparateAVLatent
→ LTXVCropGuides
→ video/audio decoding
Two connection rules are especially important:
- Place the Guide before
LTXVConcatAVLatent. It accepts a video-only latent, not a combined audio/video latent. - Send the Guide’s conditioning outputs to
LTXVCropGuidesafter sampling. This allows the temporary reference slots to be removed before video decoding.
The Guide expects a video latent shaped [B, 128, F, H, W], where B is the batch size. Current MSR inference requires a batch size of one.
Two-stage latent-upscale refinement
A two-stage workflow first generates a video latent, then increases its spatial resolution and refines it.
Use this sequence:
- Run the first MSR-guided sampling pass.
- Separate the audio and video latents.
- Crop the first-stage reference slots.
- Upscale the generated video latent with
LTXVLatentUpsampler. - Apply a second Multi-Reference Guide using the same references.
- Rejoin the upscaled video latent with the audio latent.
- Run a low-noise refinement pass.
- Crop the second-stage reference slots before decoding.
The second Guide rebuilds reference conditioning for the higher-resolution stage while retaining the upscaled generated video latent.
Do not replace this step with LTXVImgToVideoInplace. That node re-encodes pixel-space images or videos and overwrites latent frames, which is different from preserving the generated latent for MSR refinement.
Example workflow
The author provides a V2 sample workflow demonstrating two-stage sampling with audio references.
The sample uses:
- The main MSR loader and Guide.
- Native audio VAE encoding.
- KJNodes, rgthree, and PromptRelay.
After importing it, select your own model, image, and audio files. The additional node packages are used by the sample; they are not separate MSR implementations required by the extension itself.
What’s New with ComfyUI-LTX2.5-MSR
Version 1.2.2
- Added the V2 sample workflow, demonstrating two-stage sampling with audio references.
The current workflow uses the unified loader and Guide, supports two optional audio-reference inputs, preserves missing audio windows, and offers both 25- and 33-frame reference settings.
Version 1.2.1
- Removed AVref’s fixed 25-frame restriction.
- Added the choice of
25or33reference frames for AVref. - Preserved the existing empty-window behavior for missing audio references.
Why it matters: You can compare both reference lengths with your AVref LoRA without changing how sparse audio inputs are positioned.
Version 1.2.0
- Integrated audio references into the main Multi-Reference Guide.
- Consolidated the extension into the main loader and main Guide.
- Preserved sparse absolute audio windows.
- Kept the third audio input hidden.
- Removed the three older standalone AVref nodes.
Why it matters: Image and audio-reference workflows now share the same main nodes. Older AVref workflows must be updated to use these nodes and native audio encoding. The separate AVref plugin remains disabled.
Troubleshooting ComfyUI-LTX2.5-MSR
Invalid input: lora_name
The workflow refers to a LoRA path that is not in ComfyUI’s current model list.
- Confirm that the checkpoint is in
ComfyUI/models/loras. - Open the loader’s
lora_namedropdown. - Select the file from the available entries instead of relying on the workflow’s saved path.
- Refresh the browser model list or restart ComfyUI if the file is not listed.
- Check that the selected path exactly matches the dropdown entry, including any subfolder.
This LoRA does not contain reference_slot_embedding weights
The selected file is not a compatible MSR checkpoint.
- Check which file is selected in the loader.
- Replace an ordinary LoRA with an MSR-compatible checkpoint containing learned slot embeddings.
- For audio references, choose a compatible AVref checkpoint.
Renaming a normal LoRA will not make it compatible.
The Guide reports a latent-shape error
- Locate the Guide’s latent input.
- Make sure it receives a video-only LTX latent.
- Move the Guide before
LTXVConcatAVLatentif necessary. - Confirm that the latent has the expected shape,
[B, 128, F, H, W]. - Use batch size
1.
Reference images appear as frames in the decoded video
The reference slots have not been removed correctly.
- Separate the sampled audio/video latent with
LTXVSeparateAVLatent. - Route the sampled video latent through
LTXVCropGuides. - Connect the Guide’s conditioning outputs to that crop node.
- Decode the cropped video latent.
For two-stage workflows, crop the guide slots after each sampling stage.
Audio-reference connections are rejected or incomplete
- Confirm that the loader uses a compatible AVref LoRA.
- Encode audio with native
LTXVAudioVAEEncode. - Connect its
LATENToutput toaudio_ref1oraudio_ref2. - Connect the matching picture:
pic1foraudio_ref1, orpic2foraudio_ref2. - Keep numbered picture inputs contiguous. Using
pic2requirespic1as well. - Leave unused audio inputs disconnected; do not expect later audio references to shift into empty windows.
An older AVref workflow has missing nodes
- Replace the old standalone AVref loader with the main IC-LoRA Loader.
- Replace the old AVref Guide with the main Multi-Reference Guide.
- Use native audio VAE encoding for audio references.
- Compare the connections with the AVref guide or V2 sample workflow.
Frequently asked questions
Can I use any LoRA?
No. The checkpoint must contain the learned reference-slot embeddings expected by the loader. Audio-reference use additionally requires AVref compatibility.
Do I need to connect all five image references?
No. You can use one to five. Image-only workflows skip missing optional inputs; audio-reference workflows require contiguous numbered pictures.
Does background add a sixth slot?
No. It counts toward the five-reference maximum.
Can I use audio references without their matching pictures?
No. Each audio reference requires the same-numbered picture.
Should I use 25 or 33 reference frames?
Both are supported, and 33 is the default. Compare results with your particular LoRA; the author does not identify one setting as universally best.
Can I generate a batch of several videos through the Guide?
Current MSR inference requires batch size one.
Does this extension handle prompts, sampling schedules, or video export?
No. Those tasks remain with native ComfyUI nodes and the rest of your workflow.
Learn More about ComfyUI-LTX2.5-MSR
- V2 sample workflow: A practical example of two-stage sampling with image and audio references. Useful for checking node order and comparing your connections.
- AVref connection guide: Additional guidance for connecting audio references to the unified nodes.
The supplied context does not include additional tutorials or community-support links.
ComfyUI-LTX2.5-MSR License
ComfyUI-LTX2.5-MSR is licensed under the Apache License 2.0.
