Diffusers documentation
LTX-2
LTX-2
LTX-2 est un modèle de fondation basé sur DiT, conçu pour générer de la vidéo et de l’audio synchronisés au sein d’un seul modèle. Il réunit les briques fondamentales de la génération vidéo moderne, avec des poids ouverts et une orientation vers une exécution locale et pratique.
Vous pouvez trouver tous les points de contrôle originaux de LTX-Video sous l'organisation Lightricks.
Le code source original de LTX-2 peut être trouvé ici.
Génération en deux étapes
Les valeurs par défaut du __call__ partagé de LTX2Pipeline / LTX2ImageToVideoPipeline correspondent à la référence LTX-2.5 (num_inference_steps=30 ; num_frames est facultatif lorsqu'un duration_head est présent, sinon il retombe sur 121). Les exemples ci-dessous utilisent ces valeurs par défaut pour LTX-2.0/2.3 également.
Pipeline recommandé pour obtenir une génération de qualité production, ce pipeline est composé de deux étapes :
- Étape 1 : générer une vidéo à la résolution cible en utilisant l'échantillonnage par diffusion avec un guidage sans classifieur (CFG). Cette étape produit une séquence vidéo cohérente à faible bruit qui respecte le conditionnement texte/image.
- Étape 2 : Augmenter la résolution de la sortie de l'étape 1 par un facteur de 2 et affiner les détails à l'aide d'un modèle LoRA distillé pour améliorer la fidélité et la qualité visuelle. L'étape 2 peut appliquer un CFG plus léger pour préserver la structure de l'étape 1 tout en améliorant la texture et la netteté.
Exemple d'utilisation du pipeline de génération de vidéo à partir de texte en deux étapes
import torch
from diffusers import FlowMatchEulerDiscreteScheduler
from diffusers.pipelines.ltx2 import LTX2Pipeline, LTX2LatentUpsamplePipeline
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.utils import STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video
device = "cuda:0"
width = 768
height = 512
pipe = LTX2Pipeline.from_pretrained(
"Lightricks/LTX-2", dtype=torch.bfloat16
)
pipe.enable_sequential_cpu_offload(device=device)
prompt = "A beautiful sunset over the ocean"
negative_prompt = "shaky, glitchy, low quality, worst quality, deformed, distorted, disfigured, motion smear, motion artifacts, fused fingers, bad anatomy, weird hand, ugly, transition, static."
# Stage 1 default (non-distilled) inference
frame_rate = 24.0
video_latent, audio_latent = pipe(
prompt=prompt,
negative_prompt=negative_prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=30,
sigmas=None,
guidance_scale=3.0,
output_type="latent",
return_dict=False,
)
latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
"Lightricks/LTX-2",
subfolder="latent_upsampler",
dtype=torch.bfloat16,
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
upsample_pipe.enable_model_cpu_offload(device=device)
upscaled_video_latent = upsample_pipe(
latents=video_latent,
output_type="latent",
return_dict=False,
)[0]
# Load Stage 2 distilled LoRA
pipe.load_lora_weights(
"Lightricks/LTX-2", adapter_name="stage_2_distilled", weight_name="ltx-2-19b-distilled-lora-384.safetensors"
)
pipe.set_adapters("stage_2_distilled", 1.0)
# VAE tiling is usually necessary to avoid OOM error when VAE decoding
pipe.vae.enable_tiling()
# Change scheduler to use Stage 2 distilled sigmas as is
new_scheduler = FlowMatchEulerDiscreteScheduler.from_config(
pipe.scheduler.config, use_dynamic_shifting=False, shift_terminal=None
)
pipe.scheduler = new_scheduler
# Stage 2 inference with distilled LoRA and sigmas
video, audio = pipe(
latents=upscaled_video_latent,
audio_latents=audio_latent,
prompt=prompt,
negative_prompt=negative_prompt,
num_inference_steps=3,
noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0], # renoise with first sigma value https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/ti2vid_two_stages.py#L218
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_lora_distilled_sample.mp4",
)Génération de points de contrôle distillés
Pipeline de génération en deux étapes le plus rapide, utilisant un point de contrôle distillé.
import torch
from diffusers.pipelines.ltx2 import LTX2Pipeline, LTX2LatentUpsamplePipeline
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES, STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "rootonchair/LTX-2-19b-distilled"
pipe = LTX2Pipeline.from_pretrained(
model_path, dtype=torch.bfloat16
)
pipe.enable_sequential_cpu_offload(device=device)
prompt = "A beautiful sunset over the ocean"
negative_prompt = "shaky, glitchy, low quality, worst quality, deformed, distorted, disfigured, motion smear, motion artifacts, fused fingers, bad anatomy, weird hand, ugly, transition, static."
frame_rate = 24.0
video_latent, audio_latent = pipe(
prompt=prompt,
negative_prompt=negative_prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=8,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
generator=generator,
output_type="latent",
return_dict=False,
)
latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
model_path,
subfolder="latent_upsampler",
dtype=torch.bfloat16,
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
upsample_pipe.enable_model_cpu_offload(device=device)
upscaled_video_latent = upsample_pipe(
latents=video_latent,
output_type="latent",
return_dict=False,
)[0]
video, audio = pipe(
latents=upscaled_video_latent,
audio_latents=audio_latent,
prompt=prompt,
negative_prompt=negative_prompt,
num_inference_steps=3,
noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0], # renoise with first sigma value https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/distilled.py#L178
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
generator=generator,
guidance_scale=1.0,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_distilled_sample.mp4",
)Génération du pipeline de condition
Vous pouvez utiliser LTX2ConditionPipeline pour spécifier des conditions d’image et/ou de vidéo à des indices latents arbitraires. Par exemple, nous pouvons spécifier à la fois une condition de première image et une condition de dernière image pour effectuer une génération first-last-frame-to-video (FLF2V) :
import torch
from diffusers import LTX2ConditionPipeline, LTX2LatentUpsamplePipeline
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2VideoCondition
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES, STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video
from diffusers.utils import load_image
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "rootonchair/LTX-2-19b-distilled"
pipe = LTX2ConditionPipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
prompt = (
"CG animation style, a small blue bird takes off from the ground, flapping its wings. The bird's feathers are "
"delicate, with a unique pattern on its chest. The background shows a blue sky with white clouds under bright "
"sunshine. The camera follows the bird upward, capturing its flight and the vastness of the sky from a close-up, "
"low-angle perspective."
)
first_image = load_image(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_first_frame.png",
)
last_image = load_image(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_last_frame.png",
)
first_cond = LTX2VideoCondition(frames=first_image, index=0, strength=1.0)
last_cond = LTX2VideoCondition(frames=last_image, index=-1, strength=1.0)
conditions = [first_cond, last_cond]
frame_rate = 24.0
video_latent, audio_latent = pipe(
conditions=conditions,
prompt=prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=8,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
generator=generator,
output_type="latent",
return_dict=False,
)
latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
model_path,
subfolder="latent_upsampler",
dtype=torch.bfloat16,
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
upsample_pipe.enable_model_cpu_offload(device=device)
upscaled_video_latent = upsample_pipe(
latents=video_latent,
output_type="latent",
return_dict=False,
)[0]
video, audio = pipe(
latents=upscaled_video_latent,
audio_latents=audio_latent,
prompt=prompt,
width=width * 2,
height=height * 2,
num_inference_steps=3,
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
generator=generator,
guidance_scale=1.0,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_distilled_flf2v.mp4",
)Vous pouvez utiliser à la fois des conditions d'image et de vidéo :
import torch
from diffusers import LTX2ConditionPipeline
from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2VideoCondition
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT
from diffusers.utils import load_image, load_video
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "rootonchair/LTX-2-19b-distilled"
pipe = LTX2ConditionPipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
prompt = (
"The video depicts a long, straight highway stretching into the distance, flanked by metal guardrails. The road is "
"divided into multiple lanes, with a few vehicles visible in the far distance. The surrounding landscape features "
"dry, grassy fields on one side and rolling hills on the other. The sky is mostly clear with a few scattered "
"clouds, suggesting a bright, sunny day. And then the camera switch to a winding mountain road covered in snow, "
"with a single vehicle traveling along it. The road is flanked by steep, rocky cliffs and sparse vegetation. The "
"landscape is characterized by rugged terrain and a river visible in the distance. The scene captures the "
"solitude and beauty of a winter drive through a mountainous region."
)
cond_video = load_video(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cosmos/cosmos-video2world-input-vid.mp4"
)
cond_image = load_image(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cosmos/cosmos-video2world-input.jpg"
)
video_cond = LTX2VideoCondition(frames=cond_video, index=0, strength=1.0)
image_cond = LTX2VideoCondition(frames=cond_image, index=8, strength=1.0)
conditions = [video_cond, image_cond]
frame_rate = 24.0
video, audio = pipe(
conditions=conditions,
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=30,
guidance_scale=3.0,
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_cond_video.mp4",
)Comme le conditionnement est effectué via des images latentes, les 8 images de l'espace des données correspondant à l'image latente spécifiée pour une condition d'image tendront à être statiques.
Guidage multimodal
Les pipelines LTX-2.X prennent en charge le guidage multimodal. Il est composé de trois termes, tous utilisant une règle de mise à jour de type CFG :
- Guidage sans classifieur (CFG) : CFG standard où la sortie perturbée (« plus faible ») est générée à l'aide du prompt négatif.
- Guidance spatio-temporelle (STG) : STG s'écarte d'une sortie perturbée créée en court-circuitant les opérations d'auto-attention et substitue à la place les valeurs d'attention. L'idée est que cela crée des vidéos plus nettes et une meilleure cohérence spatio-temporelle.
- Guidance d'isolation de la modalité : s'écarte d'une sortie perturbée créée en désactivant l'attention croisée inter-modalités (audio-vers-vidéo et vidéo-vers-audio). Cette guidance est plus spécifique aux modèles LTX-2.X, avec l'idée qu'elle produit une meilleure cohérence entre l'audio et la vidéo générés.
Ces paramètres sont contrôlés par les arguments guidance_scale, stg_scale et modality_scale et peuvent être définis séparément pour la vidéo et l’audio. De plus, pour STG, il est nécessaire de spécifier les indices des blocs du transformer où l’auto-attention est ignorée via l’argument spatio_temporal_guidance_blocks. Les pipelines LTX-2.X prennent également en charge le guidance rescaling pour aider à réduire l’exposition excessive, un problème qui peut survenir lorsque les échelles de guidance sont fixées à des valeurs élevées.
import torch
from diffusers import LTX2ImageToVideoPipeline
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT
from diffusers.utils import load_image
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "diffusers/LTX-2.3-Diffusers"
pipe = LTX2ImageToVideoPipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
prompt = (
"An astronaut hatches from a fragile egg on the surface of the Moon, the shell cracking and peeling apart in "
"gentle low-gravity motion. Fine lunar dust lifts and drifts outward with each movement, floating in slow arcs "
"before settling back onto the ground. The astronaut pushes free in a deliberate, weightless motion, small "
"fragments of the egg tumbling and spinning through the air. In the background, the deep darkness of space subtly "
"shifts as stars glide with the camera's movement, emphasizing vast depth and scale. The camera performs a "
"smooth, cinematic slow push-in, with natural parallax between the foreground dust, the astronaut, and the "
"distant starfield. Ultra-realistic detail, physically accurate low-gravity motion, cinematic lighting, and a "
"breath-taking, movie-like shot."
)
image = load_image(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg",
)
video, audio = pipe(
image=image,
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=30,
guidance_scale=3.0, # Recommended LTX-2.3 guidance parameters
stg_scale=1.0, # Note that 0.0 (not 1.0) means that STG is disabled (all other guidance is disabled at 1.0)
modality_scale=3.0,
guidance_rescale=0.7,
audio_guidance_scale=7.0, # Note that a higher CFG guidance scale is recommended for audio
audio_stg_scale=1.0,
audio_modality_scale=3.0,
audio_guidance_rescale=0.7,
spatio_temporal_guidance_blocks=[28],
use_cross_timestep=True,
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_3_i2v_stage_1.mp4",
)Amélioration du prompt
Les modèles LTX-2.X sont sensibles au style de formulation des prompts. Consultez le guide officiel de formulation des prompts pour des recommandations sur la rédaction d’un bon prompt. L’utilisation de l’amélioration de prompt, où les prompts fournis sont enrichis à l’aide de l’encodeur de texte du pipeline (par défaut un modèle Gemma 3) à partir d’un prompt système, peut également améliorer la qualité des échantillons. Le composant de pipeline optionnel processor doit être présent pour utiliser l’amélioration de prompt. Activez-le avec enable_prompt_enhancement=True et un system_prompt (opt-in, conforme aux pipelines de référence Lightricks) :
import torch
from transformers import Gemma3Processor
from diffusers import LTX2Pipeline
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT, T2V_DEFAULT_SYSTEM_PROMPT
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "diffusers/LTX-2.3-Diffusers"
pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_model_cpu_offload(device=device)
pipe.vae.enable_tiling()
if getattr(pipe, "processor", None) is None:
processor = Gemma3Processor.from_pretrained("google/gemma-3-12b-it-qat-q4_0-unquantized")
pipe.processor = processor
prompt = (
"An astronaut hatches from a fragile egg on the surface of the Moon, the shell cracking and peeling apart in "
"gentle low-gravity motion. Fine lunar dust lifts and drifts outward with each movement, floating in slow arcs "
"before settling back onto the ground. The astronaut pushes free in a deliberate, weightless motion, small "
"fragments of the egg tumbling and spinning through the air. In the background, the deep darkness of space subtly "
"shifts as stars glide with the camera's movement, emphasizing vast depth and scale. The camera performs a "
"smooth, cinematic slow push-in, with natural parallax between the foreground dust, the astronaut, and the "
"distant starfield. Ultra-realistic detail, physically accurate low-gravity motion, cinematic lighting, and a "
"breath-taking, movie-like shot."
)
video, audio = pipe(
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=30,
guidance_scale=3.0,
stg_scale=1.0,
modality_scale=3.0,
guidance_rescale=0.7,
audio_guidance_scale=7.0,
audio_stg_scale=1.0,
audio_modality_scale=3.0,
audio_guidance_rescale=0.7,
spatio_temporal_guidance_blocks=[28],
use_cross_timestep=True,
enable_prompt_enhancement=True,
system_prompt=T2V_DEFAULT_SYSTEM_PROMPT,
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_3_t2v_stage_1.mp4",
)LTX-2.5
LTX-2.5 réutilise les mêmes classes LTX2Pipeline/LTX2VideoTransformer3DModel/AutoencoderKLLTX2Video/etc. que LTX-2.3 — il n'existe pas de classe de pipeline distincte pour ce modèle. La différence visible pour l'utilisateur réside dans l'encodeur de texte : LTX-2.5 est associé à un point de contrôle Gemma 4 (gemma4_unified) au lieu de Gemma 3. Ce dernier est chargé automatiquement lors de l'appel de from_pretrained sur un point de contrôle LTX-2.5 converti (via les classes Auto* de transformers), de sorte qu'aucune configuration supplémentaire n'est nécessaire au moment de l'inférence — il suffit de diriger from_pretrained vers un dépôt LTX-2.5 plutôt qu'un dépôt LTX-2.3.
Lightricks/LTX-2.5-Diffusers fournit les deux transformers : le DiT distillé dans transformer/, auquel model_index.json pointe, et le DiT complet/SFT dans transformer_full/, qui doit être chargé explicitement (voir Transformer complet / SFT). Le scheduler/ du dépôt est configuré pour le checkpoint distillé (use_dynamic_shifting=False, shift_terminal=None) afin que son calendrier de sigmas soit utilisé tel quel. Tout ce dont la génération en deux étapes a besoin y est également fourni : un sous-dossier latent_upsampler/ et le LoRA distillé de l’étape 2, ltx-2.5-22b-distilled-lora-450-bf16.safetensors, à la racine du dépôt.
L’inférence distillée est pilotée par un calendrier sigma explicite plutôt que par un nombre d’étapes, et s’exécute sans guidage (guidance_scale=1.0, donc negative_prompt n’est pas utilisé). Transmettre num_inference_steps à la place fournirait au modèle un calendrier linéaire générique et entraînerait une perte de qualité silencieuse :
import torch
from diffusers import LTX2Pipeline
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "Lightricks/LTX-2.5-Diffusers"
pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
prompt = "A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees."
video, audio = pipe(
prompt=prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
audio_guidance_scale=1.0,
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_t2v.mp4",
)Génération en deux étapes pour LTX-2.5
LTX-2.5 prend en charge les deux variantes à deux étapes, et DISTILLED_SIGMA_VALUES / STAGE_2_DISTILLED_SIGMA_VALUES sont ses plans de référence :
- Point de contrôle distillé, les deux étapes — la recette de référence pour le
transformer/par défaut, et celle présentée ci-dessous. Aucun LoRA d'étape 2 n'est impliqué, car le transformer est déjà distillé ; il s'agit de la Génération du point de contrôle distillé avec les poids LTX-2.5. - Étape 1 Full/SFT + étape 2 LoRA distillé — Génération en deux étapes comme décrit en haut de cette page, en utilisant
transformer_full/et le LoRA fourni. Voir ci-dessous pour les modifications.
L’étape 1 s’exécute à la moitié de la résolution cible, l’amplificateur de résolution la double, et l’étape 2 affine à la résolution complète — vidéo et audio, toutes deux réinitialisées à partir des latents de l’étape 1 avec noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0]. La hauteur et la largeur doivent être divisibles par 64, car l’étape 1 divise chaque axe par deux et doit toujours correspondre à la grille spatiale du VAE.
import torch
from diffusers.pipelines.ltx2 import LTX2Pipeline, LTX2LatentUpsamplePipeline
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES, STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video
device = "cuda" # or "mps", "xpu", "cpu"
width = 1536
height = 1024
num_frames = 121
frame_rate = 24.0
model_path = "Lightricks/LTX-2.5-Diffusers"
# One generator for the whole call, threaded through both stages, so stage 2 continues the noise
# stream instead of repeating stage 1's draw.
generator = torch.Generator(device).manual_seed(42)
pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
prompt = "A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees."
# Stage 1: half resolution, 8 distilled sigmas
video_latent, audio_latent = pipe(
prompt=prompt,
width=width // 2,
height=height // 2,
num_frames=num_frames,
frame_rate=frame_rate,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
audio_guidance_scale=1.0,
generator=generator,
output_type="latent",
return_dict=False,
)
latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
model_path,
subfolder="latent_upsampler",
dtype=torch.bfloat16,
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
upsample_pipe.enable_model_cpu_offload(device=device)
# `latents_normalized=False`: `output_type="latent"` already applied the latent statistics, and the
# upsampler is trained on denormalized latents. Stage 2 renormalizes them in `prepare_latents`.
upscaled_video_latent = upsample_pipe(
latents=video_latent,
latents_normalized=False,
output_type="latent",
return_dict=False,
)[0]
# Stage 2: full resolution, 3 sigmas, reseeded from stage 1. Pass `num_frames` explicitly here --
# omitting it would run the duration head a second time instead of using the stage 1 length.
pipe.vae.enable_tiling()
video, audio = pipe(
prompt=prompt,
latents=upscaled_video_latent,
audio_latents=audio_latent,
width=width,
height=height,
num_frames=num_frames,
frame_rate=frame_rate,
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0], # renoise with the stage 2 entry sigma
guidance_scale=1.0,
audio_guidance_scale=1.0,
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_t2v_two_stages.mp4",
)Lorsque la longueur provient de la tête de durée plutôt que d’un num_frames explicite, laissez l’étape 1 décider et récupérer la longueur réalisée à partir de ses latents ([B, C, F, H, W]) avant l’exécution de l’étape 2, au lieu de prédire une seconde fois :
num_frames = (video_latent.shape[2] - 1) * pipe.vae_temporal_compression_ratio + 1Étape 2 avec le LoRA distillé
Pour exécuter la génération en deux étapes à la place — DiT complet/SFT pour l’étape 1, LoRA distillé pour l’étape 2 —, construisez le pipeline comme indiqué dans transformer complet / SFT et générez les latents de l’étape 1 avec cette pile de guidage. Deux éléments diffèrent alors de LTX-2.0/2.3. Le LoRA se trouve dans le dépôt diffusers lui-même plutôt qu’à côté des poids d’origine, et l’inversion du planificateur se fait dans l’autre sens : LTX-2.5 fournit la configuration du planificateur distillé, de sorte que c’est l’étape 1 qui a activé le décalage dynamique, et l’étape 2 qui le désactive à nouveau.
pipe.load_lora_weights(
"Lightricks/LTX-2.5-Diffusers",
adapter_name="stage_2_distilled",
weight_name="ltx-2.5-22b-distilled-lora-450-bf16.safetensors",
)
pipe.set_adapters("stage_2_distilled", 1.0)
pipe.vae.enable_tiling()
pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(
pipe.scheduler.config, use_dynamic_shifting=False, shift_terminal=None
)L'étape de suréchantillonnage et l'appel de l'étape 2 sont inchangés par rapport à la recette distillée ci-dessus : mêmes sigmas=STAGE_2_DISTILLED_SIGMA_VALUES, même noise_scale et guidance_scale=1.0, car l'étape 2 exécute de toute façon un modèle distillé.
Décodage convolutif et par diffusion
LTX-2.5 fournit deux décodeurs vidéo sur le même espace latent, de sorte que les latents sont interchangeables entre eux :
vae/— le VAE convolutif (AutoencoderKLLTX2Video). C’est lui que les pipelines utilisent pour le décodage, donc tous les extraits ci-dessus l’emploient déjà, et c’est le seul des deux à prendre en charge le tuilage (pipe.vae.enable_tiling()), ce qui permet généralement de faire tenir une haute résolution.diffusion_decoder/— LTX2VideoDiffusionDecoderModel. Il s’agit d’un modèle de diffusion à part entière et non d’un composant de pipeline, il n’est donc pas transmis en tant quevae: exécutez le pipeline avecoutput_type="latent"et transmettez les latents à LTX2VideoDiffusionDecodePipeline.
L'encodage passe toujours par vae/, de sorte que le conditionnement par image et par vidéo n'est pas affecté par le choix effectué.
Deux éléments changent lors du décodage avec le décodeur de diffusion. output_type="latent" passe également par le vocoder, de sorte que l’audio est renvoyé sous forme de latents et doit être finalisé manuellement, et le processeur NATTEN est en pratique obligatoire aux résolutions vidéo :
import torch
from diffusers import LTX2Pipeline, LTX2VideoDiffusionDecodePipeline, LTX2VideoDiffusionDecoderModel
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video
device = "cuda" # or "mps", "xpu", "cpu"
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(42)
model_path = "Lightricks/LTX-2.5-Diffusers"
pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_model_cpu_offload(device=device)
prompt = "A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees."
latents, audio_latents = pipe(
prompt=prompt,
width=960,
height=544,
num_frames=121,
frame_rate=frame_rate,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
audio_guidance_scale=1.0,
generator=generator,
output_type="latent",
return_dict=False,
)
# `output_type="latent"` skips the vocoder, so finish the audio by hand. These latents are already
# denormalized, which is what `audio_vae.decode` expects.
mel = pipe.audio_vae.decode(audio_latents.to(pipe.audio_vae.dtype), return_dict=False)[0]
audio = pipe.vocoder(mel)
decoder = LTX2VideoDiffusionDecoderModel.from_pretrained(
model_path, subfolder="diffusion_decoder", dtype=torch.bfloat16
).to(device)
# The decoder runs on the `flex` backend by default, and uncompiled `flex_attention` materializes the
# full score matrix -- tens of GB at video resolutions. NATTEN's kernels are what the original
# implementation uses; they are fetched from the Hub by `kernels` (`pip install kernels`), not from a
# local NATTEN build. Switching the attention *backend* instead raises: only `flex` takes the BlockMask.
decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())
# Decode in overlapping tiles so peak memory scales with the tile size rather than the video size.
decoder.enable_tiling()
decode_pipe = LTX2VideoDiffusionDecodePipeline(diffusion_decoder=decoder, scheduler=pipe.scheduler)
# `denormalize=False`: `output_type="latent"` already applied the latent statistics, so applying them
# again would rescale every channel by its std a second time. The decoder draws the noise it denoises,
# so pass a generator to make decoding reproducible.
video = decode_pipe(
latents, generator=generator, output_type="np", denormalize=False, return_dict=False
)[0]
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_t2v_diffusion_decode.mp4",
)Pour combiner cela avec la génération en deux étapes, demandez à l'étape 2 de produire output_type="latent" et décodez ce résultat.
decoder.enable_tiling() est ce qui permet de maintenir un décodage haute résolution en mémoire, de la même manière que pipe.vae.enable_tiling() le fait pour le VAE convolutif. La partie du décodage qui domine la consommation mémoire — l’étape finale de suréchantillonnage et l’étape de diffusion — s’exécute alors sur des tuiles superposées qui sont ensuite fusionnées, de sorte que la mémoire de pointe est limitée par la taille de la tuile plutôt que par la taille de la vidéo. Le découpage en tuiles n’entre en jeu que lorsque le latent dépasse une tuile, et les tailles de tuile et de chevauchement peuvent être ajustées via les arguments tile_sample_min_* / tile_sample_stride_* (les valeurs par défaut correspondent à l’implémentation de référence). Étant donné que l’étape de diffusion débruite chaque tuile séparément, un décodage en tuiles ne reproduit pas exactement le résultat non découpé.
Sur une carte unique, il est également judicieux de déplacer le pipeline hors de la mémoire GPU avant le décodage (pipe.to("cpu") et torch.cuda.empty_cache(), après avoir capturé pipe.scheduler et le output_sampling_rate du vocodeur), car le décodeur a besoin de sa propre marge de manœuvre. Consultez LTX2VideoDiffusionDecoderModel pour les backends d’attention, les détails du tuilage et le reste du comportement du décodeur.
Transformeur complet / SFT
transformer_full/ n’est pas référencé par model_index.json, il faut donc le charger explicitement. Il nécessite également un scheduler différent et une pile de guidance réelle : le scheduler/ fourni est configuré pour le checkpoint distillé, et les valeurs par défaut de guidance sont des génériques de l’ère LTX-2.0 qui laissent un run SFT LTX-2.5 visiblement sous-guidé sans déclencher d’alerte. Les recommandations de Multimodal Guidance s’appliquent ici sans modification, y compris le STG sur le bloc 28 :
import torch
from diffusers import FlowMatchEulerDiscreteScheduler, LTX2Pipeline, LTX2VideoTransformer3DModel
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT
device = "cuda" # or "mps", "xpu", "cpu"
model_path = "Lightricks/LTX-2.5-Diffusers"
# Passing `transformer=` keeps `from_pretrained` from fetching the distilled folder as well.
transformer = LTX2VideoTransformer3DModel.from_pretrained(
model_path, subfolder="transformer_full", dtype=torch.bfloat16
)
pipe = LTX2Pipeline.from_pretrained(model_path, transformer=transformer, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
# Re-enable dynamic shifting and the terminal shift, which the distilled configuration turns off.
pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(
pipe.scheduler.config, use_dynamic_shifting=True, shift_terminal=0.1
)
video, audio = pipe(
prompt="A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees.",
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=768,
height=512,
num_frames=121,
frame_rate=24.0,
num_inference_steps=30,
guidance_scale=3.0,
stg_scale=1.0,
modality_scale=3.0,
guidance_rescale=0.7,
audio_guidance_scale=7.0,
audio_stg_scale=1.0,
audio_modality_scale=3.0,
audio_guidance_rescale=0.7,
spatio_temporal_guidance_blocks=[28],
use_cross_timestep=True,
generator=torch.Generator(device).manual_seed(42),
output_type="np",
return_dict=False,
)Déposez sigmas ici — le DiT complet récupère son calendrier depuis le scheduler.
Amélioration des prompts pour LTX-2.5
L’utilisation de l’amélioration du prompt est fortement recommandée pour LTX-2.5 ; passez enable_prompt_enhancement=True pour l’activer (comme dans les pipelines de référence Lightricks). Contrairement à LTX-2.0/2.3, où le même point de contrôle de l’encodeur de texte sert également d’améliorateur (voir Amélioration du prompt ci-dessus), l’encodeur de texte affiné de LTX-2.5 n’a pas été entraîné pour l’amélioration. À la place, l’amélioration utilise un point de contrôle distinct, prêt à l’emploi, google/gemma-4-E2B-it. Chargez-le dans les composants optionnels prompt_enhancer/processor du pipeline, puis activez l’amélioration — le pipeline utilise par défaut LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT et la recette Gemma 4 (do_sample=False, no_repeat_ngram_size=5, max_new_tokens=600). Passez un system_prompt= explicite pour le remplacer :
import torch
from transformers import AutoModelForImageTextToText, AutoProcessor
from diffusers import LTX2Pipeline
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "Lightricks/LTX-2.5-Diffusers"
enhancer_model_id = "google/gemma-4-E2B-it"
pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_model_cpu_offload(device=device)
pipe.vae.enable_tiling()
if getattr(pipe, "prompt_enhancer", None) is None:
pipe.prompt_enhancer = AutoModelForImageTextToText.from_pretrained(enhancer_model_id)
pipe.processor = AutoProcessor.from_pretrained(enhancer_model_id)
prompt = "A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees."
video, audio = pipe(
prompt=prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
audio_guidance_scale=1.0,
enable_prompt_enhancement=True,
# No `system_prompt=` needed -- defaults to `LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT` when `prompt_enhancer` is set.
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_t2v_enhanced.mp4",
)Il en va de même pour la génération vidéo à partir d’image avec LTX2ImageToVideoPipeline : configurez pipe.prompt_enhancer/pipe.processor de la même manière et passez enable_prompt_enhancement=True (en utilisant LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, avec un conditionnement à la fois sur l’image de référence et sur le prompt texte) — encore une fois, aucun system_prompt= n’est nécessaire, sauf si vous souhaitez le remplacer.
Durée automatique pour LTX-2.5
Les points de contrôle LTX-2.5 incluent un petit duration_head qui prédit la durée de la séquence décrite, à partir de la même sortie de connecteur de texte sur laquelle le transformateur est conditionné. Lorsque le pipeline chargé en possède un, num_frames est prédit automatiquement par défaut — omettez-le et le modèle choisira la durée :
video, audio = pipe(prompt=prompt, output_type="np", return_dict=False)Pour définir la longueur vous-même, passez explicitement num_frames. Un entier l’emporte toujours sur la tête :
video, audio = pipe(prompt=prompt, num_frames=121, output_type="np", return_dict=False)Les pipelines chargés à partir de points de contrôle LTX-2.0 ou LTX-2.3 ne disposent pas de tête de durée et conservent la valeur par défaut précédente de 121 images, ce qui ne change donc rien pour eux.
Passez min_seconds / max_seconds pour contraindre la prédiction. La prédiction brute est bornée dans l'intervalle, puis convertie en images :
video, audio = pipe(
prompt=prompt,
min_seconds=2.0,
max_seconds=10.0,
frame_rate=frame_rate,
output_type="np",
return_dict=False,
)Les nombres de frames prédits sont arrondis à la grille temporelle causale du VAE (8k + 1), si bien que la durée réalisée est quantifiée — environ 0,33 s par pas à 24 fps — et elle varie avec frame_rate, car la tête prédit des secondes plutôt que des frames. min_seconds doit être strictement inférieur à max_seconds. Ces bornes sont ignorées lorsque num_frames est défini explicitement.
Des bornes plus étroites qu'une étape de grille peuvent ne pas être satisfaites exactement : à 24 fps, [1.0s, 1.02s] se convertit en [24, 24] images, et 24 n'est pas de la forme 8k + 1. Le point de grille le plus proche est utilisé et un avertissement est consigné, de sorte que la longueur renvoyée peut se situer juste en dehors de bornes aussi strictes.
Pour inspecter une prédiction sans générer de vidéo, appelez directement la tête. Tout ce dont elle a besoin est public :
prompt_embeds, prompt_attention_mask, _, _ = pipe.encode_prompt(prompt, do_classifier_free_guidance=False)
video_tokens, audio_tokens, _ = pipe.connectors(prompt_embeds, prompt_attention_mask)
num_frames = pipe.duration_head.predict_num_frames(
video_tokens,
audio_tokens,
frame_rate=24.0,
temporal_compression_ratio=pipe.vae_temporal_compression_ratio,
)
seconds = pipe.duration_head(video_tokens, audio_tokens).item() # raw, before clamping
print(f"predicted {seconds:.2f}s -> {num_frames} frames")La conversion d’un point de contrôle 2.5 récupère automatiquement la tête avec --full_pipeline, ou de manière isolée avec --duration_head. Les points de contrôle antérieurs à la version 2.5 ne contiennent pas de tels poids, et la conversion ignore ce composant au lieu d’échouer.
Vitesse de mouvement pour LTX-2.5
LTX-2 place chaque jeton vidéo sur un axe temporel en secondes, dérivé par défaut de frame_rate, le taux de lecture. motion_speed (valeur par défaut 1.0) sépare les deux : l’axe temporel est conditionné par frame_rate / motion_speed, tandis que la durée de l’audio, la duration head et la vidéo renvoyée suivent toujours frame_rate. Avec frame_rate=24.0 et motion_speed=0.2, le modèle est informé que l’action a été capturée à 120 images par seconde et que le résultat est lu à 24 images par seconde, ce qui produit un ralenti de 5x.
Le modèle de base est entraîné aux alentours de 24/25/30/60 fps, de sorte que des vitesses très éloignées de 1.0 n’ont de sens qu’avec un adaptateur entraîné à cet effet, tel que Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control (accès restreint : acceptez d’abord sa licence sur le Hub). Sans motion_speed, ce LoRA se charge comme un LoRA standard et ne fournit aucun contrôle du mouvement. La fiche modèle suggère des vitesses de 1.0, 0.5, 0.2, 0.1, 0.05 et 0.025, avec une intensité LoRA de 1.0. Omettez les termes de vitesse (« slow motion », « high fps ») du prompt et réutilisez la même légende pour toutes les vitesses, car motion_speed à lui seul pilote l’effet.
import torch
from diffusers import LTX2ImageToVideoPipeline
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video, load_image
device = "cuda" # or "mps", "xpu", "cpu"
width = 1920 # the LoRA's recommended resolution; the effect is much weaker at 768x512
height = 1088
frame_rate = 24.0 # playback rate, always 24 for this LoRA
model_path = "Lightricks/LTX-2.5-Diffusers"
pipe = LTX2ImageToVideoPipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.load_lora_weights(
"Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control",
weight_name="ltx-2.5-22b-lora-slow-motion-control-1.0.safetensors",
adapter_name="slow_motion",
)
pipe.set_adapters("slow_motion", 1.0)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
image = load_image(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
)
# No speed wording: the same caption is reused at every speed.
prompt = (
"An astronaut hatches from a fragile egg on the surface of the Moon, the shell cracking apart and lunar dust "
"lifting into the air, while the camera pushes in."
)
for motion_speed in (1.0, 0.2):
video, audio = pipe(
image=image,
prompt=prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
motion_speed=motion_speed, # 1.0 = real time, 0.2 = 5x slow motion
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
audio_guidance_scale=1.0,
generator=torch.Generator(device).manual_seed(42),
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate, # the file plays at the playback rate, not frame_rate / motion_speed
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path=f"ltx2_5_i2v_motion_speed_{motion_speed}.mp4",
)Les deux extraits durent 121 images (environ 5 secondes à 24 images par seconde) et seul le rythme du mouvement change. Dans la génération en deux étapes, passez la même valeur de motion_speed aux deux étapes. L'étape 2 ré-applique le débruitage à la vidéo et annulerait le ralenti si elle s'exécutait sur l'axe du temps réel. Le pilote de référence fait de même en encapsulant l'objet d'étape partagé par les deux passages.
motion_speed est également une entrée des blocs modulaires LTX-2 / LTX-2.5, et elle est transmise au pipeline modulaire de la même manière.
LTX-2.5 Modulaire
LTX-2.5 est également disponible sous forme de pipeline modulaire. Le jeu de blocs par défaut utilise le décodeur de diffusion et prédit la durée de la vidéo lorsque num_frames est omis. Il applique le guidage séparément à la vidéo et à l’audio via les composants guider et audio_guider. Consultez LTX2Guidance pour les paramètres de guidage disponibles. Par défaut, le pipeline modulaire télécharge l’améliorateur et le processeur de prompt depuis le dépôt google/gemma-4-E2B-it. Voici un exemple modulaire T2V :
import torch
from diffusers import ModularPipeline, ComponentsManager
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT
from diffusers.utils import encode_video
device = "cuda" # or "mps", "xpu", "cpu"
frame_rate = 24.0
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "Lightricks/LTX-2.5-Diffusers"
cm = ComponentsManager()
pipe = ModularPipeline.from_pretrained(model_path, components_manager=cm)
pipe.load_components(dtype=torch.bfloat16)
# Set memory_reserve_margin higher to more aggressively offload component models
cm.enable_auto_cpu_offload(device=device, memory_reserve_margin="20GB")
# The NATTEN processor works if `kernels` is available (`pip install kernels`)
# Otherwise omit the below line to use the Flex Attention processor
pipe.diffusion_decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())
pipe.diffusion_decoder.enable_tiling()
prompt = (
"A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees."
)
output_state = pipe(
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=768,
height=512,
num_frames=None, # Set to an int (e.g. 121) to specify a fixed video length
frame_rate=frame_rate,
num_inference_steps=30,
use_cross_timestep=True,
enable_prompt_enhancement=True,
generator=generator,
output_type="np",
)
video = output_state.get("videos")
audio = output_state.get("audio")
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_modular_t2v.mp4",
)Le pipeline modulaire basculera automatiquement les flux de travail en fonction des entrées fournies. Par exemple, si image est fourni, un flux de travail I2V sera utilisé :
import torch
from diffusers import ModularPipeline, ComponentsManager
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT
from diffusers.utils import encode_video, load_image
device = "cuda" # or "mps", "xpu", "cpu"
frame_rate = 24.0
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "Lightricks/LTX-2.5-Diffusers"
cm = ComponentsManager()
pipe = ModularPipeline.from_pretrained(model_path, components_manager=cm)
pipe.load_components(dtype=torch.bfloat16)
cm.enable_auto_cpu_offload(device=device, memory_reserve_margin="20GB")
pipe.diffusion_decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())
pipe.diffusion_decoder.enable_tiling()
prompt = (
"An astronaut hatches from a fragile egg on the surface of the Moon, the shell cracking and peeling apart in "
"gentle low-gravity motion."
)
image_path = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
image = load_image(image_path)
output_state = pipe(
image=image,
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=768,
height=512,
num_frames=None, # Set to an int (e.g. 121) to specify a fixed video length
frame_rate=frame_rate,
num_inference_steps=30,
use_cross_timestep=True,
enable_prompt_enhancement=True,
generator=generator,
output_type="np",
)
video = output_state.get("videos")
audio = output_state.get("audio")
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_modular_i2v.mp4",
)Vous pouvez consulter les workflows pris en charge dans la documentation de chaque blockset (par exemple LTX2AutoBlocks, LTX25AutoBlocks).
Rendu de fidélité par diffusion (DFR) pour LTX-2.5
LTX2DFRPipeline échange le temps réel contre la fidélité des détails. Chaque __call__ est un passage de débruitage à height × width : il génère une vidéo ainsi que des slots de keyframes supplémentaires de type image à un seul pixel, ou il débruite à nouveau des latents fournis, initialisés à partir de ces slots. Les appelants composent les étapes de la même manière que pour les autres pipelines LTX à deux étapes — ce pipeline, LTX2LatentUpsamplePipeline, ce pipeline à nouveau, puis LTX2DFRTemporalRefinePipeline pour chaque passe temporelle.
Un slot coûte un cadre latent complet de jetons pour acheter un cadre pixel, ce qui relâche la compression temporelle effective à cette position — la vidéo environnante est donc conditionnée sur des cadres réellement nouveaux plutôt que sur des cadres interpolés. Les positions des slots proviennent d'une grille de segments alignée sur la frontière temporelle du VAE (24 ou 32 cadres pixel, selon celle qui minimise le bourrage de la requête). La toile est bourrée à un nombre entier de segments en interne ; output_type="latent" renvoie cette grille bourrée afin qu'un slot situé sur le bourrage ne soit pas supprimé. Effectuez un rognage avec trim_canvas avant le décodage VAE.
Cela nécessite un transformer dont la configuration définit use_keyframes_abs_pos_embedding, ce qui marque les latents de trames monoxel avec un embedding appris. Les points de contrôle LTX-2.5 l’incluent ; le pipeline lève une erreur pour toute version antérieure plutôt que de gaspiller le budget de jetons sur des jetons qu’il ne peut pas interpréter.
Budget pour les jetons supplémentaires : chaque slot ajoute l’équivalent d’une frame latente, de sorte que l’étape 2 exécute une séquence plus longue que le passage distillé à deux étapes équivalent — +31 % à 1024x1536 / 121 frames (24576 -> 32256 jetons, 5 slots sur une grille de segments de 24 frames). La mémoire d’activation au pic évolue en conséquence, si bien qu’une résolution qui correspond juste à la recette distillée standard peut nécessiter enable_sequential_cpu_offload, vae.enable_tiling(), ou un canevas plus petit sous DFR.
La composition utilise return_dict=True pour keyframes et keyframe_positions (return_dict=False renvoie les mêmes quatre champs sous forme de tuple).
La recette complète ci-dessous est celle à privilégier pour démarrer : image-vers-vidéo 1088×1920, un tour de raffinement temporel x2, et le IC-LoRA de détail spatial x2 en étape 2.
import torch
from diffusers import (
LTX2DFRPipeline,
LTX2DFRTemporalRefinePipeline,
LTX2LatentUpsamplePipeline,
LTXEulerAncestralRFScheduler,
)
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.utils import trim_canvas
from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2VideoCondition
from diffusers.pipelines.ltx2.utils import STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video, load_image
pipe = LTX2DFRPipeline.from_pretrained("Lightricks/LTX-2.5-Diffusers", torch_dtype=torch.bfloat16)
latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
"Lightricks/LTX-2.5-Diffusers", subfolder="latent_upsampler", torch_dtype=torch.bfloat16
)
# The x2 temporal upsampler is not in the published `model_index.json` — convert it with
# `--temporal_latent_upsampler`.
temporal_latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
"path/to/converted/temporal_latent_upsampler", torch_dtype=torch.bfloat16
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
temporal_pipe = LTX2DFRTemporalRefinePipeline(
scheduler=LTXEulerAncestralRFScheduler(eta=0.5),
vae=pipe.vae,
audio_vae=pipe.audio_vae,
text_encoder=pipe.text_encoder,
tokenizer=pipe.tokenizer,
connectors=pipe.connectors,
transformer=pipe.transformer,
vocoder=pipe.vocoder,
temporal_latent_upsampler=temporal_latent_upsampler,
)
# All three pipelines share the same components, so place them together. Do not call
# `enable_model_cpu_offload()` on one of them: its hooks would own modules the other two also call,
# and `temporal_latent_upsampler` — held only by `temporal_pipe` — would never reach the device.
pipe.to("cuda")
upsample_pipe.to("cuda")
temporal_pipe.to("cuda")
image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png")
prompt = "A tabby cat stretching in a sunlit window, dust motes drifting in the light"
conditions = [LTX2VideoCondition(frames=image, index=0, strength=1.0)]
height, width = 1088, 1920
frame_rate = 24.0
generator = torch.Generator(device="cuda").manual_seed(0)
num_frames = 121
out = pipe(
prompt=prompt,
conditions=conditions,
height=height // 2,
width=width // 2,
num_frames=num_frames,
frame_rate=frame_rate,
generator=generator,
output_type="latent",
)
up_video = upsample_pipe(latents=out.frames, output_type="latent", return_dict=False)[0]
up_keyframes = upsample_pipe(latents=out.keyframes, output_type="latent", return_dict=False)[0]
# Load after stage 1 so the adapter is never disabled. `set_adapters` does not re-enable a
# transformer that already had `disable_adapters()` called on it.
pipe.load_lora_weights("Lightricks/LTX-2.5-22b-IC-LoRA-Pixel-Spatial-Upscaler", adapter_name="detailing")
pipe.set_adapters(["detailing"], adapter_weights=[0.5])
out2 = pipe(
prompt=prompt,
conditions=conditions,
latents=up_video,
audio_latents=out.audio,
keyframes_latents=up_keyframes,
keyframe_positions=out.keyframe_positions,
reference_latents=out.frames,
height=height,
width=width,
num_frames=num_frames,
frame_rate=frame_rate,
noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0],
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
generator=generator,
output_type="latent",
)
pipe.transformer.disable_adapters()
# `num_frames` here is the *padded* canvas the latents actually cover, which `resolve_canvas` may have
# grown past the 121 that were asked for. `condition_num_frames` stays the original request so a
# negative `condition.index` does not wrap onto the pad.
ratio = pipe.vae.temporal_compression_ratio
canvas_frames = (out2.frames.shape[2] - 1) * ratio + 1
out3 = temporal_pipe(
latents=out2.frames,
keyframes_latents=out2.keyframes,
keyframe_positions=out2.keyframe_positions,
audio_latents=out.audio,
prompt=prompt,
conditions=conditions,
height=height,
width=width,
num_frames=canvas_frames,
frame_rate=frame_rate,
source_seconds=canvas_frames / frame_rate,
condition_num_frames=num_frames,
generator=generator,
output_type="latent",
)
# Keep the padded canvas until decode so a slot on the pad is not dropped. `trim_canvas` counts *pixel*
# frames, and the round mapped `N -> 2 (N - 1) + 1`.
playback_fps = frame_rate * 2
requested_frames = (num_frames - 1) * 2 + 1
video_latents = trim_canvas(out3.frames, requested_frames, ratio)
timestep = None
if pipe.vae.config.timestep_conditioning:
timestep = torch.zeros(video_latents.shape[0], device=video_latents.device, dtype=pipe.vae.dtype)
video = pipe.vae.decode(video_latents.to(pipe.vae.dtype), timestep, return_dict=False)[0]
video = pipe.video_processor.postprocess_video(video, output_type="np")
# Audio is stage 1's. Cut it to the video's duration so a muxed container does not outlast the picture.
audio = pipe.vocoder(pipe.audio_vae.decode(out.audio.to(pipe.audio_vae.dtype), return_dict=False)[0])
audio_samples = round(requested_frames / playback_fps * pipe.vocoder.config.output_sampling_rate)
audio = audio[..., : min(audio.shape[-1], audio_samples)]
encode_video(
video[0],
fps=playback_fps,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_dfr.mp4",
)height et width correspondent à ce passage, et non à la sortie finale. L’étape 1 s’exécute à la moitié du canevas 1080p (544×960) ; l’étape 2 à 1088×1920. Chacun doit être divisible par le ratio de compression spatiale du VAE (32 sur LTX-2.5 pour un passage unique ; 64 lorsque l’étape 1 est la moitié du 1080p). C’est pourquoi le 1080p est 1920×1088 et le 4K est 3840×2176. Chaque passage exécute un calendrier distillé fixe (sigmas), il n’y a donc pas de num_inference_steps ; les calendriers distillés sont entraînés sans guidage, il n’y a donc pas non plus de negative_prompt ou de guidance_scale. L’audio fourni est celui de l’étape 1 — les passages ultérieurs exécutent toujours un flux audio afin que la branche vidéo dispose d’une attention intermodale ; la forme d’onde elle-même n’est pas affinée après l’étape 1.
Détail spatial. Chargez l’IC-LoRA de détail spatial 2x sous un adaptateur nommé après l’étape 1 et activez-le uniquement pour l’étape 2 (set_adapters(["detailing"], adapter_weights=[0.5])). L’étape 2 porte alors son attention sur le latent de demi-résolution de l’étape 1 en tant que reference_latents. L’étape 1 et les passes temporelles s’exécutent avec l’adaptateur désactivé. Si vous chargez le LoRA avant l’étape 1, transformer.disable_adapters() le désactive, et set_adapters ne le réactive pas — appelez transformer.enable_adapters() avant l’étape 2, ou chargez les poids après l’étape 1 comme dans la recette. reference_downscale_factor (valeur par défaut 2) met à l’échelle les coordonnées spatiales des jetons de référence dans l’espace de coordonnées de la cible.
Raffinement temporel. LTX2DFRTemporalRefinePipeline correspond à un seul passage : suréchantillonnage temporel, tuilage aux coutures des images clés, débruitage ancestral avec LTXEulerAncestralRFScheduler (eta=0.5), assemblage par suppression de l’intro de la tuile suivante, et fusion du sac d’images clés portées. Construisez ce planificateur vous-même — le passage est refusé avec tout autre planificateur, car une étape déterministe s’exécuterait jusqu’au bout et ne renverrait qu’une toile plus douce. Appelez le pipeline une fois par passage ; bouclez pour 2x / 4x en transmettant round_index. Après un passage, keyframe_positions ne peut plus être redéduit du num_frames d’origine et doit être transmis tel quel. Chaque tuile reçoit la portion de l’audio figé de l’étape 1 couvrant sa propre fenêtre de lecture. source_seconds est la durée de l’étape 1 et reste fixe d’un passage à l’autre, les passages suivants doivent donc le transmettre explicitement plutôt que de prendre la valeur par défaut.
Le fps de conditionnement est de 60 dès que la lecture dépasse 30, indépendamment du multiplexage : le temps de RoPE est pixel_frame / fps, donc une base temporelle de 120 fps réduirait de moitié l’étendue temporelle de chaque jeton par rapport à la distribution d’entraînement, tandis que 48 fps l’étirerait. Les deux mentent en affirmant être à 60 et traitent les images décodées au taux de lecture.
Une troisième étape spatiale. Composez-la ; il n'existe pas de quatrième pipeline. Effectuez un suréchantillonnage spatial de la vidéo uniquement, reconstruisez les images clés de transport en RGB (decode → Lanczos ×2 → encode via rebuild_epilogue_keyframes() ; ne faites jamais de suréchantillonnage latent des images clés de l'épilogue), puis :
from diffusers.pipelines.ltx2.dfr_layout import epilogue_tiles, pixel_to_latent_index
# One more doubling on top of the recipe above, so every stage below the output halves again:
# `epilogue_height` must be divisible by 128 (`4 * 32`), which is why 4K is 3840x2176.
epilogue_height, epilogue_width = height * 2, width * 2
refined_frames = (out3.frames.shape[2] - 1) * ratio + 1
up_video = upsample_pipe(latents=out3.frames, output_type="latent", return_dict=False)[0]
epilogue_keyframes = pipe.rebuild_epilogue_keyframes(
out3.keyframes,
decode_timestep=0.0,
decode_noise_scale=0.0,
seed=0,
device=up_video.device,
dtype=torch.float32,
)
# Temporal cuts land on the seams the *last* round stitched on -- the positions handed into it, doubled --
# not on every carry keyframe, since the slots that round invented sit mid-window.
tiles = epilogue_tiles(
latent_shape=(
(refined_frames - 1) // ratio + 1,
epilogue_height // pipe.vae.spatial_compression_ratio,
epilogue_width // pipe.vae.spatial_compression_ratio,
),
frame_tiles=2, # 2 ** number of temporal rounds
frame_seams=[pixel_to_latent_index(2 * p, ratio) for p in out2.keyframe_positions],
)
pipe.transformer.enable_adapters() # the epilogue is a detailing pass too
out4 = pipe(
prompt=prompt,
conditions=conditions,
latents=up_video,
audio_latents=out.audio,
generate_slots=False,
guidance_keyframe_latents=epilogue_keyframes,
guidance_keyframe_positions=out3.keyframe_positions,
reference_latents=out3.frames,
height=epilogue_height,
width=epilogue_width,
num_frames=refined_frames,
frame_rate=playback_fps,
noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0],
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
freeze_audio=True,
video_tiles=tiles,
generator=generator,
output_type="latent",
)
pipe.transformer.disable_adapters()Les deux axes sont assemblés différemment. Aucun des deux côtés d'une frontière spatiale ne détient une réponse connue, de sorte que ces chevauchements sont fusionnés avec des poids trapézoïdaux. Les tuiles temporelles sont découpées sur les coutures des images clés de la dernière passe de raffinement.
Décodage avec le décodeur de diffusion. Pour une fidélité maximale des détails, restez sur output_type="latent" et transmettez les latents (déjà dénormalisés, éventuellement trim_canvas‘d) à LTX2VideoDiffusionDecodePipeline.
from diffusers import LTX2VideoDiffusionDecodePipeline
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoDiffusionDecoderModel
decoder = LTX2VideoDiffusionDecoderModel.from_pretrained(
"Lightricks/LTX-2.5-Diffusers", subfolder="diffusion_decoder", dtype=torch.bfloat16
)
decode_pipe = LTX2VideoDiffusionDecodePipeline(
diffusion_decoder=decoder, scheduler=pipe.scheduler, vae=pipe.vae
)
decode_pipe.enable_model_cpu_offload()
# `denormalize=False`: the `output_type="latent"` path already applied the latent statistics.
video = decode_pipe(latents=out3.frames, denormalize=False, output_type="np", return_dict=False)[0]LTX2Pipeline
classe diffusers.LTX2Pipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
Paramètres
- transformer (LTXVideoTransformer3DModel) — Architecture Transformer conditionnelle pour débruyer les latents vidéo encodés.
- scheduler (FlowMatchEulerDiscreteScheduler) —
Un planificateur à utiliser en combinaison avec
transformerpour débruyer les latents d'image encodés. - vae (AutoencoderKLLTXVideo) — Modèle de Variational Auto-Encoder (VAE) pour encoder et décoder des images vers et depuis des représentations latentes.
- text_encoder (
T5EncoderModel) — T5, plus précisément la variante google/t5-v1_1-xxl. - tokenizer (
CLIPTokenizer) — Tokeniseur de la classe CLIPTokenizer. - tokenizer (
T5TokenizerFast) — Deuxième Tokenizer de la classe T5TokenizerFast. - connectors (
LTX2TextConnectors) — Pile de connecteurs de texte utilisée pour adapter les états cachés de l’encodeur de texte aux branches vidéo et audio.
Pipeline pour la génération de vidéos à partir de texte.
Référence : https://github.com/Lightricks/LTX-Video
__call__
< source >( prompt: str | list[str] = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 512width: int = 768num_frames: int | None = Nonemin_seconds: float = 1.0max_seconds: float = 20.0frame_rate: float = 24.0motion_speed: float = 1.0num_inference_steps: int = 30sigmas: list[float] | None = Nonetimesteps: list[int] = Noneguidance_scale: float = 3.0stg_scale: float = 1.0modality_scale: float = 3.0guidance_rescale: float = 0.7audio_guidance_scale: float | None = 7.0audio_stg_scale: float | None = 1.0audio_modality_scale: float | None = 3.0audio_guidance_rescale: float | None = 0.7spatio_temporal_guidance_blocks: list[int] | None = [28]noise_scale: float = 0.0num_videos_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10output_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Paramètres
- prompt (
stroulist[str], facultatif) — Le prompt ou les prompts pour guider la génération d’image. S’il n’est pas défini, il faut passerprompt_embedsà la place. - negative_prompt (
stroulist[str], facultatif) — Le ou les prompts à ne pas utiliser pour guider la génération d’image. S’il n’est pas défini, il faut passernegative_prompt_embedsà la place. Ignoré lorsque le guidage n’est pas utilisé (guidance_scale < 1). - height (
int, facultatif, par défaut512) — La hauteur en pixels de l'image générée. Cette valeur est fixée à 480 par défaut pour obtenir les meilleurs résultats. - width (
int, facultatif, par défaut768) — La largeur en pixels de l'image générée. Cette valeur est fixée à 848 par défaut pour obtenir les meilleurs résultats. - num_frames (
int, facultatif) — Le nombre de frames vidéo à générer. Si non fourni, la valeur par défaut est une durée prédite automatiquement lorsque ce pipeline possède un composantduration_head(checkpoints LTX-2.5 et ultérieurs), et121sinon. Transmettez un entier pour définir explicitement la longueur. Les compteurs prédits automatiquement sont alignés sur la grille temporelle causale du VAE, de sorte que la durée réalisée est quantifiée (environ 0,33 s à 24 fps). - min_seconds (
float, facultatif, valeur par défaut1.0) — Limite inférieure de la durée prédite automatiquement lorsquenum_framesest omis et qu’uneduration_headest présente. Ignoré lorsquenum_framesest défini explicitement. - max_seconds (
float, facultatif, par défaut20.0) — Limite supérieure de la durée prédite automatiquement lorsquenum_framesest omis et qu’unduration_headest présent. Ignoré lorsquenum_framesest défini explicitement. Doit être strictement supérieur àmin_seconds. - frame_rate (
float, facultatif, par défaut24.0) — Le nombre d'images par seconde (IPS) de la vidéo générée. - motion_speed (
float, facultatif, par défaut1.0) — Vitesse du mouvement par rapport au temps réel. Les embeddings positionnels sont conditionnés surframe_rate / motion_speed, de sorte que les valeurs inférieures à 1 ralentissent le mouvement, par exemple0.2pour le ralenti 5x du LoRA Slow-Motion-Control.frame_ratereste le taux de lecture : la durée audio et le nombre de frames prédit en dépendent. - num_inference_steps (
int, facultatif, valeur par défaut 30) — Le nombre d'étapes de débruitage. Un plus grand nombre d'étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d'une inférence plus lente. - sigmas (
List[float], facultatif) — Sigmas personnalisés à utiliser pour le processus de débruitage avec les planificateurs qui prennent en charge un argumentsigmasdans leur méthodeset_timesteps. S'il n'est pas défini, le comportement par défaut lorsquenum_inference_stepsest passé sera utilisé. - timesteps (
list[int], facultatif) — Timesteps personnalisés à utiliser pour le processus de débruitage avec les planificateurs qui prennent en charge un argumenttimestepsdans leur méthodeset_timesteps. S'il n'est pas défini, le comportement par défaut lorsquenum_inference_stepsest passé sera utilisé. Doit être dans l'ordre décroissant. - guidance_scale (
float, facultatif, par défaut4.0) — Échelle de guidage telle que définie dans Classifier-Free Diffusion Guidance.guidance_scaleest défini commewde l'équation 2 de Imagen Paper. L'échelle de guidage est activée en définissantguidance_scale > 1. Une échelle de guidage plus élevée encourage la génération d'images étroitement liées auprompttexte, généralement au détriment de la qualité de l'image. Utilisé pour la modalité vidéo (il existe une valeur distincteaudio_guidance_scalepour la modalité audio). - stg_scale (
float, facultatif, valeur par défaut0.0) — Échelle de guidage vidéo pour le Spatio-Temporal Guidance (STG), proposée dans Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. Le STG utilise une estimation de type CFG où l’on déplace l’échantillon loin d’un échantillon faible issu d’une version perturbée du modèle de débruitage. L’activation du STG entraîne un passage avant supplémentaire du modèle de débruitage ; la valeur par défaut de0.0signifie que le STG est désactivé. - modality_scale (
float, facultatif, valeur par défaut1.0) — Échelle de guidage vidéo pour l’isolation des modalités dans LTX-2.X, où l’on éloigne l’échantillon d’un échantillon plus faible généré par le modèle de débruitage avec l’attention croisée inter-modalités (audio-vers-vidéo et vidéo-vers-audio) désactivée, en utilisant une estimation de type CFG. L’activation du guidage par modalité entraîne un passage avant supplémentaire du modèle de débruitage ; la valeur par défaut de1.0signifie que le guidage par modalité est désactivé. - guidance_rescale (
float, facultatif, valeur par défaut 0.0) — Facteur de rescaling du guidance proposé par Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaleest défini commeφdans l'équation 16. de Common Diffusion Noise Schedules and Sample Steps are Flawed. Le facteur de rescaling du guidance doit corriger l'exposition excessive lors de l'utilisation d'un SNR terminal nul. Utilisé pour la modalité vidéo. - audio_guidance_scale (
float, facultatif, par défautNone) — Échelle de guidage audio pour le CFG par rapport au prompt négatif. La règle de mise à jour du CFG est la même pour la vidéo et l’audio, mais des valeurs différentes peuvent être utilisées pour l’échelle de guidage. Les auteurs de LTX-2.X suggèrent queaudio_guidance_scaledoit être plus élevé par rapport àguidance_scalede la vidéo (par exemple, pour LTX-2.3, ils suggèrent 3.0 pour la vidéo et 7.0 pour l’audio). SiNone, la valeur par défaut est celle de la vidéoguidance_scale. - audio_stg_scale (
float, facultatif, valeur par défautNone) — Échelle de guidage audio pour STG. Comme pour CFG, la règle de mise à jour STG est sinon identique pour la vidéo et l’audio. Pour LTX-2.3, une valeur de 1.0 est suggérée pour la vidéo et l’audio. SiNone, la valeur par défaut est la valeur vidéostg_scale. - audio_modality_scale (
float, facultatif, valeur par défautNone) — Échelle de guidage audio pour l’isolation des modalités de LTX-2.X. Comme pour CFG, la règle de guidage des modalités est sinon la même pour la vidéo et l’audio. Pour LTX-2.3, une valeur de 3.0 est suggérée pour la vidéo et l’audio. SiNone, la valeur par défaut est la valeur vidéomodality_scale. - audio_guidance_rescale (
float, facultatif, valeur par défautNone) — Facteur de rescaling de guidance distinct pour la modalité audio. SiNone, la valeur par défaut est celle de la vidéoguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], facultatif, valeur par défautNone) — Indices des blocs de transformer (à partir de zéro) auxquels appliquer le STG. Doit être fourni si le STG est utilisé (stg_scaleouaudio_stg_scaleest supérieur à0). Une valeur de[29]est recommandée pour LTX-2.0 et[28]est recommandée pour LTX-2.3. - noise_scale (
float, facultatif, valeur par défaut0.0) — Le facteur d’interpolation entre le bruit aléatoire et les latents débruités à chaque pas de temps. Applique un bruit auxlatentset auxaudio_latentsavant de poursuivre le débruitage. - num_videos_per_prompt (
int, facultatif, valeur par défaut 1) — Le nombre de vidéos à générer par invite. - generator (
torch.Generatoroulist[torch.Generator], facultatif) — Un ou une liste de générateurs torch pour rendre la génération déterministe. - latents (
torch.Tensor, facultatif) — Latents bruités pré-générés, échantillonnés à partir d’une distribution gaussienne, à utiliser comme entrées pour la génération de vidéo. Peut être utilisé pour ajuster la même génération avec des prompts différents. S’il n’est pas fourni, un tenseur de latents sera généré par échantillonnage à l’aide dugeneratoraléatoire fourni. - audio_latents (
torch.Tensor, facultatif) — Latents bruités pré-générés, échantillonnés à partir d’une distribution gaussienne, à utiliser comme entrées pour la génération audio. Peut être utilisé pour ajuster la même génération avec des prompts différents. S’il n’est pas fourni, un tenseur de latents sera généré par échantillonnage à l’aide dugeneratoraléatoire fourni. - prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, les embeddings de texte seront générés à partir de l'argument d'entréeprompt. - prompt_attention_mask (
torch.Tensor, facultatif) — Masque d'attention pré-généré pour les embeddings de texte. - negative_prompt_embeds (
torch.FloatTensor, facultatif) — Embeddings de texte négatifs pré-générés. Pour PixArt-Sigma, ce prompt négatif doit être "". S'il n'est pas fourni, negative_prompt_embeds sera généré à partir de l'argument d'entréenegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, facultatif) — Masque d'attention pré-généré pour les embeddings de texte négatifs. - decode_timestep (
float, par défaut0.0) — Le timestep auquel la vidéo générée est décodée. - decode_noise_scale (
float, par défautNone) — Le facteur d'interpolation entre le bruit aléatoire et les latents débruités à l'étape de décodage. - use_cross_timestep (
boolfacultatif, par défautTrue) — Indique s'il faut utiliser le sigma de la modalité croisée (l'audio est la modalité croisée de la vidéo, et inversement) lors du calcul des paramètres de modulation de l'attention croisée.Truecorrespond au comportement de LTX-2.3/2.5 ;Falsecorrespond au comportement hérité de LTX-2.0. - system_prompt (
str, facultatif, par défautNone) — Prompt système facultatif à utiliser pour l’amélioration du prompt. Le prompt système sera utilisé par l’améliorateur de prompt (un modèle de génération conditionnelle Gemma — le composant dédiéprompt_enhancers’il est configuré, sinon letext_encoderprincipal) pour générer un prompt amélioré à partir dupromptd’origine afin de conditionner la génération. S’il n’est pas fourni et qu’unprompt_enhancerdédié est configuré (LTX-2.5), la valeur par défaut estLTX2_5_T2V_DEFAULT_SYSTEM_PROMPT(depuisdiffusers.pipelines.ltx2.utils) — voirenable_prompt_enhancement. - enable_prompt_enhancement (
bool, facultatif, valeur par défautFalse) — Indique s'il faut exécuter l'amélioration du prompt. Option, conformément aux pipelines de référence Lightricks. SiTrueet quesystem_promptest omis, LTX-2.5 utiliseLTX2_5_T2V_DEFAULT_SYSTEM_PROMPTsi unprompt_enhancerdédié est configuré ; LTX-2.0/2.3 nécessitent unsystem_promptexplicite. - prompt_max_new_tokens (
int, facultatif, valeur par défautNone) — Nombre maximal de nouveaux jetons à générer lors de l'amélioration du prompt. Si non fourni, utilise 600 pour unprompt_enhancerGemma 4 dédié (LTX-2.5) ou 512 pour letext_encoderGemma 3 de secours (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], facultatif, par défautNone) — Arguments par mot-clé pour l’appel.generatede l’améliorateur de prompt. S’ils ne sont pas fournis, ils correspondent toujours au modèle qui effectue l’amélioration :do_sample=False, no_repeat_ngram_size=5(glouton) lors de l’utilisation d’unprompt_enhancerdédié (LTX-2.5), oudo_sample=True, temperature=0.7pour le repli sur letext_encoder(LTX-2.0/2.3). Voir https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate pour plus de détails. - prompt_enhancement_seed (
int, facultatif, par défaut10) — Graine aléatoire pour toute opération aléatoire lors de l'amélioration du prompt. - output_type (
str, facultatif, par défaut"pil") — Le format de sortie de l'image générée. Choisissez entre PIL :PIL.Image.Imageounp.array. - return_dict (
bool, facultatif, par défautTrue) — Indique s'il faut retourner un~pipelines.ltx.LTX2PipelineOutputplutôt qu'un simple tuple. - attention_kwargs (
dict, facultatif) — Un dictionnaire de kwargs qui, s'il est spécifié, est transmis à l'AttentionProcessordéfini sousself.processordans diffusers.models.attention_processor. - callback_on_step_end (
Callable, facultatif) — Une fonction appelée à la fin de chaque étape de débruitage pendant l'inférence. La fonction est appelée avec les arguments suivants :callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargscontiendra une liste de tous les tenseurs spécifiés parcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, facultatif, par défaut["latents"]) — La liste des entrées tensorielles pour la fonctioncallback_on_step_end. Les tenseurs spécifiés dans la liste seront passés en tant qu'argumentcallback_kwargs. Vous ne pourrez inclure que les variables listées dans l'attribut._callback_tensor_inputsde votre classe de pipeline. - max_sequence_length (
int, facultatif, par défaut1024) — Longueur maximale de la séquence à utiliser avec leprompt.
Retourne
~pipelines.ltx.LTX2PipelineOutput ou tuple
Si return_dict est True, ~pipelines.ltx.LTX2PipelineOutput est retourné, sinon un tuple est retourné dont le premier élément est une liste contenant les images générées.
Fonction appelée lors de l'appel du pipeline pour la génération.
Exemples :
>>> import torch
>>> from diffusers import LTX2Pipeline
>>> from diffusers.utils import encode_video
>>> pipe = LTX2Pipeline.from_pretrained("Lightricks/LTX-2", torch_dtype=torch.bfloat16)
>>> pipe.enable_model_cpu_offload()
>>> prompt = "A woman with long brown hair and light skin smiles at another woman with long blonde hair. The woman with brown hair wears a black jacket and has a small, barely noticeable mole on her right cheek. The camera angle is a close-up, focused on the woman with brown hair's face. The lighting is warm and natural, likely from the setting sun, casting a soft glow on the scene. The scene appears to be real-life footage"
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"
>>> frame_rate = 24.0
>>> video, audio = pipe(
... prompt=prompt,
... negative_prompt=negative_prompt,
... width=768,
... height=512,
... num_frames=121,
... frame_rate=frame_rate,
... num_inference_steps=30,
... guidance_scale=3.0,
... output_type="np",
... return_dict=False,
... )
>>> encode_video(
... video[0],
... fps=frame_rate,
... audio=audio[0].float().cpu(),
... audio_sample_rate=pipe.vocoder.config.output_sampling_rate, # should be 24000
... output_path="video.mp4",
... )encode_prompt
< source >( prompt: str | list[str]negative_prompt: str | list[str] | None = Nonedo_classifier_free_guidance: bool = Truenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024scale_factor: int = 8device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Paramètres
- prompt (
stroulist[str], facultatif) — prompt à encoder - negative_prompt (
stroulist[str], facultatif) — Le ou les prompts à ne pas utiliser pour guider la génération d’image. S’il n’est pas défini, il faut passernegative_prompt_embedsà la place. Ignoré lorsque le guidage n’est pas utilisé (c’est-à-dire ignoré siguidance_scaleest inférieur à1). - do_classifier_free_guidance (
bool, facultatif, valeur par défautTrue) — Indique s'il faut utiliser le classifier free guidance ou non. - num_videos_per_prompt (
int, facultatif, valeur par défaut 1) — Nombre de vidéos à générer par invite. Appareil torch sur lequel placer les embeddings résultants - prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, les embeddings de texte seront générés à partir de l'argument d'entréeprompt. - negative_prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte négatifs pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, negative_prompt_embeds sera généré à partir de l'argument d'entréenegative_prompt. - device — (
torch.device, facultatif) : torch device - dtype — (
torch.dtype, facultatif) : dtype torch
Encode le prompt dans les états cachés de l'encodeur de texte.
enhance_prompt
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
Enhances the supplied prompt by generating a new prompt using the prompt enhancer (a Gemma
conditional-generation model) from it and a system prompt. When image is supplied, the enhancer is also
conditioned on that reference frame (I2V / keyframe-style enhancement). Uses the dedicated prompt_enhancer component if one is configured (e.g. LTX-2.5, whose text encoder isn’t trained for enhancement), otherwise
falls back to the main text_encoder (LTX-2.0/2.3, which double as their own enhancer).
Les modèles de messages, les mots-clés de décodage, le nettoyage des réponses et la préparation du côté long des images correspondent à ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ImageToVideoPipeline
classe diffusers.LTX2ImageToVideoPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
Pipeline pour la génération de vidéos à partir d'images.
Référence : https://github.com/Lightricks/LTX-Video
TODO
__call__
< source >( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Noneprompt: str | list[str] = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 512width: int = 768num_frames: int | None = Nonemin_seconds: float = 1.0max_seconds: float = 20.0frame_rate: float = 24.0motion_speed: float = 1.0num_inference_steps: int = 30sigmas: list[float] | None = Nonetimesteps: list[int] | None = Noneguidance_scale: float = 3.0stg_scale: float = 1.0modality_scale: float = 3.0guidance_rescale: float = 0.7audio_guidance_scale: float | None = 7.0audio_stg_scale: float | None = 1.0audio_modality_scale: float | None = 3.0audio_guidance_rescale: float | None = 0.7spatio_temporal_guidance_blocks: list[int] | None = [28]noise_scale: float = 0.0num_videos_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10image_crf: int | None = Noneoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Paramètres
- image (
PipelineImageInput) — L'image d'entrée sur laquelle conditionner la génération. Doit être une image, une liste d'images ou untorch.Tensor. - prompt (
stroulist[str], facultatif) — Le prompt ou les prompts pour guider la génération d’image. S’il n’est pas défini, il faut passerprompt_embedsà la place. - negative_prompt (
stroulist[str], facultatif) — Le ou les prompts à ne pas utiliser pour guider la génération d’image. S’il n’est pas défini, il faut passernegative_prompt_embedsà la place. Ignoré lorsque le guidage n’est pas utilisé (guidance_scale < 1). - height (
int, facultatif, par défaut512) — La hauteur en pixels de l'image générée. Cette valeur est fixée à 480 par défaut pour obtenir les meilleurs résultats. - width (
int, facultatif, par défaut768) — La largeur en pixels de l'image générée. Cette valeur est fixée à 848 par défaut pour obtenir les meilleurs résultats. - num_frames (
int, facultatif) — Le nombre de frames vidéo à générer. Si non fourni, la valeur par défaut est une durée prédite automatiquement lorsque ce pipeline possède un composantduration_head(checkpoints LTX-2.5 et ultérieurs), et121sinon. Transmettez un entier pour définir explicitement la longueur. Les compteurs prédits automatiquement sont alignés sur la grille temporelle causale du VAE, de sorte que la durée réalisée est quantifiée (environ 0,33 s à 24 fps). - min_seconds (
float, facultatif, valeur par défaut1.0) — Limite inférieure de la durée prédite automatiquement lorsquenum_framesest omis et qu’uneduration_headest présente. Ignoré lorsquenum_framesest défini explicitement. - max_seconds (
float, facultatif, par défaut20.0) — Limite supérieure de la durée prédite automatiquement lorsquenum_framesest omis et qu’unduration_headest présent. Ignoré lorsquenum_framesest défini explicitement. Doit être strictement supérieur àmin_seconds. - frame_rate (
float, facultatif, par défaut24.0) — Le nombre d'images par seconde (IPS) de la vidéo générée. - motion_speed (
float, facultatif, par défaut1.0) — Vitesse du mouvement par rapport au temps réel. Les embeddings positionnels sont conditionnés surframe_rate / motion_speed, de sorte que les valeurs inférieures à 1 ralentissent le mouvement, par exemple0.2pour le ralenti 5x du LoRA Slow-Motion-Control.frame_ratereste le taux de lecture : la durée audio et le nombre de frames prédit en dépendent. - num_inference_steps (
int, facultatif, valeur par défaut 30) — Le nombre d'étapes de débruitage. Un plus grand nombre d'étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d'une inférence plus lente. - sigmas (
List[float], facultatif) — Sigmas personnalisés à utiliser pour le processus de débruitage avec les planificateurs qui prennent en charge un argumentsigmasdans leur méthodeset_timesteps. S'il n'est pas défini, le comportement par défaut lorsquenum_inference_stepsest passé sera utilisé. - timesteps (
List[int], facultatif) — Timesteps personnalisés à utiliser pour le processus de débruitage avec les planificateurs qui prennent en charge un argumenttimestepsdans leur méthodeset_timesteps. S'il n'est pas défini, le comportement par défaut lorsquenum_inference_stepsest passé sera utilisé. Doit être dans l'ordre décroissant. - guidance_scale (
float, facultatif, par défaut4.0) — Échelle de guidage telle que définie dans Classifier-Free Diffusion Guidance.guidance_scaleest défini commewde l'équation 2 de Imagen Paper. L'échelle de guidage est activée en définissantguidance_scale > 1. Une échelle de guidage plus élevée encourage la génération d'images étroitement liées auprompttexte, généralement au détriment de la qualité de l'image. Utilisé pour la modalité vidéo (il existe une valeur distincteaudio_guidance_scalepour la modalité audio). - stg_scale (
float, facultatif, valeur par défaut0.0) — Échelle de guidage vidéo pour le Spatio-Temporal Guidance (STG), proposée dans Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. Le STG utilise une estimation de type CFG où l’on déplace l’échantillon loin d’un échantillon faible issu d’une version perturbée du modèle de débruitage. L’activation du STG entraîne un passage avant supplémentaire du modèle de débruitage ; la valeur par défaut de0.0signifie que le STG est désactivé. - modality_scale (
float, facultatif, valeur par défaut1.0) — Échelle de guidage vidéo pour l’isolation des modalités dans LTX-2.X, où l’on éloigne l’échantillon d’un échantillon plus faible généré par le modèle de débruitage avec l’attention croisée inter-modalités (audio-vers-vidéo et vidéo-vers-audio) désactivée, en utilisant une estimation de type CFG. L’activation du guidage par modalité entraîne un passage avant supplémentaire du modèle de débruitage ; la valeur par défaut de1.0signifie que le guidage par modalité est désactivé. - guidance_rescale (
float, facultatif, valeur par défaut 0.0) — Facteur de rescaling du guidance proposé par Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaleest défini commeφdans l'équation 16. de Common Diffusion Noise Schedules and Sample Steps are Flawed. Le facteur de rescaling du guidance doit corriger l'exposition excessive lors de l'utilisation d'un SNR terminal nul. Utilisé pour la modalité vidéo. - audio_guidance_scale (
float, facultatif, par défautNone) — Échelle de guidage audio pour le CFG par rapport au prompt négatif. La règle de mise à jour du CFG est la même pour la vidéo et l’audio, mais des valeurs différentes peuvent être utilisées pour l’échelle de guidage. Les auteurs de LTX-2.X suggèrent queaudio_guidance_scaledoit être plus élevé par rapport àguidance_scalede la vidéo (par exemple, pour LTX-2.3, ils suggèrent 3.0 pour la vidéo et 7.0 pour l’audio). SiNone, la valeur par défaut est celle de la vidéoguidance_scale. - audio_stg_scale (
float, facultatif, valeur par défautNone) — Échelle de guidage audio pour STG. Comme pour CFG, la règle de mise à jour STG est sinon identique pour la vidéo et l’audio. Pour LTX-2.3, une valeur de 1.0 est suggérée pour la vidéo et l’audio. SiNone, la valeur par défaut est la valeur vidéostg_scale. - audio_modality_scale (
float, facultatif, valeur par défautNone) — Échelle de guidage audio pour l’isolation des modalités de LTX-2.X. Comme pour CFG, la règle de guidage des modalités est sinon la même pour la vidéo et l’audio. Pour LTX-2.3, une valeur de 3.0 est suggérée pour la vidéo et l’audio. SiNone, la valeur par défaut est la valeur vidéomodality_scale. - audio_guidance_rescale (
float, facultatif, valeur par défautNone) — Facteur de rescaling de guidance distinct pour la modalité audio. SiNone, la valeur par défaut est celle de la vidéoguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], facultatif, valeur par défautNone) — Indices des blocs de transformer (à partir de zéro) auxquels appliquer le STG. Doit être fourni si le STG est utilisé (stg_scaleouaudio_stg_scaleest supérieur à0). Une valeur de[29]est recommandée pour LTX-2.0 et[28]est recommandée pour LTX-2.3. - noise_scale (
float, facultatif, valeur par défaut0.0) — Le facteur d’interpolation entre le bruit aléatoire et les latents débruités à chaque pas de temps. Applique un bruit auxlatentset auxaudio_latentsavant de poursuivre le débruitage. - num_videos_per_prompt (
int, facultatif, valeur par défaut 1) — Le nombre de vidéos à générer par invite. - generator (
torch.Generatoroulist[torch.Generator], facultatif) — Un ou une liste de générateurs torch pour rendre la génération déterministe. - latents (
torch.Tensor, facultatif) — Latents bruités pré-générés, échantillonnés à partir d’une distribution gaussienne, à utiliser comme entrées pour la génération de vidéo. Peut être utilisé pour ajuster la même génération avec des prompts différents. S’il n’est pas fourni, un tenseur de latents sera généré par échantillonnage à l’aide dugeneratoraléatoire fourni. - audio_latents (
torch.Tensor, facultatif) — Latents bruités pré-générés, échantillonnés à partir d’une distribution gaussienne, à utiliser comme entrées pour la génération audio. Peut être utilisé pour ajuster la même génération avec des prompts différents. S’il n’est pas fourni, un tenseur de latents sera généré par échantillonnage à l’aide dugeneratoraléatoire fourni. - prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, les embeddings de texte seront générés à partir de l'argument d'entréeprompt. - prompt_attention_mask (
torch.Tensor, facultatif) — Masque d'attention pré-généré pour les embeddings de texte. - negative_prompt_embeds (
torch.FloatTensor, facultatif) — Embeddings de texte négatifs pré-générés. Pour PixArt-Sigma, ce prompt négatif doit être "". S'il n'est pas fourni, negative_prompt_embeds sera généré à partir de l'argument d'entréenegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, facultatif) — Masque d'attention pré-généré pour les embeddings de texte négatifs. - decode_timestep (
float, par défaut0.0) — Le timestep auquel la vidéo générée est décodée. - decode_noise_scale (
float, par défautNone) — Le facteur d'interpolation entre le bruit aléatoire et les latents débruités à l'étape de décodage. - use_cross_timestep (
boolfacultatif, par défautTrue) — Indique s'il faut utiliser le sigma de la modalité croisée (l'audio est la modalité croisée de la vidéo, et inversement) lors du calcul des paramètres de modulation de l'attention croisée.Truecorrespond au comportement de LTX-2.3/2.5 ;Falsecorrespond au comportement hérité de LTX-2.0. - system_prompt (
str, facultatif, par défautNone) — Prompt système facultatif à utiliser pour l’amélioration du prompt. Le prompt système est utilisé par l’améliorateur de prompt (un modèle de génération conditionnelle Gemma — le composant dédiéprompt_enhancers’il est configuré, sinon letext_encoderprincipal) pour générer un prompt amélioré à partir dupromptd’origine et de la premièreimageservant à conditionner la génération. S’il n’est pas fourni et qu’unprompt_enhancerdédié est configuré (LTX-2.5), la valeur par défaut estLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT(depuisdiffusers.pipelines.ltx2.utils) — voirenable_prompt_enhancement. - enable_prompt_enhancement (
bool, facultatif, valeur par défautFalse) — Indique s'il faut exécuter l'amélioration du prompt. Option, conformément aux pipelines de référence Lightricks. SiTrueet quesystem_promptest omis, LTX-2.5 utiliseLTX2_5_I2V_DEFAULT_SYSTEM_PROMPTsi unprompt_enhancerdédié est configuré ; LTX-2.0/2.3 nécessitent unsystem_promptexplicite. - prompt_max_new_tokens (
int, facultatif, valeur par défautNone) — Nombre maximal de nouveaux jetons à générer lors de l'amélioration du prompt. Si non fourni, utilise 600 pour unprompt_enhancerGemma 4 dédié (LTX-2.5) ou 512 pour letext_encoderGemma 3 de secours (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], facultatif, par défautNone) — Arguments par mot-clé pour l’appel.generatede l’améliorateur de prompt. S’ils ne sont pas fournis, ils correspondent toujours au modèle qui effectue l’amélioration :do_sample=False, no_repeat_ngram_size=3(glouton) lorsqu’unprompt_enhancerdédié est utilisé (LTX-2.5), oudo_sample=True, temperature=0.7pour le repli sur letext_encoder(LTX-2.0/2.3). Voir https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate pour plus de détails. - prompt_enhancement_seed (
int, facultatif, par défaut10) — Graine aléatoire pour toute opération aléatoire lors de l'amélioration du prompt. - image_crf (
int, facultatif, valeur par défautNone) — CRF H.264 utilisé pour recompresser l'imagede conditionnement avant l'encodage VAE, afin de correspondre à la compression utilisée lors de l'entraînement du modèle.Nonesignifie « utiliser la valeur par défaut du modèle » (33 jusqu'à LTX-2.3, 18 pour LTX-2.5). Passez0pour ignorer la recompression. Nécessite unPIL.Image.Imagelorsque la recompression est exécutée. - output_type (
str, facultatif, par défaut"pil") — Le format de sortie de l'image générée. Choisissez entre PIL :PIL.Image.Imageounp.array. - return_dict (
bool, facultatif, par défautTrue) — Indique s'il faut retourner un~pipelines.ltx.LTX2PipelineOutputplutôt qu'un simple tuple. - attention_kwargs (
dict, facultatif) — Un dictionnaire de kwargs qui, s'il est spécifié, est transmis à l'AttentionProcessordéfini sousself.processordans diffusers.models.attention_processor. - callback_on_step_end (
Callable, facultatif) — Une fonction appelée à la fin de chaque étape de débruitage pendant l'inférence. La fonction est appelée avec les arguments suivants :callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargscontiendra une liste de tous les tenseurs spécifiés parcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, facultatif) — La liste des entrées tensorielles pour la fonctioncallback_on_step_end. Les tenseurs spécifiés dans la liste seront passés en tant qu'argumentcallback_kwargs. Vous ne pourrez inclure que les variables listées dans l'attribut._callback_tensor_inputsde votre classe de pipeline. - max_sequence_length (
int, facultatif, par défaut1024) — Longueur maximale de la séquence à utiliser avec leprompt.
Retourne
~pipelines.ltx.LTX2PipelineOutput ou tuple
Si return_dict est True, ~pipelines.ltx.LTX2PipelineOutput est retourné, sinon un tuple est retourné dont le premier élément est une liste contenant les images générées.
Fonction appelée lors de l'appel du pipeline pour la génération.
Exemples :
>>> import torch
>>> from diffusers import LTX2ImageToVideoPipeline
>>> from diffusers.utils import encode_video
>>> from diffusers.utils import load_image
>>> pipe = LTX2ImageToVideoPipeline.from_pretrained("Lightricks/LTX-2", torch_dtype=torch.bfloat16)
>>> pipe.enable_model_cpu_offload()
>>> image = load_image(
... "https://huggingface.co/datasets/a-r-r-o-w/tiny-meme-dataset-captioned/resolve/main/images/8.png"
... )
>>> prompt = "A young girl stands calmly in the foreground, looking directly at the camera, as a house fire rages in the background."
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"
>>> frame_rate = 24.0
>>> video, audio = pipe(
... image=image,
... prompt=prompt,
... negative_prompt=negative_prompt,
... width=768,
... height=512,
... num_frames=121,
... frame_rate=frame_rate,
... num_inference_steps=30,
... guidance_scale=3.0,
... output_type="np",
... return_dict=False,
... )
>>> encode_video(
... video[0],
... fps=frame_rate,
... audio=audio[0].float().cpu(),
... audio_sample_rate=pipe.vocoder.config.output_sampling_rate, # should be 24000
... output_path="video.mp4",
... )encode_prompt
< source >( prompt: str | list[str]negative_prompt: str | list[str] | None = Nonedo_classifier_free_guidance: bool = Truenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024scale_factor: int = 8device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Paramètres
- prompt (
stroulist[str], facultatif) — prompt à encoder - negative_prompt (
stroulist[str], facultatif) — Le ou les prompts à ne pas utiliser pour guider la génération d’image. S’il n’est pas défini, il faut passernegative_prompt_embedsà la place. Ignoré lorsque le guidage n’est pas utilisé (c’est-à-dire ignoré siguidance_scaleest inférieur à1). - do_classifier_free_guidance (
bool, facultatif, valeur par défautTrue) — Indique s'il faut utiliser le classifier free guidance ou non. - num_videos_per_prompt (
int, facultatif, valeur par défaut 1) — Nombre de vidéos à générer par invite. Appareil torch sur lequel placer les embeddings résultants - prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, les embeddings de texte seront générés à partir de l'argument d'entréeprompt. - negative_prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte négatifs pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, negative_prompt_embeds sera généré à partir de l'argument d'entréenegative_prompt. - device — (
torch.device, facultatif) : torch device - dtype — (
torch.dtype, facultatif) : dtype torch
Encode le prompt dans les états cachés de l'encodeur de texte.
enhance_prompt
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
Enhances the supplied prompt by generating a new prompt using the prompt enhancer (a Gemma
conditional-generation model) from it and a system prompt. When image is supplied, the enhancer is also
conditioned on that reference frame (I2V / keyframe-style enhancement). Uses the dedicated prompt_enhancer component if one is configured (e.g. LTX-2.5, whose text encoder isn’t trained for enhancement), otherwise
falls back to the main text_encoder (LTX-2.0/2.3, which double as their own enhancer).
Les modèles de messages, les mots-clés de décodage, le nettoyage des réponses et la préparation du côté long des images correspondent à ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ConditionPipeline
classe diffusers.LTX2ConditionPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEaudio_scheduler: diffusers.schedulers.scheduling_flow_match_euler_discrete.FlowMatchEulerDiscreteScheduler | None = Noneprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
Pipeline de génération de vidéo permettant d'insérer des conditions d'image à des emplacements arbitraires de la vidéo.
Référence : https://github.com/Lightricks/LTX-Video
TODO
__call__
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneprompt: str | list[str] = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 512width: int = 768num_frames: int | None = Nonemin_seconds: float = 1.0max_seconds: float = 20.0frame_rate: float = 24.0motion_speed: float = 1.0num_inference_steps: int = 30sigmas: list[float] | None = Nonetimesteps: list[float] | None = Noneguidance_scale: float = 3.0stg_scale: float = 1.0modality_scale: float = 3.0guidance_rescale: float = 0.7audio_guidance_scale: float | None = 7.0audio_stg_scale: float | None = 1.0audio_modality_scale: float | None = 3.0audio_guidance_rescale: float | None = 0.7spatio_temporal_guidance_blocks: list[int] | None = [28]noise_scale: float | None = Nonenum_videos_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10output_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Paramètres
- conditions (
List[LTXVideoCondition], *optional*) — La liste des éléments de conditionnement par image pour la génération de la vidéo. - prompt (
strouList[str], facultatif) — Le prompt ou les prompts pour guider la génération d’image. S’il n’est pas défini, il faut passerprompt_embedsà la place. - negative_prompt (
strouList[str], facultatif) — Le ou les prompts à ne pas utiliser pour guider la génération d’image. S’il n’est pas défini, il faut passernegative_prompt_embedsà la place. Ignoré lorsque le guidage n’est pas utilisé (guidance_scale < 1). - height (
int, facultatif, par défaut512) — La hauteur en pixels de l'image générée. Cette valeur est fixée à 480 par défaut pour obtenir les meilleurs résultats. - width (
int, facultatif, par défaut768) — La largeur en pixels de l'image générée. Cette valeur est fixée à 848 par défaut pour obtenir les meilleurs résultats. - num_frames (
int, facultatif) — Le nombre de frames vidéo à générer. Si non fourni, la valeur par défaut est une durée prédite automatiquement lorsque ce pipeline possède un composantduration_head(checkpoints LTX-2.5 et ultérieurs), et121sinon. Transmettez un entier pour définir explicitement la longueur. Les compteurs prédits automatiquement sont alignés sur la grille temporelle causale du VAE, de sorte que la durée réalisée est quantifiée (environ 0,33 s à 24 fps). - min_seconds (
float, facultatif, valeur par défaut1.0) — Limite inférieure de la durée prédite automatiquement lorsquenum_framesest omis et qu’uneduration_headest présente. Ignoré lorsquenum_framesest défini explicitement. - max_seconds (
float, facultatif, par défaut20.0) — Limite supérieure de la durée prédite automatiquement lorsquenum_framesest omis et qu’unduration_headest présent. Ignoré lorsquenum_framesest défini explicitement. Doit être strictement supérieur àmin_seconds. - frame_rate (
float, facultatif, par défaut24.0) — Le nombre d'images par seconde (IPS) de la vidéo générée. - motion_speed (
float, facultatif, par défaut1.0) — Vitesse du mouvement par rapport au temps réel. Les embeddings positionnels sont conditionnés surframe_rate / motion_speed, de sorte que les valeurs inférieures à 1 ralentissent le mouvement, par exemple0.2pour le ralenti 5x du LoRA Slow-Motion-Control.frame_ratereste le taux de lecture : la durée audio et le nombre de frames prédit en dépendent. - num_inference_steps (
int, facultatif, valeur par défaut 30) — Le nombre d'étapes de débruitage. Un plus grand nombre d'étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d'une inférence plus lente. - sigmas (
List[float], facultatif) — Sigmas personnalisés à utiliser pour le processus de débruitage avec les planificateurs qui prennent en charge un argumentsigmasdans leur méthodeset_timesteps. S'il n'est pas défini, le comportement par défaut lorsquenum_inference_stepsest passé sera utilisé. - timesteps (
List[int], facultatif) — Timesteps personnalisés à utiliser pour le processus de débruitage avec les planificateurs qui prennent en charge un argumenttimestepsdans leur méthodeset_timesteps. S'il n'est pas défini, le comportement par défaut lorsquenum_inference_stepsest passé sera utilisé. Doit être dans l'ordre décroissant. - guidance_scale (
float, facultatif, par défaut4.0) — Échelle de guidage telle que définie dans Classifier-Free Diffusion Guidance.guidance_scaleest défini commewde l'équation 2 de Imagen Paper. L'échelle de guidage est activée en définissantguidance_scale > 1. Une échelle de guidage plus élevée encourage la génération d'images étroitement liées auprompttexte, généralement au détriment de la qualité de l'image. Utilisé pour la modalité vidéo (il existe une valeur distincteaudio_guidance_scalepour la modalité audio). - stg_scale (
float, facultatif, valeur par défaut0.0) — Échelle de guidage vidéo pour le Spatio-Temporal Guidance (STG), proposée dans Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. Le STG utilise une estimation de type CFG où l’on déplace l’échantillon loin d’un échantillon faible issu d’une version perturbée du modèle de débruitage. L’activation du STG entraîne un passage avant supplémentaire du modèle de débruitage ; la valeur par défaut de0.0signifie que le STG est désactivé. - modality_scale (
float, facultatif, valeur par défaut1.0) — Échelle de guidage vidéo pour l’isolation des modalités dans LTX-2.X, où l’on éloigne l’échantillon d’un échantillon plus faible généré par le modèle de débruitage avec l’attention croisée inter-modalités (audio-vers-vidéo et vidéo-vers-audio) désactivée, en utilisant une estimation de type CFG. L’activation du guidage par modalité entraîne un passage avant supplémentaire du modèle de débruitage ; la valeur par défaut de1.0signifie que le guidage par modalité est désactivé. - guidance_rescale (
float, facultatif, valeur par défaut 0.0) — Facteur de rescaling du guidance proposé par Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaleest défini commeφdans l'équation 16. de Common Diffusion Noise Schedules and Sample Steps are Flawed. Le facteur de rescaling du guidance doit corriger l'exposition excessive lors de l'utilisation d'un SNR terminal nul. Utilisé pour la modalité vidéo. - audio_guidance_scale (
float, facultatif, par défautNone) — Échelle de guidage audio pour le CFG par rapport au prompt négatif. La règle de mise à jour du CFG est la même pour la vidéo et l’audio, mais des valeurs différentes peuvent être utilisées pour l’échelle de guidage. Les auteurs de LTX-2.X suggèrent queaudio_guidance_scaledoit être plus élevé par rapport àguidance_scalede la vidéo (par exemple, pour LTX-2.3, ils suggèrent 3.0 pour la vidéo et 7.0 pour l’audio). SiNone, la valeur par défaut est celle de la vidéoguidance_scale. - audio_stg_scale (
float, facultatif, valeur par défautNone) — Échelle de guidage audio pour STG. Comme pour CFG, la règle de mise à jour STG est sinon identique pour la vidéo et l’audio. Pour LTX-2.3, une valeur de 1.0 est suggérée pour la vidéo et l’audio. SiNone, la valeur par défaut est la valeur vidéostg_scale. - audio_modality_scale (
float, facultatif, valeur par défautNone) — Échelle de guidage audio pour l’isolation des modalités de LTX-2.X. Comme pour CFG, la règle de guidage des modalités est sinon la même pour la vidéo et l’audio. Pour LTX-2.3, une valeur de 3.0 est suggérée pour la vidéo et l’audio. SiNone, la valeur par défaut est la valeur vidéomodality_scale. - audio_guidance_rescale (
float, facultatif, valeur par défautNone) — Facteur de rescaling de guidance distinct pour la modalité audio. SiNone, la valeur par défaut est celle de la vidéoguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], facultatif, valeur par défautNone) — Indices des blocs de transformer (à partir de zéro) auxquels appliquer le STG. Doit être fourni si le STG est utilisé (stg_scaleouaudio_stg_scaleest supérieur à0). Une valeur de[29]est recommandée pour LTX-2.0 et[28]est recommandée pour LTX-2.3. - noise_scale (
float, facultatif, par défautNone) — Le facteur d’interpolation entre le bruit aléatoire et les latents débruités à chaque pas de temps. Applique un bruit auxlatentset auxaudio_latentsavant de poursuivre le débruitage. S’il n’est pas défini, il est déduit de la planification des sigmas. - num_videos_per_prompt (
int, facultatif, valeur par défaut 1) — Le nombre de vidéos à générer par invite. - generator (
torch.GeneratorouList[torch.Generator], facultatif) — Un ou une liste de générateurs torch pour rendre la génération déterministe. - latents (
torch.Tensor, facultatif) — Latents bruités pré-générés, échantillonnés à partir d’une distribution gaussienne, à utiliser comme entrées pour la génération de vidéo. Peut être utilisé pour ajuster la même génération avec des prompts différents. S’il n’est pas fourni, un tenseur de latents sera généré par échantillonnage à l’aide dugeneratoraléatoire fourni. - audio_latents (
torch.Tensor, facultatif) — Latents bruités pré-générés, échantillonnés à partir d’une distribution gaussienne, à utiliser comme entrées pour la génération audio. Peut être utilisé pour ajuster la même génération avec des prompts différents. S’il n’est pas fourni, un tenseur de latents sera généré par échantillonnage à l’aide dugeneratoraléatoire fourni. - prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, les embeddings de texte seront générés à partir de l'argument d'entréeprompt. - prompt_attention_mask (
torch.Tensor, facultatif) — Masque d'attention pré-généré pour les embeddings de texte. - negative_prompt_embeds (
torch.FloatTensor, facultatif) — Embeddings de texte négatifs pré-générés. Pour PixArt-Sigma, ce prompt négatif doit être "". S'il n'est pas fourni, negative_prompt_embeds sera généré à partir de l'argument d'entréenegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, facultatif) — Masque d'attention pré-généré pour les embeddings de texte négatifs. - decode_timestep (
float, par défaut0.0) — Le timestep auquel la vidéo générée est décodée. - decode_noise_scale (
float, par défautNone) — Le facteur d'interpolation entre le bruit aléatoire et les latents débruités à l'étape de décodage. - use_cross_timestep (
boolfacultatif, par défautTrue) — Indique s'il faut utiliser le sigma de la modalité croisée (l'audio est la modalité croisée de la vidéo, et inversement) lors du calcul des paramètres de modulation de l'attention croisée.Truecorrespond au comportement de LTX-2.3/2.5 ;Falsecorrespond au comportement hérité de LTX-2.0. - system_prompt (
str, facultatif, par défautNone) — Prompt système facultatif à utiliser pour l’amélioration du prompt. Le prompt système est utilisé par l’améliorateur de prompt (un modèle de génération conditionnelle Gemma — le composant dédiéprompt_enhancers’il est configuré, sinon letext_encoderprincipal) pour générer un prompt amélioré à partir dupromptd’origine (et d’une image de conditionnement si disponible) afin de conditionner la génération. S’il n’est pas fourni et qu’unprompt_enhancerdédié est configuré (LTX-2.5), la valeur par défaut estLTX2_5_I2V_DEFAULT_SYSTEM_PROMPTsi une image de conditionnement est disponible, sinonLTX2_5_T2V_DEFAULT_SYSTEM_PROMPT— voirenable_prompt_enhancement. - enable_prompt_enhancement (
bool, facultatif, valeur par défautFalse) — Indique s'il faut exécuter l'amélioration du prompt. Option, conformément aux pipelines de référence Lightricks. SiTrueet quesystem_promptest omis, LTX-2.5 choisitLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT/LTX2_5_T2V_DEFAULT_SYSTEM_PROMPTen fonction de la disponibilité d'une image de conditionnement. - prompt_max_new_tokens (
int, facultatif, valeur par défautNone) — Nombre maximal de nouveaux jetons à générer lors de l'amélioration du prompt. Si non fourni, utilise 600 pour unprompt_enhancerGemma 4 dédié (LTX-2.5) ou 512 pour letext_encoderGemma 3 de secours (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], facultatif, par défautNone) — Arguments par mot-clé pour l’appel.generatede l’améliorateur de prompt. S’ils ne sont pas fournis, ils correspondent toujours au modèle qui effectue l’amélioration :do_sample=False, no_repeat_ngram_size=5(glouton) lors de l’utilisation d’unprompt_enhancerdédié (LTX-2.5), oudo_sample=True, temperature=0.7pour le repli sur letext_encoder(LTX-2.0/2.3). Voir https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate pour plus de détails. - prompt_enhancement_seed (
int, facultatif, par défaut10) — Graine aléatoire pour toute opération aléatoire lors de l'amélioration du prompt. - output_type (
str, facultatif, par défaut"pil") — Le format de sortie de l'image générée. Choisissez entre PIL :PIL.Image.Imageounp.array. - return_dict (
bool, facultatif, par défautTrue) — Indique s'il faut retourner un~pipelines.ltx.LTX2PipelineOutputplutôt qu'un simple tuple. - attention_kwargs (
dict, facultatif) — Un dictionnaire de kwargs qui, s'il est spécifié, est transmis à l'AttentionProcessordéfini sousself.processordans diffusers.models.attention_processor. - callback_on_step_end (
Callable, facultatif) — Une fonction appelée à la fin de chaque étape de débruitage pendant l'inférence. La fonction est appelée avec les arguments suivants :callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargscontiendra une liste de tous les tenseurs spécifiés parcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, facultatif) — La liste des entrées tensorielles pour la fonctioncallback_on_step_end. Les tenseurs spécifiés dans la liste seront passés en tant qu'argumentcallback_kwargs. Vous ne pourrez inclure que les variables listées dans l'attribut._callback_tensor_inputsde votre classe de pipeline. - max_sequence_length (
int, facultatif, par défaut1024) — Longueur maximale de la séquence à utiliser avec leprompt.
Retourne
~pipelines.ltx.LTX2PipelineOutput ou tuple
Si return_dict est True, ~pipelines.ltx.LTX2PipelineOutput est retourné, sinon un tuple est retourné dont le premier élément est une liste contenant les images générées.
Fonction appelée lors de l'appel du pipeline pour la génération.
Exemples :
>>> import torch
>>> from diffusers import LTX2ConditionPipeline
>>> from diffusers.utils import encode_video
>>> from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2VideoCondition
>>> from diffusers.utils import load_image
>>> pipe = LTX2ConditionPipeline.from_pretrained("Lightricks/LTX-2", torch_dtype=torch.bfloat16)
>>> pipe.enable_model_cpu_offload()
>>> first_image = load_image(
... "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_first_frame.png"
... )
>>> last_image = load_image(
... "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_last_frame.png"
... )
>>> first_cond = LTX2VideoCondition(frames=first_image, index=0, strength=1.0)
>>> last_cond = LTX2VideoCondition(frames=last_image, index=-1, strength=1.0)
>>> conditions = [first_cond, last_cond]
>>> prompt = "CG animation style, a small blue bird takes off from the ground, flapping its wings."
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted, static"
>>> frame_rate = 24.0
>>> video = pipe(
... conditions=conditions,
... prompt=prompt,
... negative_prompt=negative_prompt,
... width=768,
... height=512,
... num_frames=121,
... frame_rate=frame_rate,
... num_inference_steps=30,
... guidance_scale=3.0,
... output_type="np",
... return_dict=False,
... )
>>> video = (video * 255).round().astype("uint8")
>>> video = torch.from_numpy(video)
>>> encode_video(
... video[0],
... fps=frame_rate,
... audio=audio[0].float().cpu(),
... audio_sample_rate=pipe.vocoder.config.output_sampling_rate, # should be 24000
... output_path="video.mp4",
... )apply_first_frame_conditioning
< source >( latents: Tensorconditioning_mask: Tensorcondition_latents: list[torch.Tensor]condition_strengths: list[float]condition_indices: list[int]latent_height: intlatent_width: int ) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
Paramètres
- latents (
torch.Tensor) — Latents initiaux empilés (patchifiés) de forme [batch_size, patch_seq_len, hidden_dim]. - conditioning_mask (
torch.Tensor) — Masque de conditionnement initial, compacté (patchifié), de forme [batch_size, patch_seq_len, 1], avec des valeurs dans [0, 1], où 0 signifie que la sortie du modèle de débruitage sera entièrement utilisée et 1 signifie que la condition sera entièrement utilisée.
Retourne
Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
Retourne un 3-tuple de tenseurs où :
- Les latents vidéo empilés avec les conditions de la première image appliquées.
- Le masque de conditionnement compact avec les intensités de la première image appliquées.
- Les latents de conditionnement propres aux positions de la première image (zéros ailleurs).
Appliquez le conditionnement visuel de la première image en écrasant les jetons aux positions de la première image.
Seules les conditions pour lesquelles latent_idx == 0 sont appliquées ici (correspondant à VideoConditionByLatentIndex dans l'implémentation de référence). Les conditions aux indices latents non nuls sont ajoutées en tant que jetons de keyframe distincts via prepare_keyframe_extras (correspondant à VideoConditionByKeyframeIndex) et sont ignorées ici.
encode_prompt
< source >( prompt: str | list[str]negative_prompt: str | list[str] | None = Nonedo_classifier_free_guidance: bool = Truenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024scale_factor: int = 8device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Paramètres
- prompt (
stroulist[str], facultatif) — prompt à encoder - negative_prompt (
stroulist[str], facultatif) — Le ou les prompts à ne pas utiliser pour guider la génération d’image. S’il n’est pas défini, il faut passernegative_prompt_embedsà la place. Ignoré lorsque le guidage n’est pas utilisé (c’est-à-dire ignoré siguidance_scaleest inférieur à1). - do_classifier_free_guidance (
bool, facultatif, valeur par défautTrue) — Indique s'il faut utiliser le classifier free guidance ou non. - num_videos_per_prompt (
int, facultatif, valeur par défaut 1) — Nombre de vidéos à générer par invite. Appareil torch sur lequel placer les embeddings résultants - prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, les embeddings de texte seront générés à partir de l'argument d'entréeprompt. - negative_prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte négatifs pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, negative_prompt_embeds sera généré à partir de l'argument d'entréenegative_prompt. - device — (
torch.device, facultatif) : torch device - dtype — (
torch.dtype, facultatif) : dtype torch
Encode le prompt dans les états cachés de l'encodeur de texte.
enhance_prompt
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
Enhances the supplied prompt by generating a new prompt using the prompt enhancer (a Gemma
conditional-generation model) from it and a system prompt. When image is supplied, the enhancer is also
conditioned on that reference frame (I2V / keyframe-style enhancement). Uses the dedicated prompt_enhancer component if one is configured (e.g. LTX-2.5, whose text encoder isn’t trained for enhancement), otherwise
falls back to the main text_encoder (LTX-2.0/2.3, which double as their own enhancer).
Les modèles de messages, les mots-clés de décodage, le nettoyage des réponses et la préparation du côté long des images correspondent à ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
prepare_latents
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Nonebatch_size: int = 1num_channels_latents: int = 128height: int = 512width: int = 768num_frames: int = 121frame_rate: float = 24.0noise_scale: float = 1.0dtype: typing.Optional[torch.dtype] = Nonedevice: typing.Optional[torch.device] = Nonegenerator: typing.Optional[torch.Generator] = Nonelatents: typing.Optional[torch.Tensor] = None )
Préparez les latents vidéo bruités en appliquant les conditions de cadre.
Les conditions de la première image (latent_idx == 0) sont appliquées en écrasant les jetons aux positions de la première image
(sémantique de VideoConditionByLatentIndex). Les conditions non liées à la première image (latent_idx > 0) sont concaténées à la
séquence latente principale avec un conditioning_mask = strength par jeton (sémantique de VideoConditionByKeyframeIndex) — la formule de pas de temps existante de la boucle de débruitage t * (1 - conditioning_mask) et le mélange post-traitement denoised * (1 - conditioning_mask) + clean * conditioning_mask les pilotent ensuite au fil des étapes.
Retourne un 4-uplet :
latents: latents bruités empilés (jetons de base + jetons de keyframe concaténés sur la dimension de la séquence).conditioning_mask: masque de conditionnement compact avec des valeurs dans[0, 1]—1aux positions de la première image,strengthaux positions des images clés,0ailleurs.clean_latents: valeurs de conditionnement propres aux positions conditionnées (zéros ailleurs) ; même forme quelatents.keyframe_coords: coordonnées positionnelles[B, 3, num_keyframe_patches, 2]à ajouter àvideo_coords, ouNones'il n'y a pas de conditions autres que la première image.
preprocess_conditions
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 512width: int = 768num_frames: int = 121device: typing.Optional[torch.device] = None ) → Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Paramètres
- conditions (
LTX2VideoConditionorList[LTX2VideoCondition], optional, defaults toNone) — A list of image/video condition instances. - height (
int, facultatif, par défaut512) — La hauteur souhaitée en pixels. - width (
int, facultatif, par défaut768) — La largeur souhaitée en pixels. - num_frames (
int, facultatif, par défaut121) — Le nombre de frames souhaité dans la vidéo générée. - device (
torch.device, facultatif, par défautNone) — L'appareil sur lequel placer les tenseurs d'images/vidéos prétraitées.
Retourne
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Retourne un 4-uplet de listes de longueur len(conditions) comme suit :
- La première liste est une liste de tenseurs vidéo prétraités de forme [batch_size=1, num_channels, num_frames, height, width].
- La deuxième liste est une liste de forces de conditionnement.
- La troisième liste est une liste d'indices de l'espace latent pour chaque condition.
- La quatrième liste est une liste de nombres de trames (rognées) dans l’espace des pixels par condition. Elle est nécessaire pour la sémantique des coordonnées des images clés (les images clés d’une seule trame de pixel ont une étendue temporelle bornée).
Prétraite les images/vidéos de condition en tenseurs torch.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Réduire une séquence de conditionnement au nombre de frames autorisé.
LTX2DFRPipeline
classe diffusers.LTX2DFRPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
Paramètres
- scheduler (FlowMatchEulerDiscreteScheduler) —
Un planificateur à utiliser en combinaison avec
transformerpour débruyer les latents vidéo encodés. - vae (AutoencoderKLLTX2Video) — Modèle de Variational Auto-Encoder (VAE) pour encoder et décoder des vidéos vers et depuis des représentations latentes.
- audio_vae (AutoencoderKLLTX2Audio) — VAE audio pour encoder et décoder des spectrogrammes audio.
- text_encoder (
Gemma3ForConditionalGenerationouGemma4UnifiedForConditionalGeneration) — Modèle d'encodeur de texte. - tokenizer (
GemmaTokenizerouGemmaTokenizerFast) — Tokeniseur pour l’encodeur de texte. - connectors (
LTX2TextConnectors) — Pile de connecteurs de texte utilisée pour adapter les états cachés de l’encodeur de texte aux branches vidéo et audio. - transformer (LTX2VideoTransformer3DModel) — Architecture Transformer conditionnelle pour débruyer les latents vidéo encodés.
- vocoder (
LTX2VocoderouLTX2VocoderWithBWE) — Vocodeur pour convertir les spectrogrammes de mel en formes d'onde audio. - processor (
ProcessorMixin, facultatif) — Processeur utilisé pour le chat templating d’amélioration des prompts. - prompt_enhancer (
Gemma4ForConditionalGeneration, facultatif) — Modèle dédié à l'amélioration des prompts (LTX-2.5). - duration_head (
LTX2DurationHead, facultatif) — Préditnum_framesà partir des embeddings du prompt lorsquenum_framesn’est pas fourni.
Pipeline pour un passage de débruitage Diffusion Fidelity Rendering (DFR) avec LTX-2.5.
Un passage génère une vidéo et des emplacements de keyframes supplémentaires à un seul pixel, ou redébruite des latents fournis initialisés à partir de ces emplacements. Les appelants composent les étapes : ce pipeline à la moitié de la résolution, LTX2LatentUpsamplePipeline spatialement, ce pipeline à nouveau à la résolution complète avec les emplacements suréchantillonnés et une référence IC-LoRA, puis LTX2DFRTemporalRefinePipeline pour chaque tour de raffinement temporel. Consultez la documentation de LTX-2 pour la recette 1080p.
Les positions des slots proviennent d’une grille de segments alignée sur la frontière temporelle du VAE (resolve_canvas). La grille est
rembourrée jusqu’à un nombre entier de segments ; output_type="latent" renvoie cette grille rembourrée afin qu’aucun slot situé sur le rembourrage ne soit
supprimé. Utilisez trim_canvas avant le décodage VAE.
Nécessite un transformer dont la configuration définit use_keyframes_abs_pos_embedding (LTX-2.5 et versions ultérieures) lorsque generate_slots=True.
Référence : https://github.com/Lightricks/LTX-2
__call__
< source >( prompt: str | list[str] = Noneconditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 704width: int = 1216num_frames: int | None = Noneframe_rate: float = 24.0min_seconds: float = 1.0max_seconds: float = 20.0latents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Nonekeyframes_latents: typing.Optional[torch.Tensor] = Nonekeyframe_positions: list[int] | None = Nonereference_latents: typing.Optional[torch.Tensor] = Nonereference_downscale_factor: int = 2guidance_keyframe_latents: typing.Optional[torch.Tensor] = Noneguidance_keyframe_positions: list[int] | None = Noneguidance_keyframe_strength: float = 1.0generate_slots: bool = Truesigmas: list[float] = [1.0, 0.99375, 0.9875, 0.98125, 0.975, 0.909375, 0.725, 0.421875]noise_scale: float | None = Nonefreeze_audio: bool = Falsevideo_tiles: list[diffusers.pipelines.ltx2.dfr_layout.LTX2DFREpilogueTile] | None = Nonenum_videos_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10output_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 1024 ) → LTX2DFRPipelineOutput or tuple
Paramètres
- prompt (
strouList[str], facultatif) — Le prompt ou les prompts pour guider la génération de la vidéo. S'il n'est pas défini, il faut passerprompt_embeds. - conditions (
LTX2VideoConditionouList[LTX2VideoCondition], facultatif) — Conditions d’image ou de vidéo au niveau des images.indexest un index latent surnum_framesde ce passage. - height (
int, facultatif, par défaut704) — La hauteur en pixels de ce passage, et non de la sortie finale composée. - width (
int, facultatif, par défaut1216) — La largeur en pixels de ce passage. - num_frames (
int, facultatif) — Nombre de trames en pixels de ce passage, avant le bourrage interne du canevas. Si non fourni, la durée est prédite à partir du prompt par leduration_head. Doit satisfaire(num_frames - 1) % 8 == 0. - frame_rate (
float, facultatif, valeur par défaut24.0) — FPS de lecture de ce passage. Le temps RoPE est arrondi à 60 lorsque cette valeur est supérieure à 30. - min_seconds (
float, facultatif, par défaut1.0) — Limite inférieure de la durée prédite automatiquement lorsquenum_framesest omis. - max_seconds (
float, facultatif, par défaut20.0) — Limite supérieure de la durée prédite automatiquement lorsquenum_framesest omis. - latents (
torch.Tensor, facultatif) — Latents vidéo bruts de forme(batch_size, channels, frames, height, width)à redébruitiser (étape 2 / épilogue). - audio_latents (
torch.Tensor, facultatif) — Latents audio bruts non décompressés de forme(batch_size, channels, length, mel_bins). L’étape 2 exécute toujours un passage audio conjoint ; la forme d’onde livrée par une recette composée est celle de l’étape 1, que l’appelant conserve. - keyframes_latents (
torch.Tensor, facultatif) — Initiales brutes des slots(batch_size, channels, num_slots, height, width), utilisées lorsquegenerate_slots=True. - keyframe_positions (
list[int], facultatif) — Indices des images-pixels des créneaux générés. Par défaut,resolve_canvas(num_frames). - reference_latents (
torch.Tensor, facultatif) — Vidéo de référence brute IC-LoRA (généralement les images de l’étape 1). - reference_downscale_factor (
int, facultatif, par défaut2) — Ratio entre ce passage et la résolution de référence, utilisé pour mettre à l'échelle les coordonnées des jetons de référence. - guidance_keyframe_latents (
torch.Tensor, facultatif) — Keyframes de guidance brutes épinglées(batch_size, channels, K, height, width)— le chemin épilogue. Pas de slots générés. - guidance_keyframe_positions (
list[int], facultatif) — Indices des trames en pixels pourguidance_keyframe_latents. - guidance_keyframe_strength (
float, facultatif, valeur par défaut1.0) — Force de conditionnement pour les keyframes de guidage épinglées. - generate_slots (
bool, facultatif, par défautTrue) — Ajoute les jetons de créneaux de keyframes générés. L'épilogue définit cette valeur àFalseet fixe à la placeguidance_keyframe_latents. - sigmas (
list[float], facultatif) — Plan de bruit pour ce passage, sans le terminal0.0. - noise_scale (
float, facultatif) — Niveau de bruit auquel les jetons non conditionnés démarrent. Valeur par défaut :sigmas[0]. - freeze_audio (
bool, facultatif, valeur par défautFalse) — Maintient l’audio à sigma 0 (épilogue / lorsqu’il suit une forme d’onde de l’étape 1 figée). - video_tiles (
list[LTX2DFREpilogueTile], facultatif) — Tuilage de l’épilogue issu deepilogue_tiles(), permettant ainsi de faire avancer un seul canevas même si la résolution est trop grande pour un seul passage avant : chaque étape exécute le transformeur une fois par tuile et fusionne les prédictions. Résolu en un plan de jetons par rapport aux coordonnées RoPE propres à ce passage, ce qui explique pourquoi la disposition est transmise plutôt que le plan — les coordonnées n’existant qu’une fois que prepare_latents() a été exécuté. - num_videos_per_prompt (
int, facultatif, valeur par défaut 1) — Le nombre de vidéos à générer par invite. - generator (
torch.Generatoroulist[torch.Generator], facultatif) — Générateur(s) aléatoire(s) pour la reproductibilité. - prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte pré-générés. - prompt_attention_mask (
torch.Tensor, facultatif) — Masque d'attention pré-généré pour les embeddings de texte. - decode_timestep (
float, par défaut0.0) — Le timestep auquel la vidéo générée est décodée. - decode_noise_scale (
float, par défautNone) — Échelle du bruit lors du décodage. - use_cross_timestep (
bool, facultatif, valeur par défautTrue) — Indique s'il faut utiliser le sigma inter-modalités pour la modulation de l'attention croisée.Truepour LTX-2.3+. - system_prompt (
str, facultatif) — Prompt système facultatif pour l’amélioration du prompt. Voirenable_prompt_enhancement. - enable_prompt_enhancement (
bool, facultatif, valeur par défautFalse) — Indique s'il faut exécuter l'amélioration du prompt. - prompt_max_new_tokens (
int, facultatif) — Le nombre maximal de nouveaux jetons à générer lors de l'amélioration du prompt. - prompt_enhancement_kwargs (
dict[str, Any], facultatif) — Arguments par mot-clé pour l'appel.generatede l'améliorateur de prompt. - prompt_enhancement_seed (
int, facultatif, par défaut10) — Graine aléatoire pour toute opération aléatoire lors de l'amélioration du prompt. - output_type (
str, facultatif, par défaut"pil") — Format de sortie. Choisissez"pil","np","pt"ou"latent". La sortie latente est le canevas non rogné. - return_dict (
bool, facultatif, par défautTrue) — Indique s'il faut retourner un LTX2DFRPipelineOutput ou un simple tuple(frames, audio, keyframes, keyframe_positions). - attention_kwargs (
dict, facultatif) — Arguments supplémentaires transmis au processeur d'attention. - callback_on_step_end (
Callable, facultatif) — Une fonction appelée à la fin de chaque étape de débruitage. - callback_on_step_end_tensor_inputs (
List, facultatif, par défaut["latents"]) — Entrées tensorielles pour la fonction de rappel. - max_sequence_length (
int, facultatif, par défaut1024) — Longueur maximale de la séquence pour le prompt texte.
Retourne
LTX2DFRPipelineOutput ou tuple
Si return_dict est True, LTX2DFRPipelineOutput est retourné, sinon un tuple de (video, audio, keyframes, keyframe_positions) est retourné.
Fonction appelée lors de l'appel du pipeline pour la génération.
Un passage de débruitage à height × width. Composez les étapes dans l'appelant : ce pipeline à la moitié de la résolution, un échantillonnage spatial, ce pipeline à nouveau avec latents / keyframes_latents / reference_latents, puis LTX2DFRTemporalRefinePipeline pour chaque passe temporelle.
Exemples :
>>> import torch
>>> from diffusers import LTX2DFRPipeline
>>> from diffusers.utils import encode_video
>>> pipe = LTX2DFRPipeline.from_pretrained("Lightricks/LTX-2.5-Diffusers", torch_dtype=torch.bfloat16)
>>> pipe.enable_model_cpu_offload()
>>> frame_rate = 24.0
>>> video, audio, _, _ = pipe(
... prompt="A tabby cat stretching in a sunlit window, dust motes drifting in the light",
... height=704,
... width=1216,
... num_frames=121,
... frame_rate=frame_rate,
... output_type="np",
... return_dict=False,
... )
>>> encode_video(
... video[0],
... fps=frame_rate,
... audio=audio[0].float().cpu(),
... audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
... output_path="dfr_output.mp4",
... )denoise
< source >( latents: Tensorconditioning_mask: Tensorclean_latents: Tensorvideo_coords: Tensorkeyframes_mask: Tensorprompt_embeds: Tensoraudio_prompt_embeds: Tensorprompt_attention_mask: Tensorsigmas: list[float]frame_rate: floataudio_latents: Tensorfreeze_audio: bool = Falsevideo_tile_plan: list | None = Nonegenerator: typing.Optional[torch.Generator] = Noneuse_cross_timestep: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Noneprogress_bar = Nonestep_offset: int = 0callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] | None = None )
Paramètres
- sigmas (
list[float]) — Plan de bruit pour ce passage, sans le terminal0.0. - freeze_audio (
bool, facultatif, valeur par défautFalse) — Conserveaudio_latentspropre (pas de temps/sigma 0, aucune étape Euler audio) tout en exécutant l'attention croisée audio-verso-vidéo. Ignoré lorsqueaudio_latentsestNone. - video_tile_plan (
list, facultatif) — Plan de jetons par tuile issu devideo_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. Lorsqu’il est fourni, chaque étape exécute le transformer une fois par tuile et fusionne les prédictions, de sorte que le sampler avance toujours sur une seule toile complète et que les tuiles concordent sur leurs chevauchements à chaque étape. - generator (
torch.Generator, facultatif) — Transmis àLTXEulerAncestralRFScheduler.step(). Les tuiles temporelles passent une graine par tuile afin que les tirages ancestraux ne partagent pas un même flux et ne consomment pas l’état que le bruitage initial de la tuile suivante lit. L’Euler distillé ne le lit pas. - step_offset (
int) — Index de la première étape de ce passage dans l’ensemble du calendrier du pipeline, utilisé pourcallback_on_step_endet la barre de progression partagée.
Effectuer un passage de débruitage DFR sur sigmas et retourner (latents, audio_latents), tous deux encore empilés.
L’horaire distillé est utilisé sans guidage sans classifieur, ce qui correspond à un seul appel au transformeur par étape.
Chaque passe exécute les deux flux, car la branche vidéo a besoin de l’attention intermodale, même lorsque l’audio qu’elle
produit est jeté. freeze_audio=True maintient le flux audio à sigma 0 (pas d’étape d’Euler) afin que la vidéo
puisse toujours effectuer une attention croisée avec celui-ci — les tuiles de raffinement temporel et l’épilogue utilisent
ce mécanisme pour suivre la parole de l’étape 1 sans que chaque tuile ne redébruite une réalisation audio différente.
Après le mélange de conditionnement x0, la vitesse est (latents - denoised) / sigma, de sorte qu'une étape RF x0 = x - σ v récupère le denoised mélangé. Les étapes 1 / 2 / l'épilogue conservent FlowMatchEulerDiscreteScheduler et appliquent cette étape d'Euler telle quelle. Le raffinement temporel remplace par LTXEulerAncestralRFScheduler (eta=0.5) ; cette étape rebruit chaque jeton, il faut donc réappliquer le mélange de conditionnement par la suite, sinon les ancrages de couture de force 0,95 s'érodent.
encode_conditions
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | Noneheight: intwidth: intnum_frames: intdevice: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = Nonegenerator: typing.Optional[torch.Generator] = None )
Prétraitez et encodez les conditions de trame avec le VAE, positionnées par trame de pixels.
Retourne (pixel_frame_index, latent, strength, num_pixel_frames) pour chaque condition, prêt pour condition_latents de prepare_latents(). L’encodage est maintenu séparé du placement car les tours de raffinement temporel échelonnent la position d’une condition par 2 ** round et la réinitialisent par tuile, et ne doivent pas réencoder la même image fixe une fois par tuile pour ce faire.
L’indice retourné est sur la grille de pixels propre à num_frames ; le transfert sur un canevas affiné est à la charge de l’appelant.
encode_prompt
< source >( prompt: str | list[str]num_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Paramètres
- prompt (
stroulist[str], facultatif) — prompt à encoder - num_videos_per_prompt (
int, facultatif, valeur par défaut 1) — Nombre de vidéos à générer par invite. - prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, les embeddings de texte seront générés à partir de l'argument d'entréeprompt. - prompt_attention_mask (
torch.Tensor, facultatif) — Masque d'attention pré-généré pourprompt_embeds. - device — (
torch.device, facultatif) : torch device - dtype — (
torch.dtype, facultatif) : dtype torch
Encode le prompt dans les états cachés de l'encodeur de texte.
DFR exécute le calendrier sigma distillé, qui est entraîné pour être utilisé sans guidage sans classifieur, il n'y a donc pas de branche négative ici.
enhance_prompt
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
Enhances the supplied prompt by generating a new prompt using the prompt enhancer (a Gemma
conditional-generation model) from it and a system prompt. When image is supplied, the enhancer is also
conditioned on that reference frame (I2V / keyframe-style enhancement). Uses the dedicated prompt_enhancer component if one is configured (e.g. LTX-2.5, whose text encoder isn’t trained for enhancement), otherwise
falls back to the main text_encoder (LTX-2.0/2.3, which double as their own enhancer).
Les modèles de messages, les mots-clés de décodage, le nettoyage des réponses et la préparation du côté long des images correspondent à ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
prepare_latents
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Nonecondition_latents: list[tuple[int, torch.Tensor, float, int]] | None = Nonekeyframe_latents: list[tuple[int, torch.Tensor, float]] | None = Noneslot_frame_indices: list[int] | None = Noneslot_initial_latents: typing.Optional[torch.Tensor] = Nonereference_latents: typing.Optional[torch.Tensor] = Nonereference_downscale_factor: int = 1batch_size: int = 1num_channels_latents: int = 128height: int = 512width: int = 768num_frames: int = 121frame_rate: float = 24.0noise_scale: float = 1.0dtype: typing.Optional[torch.dtype] = Nonedevice: typing.Optional[torch.device] = Nonegenerator: typing.Optional[torch.Generator] = Nonelatents: typing.Optional[torch.Tensor] = Nonelatents_normalized: bool = True ) → tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, slice | None]
Paramètres
- conditions (
list[LTX2VideoCondition], facultatif) — Conditions d'image / vidéo au niveau des images, positionnées par index latent. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], facultatif) — Substitut déjà encodé pourconditions, sous la forme(pixel_frame_index, latent, strength, num_pixel_frames). L’index est en pixels plutôt qu’en latents, car une passe de raffinement temporel multiplie la position d’une condition par2 ** roundet le résultat ne tombe généralement pas sur une frontière de latents — seul un jeton de cléframe ajouté peut s’y situer, et il est placé par pixel.pixel_frame_index == 0signifie toujours « remplacer la première image ». - keyframe_latents (
list[tuple[int, torch.Tensor, float]], facultatif) — Guides de keyframes déjà encodés sous la forme(pixel_frame_index, latent, strength), oùlatenta la forme(batch_size, num_channels_latents, 1, latent_height, latent_width). Utilisé par les passes de raffinement temporel pour ancrer les keyframes de couture transmises depuis la passe précédente. - slot_frame_indices (
list[int], facultatif) — Positions des images-pixels des emplacements des images clés générées. - slot_initial_latents (
torch.Tensor, facultatif) —(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)contenu écrit dans les jetons de slot avant le bruitage. - reference_latents (
torch.Tensor, facultatif) —(batch_size, num_channels_latents, F, H, W)latent de référence IC-LoRA. - reference_downscale_factor (
int, par défaut1) — Ratio entre la résolution cible et la résolution de référence. - latents (
torch.Tensor, facultatif) —(batch_size, num_channels_latents, F, H, W)contenu initial pour les jetons de base. Les latents du pipeline public sont bruts (non normalisés) ; passezlatents_normalized=Falseà cette frontière. Les boucles de tuiles qui sont déjà dans l’espace normalisé par le VAE conservent la valeur par défaut. - latents_normalized (
bool, par défautTrue) — Indique silatents,slot_initial_latents,reference_latentsetkeyframe_latentssont déjà normalisés par le VAE. Les boucles internes de tuiles passentTrue; chaque__call__de pipeline passeFalse. - noise_scale (
float, par défaut1.0) — Niveau de bruit auquel les jetons non conditionnés sont initialisés, c’est-à-dire la première sigma de l’ordonnancement.
Retourne
tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, slice | None]
(latents, conditioning_mask, clean_latents, video_coords, keyframes_mask, slot_token_slice).
slot_token_slice indexe les jetons de créneaux de keyframes générés dans la séquence compactée, ou vaut None si aucun
créneau n’a été demandé.
Préparez les latents vidéo bruités et empilés pour un passage de débruitage DFR.
La séquence compacte est disposée comme suit : [base | keyframes | slots | reference] :
- Les jetons de base couvrent la grille latente cible, initialisée à partir de
latentslorsqu’ils sont fournis. - Les conditions de trame avec
index == 0définissent la cible propre aux positions de la première trame ; celles avecindex > 0et chaque entrée dekeyframe_latentssont ajoutées en tant que jetons de trame clé supplémentaires avec un masque de conditionnement par jeton égal à leur intensité. slot_frame_indicesajoute, pour chaque position, un lot de jetons de keyframe générés correspondant à une frame latente, avec un masque de conditionnement0(entièrement débruité) et une étendue temporelle RoPE d’exactement une frame pixel. Ce sont les slots de keyframe qui apportent les frames supplémentaires à DFR ;slot_initial_latentsinitialise leur contenu.reference_latentsajoute le latent de résolution moitié de l’étape 1 comme référence IC-LoRA entièrement propre, avec les coordonnées spatiales mises à l’échelle parreference_downscale_factorafin qu’il corresponde à l’espace de coordonnées cible.
Les jetons de conditionnement ajoutés portent leur contenu dans clean_latents et un zéro de remplacement dans latents, tandis que les emplacements de images clés portent leur graine dans latents et des zéros dans clean_latents — les latents retournés sont le mélange bruité des deux (voir l’étape de bruitage à la fin de cette méthode).
preprocess_conditions
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 512width: int = 768num_frames: int = 121device: typing.Optional[torch.device] = None ) → Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Paramètres
- conditions (
LTX2VideoConditionorList[LTX2VideoCondition], optional, defaults toNone) — A list of image/video condition instances. - height (
int, facultatif, par défaut512) — La hauteur souhaitée en pixels. - width (
int, facultatif, par défaut768) — La largeur souhaitée en pixels. - num_frames (
int, facultatif, par défaut121) — Le nombre de frames souhaité dans la vidéo générée. - device (
torch.device, facultatif, par défautNone) — L'appareil sur lequel placer les tenseurs d'images/vidéos prétraitées.
Retourne
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Retourne un 4-uplet de listes de longueur len(conditions) comme suit :
- La première liste est une liste de tenseurs vidéo prétraités de forme [batch_size=1, num_channels, num_frames, height, width].
- La deuxième liste est une liste de forces de conditionnement.
- La troisième liste est une liste d'indices de l'espace latent pour chaque condition.
- La quatrième liste est une liste de nombres de trames (rognées) dans l’espace des pixels par condition. Elle est nécessaire pour la sémantique des coordonnées des images clés (les images clés d’une seule trame de pixel ont une étendue temporelle bornée).
Prétraite les images/vidéos de condition en tenseurs torch.
rebuild_epilogue_keyframes
< source >( keyframe_latents: Tensordecode_timestep: floatdecode_noise_scale: floatseed: intdevice: devicedtype: dtype ) → torch.Tensor
Paramètres
- keyframe_latents (
torch.Tensor) — Images clés brutes de forme(batch_size, C, K, H, W), telles que renvoyées par un passage précédent. - seed (
int) — Graine de base ; le planiest décodé sousseed + 4000 + i, de sorte que les pixels d’un plan ne dépendent pas du nombre de plans décodés avant lui.
Retourne
torch.Tensor
Latents bruts (batch_size, C, K, 2H, 2W), prêts à être renvoyés directement en tant que
guidance_keyframe_latents.
Re-encodez les images clés de transport à deux fois leur résolution via le RGB.
Il s’agit d’images déjà stabilisées par les cycles de raffinement, de sorte que l’épilogue les reçoit plutôt qu’il ne les génère. Le décodage en pixels, l’agrandissement x2 avec Lanczos puis le réencodage préservent l’image tout en la positionnant sur la grille de sortie, ce qui permet à l’épilogue de la verrouiller parfaitement propre.
Chaque plan est décodé comme un clip d'une seule image. Le VAE est causal, donc un décodage empilé permettrait aux plans voisins de se mélanger — ce sont des images fixes indépendantes, et non une séquence.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Réduire une séquence de conditionnement au nombre de frames autorisé.
LTX2DFRTemporalRefinePipeline
classe diffusers.LTX2DFRTemporalRefinePipeline
< source >( scheduler: LTXEulerAncestralRFSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEtemporal_latent_upsampler: LTX2LatentUpsamplerModel )
Paramètres
- scheduler (
LTXEulerAncestralRFScheduler) — Planificateur Euler ancestral dans la paramétrisation rectified-flow. À construire aveceta=0.5pour correspondre à la recette temporelle DFR. - vae (AutoencoderKLLTX2Video) — Modèle de Variational Auto-Encoder (VAE) pour encoder et décoder des vidéos vers et depuis des représentations latentes.
- audio_vae (AutoencoderKLLTX2Audio) — VAE audio pour encoder et décoder des spectrogrammes audio.
- text_encoder (
Gemma3ForConditionalGenerationouGemma4UnifiedForConditionalGeneration) — Modèle d'encodeur de texte. - tokenizer (
GemmaTokenizerouGemmaTokenizerFast) — Tokeniseur pour l’encodeur de texte. - connectors (
LTX2TextConnectors) — Pile de connecteurs de texte utilisée pour adapter les états cachés de l’encodeur de texte aux branches vidéo et audio. - transformer (LTX2VideoTransformer3DModel) — Architecture Transformer conditionnelle pour débruyer les latents vidéo encodés.
- vocoder (
LTX2VocoderouLTX2VocoderWithBWE) — Vocodeur pour convertir les spectrogrammes de mel en formes d'onde audio. - temporal_latent_upsampler (
LTX2LatentUpsamplerModel) — Upsampler latent temporel x2 appliqué au début du cycle.
Une passe de raffinement temporel DFR : interpoler la toile x2 dans le temps, tuiler sur les coutures des images clés, débruitage ancestral de chaque tuile, assemblage en supprimant l’intro de la tuile suivante, et fusion du sac d’images clés portées.
Le planificateur est LTXEulerAncestralRFScheduler (eta=0.5 par défaut). Les étapes 1 / 2 / l'épilogue spatial restent sur FlowMatchEulerDiscreteScheduler via LTX2DFRPipeline. Appelez ce pipeline une fois par tour ; l'appelant boucle pour 2x / 4x.
Les latents / keyframes_latents / audio_latents entrants sont bruts (non normalisés), conformément à LTX2Pipeline. keyframe_positions doit correspondre aux positions renvoyées par le passage précédent — elles ne peuvent pas être re-déduites du
num_frames d'origine après l'exécution d'un passage.
__call__
< source >( prompt: str | list[str] = Nonelatents: Tensor = Nonekeyframes_latents: Tensor = Nonekeyframe_positions: list[int] = Noneaudio_latents: Tensor = Noneconditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 704width: int = 1216num_frames: int = 121frame_rate: float = 24.0source_seconds: float | None = Nonecondition_num_frames: int | None = Noneround_index: int = 1sigmas: list[float] = [0.975, 0.909375, 0.725, 0.421875]noise_scale: float | None = Nonegenerator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Trueoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 1024 ) → LTX2DFRPipelineOutput or tuple
Paramètres
- prompt (
strouList[str], facultatif) — Le prompt ou les prompts pour guider la génération de la vidéo. S'il n'est pas défini, il faut passerprompt_embeds. - latents (
torch.Tensor) — Latents bruts de la vidéo du canevas input,(batch_size, channels, frames, height, width). - keyframes_latents (
torch.Tensor) — Keyframes brutes de transport(batch_size, channels, K, height, width)de l’itération précédente. - keyframe_positions (
list[int]) — Indices des images en pixels deskeyframes_latentssur le canevas input. - audio_latents (
torch.Tensor) — Audio de l’étape 1 figé, dépaqueté et dénormalisé. Chaque tuile reçoit la tranche couvrant sa fenêtre de lecture ; l’audio renvoyé est cette forme d’onde, et non un re-débruitage par tuile. - conditions (
LTX2VideoConditionouList[LTX2VideoCondition], facultatif) — Conditions au niveau des images indexées surcondition_num_frames(la demande d’origine). À chaque itération, la position en pixels d’une condition est multipliée par2 ** round_index. - height (
int, facultatif, par défaut704) — Hauteur en pixels de ce passage (identique à celle de la vidéo entrante). - width (
int, facultatif, par défaut1216) — Largeur en pixels de ce passage. - num_frames (
int, facultatif, par défaut121) — Nombre de trames en pixels de la toile d'entrée (non rognée). - frame_rate (
float, facultatif, par défaut24.0) — FPS de lecture de l'entrée. Le round le double. - source_seconds (
float, facultatif) — Durée de l’audio de l’étape 1 figée. La valeur par défaut estnum_frames / frame_rate, ce qui est correct pour le premier tour ; les tours suivants doivent transmettre la durée d’origine de l’étape 1 afin d’éviter tout décalage des tuiles. - condition_num_frames (
int, facultatif) — Nombre de framesnum_framesde la génération d’origine utilisé pour encoder lesconditions. La valeur par défaut estnum_frames. Après un padding ou un tour précédent, passez la demande d’origine afin queindex=-1ne renvoie pas à la fin du segment padding. - round_index (
int, facultatif, par défaut1) — Numéro de tour basé sur 1. Les tuiles de bruit ancestral sont initialisées avecseed + 1000 * round_index + tile, et les conditions sont mises à l'échelle par2 ** round_index. - sigmas (
list[float], facultatif) — Plan de distillation pour les tuiles de ce tour, sans le0.0terminal. - noise_scale (
float, facultatif) — Niveau de bruit auquel les jetons non conditionnés démarrent. Valeur par défaut :sigmas[0]. - generator (
torch.Generatoroulist[torch.Generator], facultatif) — Générateur(s) aléatoire(s) pour la reproductibilité. Les tirages ancestraux utilisent une graine distincte par tuile, dérivée de lainitial_seed()de ce générateur. - prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte pré-générés. - prompt_attention_mask (
torch.Tensor, facultatif) — Masque d'attention pré-généré pour les embeddings de texte. - decode_timestep (
float, par défaut0.0) — Le timestep auquel la vidéo générée est décodée. - decode_noise_scale (
float, par défautNone) — Échelle du bruit lors du décodage. - use_cross_timestep (
bool, facultatif, valeur par défautTrue) — Indique s'il faut utiliser le sigma inter-modalités pour la modulation de l'attention croisée.Truepour LTX-2.3+. - output_type (
str, facultatif, par défaut"pil") — Format de sortie. Choisissez"pil","np","pt"ou"latent". La sortie latente est le canevas non rogné. - return_dict (
bool, facultatif, par défautTrue) — Indique s'il faut retourner un LTX2DFRPipelineOutput ou un simple tuple(frames, audio, keyframes, keyframe_positions). - attention_kwargs (
dict, facultatif) — Arguments supplémentaires transmis au processeur d'attention. - callback_on_step_end (
Callable, facultatif) — Une fonction appelée à la fin de chaque étape de débruitage, sur chaque tuile. - callback_on_step_end_tensor_inputs (
List, facultatif, par défaut["latents"]) — Entrées tensorielles pour la fonction de rappel. - max_sequence_length (
int, facultatif, par défaut1024) — Longueur maximale de la séquence pour le prompt texte.
Retourne
LTX2DFRPipelineOutput ou tuple
Si return_dict est True, LTX2DFRPipelineOutput est retourné, sinon un tuple de (video, audio, keyframes, keyframe_positions) est retourné.
Exécuter une passe de raffinement temporel.
Exemples :
>>> import torch
>>> from diffusers import LTX2DFRPipeline, LTX2DFRTemporalRefinePipeline, LTXEulerAncestralRFScheduler
>>> from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
>>> pipe = LTX2DFRPipeline.from_pretrained("Lightricks/LTX-2.5-Diffusers", torch_dtype=torch.bfloat16)
>>> temporal_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
... "path/to/converted/temporal_latent_upsampler", torch_dtype=torch.bfloat16
... )
>>> temporal_pipe = LTX2DFRTemporalRefinePipeline(
... scheduler=LTXEulerAncestralRFScheduler(eta=0.5),
... vae=pipe.vae,
... audio_vae=pipe.audio_vae,
... text_encoder=pipe.text_encoder,
... tokenizer=pipe.tokenizer,
... connectors=pipe.connectors,
... transformer=pipe.transformer,
... vocoder=pipe.vocoder,
... temporal_latent_upsampler=temporal_upsampler,
... )
>>> # `out` is a prior DFR pass at the same spatial size, `return_dict=True`.
>>> out = temporal_pipe(
... latents=out.frames,
... keyframes_latents=out.keyframes,
... keyframe_positions=out.keyframe_positions,
... audio_latents=out.audio,
... prompt="A tabby cat stretching in a sunlit window",
... height=1088,
... width=1920,
... num_frames=121,
... output_type="latent",
... )denoise
< source >( latents: Tensorconditioning_mask: Tensorclean_latents: Tensorvideo_coords: Tensorkeyframes_mask: Tensorprompt_embeds: Tensoraudio_prompt_embeds: Tensorprompt_attention_mask: Tensorsigmas: list[float]frame_rate: floataudio_latents: Tensorfreeze_audio: bool = Falsevideo_tile_plan: list | None = Nonegenerator: typing.Optional[torch.Generator] = Noneuse_cross_timestep: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Noneprogress_bar = Nonestep_offset: int = 0callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] | None = None )
Paramètres
- sigmas (
list[float]) — Plan de bruit pour ce passage, sans le terminal0.0. - freeze_audio (
bool, facultatif, valeur par défautFalse) — Conserveaudio_latentspropre (pas de temps/sigma 0, aucune étape Euler audio) tout en exécutant l'attention croisée audio-verso-vidéo. Ignoré lorsqueaudio_latentsestNone. - video_tile_plan (
list, facultatif) — Plan de jetons par tuile issu devideo_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. Lorsqu’il est fourni, chaque étape exécute le transformer une fois par tuile et fusionne les prédictions, de sorte que le sampler avance toujours sur une seule toile complète et que les tuiles concordent sur leurs chevauchements à chaque étape. - generator (
torch.Generator, facultatif) — Transmis àLTXEulerAncestralRFScheduler.step(). Les tuiles temporelles passent une graine par tuile afin que les tirages ancestraux ne partagent pas un même flux et ne consomment pas l’état que le bruitage initial de la tuile suivante lit. L’Euler distillé ne le lit pas. - step_offset (
int) — Index de la première étape de ce passage dans l’ensemble du calendrier du pipeline, utilisé pourcallback_on_step_endet la barre de progression partagée.
Effectuer un passage de débruitage DFR sur sigmas et retourner (latents, audio_latents), tous deux encore empilés.
L’horaire distillé est utilisé sans guidage sans classifieur, ce qui correspond à un seul appel au transformeur par étape.
Chaque passe exécute les deux flux, car la branche vidéo a besoin de l’attention intermodale, même lorsque l’audio qu’elle
produit est jeté. freeze_audio=True maintient le flux audio à sigma 0 (pas d’étape d’Euler) afin que la vidéo
puisse toujours effectuer une attention croisée avec celui-ci — les tuiles de raffinement temporel et l’épilogue utilisent
ce mécanisme pour suivre la parole de l’étape 1 sans que chaque tuile ne redébruite une réalisation audio différente.
Après le mélange de conditionnement x0, la vitesse est (latents - denoised) / sigma, de sorte qu'une étape RF x0 = x - σ v récupère le denoised mélangé. Les étapes 1 / 2 / l'épilogue conservent FlowMatchEulerDiscreteScheduler et appliquent cette étape d'Euler telle quelle. Le raffinement temporel remplace par LTXEulerAncestralRFScheduler (eta=0.5) ; cette étape rebruit chaque jeton, il faut donc réappliquer le mélange de conditionnement par la suite, sinon les ancrages de couture de force 0,95 s'érodent.
encode_conditions
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | Noneheight: intwidth: intnum_frames: intdevice: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = Nonegenerator: typing.Optional[torch.Generator] = None )
Prétraitez et encodez les conditions de trame avec le VAE, positionnées par trame de pixels.
Retourne (pixel_frame_index, latent, strength, num_pixel_frames) pour chaque condition, prêt pour condition_latents de prepare_latents(). L’encodage est maintenu séparé du placement car les tours de raffinement temporel échelonnent la position d’une condition par 2 ** round et la réinitialisent par tuile, et ne doivent pas réencoder la même image fixe une fois par tuile pour ce faire.
L’indice retourné est sur la grille de pixels propre à num_frames ; le transfert sur un canevas affiné est à la charge de l’appelant.
encode_prompt
< source >( prompt: str | list[str]num_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Paramètres
- prompt (
stroulist[str], facultatif) — prompt à encoder - num_videos_per_prompt (
int, facultatif, valeur par défaut 1) — Nombre de vidéos à générer par invite. - prompt_embeds (
torch.Tensor, facultatif) — Embeddings de texte pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, les embeddings de texte seront générés à partir de l'argument d'entréeprompt. - prompt_attention_mask (
torch.Tensor, facultatif) — Masque d'attention pré-généré pourprompt_embeds. - device — (
torch.device, facultatif) : torch device - dtype — (
torch.dtype, facultatif) : dtype torch
Encode le prompt dans les états cachés de l'encodeur de texte.
DFR exécute le calendrier sigma distillé, qui est entraîné pour être utilisé sans guidage sans classifieur, il n'y a donc pas de branche négative ici.
prepare_latents
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Nonecondition_latents: list[tuple[int, torch.Tensor, float, int]] | None = Nonekeyframe_latents: list[tuple[int, torch.Tensor, float]] | None = Noneslot_frame_indices: list[int] | None = Noneslot_initial_latents: typing.Optional[torch.Tensor] = Nonereference_latents: typing.Optional[torch.Tensor] = Nonereference_downscale_factor: int = 1batch_size: int = 1num_channels_latents: int = 128height: int = 512width: int = 768num_frames: int = 121frame_rate: float = 24.0noise_scale: float = 1.0dtype: typing.Optional[torch.dtype] = Nonedevice: typing.Optional[torch.device] = Nonegenerator: typing.Optional[torch.Generator] = Nonelatents: typing.Optional[torch.Tensor] = Nonelatents_normalized: bool = True ) → tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, slice | None]
Paramètres
- conditions (
list[LTX2VideoCondition], facultatif) — Conditions d'image / vidéo au niveau des images, positionnées par index latent. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], facultatif) — Substitut déjà encodé pourconditions, sous la forme(pixel_frame_index, latent, strength, num_pixel_frames). L’index est en pixels plutôt qu’en latents, car une passe de raffinement temporel multiplie la position d’une condition par2 ** roundet le résultat ne tombe généralement pas sur une frontière de latents — seul un jeton de cléframe ajouté peut s’y situer, et il est placé par pixel.pixel_frame_index == 0signifie toujours « remplacer la première image ». - keyframe_latents (
list[tuple[int, torch.Tensor, float]], facultatif) — Guides de keyframes déjà encodés sous la forme(pixel_frame_index, latent, strength), oùlatenta la forme(batch_size, num_channels_latents, 1, latent_height, latent_width). Utilisé par les passes de raffinement temporel pour ancrer les keyframes de couture transmises depuis la passe précédente. - slot_frame_indices (
list[int], facultatif) — Positions des images-pixels des emplacements des images clés générées. - slot_initial_latents (
torch.Tensor, facultatif) —(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)contenu écrit dans les jetons de slot avant le bruitage. - reference_latents (
torch.Tensor, facultatif) —(batch_size, num_channels_latents, F, H, W)latent de référence IC-LoRA. - reference_downscale_factor (
int, par défaut1) — Ratio entre la résolution cible et la résolution de référence. - latents (
torch.Tensor, facultatif) —(batch_size, num_channels_latents, F, H, W)contenu initial pour les jetons de base. Les latents du pipeline public sont bruts (non normalisés) ; passezlatents_normalized=Falseà cette frontière. Les boucles de tuiles qui sont déjà dans l’espace normalisé par le VAE conservent la valeur par défaut. - latents_normalized (
bool, par défautTrue) — Indique silatents,slot_initial_latents,reference_latentsetkeyframe_latentssont déjà normalisés par le VAE. Les boucles internes de tuiles passentTrue; chaque__call__de pipeline passeFalse. - noise_scale (
float, par défaut1.0) — Niveau de bruit auquel les jetons non conditionnés sont initialisés, c’est-à-dire la première sigma de l’ordonnancement.
Retourne
tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, slice | None]
(latents, conditioning_mask, clean_latents, video_coords, keyframes_mask, slot_token_slice).
slot_token_slice indexe les jetons de créneaux de keyframes générés dans la séquence compactée, ou vaut None si aucun
créneau n’a été demandé.
Préparez les latents vidéo bruités et empilés pour un passage de débruitage DFR.
La séquence compacte est disposée comme suit : [base | keyframes | slots | reference] :
- Les jetons de base couvrent la grille latente cible, initialisée à partir de
latentslorsqu’ils sont fournis. - Les conditions de trame avec
index == 0définissent la cible propre aux positions de la première trame ; celles avecindex > 0et chaque entrée dekeyframe_latentssont ajoutées en tant que jetons de trame clé supplémentaires avec un masque de conditionnement par jeton égal à leur intensité. slot_frame_indicesajoute, pour chaque position, un lot de jetons de keyframe générés correspondant à une frame latente, avec un masque de conditionnement0(entièrement débruité) et une étendue temporelle RoPE d’exactement une frame pixel. Ce sont les slots de keyframe qui apportent les frames supplémentaires à DFR ;slot_initial_latentsinitialise leur contenu.reference_latentsajoute le latent de résolution moitié de l’étape 1 comme référence IC-LoRA entièrement propre, avec les coordonnées spatiales mises à l’échelle parreference_downscale_factorafin qu’il corresponde à l’espace de coordonnées cible.
Les jetons de conditionnement ajoutés portent leur contenu dans clean_latents et un zéro de remplacement dans latents, tandis que les emplacements de images clés portent leur graine dans latents et des zéros dans clean_latents — les latents retournés sont le mélange bruité des deux (voir l’étape de bruitage à la fin de cette méthode).
preprocess_conditions
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 512width: int = 768num_frames: int = 121device: typing.Optional[torch.device] = None ) → Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Paramètres
- conditions (
LTX2VideoConditionorList[LTX2VideoCondition], optional, defaults toNone) — A list of image/video condition instances. - height (
int, facultatif, par défaut512) — La hauteur souhaitée en pixels. - width (
int, facultatif, par défaut768) — La largeur souhaitée en pixels. - num_frames (
int, facultatif, par défaut121) — Le nombre de frames souhaité dans la vidéo générée. - device (
torch.device, facultatif, par défautNone) — L'appareil sur lequel placer les tenseurs d'images/vidéos prétraitées.
Retourne
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Retourne un 4-uplet de listes de longueur len(conditions) comme suit :
- La première liste est une liste de tenseurs vidéo prétraités de forme [batch_size=1, num_channels, num_frames, height, width].
- La deuxième liste est une liste de forces de conditionnement.
- La troisième liste est une liste d'indices de l'espace latent pour chaque condition.
- La quatrième liste est une liste de nombres de trames (rognées) dans l’espace des pixels par condition. Elle est nécessaire pour la sémantique des coordonnées des images clés (les images clés d’une seule trame de pixel ont une étendue temporelle bornée).
Prétraite les images/vidéos de condition en tenseurs torch.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Réduire une séquence de conditionnement au nombre de frames autorisé.
Exécutez upsampler sur les latents normalisés, en effectuant un aller-retour dans l'espace latent brut du VAE, comme il l'attend.
LTX2DFRPipelineOutput
classe diffusers.LTX2DFRPipelineOutput
< source >( frames: Tensoraudio: Tensorkeyframes: typing.Optional[torch.Tensor] = Nonekeyframe_positions: list[int] | None = None )
Paramètres
- frames (
torch.Tensor,np.ndarrayou list[list[PIL.Image.Image]]) — Vidéo débruitée. La sortie latente est le canevas non rogné, de forme(batch_size, num_channels, latent_frames, latent_height, latent_width). - audio (
torch.Tensor,np.ndarray) — Latents audio ou forme d’onde associés. - keyframes (
torch.Tensor, optional) — Generated or carried keyframe latents of shape(batch_size, num_channels, num_keyframes, latent_height, latent_width).Nonewhenoutput_type != "latent", or when the pass did not produce slots (e.g. a tiled epilogue). - keyframe_positions (
list[int], facultatif) — Index de la trame en pixels de chaque image clé sur la toile de ce passage ;Nonechaque fois quekeyframesestNone. Après un cycle temporel, elles ne peuvent plus être dérivées dunum_framesd’origine et doivent être transmises à l’étape suivante.
Classe de sortie pour les pipelines DFR.
LTX2LatentUpsamplePipeline
classe diffusers.LTX2LatentUpsamplePipeline
< source >( vae: AutoencoderKLLTX2Videolatent_upsampler: LTX2LatentUpsamplerModel )
__call__
< source >( video: list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]] | None = Noneheight: int = 512width: int = 768num_frames: int = 121spatial_patch_size: int = 1temporal_patch_size: int = 1latents: typing.Optional[torch.Tensor] = Nonelatents_normalized: bool = Falsedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneadain_factor: float = 0.0tone_map_compression_ratio: float = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneoutput_type: str | None = 'pil'return_dict: bool = True ) → ~pipelines.ltx.LTXPipelineOutput or tuple
Paramètres
- video (
list[PipelineImageInput], facultatif) — La vidéo à suréchantillonner (par exemple, la sortie de la première étape de LTX 2.0). Si elle n’est pas fournie,latentsdoit être fourni. - height (
int, facultatif, par défaut512) — La hauteur en pixels de la vidéo d’entrée (et non de la vidéo générée, qui aura une résolution plus élevée). - width (
int, facultatif, par défaut768) — La largeur en pixels de la vidéo d’entrée (et non de la vidéo générée, qui aura une résolution plus élevée). - num_frames (
int, facultatif, par défaut121) — Le nombre d'images de la vidéo d'entrée. - spatial_patch_size (
int, facultatif, par défaut1) — La taille des patches spatiaux des latents vidéo. Utilisé lorsquelatentsest fourni si un dépaquetage est nécessaire. - temporal_patch_size (
int, facultatif, par défaut1) — La taille des patches temporels des latents vidéo. Utilisé lorsquelatentsest fourni si le dépaquetage est nécessaire. - latents (
torch.Tensor, facultatif) — Latents vidéo pré-générés. Peut être fourni à la place de l'argumentvideo. Peut être soit une séquence de patches de forme(batch_size, seq_len, hidden_dim), soit un latent vidéo de forme(batch_size, latent_channels, latent_frames, latent_height, latent_width). - latents_normalized (
bool, optional, defaults toFalse) — Iflatentsare supplied, whether thelatentsare normalized using the VAE latent mean and std. IfTrue, thelatentswill be denormalized before being supplied to the latent upsampler. - decode_timestep (
float, par défaut0.0) — Le timestep auquel la vidéo générée est décodée. - decode_noise_scale (
float, par défautNone) — Le facteur d'interpolation entre le bruit aléatoire et les latents débruités à l'étape de décodage. - adain_factor (
float, facultatif, valeur par défaut0.0) — Facteur de mélange de la normalisation d'instance adaptative (AdaIN) entre les latents suréchantillonnés et les latents d'origine. Doit être compris dans l'intervalle [-10.0, 10.0] ; fournir 0.0 (la valeur par défaut) signifie que l'AdaIN n'est pas appliquée. - tone_map_compression_ratio (
float, facultatif, par défaut0.0) — L'intensité de compression pour le tone mapping, qui réduit la plage dynamique des valeurs latentes. Cela est utile pour régulariser les latentes à forte variance ou pour conditionner les sorties lors de la génération. Doit être compris dans [0, 1], où 0.0 (la valeur par défaut) signifie que le tone mapping n'est pas appliqué et 1.0 correspond à l'effet de compression complet. - generator (
torch.Generatoroulist[torch.Generator], facultatif) — Un ou une liste de générateurs torch pour rendre la génération déterministe. - output_type (
str, facultatif, par défaut"pil") — Le format de sortie de l'image générée. Choisissez entre PIL :PIL.Image.Imageounp.array. - return_dict (
bool, facultatif, par défautTrue) — Indique s'il faut retourner un~pipelines.ltx.LTXPipelineOutputplutôt qu'un simple tuple.
Retourne
~pipelines.ltx.LTXPipelineOutput ou tuple
Si return_dict est True, ~pipelines.ltx.LTXPipelineOutput est retourné, sinon un tuple est retourné dont le premier élément est la vidéo upsampled.
Fonction appelée lors de l'appel du pipeline pour la génération.
Exemples :
>>> import torch
>>> from diffusers import LTX2ImageToVideoPipeline, LTX2LatentUpsamplePipeline
>>> from diffusers.utils import encode_video
>>> from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
>>> from diffusers.utils import load_image
>>> pipe = LTX2ImageToVideoPipeline.from_pretrained("Lightricks/LTX-2", torch_dtype=torch.bfloat16)
>>> pipe.enable_model_cpu_offload()
>>> image = load_image(
... "https://huggingface.co/datasets/a-r-r-o-w/tiny-meme-dataset-captioned/resolve/main/images/8.png"
... )
>>> prompt = "A young girl stands calmly in the foreground, looking directly at the camera, as a house fire rages in the background."
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"
>>> frame_rate = 24.0
>>> video, audio = pipe(
... image=image,
... prompt=prompt,
... negative_prompt=negative_prompt,
... width=768,
... height=512,
... num_frames=121,
... frame_rate=frame_rate,
... num_inference_steps=40,
... guidance_scale=4.0,
... output_type="pil",
... return_dict=False,
... )
>>> latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
... "Lightricks/LTX-2", subfolder="latent_upsampler", torch_dtype=torch.bfloat16
... )
>>> upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
>>> upsample_pipe.vae.enable_tiling()
>>> upsample_pipe.to(device="cuda", dtype=torch.bfloat16)
>>> video = upsample_pipe(
... video=video,
... width=768,
... height=512,
... output_type="np",
... return_dict=False,
... )[0]
>>> encode_video(
... video[0],
... fps=frame_rate,
... audio=audio[0].float().cpu(),
... audio_sample_rate=pipe.vocoder.config.output_sampling_rate, # should be 24000
... output_path="video.mp4",
... )adain_filter_latent
< source >( latents: Tensorreference_latents: Tensorfactor: float = 1.0 ) → torch.Tensor
Paramètres
- latents (
torch.Tensor) — Latents d’entrée à normaliser - reference_latents (
torch.Tensor) — Les latents de référence fournissant les statistiques de style. - factor (
float) — Facteur de mélange entre le latent original et le latent transformé. Plage : -10.0 à 10.0, valeur par défaut : 1.0
Retourne
torch.Tensor
Le tenseur latent transformé
Applique la normalisation d'instance adaptative (AdaIN) à un tenseur latent en fonction des statistiques d'un tenseur latent de référence.
tone_map_latents
< source >( latents: Tensorcompression: float )
Paramètres
- latents — torch.Tensor Tenseur latent d'entrée de forme arbitraire. Il est attendu qu'il soit approximativement dans l'intervalle [-1, 1] ou [0, 1].
- compression — float
Intensité de la compression dans l'intervalle [0, 1].
- 0.0 : aucun mappage de ton (transformation identité)
- 1.0 : Effet de compression complet
Applique une fonction de mappage de tonalité non linéaire aux valeurs latentes afin de réduire leur plage dynamique de manière perceptuellement lisse, en utilisant une compression basée sur une sigmoïde.
Cela est utile pour régulariser les latents à forte variance ou pour conditionner les sorties lors de la génération, en particulier lors du contrôle du comportement dynamique avec un facteur de compression.
LTX2VideoDiffusionDecodePipeline
classe diffusers.LTX2VideoDiffusionDecodePipeline
< source >( diffusion_decoder: LTX2VideoDiffusionDecoderModelschedulervae: AutoencoderKLLTX2Video = None )
Paramètres
- diffusion_decoder (LTX2VideoDiffusionDecoderModel) — Le décodeur vidéo par diffusion.
- scheduler (FlowMatchEulerDiscreteScheduler) — Planificateur qui pilote les étapes de débruitage du décodeur.
- vae (AutoencoderKLLTX2Video, facultatif) — Consulté uniquement pour les statistiques latentes utilisées pour la dénormalisation. S’il est omis, le pipeline utilise les valeurs par défaut de LTX-2, de sorte qu’un flux de travail de décodage seul n’a pas à charger un second autoencodeur.
Décoder les latents vidéo LTX-2 avec le décodeur de diffusion introduit dans LTX-2.5.
Contrairement à un décodeur convolutif, celui-ci est lui-même un petit modèle de diffusion : il débruite les pixels en fonction d’un volume de contexte construit à partir des latents, il a donc besoin d’un planificateur et d’un générateur. Associez-le à n’importe quel pipeline LTX-2 exécuté avec output_type="latent", en passant denormalize=False car cette voie a déjà appliqué les statistiques des latents.
__call__
< source >( latents: Tensorgenerator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneoutput_type: str = 'pil'return_dict: bool = Truedenormalize: bool = True ) → LTX2VideoDecodeOutput or tuple
Paramètres
- latents (
torch.Tensor) — Latents de forme(B, C, F, H, W). Notez qu’une exécution du pipeline LTX-2 avecoutput_type="latent"renvoie des latents déjà dénormalisés ; passez doncdenormalize=Falsepour ceux-ci. - generator (
torch.Generator, facultatif) — Le décodeur échantillonne le bruit qu’il débruite ; passez un générateur pour rendre le décodage reproductible. - output_type (
str, facultatif, par défaut"pil") — Le format de sortie de la vidéo décodée. Choisissez entre"pil","np","pt"et"latent". - return_dict (
bool, facultatif, par défautTrue) — Indique s'il faut retourner unLTX2VideoDecodeOutputplutôt qu'un simple tuple. - denormalize (
bool, facultatif, par défautTrue) — Indique s'il faut appliquer les statistiques latentes avant le décodage. Définissez surFalsesi les latentes sont déjà dénormalisées.
Retourne
LTX2VideoDecodeOutput ou tuple
LTX2DurationHead
classe diffusers.pipelines.ltx2.LTX2DurationHead
< source >( video_cross_attention_dim: int = 4096audio_cross_attention_dim: int = 2048pooler_hidden_dim: int = 256num_queries: int = 1num_pooler_heads: int = 4mlp_hidden_dim: int = 256 )
Paramètres
- video_cross_attention_dim (
int, par défaut4096) — Largeur de la sortie du connecteur vidéo. - audio_cross_attention_dim (
int, par défaut2048) — Largeur de la sortie du connecteur audio. - pooler_hidden_dim (
int, par défaut256) — Dimension cachée partagée dans laquelle les deux modalités sont projetées. - num_queries (
int, par défaut1) — Nombre de requêtes de pooling apprenables. - num_pooler_heads (
int, par défaut4) — Têtes d'attention utilisées par le pooler. - mlp_hidden_dim (
int, par défaut256) — Largeur cachée du MLP de sortie. Le nom porte un suffixe_dimpour éviter toute collision avec le sous-modulemlp_hidden, queConfigMixin.__getattr__masquerait autrement avec cette valeur de configuration.
Prédit la durée naturelle de la prise suggérée par une légende, à partir des sorties du connecteur texte de LTX-2.
La tête est agnostique par rapport à la modalité : passez la sortie du connecteur vidéo, celle de l’audio, ou les deux. Les projections d’entrée spécifiques à chaque modalité projettent chaque flux dans une dimension de pooler partagée, des embeddings de modalité apprenables étiquettent les flux afin que le pooler puisse les distinguer, et un petit MLP transforme le vecteur poolé en durée logarithmique. La cible de régression est entraînée en secondes logarithmiques, de sorte que forward exponentie et que les appelants reçoivent toujours des secondes.
Disponible à partir des points de contrôle LTX-2.5.
forward
< source >( video_tokens: typing.Optional[torch.Tensor] = Noneaudio_tokens: typing.Optional[torch.Tensor] = None ) → torch.Tensor of shape (batch_size,)
Paramètres
- video_tokens (
torch.Tensorde forme(batch_size, seq_len, video_cross_attention_dim), facultatif) — Sortie du connecteur vidéo. - audio_tokens (
torch.Tensorde forme(batch_size, seq_len, audio_cross_attention_dim), facultatif) — Sortie du connecteur audio.
Retourne
torch.Tensor de forme (batch_size,)
la durée prédite en secondes.
predict_num_frames
< source >( video_tokens: typing.Optional[torch.Tensor] = Noneaudio_tokens: typing.Optional[torch.Tensor] = Noneframe_rate: floattemporal_compression_ratio: intmin_seconds: float = 1.0max_seconds: float = 20.0 ) → int
Paramètres
- video_tokens (
torch.Tensor, facultatif) — Sortie du connecteur vidéo pour un seul prompt. - audio_tokens (
torch.Tensor, facultatif) — Sortie du connecteur audio pour un seul prompt. - frame_rate (
float) — Nombre d'images par seconde utilisé pour convertir la durée prédite en nombre d'images. - temporal_compression_ratio (
int) — Le ratio de compression temporelle du VAE, qui définit la grille de frames. - min_seconds (
float, par défaut1.0) — Borne inférieure de la prédiction. - max_seconds (
float, par défaut20.0) — Limite supérieure de la prédiction.
Retourne
int
un nombre de images aligné sur la grille temporelle du VAE.
Prédit un nombre d’images à partir des jetons de connecteur, borné à [min_seconds, max_seconds] et aligné sur la grille temporelle causale du VAE (k * temporal_compression_ratio + 1).
Le clamp est appliqué avant le snapping : un nombre de frames clamped n’est pas nécessairement aligné sur la grille, donc effectuer le snapping en premier donnerait un résultat différent. Comme le snapping arrondit par défaut, il peut aboutir en dessous du minimum ; dans ce cas, le résultat est arrondi par excès au point de grille suivant, afin que le nombre de frames reste dans les limites.
Des bornes étroites peuvent aboutir à une fenêtre de trame ne contenant aucun point de grille — à 24 fps, [1.0s, 1.02s] est arrondi à [24, 24], et 24 n’est pas de la forme 8k + 1. Le point de grille le plus proche est alors utilisé et un avertissement est consigné, car dépasser la limite de moins d’un pas de grille est préférable à refuser la génération. Le nombre retourné est donc toujours aligné sur la grille, mais peut se situer juste en dehors des bornes demandées dans ce cas.
LTX2PipelineOutput
classe diffusers.pipelines.ltx2.LTX2PipelineOutput
< source >( frames: Tensoraudio: Tensor )
Paramètres
- frames (
torch.Tensor,np.ndarrayou list[list[PIL.Image.Image]]) — Liste des sorties vidéo - Il peut s'agir d'une liste imbriquée de longueurbatch_size,où chaque sous-liste contient des séquences d'images PIL débruitées de longueurnum_frames.Il peut également s'agir d'un tableau NumPy ou d'un tenseur Torch de forme(batch_size, num_frames, channels, height, width). - audio (
torch.Tensor,np.ndarray) — À faire
Classe de sortie pour les pipelines LTX.
LTX2ModularPipeline
classe diffusers.LTX2ModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
Un ModularPipeline pour LTX-2 (génération conjointe de vidéo et d'audio).
LTX2AutoBlocks
Auto blocks pour LTX-2 prenant en charge la génération texte-vers-vidéo, image-vers-vidéo, condition-vers-vidéo et in-context (IC-LoRA) (vidéo + audio conjointes).
Workflows pris en charge :
text2video: nécessitepromptimage2video: nécessiteimage,promptcondition: nécessiteconditions,promptin_context: nécessitereference_conditions,num_frames,prompt
Composants :
prompt_enhancer (PreTrainedModel) processor (ProcessorMixin) text_encoder (PreTrainedModel) tokenizer
(PreTrainedTokenizerBase) connectors (LTX2TextConnectors) duration_head (LTX2DurationHead) vae
(AutoencoderKLLTX2Video) video_processor (VideoProcessor) transformer (LTX2VideoTransformer3DModel)
scheduler (FlowMatchEulerDiscreteScheduler) audio_vae (AutoencoderKLLTX2Audio) guider (LTX2Guidance)
audio_guider (LTX2Guidance) vocoder (LTX2Vocoder)
Entrées :
prompt (str, facultatif) :
Le prompt ou les prompts pour guider la génération d'image.
conditions (list, facultatif) : LTX2VideoCondition (ou une liste de ceux-ci) plaçant des conditions d'image/vidéo aux indices de trames latentes de la
vidéo générée.
enable_prompt_enhancement (bool, facultatif, par défaut False) :
Indique s'il faut exécuter l'améliorateur de prompt. Option à activer explicitement, conformément aux pipelines de référence Lightricks.
system_prompt (str, facultatif) :
Prompt système pour l'amélioration. Par défaut, LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT si une trame de condition PIL.Image.Image est disponible, sinon LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT.
prompt_max_new_tokens (int, facultatif) :
Nombre maximal de nouveaux jetons à générer lors de l'amélioration du prompt. Par défaut, 600, le budget de l'améliorateur Gemma-4 de LTX-2.5.
prompt_enhancement_kwargs (dict, facultatif) :
Arguments par mot-clé pour l'appel .generate de l'améliorateur. Par défaut, décodage glouton.
prompt_enhancement_seed (int, facultatif, par défaut 10) :
Graine aléatoire pour l'amélioration du prompt (sans effet avec le décodage glouton de LTX-2.5).
generator (Generator, facultatif) :
Générateur Torch pour une génération déterministe.
image (Image | list, facultatif) :
Image(s) de référence pour le débruitage. Peut être une image unique ou une liste d'images.
negative_prompt (str, facultatif) :
Le prompt ou les prompts qui ne doivent pas guider la génération d'image.
max_sequence_length (int, facultatif, par défaut 1024) :
Longueur de séquence maximale pour l'encodage du prompt.
min_seconds (float, facultatif, par défaut 1.0) :
Borne inférieure de la durée prédite automatiquement.
max_seconds (float, facultatif, par défaut 20.0) :
Borne supérieure de la durée prédite automatiquement. Doit être strictement supérieure à min_seconds.
frame_rate (float, facultatif, par défaut 24.0) :
Nombre de trames par seconde de la vidéo générée.
height (int, facultatif, par défaut 512) :
La hauteur en pixels de l'image générée.
width (int, facultatif, par défaut 704) :
La largeur en pixels de l'image générée.
image_crf (int, facultatif) :
CRF H.264 utilisé pour recompresser l'image de conditionnement avant l'encodage VAE, correspondant à la compression
contre laquelle le modèle a été entraîné. None (par défaut) est résolu à partir de la génération du texte-encodeur (33 jusqu'à
LTX-2.3, 18 pour LTX-2.5). Passez 0 pour ignorer la recompression. Nécessite un PIL.Image.Image lorsque
la recompression est exécutée.
num_frames (int, facultatif) :
Le nombre de trames dans la vidéo générée. Omettez pour prédire automatiquement via duration_head (voir LTX2AutoDurationStep).
reference_conditions (list, facultatif) : LTX2ReferenceCondition (ou une liste de ceux-ci) dont les vidéos sont encodées en jetons latents supplémentaires auxquels l'adaptateur
IC-LoRA prête attention.
reference_downscale_factor (int, facultatif, par défaut 1) :
Ratio entre les résolutions cible et de référence ; 2 signifie que la référence est prétraitée à la moitié de la
résolution cible. Les coordonnées spatiales sont mises à l'échelle par ce facteur afin que les jetons de référence se situent dans
l'espace de coordonnées cible. Doit correspondre au facteur avec lequel l'IC-LoRA a été entraîné.
conditioning_attention_strength (float, facultatif, par défaut 1.0) :
Scalaire dans [0, 1] contrôlant la force avec laquelle les jetons bruités et les jetons de référence se prêtent attention mutuellement. 1.0
(par défaut) laisse l'attention non masquée.
conditioning_attention_mask (Tensor, facultatif) :
Masque facultatif dans l'espace des pixels de forme (1, 1, F, H, W) avec des valeurs dans [0, 1] donnant une force d'attention
variant spatialement. Sous-échantillonné à la grille latente de la référence et multiplié par conditioning_attention_strength.
motion_speed (float, facultatif, par défaut 1.0) :
Vitesse du mouvement par rapport au temps réel. Les plongements positionnels sont conditionnés sur frame_rate / motion_speed, de sorte que les valeurs inférieures à 1 ralentissent le mouvement, par exemple 0.2 pour le ralenti 5x du LoRA Slow-Motion-Control. frame_rate reste le taux de lecture.
num_videos_per_prompt (int, facultatif, par défaut 1) :
Le nombre d'images à générer par prompt.
condition_latents (list, facultatif) :
Latents VAE normalisés par condition de forme [1, C, F, H, W].
condition_strengths (list, facultatif) :
Forces de conditionnement par condition.
condition_indices (list, facultatif) :
Indice de trame latente par condition auquel la condition est appliquée.
condition_pixel_frames (list, facultatif) :
Nombre de trames pixels rognées par condition, utilisé pour limiter les coordonnées des trames clés uniques.
reference_latents (Tensor, facultatif) :
Jetons de référence empilés de forme [1, total_reference_tokens, C], ou None si aucune condition de référence
n'a été fournie (LTX2AutoReferenceEncoderStep est ignoré).
reference_coords (Tensor, facultatif) :
Coordonnées RoPE pour les jetons de référence.
reference_token_counts (list, facultatif) :
Nombres de jetons par référence, dans l'ordre de reference_conditions.
latents (Tensor) :
Latents bruités pré-générés pour la génération d'image.
noise_scale (float, facultatif) :
Niveau de bruit initial pour les jetons non conditionnés. None (par défaut) est résolu à sigmas[0] si des sigmas personnalisés sont fournis, sinon 1.0.
sigmas (list, facultatif) :
Sigmas personnalisés pour le processus de débruitage.
reference_cross_mask (Tensor, facultatif) :
Forces d'attention bruité<->référence par jeton de référence de forme [1, num_ref_tokens].
num_inference_steps (int) :
Le nombre d'étapes de débruitage.
timesteps (Tensor) :
Pas de temps pour le processus de débruitage.
audio_latents (Tensor) :
Latents audio pré-encodés facultatifs ; un bruit aléatoire est utilisé s'ils ne sont pas fournis.
*denoiser_input_fields (None,facultatif) :
entrées conditionnelles du modèle pour le débruiteur : par exemple prompt_embeds, negative_prompt_embeds, etc.
use_cross_timestep (bool,facultatif, par défaut True) :
Indique s'il faut conditionner le transformeur sur un pas de temps croisé séparé par jeton (LTX-2.3+).
attention_kwargs (dict,facultatif) :
Kwargs supplémentaires pour les processeurs d'attention.
image_latents (Tensor,facultatif) :
Latents d'image de référence encodés par VAE utilisés pour le conditionnement image-vers-vidéo.
output_type (str,facultatif, par défaut pil) :
Format de sortie : ‘pil’, ‘np’, ‘pt’.
decode_timestep (None,facultatif, par défaut 0.0) :
Le pas de temps auquel le VAE décode les latents finaux.
decode_noise_scale (None,facultatif*) :
Facteur d'interpolation du bruit appliqué aux latents au pas de temps de décodage.
Sorties :
vidéos (list) :
Les vidéos générées.
audio (Tensor) :
La forme d'onde audio générée.
LTX25ModularPipeline
classe diffusers.LTX25ModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
Un ModularPipeline pour LTX-2.5 (génération conjointe de vidéo et d'audio).
Identique à LTX2ModularPipeline, à l’exception de ses blocs par défaut qui décodent avec le décodeur vidéo de diffusion, qui est le comportement natif par défaut à partir de LTX-2.5. Un point de contrôle est routé ici via modular_model_index.json.
LTX25AutoBlocks
Auto blocks pour LTX-2.5 prenant en charge la génération texte-vers-vidéo, image-vers-vidéo, condition-vers-vidéo et in-context (IC-LoRA) (vidéo + audio conjointes). Identique à LTX2AutoBlocks à l'exception du décodeur vidéo qui est LTX2DiffusionVaeDecoderStep, car le décodeur de diffusion est le défaut natif à partir de LTX-2.5. Pour décoder avec le VAE convolutif à la place, remplacez le bloc de décodage : blocks.sub_blocks["decode"] = LTX2AutoDecoderStep().
Workflows pris en charge :
text2video: nécessitepromptimage2video: nécessiteimage,promptcondition: nécessiteconditions,promptin_context: nécessitereference_conditions,num_frames,prompt
Composants :
prompt_enhancer (PreTrainedModel) processor (ProcessorMixin) text_encoder (PreTrainedModel) tokenizer
(PreTrainedTokenizerBase) connectors (LTX2TextConnectors) duration_head (LTX2DurationHead) vae
(AutoencoderKLLTX2Video) video_processor (VideoProcessor) transformer (LTX2VideoTransformer3DModel)
scheduler (FlowMatchEulerDiscreteScheduler) audio_vae (AutoencoderKLLTX2Audio) guider (LTX2Guidance)
audio_guider (LTX2Guidance) diffusion_decoder (LTX2VideoDiffusionDecoderModel) vocoder (LTX2Vocoder)
Entrées :
prompt (str, facultatif) :
Le prompt ou les prompts pour guider la génération d'image.
conditions (list, facultatif) : LTX2VideoCondition (ou une liste de ceux-ci) plaçant des conditions image/vidéo aux indices de trames latentes de la
vidéo générée.
enable_prompt_enhancement (bool, facultatif, par défaut False) :
Indique s'il faut exécuter l'améliorateur de prompt. Option à activer explicitement, conformément aux pipelines de référence Lightricks.
system_prompt (str, facultatif) :
Prompt système pour l'amélioration. Par défaut, LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT si une trame de condition PIL.Image.Image est disponible, sinon LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT.
prompt_max_new_tokens (int, facultatif) :
Nombre maximal de nouveaux jetons à générer lors de l'amélioration du prompt. Par défaut, 600, le budget de l'améliorateur Gemma-4 de LTX-2.5.
prompt_enhancement_kwargs (dict, facultatif) :
Arguments par mot-clé pour l'appel .generate de l'améliorateur. Par défaut, décodage glouton.
prompt_enhancement_seed (int, facultatif, par défaut 10) :
Graine aléatoire pour l'amélioration du prompt (sans effet avec le décodage glouton de LTX-2.5).
generator (Generator, facultatif) :
Générateur Torch pour une génération déterministe.
image (Image | list, facultatif) :
Image(s) de référence pour le débruitage. Peut être une image unique ou une liste d'images.
negative_prompt (str, facultatif) :
Le prompt ou les prompts qui ne doivent pas guider la génération d'image.
max_sequence_length (int, facultatif, par défaut 1024) :
Longueur de séquence maximale pour l'encodage du prompt.
min_seconds (float, facultatif, par défaut 1.0) :
Borne inférieure de la durée prédite automatiquement.
max_seconds (float, facultatif, par défaut 20.0) :
Borne supérieure de la durée prédite automatiquement. Doit être strictement supérieure à min_seconds.
frame_rate (float, facultatif, par défaut 24.0) :
Nombre de trames par seconde de la vidéo générée.
height (int, facultatif, par défaut 512) :
La hauteur en pixels de l'image générée.
width (int, facultatif, par défaut 704) :
La largeur en pixels de l'image générée.
image_crf (int, facultatif) :
CRF H.264 utilisé pour recompresser l'image de conditionnement avant l'encodage VAE, afin de correspondre à la compression
contre laquelle le modèle a été entraîné. None (par défaut) est résolu à partir de la génération du texte-encodeur (33 jusqu'à
LTX-2.3, 18 pour LTX-2.5). Passez 0 pour ignorer la recompression. Nécessite un PIL.Image.Image lorsque
la recompression est exécutée.
num_frames (int, facultatif) :
Le nombre de trames dans la vidéo générée. Omettez pour prédire automatiquement via le duration_head (voir LTX2AutoDurationStep).
reference_conditions (list, facultatif) : LTX2ReferenceCondition (ou une liste de ceux-ci) dont les vidéos sont encodées en jetons latents supplémentaires auxquels l'adaptateur
IC-LoRA prête attention.
reference_downscale_factor (int, facultatif, par défaut 1) :
Ratio entre les résolutions cible et de référence ; 2 signifie que la référence est prétraitée à la moitié de la
résolution cible. Les coordonnées spatiales sont mises à l'échelle par ce facteur afin que les jetons de référence se situent dans
l'espace de coordonnées cible. Doit correspondre au facteur avec lequel l'IC-LoRA a été entraîné.
conditioning_attention_strength (float, facultatif, par défaut 1.0) :
Scalaire dans [0, 1] contrôlant la force avec laquelle les jetons bruités et les jetons de référence se prêtent attention mutuellement. 1.0
(par défaut) laisse l'attention non masquée.
conditioning_attention_mask (Tensor, facultatif) :
Masque facultatif en espace pixel de forme (1, 1, F, H, W) avec des valeurs dans [0, 1] donnant une force d'attention
variant spatialement. Sous-échantillonné à la grille latente de la référence et multiplié par conditioning_attention_strength.
motion_speed (float, facultatif, par défaut 1.0) :
Vitesse du mouvement par rapport au temps réel. Les plongements positionnels sont conditionnés sur frame_rate / motion_speed, de sorte que les valeurs inférieures à 1 ralentissent le mouvement, par exemple 0.2 pour le ralenti 5x du LoRA Slow-Motion-Control. frame_rate reste le taux de lecture.
num_videos_per_prompt (int, facultatif, par défaut 1) :
Le nombre d'images à générer par prompt.
condition_latents (list, facultatif) :
Latents VAE normalisés par condition de forme [1, C, F, H, W].
condition_strengths (list, facultatif) :
Forces de conditionnement par condition.
condition_indices (list, facultatif) :
Indice de trame latente par condition auquel la condition est appliquée.
condition_pixel_frames (list, facultatif) :
Nombre de trames pixel rognées par condition, utilisé pour limiter les coordonnées des trames clés uniques.
reference_latents (Tensor, facultatif) :
Jetons de référence empilés de forme [1, total_reference_tokens, C], ou None si aucune condition de référence
n'a été fournie (LTX2AutoReferenceEncoderStep est ignoré).
reference_coords (Tensor, facultatif) :
Coordonnées RoPE pour les jetons de référence.
reference_token_counts (list, facultatif) :
Nombre de jetons par référence, dans l'ordre de reference_conditions.
latents (Tensor) :
Latents bruités pré-générés pour la génération d'image.
noise_scale (float, facultatif) :
Niveau de bruit initial pour les jetons non conditionnés. None (par défaut) est résolu à sigmas[0] si des sigmas personnalisés sont fournis, sinon 1.0.
sigmas (list, facultatif) :
Sigmas personnalisés pour le processus de débruitage.
reference_cross_mask (Tensor, facultatif) :
Forces d'attention bruité<->référence par jeton de référence de forme [1, num_ref_tokens].
num_inference_steps (int) :
Le nombre d'étapes de débruitage.
timesteps (Tensor) :
Pas de temps pour le processus de débruitage.
audio_latents (Tensor) :
Latents audio pré-encodés facultatifs ; un bruit aléatoire est utilisé s'ils ne sont pas fournis.
*denoiser_input_fields (None,facultatif) :
entrées conditionnelles du modèle pour le débruiteur : par exemple prompt_embeds, negative_prompt_embeds, etc.
use_cross_timestep (bool,facultatif, par défaut True) :
Indique s'il faut conditionner le transformeur sur un pas de temps croisé séparé par jeton (LTX-2.3+).
attention_kwargs (dict,facultatif) :
Kwargs supplémentaires pour les processeurs d'attention.
image_latents (Tensor,facultatif) :
Latents d'image de référence encodés par VAE utilisés pour le conditionnement image-vers-vidéo.
output_type (str,facultatif*, par défaut pil) :
Format de sortie : ‘pil’, ‘np’, ‘pt’.
Sorties :
vidéos (list) :
Les vidéos générées.
audio (Tensor) :
La forme d'onde audio générée.