# LTX2VideoTransformer3DModel

Um modelo Diffusion Transformer para dados 3D da [LTX](https://huggingface.co/Lightricks/LTX-2) foi introduzido pela Lightricks.

O modelo pode ser carregado com o seguinte trecho de código.

```python
from diffusers import LTX2VideoTransformer3DModel

transformer = LTX2VideoTransformer3DModel.from_pretrained("Lightricks/LTX-2", subfolder="transformer", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
```

## LTX2VideoTransformer3DModel[[diffusers.LTX2VideoTransformer3DModel]]

#### diffusers.LTX2VideoTransformer3DModel[[diffusers.LTX2VideoTransformer3DModel]]

```python
diffusers.LTX2VideoTransformer3DModel(in_channels: int = 128, out_channels: int | None = 128, patch_size: int = 1, patch_size_t: int = 1, num_attention_heads: int = 32, attention_head_dim: int = 128, cross_attention_dim: int = 4096, vae_scale_factors: tuple[int, int, int] = (8, 32, 32), pos_embed_max_pos: int = 20, base_height: int = 2048, base_width: int = 2048, gated_attn: bool = False, cross_attn_mod: bool = False, audio_in_channels: int = 128, audio_out_channels: int | None = 128, audio_patch_size: int = 1, audio_patch_size_t: int = 1, audio_num_attention_heads: int = 32, audio_attention_head_dim: int = 64, audio_cross_attention_dim: int = 2048, audio_scale_factor: int = 4, audio_pos_embed_max_pos: int = 20, audio_sampling_rate: int = 16000, audio_hop_length: int = 160, audio_gated_attn: bool = False, audio_cross_attn_mod: bool = False, num_layers: int = 48, activation_fn: str = 'gelu-approximate', qk_norm: str = 'rms_norm_across_heads', norm_elementwise_affine: bool = False, norm_eps: float = 1e-06, caption_channels: int = 3840, attention_bias: bool = True, attention_out_bias: bool = True, rope_theta: float = 10000.0, rope_double_precision: bool = True, causal_offset: int = 1, timestep_scale_multiplier: int = 1000, cross_attn_timestep_scale_multiplier: int = 1000, rope_type: str = 'interleaved', use_prompt_embeddings = True, perturbed_attn: bool = False, ff_bias: bool = True, audio_ff_bias: bool = True, use_prompt_adaln_single: bool = True, use_keyframes_abs_pos_embedding: bool = False)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_ltx2.py#L1069)

**Parâmetros:**

in_channels (`int`, padrão `128`) : O número de canais na entrada.

out_channels (`int`, padrão `128`) : O número de canais na saída.

patch_size (`int`, padrão `1`) : O tamanho dos patches espaciais a serem usados na camada de incorporação de patches.

patch_size_t (`int`, padrão `1`) : O tamanho dos patches temporais a serem usados na camada de incorporação de patches.

num_attention_heads (`int`, padrão `32`) : O número de cabeças a serem usadas para a atenção multi-cabeça.

attention_head_dim (`int`, padrão `64`) : O número de canais em cada head.

cross_attention_dim (`int`, padrão `2048 `) : O número de canais para as cabeças de atenção cruzada.

num_layers (`int`, padrão `28`) : O número de blocos de Transformer a serem usados.

activation_fn (`str`, padrão `"gelu-approximate"`) : Função de ativação a ser usada no feed-forward.

qk_norm (`str`, padrão `"rms_norm_across_heads"`) : A camada de normalização a ser usada.

ff_bias (`bool`, padrão `True`) : Se as camadas lineares da camada feed-forward do vídeo incluem um termo de viés. `False` para LTX-2.5.

audio_ff_bias (`bool`, padrão `True`) : Se as camadas lineares da camada feed-forward de áudio incluem um termo de viés.

use_prompt_adaln_single (`bool`, padrão `True`) : Se a modulação de Key/Value da cross-attention do prompt é dependente do timestep. Quando `False`, usa uma tabela fixa por camada, tornando os valores de Key/Value da cross-attention cacheáveis entre as etapas de desruidamento para um prompt dado.

use_keyframes_abs_pos_embedding (`bool`, padrão `False`) : Se deve armazenar um embedding absoluto de posição aprendido `(1, inner_dim)` para tokens de keyframes gerados (LTX-2.5). Quando `True`, os tokens selecionados por `video_keyframes_mask` recebem esse embedding. O argumento é opcional; omiti-lo mantém o caminho de forward destilado inalterado.

Um modelo Transformer para dados semelhantes a vídeo usado no [LTX](https://huggingface.co/Lightricks/LTX-Video).

#### forward[[diffusers.LTX2VideoTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, audio_hidden_states: Tensor, encoder_hidden_states: Tensor, audio_encoder_hidden_states: Tensor, timestep: LongTensor, audio_timestep: typing.Optional[torch.LongTensor] = None, sigma: typing.Optional[torch.Tensor] = None, audio_sigma: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.Tensor] = None, audio_encoder_attention_mask: typing.Optional[torch.Tensor] = 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: typing.Optional[torch.Tensor] = None, audio_coords: typing.Optional[torch.Tensor] = None, isolate_modalities: bool = False, spatio_temporal_guidance_blocks: list[int] | None = None, perturbation_mask: typing.Optional[torch.Tensor] = None, use_cross_timestep: bool = False, attention_kwargs: dict[str, typing.Any] | None = None, video_self_attention_mask: typing.Optional[torch.Tensor] = None, video_keyframes_mask: typing.Optional[torch.Tensor] = None, return_dict: bool = True)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_ltx2.py#L1353)

**Parâmetros:**

hidden_states (`torch.Tensor`) : Latentes de vídeo em patches de entrada, com forma `(batch_size, num_video_tokens, in_channels)`.

audio_hidden_states (`torch.Tensor`) : Latentes de áudio em patches de entrada, com forma `(batch_size, num_audio_tokens, audio_in_channels)`.

encoder_hidden_states (`torch.Tensor`) : Embeddings de texto do vídeo de entrada, com forma `(batch_size, text_seq_len, self.config.caption_channels)`.

audio_encoder_hidden_states (`torch.Tensor`) : Embeddings de texto de áudio de entrada com forma `(batch_size, text_seq_len, self.config.caption_channels)`.

timestep (`torch.Tensor`) : Timestep de entrada com forma `(batch_size, num_video_tokens)`. Estes devem já ter sido escalados por `self.config.timestep_scale_multiplier`.

audio_timestep (`torch.Tensor`, *opcional*) : Timestep de entrada com forma `(batch_size,)` ou `(batch_size, num_audio_tokens)` para os parâmetros de modulação de áudio. Isso é usado apenas por determinados pipelines, como o pipeline I2V.

sigma (`torch.Tensor`, *opcional*) : Timestep de entrada escalado com forma (batch_size,). Usado para modulação de atenção cruzada de prompt de vídeo em modelos como LTX-2.3.

audio_sigma (`torch.Tensor`, *opcional*) : Timestep de entrada escalonado com forma (batch_size,). Usado para modulação de atenção cruzada de prompt de áudio em modelos como LTX-2.3. Se `sigma` for fornecido, mas `audio_sigma` não, `audio_sigma` será definido para o valor de `sigma` fornecido.

encoder_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atenção de texto multiplicativa opcional com forma `(batch_size, text_seq_len)`.

audio_encoder_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atenção de texto multiplicativa opcional de forma `(batch_size, text_seq_len)` para modelagem de áudio.

num_frames (`int`, *opcional*) : O número de quadros de vídeo latentes. Usado ao calcular as coordenadas do vídeo para o RoPE.

height (`int`, *opcional*) : A altura do vídeo latente. Usada ao calcular as coordenadas do vídeo para o RoPE.

width (`int`, *opcional*) : A largura do vídeo latente. Usado ao calcular as coordenadas do vídeo para o RoPE.

fps : (`float`, *opcional*, padrão `24.0`): Os quadros por segundo desejados do vídeo gerado. Usado ao calcular as coordenadas do vídeo para o RoPE.

audio_num_frames : (`int`, *opcional*): O número de quadros de áudio latentes. Usado ao calcular as coordenadas de áudio para o RoPE.

video_coords (`torch.Tensor`, *opcional*) : As coordenadas do vídeo a serem usadas ao calcular os embeddings posicionais rotativos (RoPE) de forma `(batch_size, 3, num_video_tokens, 2)`. Se não fornecidas, serão calculadas dentro de `forward`.

audio_coords (`torch.Tensor`, *opcional*) : As coordenadas de áudio a serem usadas ao calcular os embeddings posicionais rotativos (RoPE) de forma `(batch_size, 1, num_audio_tokens, 2)`. Se não fornecidas, serão calculadas dentro de `forward`.

isolate_modalities (`bool`, *opcional*, padrão `False`) : Se deve isolar cada modalidade desativando a atenção cruzada entre modalidades (de áudio para vídeo e de vídeo para áudio) em todos os blocos. Use para orientação de modalidade no LTX-2.3.

spatio_temporal_guidance_blocks (`list[int]`, *opcional*, padrão `None`) : Os índices dos blocos do transformer nos quais aplicar o direcionamento espaço-temporal (STG), que encurta as operações de autoatenção usando simplesmente os valores em vez da operação completa de atenção de produto escalar normalizado (SDPA). Se `None` ou vazio, o STG não será aplicado a nenhum bloco.

perturbation_mask (`torch.Tensor`, *opcional*) : Máscara de perturbação para STG com forma `(batch_size,)` ou `(batch_size, 1, 1)`. Deve ser 0 nos elementos do lote onde o STG deve ser aplicado e 1 nos demais. Se o STG estiver sendo usado, mas `perturbation_mask` não for fornecido, o padrão será aplicar o STG (perturbar) todos os elementos do lote.

use_cross_timestep (`bool` *opcional*, padrão `False`) : Se deve usar o sigma da modalidade cruzada (áudio é a modalidade cruzada de vídeo, e vice-versa) ao calcular os parâmetros de modulação da atenção cruzada. `True` é o comportamento mais recente (por exemplo, LTX-2.3); `False` é o comportamento legado do LTX-2.0.

attention_kwargs (`dict[str, Any]`, *opcional*) : Dicionário opcional de argumentos de palavra-chave a serem passados para o processador de atenção.

video_self_attention_mask (`torch.Tensor`, *opcional*) : Máscara opcional de autoatenção multiplicativa de forma `(batch_size, num_video_tokens, num_video_tokens)` aplicada à autoatenção do vídeo em cada bloco do transformer. Valores em `[0, 1]`, onde `1` significa atenção total e `0` significa mascarado. Usado, por exemplo, pelo pipeline IC-LoRA para controlar a intensidade da atenção entre tokens ruidosos e tokens de referência anexados. A autoatenção de áudio não é afetada.

video_keyframes_mask (`torch.Tensor`, *opcional*) : Marcador opcional por token, de forma `(batch_size, num_video_tokens, 1)`, não nulo nos tokens de vídeo cujo quadro latente codifica um quadro de pixel único. Esses tokens recebem `keyframes_abs_pos_embedding`. Ignorado quando o modelo foi construído sem `use_keyframes_abs_pos_embedding`.

return_dict (`bool`, *opcional*, padrão `True`) : Se deve retornar uma saída estruturada em formato de dicionário do tipo `AudioVisualModelOutput` ou uma tupla.

**Retorna:** `AudioVisualModelOutput` ou `tuple`

Se `return_dict` for `True`, retorna uma saída estruturada do tipo `AudioVisualModelOutput`; caso contrário, uma `tuple` é retornada, em que o primeiro elemento é a sequência de patches latentes do vídeo dessonada e o segundo elemento é a sequência de patches latentes do áudio dessonada.

Passada para frente do transformador audiovisual de vídeo LTX-2.0.