# LTX2VideoTransformer3DModel

[LTX](https://huggingface.co/Lightricks/LTX-2) によって、3Dデータ向けの Diffusion Transformer モデルが紹介されました。

モデルは、以下のコードスニペットで読み込むことができます。

```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 = (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)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_ltx2.py#L1081)

**パラメータ:**

in_channels (`int`、デフォルトは`128`) : 入力におけるチャネル数。

out_channels (`int`、デフォルトは`128`) : 出力のチャネル数。

patch_size (`int`、デフォルトは`1`) : パッチ埋め込み層で使用する空間パッチのサイズ。

patch_size_t (`int`、デフォルトは`1`) : パッチ埋め込み層で使用する時間的パッチのサイズです。

num_attention_heads (`int`、デフォルトは`32`) : マルチヘッドアテンションで使用するヘッド数。

attention_head_dim (`int`、デフォルトは`64`) : 各ヘッドのチャネル数。

cross_attention_dim (`int`、デフォルトは `2048 `) : クロスアテンションヘッドのチャネル数。

num_layers (`int`、デフォルトは`28`) : 使用する Transformer ブロックの層数。

activation_fn (`str`、デフォルトは `"gelu-approximate"`) : feed-forward で使用する活性化関数。

qk_norm (`str`、デフォルトは`"rms_norm_across_heads"`) : 使用する正規化レイヤー。

ff_bias (`bool`、デフォルトは`True`) : ビデオのフィードフォワード層の線形層にバイアス項が含まれるかどうか。`False`がLTX-2.5です。

audio_ff_bias (`bool`、デフォルトは`True`) : 音声フィードフォワード層の線形層にバイアス項が含まれるかどうかを示します。

use_prompt_adaln_single (`bool`、デフォルトは`True`) : プロンプトのクロスアテンションにおける Key/Value 調整がタイムステップに依存するかどうかを指定します。`False` の場合、代わりにレイヤーごとの固定テーブルを使用し、与えられたプロンプトに対して、デノイジングステップ間でクロスアテンションの Key/Value 値をキャッシュ可能にします。

use_keyframes_abs_pos_embedding (`bool`、デフォルトは`False`) : 生成されたキーフレームトークンに対して学習された`(1, inner_dim)`の絶対位置埋め込みを保存するかどうかを指定します（LTX-2.5）。`True`の場合、`video_keyframes_mask`によって選択されたトークンにこの埋め込みが適用されます。この引数は任意です。省略した場合、蒸留済みフォワードパスは変更されません。

[LTX](https://huggingface.co/Lightricks/LTX-Video)で使用する、動画のようなデータ向けのTransformerモデル。

#### 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)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_ltx2.py#L1365)

**パラメータ:**

hidden_states (`torch.Tensor`) : 形状が `(batch_size, num_video_tokens, in_channels)` の、パッチ化された動画の潜在変数を入力します。

audio_hidden_states (`torch.Tensor`) : 形状が `(batch_size, num_audio_tokens, audio_in_channels)` の、パッチ化された入力オーディオ潜在変数。

encoder_hidden_states (`torch.Tensor`) : 形状が `(batch_size, text_seq_len, self.config.caption_channels)` の入力動画テキスト埋め込み。

audio_encoder_hidden_states (`torch.Tensor`) : 形状が `(batch_size, text_seq_len, self.config.caption_channels)` の入力音声テキスト埋め込み。

timestep (`torch.Tensor`) : 形状が `(batch_size, num_video_tokens)` の入力タイムステップ。これらはすでに `self.config.timestep_scale_multiplier` によってスケーリングされている必要があります。

audio_timestep (`torch.Tensor`, *任意*) : 形状が`(batch_size,)`または`(batch_size, num_audio_tokens)`の入力タイムステップ。オーディオモジュレーションパラメータに使用されます。これはI2Vパイプラインなどの特定のパイプラインでのみ使用されます。

sigma (`torch.Tensor`, *任意*) : 形状が (batch_size,) のスケーリング済みタイムステップを入力します。LTX-2.3 などのモデルにおける、ビデオプロンプトのクロスアテンションのモジュレーションに使用されます。

audio_sigma (`torch.Tensor`, *任意*) : 形状が (batch_size,) のスケーリング済みタイムステップを入力します。LTX-2.3 などのモデルにおけるオーディオプロンプトのクロスアテンションのモジュレーションに使用されます。`sigma` が指定されていても `audio_sigma` が指定されていない場合、`audio_sigma` は指定された `sigma` の値に設定されます。

encoder_attention_mask (`torch.Tensor`, *任意*) : 形状が `(batch_size, text_seq_len)` の、乗算的なテキストアテンションマスク（任意）。

audio_encoder_attention_mask (`torch.Tensor`, *任意*) : 音声モデリング用の、形状が `(batch_size, text_seq_len)` の任意の乗法的テキストアテンションマスク。

num_frames (`int`, *任意*) : 潜在ビデオフレームの数。RoPE のビデオ座標を計算する場合に使用されます。

height (`int`、*任意*) : 潜在動画の高さ。RoPE 用の動画座標を計算する場合に使用されます。

width (`int`、*optional*) : 潜在動画の幅。RoPE 用の動画座標を計算する場合に使用されます。

fps : (`float`、*任意*、デフォルトは `24.0`): 生成される動画の希望する秒間フレーム数。RoPE 用の動画座標を計算する場合に使用されます。

audio_num_frames : (`int`、*任意*): 潜在オーディオフレームの数。RoPE のオーディオ座標を計算する場合に使用されます。

video_coords (`torch.Tensor`, *任意*) : `(batch_size, 3, num_video_tokens, 2)` の形状を持つ、回転位置埋め込み (RoPE) を計算する際に使用する動画の座標です。指定されない場合、`forward` の内部で計算されます。

audio_coords (`torch.Tensor`, *任意*) : rotary positional embeddings (RoPE) を計算する際に使用するオーディオ座標で、形状は `(batch_size, 1, num_audio_tokens, 2)` です。指定されない場合、`forward` の内部で計算されます。

isolate_modalities (`bool`、*任意*、デフォルトは`False`) : 各モダリティを分離するために、クロスモダリティ（オーディオからビデオ、およびビデオからオーディオ）のクロスアテンション（すべてのブロック）を無効にするかどうか。LTX-2.3 のモダリティガイダンスに使用します。

spatio_temporal_guidance_blocks (`list[int]`、*任意*、デフォルトは `None`) : 時空間ガイダンス (STG) を適用する Transformer ブロックのインデックスです。STG は、完全なスケーリングドットプロダクトアテンション (SDPA) 演算の代わりに、値を直接使用することで、自己アテンション演算をショートカットします。`None` または空の場合、STG はどのブロックにも適用されません。

perturbation_mask (`torch.Tensor`, *optional*) : STG用のパーターベーションマスク。形状は`(batch_size,)`または`(batch_size, 1, 1)`です。STGを適用するバッチ要素では0、それ以外では1である必要があります。STGを使用しているが`perturbation_mask`が指定されていない場合、デフォルトですべてのバッチ要素にSTG（パーターベーション）が適用されます。

use_cross_timestep (`bool` *optional*、デフォルトは `False`) : クロスアテンションのモジュレーションパラメータを計算する際に、クロスモーダリティ（動画に対するクロスモーダリティは音声、その逆も同様）のシグマを使用するかどうかを指定します。`True` は新しい（例：LTX-2.3）動作であり、`False` は従来の LTX-2.0 の動作です。

attention_kwargs (`dict[str, Any]`、*省略可*) : attention processor に渡すキーワード引数の任意の辞書。

video_self_attention_mask (`torch.Tensor`, *任意*) : 各 Transformer ブロック内の動画自己注意機構に適用される、形状が `(batch_size, num_video_tokens, num_video_tokens)` の任意の乗算型自己注意マスク。`[0, 1]` の範囲の値で、`1` は完全な注意、`0` はマスクを意味します。例えば、IC-LoRA パイプラインでは、ノイズ付きトークンと追加された参照トークンの間の注意強度を制御するために使用されます。音声自己注意には影響しません。

video_keyframes_mask (`torch.Tensor`, *任意*) : 形状が `(batch_size, num_video_tokens, 1)` の、トークンごとの任意のマーカ。単一のピクセルフレームをエンコードする潜在フレームを持つ動画トークンに対して非ゼロになります。これらのトークンは `keyframes_abs_pos_embedding` を受け取ります。モデルが `use_keyframes_abs_pos_embedding` なしで構築された場合は無視されます。

return_dict (`bool`、*任意*、デフォルトは `True`) : `AudioVisualModelOutput` 型の辞書のような構造化された出力を返すか、タプルを返すかを指定します。

**戻り値:** `AudioVisualModelOutput` または `tuple`

`return_dict` が `True` の場合、`AudioVisualModelOutput` 型の構造化された出力を返し、それ以外の場合は `tuple` が返されます。このとき、最初の要素はノイズ除去された動画の潜在パッチシーケンス、2番目の要素はノイズ除去された音声の潜在パッチシーケンスです。

LTX-2.0 音声・映像トランスフォーマーのフォワードパス。