ComfyUI-LTX-AssetGuide

Custom node extension for ComfyUI that brings MiniMax H3 Easy style @asset prompt referencing, multi-reference MSR slot embeddings, and temporal keyframe placement to LTX-2.5 video generation workflows.

Connect multiple reference assets (images, videos, audio) to a single node and reference them naturally in your prompt using @1, @2, @hero, or with temporal offsets like @2 at 3.5s.

---

Key Features

1. Natural @asset Mention Syntax:

   • Mention connected assets in your prompt text using slot numbers (@1, @2), slot names (@media_1), or exact filenames (@ad_cyber_hero).
   • Automatically resolves to training-compliant Image 1: ..., Image 2: ... labels for PromptRelay and downstream conditioners.

2. Temporal Keyframe Placement (at Ns):

   • Place assets on specific timeline timestamps (e.g., @scene at 2.5s).
   • Bypasses the traditional single "first frame" limitation by encoding and injecting VAE guide keyframes at arbitrary timestamps.

3. MSR Multi-Reference Character Consistency:

   • Full integration with LTX-2.5-Licon-MSR-V1 IC-LoRA.
   • Extracts learned Fourier-MLP reference slot embeddings and places them at negative temporal positions, maintaining strict character and item identity across shots.

4. Multi-Modal Audio Identity Transfer:

   • Directly routes audio references into the LTX-2.5 ID-LoRA speaker identity pipeline via LTXVReferenceAudio with configurable identity_guidance_scale.

5. Visual Frontend Extension (Phase 5):

   • Connected media pills and asset badges rendered directly on the LTXAssetPrompt node.
   • Interactive @ autocomplete dropdown menu inside prompt textareas.

---

Nodes Overview

1. LTX Asset Prompt (LTXAssetPrompt)

• Inputs: global_prompt (multiline text), local_prompts (multiline text), media_1 through media_8 (wildcard inputs accepting image tensors, video components, or audio dicts).
• Outputs:
  • resolved_global_prompt (STRING): prompt text with @ mentions converted to MSR format.
  • resolved_local_prompts (STRING): timeline local prompts ready for PromptRelay.
  • asset_set (LTX_ASSET_SET): internal representation carrying media tensors, types, and timestamp placements.

2. LTX Asset Guide (LTXAssetGuide)

• Inputs: positive, negative, vae, latent, asset_set, strength, fps, identity_guidance_scale, optional model, audio_vae, and msr_parameters.
• Outputs: model, positive, negative, latent.
• Behavior: Encodes reference images into guide latents, applies MSR Fourier slot embeddings, adds keyframe indices and per-reference attention entries, and delegates audio references to LTXVReferenceAudio.

---

Mention Syntax Examples

@hero                 -> Injected as MSR reference slot (Image 1)
@hero at 3.5s         -> Injected as timeline keyframe at 3.5 seconds
@1 and @2             -> Reference media_1 and media_2 by connection index
@battle.mp4 at 6s     -> Video reference placed at 6 seconds
@speaker              -> Audio clip routed to ID-LoRA speaker identity

---

Recommended Workflow

A ready-to-run, fully optimized workflow is provided in workflows/LTX2.5-MSR-AssetGuide.json.

[UNet Loader] ──> [MSR IC-LoRA Loader] ──(model)──> [Prompt Relay]
                       │ (msr_params)                     │
                       ▼                                  ▼
[Images/Audio] ──> [LTX Asset Prompt] ──(asset_set)──> [LTX Asset Guide] ──> [CFG Guider] ──> [Sampler] ──> [Crop Guides] ──> [Decode & Save]

Memory Management

The included workflow integrates 6 strategic UnloadAllModels barriers across pipeline stages to ensure smooth 1280x720 and 640x360 generation on 24GB VRAM GPUs (e.g., RTX 3090, RTX 4090).

---

Installation

1. Navigate to your ComfyUI custom_nodes directory:

   cd ComfyUI/custom_nodes

2. Clone the repository:

   git clone https://github.com/UgurInanc12/ComfyUI_LTX_AssetGuide.git

3. Restart ComfyUI.

---

Testing

Run the test suite with pytest:

python -m pytest tests/ -v

---

License

MIT License. See LICENSE for details.