ComfyUI-LTX2.5-MSR Multi-Reference Guide:
ComfyUI-LTX2.5-MSR Multi-Reference Guide prepares multiple still-image references to guide LTX video generation, allowing you to provide several visual subjects and an optional background within one reference-guidance setup. Rather than combining the images into a single collage, it encodes each reference independently, preserving their separation during preparation. In MSR mode, it adds learned slot embeddings—identifying signals that distinguish the reference positions—and places reference guidance at distinct negative timeline positions that match the MSR training convention. These positions organize the references for the model; they are not instructions to display reference pictures before the generated video. Without MSR configuration, the node falls back to standard LTX guide behavior, without learned slot embeddings or negative time offsets. It also supports optional audio-reference conditioning when used with a compatible AVref LoRA, and tiled image encoding is available to help manage the encoding workload.
ComfyUI-LTX2.5-MSR Multi-Reference Guide Input Parameters:
positive
Required CONDITIONING input containing the positive guidance for your generation, typically prepared from your prompt upstream. The node incorporates reference-related guidance into this conditioning and passes the updated version onward. This lets your text guidance and reference images participate in the same generation workflow. There is no numeric range or default value; connect conditioning compatible with your LTX workflow.
negative
Required CONDITIONING input containing the negative guidance used by your sampling workflow. The node processes this alongside the positive conditioning so that the reference setup is carried through the corresponding conditioning paths; when audio references are present, both are passed through the audio-reference attachment step. This is conditioning data, not a negative reference image. There is no numeric range or default value.
vae
Required VAE input used to encode the reference images into the compressed representation understood by the video model. The node uses the VAE’s spatial and temporal scaling information when preparing references for the target video latent. Connect a VAE compatible with your LTX video model; this socket is for video-reference encoding, while audio references must already be encoded separately. There is no numeric range or default value.
latent
Required LATENT input representing the video to be generated. Its dimensions determine the target spatial grid used to prepare the image references. The node requires a video-only latent with shape [B, 128, F, H, W], where B is batch size, F is the latent frame dimension, and H and W are latent height and width; B must be 1. Connect this before LTXVConcatAVLatent, rather than supplying an already combined audio-video latent. In MSR mode, its spatial dimensions must also be divisible by the reference downscale factor supplied through the MSR configuration. There is no fixed numeric default or interface range.
pic1
Required IMAGE input for the first visual reference. Supply exactly one still image, not an image batch or video sequence. The node repeats this image for the selected reference-frame count and encodes it independently. In MSR mode, it receives the first learned reference-slot embedding. The optional first audio reference is associated with this image position. There is no default image or numeric range.
strength
Required FLOAT control for reference-guidance strength. The default is 1.0, the minimum is 0.0, the maximum is 1.0, and the adjustment step is 0.01. Use it to adjust how strongly the reference guidance participates in your generation rather than changing the source pictures themselves. The supplied source is truncated before the precise application of this value, so it does not establish a linear relationship between this setting and the visible result. Lowering it also should not be treated as bypassing reference validation or encoding.
reference_frames
Required COMBO selection with the options 25 and 33; the default is 33. Each still image is repeated this many times before VAE encoding, creating the reference sequence used for guide preparation. This does not set the length of your generated video, and it does not require you to provide a 25- or 33-frame source clip. The node explicitly rejects any other value. Optional AVref audio references use the corresponding supported reference-frame arrangement. Increasing the count increases the number of image frames presented to the encoder, although the resulting latent frame count depends on the VAE’s temporal compression.
use_tiled_encode
Required BOOLEAN control that enables or disables tiled reference encoding. The default is False. When enabled, the reference-encoding path receives the tile size and overlap settings, allowing encoding to be divided into smaller spatial areas rather than handled as one full image. This can help when full-image VAE encoding exceeds available memory, though the exact memory and speed effects depend on the VAE and image dimensions. This setting concerns reference encoding, not tiled video sampling.
tile_size
Required INT control for the spatial tile size passed to tiled reference encoding. The default is 256, the interface minimum is 0, the maximum is 512, and the step is 32. Smaller tiles can reduce the amount of image data handled at once, while larger tiles process larger regions together. Although the interface permits values below 64 for compatibility with older workflows, execution replaces such values with 256 and logs a warning. This setting is relevant when tiled encoding is enabled; keeping the default is a sensible starting point.
tile_overlap
Required INT control for the overlap between neighboring encoding tiles. The default is 64, the interface minimum is 0, the maximum is 256, and the step is 16. Overlap gives adjacent tiles shared image content, helping their encoded regions meet more consistently, but also adds repeated encoding work. The code includes a compatibility correction that replaces values below 16 with 64 when that validation branch is reached. Use a practical overlap relative to your tile size rather than assuming every combination allowed by the interface is equally useful.
pic2
Optional IMAGE input for a second still-image reference. Like the other visual reference sockets, it must contain exactly one image. When supplied after pic1, it is independently encoded and receives the next available reference slot in MSR mode. Connect it when you want another visual subject or reference represented separately rather than merged into the first image. If you supply audio_ref2, provide the corresponding image here so that the audio/image mapping can be validated. There is no default image or numeric range.
pic3
Optional IMAGE input for another independently encoded still-image reference. It must contain exactly one image. References are collected in socket order while empty optional sockets are skipped, so its assigned MSR slot depends on which earlier image sockets are connected. For example, if pic2 is empty, pic3 becomes the second collected reference. There is no default image or numeric range.
pic4
Optional IMAGE input for an additional still-image reference, again limited to exactly one image. It is processed independently and placed after the earlier connected picture references in the collected reference order. In MSR mode, it receives the learned embedding for its position in that collected list, rather than necessarily receiving slot four when earlier optional sockets are empty. There is no default image or numeric range.
background
Optional IMAGE input for a background reference. Supply one still image. It is collected after all connected picture references and is explicitly marked as a background when passed into reference encoding, distinguishing its role from the other images. The supplied source does not show the encoding helper’s implementation, so it does not establish the exact background-specific resizing or cropping behavior. With all picture sockets connected, this is the fifth reference; if some are empty, it receives an earlier collected slot. There is no default image or numeric range.
msr_parameters
Optional LTX_MSR_REFERENCE_PARAMETERS input carrying the MSR setup from the ComfyUI-LTX2.5-MSR IC-LoRA Loader. Connecting it enables learned reference-slot embeddings, MSR negative temporal offsets, and the configured reference downscale factor. Omitting it switches to standard LTX guide behavior, where references start at frame 0 without MSR slot embeddings. The metadata must use prepend reference-token order and pic1_based_negative_time slot offsets when those fields are provided. For audio references, the parameters must also contain AVref audio-slot state from a compatible AVref LoRA. This is a structured connection, not a numeric widget, and it has no interface default value.
audio_ref1
Optional LATENT input for an encoded audio reference associated with pic1. The socket expects the output of LTXV Audio VAE Encode, not a raw audio clip and not an ordinary video latent. Supplying it activates audio-reference preparation and mapping validation, and requires AVref-capable parameters from the MSR IC-LoRA Loader. Audio references use AVref absolute slot windows rather than ordinary image-guide placement. There is no numeric range or default value; leave it disconnected when you do not need audio-reference conditioning.
audio_ref2
Optional LATENT input for an encoded audio reference associated with pic2. Like audio_ref1, it expects LTXV Audio VAE Encode output and requires an AVref LoRA loaded through the MSR IC-LoRA Loader. Connect the corresponding second picture reference so that the mapping can be checked. The socket tooltip specifically states that leaving this input empty preserves its audio time window, so you do not need to populate it merely because you supplied a second image. There is no numeric range or default value.
ComfyUI-LTX2.5-MSR Multi-Reference Guide Output Parameters:
positive
Updated CONDITIONING containing the positive conditioning after reference-guide preparation. If audio references are supplied, it also passes through the audio-reference attachment stage. Connect this output to the positive-conditioning path used downstream so that the sampler receives the prepared reference information rather than only the original prompt conditioning. It is structured conditioning data, not a rendered image or a text string.
negative
Updated CONDITIONING for the negative-conditioning path after the node has processed the reference setup. Audio-reference attachment, when active, also receives and returns this conditioning. Use this output alongside the updated positive conditioning to keep the two conditioning paths consistent with the prepared guides. Its contents are model-conditioning data, not a visual negative reference or an audio waveform.
latent
Prepared LATENT containing the resulting samples tensor and noise_mask. These carry the video latent with the appended reference-guide material and the corresponding noise-mask information used downstream. It remains a latent representation requiring sampling and decoding, not a finished video. Because the node adds guide material, do not assume its temporal dimensions are identical to the incoming generation latent. Route this output onward together with the updated conditioning; in an audio-video workflow, place this guide preparation before LTXVConcatAVLatent.
ComfyUI-LTX2.5-MSR Multi-Reference Guide Usage Tips:
- Connect the matching IC-LoRA Loader configuration through
msr_parameterswhen you want MSR behavior. Without this connection, the node can still prepare standard LTX guides, but it explicitly skips learned slot embeddings and MSR negative time offsets. - Start with one reference in
pic1,strengthat 1.0, and the defaultreference_framesvalue of33. Add references one at a time so you can judge how each changes the result before adjusting several settings together. - Keep your reference order consistent across tests. Empty optional image sockets are skipped, so removing an earlier picture changes the learned slot assigned to later pictures and the background.
- Supply one still image per image socket. If your image-loading or processing chain creates a batch, select a single image before connecting it here.
- Use
backgroundfor your background reference rather than placing it in a picture socket. The encoder receives an explicit background flag for this connection, although the provided code does not establish the exact preprocessing difference. - If reference encoding runs out of GPU memory, enable
use_tiled_encodeand begin withtile_size256 andtile_overlap64. If necessary, try a smaller valid tile size while retaining a sensible overlap; these controls affect encoding, not the memory required for every later sampling step. - Treat
reference_framesas a reference-preparation setting, not a video-duration control. Compare25and33if your workflow supports both, and use the setting expected by your chosen MSR or AVref workflow. - For audio references, load an AVref-compatible LoRA through the MSR IC-LoRA Loader and encode your audio with LTXV Audio VAE Encode. Associate the first audio reference with
pic1and the second withpic2; leaveaudio_ref2empty when you want to preserve its audio window. - Connect all three outputs onward. Using the original conditioning or original latent instead can discard part of the prepared reference setup.
- Check the console when troubleshooting. Messages such as
slot_embedding=APPLIEDconfirm MSR slot application, whileslot_embedding=SKIPPEDandstandard fallbackindicate that MSR parameters were not connected.
ComfyUI-LTX2.5-MSR Multi-Reference Guide Common Errors and Solutions:
Audio references require an AVref LoRA loaded with the MSR IC-LoRA Loader.
- Explanation: At least one audio reference was supplied, but the MSR parameters are missing or do not contain the audio-slot state required for AVref.
- Solution: Load a compatible AVref LoRA with the MSR IC-LoRA Loader and connect its parameters to
msr_parameters. If you only need image guidance, disconnect the audio references.
pic1 must be one still image, but received N frames.
- Explanation: The named image socket contains an image batch or video sequence instead of one still image. The same message can name
pic2,pic3,pic4, orbackground. - Solution: Select one frame or image from the upstream batch and connect that single image. Do not create the 25- or 33-frame repetition yourself; the node handles it internally.
MSR requires 1-5 references, got N.
- Explanation: The collected image-reference count is outside the supported range of one to five.
- Solution: Ensure
pic1contains a valid image and use only the four picture sockets plus the optional background. With the normal interface, supplyingpic1satisfies the minimum.
reference_frames must be 25 or 33, got N.
- Explanation: The frame-count setting contains an unsupported value, potentially from an edited workflow or programmatic call.
- Solution: Select
25or33from the dropdown. Restore the default33if an older or modified workflow has stored another value.
Unsupported reference_token_order; expected 'prepend'.
- Explanation: The connected MSR metadata requests a reference-token arrangement that this node does not support.
- Solution: Use parameters produced by a compatible MSR IC-LoRA Loader and checkpoint. Avoid manually changing this metadata merely to bypass validation.
Unsupported reference_slot_time_offsets; expected 'pic1_based_negative_time'.
- Explanation: The MSR parameters specify a different reference timing convention from the one implemented here.
- Solution: Check that your loader, LoRA, and guide-node installation are compatible. Reload the parameters from the intended MSR checkpoint rather than editing the timing field manually.
The guide node needs a video-only LTX latent shaped [B, 128, F, H, W]. Connect it before LTXVConcatAVLatent.
- Explanation: The incoming latent is not the required five-dimensional, 128-channel video latent. A combined audio-video latent or a latent from another model family can cause this.
- Solution: Connect a compatible LTX video latent and move this guide node before
LTXVConcatAVLatentin your workflow.
MSR multi-reference inference currently requires batch_size=1.
- Explanation: The incoming video latent contains more than one batch item.
- Solution: Set the upstream video-latent batch size to 1. Generate multiple variations through separate runs rather than a multi-item latent batch.
Target latent grid WIDTHxHEIGHT is not divisible by reference_downscale_factor=FACTOR.
- Explanation: The target latent width or height cannot be divided evenly by the reference downscale factor in the MSR parameters. These are latent-grid dimensions, not necessarily the displayed pixel dimensions of your video.
- Solution: Adjust the generation resolution so that both resulting latent dimensions are compatible with the configured factor. Keep the loader’s intended downscale factor unless you know the model supports a different one.
Slot embedding dimension N does not match LTX latent channels C.
- Explanation: A learned slot embedding has a different number of values from the channels in the encoded reference. This indicates incompatible components in the MSR setup.
- Solution: Verify that the LoRA, loader parameters, video model, and VAE belong to a compatible LTX/MSR configuration. Reload matching components rather than reshaping embeddings manually.
Unexpected input(s): INPUT_NAMES
- Explanation: A workflow or external call supplied input names that the node does not recognize. The legacy
pic5name is handled separately, but other unexpected names cause an error. - Solution: Recreate or update the node using its current interface and remove obsolete connections or arguments. Use
backgroundfor the current background-reference socket.
Warning: Invalid tile_size=N; using default tile_size=256
- Explanation: This is a correction warning, not a fatal error. The supplied tile size is below 64, so the node substitutes 256 despite the interface allowing lower values for compatibility.
- Solution: Set
tile_sizeexplicitly to 256, or another supported value of at least 64, and save the workflow again.
Warning: Invalid tile_overlap=N; using default tile_overlap=64
- Explanation: This is a correction warning indicating that the overlap is below 16 and the node has reached the branch that resets it to 64. - Solution: Use the default overlap of 64 or a suitable value of at least 16, then save the updated workflow.
Warning: Migrating legacy widget layout
- Explanation: An older workflow contains a removed crop-widget value that has shifted the stored encoding settings. The node recognizes this layout and resets tiled encoding to False, tile size to 256, and overlap to 64. - Solution: Review the corrected settings, re-enable tiled encoding if needed, and save the workflow with the current node version.
Warning: Both legacy pic5 and background were provided; using background
- Explanation: The workflow supplied both the old fifth-picture input and the current background input. The node keeps
backgroundand ignores the legacy image. - Solution: Remove the obsolete
pic5connection and retain onlybackground. If onlypic5was supplied, the node can migrate it automatically, but updating and saving the workflow avoids continued migration warnings.
