Skip to content

vllm_omni.diffusion.models.ltx2

Modules:

Name Description
ltx2_adapter_parser

Parse official LTX distilled adapters without materializing their tensors.

ltx2_components

Shared component construction helpers for the LTX model family.

ltx2_conditioning

Task-specific conditioning shared by LTX model versions.

ltx2_denoise

Shared denoise execution primitives for LTX pipelines.

ltx2_guidance

Official multi-modal guidance for the LTX model family.

ltx2_latents

Shared latent layout and normalization primitives for LTX pipelines.

ltx2_phase_adapter

Construction and execution of a fixed LTX refinement-phase adapter.

ltx2_recipes

Declarative execution recipes for the LTX model family.

ltx2_request

Request normalization and validation shared by LTX pipeline variants.

ltx2_runtime

Shared recipe-driven runtime for LTX pipeline variants.

ltx2_sequence_parallel
ltx2_transformer
ops

Shared operator selection for LTX-2 eager kernels and their tests.

pipeline_ltx2

One-stage entry points for the LTX model family.

pipeline_ltx2_two_stage

Two-stage entry points for the LTX model family.

vae

Ordinary LTX-2.5 DiffVAE, tiled decoding and acceleration operators.

LTX2DistilledPipeline module-attribute

LTX2DistilledPipeline = LTX2DistilledTwoStagePipeline

LTX2DistilledOneStagePipeline

Bases: LTX2Pipeline

Merged-distilled checkpoint at its native one-stage resolution.

component_profile class-attribute instance-attribute

pipeline_kind class-attribute instance-attribute

pipeline_kind = 'distilled_one_stage'

pipeline_recipe class-attribute instance-attribute

LTX2DistilledTwoStagePipeline

Bases: _LTX2TwoStageBase

Merged-distilled checkpoint with latent upsampling and refinement.

component_profile class-attribute instance-attribute

pipeline_kind class-attribute instance-attribute

pipeline_kind = 'distilled_two_stage'

pipeline_recipe class-attribute instance-attribute

LTX2I2VDMD2Pipeline

Bases: DMD2PipelineMixin, LTX2Pipeline

LTX2 I2V entry for FastGen DMD2-distilled models.

pipeline_kind class-attribute instance-attribute

pipeline_kind = 'dmd2'

pipeline_recipe class-attribute instance-attribute

pipeline_recipe = LTX_POSITIVE_ONLY_RECIPE

unified_text_image_entry class-attribute instance-attribute

unified_text_image_entry = False

LTX2Pipeline

Bases: LTXI2VConditioningMixin, LTXRuntime

LTX-2 family one-stage entry, configured from checkpoint metadata.

component_profile class-attribute instance-attribute

component_profile = LTX2_COMPONENT_PROFILE

pipeline_kind class-attribute instance-attribute

pipeline_kind = 'one_stage'

pipeline_recipe class-attribute instance-attribute

pipeline_recipe = LTX2_ONE_STAGE_RECIPE

supports_request_batch class-attribute instance-attribute

supports_request_batch = True

unified_text_image_entry class-attribute instance-attribute

unified_text_image_entry = True

LTX2T2VDMD2Pipeline

Bases: DMD2PipelineMixin, LTX2Pipeline

LTX2 T2V entry for FastGen DMD2-distilled models.

pipeline_kind class-attribute instance-attribute

pipeline_kind = 'dmd2'

pipeline_recipe class-attribute instance-attribute

pipeline_recipe = LTX_POSITIVE_ONLY_RECIPE

support_image_input class-attribute instance-attribute

support_image_input = False

LTX2TwoStagePipeline

Bases: _LTX2TwoStageBase

Regular checkpoint with low-resolution generation and LoRA refinement.

component_profile class-attribute instance-attribute

pipeline_kind class-attribute instance-attribute

pipeline_kind = 'two_stage'

pipeline_recipe class-attribute instance-attribute

pipeline_recipe = LTX2_TWO_STAGE_RECIPE

LTX2VideoTransformer3DModel

Bases: Module

A Transformer model for video-like data used in LTX.

Parameters:

Name Type Description Default
in_channels `int`, defaults to `128`

The number of channels in the input.

128
out_channels `int`, defaults to `128`

The number of channels in the output.

128
patch_size `int`, defaults to `1`

The size of the spatial patches to use in the patch embedding layer.

1
patch_size_t `int`, defaults to `1`

The size of the tmeporal patches to use in the patch embedding layer.

1
num_attention_heads `int`, defaults to `32`

The number of heads to use for multi-head attention.

32
attention_head_dim `int`, defaults to `64`

The number of channels in each head.

128
cross_attention_dim `int`, defaults to `2048 `

The number of channels for cross attention heads.

4096
num_layers `int`, defaults to `28`

The number of layers of Transformer blocks to use.

48
activation_fn `str`, defaults to `"gelu-approximate"`

Activation function to use in feed-forward.

'gelu-approximate'
qk_norm `str`, defaults to `"rms_norm_across_heads"`

The normalization layer to use.

'rms_norm_across_heads'

audio_caption_projection instance-attribute

audio_caption_projection = PixArtAlphaTextProjection(
    in_features=caption_channels,
    hidden_size=audio_inner_dim,
)

audio_norm_out instance-attribute

audio_norm_out = nn.LayerNorm(
    audio_inner_dim, eps=1e-06, elementwise_affine=False
)

audio_proj_in instance-attribute

audio_proj_in = nn.Linear(
    audio_in_channels, audio_inner_dim
)

audio_proj_out instance-attribute

audio_proj_out = nn.Linear(
    audio_inner_dim, audio_out_channels
)

audio_prompt_adaln instance-attribute

audio_prompt_adaln = LTX2AdaLayerNormSingle(
    audio_inner_dim,
    num_mod_params=2,
    use_additional_conditions=False,
)

audio_rope instance-attribute

audio_rope = LTX2AudioVideoRotaryPosEmbed(
    dim=audio_inner_dim,
    patch_size=audio_patch_size,
    patch_size_t=audio_patch_size_t,
    base_num_frames=audio_pos_embed_max_pos,
    sampling_rate=audio_sampling_rate,
    hop_length=audio_hop_length,
    scale_factors=[audio_scale_factor],
    theta=rope_theta,
    causal_offset=causal_offset,
    modality="audio",
    double_precision=rope_double_precision,
    rope_type=rope_type,
    num_attention_heads=audio_num_attention_heads,
)

audio_scale_shift_table instance-attribute

audio_scale_shift_table = nn.Parameter(
    torch.randn(2, audio_inner_dim) / audio_inner_dim**0.5
)

audio_time_embed instance-attribute

audio_time_embed = LTX2AdaLayerNormSingle(
    audio_inner_dim,
    num_mod_params=audio_num_mod_params,
    use_additional_conditions=False,
)

av_cross_attn_audio_scale_shift instance-attribute

av_cross_attn_audio_scale_shift = LTX2AdaLayerNormSingle(
    audio_inner_dim,
    num_mod_params=4,
    use_additional_conditions=False,
)

av_cross_attn_audio_v2a_gate instance-attribute

av_cross_attn_audio_v2a_gate = LTX2AdaLayerNormSingle(
    audio_inner_dim,
    num_mod_params=1,
    use_additional_conditions=False,
)

av_cross_attn_video_a2v_gate instance-attribute

av_cross_attn_video_a2v_gate = LTX2AdaLayerNormSingle(
    inner_dim,
    num_mod_params=1,
    use_additional_conditions=False,
)

av_cross_attn_video_scale_shift instance-attribute

av_cross_attn_video_scale_shift = LTX2AdaLayerNormSingle(
    inner_dim,
    num_mod_params=4,
    use_additional_conditions=False,
)

caption_projection instance-attribute

caption_projection = PixArtAlphaTextProjection(
    in_features=caption_channels, hidden_size=inner_dim
)

config instance-attribute

config = SimpleNamespace(
    in_channels=in_channels,
    out_channels=out_channels,
    patch_size=patch_size,
    patch_size_t=patch_size_t,
    num_attention_heads=num_attention_heads,
    attention_head_dim=attention_head_dim,
    cross_attention_dim=cross_attention_dim,
    vae_scale_factors=vae_scale_factors,
    pos_embed_max_pos=pos_embed_max_pos,
    base_height=base_height,
    base_width=base_width,
    audio_in_channels=audio_in_channels,
    audio_out_channels=audio_out_channels,
    audio_patch_size=audio_patch_size,
    audio_patch_size_t=audio_patch_size_t,
    audio_num_attention_heads=audio_num_attention_heads,
    audio_attention_head_dim=audio_attention_head_dim,
    audio_cross_attention_dim=audio_cross_attention_dim,
    audio_scale_factor=audio_scale_factor,
    audio_pos_embed_max_pos=audio_pos_embed_max_pos,
    audio_sampling_rate=audio_sampling_rate,
    audio_hop_length=audio_hop_length,
    num_layers=num_layers,
    activation_fn=activation_fn,
    qk_norm=qk_norm,
    norm_elementwise_affine=norm_elementwise_affine,
    norm_eps=norm_eps,
    caption_channels=caption_channels,
    attention_bias=attention_bias,
    attention_out_bias=attention_out_bias,
    rope_theta=rope_theta,
    rope_double_precision=rope_double_precision,
    causal_offset=causal_offset,
    timestep_scale_multiplier=timestep_scale_multiplier,
    cross_attn_timestep_scale_multiplier=cross_attn_timestep_scale_multiplier,
    rope_type=rope_type,
    ff_bias=ff_bias,
    audio_ff_bias=audio_ff_bias,
    use_prompt_adaln_single=use_prompt_adaln_single,
    use_keyframes_abs_pos_embedding=use_keyframes_abs_pos_embedding,
)

cross_attn_audio_rope instance-attribute

cross_attn_audio_rope = LTX2AudioVideoRotaryPosEmbed(
    dim=audio_cross_attention_dim,
    patch_size=audio_patch_size,
    patch_size_t=audio_patch_size_t,
    base_num_frames=cross_attn_pos_embed_max_pos,
    sampling_rate=audio_sampling_rate,
    hop_length=audio_hop_length,
    theta=rope_theta,
    causal_offset=causal_offset,
    modality="audio",
    double_precision=rope_double_precision,
    rope_type=rope_type,
    num_attention_heads=audio_num_attention_heads,
)

cross_attn_rope instance-attribute

cross_attn_rope = LTX2AudioVideoRotaryPosEmbed(
    dim=audio_cross_attention_dim,
    patch_size=patch_size,
    patch_size_t=patch_size_t,
    base_num_frames=cross_attn_pos_embed_max_pos,
    base_height=base_height,
    base_width=base_width,
    theta=rope_theta,
    causal_offset=causal_offset,
    modality="video",
    double_precision=rope_double_precision,
    rope_type=rope_type,
    num_attention_heads=num_attention_heads,
)

gradient_checkpointing instance-attribute

gradient_checkpointing = False

keyframes_abs_pos_embedding instance-attribute

keyframes_abs_pos_embedding = nn.Parameter(
    torch.zeros(1, inner_dim)
)

norm_out instance-attribute

norm_out = nn.LayerNorm(
    inner_dim, eps=1e-06, elementwise_affine=False
)

packed_modules_mapping class-attribute instance-attribute

packed_modules_mapping = {
    "to_qkv": ["to_q", "to_k", "to_v"]
}

perturbed_attn instance-attribute

perturbed_attn = perturbed_attn

proj_in instance-attribute

proj_in = nn.Linear(in_channels, inner_dim)

proj_out instance-attribute

proj_out = nn.Linear(inner_dim, out_channels)

prompt_adaln instance-attribute

prompt_adaln = LTX2AdaLayerNormSingle(
    inner_dim,
    num_mod_params=2,
    use_additional_conditions=False,
)

prompt_modulation instance-attribute

prompt_modulation = cross_attn_mod or audio_cross_attn_mod

rope instance-attribute

rope = LTX2AudioVideoRotaryPosEmbed(
    dim=inner_dim,
    patch_size=patch_size,
    patch_size_t=patch_size_t,
    base_num_frames=pos_embed_max_pos,
    base_height=base_height,
    base_width=base_width,
    scale_factors=vae_scale_factors,
    theta=rope_theta,
    causal_offset=causal_offset,
    modality="video",
    double_precision=rope_double_precision,
    rope_type=rope_type,
    num_attention_heads=num_attention_heads,
)

scale_shift_table instance-attribute

scale_shift_table = nn.Parameter(
    torch.randn(2, inner_dim) / inner_dim**0.5
)

stacked_params_mapping class-attribute instance-attribute

stacked_params_mapping = (
    (".attn1.to_qkv", ".attn1.to_q", "q"),
    (".attn1.to_qkv", ".attn1.to_k", "k"),
    (".attn1.to_qkv", ".attn1.to_v", "v"),
    (".audio_attn1.to_qkv", ".audio_attn1.to_q", "q"),
    (".audio_attn1.to_qkv", ".audio_attn1.to_k", "k"),
    (".audio_attn1.to_qkv", ".audio_attn1.to_v", "v"),
)

time_embed instance-attribute

time_embed = LTX2AdaLayerNormSingle(
    inner_dim,
    num_mod_params=video_num_mod_params,
    use_additional_conditions=False,
)

transformer_blocks instance-attribute

transformer_blocks = nn.ModuleList(
    [
        LTX2VideoTransformerBlock(
            dim=inner_dim,
            num_attention_heads=num_attention_heads,
            attention_head_dim=attention_head_dim,
            cross_attention_dim=cross_attention_dim,
            audio_dim=audio_inner_dim,
            audio_num_attention_heads=audio_num_attention_heads,
            audio_attention_head_dim=audio_attention_head_dim,
            audio_cross_attention_dim=audio_cross_attention_dim,
            video_gated_attn=gated_attn,
            video_cross_attn_adaln=cross_attn_mod,
            audio_gated_attn=audio_gated_attn,
            audio_cross_attn_adaln=audio_cross_attn_mod,
            qk_norm=qk_norm,
            activation_fn=activation_fn,
            attention_bias=attention_bias,
            attention_out_bias=attention_out_bias,
            eps=norm_eps,
            elementwise_affine=norm_elementwise_affine,
            rope_type=rope_type,
            perturbed_attn=perturbed_attn,
            ff_bias=ff_bias,
            audio_ff_bias=audio_ff_bias,
            quant_config=quant_config,
            prefix=f"transformer_blocks.{layer_idx}",
        )
        for layer_idx in range(num_layers)
    ]
)

disable_gradient_checkpointing

disable_gradient_checkpointing() -> None

enable_gradient_checkpointing

enable_gradient_checkpointing() -> None

forward

forward(
    hidden_states: Tensor,
    audio_hidden_states: Tensor,
    encoder_hidden_states: Tensor,
    audio_encoder_hidden_states: Tensor,
    timestep: LongTensor,
    audio_timestep: LongTensor | None = None,
    keyframes_mask: Tensor | None = None,
    sigma: Tensor | None = None,
    audio_sigma: Tensor | None = None,
    encoder_attention_mask: Tensor | None = None,
    audio_encoder_attention_mask: Tensor | None = None,
    audio_attention_mask: Tensor | None = None,
    num_frames: int | None = None,
    height: int | None = None,
    width: int | None = None,
    fps: float = 24.0,
    audio_num_frames: int | None = None,
    video_coords: Tensor | None = None,
    audio_coords: Tensor | None = None,
    attention_kwargs: dict[str, Any] | None = None,
    return_dict: bool = True,
    **kwargs,
) -> Tensor

Forward pass for LTX-2.0 audiovisual video transformer.

Parameters:

Name Type Description Default
hidden_states `torch.Tensor`

Input patchified video latents of shape (batch_size, num_video_tokens, in_channels).

required
audio_hidden_states `torch.Tensor`

Input patchified audio latents of shape (batch_size, num_audio_tokens, audio_in_channels).

required
encoder_hidden_states `torch.Tensor`

Input video text embeddings of shape (batch_size, text_seq_len, self.config.caption_channels).

required
audio_encoder_hidden_states `torch.Tensor`

Input audio text embeddings of shape (batch_size, text_seq_len, self.config.caption_channels).

required
timestep `torch.Tensor`

Input timestep of shape (batch_size, num_video_tokens). These should already be scaled by self.config.timestep_scale_multiplier.

required
audio_timestep `torch.Tensor`, *optional*

Input timestep of shape (batch_size,) or (batch_size, num_audio_tokens) for audio modulation params. This is only used by certain pipelines such as the I2V pipeline.

None
encoder_attention_mask `torch.Tensor`, *optional*

Optional multiplicative text attention mask of shape (batch_size, text_seq_len).

None
audio_encoder_attention_mask `torch.Tensor`, *optional*

Optional multiplicative text attention mask of shape (batch_size, text_seq_len) for audio modeling.

None
audio_attention_mask `torch.Tensor`, *optional*

Optional audio-token key padding mask shared by audio self-attention and audio-to-video attention.

None
num_frames `int`, *optional*

The number of latent video frames. Used if calculating the video coordinates for RoPE.

None
height `int`, *optional*

The latent video height. Used if calculating the video coordinates for RoPE.

None
width `int`, *optional*

The latent video width. Used if calculating the video coordinates for RoPE.

None
fps float

(float, optional, defaults to 24.0): The desired frames per second of the generated video. Used if calculating the video coordinates for RoPE.

24.0
audio_num_frames int | None

(int, optional): The number of latent audio frames. Used if calculating the audio coordinates for RoPE.

None
video_coords `torch.Tensor`, *optional*

The video coordinates to be used when calculating the rotary positional embeddings (RoPE) of shape (batch_size, 3, num_video_tokens, 2). If not supplied, this will be calculated inside forward.

None
audio_coords `torch.Tensor`, *optional*

The audio coordinates to be used when calculating the rotary positional embeddings (RoPE) of shape (batch_size, 1, num_audio_tokens, 2). If not supplied, this will be calculated inside forward.

None
attention_kwargs `Dict[str, Any]`, *optional*

Optional dict of keyword args to be passed to the attention processor.

None
return_dict `bool`, *optional*, defaults to `True`

Whether to return a dict-like structured output of type AudioVisualModelOutput or a tuple.

True

Returns:

Type Description
Tensor

AudioVisualModelOutput or tuple: If return_dict is True, returns a structured output of type AudioVisualModelOutput, otherwise a tuple is returned where the first element is the denoised video latent patch sequence and the second element is the denoised audio latent patch sequence.

load_weights

load_weights(
    weights: Iterable[tuple[str, Tensor]],
) -> set[str]

Load weights from a pretrained model, mapping separate Q/K/V projections into fused QKV projections for self-attention blocks.

Returns:

Type Description
set[str]

Set of parameter names that were successfully loaded.

create_transformer_from_config

create_transformer_from_config(
    config: dict,
    quant_config: QuantizationConfig | None = None,
) -> LTX2VideoTransformer3DModel

Construct the shared LTX transformer from a Diffusers config.

get_ltx2_post_process_func

get_ltx2_post_process_func(od_config: Any)

Build the common LTX engine-output adapter.

load_transformer_config

load_transformer_config(
    model_path: str,
    subfolder: str = "transformer",
    local_files_only: bool = True,
    *,
    revision: str | None = None,
) -> dict

Load an LTX transformer config from a local model or the HF Hub.