Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-LTX2.5-MSR

ComfyUI Extension: ComfyUI-LTX2.5-MSR

Repo Name

ComfyUI-LTX2.5-MSR

Author
liconstudio (Account age: 478 days)
Nodes
View all nodes(2)
Latest Updated
2026-09-24
Github Stars
0.04K

How to Install ComfyUI-LTX2.5-MSR

Install this extension via the ComfyUI Manager by searching for ComfyUI-LTX2.5-MSR
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-LTX2.5-MSR in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

ComfyUI-LTX2.5-MSR Description

ComfyUI-LTX2.5-MSR guides LTX-2.5 video generation with up to five reference images and two optional paired audio references, using compatible LoRAs for single-pass or two-stage workflows.

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:

  1. Applies the compatible LoRA to your LTX-2.5 model.
  2. Passes its slot embeddings and reference metadata to the Guide through the msr_parameters connection.

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:

  1. pic1
  2. pic2
  3. pic3
  4. pic4
  5. background

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_ref1 with pic1
  • audio_ref2 with pic2

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.

InputWhat it does
modelAccepts an LTX-2.5 model from a native ComfyUI model loader.
lora_nameSelects a compatible checkpoint from ComfyUI/models/loras.
strength_modelControls 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:

InputRole
pic1First image reference.
pic2–pic4Additional image references.
backgroundOptional 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_model changes how strongly the LoRA is applied.
  • strength changes 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:

  • 25
  • 33 — 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_encode
  • tile_size
  • tile_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 typePurposeWhen to use it
MSR LoRAMulti-reference image conditioning with learned slot embeddings.Use when your workflow needs image references without AVref audio guidance.
AVref LoRACompatible 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:

ComponentPurposeStandard folder
LTX-2.5 transformerMain generation model.ComfyUI/models/diffusion_models
LTX-2.5 Gemma text encoderEncodes your text prompts.ComfyUI/models/text_encoders
Video and audio VAEsEncode and decode visual and audio data.ComfyUI/models/vae
MSR or AVref LoRAAdds compatible reference behavior.ComfyUI/models/loras
Optional LTX-2.5 latent upscalerSupports 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:

  1. Place the Guide before LTXVConcatAVLatent. It accepts a video-only latent, not a combined audio/video latent.
  2. Send the Guide’s conditioning outputs to LTXVCropGuides after 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:

  1. Run the first MSR-guided sampling pass.
  2. Separate the audio and video latents.
  3. Crop the first-stage reference slots.
  4. Upscale the generated video latent with LTXVLatentUpsampler.
  5. Apply a second Multi-Reference Guide using the same references.
  6. Rejoin the upscaled video latent with the audio latent.
  7. Run a low-noise refinement pass.
  8. 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

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 25 or 33 reference 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.

  1. Confirm that the checkpoint is in ComfyUI/models/loras.
  2. Open the loader’s lora_name dropdown.
  3. Select the file from the available entries instead of relying on the workflow’s saved path.
  4. Refresh the browser model list or restart ComfyUI if the file is not listed.
  5. 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.

  1. Check which file is selected in the loader.
  2. Replace an ordinary LoRA with an MSR-compatible checkpoint containing learned slot embeddings.
  3. For audio references, choose a compatible AVref checkpoint.

Renaming a normal LoRA will not make it compatible.

The Guide reports a latent-shape error

  1. Locate the Guide’s latent input.
  2. Make sure it receives a video-only LTX latent.
  3. Move the Guide before LTXVConcatAVLatent if necessary.
  4. Confirm that the latent has the expected shape, [B, 128, F, H, W].
  5. Use batch size 1.

Reference images appear as frames in the decoded video

The reference slots have not been removed correctly.

  1. Separate the sampled audio/video latent with LTXVSeparateAVLatent.
  2. Route the sampled video latent through LTXVCropGuides.
  3. Connect the Guide’s conditioning outputs to that crop node.
  4. Decode the cropped video latent.

For two-stage workflows, crop the guide slots after each sampling stage.

Audio-reference connections are rejected or incomplete

  1. Confirm that the loader uses a compatible AVref LoRA.
  2. Encode audio with native LTXVAudioVAEEncode.
  3. Connect its LATENT output to audio_ref1 or audio_ref2.
  4. Connect the matching picture: pic1 for audio_ref1, or pic2 for audio_ref2.
  5. Keep numbered picture inputs contiguous. Using pic2 requires pic1 as well.
  6. Leave unused audio inputs disconnected; do not expect later audio references to shift into empty windows.

An older AVref workflow has missing nodes

  1. Replace the old standalone AVref loader with the main IC-LoRA Loader.
  2. Replace the old AVref Guide with the main Multi-Reference Guide.
  3. Use native audio VAE encoding for audio references.
  4. 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.

ComfyUI-LTX2.5-MSR Related Nodes

RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

ComfyUI-LTX2.5-MSR detailed guide | ComfyUI