Diffusers documentation
LTX-2
LTX-2
LTX-2 adalah model fondasi berbasis DiT yang dirancang untuk menghasilkan video dan audio yang tersinkronisasi dalam satu model. Model ini mengintegrasikan blok-blok pembangun inti dari generasi video modern, dengan bobot terbuka dan fokus pada eksekusi lokal yang praktis.
Anda dapat menemukan semua checkpoint asli LTX-Video di bawah organisasi Lightricks.
Kodebase asli untuk LTX-2 dapat ditemukan di sini.
Generasi Dua Tahap
Nilai default __call__ bersama untuk LTX2Pipeline / LTX2ImageToVideoPipeline sesuai dengan referensi LTX-2.5 (num_inference_steps=30; num_frames bersifat opsional jika ada duration_head, jika tidak, nilainya kembali ke 121). Contoh di bawah ini juga menggunakan nilai default tersebut untuk LTX-2.0/2.3.
Pipeline yang direkomendasikan untuk mencapai kualitas produksi, pipeline ini terdiri dari dua tahap:
- Tahap 1: Menghasilkan video pada resolusi target menggunakan pengambilan sampel difusi dengan panduan bebas pengklasifikasi (CFG). Tahap ini menghasilkan urutan video ber-noise rendah yang koheren dan menghormati kondisioning teks/gambar.
- Tahap 2: Upsample output Tahap 1 sebesar 2 dan haluskan detail menggunakan model LoRA yang telah didistilasi untuk meningkatkan fidelitas dan kualitas visual. Tahap 2 dapat menerapkan CFG yang lebih ringan untuk mempertahankan struktur dari Tahap 1 sambil meningkatkan tekstur dan ketajaman.
Contoh penggunaan pipeline dua tahap text-to-video
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",
)Generasi checkpoint terdistil
Pipeline generasi dua tahap tercepat menggunakan checkpoint yang telah didistilasi.
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",
)Kondisi Pipeline Generasi
Anda dapat menggunakan LTX2ConditionPipeline untuk menentukan kondisi gambar dan/atau video pada indeks laten yang sembarang. Sebagai contoh, kita dapat menentukan kondisi bingkai pertama dan bingkai terakhir untuk melakukan generasi 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",
)Anda dapat menggunakan kondisi gambar dan video:
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",
)Karena kondisioning dilakukan melalui frame laten, 8 frame ruang data yang sesuai dengan frame laten yang ditentukan untuk kondisi gambar cenderung statis.
Panduan Multimodal
Pipeline LTX-2.X mendukung panduan multimodal. Ini terdiri dari tiga istilah, semuanya menggunakan aturan pembaruan bergaya CFG:
- Classifier-Free Guidance (CFG): CFG standar di mana output yang terganggu (“lebih lemah”) dihasilkan menggunakan prompt negatif.
- Spatio-Temporal Guidance (STG): STG menjauh dari output yang terganggu akibat pemotongan operasi self-attention dan menggantinya dengan nilai perhatian. Idenya adalah hal ini menghasilkan video yang lebih tajam dan konsistensi spasi-temporal yang lebih baik.
- Panduan Isolasi Modalitas: beralih dari output yang terganggu yang dibuat dengan menonaktifkan cross attention lintas modalitas (audio-ke-video dan video-ke-audio). Panduan ini lebih spesifik untuk model LTX-2.X, dengan gagasan bahwa hal ini menghasilkan konsistensi yang lebih baik antara audio dan video yang dihasilkan.
Parameter ini dikendalikan oleh argumen guidance_scale, stg_scale, dan modality_scale dan dapat diatur secara terpisah untuk video dan audio. Selain itu, untuk STG, indeks blok transformer di mana self-attention dilewati perlu ditentukan melalui argumen spatio_temporal_guidance_blocks. Pipeline LTX-2.X juga mendukung guidance rescaling untuk membantu mengurangi over-exposure, yang dapat menjadi masalah ketika skala guidance diatur ke nilai tinggi.
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",
)Peningkatan Prompt
Model LTX-2.X sensitif terhadap gaya prompting. Lihat panduan prompting resmi untuk rekomendasi cara menulis prompt yang baik. Penggunaan prompt enhancement, di mana prompt yang diberikan ditingkatkan menggunakan text encoder dari pipeline (secara default model Gemma 3) dengan system prompt, juga dapat meningkatkan kualitas sampel. Komponen pipeline opsional processor harus ada untuk menggunakan prompt enhancement. Aktifkan dengan enable_prompt_enhancement=True dan system_prompt (opt-in, sesuai dengan pipeline referensi 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 menggunakan ulang kelas LTX2Pipeline/LTX2VideoTransformer3DModel/AutoencoderKLLTX2Video/dst. yang sama dengan LTX-2.3 — tidak ada kelas pipeline terpisah untuknya. Perbedaan yang terlihat oleh pengguna adalah text encoder: LTX-2.5 dipasangkan dengan checkpoint Gemma 4 (gemma4_unified) alih-alih Gemma 3. Ini dimuat secara otomatis saat Anda memanggil from_pretrained pada checkpoint LTX-2.5 yang telah dikonversi (melalui kelas Auto* dari transformers), sehingga tidak diperlukan setup tambahan pada saat inferensi — cukup arahkan from_pretrained ke repo LTX-2.5 alih-alih repo LTX-2.3.
Lightricks/LTX-2.5-Diffusers menyediakan kedua transformer: DiT distilled di transformer/, yang merupakan target dari model_index.json, dan DiT full/SFT di transformer_full/, yang harus dimuat secara eksplisit (lihat Full / SFT transformer). Folder scheduler/ di repo dikonfigurasi untuk checkpoint distilled (use_dynamic_shifting=False, shift_terminal=None) sehingga jadwal sigma-nya digunakan persis seperti yang diberikan. Semua yang dibutuhkan untuk two-stage generation juga disertakan di sana: subfolder latent_upsampler/ dan LoRA distilled tahap 2, ltx-2.5-22b-distilled-lora-450-bf16.safetensors, di root repo.
Inferensi yang telah di-distil dikendalikan oleh jadwal sigma yang eksplisit, bukan jumlah langkah, dan berjalan tanpa panduan (guidance_scale=1.0, sehingga negative_prompt tidak digunakan). Mengalihkan num_inference_steps sebagai gantinya akan memberikan model jadwal linear generik dan secara diam-diam mengurangi kualitas:
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",
)Generasi dua tahap untuk LTX-2.5
LTX-2.5 mendukung kedua varian dua tahap, dan DISTILLED_SIGMA_VALUES / STAGE_2_DISTILLED_SIGMA_VALUES adalah jadwal referensinya:
- Checkpoint terdistil, kedua tahap — resep referensi untuk
transformer/bawaan, dan yang ditampilkan di bawah. Tidak ada LoRA tahap 2 yang terlibat, karena transformer sudah terdistil; ini adalah Generasi checkpoint terdistil dengan bobot LTX-2.5. - Tahap 1 Full/SFT + tahap 2 LoRA terdistilasi — Generasi dua tahap seperti yang dijelaskan di bagian atas halaman ini, menggunakan
transformer_full/dan LoRA yang disertakan. Lihat di bawah untuk perubahan yang terjadi.
Stage 1 berjalan pada setengah resolusi target, upsampler menggandakannya, dan stage 2 menyempurnakan pada resolusi penuh — video dan audio, keduanya di-reseed dari latents stage 1 pada noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0]. Tinggi dan lebar harus habis dibagi 64, karena stage 1 membagi dua setiap sumbu dan tetap harus mendarat pada grid spasial 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",
)Ketika panjang berasal dari duration head alih-alih num_frames yang eksplisit, biarkan stage 1 yang memutuskan dan pulihkan panjang yang terealisasi dari latents-nya ([B, C, F, H, W]) sebelum stage 2 dijalankan, bukan memprediksinya untuk kedua kalinya:
num_frames = (video_latent.shape[2] - 1) * pipe.vae_temporal_compression_ratio + 1Tahap 2 dengan LoRA yang telah didistilasi
Untuk menjalankan Two-stages Generation sebagai gantinya — full/SFT DiT untuk tahap 1, distilled LoRA untuk tahap 2 — bangun pipeline seperti pada Full / SFT transformer dan hasilkan latents tahap 1 dengan tumpukan panduan tersebut. Dua hal yang berbeda dari LTX-2.0/2.3. LoRA berada di repo diffusers itu sendiri, bukan berdampingan dengan bobot asli, dan pembalikan scheduler berlawanan arah: LTX-2.5 menyertakan konfigurasi scheduler distilled, sehingga tahap 1 adalah yang mengaktifkan dynamic shifting, dan tahap 2 mematikannya kembali.
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
)Langkah upsample dan pemanggilan stage 2 itu sendiri tidak berubah dari resep distilled di atas: sigmas=STAGE_2_DISTILLED_SIGMA_VALUES yang sama, noise_scale yang sama, dan guidance_scale=1.0, karena stage 2 menjalankan model distilled dalam kondisi apa pun.
Dekoding konvolusional dan difusi
LTX-2.5 menyediakan dua dekoder video di atas ruang laten yang sama, sehingga laten dapat dipertukarkan di antara keduanya:
vae/— VAE konvolusional (AutoencoderKLLTX2Video). Ini adalah komponen yang digunakan pipeline untuk melakukan dekoding, sehingga setiap cuplikan di atas sudah memakainya, dan ini adalah satu-satunya dari dua komponen tersebut yang mendukung tiling (pipe.vae.enable_tiling()), yang biasanya memungkinkan resolusi tinggi untuk muat.diffusion_decoder/— LTX2VideoDiffusionDecoderModel. Ini adalah model difusi yang berdiri sendiri, bukan komponen pipeline, sehingga tidak dilewatkan sebagaivae: jalankan pipeline denganoutput_type="latent"dan serahkan latents ke LTX2VideoDiffusionDecodePipeline.
Encoding selalu melewati vae/, sehingga conditioning gambar dan video tidak terpengaruh oleh pilihan tersebut.
Dua hal berubah saat Anda melakukan dekoding dengan diffusion decoder. output_type="latent" juga melewati vocoder, sehingga audio dikembalikan sebagai latents dan harus diselesaikan secara manual, dan prosesor NATTEN secara efektif diperlukan pada resolusi video:
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",
)Untuk menggabungkan ini dengan generasi dua tahap, minta tahap 2 untuk output_type="latent" dan dekode hasilnya.
decoder.enable_tiling() adalah yang menjaga decode resolusi tinggi tetap dalam memori, dengan cara yang sama seperti pipe.vae.enable_tiling() untuk VAE konvolusional. Bagian decode yang dominan dalam memori — tahap upsampling terakhir dan tahap difusi — kemudian dijalankan pada tile yang tumpang tindih dan digabungkan kembali, sehingga memori puncak dibatasi oleh ukuran tile, bukan ukuran video. Tiling hanya aktif ketika latent melebihi satu tile, dan ukuran tile serta overlap dapat disesuaikan melalui argumen tile_sample_min_* / tile_sample_stride_* (nilai default sesuai dengan implementasi referensi). Karena tahap difusi melakukan denoising pada setiap tile secara terpisah, decode bertile tidak mereproduksi hasil tanpa tile secara persis.
Pada kartu tunggal, juga disarankan untuk memindahkan pipeline ke tempat lain sebelum decoding (pipe.to("cpu") dan torch.cuda.empty_cache(), setelah menangkap pipe.scheduler dan output_sampling_rate dari vocoder), karena decoder membutuhkan ruang cadangan tersendiri. Lihat LTX2VideoDiffusionDecoderModel untuk backend perhatian, detail tiling, dan perilaku decoder lainnya.
Transformer penuh / SFT
transformer_full/ tidak dirujuk oleh model_index.json, sehingga muat secara eksplisit. Ia juga memerlukan scheduler yang berbeda dan stack guidance yang nyata: scheduler/ bawaan dikonfigurasi untuk checkpoint terdistil, dan nilai default guidance-nya adalah generik era LTX-2.0 yang membuat run SFT LTX-2.5 terlihat kurang ter-guide tanpa memicu peringatan apa pun. Rekomendasi Multimodal Guidance berlaku di sini tanpa perubahan, termasuk STG pada blok 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,
)Letakkan sigmas di sini — DiT lengkap mengambil jadwalnya dari scheduler.
Peningkatan Prompt untuk LTX-2.5
Penggunaan prompt enhancement sangat direkomendasikan untuk LTX-2.5; berikan enable_prompt_enhancement=True untuk mengaktifkannya (sama seperti pipeline referensi Lightricks). Berbeda dengan LTX-2.0/2.3, di mana checkpoint text encoder yang sama juga berfungsi sebagai enhancer (lihat Prompt Enhancement di atas), text encoder yang telah di-fine-tune untuk LTX-2.5 tidak dilatih untuk enhancement. Sebagai gantinya, enhancement menggunakan checkpoint google/gemma-4-E2B-it yang terpisah dan siap pakai. Muat checkpoint tersebut ke komponen opsional prompt_enhancer/processor dari pipeline, lalu aktifkan enhancement — pipeline secara default menggunakan LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT dan resep Gemma 4 (do_sample=False, no_repeat_ngram_size=5, max_new_tokens=600). Berikan system_prompt= secara eksplisit untuk menimpa:
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",
)Hal yang sama berlaku untuk image-to-video dengan LTX2ImageToVideoPipeline: atur pipe.prompt_enhancer/pipe.processor dengan cara yang sama dan teruskan enable_prompt_enhancement=True (menggunakan LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, dengan conditioning pada gambar referensi dan teks prompt) — sekali lagi, tidak perlu system_prompt= kecuali Anda ingin menimpanya.
Durasi otomatis untuk LTX-2.5
Checkpoint LTX-2.5 menyertakan duration_head kecil yang memprediksi berapa lama shot yang dijelaskan seharusnya berlangsung, dari output text-connector yang sama yang menjadi kondisi bagi transformer. Ketika pipeline yang dimuat memilikinya, num_frames diprediksi secara otomatis secara default — abaikan parameter ini dan model akan memilih panjangnya:
video, audio = pipe(prompt=prompt, output_type="np", return_dict=False)Untuk mengatur panjangnya sendiri, berikan num_frames secara eksplisit. Bilangan bulat selalu menang atas kepala:
video, audio = pipe(prompt=prompt, num_frames=121, output_type="np", return_dict=False)Pipelines yang dimuat dari checkpoint LTX-2.0 atau LTX-2.3 tidak memiliki duration head dan tetap mempertahankan default sebelumnya yaitu 121 frame, sehingga hal ini tidak mengubah apa pun bagi mereka.
Lewati min_seconds / max_seconds untuk membatasi prediksi. Prediksi mentah di-clamp ke dalam rentang, lalu dikonversi ke frame:
video, audio = pipe(
prompt=prompt,
min_seconds=2.0,
max_seconds=10.0,
frame_rate=frame_rate,
output_type="np",
return_dict=False,
)Jumlah frame yang diprediksi akan disesuaikan ke grid temporal kausal VAE (8k + 1), sehingga durasi yang terwujud terkuantisasi — sekitar 0,33 detik per langkah pada 24 fps — dan bergeser sesuai frame_rate, karena head memprediksi detik, bukan frame. min_seconds harus lebih kecil secara ketat dari max_seconds. Batas-batas ini diabaikan ketika num_frames diatur secara eksplisit.
Batas yang lebih sempit dari satu langkah grid mungkin tidak dapat dipenuhi secara persis: pada 24 fps, [1.0s, 1.02s] dikonversi menjadi [24, 24] frame, dan 24 bukan 8k + 1. Titik grid terdekat digunakan dan peringatan dicatat, sehingga panjang yang dikembalikan dapat jatuh tepat di luar batas yang sangat ketat tersebut.
Untuk memeriksa prediksi tanpa menghasilkan video, panggil head secara langsung. Semua yang dibutuhkan bersifat publik:
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")Mengonversi checkpoint 2.5 akan mengambil head secara otomatis dengan --full_pipeline, atau secara terpisah dengan --duration_head. Checkpoint yang lebih lama dari 2.5 tidak memiliki bobot semacam itu, dan proses konversi akan melewati komponen tersebut alih-alih gagal.
Kecepatan gerak untuk LTX-2.5
LTX-2 menempatkan setiap token video pada sumbu waktu dalam satuan detik, yang secara default diturunkan dari frame_rate, yaitu laju pemutaran. motion_speed (default 1.0) memisahkan keduanya: sumbu waktu dikondisikan pada frame_rate / motion_speed, sedangkan panjang audio, duration head, dan video yang dikembalikan tetap mengikuti frame_rate. Dengan frame_rate=24.0 dan motion_speed=0.2, model diberi tahu bahwa aksi tersebut direkam pada 120 fps dan hasilnya diputar pada 24 fps, yang menghasilkan efek slow motion 5x.
Model dasar dilatih pada sekitar 24/25/30/60 fps, sehingga kecepatan yang jauh dari 1.0 hanya masuk akal jika menggunakan adapter yang dilatih khusus untuknya, seperti Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control (bergerbang: terima lisensinya di Hub terlebih dahulu). Tanpa motion_speed, LoRA tersebut dimuat sebagai LoRA biasa dan tidak memberikan kontrol gerakan apa pun. Kartu model menyarankan kecepatan 1.0, 0.5, 0.2, 0.1, 0.05, dan 0.025, dengan kekuatan LoRA 1.0. Jangan sertakan kata-kata kecepatan (“slow motion”, “high fps”) dalam prompt, dan gunakan kembali caption yang sama di berbagai kecepatan, karena hanya motion_speed yang menggerakkan efek tersebut.
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",
)Kedua klip berdurasi 121 frame (sekitar 5 detik pada 24 fps) dan hanya kecepatan gerak yang berubah. Pada generasi dua tahap, berikan motion_speed yang sama ke kedua tahap. Tahap 2 melakukan denoising ulang pada video, dan akan membatalkan efek slow motion jika dijalankan pada sumbu waktu nyata. Driver referensi melakukan hal yang sama dengan membungkus objek tahap yang digunakan bersama oleh kedua pass.
motion_speed juga merupakan input dari blok modular LTX-2 / LTX-2.5, dan diteruskan ke pipeline modular dengan cara yang sama.
LTX-2.5 Modular
LTX-2.5 juga tersedia sebagai pipeline modular. Blockset default menggunakan diffusion decoder dan memprediksi durasi video ketika num_frames diabaikan. Ia menerapkan guidance secara terpisah untuk video dan audio melalui komponen guider dan audio_guider. Lihat LTX2Guidance untuk parameter guidance yang tersedia. Secara default, pipeline modular akan mengunduh prompt enhancer dan processor dari repo google/gemma-4-E2B-it. Berikut adalah contoh modular 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",
)Pipeline modular akan secara otomatis beralih alur kerja berdasarkan input yang diberikan. Misalnya, jika image diberikan, alur kerja I2V akan digunakan:
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",
)Anda dapat melihat workflow yang didukung dalam dokumentasi untuk setiap blockset (misalnya LTX2AutoBlocks, LTX25AutoBlocks).
Diffusion Fidelity Rendering (DFR) untuk LTX-2.5
LTX2DFRPipeline menukar waktu eksekusi dengan tingkat detail. Setiap __call__ adalah satu langkah denoise pada height × width: pipeline ini menghasilkan video beserta slot keyframe tambahan berupa frame satu piksel, atau melakukan denoise ulang pada latents yang diberikan dengan benih dari slot tersebut. Pemanggil menyusun tahapan dengan cara yang sama seperti pipeline dua tahap LTX lainnya — pipeline ini, LTX2LatentUpsamplePipeline, pipeline ini lagi, lalu LTX2DFRTemporalRefinePipeline untuk setiap putaran temporal.
Slot membutuhkan satu frame laten penuh dari token untuk membeli satu frame piksel, yang melonggarkan kompresi temporal efektif pada posisi tersebut — sehingga video di sekitarnya dikondisikan pada frame yang benar-benar baru, bukan yang diinterpolasi. Posisi slot berasal dari grid segmen yang selaras dengan batas temporal VAE (24 atau 32 frame piksel, mana pun yang menghasilkan padding paling sedikit untuk permintaan). Kanvas dipad hingga menjadi bilangan bulat segmen secara internal; output_type="latent" mengembalikan grid yang sudah dipad tersebut sehingga slot pada area padding tidak dibuang. Potong dengan trim_canvas sebelum dekode VAE.
Ini memerlukan transformer yang konfigurasinya mengatur use_keyframes_abs_pos_embedding, yang menandai latens frame satu piksel dengan embedding yang dipelajari. Checkpoint LTX-2.5 menyediakannya; pipeline akan melempar error untuk versi yang lebih lama daripada menghabiskan anggaran token untuk token yang tidak dapat diinterpretasikan.
Anggarkan token tambahan: setiap slot menambah satu frame laten, sehingga tahap 2 menjalankan urutan yang lebih panjang daripada jalur dua tahap yang setara dengan distilasi — +31% pada 1024x1536 / 121 frame (24576 -> 32256 token, 5 slot pada grid segmen 24-frame). Memori aktivasi puncak berskala dengan itu, sehingga resolusi yang baru saja muat dengan resep distilasi biasa mungkin memerlukan enable_sequential_cpu_offload, vae.enable_tiling(), atau kanvas yang lebih kecil di bawah DFR.
Komposisi menggunakan return_dict=True untuk keyframes dan keyframe_positions (return_dict=False mengembalikan empat bidang yang sama sebagai tuple).
Resep lengkap di bawah ini adalah yang sebaiknya dijadikan titik awal: image-to-video 1088×1920, satu putaran temporal refine x2, dan IC-LoRA spatial detailing x2 pada stage 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 dan width adalah lalu lintas ini, bukan output akhir. Tahap 1 berjalan pada setengah kanvas 1080p (544×960); tahap 2 pada 1088×1920. Masing-masing harus dapat dibagi dengan rasio kompresi spasial VAE (32 pada LTX-2.5 untuk satu lalu lintas; 64 ketika tahap 1 adalah setengah dari 1080p). Inilah mengapa 1080p adalah 1920×1088 dan 4K adalah 3840×2176. Setiap lalu lintas menjalankan jadwal distilasi tetap (sigmas), sehingga tidak ada num_inference_steps; jadwal distilasi dilatih tanpa panduan, sehingga tidak ada negative_prompt atau guidance_scale juga. Audio yang disertakan adalah milik tahap 1 — lalu lintas berikutnya masih menjalankan stream audio agar cabang video memiliki perhatian lintas-modal; gelombang itu sendiri tidak disempurnakan setelah tahap 1.
Detailing spasial. Muat IC-LoRA detailing spasial 2x di bawah adapter bernama setelah tahap 1 dan aktifkan hanya untuk tahap 2 (set_adapters(["detailing"], adapter_weights=[0.5])). Tahap 2 kemudian memperhatikan latent setengah resolusi dari tahap 1 sebagai reference_latents. Tahap 1 dan putaran temporal berjalan dengan adapter nonaktif. Jika Anda memuat LoRA sebelum tahap 1, transformer.disable_adapters() mematikannya, dan set_adapters tidak mengaktifkannya kembali — panggil transformer.enable_adapters() sebelum tahap 2, atau muat bobot setelah tahap 1 seperti dalam resep. reference_downscale_factor (default 2) menskalakan koordinat spasial token referensi ke ruang koordinat target.
Penyempurnaan temporal. LTX2DFRTemporalRefinePipeline adalah satu putaran: upsample temporal, tile pada sambungan keyframe, ancestral-denoise dengan LTXEulerAncestralRFScheduler (eta=0.5), jahit dengan membuang lead-in dari tile yang lebih akhir, dan gabungkan carry-keyframe bag. Konstruksi scheduler tersebut secara mandiri — putaran akan ditolak jika menggunakan scheduler lain, karena langkah deterministik akan berjalan hingga selesai dan hanya mengembalikan kanvas yang lebih lembut. Panggil pipeline sekali per putaran; lakukan loop untuk 2x / 4x, dengan meneruskan round_index. Setelah satu putaran, keyframe_positions tidak dapat diturunkan ulang dari num_frames asli dan harus diteruskan. Setiap tile diberikan slice dari audio stage-1 yang dibekukan yang mencakup jendela pemutaran miliknya sendiri. source_seconds adalah durasi stage-1 dan tetap tetap di seluruh putaran, sehingga putaran berikutnya harus meneruskannya secara eksplisit alih-alih mengambil nilai default.
Kondisi fps adalah 60 setiap kali pemutaran di atas 30, terlepas dari muxing: waktu RoPE adalah pixel_frame / fps, sehingga basis waktu 120 fps akan memperkecil rentang temporal setiap token menjadi setengahnya dibandingkan distribusi yang dilatih, dan 48 fps akan memperluasnya. Keduanya berbohong bahwa mereka adalah 60 dan memperlakukan frame yang didekode pada laju pemutaran.
Tahap spasial ketiga. Susunlah; tidak ada pipeline keempat. Upsample secara spasial hanya video, bangun ulang keyframe carry dalam RGB (decode → Lanczos ×2 → encode melalui rebuild_epilogue_keyframes(); jangan pernah upsample keyframe epilog secara laten), kemudian:
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()Kedua sumbu tersebut dijahit dengan cara yang berbeda. Tidak ada sisi dari batas spasial yang memegang jawaban yang diketahui, sehingga tumpang tindih tersebut dicampur dengan bobot trapesium. Ubin temporal dipotong pada jahitan keyframe dari putaran refine terakhir.
Decoding dengan diffusion decoder. Untuk fidelitas detail maksimal, tetap gunakan output_type="latent" dan serahkan latents (yang sudah dinormalisasi, mungkin sudah trim_canvas) ke 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
kelas 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 )
Parameter
- transformer (LTXVideoTransformer3DModel) — Arsitektur Transformer bersyarat untuk mendenoise latens video yang telah dikodekan.
- scheduler (FlowMatchEulerDiscreteScheduler) —
Scheduler yang digunakan bersama
transformeruntuk menghilangkan noise pada latens gambar yang telah dikodekan. - vae (AutoencoderKLLTXVideo) — Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten.
- text_encoder (
T5EncoderModel) — T5, khususnya varian google/t5-v1_1-xxl. - tokenizer (
CLIPTokenizer) — Tokenizer dari kelas CLIPTokenizer. - tokenizer (
T5TokenizerFast) — Tokenizer kedua dari kelas T5TokenizerFast. - connectors (
LTX2TextConnectors) — Tumpukan konektor teks yang digunakan untuk menyesuaikan hidden states encoder teks untuk cabang video dan audio.
Pipeline untuk generasi teks-ke-video.
Referensi: 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 = 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 = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Parameter
- prompt (
strataulist[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskanprompt_embedssebagai gantinya. - negative_prompt (
strataulist[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk memandu generasi gambar. Jika tidak didefinisikan, Anda harus meneruskannegative_prompt_embedssebagai gantinya. Diabaikan ketika tidak menggunakan guidance (guidance_scale < 1). - height (
int, opsional, default512) — Tinggi gambar yang dihasilkan dalam piksel. Nilai ini secara default diatur ke 480 untuk hasil terbaik. - width (
int, opsional, defaultnya768) — Lebar gambar yang dihasilkan dalam piksel. Nilai ini secara default diatur ke 848 untuk hasil terbaik. - num_frames (
int, opsional) — Jumlah bingkai video yang akan dihasilkan. Jika tidak diberikan, nilai defaultnya adalah durasi yang diprediksi secara otomatis ketika pipeline ini memiliki komponenduration_head(checkpoint LTX-2.5 dan yang lebih baru), dan121jika tidak. Lewatkan bilangan bulat untuk menetapkan panjang secara eksplisit. Jumlah yang diprediksi secara otomatis akan disesuaikan ke grid temporal kausal VAE, sehingga durasi yang terwujud akan terkuantisasi (sekitar 0,33 detik pada 24 fps). - min_seconds (
float, opsional, default1.0) — Batas bawah durasi yang diprediksi secara otomatis ketikanum_framesdiabaikan danduration_headada. Diabaikan ketikanum_framesdiatur secara eksplisit. - max_seconds (
float, opsional, default20.0) — Batas atas durasi yang diprediksi secara otomatis ketikanum_framesdiabaikan danduration_headada. Diabaikan ketikanum_framesdiatur secara eksplisit. Harus lebih besar secara ketat darimin_seconds. - frame_rate (
float, opsional, default24.0) — Jumlah frame per detik (FPS) dari video yang dihasilkan. - motion_speed (
float, opsional, default1.0) — Kecepatan gerakan relatif terhadap waktu nyata. Embedding posisi dikondisikan padaframe_rate / motion_speed, sehingga nilai di bawah 1 memperlambat gerakan, misalnya0.2untuk slow motion 5x pada Slow-Motion-Control LoRA.frame_ratetetap menjadi kecepatan pemutaran: durasi audio dan jumlah frame yang diprediksi mengikutinya. - num_inference_steps (
int, opsional, default 30) — Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat. - sigmas (
List[float], opsional) — Sigmas kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumensigmasdi metodeset_timestepsmereka. Jika tidak didefinisikan, perilaku default saatnum_inference_stepsditeruskan akan digunakan. - timesteps (
list[int], opsional) — Timesteps kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumentimestepsdi metodeset_timestepsmereka. Jika tidak didefinisikan, perilaku default saatnum_inference_stepsdilewatkan akan digunakan. Harus dalam urutan menurun. - guidance_scale (
float, optional, defaults to4.0) — Guidance scale as defined in Classifier-Free Diffusion Guidance.guidance_scaleis defined aswof equation 2. of Imagen Paper. Guidance scale is enabled by settingguidance_scale > 1. Higher guidance scale encourages to generate images that are closely linked to the textprompt, usually at the expense of lower image quality. Used for the video modality (there is a separate valueaudio_guidance_scalefor the audio modality). - stg_scale (
float, opsional, default0.0) — Skala panduan video untuk Spatio-Temporal Guidance (STG), yang diusulkan dalam Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. STG menggunakan estimasi serupa CFG di mana sampel dijauhkan dari sampel lemah dari versi terganggu dari model denoising. Mengaktifkan STG akan menghasilkan satu langkah forward model denoising tambahan; nilai default0.0berarti STG dinonaktifkan. - modality_scale (
float, opsional, default1.0) — Skala panduan video untuk panduan isolasi modalitas LTX-2.X, di mana sampel dipindahkan menjauh dari sampel yang lebih lemah yang dihasilkan oleh model denoising dengan cross-attention lintas-modalitas (audio-ke-video dan video-ke-audio) dinonaktifkan menggunakan estimasi serupa CFG. Mengaktifkan panduan modalitas akan menghasilkan satu langkah forward model denoising tambahan; nilai default1.0berarti panduan modalitas dinonaktifkan. - guidance_rescale (
float, opsional, default 0.0) — Faktor rescale guidance yang diusulkan oleh Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaledidefinisikan sebagaiφdalam persamaan 16. dari Common Diffusion Noise Schedules and Sample Steps are Flawed. Faktor rescale guidance harus memperbaiki overexposure saat menggunakan zero terminal SNR. Digunakan untuk modalitas video. - audio_guidance_scale (
float, opsional defaultnyaNone) — Skala panduan audio untuk CFG terhadap prompt negatif. Aturan pembaruan CFG sama untuk video dan audio, tetapi keduanya dapat menggunakan nilai yang berbeda untuk skala panduan. Para penulis LTX-2.X menyarankan bahwaaudio_guidance_scaleharus lebih tinggi relatif terhadapguidance_scalevideo (misalnya untuk LTX-2.3 mereka menyarankan 3.0 untuk video dan 7.0 untuk audio). JikaNone, defaultnya adalah nilai videoguidance_scale. - audio_stg_scale (
float, opsional, defaultNone) — Skala panduan audio untuk STG. Seperti pada CFG, aturan pembaruan STG pada dasarnya sama untuk video dan audio. Untuk LTX-2.3, nilai 1.0 disarankan untuk video dan audio. JikaNone, default ke nilai videostg_scale. - audio_modality_scale (
float, opsional, defaultNone) — Skala panduan audio untuk panduan isolasi modalitas LTX-2.X. Seperti pada CFG, aturan panduan modalitas pada dasarnya sama untuk video dan audio. Untuk LTX-2.3, nilai 3,0 disarankan untuk video dan audio. JikaNone, default ke nilai videomodality_scale. - audio_guidance_rescale (
float, opsional, defaultnyaNone) — Faktor rescale panduan terpisah untuk modalitas audio. JikaNone, defaultnya adalah nilai videoguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], opsional, defaultNone) — Indeks blok transformer berbasis nol tempat STG diterapkan. Harus disediakan jika STG digunakan (stg_scaleatauaudio_stg_scalelebih besar dari0). Nilai[29]direkomendasikan untuk LTX-2.0 dan[28]direkomendasikan untuk LTX-2.3. - noise_scale (
float, opsional, default0.0) — Faktor interpolasi antara noise acak dan latents yang telah dinoised pada setiap timestep. Menerapkan noise padalatentsdanaudio_latentssebelum melanjutkan proses denoising. - num_videos_per_prompt (
int, opsional, default 1) — Jumlah video yang akan dihasilkan per prompt. - generator (
torch.Generatorataulist[torch.Generator], opsional) — Satu atau daftar generator torch untuk membuat proses generasi menjadi deterministik. - latents (
torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi video. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakangeneratoracak yang diberikan. - audio_latents (
torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi audio. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakangeneratoracak yang diberikan. - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen inputprompt. - prompt_attention_mask (
torch.Tensor, opsional) — Mask attention yang telah dibuat sebelumnya untuk embedding teks. - negative_prompt_embeds (
torch.FloatTensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Untuk PixArt-Sigma, prompt negatif ini harus berupa "". Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen inputnegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, opsional) — Attention mask yang telah dibuat sebelumnya untuk embedding teks negatif. - decode_timestep (
float, defaultnya0.0) — Timestep di mana video yang dihasilkan didekode. - decode_noise_scale (
float, defaultnyaNone) — Faktor interpolasi antara noise acak dan latents yang telah dinoise pada timestep decode. - use_cross_timestep (
boolopsional, defaultTrue) — Apakah akan menggunakan sigma dari modality silang (audio adalah modality silang dari video, dan sebaliknya) saat menghitung parameter modulasi cross attention.Trueadalah perilaku LTX-2.3/2.5;Falseadalah perilaku legacy LTX-2.0. - system_prompt (
str, opsional, defaultNone) — Prompt sistem opsional untuk digunakan dalam peningkatan prompt. Prompt sistem akan digunakan oleh pengenhancer prompt (model generasi kondisional Gemma — komponenprompt_enhancerkhusus jika dikonfigurasi, jika tidak,text_encoderutama) untuk menghasilkan prompt yang ditingkatkan daripromptasli untuk mengondisikan generasi. Jika tidak diberikan danprompt_enhancerkhusus dikonfigurasi (LTX-2.5), defaultnya adalahLTX2_5_T2V_DEFAULT_SYSTEM_PROMPT(daridiffusers.pipelines.ltx2.utils) — lihatenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opsional, defaultFalse) — Apakah akan menjalankan prompt enhancement. Opt-in, sesuai dengan pipeline referensi Lightricks. KetikaTruedansystem_promptdiabaikan, LTX-2.5 menggunakanLTX2_5_T2V_DEFAULT_SYSTEM_PROMPTjikaprompt_enhancerkhusus telah dikonfigurasi; LTX-2.0/2.3 memerlukansystem_prompteksplisit. - prompt_max_new_tokens (
int, opsional, defaultNone) — Jumlah maksimum token baru yang akan dihasilkan saat melakukan peningkatan prompt. Jika tidak diberikan, menggunakan 600 untukprompt_enhancerGemma 4 khusus (LTX-2.5) atau 512 untuk fallbacktext_encoderGemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], opsional, defaultNone) — Argumen kata kunci untuk panggilan.generatedari prompt enhancer. Jika tidak diberikan, selalu sesuai dengan model yang melakukan enhancement:do_sample=False, no_repeat_ngram_size=5(greedy) saat menggunakanprompt_enhancerkhusus (LTX-2.5), ataudo_sample=True, temperature=0.7untuk fallbacktext_encoder(LTX-2.0/2.3). Lihat https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate untuk detail lebih lanjut. - prompt_enhancement_seed (
int, opsional, default10) — Seed acak untuk operasi acak apa pun selama peningkatan prompt. - output_type (
str, opsional, defaultnya"pil") — Format output dari generate image. Pilih antara PIL:PIL.Image.Imageataunp.array. - return_dict (
bool, opsional, defaultTrue) — Apakah akan mengembalikan~pipelines.ltx.LTX2PipelineOutputalih-alih tuple biasa. - attention_kwargs (
dict, opsional) — Kamus kwargs yang jika ditentukan akan diteruskan keAttentionProcessorseperti yang didefinisikan di bawahself.processordalam diffusers.models.attention_processor. - callback_on_step_end (
Callable, opsional) — Fungsi yang dipanggil di akhir setiap langkah denoising selama inferensi. Fungsi ini dipanggil dengan argumen berikut:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsakan berisi daftar semua tensor sesuai yang ditentukan olehcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, opsional, defaultnya["latents"]) — Daftar input tensor untuk fungsicallback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumencallback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut._callback_tensor_inputsdari kelas pipeline Anda. - max_sequence_length (
int, opsional, defaultnya1024) — Panjang maksimum urutan yang digunakan denganprompt.
Mengembalikan
~pipelines.ltx.LTX2PipelineOutput atau tuple
Jika return_dict adalah True, maka ~pipelines.ltx.LTX2PipelineOutput yang dikembalikan, selain itu sebuah tuple yang dikembalikan di mana elemen pertama adalah daftar berisi gambar yang dihasilkan.
Fungsi yang dipanggil saat memanggil pipeline untuk generasi.
Contoh:
>>> 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 )
Parameter
- prompt (
strataulist[str], opsional) — prompt yang akan dienkod - negative_prompt (
strataulist[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskannegative_prompt_embedssebagai gantinya. Diabaikan jika tidak menggunakan guidance (yaitu, diabaikan jikaguidance_scalekurang dari1). - do_classifier_free_guidance (
bool, opsional, defaultTrue) — Apakah akan menggunakan classifier free guidance atau tidak. - num_videos_per_prompt (
int, opsional, default 1) — Jumlah video yang harus dihasilkan per prompt. perangkat torch untuk menempatkan embedding yang dihasilkan - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen inputprompt. - negative_prompt_embeds (
torch.Tensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen inputnegative_prompt. - device — (
torch.device, opsional): perangkat torch - dtype — (
torch.dtype, opsional): torch dtype
Mengkodekan prompt menjadi hidden states dari text encoder.
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 )
Meningkatkan prompt yang diberikan dengan menghasilkan prompt baru menggunakan prompt enhancer (model conditional-generation Gemma) dari prompt tersebut dan system prompt. Ketika image diberikan, enhancer juga dikondisikan pada frame referensi tersebut (peningkatan gaya I2V / keyframe). Menggunakan komponen prompt_enhancer khusus jika ada yang dikonfigurasi (misalnya LTX-2.5, yang text encoder-nya tidak dilatih untuk peningkatan), jika tidak, kembali ke text_encoder utama (LTX-2.0/2.3, yang juga berfungsi sebagai enhancer mereka sendiri).
Template pesan, kwargs decoding, pembersihan respons, dan persiapan sisi panjang gambar sesuai dengan ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ImageToVideoPipeline
kelas 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 untuk generasi gambar-ke-video.
Referensi: 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 = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Parameter
- image (
PipelineImageInput) — Gambar input untuk mengondisikan generasi. Harus berupa gambar, daftar gambar, atautorch.Tensor. - prompt (
strataulist[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskanprompt_embedssebagai gantinya. - negative_prompt (
strataulist[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk memandu generasi gambar. Jika tidak didefinisikan, Anda harus meneruskannegative_prompt_embedssebagai gantinya. Diabaikan ketika tidak menggunakan guidance (guidance_scale < 1). - height (
int, opsional, default512) — Tinggi gambar yang dihasilkan dalam piksel. Nilai ini secara default diatur ke 480 untuk hasil terbaik. - width (
int, opsional, defaultnya768) — Lebar gambar yang dihasilkan dalam piksel. Nilai ini secara default diatur ke 848 untuk hasil terbaik. - num_frames (
int, opsional) — Jumlah bingkai video yang akan dihasilkan. Jika tidak diberikan, nilai defaultnya adalah durasi yang diprediksi secara otomatis ketika pipeline ini memiliki komponenduration_head(checkpoint LTX-2.5 dan yang lebih baru), dan121jika tidak. Lewatkan bilangan bulat untuk menetapkan panjang secara eksplisit. Jumlah yang diprediksi secara otomatis akan disesuaikan ke grid temporal kausal VAE, sehingga durasi yang terwujud akan terkuantisasi (sekitar 0,33 detik pada 24 fps). - min_seconds (
float, opsional, default1.0) — Batas bawah durasi yang diprediksi secara otomatis ketikanum_framesdiabaikan danduration_headada. Diabaikan ketikanum_framesdiatur secara eksplisit. - max_seconds (
float, opsional, default20.0) — Batas atas durasi yang diprediksi secara otomatis ketikanum_framesdiabaikan danduration_headada. Diabaikan ketikanum_framesdiatur secara eksplisit. Harus lebih besar secara ketat darimin_seconds. - frame_rate (
float, opsional, default24.0) — Jumlah frame per detik (FPS) dari video yang dihasilkan. - motion_speed (
float, opsional, default1.0) — Kecepatan gerakan relatif terhadap waktu nyata. Embedding posisi dikondisikan padaframe_rate / motion_speed, sehingga nilai di bawah 1 memperlambat gerakan, misalnya0.2untuk slow motion 5x pada Slow-Motion-Control LoRA.frame_ratetetap menjadi kecepatan pemutaran: durasi audio dan jumlah frame yang diprediksi mengikutinya. - num_inference_steps (
int, opsional, default 30) — Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat. - sigmas (
List[float], opsional) — Sigmas kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumensigmasdi metodeset_timestepsmereka. Jika tidak didefinisikan, perilaku default saatnum_inference_stepsditeruskan akan digunakan. - timesteps (
List[int], opsional) — Timesteps kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumentimestepsdi metodeset_timestepsmereka. Jika tidak didefinisikan, perilaku default saatnum_inference_stepsdilewatkan akan digunakan. Harus dalam urutan menurun. - guidance_scale (
float, optional, defaults to4.0) — Guidance scale as defined in Classifier-Free Diffusion Guidance.guidance_scaleis defined aswof equation 2. of Imagen Paper. Guidance scale is enabled by settingguidance_scale > 1. Higher guidance scale encourages to generate images that are closely linked to the textprompt, usually at the expense of lower image quality. Used for the video modality (there is a separate valueaudio_guidance_scalefor the audio modality). - stg_scale (
float, opsional, default0.0) — Skala panduan video untuk Spatio-Temporal Guidance (STG), yang diusulkan dalam Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. STG menggunakan estimasi serupa CFG di mana sampel dijauhkan dari sampel lemah dari versi terganggu dari model denoising. Mengaktifkan STG akan menghasilkan satu langkah forward model denoising tambahan; nilai default0.0berarti STG dinonaktifkan. - modality_scale (
float, opsional, default1.0) — Skala panduan video untuk panduan isolasi modalitas LTX-2.X, di mana sampel dipindahkan menjauh dari sampel yang lebih lemah yang dihasilkan oleh model denoising dengan cross-attention lintas-modalitas (audio-ke-video dan video-ke-audio) dinonaktifkan menggunakan estimasi serupa CFG. Mengaktifkan panduan modalitas akan menghasilkan satu langkah forward model denoising tambahan; nilai default1.0berarti panduan modalitas dinonaktifkan. - guidance_rescale (
float, opsional, default 0.0) — Faktor rescale guidance yang diusulkan oleh Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaledidefinisikan sebagaiφdalam persamaan 16. dari Common Diffusion Noise Schedules and Sample Steps are Flawed. Faktor rescale guidance harus memperbaiki overexposure saat menggunakan zero terminal SNR. Digunakan untuk modalitas video. - audio_guidance_scale (
float, opsional defaultnyaNone) — Skala panduan audio untuk CFG terhadap prompt negatif. Aturan pembaruan CFG sama untuk video dan audio, tetapi keduanya dapat menggunakan nilai yang berbeda untuk skala panduan. Para penulis LTX-2.X menyarankan bahwaaudio_guidance_scaleharus lebih tinggi relatif terhadapguidance_scalevideo (misalnya untuk LTX-2.3 mereka menyarankan 3.0 untuk video dan 7.0 untuk audio). JikaNone, defaultnya adalah nilai videoguidance_scale. - audio_stg_scale (
float, opsional, defaultNone) — Skala panduan audio untuk STG. Seperti pada CFG, aturan pembaruan STG pada dasarnya sama untuk video dan audio. Untuk LTX-2.3, nilai 1.0 disarankan untuk video dan audio. JikaNone, default ke nilai videostg_scale. - audio_modality_scale (
float, opsional, defaultNone) — Skala panduan audio untuk panduan isolasi modalitas LTX-2.X. Seperti pada CFG, aturan panduan modalitas pada dasarnya sama untuk video dan audio. Untuk LTX-2.3, nilai 3,0 disarankan untuk video dan audio. JikaNone, default ke nilai videomodality_scale. - audio_guidance_rescale (
float, opsional, defaultnyaNone) — Faktor rescale panduan terpisah untuk modalitas audio. JikaNone, defaultnya adalah nilai videoguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], opsional, defaultNone) — Indeks blok transformer berbasis nol tempat STG diterapkan. Harus disediakan jika STG digunakan (stg_scaleatauaudio_stg_scalelebih besar dari0). Nilai[29]direkomendasikan untuk LTX-2.0 dan[28]direkomendasikan untuk LTX-2.3. - noise_scale (
float, opsional, default0.0) — Faktor interpolasi antara noise acak dan latents yang telah dinoised pada setiap timestep. Menerapkan noise padalatentsdanaudio_latentssebelum melanjutkan proses denoising. - num_videos_per_prompt (
int, opsional, default 1) — Jumlah video yang akan dihasilkan per prompt. - generator (
torch.Generatorataulist[torch.Generator], opsional) — Satu atau daftar generator torch untuk membuat proses generasi menjadi deterministik. - latents (
torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi video. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakangeneratoracak yang diberikan. - audio_latents (
torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi audio. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakangeneratoracak yang diberikan. - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen inputprompt. - prompt_attention_mask (
torch.Tensor, opsional) — Mask attention yang telah dibuat sebelumnya untuk embedding teks. - negative_prompt_embeds (
torch.FloatTensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Untuk PixArt-Sigma, prompt negatif ini harus berupa "". Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen inputnegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, opsional) — Attention mask yang telah dibuat sebelumnya untuk embedding teks negatif. - decode_timestep (
float, defaultnya0.0) — Timestep di mana video yang dihasilkan didekode. - decode_noise_scale (
float, defaultnyaNone) — Faktor interpolasi antara noise acak dan latents yang telah dinoise pada timestep decode. - use_cross_timestep (
boolopsional, defaultTrue) — Apakah akan menggunakan sigma dari modality silang (audio adalah modality silang dari video, dan sebaliknya) saat menghitung parameter modulasi cross attention.Trueadalah perilaku LTX-2.3/2.5;Falseadalah perilaku legacy LTX-2.0. - system_prompt (
str, opsional, defaultNone) — Prompt sistem opsional untuk digunakan dalam peningkatan prompt. Prompt sistem akan digunakan oleh peningkat prompt (model generasi kondisional Gemma — komponenprompt_enhancerkhusus jika terkonfigurasi, jika tidak,text_encoderutama) untuk menghasilkan prompt yang ditingkatkan daripromptasli danimagepertama untuk mengondisikan generasi. Jika tidak diberikan danprompt_enhancerkhusus terkonfigurasi (LTX-2.5), defaultnya adalahLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT(daridiffusers.pipelines.ltx2.utils) — lihatenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opsional, defaultFalse) — Apakah akan menjalankan prompt enhancement. Opt-in, sesuai dengan pipeline referensi Lightricks. KetikaTruedansystem_promptdiabaikan, LTX-2.5 menggunakanLTX2_5_I2V_DEFAULT_SYSTEM_PROMPTjikaprompt_enhancerkhusus telah dikonfigurasi; LTX-2.0/2.3 memerlukansystem_prompteksplisit. - prompt_max_new_tokens (
int, opsional, defaultNone) — Jumlah maksimum token baru yang akan dihasilkan saat melakukan peningkatan prompt. Jika tidak diberikan, menggunakan 600 untukprompt_enhancerGemma 4 khusus (LTX-2.5) atau 512 untuk fallbacktext_encoderGemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], opsional, defaultNone) — Argumen kata kunci untuk panggilan.generatedari prompt enhancer. Jika tidak diberikan, selalu sesuai dengan model yang melakukan enhancement:do_sample=False, no_repeat_ngram_size=3(greedy) saat menggunakanprompt_enhancerkhusus (LTX-2.5), ataudo_sample=True, temperature=0.7untuk fallbacktext_encoder(LTX-2.0/2.3). Lihat https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate untuk detail lebih lanjut. - prompt_enhancement_seed (
int, opsional, default10) — Seed acak untuk operasi acak apa pun selama peningkatan prompt. - image_crf (
int, opsional, defaultNone) — CRF H.264 yang digunakan untuk mengompres ulangimagekondisioning sebelum encode VAE, agar sesuai dengan kompresi yang digunakan saat model dilatih.Noneberarti “gunakan default model” (33 hingga LTX-2.3, 18 untuk LTX-2.5). Lewati0untuk melewati kompresi ulang. MemerlukanPIL.Image.Imagesaat kompresi ulang dijalankan. - output_type (
str, opsional, defaultnya"pil") — Format output dari generate image. Pilih antara PIL:PIL.Image.Imageataunp.array. - return_dict (
bool, opsional, defaultTrue) — Apakah akan mengembalikan~pipelines.ltx.LTX2PipelineOutputalih-alih tuple biasa. - attention_kwargs (
dict, opsional) — Kamus kwargs yang jika ditentukan akan diteruskan keAttentionProcessorseperti yang didefinisikan di bawahself.processordalam diffusers.models.attention_processor. - callback_on_step_end (
Callable, opsional) — Fungsi yang dipanggil di akhir setiap langkah denoising selama inferensi. Fungsi ini dipanggil dengan argumen berikut:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsakan berisi daftar semua tensor sesuai yang ditentukan olehcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, opsional) — Daftar input tensor untuk fungsicallback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumencallback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut._callback_tensor_inputsdari kelas pipeline Anda. - max_sequence_length (
int, opsional, defaultnya1024) — Panjang maksimum urutan yang digunakan denganprompt.
Mengembalikan
~pipelines.ltx.LTX2PipelineOutput atau tuple
Jika return_dict adalah True, maka ~pipelines.ltx.LTX2PipelineOutput yang dikembalikan, selain itu sebuah tuple yang dikembalikan di mana elemen pertama adalah daftar berisi gambar yang dihasilkan.
Fungsi yang dipanggil saat memanggil pipeline untuk generasi.
Contoh:
>>> 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 )
Parameter
- prompt (
strataulist[str], opsional) — prompt yang akan dienkod - negative_prompt (
strataulist[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskannegative_prompt_embedssebagai gantinya. Diabaikan jika tidak menggunakan guidance (yaitu, diabaikan jikaguidance_scalekurang dari1). - do_classifier_free_guidance (
bool, opsional, defaultTrue) — Apakah akan menggunakan classifier free guidance atau tidak. - num_videos_per_prompt (
int, opsional, default 1) — Jumlah video yang harus dihasilkan per prompt. perangkat torch untuk menempatkan embedding yang dihasilkan - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen inputprompt. - negative_prompt_embeds (
torch.Tensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen inputnegative_prompt. - device — (
torch.device, opsional): perangkat torch - dtype — (
torch.dtype, opsional): torch dtype
Mengkodekan prompt menjadi hidden states dari text encoder.
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 )
Meningkatkan prompt yang diberikan dengan menghasilkan prompt baru menggunakan prompt enhancer (model conditional-generation Gemma) dari prompt tersebut dan system prompt. Ketika image diberikan, enhancer juga dikondisikan pada frame referensi tersebut (peningkatan gaya I2V / keyframe). Menggunakan komponen prompt_enhancer khusus jika ada yang dikonfigurasi (misalnya LTX-2.5, yang text encoder-nya tidak dilatih untuk peningkatan), jika tidak, kembali ke text_encoder utama (LTX-2.0/2.3, yang juga berfungsi sebagai enhancer mereka sendiri).
Template pesan, kwargs decoding, pembersihan respons, dan persiapan sisi panjang gambar sesuai dengan ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ConditionPipeline
kelas 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 untuk generasi video yang memungkinkan kondisi gambar disisipkan di bagian mana pun dari video.
Referensi: 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 = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Parameter
- conditions (
List[LTXVideoCondition], *optional*) — Daftar item kondisioning frame untuk generasi video. - prompt (
stratauList[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskanprompt_embedssebagai gantinya. - negative_prompt (
stratauList[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk memandu generasi gambar. Jika tidak didefinisikan, Anda harus meneruskannegative_prompt_embedssebagai gantinya. Diabaikan ketika tidak menggunakan guidance (guidance_scale < 1). - height (
int, opsional, default512) — Tinggi gambar yang dihasilkan dalam piksel. Nilai ini secara default diatur ke 480 untuk hasil terbaik. - width (
int, opsional, defaultnya768) — Lebar gambar yang dihasilkan dalam piksel. Nilai ini secara default diatur ke 848 untuk hasil terbaik. - num_frames (
int, opsional) — Jumlah bingkai video yang akan dihasilkan. Jika tidak diberikan, nilai defaultnya adalah durasi yang diprediksi secara otomatis ketika pipeline ini memiliki komponenduration_head(checkpoint LTX-2.5 dan yang lebih baru), dan121jika tidak. Lewatkan bilangan bulat untuk menetapkan panjang secara eksplisit. Jumlah yang diprediksi secara otomatis akan disesuaikan ke grid temporal kausal VAE, sehingga durasi yang terwujud akan terkuantisasi (sekitar 0,33 detik pada 24 fps). - min_seconds (
float, opsional, default1.0) — Batas bawah durasi yang diprediksi secara otomatis ketikanum_framesdiabaikan danduration_headada. Diabaikan ketikanum_framesdiatur secara eksplisit. - max_seconds (
float, opsional, default20.0) — Batas atas durasi yang diprediksi secara otomatis ketikanum_framesdiabaikan danduration_headada. Diabaikan ketikanum_framesdiatur secara eksplisit. Harus lebih besar secara ketat darimin_seconds. - frame_rate (
float, opsional, default24.0) — Jumlah frame per detik (FPS) dari video yang dihasilkan. - motion_speed (
float, opsional, default1.0) — Kecepatan gerakan relatif terhadap waktu nyata. Embedding posisi dikondisikan padaframe_rate / motion_speed, sehingga nilai di bawah 1 memperlambat gerakan, misalnya0.2untuk slow motion 5x pada Slow-Motion-Control LoRA.frame_ratetetap menjadi kecepatan pemutaran: durasi audio dan jumlah frame yang diprediksi mengikutinya. - num_inference_steps (
int, opsional, default 30) — Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat. - sigmas (
List[float], opsional) — Sigmas kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumensigmasdi metodeset_timestepsmereka. Jika tidak didefinisikan, perilaku default saatnum_inference_stepsditeruskan akan digunakan. - timesteps (
List[int], opsional) — Timesteps kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumentimestepsdi metodeset_timestepsmereka. Jika tidak didefinisikan, perilaku default saatnum_inference_stepsdilewatkan akan digunakan. Harus dalam urutan menurun. - guidance_scale (
float, optional, defaults to4.0) — Guidance scale as defined in Classifier-Free Diffusion Guidance.guidance_scaleis defined aswof equation 2. of Imagen Paper. Guidance scale is enabled by settingguidance_scale > 1. Higher guidance scale encourages to generate images that are closely linked to the textprompt, usually at the expense of lower image quality. Used for the video modality (there is a separate valueaudio_guidance_scalefor the audio modality). - stg_scale (
float, opsional, default0.0) — Skala panduan video untuk Spatio-Temporal Guidance (STG), yang diusulkan dalam Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. STG menggunakan estimasi serupa CFG di mana sampel dijauhkan dari sampel lemah dari versi terganggu dari model denoising. Mengaktifkan STG akan menghasilkan satu langkah forward model denoising tambahan; nilai default0.0berarti STG dinonaktifkan. - modality_scale (
float, opsional, default1.0) — Skala panduan video untuk panduan isolasi modalitas LTX-2.X, di mana sampel dipindahkan menjauh dari sampel yang lebih lemah yang dihasilkan oleh model denoising dengan cross-attention lintas-modalitas (audio-ke-video dan video-ke-audio) dinonaktifkan menggunakan estimasi serupa CFG. Mengaktifkan panduan modalitas akan menghasilkan satu langkah forward model denoising tambahan; nilai default1.0berarti panduan modalitas dinonaktifkan. - guidance_rescale (
float, opsional, default 0.0) — Faktor rescale guidance yang diusulkan oleh Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaledidefinisikan sebagaiφdalam persamaan 16. dari Common Diffusion Noise Schedules and Sample Steps are Flawed. Faktor rescale guidance harus memperbaiki overexposure saat menggunakan zero terminal SNR. Digunakan untuk modalitas video. - audio_guidance_scale (
float, opsional defaultnyaNone) — Skala panduan audio untuk CFG terhadap prompt negatif. Aturan pembaruan CFG sama untuk video dan audio, tetapi keduanya dapat menggunakan nilai yang berbeda untuk skala panduan. Para penulis LTX-2.X menyarankan bahwaaudio_guidance_scaleharus lebih tinggi relatif terhadapguidance_scalevideo (misalnya untuk LTX-2.3 mereka menyarankan 3.0 untuk video dan 7.0 untuk audio). JikaNone, defaultnya adalah nilai videoguidance_scale. - audio_stg_scale (
float, opsional, defaultNone) — Skala panduan audio untuk STG. Seperti pada CFG, aturan pembaruan STG pada dasarnya sama untuk video dan audio. Untuk LTX-2.3, nilai 1.0 disarankan untuk video dan audio. JikaNone, default ke nilai videostg_scale. - audio_modality_scale (
float, opsional, defaultNone) — Skala panduan audio untuk panduan isolasi modalitas LTX-2.X. Seperti pada CFG, aturan panduan modalitas pada dasarnya sama untuk video dan audio. Untuk LTX-2.3, nilai 3,0 disarankan untuk video dan audio. JikaNone, default ke nilai videomodality_scale. - audio_guidance_rescale (
float, opsional, defaultnyaNone) — Faktor rescale panduan terpisah untuk modalitas audio. JikaNone, defaultnya adalah nilai videoguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], opsional, defaultNone) — Indeks blok transformer berbasis nol tempat STG diterapkan. Harus disediakan jika STG digunakan (stg_scaleatauaudio_stg_scalelebih besar dari0). Nilai[29]direkomendasikan untuk LTX-2.0 dan[28]direkomendasikan untuk LTX-2.3. - noise_scale (
float, opsional, defaultNone) — Faktor interpolasi antara noise acak dan latents yang telah didenoise pada setiap timestep. Menerapkan noise padalatentsdanaudio_latentssebelum melanjutkan proses denoising. Jika tidak diatur, nilai ini akan disimpulkan dari jadwal sigma. - num_videos_per_prompt (
int, opsional, default 1) — Jumlah video yang akan dihasilkan per prompt. - generator (
torch.GeneratoratauList[torch.Generator], opsional) — Satu atau daftar generator torch untuk membuat proses generasi menjadi deterministik. - latents (
torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi video. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakangeneratoracak yang diberikan. - audio_latents (
torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi audio. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakangeneratoracak yang diberikan. - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen inputprompt. - prompt_attention_mask (
torch.Tensor, opsional) — Mask attention yang telah dibuat sebelumnya untuk embedding teks. - negative_prompt_embeds (
torch.FloatTensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Untuk PixArt-Sigma, prompt negatif ini harus berupa "". Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen inputnegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, opsional) — Attention mask yang telah dibuat sebelumnya untuk embedding teks negatif. - decode_timestep (
float, defaultnya0.0) — Timestep di mana video yang dihasilkan didekode. - decode_noise_scale (
float, defaultnyaNone) — Faktor interpolasi antara noise acak dan latents yang telah dinoise pada timestep decode. - use_cross_timestep (
boolopsional, defaultTrue) — Apakah akan menggunakan sigma dari modality silang (audio adalah modality silang dari video, dan sebaliknya) saat menghitung parameter modulasi cross attention.Trueadalah perilaku LTX-2.3/2.5;Falseadalah perilaku legacy LTX-2.0. - system_prompt (
str, opsional, defaultNone) — Prompt sistem opsional untuk digunakan dalam peningkatan prompt. Prompt sistem akan digunakan oleh peningkat prompt (model generasi kondisional Gemma — komponenprompt_enhancerkhusus jika terkonfigurasi, jika tidak,text_encoderutama) untuk menghasilkan prompt yang ditingkatkan daripromptasli (dan gambar kondisional jika tersedia) untuk mengondisikan generasi. Jika tidak disediakan danprompt_enhancerkhusus terkonfigurasi (LTX-2.5), defaultnya adalahLTX2_5_I2V_DEFAULT_SYSTEM_PROMPTjika gambar kondisional tersedia, jika tidakLTX2_5_T2V_DEFAULT_SYSTEM_PROMPT— lihatenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opsional, defaultFalse) — Apakah akan menjalankan prompt enhancement. Opt-in, sesuai dengan pipeline referensi Lightricks. KetikaTruedansystem_promptdiabaikan, LTX-2.5 memilihLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT/LTX2_5_T2V_DEFAULT_SYSTEM_PROMPTberdasarkan ketersediaan gambar conditioning. - prompt_max_new_tokens (
int, opsional, defaultNone) — Jumlah maksimum token baru yang akan dihasilkan saat melakukan peningkatan prompt. Jika tidak diberikan, menggunakan 600 untukprompt_enhancerGemma 4 khusus (LTX-2.5) atau 512 untuk fallbacktext_encoderGemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], opsional, defaultNone) — Argumen kata kunci untuk panggilan.generatedari prompt enhancer. Jika tidak diberikan, selalu sesuai dengan model yang melakukan enhancement:do_sample=False, no_repeat_ngram_size=5(greedy) saat menggunakanprompt_enhancerkhusus (LTX-2.5), ataudo_sample=True, temperature=0.7untuk fallbacktext_encoder(LTX-2.0/2.3). Lihat https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate untuk detail lebih lanjut. - prompt_enhancement_seed (
int, opsional, default10) — Seed acak untuk operasi acak apa pun selama peningkatan prompt. - output_type (
str, opsional, defaultnya"pil") — Format output dari generate image. Pilih antara PIL:PIL.Image.Imageataunp.array. - return_dict (
bool, opsional, defaultTrue) — Apakah akan mengembalikan~pipelines.ltx.LTX2PipelineOutputalih-alih tuple biasa. - attention_kwargs (
dict, opsional) — Kamus kwargs yang jika ditentukan akan diteruskan keAttentionProcessorseperti yang didefinisikan di bawahself.processordalam diffusers.models.attention_processor. - callback_on_step_end (
Callable, opsional) — Fungsi yang dipanggil di akhir setiap langkah denoising selama inferensi. Fungsi ini dipanggil dengan argumen berikut:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsakan berisi daftar semua tensor sesuai yang ditentukan olehcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, opsional) — Daftar input tensor untuk fungsicallback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumencallback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut._callback_tensor_inputsdari kelas pipeline Anda. - max_sequence_length (
int, opsional, defaultnya1024) — Panjang maksimum urutan yang digunakan denganprompt.
Mengembalikan
~pipelines.ltx.LTX2PipelineOutput atau tuple
Jika return_dict adalah True, maka ~pipelines.ltx.LTX2PipelineOutput yang dikembalikan, selain itu sebuah tuple yang dikembalikan di mana elemen pertama adalah daftar berisi gambar yang dihasilkan.
Fungsi yang dipanggil saat memanggil pipeline untuk generasi.
Contoh:
>>> 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: listcondition_strengths: listcondition_indices: listlatent_height: intlatent_width: int ) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
Parameter
- latents (
torch.Tensor) — Latents awal yang sudah dikemas (patchified) dengan bentuk [batch_size, patch_seq_len, hidden_dim]. - conditioning_mask (
torch.Tensor) — Mask conditioning awal yang sudah dikemas (patchified) dengan bentuk [batch_size, patch_seq_len, 1] dan nilai dalam [0, 1], di mana 0 berarti output model denoising akan sepenuhnya digunakan dan 1 berarti kondisi akan sepenuhnya digunakan.
Mengembalikan
Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
Mengembalikan 3-tuple tensor di mana:
- Latens video yang dikemas dengan kondisi bingkai pertama yang diterapkan.
- Mask kondisioning terpadat dengan kekuatan bingkai pertama yang diterapkan.
- Latent kondisioning bersih pada posisi bingkai pertama (nol di tempat lain).
Terapkan kondisioning visual bingkai pertama dengan menimpa token pada posisi bingkai pertama.
Hanya kondisi dengan latent_idx == 0 yang diterapkan di sini (sesuai dengan VideoConditionByLatentIndex dalam implementasi referensi). Kondisi pada indeks laten non-nol ditambahkan sebagai token keyframe terpisah melalui prepare_keyframe_extras (sesuai dengan VideoConditionByKeyframeIndex) dan dilewati di sini.
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 )
Parameter
- prompt (
strataulist[str], opsional) — prompt yang akan dienkod - negative_prompt (
strataulist[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskannegative_prompt_embedssebagai gantinya. Diabaikan jika tidak menggunakan guidance (yaitu, diabaikan jikaguidance_scalekurang dari1). - do_classifier_free_guidance (
bool, opsional, defaultTrue) — Apakah akan menggunakan classifier free guidance atau tidak. - num_videos_per_prompt (
int, opsional, default 1) — Jumlah video yang harus dihasilkan per prompt. perangkat torch untuk menempatkan embedding yang dihasilkan - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen inputprompt. - negative_prompt_embeds (
torch.Tensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen inputnegative_prompt. - device — (
torch.device, opsional): perangkat torch - dtype — (
torch.dtype, opsional): torch dtype
Mengkodekan prompt menjadi hidden states dari text encoder.
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 )
Meningkatkan prompt yang diberikan dengan menghasilkan prompt baru menggunakan prompt enhancer (model conditional-generation Gemma) dari prompt tersebut dan system prompt. Ketika image diberikan, enhancer juga dikondisikan pada frame referensi tersebut (peningkatan gaya I2V / keyframe). Menggunakan komponen prompt_enhancer khusus jika ada yang dikonfigurasi (misalnya LTX-2.5, yang text encoder-nya tidak dilatih untuk peningkatan), jika tidak, kembali ke text_encoder utama (LTX-2.0/2.3, yang juga berfungsi sebagai enhancer mereka sendiri).
Template pesan, kwargs decoding, pembersihan respons, dan persiapan sisi panjang gambar sesuai dengan 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 )
Siapkan latens video berisik, terapkan kondisi bingkai.
Kondisi bingkai pertama (latent_idx == 0) diterapkan dengan menimpa token pada posisi bingkai pertama
(semantik VideoConditionByLatentIndex). Kondisi non-bingkai pertama (latent_idx > 0) digabungkan ke
urutan laten utama dengan conditioning_mask = strength per token (semantik VideoConditionByKeyframeIndex) — rumus timestep yang sudah ada dalam loop denoising t * (1 - conditioning_mask) dan blend pasca-pemrosesan
denoised * (1 - conditioning_mask) + clean * conditioning_mask kemudian mengaturnya melintasi langkah-langkah.
Mengembalikan 4-tuple:
latents: latents berisik yang dikemas (token dasar + token keyframe mana pun yang digabungkan ke dimensi sekuens).conditioning_mask: packed conditioning mask dengan nilai dalam[0, 1]—1di posisi frame pertama,strengthdi posisi keyframe,0di tempat lain.clean_latents: nilai kondisi bersih pada posisi yang dikondisikan (nol di tempat lain); bentuknya sama denganlatents.keyframe_coords: koordinat posisi[B, 3, num_keyframe_patches, 2]untuk ditambahkan kevideo_coords, atauNonejika tidak ada kondisi selain frame pertama.
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]]
Parameter
- conditions (
LTX2VideoConditionatauList[LTX2VideoCondition], opsional, defaultNone) — Daftar instance kondisi gambar/video. - height (
int, opsional, default512) — Tinggi yang diinginkan dalam piksel. - width (
int, opsional, default768) — Lebar yang diinginkan dalam piksel. - num_frames (
int, opsional, default121) — Jumlah frame yang diinginkan dalam video yang dihasilkan. - device (
torch.device, opsional, defaultNone) — Perangkat tempat tensor gambar/video yang telah dipreprocess ditempatkan.
Mengembalikan
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Mengembalikan 4-tuple dari daftar dengan panjang len(conditions) sebagai berikut:
- Daftar pertama adalah daftar tensor video yang telah dipreprocess dengan bentuk [batch_size=1, num_channels, num_frames, height, width].
- Daftar kedua adalah daftar kekuatan kondisioning.
- Daftar ketiga adalah daftar indeks ruang laten untuk setiap kondisi.
- Daftar keempat adalah daftar jumlah frame (yang telah dipangkas) dalam ruang piksel per kondisi. Hal ini diperlukan untuk semantik koordinat keyframe (keyframe dengan satu frame piksel memiliki jangkauan temporal yang dijepit).
Memproses prapengolahan gambar/video kondisi menjadi tensor torch.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Potong urutan kondisioning menjadi jumlah frame yang diizinkan.
LTX2DFRPipeline
kelas 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 )
Parameter
- scheduler (FlowMatchEulerDiscreteScheduler) —
Scheduler yang digunakan bersama
transformeruntuk menghilangkan noise pada latens video yang telah dikodekan. - vae (AutoencoderKLLTX2Video) — Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan video ke dan dari representasi laten.
- audio_vae (AutoencoderKLLTX2Audio) — Audio VAE untuk mengkodekan dan mendekodekan spektrogram audio.
- text_encoder (
Gemma3ForConditionalGenerationatauGemma4UnifiedForConditionalGeneration) — Model pengkode teks. - tokenizer (
GemmaTokenizeratauGemmaTokenizerFast) — Tokenizer untuk encoder teks. - connectors (
LTX2TextConnectors) — Tumpukan konektor teks yang digunakan untuk menyesuaikan hidden states encoder teks untuk cabang video dan audio. - transformer (LTX2VideoTransformer3DModel) — Arsitektur Transformer bersyarat untuk mendenoise latens video yang telah dikodekan.
- vocoder (
LTX2VocoderatauLTX2VocoderWithBWE) — Vocoder untuk mengkonversi spektrogram mel menjadi gelombang audio. - processor (
ProcessorMixin, opsional) — Processor yang digunakan untuk penguatan prompt dan chat templating. - prompt_enhancer (
Gemma4ForConditionalGeneration, opsional) — Model peningkatan prompt khusus (LTX-2.5). - duration_head (
LTX2DurationHead, opsional) — Memprediksinum_framesdari prompt embeddings ketikanum_framestidak diberikan.
Pipeline untuk satu pass denoise Diffusion Fidelity Rendering (DFR) dengan LTX-2.5.
A pass menghasilkan video dan slot keyframe berbingkai satu piksel tambahan, atau melakukan re-denoising pada latents yang diberikan yang di-seed dari slot tersebut. Pemanggil menyusun tahapan: pipeline ini pada resolusi setengah, LTX2LatentUpsamplePipeline secara spasial, pipeline ini lagi pada resolusi penuh dengan slot yang di-upsample dan referensi IC-LoRA, kemudian LTX2DFRTemporalRefinePipeline untuk setiap putaran temporal refine. Lihat dokumentasi LTX-2 untuk resep 1080p.
Posisi slot berasal dari grid segmen yang selaras dengan batas temporal VAE (resolve_canvas). Kanvas
diisi hingga menjadi bilangan bulat segmen; output_type="latent" mengembalikan grid yang telah diisi tersebut sehingga slot pada bagian pengisi tidak
dibuang. Potong dengan trim_canvas sebelum dekode VAE.
Memerlukan transformer yang konfigurasinya mengatur use_keyframes_abs_pos_embedding (LTX-2.5 dan yang lebih baru) ketika generate_slots=True.
Referensi: 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 = [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 = ['latents']max_sequence_length: int = 1024 ) → LTX2DFRPipelineOutput or tuple
Parameter
- prompt (
stratauList[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi video. Jika tidak didefinisikan, Anda harus meneruskanprompt_embeds. - conditions (
LTX2VideoConditionatauList[LTX2VideoCondition], opsional) — Kondisi gambar atau video pada tingkat frame.indexadalah indeks latent padanum_framesdari pass ini. - height (
int, opsional, defaultnya704) — Tinggi dalam piksel dari pass ini, bukan output akhir yang dikomposisikan. - width (
int, opsional, defaultnya1216) — Lebar pass ini dalam piksel. - num_frames (
int, opsional) — Jumlah frame piksel pada pass ini, sebelum padding kanvas internal. Jika tidak diberikan, durasi diprediksi dari prompt olehduration_head. Harus memenuhi(num_frames - 1) % 8 == 0. - frame_rate (
float, opsional, default24.0) — fps pemutaran untuk pass ini. Waktu RoPE akan disamakan ke 60 setiap kali nilai ini di atas 30. - min_seconds (
float, opsional, default1.0) — Batas bawah durasi yang diprediksi secara otomatis ketikanum_framesdiabaikan. - max_seconds (
float, opsional, default20.0) — Batas atas durasi yang diprediksi secara otomatis ketikanum_framesdiabaikan. - latents (
torch.Tensor, opsional) — Latens video mentah(batch_size, channels, frames, height, width)untuk di-denoise ulang (tahap 2 / epilog). - audio_latents (
torch.Tensor, opsional) — Latens audio mentah yang belum dikemas dengan bentuk(batch_size, channels, length, mel_bins). Tahap 2 masih menjalankan jalur audio gabungan; gelombang suara yang dikirim dari resep yang disusun adalah milik tahap 1, yang dipertahankan oleh pemanggil. - keyframes_latents (
torch.Tensor, opsional) — Awal slot(batch_size, channels, num_slots, height, width)mentah, digunakan saatgenerate_slots=True. - keyframe_positions (
list[int], opsional) — Indeks bingkai piksel dari slot yang dihasilkan. Bawaan adalahresolve_canvas(num_frames). - reference_latents (
torch.Tensor, opsional) — Video referensi IC-LoRA mentah (biasanya frame dari tahap 1). - reference_downscale_factor (
int, opsional, default2) — Rasio antara pass ini dan resolusi referensi, digunakan untuk menskalakan koordinat token referensi. - guidance_keyframe_latents (
torch.Tensor, opsional) — Keyframe panduan mentah yang di-pin(batch_size, channels, K, height, width)— jalur epilog. Bukan slot yang dihasilkan. - guidance_keyframe_positions (
list[int], opsional) — Indeks bingkai piksel untukguidance_keyframe_latents. - guidance_keyframe_strength (
float, opsional, default1.0) — Kekuatan kondisioning untuk keyframe panduan yang dikunci. - generate_slots (
bool, opsional, defaultTrue) — Menambahkan token keyframe-slot yang dihasilkan. Epilog mengatur ini menjadiFalsedan mengunciguidance_keyframe_latentssebagai gantinya. - sigmas (
list[float], opsional) — Jadwal noise untuk langkah ini, tanpa terminal0.0. - noise_scale (
float, opsional) — Tingkat noise yang menjadi titik awal token tanpa kondisi. Nilai default adalahsigmas[0]. - freeze_audio (
bool, opsional, defaultFalse) — Tahan audio pada sigma 0 (epilog / saat mengikuti waveform stage-1 yang dibekukan). - video_tiles (
list[LTX2DFREpilogueTile], opsional) — Pengepilogan tiling dariepilogue_tiles(), sehingga resolusi yang terlalu besar untuk satu langkah maju masih dapat memproses kanvas tunggal: setiap langkah menjalankan transformer sekali per tile dan mencampur prediksi. Diubah menjadi rencana token terhadap koordinat RoPE milik langkah ini sendiri, itulah mengapa layout yang diteruskan bukan rencananya — koordinat hanya ada setelah prepare_latents() dijalankan. - num_videos_per_prompt (
int, opsional, default 1) — Jumlah video yang akan dihasilkan per prompt. - generator (
torch.Generatorataulist[torch.Generator], opsional) — Generator acak untuk reproduktibilitas. - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang telah dibuat sebelumnya. - prompt_attention_mask (
torch.Tensor, opsional) — Mask attention yang telah dibuat sebelumnya untuk embedding teks. - decode_timestep (
float, defaultnya0.0) — Timestep di mana video yang dihasilkan didekode. - decode_noise_scale (
float, defaultnyaNone) — Skala noise saat decode. - use_cross_timestep (
bool, opsional, defaultTrue) — Apakah akan menggunakan sigma lintas modalitas untuk modulasi cross attention.Trueuntuk LTX-2.3+. - system_prompt (
str, opsional) — Prompt sistem opsional untuk peningkatan prompt. Lihatenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opsional, defaultFalse) — Apakah akan menjalankan prompt enhancement. - prompt_max_new_tokens (
int, opsional) — Jumlah maksimum token baru yang akan dihasilkan saat melakukan peningkatan prompt. - prompt_enhancement_kwargs (
dict[str, Any], opsional) — Argumen kata kunci untuk panggilan.generatedari prompt enhancer. - prompt_enhancement_seed (
int, opsional, default10) — Seed acak untuk operasi acak apa pun selama peningkatan prompt. - output_type (
str, opsional, default"pil") — Format output. Pilih"pil","np","pt"atau"latent". Output latent adalah kanvas yang tidak dipangkas. - return_dict (
bool, opsional, defaultTrue) — Apakah akan mengembalikan LTX2DFRPipelineOutput atau tuple(frames, audio, keyframes, keyframe_positions)biasa. - attention_kwargs (
dict, opsional) — Kwargs tambahan yang diteruskan ke pemroses perhatian. - callback_on_step_end (
Callable, opsional) — Fungsi yang dipanggil di akhir setiap langkah denoising. - callback_on_step_end_tensor_inputs (
List, opsional, defaultnya["latents"]) — Input tensor untuk fungsi callback. - max_sequence_length (
int, opsional, defaultnya1024) — Panjang maksimum urutan untuk prompt teks.
Mengembalikan
LTX2DFRPipelineOutput atau tuple
Jika return_dict adalah True, LTX2DFRPipelineOutput dikembalikan, selain itu sebuah tuple dari (video, audio, keyframes, keyframe_positions) yang dikembalikan.
Fungsi yang dipanggil saat memanggil pipeline untuk generasi.
Satu langkah denoise pada height × width. Susun tahapan di pemanggil: pipeline ini pada resolusi setengah, upsample spasial, pipeline ini lagi dengan latents / keyframes_latents / reference_latents, lalu LTX2DFRTemporalRefinePipeline untuk setiap putaran temporal.
Contoh:
>>> 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: listframe_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 )
Parameter
- sigmas (
list[float]) — Jadwal noise untuk langkah ini, tanpa0.0terminal. - freeze_audio (
bool, opsional, defaultFalse) — Jagaaudio_latentstetap bersih (timestep/sigma 0, tanpa langkah Euler audio) sambil tetap menjalankan cross-attention audio-ke-video. Diabaikan ketikaaudio_latentsadalahNone. - video_tile_plan (
list, opsional) — Rencana token per-tile darivideo_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. Jika diberikan, setiap langkah menjalankan transformer sekali per tile dan mencampur prediksi, sehingga sampler tetap melangkah pada satu kanvas penuh dan tile-tile tersebut sepakat pada tumpang tindih mereka di setiap langkah. - generator (
torch.Generator, opsional) — Diteruskan keLTXEulerAncestralRFScheduler.step(). Ubin temporal meneruskan seed per-ubin sehingga undian ancestral tidak berbagi stream atau mengonsumsi state yang dibaca oleh noising awal ubin berikutnya. Distilled Euler tidak membacanya. - step_offset (
int) — Indeks langkah pertama dari pass ini dalam seluruh jadwal pipeline, digunakan untukcallback_on_step_enddan bilah progres bersama.
Jalankan satu langkah denoising DFR pada sigmas dan kembalikan (latents, audio_latents), keduanya masih dalam bentuk packed.
Jadwal terdistil digunakan tanpa panduan bebas klasifikator, sehingga ini adalah satu panggilan transformer per langkah.
Setiap lintasan menjalankan kedua aliran, karena cabang video membutuhkan perhatian lintas-modal bahkan di tempat audio yang
dihasilkannya dibuang. freeze_audio=True menjaga aliran audio pada sigma 0 (tanpa langkah Euler) sehingga video masih
bisa melakukan perhatian silang ke aliran tersebut — ubin penyempurnaan temporal dan epilog menggunakan ini untuk mengikuti ucapan tahap-1
tanpa setiap ubin melakukan denoising ulang realisasi audio yang berbeda.
Setelah pencampuran kondisioning x0, kecepatan adalah (latents - denoised) / sigma sehingga langkah RF x0 = x - σ v memulihkan denoised yang telah dicampur. Tahap 1 / 2 / epilog mempertahankan FlowMatchEulerDiscreteScheduler dan mengambil langkah Euler tersebut apa adanya. Temporal refine mengganti dengan LTXEulerAncestralRFScheduler (eta=0.5); langkah tersebut melakukan renoise pada setiap token, sehingga pencampuran kondisioning diterapkan kembali setelahnya atau jangkar sambungan strength-0.95 akan terkikis.
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 )
Praproses dan VAE-encode kondisi frame, diposisikan berdasarkan frame piksel.
Mengembalikan (pixel_frame_index, latent, strength, num_pixel_frames) per kondisi, siap untuk condition_latents dari prepare_latents(). Encoding dipisahkan dari penempatan karena
putaran refine temporal menskalakan posisi suatu kondisi dengan 2 ** round dan menyetel ulang basisnya per tile, dan seharusnya tidak
meng-encode ulang still yang sama sekali per tile untuk melakukannya.
Indeks yang dikembalikan berada pada grid piksel num_frames itu sendiri; memindahkannya ke kanvas yang telah diperhalus adalah tugas pemanggil.
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 )
Parameter
- prompt (
strataulist[str], opsional) — prompt yang akan dienkod - num_videos_per_prompt (
int, opsional, default 1) — Jumlah video yang harus dihasilkan per prompt. - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen inputprompt. - prompt_attention_mask (
torch.Tensor, opsional) — Attention mask yang telah dibuat sebelumnya untukprompt_embeds. - device — (
torch.device, opsional): perangkat torch - dtype — (
torch.dtype, opsional): torch dtype
Mengkodekan prompt menjadi hidden states dari text encoder.
DFR menjalankan jadwal sigma yang telah didistilasi, yang dilatih untuk digunakan tanpa classifier-free guidance, sehingga tidak ada cabang negatif di sini.
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 )
Meningkatkan prompt yang diberikan dengan menghasilkan prompt baru menggunakan prompt enhancer (model conditional-generation Gemma) dari prompt tersebut dan system prompt. Ketika image diberikan, enhancer juga dikondisikan pada frame referensi tersebut (peningkatan gaya I2V / keyframe). Menggunakan komponen prompt_enhancer khusus jika ada yang dikonfigurasi (misalnya LTX-2.5, yang text encoder-nya tidak dilatih untuk peningkatan), jika tidak, kembali ke text_encoder utama (LTX-2.0/2.3, yang juga berfungsi sebagai enhancer mereka sendiri).
Template pesan, kwargs decoding, pembersihan respons, dan persiapan sisi panjang gambar sesuai dengan 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]
Parameter
- conditions (
list[LTX2VideoCondition], opsional) — Kondisi gambar/video per frame, diposisikan berdasarkan indeks laten. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], opsional) — Sudah-terenkapsulasi pengganti untukconditions, sebagai(pixel_frame_index, latent, strength, num_pixel_frames). Indeks piksel, bukan indeks latent, karena putaran refine temporal menskalakan posisi suatu condition dengan2 ** rounddan hasilnya umumnya tidak jatuh pada batas latent — hanya token keyframe yang ditambahkan yang dapat berada di sana, dan ia ditempatkan berdasarkan piksel.pixel_frame_index == 0tetap berarti “ganti frame pertama”. - keyframe_latents (
list[tuple[int, torch.Tensor, float]], opsional) — Panduan keyframe yang sudah dikodekan sebagai(pixel_frame_index, latent, strength), di manalatentmemiliki bentuk(batch_size, num_channels_latents, 1, latent_height, latent_width). Digunakan oleh putaran temporal refine untuk mengunci keyframe sambungan yang dibawa dari putaran sebelumnya. - slot_frame_indices (
list[int], opsional) — Posisi bingkai piksel dari slot keyframe yang dihasilkan. - slot_initial_latents (
torch.Tensor, opsional) —(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)konten yang ditulis ke dalam token slot sebelum proses noising. - reference_latents (
torch.Tensor, opsional) —(batch_size, num_channels_latents, F, H, W)Laten referensi IC-LoRA. - reference_downscale_factor (
int, defaultnya1) — Rasio antara resolusi target dan resolusi referensi. - latents (
torch.Tensor, opsional) —(batch_size, num_channels_latents, F, H, W)konten awal untuk token dasar. Latents dari pipeline publik bersifat mentah (tidak dinormalisasi); berikanlatents_normalized=Falsepada batas tersebut. Loop tile yang sudah berada di ruang yang dinormalisasi VAE tetap menggunakan nilai default. - latents_normalized (
bool, defaultnyaTrue) — Apakahlatents,slot_initial_latents,reference_latents, dankeyframe_latentssudah dinormalisasi VAE. Loop tile internal meneruskanTrue; setiap__call__pipeline meneruskanFalse. - noise_scale (
float, defaultnya1.0) — Tingkat noise tempat token tanpa kondisi diinisialisasi, yaitu sigma pertama dari jadwal.
Mengembalikan
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 mengindeks token slot keyframe yang dihasilkan dalam urutan yang dikemas, atau None ketika tidak ada slot yang diminta.
Siapkan latens video berisik yang sudah dikemas untuk satu langkah denoising DFR.
Urutan yang dikemas disusun sebagai [base | keyframes | slots | reference]:
- Token dasar mencakup grid laten target, yang ditanam dari
latentsjika diberikan. - Kondisi frame dengan
index == 0menetapkan target bersih pada posisi frame pertama; sedangkan yang memilikiindex > 0dan setiap entri darikeyframe_latentsditambahkan sebagai token keyframe tambahan dengan mask kondisioning per token yang sama dengan kekuatan mereka. slot_frame_indicesmenambahkan satu set token keyframe yang dihasilkan per posisi, dengan mask conditioning0(sepenuhnya denoised) dan jangkauan temporal RoPE yang tepat satu frame piksel. Slot-slot keyframe inilah yang memberikan frame tambahan pada DFR;slot_initial_latentsmenginisiasi konten mereka.reference_latentsmenambahkan latent setengah resolusi tahap-1 sebagai referensi IC-LoRA yang sepenuhnya bersih, dengan koordinat spasial yang diskalakan olehreference_downscale_factorsehingga memetakan ke ruang koordinat target.
Token kondisioning yang ditambahkan membawa kontennya di clean_latents dan placeholder nol di latents, sedangkan slot keyframe membawa benihnya di latents dan nol di clean_latents — latents yang dikembalikan adalah campuran berisik dari keduanya (lihat langkah noising di akhir metode ini).
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]]
Parameter
- conditions (
LTX2VideoConditionatauList[LTX2VideoCondition], opsional, defaultNone) — Daftar instance kondisi gambar/video. - height (
int, opsional, default512) — Tinggi yang diinginkan dalam piksel. - width (
int, opsional, default768) — Lebar yang diinginkan dalam piksel. - num_frames (
int, opsional, default121) — Jumlah frame yang diinginkan dalam video yang dihasilkan. - device (
torch.device, opsional, defaultNone) — Perangkat tempat tensor gambar/video yang telah dipreprocess ditempatkan.
Mengembalikan
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Mengembalikan 4-tuple dari daftar dengan panjang len(conditions) sebagai berikut:
- Daftar pertama adalah daftar tensor video yang telah dipreprocess dengan bentuk [batch_size=1, num_channels, num_frames, height, width].
- Daftar kedua adalah daftar kekuatan kondisioning.
- Daftar ketiga adalah daftar indeks ruang laten untuk setiap kondisi.
- Daftar keempat adalah daftar jumlah frame (yang telah dipangkas) dalam ruang piksel per kondisi. Hal ini diperlukan untuk semantik koordinat keyframe (keyframe dengan satu frame piksel memiliki jangkauan temporal yang dijepit).
Memproses prapengolahan gambar/video kondisi menjadi tensor torch.
rebuild_epilogue_keyframes
< source >( keyframe_latents: Tensordecode_timestep: floatdecode_noise_scale: floatseed: intdevice: devicedtype: dtype ) → torch.Tensor
Parameter
- keyframe_latents (
torch.Tensor) — Keyframe bawaan mentah(batch_size, C, K, H, W), sebagaimana dikembalikan oleh pass sebelumnya. - seed (
int) — Seed dasar; bidangididekodekan di bawahseed + 4000 + i, sehingga piksel suatu bidang tidak bergantung pada berapa banyak bidang yang didekodekan sebelumnya.
Mengembalikan
torch.Tensor
Latens (batch_size, C, K, 2H, 2W) mentah, siap untuk langsung dikembalikan sebagai
guidance_keyframe_latents.
Enkripsi ulang keyframe carry pada dua kali resolusi mereka melalui RGB.
Frame-frame ini adalah frame yang sudah diselesaikan oleh putaran penyempurnaan, sehingga epilog memberikan frame tersebut alih-alih memintanya untuk menghasilkan frame. Dekoding ke piksel, peregangan x2 dengan Lanczos, dan enkoding ulang mempertahankan frame sambil memposisikannya pada grid keluaran, yang memungkinkan epilog menguncinya sepenuhnya bersih.
Setiap bidang didekode sebagai klip satu bingkainya sendiri. VAE bersifat kausal, sehingga dekode bertumpuk akan memungkinkan bidang tetangga saling tumpang tindih — mereka adalah still independen, bukan sebuah urutan.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Potong urutan kondisioning menjadi jumlah frame yang diizinkan.
LTX2DFRTemporalRefinePipeline
kelas 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 )
Parameter
- scheduler (
LTXEulerAncestralRFScheduler) — Scheduler Ancestral Euler dalam parameterisasi rectified-flow. Konstruksi denganeta=0.5untuk mencocokkan resep temporal DFR. - vae (AutoencoderKLLTX2Video) — Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan video ke dan dari representasi laten.
- audio_vae (AutoencoderKLLTX2Audio) — Audio VAE untuk mengkodekan dan mendekodekan spektrogram audio.
- text_encoder (
Gemma3ForConditionalGenerationatauGemma4UnifiedForConditionalGeneration) — Model pengkode teks. - tokenizer (
GemmaTokenizeratauGemmaTokenizerFast) — Tokenizer untuk encoder teks. - connectors (
LTX2TextConnectors) — Tumpukan konektor teks yang digunakan untuk menyesuaikan hidden states encoder teks untuk cabang video dan audio. - transformer (LTX2VideoTransformer3DModel) — Arsitektur Transformer bersyarat untuk mendenoise latens video yang telah dikodekan.
- vocoder (
LTX2VocoderatauLTX2VocoderWithBWE) — Vocoder untuk mengkonversi spektrogram mel menjadi gelombang audio. - temporal_latent_upsampler (
LTX2LatentUpsamplerModel) — Upsampler laten temporal x2 yang diterapkan di awal putaran.
Satu putaran penyempurnaan DFR temporal: interpolasi kanvas x2 dalam waktu, tiling pada sambungan keyframe, denoising leluhur untuk setiap tile, jahit dengan membuang lead-in dari tile yang lebih akhir, dan gabungkan tas carry-keyframe.
Scheduler-nya adalah LTXEulerAncestralRFScheduler (default eta=0.5). Stage 1 / 2 / epilog spasial tetap menggunakan FlowMatchEulerDiscreteScheduler melalui LTX2DFRPipeline. Panggil pipeline ini sekali per ronde; pemanggil melakukan loop untuk 2x / 4x.
latents / keyframes_latents / audio_latents yang masuk bersifat mentah (tidak dinormalisasi), sesuai dengan LTX2Pipeline. keyframe_positions harus berupa posisi yang dikembalikan oleh pass sebelumnya — posisi ini tidak dapat diturunkan ulang dari num_frames asli setelah satu round dijalankan.
__call__
< source >( prompt: str | list[str] = Nonelatents: Tensor = Nonekeyframes_latents: Tensor = Nonekeyframe_positions: list = 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 = [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 = ['latents']max_sequence_length: int = 1024 ) → LTX2DFRPipelineOutput or tuple
Parameter
- prompt (
stratauList[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi video. Jika tidak didefinisikan, Anda harus meneruskanprompt_embeds. - latents (
torch.Tensor) — Latens video mentah dari kanvas input,(batch_size, channels, frames, height, width). - keyframes_latents (
torch.Tensor) — Keyframe carry mentah(batch_size, channels, K, height, width)dari pass sebelumnya. - keyframe_positions (
list[int]) — Indeks bingkai piksel darikeyframes_latentspada kanvas input. - audio_latents (
torch.Tensor) — Audio tahap-1 yang dibekukan, telah di-unpack dan dinormalisasi. Setiap tile diberikan slice yang mencakup jendela pemutaran-nya; audio yang dikembalikan adalah waveform ini, bukan re-denoise per-tile. - conditions (
LTX2VideoConditionatauList[LTX2VideoCondition], opsional) — Kondisi tingkat frame yang diindeks padacondition_num_frames(permintaan asli). Setiap putaran memperbesar posisi piksel kondisi dengan2 ** round_index. - height (
int, opsional, defaultnya704) — Tinggi piksel dari pass ini (sama dengan video yang masuk). - width (
int, opsional, defaultnya1216) — Lebar piksel dari pass ini. - num_frames (
int, opsional, default121) — Jumlah frame piksel dari kanvas input (belum dipangkas). - frame_rate (
float, opsional, default24.0) — fps pemutaran input. Pembulatan menggandakannya. - source_seconds (
float, opsional) — Durasi audio stage-1 yang dibekukan. Nilainya secara default adalahnum_frames / frame_rate, yang benar untuk putaran pertama; putaran berikutnya harus meneruskan durasi stage-1 asli agar tile tidak bergeser. - condition_num_frames (
int, opsional) —num_framesgenerasi asli yang digunakan untuk mengkodekanconditions. Nilainya secara default adalahnum_frames. Setelah padding atau putaran sebelumnya, berikan permintaan asli agarindex=-1tidak melingkar ke ekor yang di-padding. - round_index (
int, opsional, default1) — Nomor ronde berbasis 1. Ubin menabur kebisingan leluhur sebagaiseed + 1000 * round_index + tile, dan kondisi diskalakan dengan2 ** round_index. - sigmas (
list[float], opsional) — Jadwal terdistil untuk tile ronde ini, tanpa0.0terminal. - noise_scale (
float, opsional) — Tingkat noise yang menjadi titik awal token tanpa kondisi. Nilai default adalahsigmas[0]. - generator (
torch.Generatorataulist[torch.Generator], opsional) — Generator acak untuk reproduktibilitas. Unduhan ancestral menggunakan seed per-tile yang terpisah, yang diturunkan dariinitial_seed()generator ini. - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang telah dibuat sebelumnya. - prompt_attention_mask (
torch.Tensor, opsional) — Mask attention yang telah dibuat sebelumnya untuk embedding teks. - decode_timestep (
float, defaultnya0.0) — Timestep di mana video yang dihasilkan didekode. - decode_noise_scale (
float, defaultnyaNone) — Skala noise saat decode. - use_cross_timestep (
bool, opsional, defaultTrue) — Apakah akan menggunakan sigma lintas modalitas untuk modulasi cross attention.Trueuntuk LTX-2.3+. - output_type (
str, opsional, default"pil") — Format output. Pilih"pil","np","pt"atau"latent". Output latent adalah kanvas yang tidak dipangkas. - return_dict (
bool, opsional, defaultTrue) — Apakah akan mengembalikan LTX2DFRPipelineOutput atau tuple(frames, audio, keyframes, keyframe_positions)biasa. - attention_kwargs (
dict, opsional) — Kwargs tambahan yang diteruskan ke pemroses perhatian. - callback_on_step_end (
Callable, opsional) — Fungsi yang dipanggil di akhir setiap langkah denoising, di seluruh tile. - callback_on_step_end_tensor_inputs (
List, opsional, defaultnya["latents"]) — Input tensor untuk fungsi callback. - max_sequence_length (
int, opsional, defaultnya1024) — Panjang maksimum urutan untuk prompt teks.
Mengembalikan
LTX2DFRPipelineOutput atau tuple
Jika return_dict adalah True, LTX2DFRPipelineOutput dikembalikan, selain itu sebuah tuple dari (video, audio, keyframes, keyframe_positions) yang dikembalikan.
Jalankan satu putaran penyempurnaan temporal.
Contoh:
>>> 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: listframe_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 )
Parameter
- sigmas (
list[float]) — Jadwal noise untuk langkah ini, tanpa0.0terminal. - freeze_audio (
bool, opsional, defaultFalse) — Jagaaudio_latentstetap bersih (timestep/sigma 0, tanpa langkah Euler audio) sambil tetap menjalankan cross-attention audio-ke-video. Diabaikan ketikaaudio_latentsadalahNone. - video_tile_plan (
list, opsional) — Rencana token per-tile darivideo_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. Jika diberikan, setiap langkah menjalankan transformer sekali per tile dan mencampur prediksi, sehingga sampler tetap melangkah pada satu kanvas penuh dan tile-tile tersebut sepakat pada tumpang tindih mereka di setiap langkah. - generator (
torch.Generator, opsional) — Diteruskan keLTXEulerAncestralRFScheduler.step(). Ubin temporal meneruskan seed per-ubin sehingga undian ancestral tidak berbagi stream atau mengonsumsi state yang dibaca oleh noising awal ubin berikutnya. Distilled Euler tidak membacanya. - step_offset (
int) — Indeks langkah pertama dari pass ini dalam seluruh jadwal pipeline, digunakan untukcallback_on_step_enddan bilah progres bersama.
Jalankan satu langkah denoising DFR pada sigmas dan kembalikan (latents, audio_latents), keduanya masih dalam bentuk packed.
Jadwal terdistil digunakan tanpa panduan bebas klasifikator, sehingga ini adalah satu panggilan transformer per langkah.
Setiap lintasan menjalankan kedua aliran, karena cabang video membutuhkan perhatian lintas-modal bahkan di tempat audio yang
dihasilkannya dibuang. freeze_audio=True menjaga aliran audio pada sigma 0 (tanpa langkah Euler) sehingga video masih
bisa melakukan perhatian silang ke aliran tersebut — ubin penyempurnaan temporal dan epilog menggunakan ini untuk mengikuti ucapan tahap-1
tanpa setiap ubin melakukan denoising ulang realisasi audio yang berbeda.
Setelah pencampuran kondisioning x0, kecepatan adalah (latents - denoised) / sigma sehingga langkah RF x0 = x - σ v memulihkan denoised yang telah dicampur. Tahap 1 / 2 / epilog mempertahankan FlowMatchEulerDiscreteScheduler dan mengambil langkah Euler tersebut apa adanya. Temporal refine mengganti dengan LTXEulerAncestralRFScheduler (eta=0.5); langkah tersebut melakukan renoise pada setiap token, sehingga pencampuran kondisioning diterapkan kembali setelahnya atau jangkar sambungan strength-0.95 akan terkikis.
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 )
Praproses dan VAE-encode kondisi frame, diposisikan berdasarkan frame piksel.
Mengembalikan (pixel_frame_index, latent, strength, num_pixel_frames) per kondisi, siap untuk condition_latents dari prepare_latents(). Encoding dipisahkan dari penempatan karena
putaran refine temporal menskalakan posisi suatu kondisi dengan 2 ** round dan menyetel ulang basisnya per tile, dan seharusnya tidak
meng-encode ulang still yang sama sekali per tile untuk melakukannya.
Indeks yang dikembalikan berada pada grid piksel num_frames itu sendiri; memindahkannya ke kanvas yang telah diperhalus adalah tugas pemanggil.
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 )
Parameter
- prompt (
strataulist[str], opsional) — prompt yang akan dienkod - num_videos_per_prompt (
int, opsional, default 1) — Jumlah video yang harus dihasilkan per prompt. - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen inputprompt. - prompt_attention_mask (
torch.Tensor, opsional) — Attention mask yang telah dibuat sebelumnya untukprompt_embeds. - device — (
torch.device, opsional): perangkat torch - dtype — (
torch.dtype, opsional): torch dtype
Mengkodekan prompt menjadi hidden states dari text encoder.
DFR menjalankan jadwal sigma yang telah didistilasi, yang dilatih untuk digunakan tanpa classifier-free guidance, sehingga tidak ada cabang negatif di sini.
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]
Parameter
- conditions (
list[LTX2VideoCondition], opsional) — Kondisi gambar/video per frame, diposisikan berdasarkan indeks laten. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], opsional) — Sudah-terenkapsulasi pengganti untukconditions, sebagai(pixel_frame_index, latent, strength, num_pixel_frames). Indeks piksel, bukan indeks latent, karena putaran refine temporal menskalakan posisi suatu condition dengan2 ** rounddan hasilnya umumnya tidak jatuh pada batas latent — hanya token keyframe yang ditambahkan yang dapat berada di sana, dan ia ditempatkan berdasarkan piksel.pixel_frame_index == 0tetap berarti “ganti frame pertama”. - keyframe_latents (
list[tuple[int, torch.Tensor, float]], opsional) — Panduan keyframe yang sudah dikodekan sebagai(pixel_frame_index, latent, strength), di manalatentmemiliki bentuk(batch_size, num_channels_latents, 1, latent_height, latent_width). Digunakan oleh putaran temporal refine untuk mengunci keyframe sambungan yang dibawa dari putaran sebelumnya. - slot_frame_indices (
list[int], opsional) — Posisi bingkai piksel dari slot keyframe yang dihasilkan. - slot_initial_latents (
torch.Tensor, opsional) —(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)konten yang ditulis ke dalam token slot sebelum proses noising. - reference_latents (
torch.Tensor, opsional) —(batch_size, num_channels_latents, F, H, W)Laten referensi IC-LoRA. - reference_downscale_factor (
int, defaultnya1) — Rasio antara resolusi target dan resolusi referensi. - latents (
torch.Tensor, opsional) —(batch_size, num_channels_latents, F, H, W)konten awal untuk token dasar. Latents dari pipeline publik bersifat mentah (tidak dinormalisasi); berikanlatents_normalized=Falsepada batas tersebut. Loop tile yang sudah berada di ruang yang dinormalisasi VAE tetap menggunakan nilai default. - latents_normalized (
bool, defaultnyaTrue) — Apakahlatents,slot_initial_latents,reference_latents, dankeyframe_latentssudah dinormalisasi VAE. Loop tile internal meneruskanTrue; setiap__call__pipeline meneruskanFalse. - noise_scale (
float, defaultnya1.0) — Tingkat noise tempat token tanpa kondisi diinisialisasi, yaitu sigma pertama dari jadwal.
Mengembalikan
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 mengindeks token slot keyframe yang dihasilkan dalam urutan yang dikemas, atau None ketika tidak ada slot yang diminta.
Siapkan latens video berisik yang sudah dikemas untuk satu langkah denoising DFR.
Urutan yang dikemas disusun sebagai [base | keyframes | slots | reference]:
- Token dasar mencakup grid laten target, yang ditanam dari
latentsjika diberikan. - Kondisi frame dengan
index == 0menetapkan target bersih pada posisi frame pertama; sedangkan yang memilikiindex > 0dan setiap entri darikeyframe_latentsditambahkan sebagai token keyframe tambahan dengan mask kondisioning per token yang sama dengan kekuatan mereka. slot_frame_indicesmenambahkan satu set token keyframe yang dihasilkan per posisi, dengan mask conditioning0(sepenuhnya denoised) dan jangkauan temporal RoPE yang tepat satu frame piksel. Slot-slot keyframe inilah yang memberikan frame tambahan pada DFR;slot_initial_latentsmenginisiasi konten mereka.reference_latentsmenambahkan latent setengah resolusi tahap-1 sebagai referensi IC-LoRA yang sepenuhnya bersih, dengan koordinat spasial yang diskalakan olehreference_downscale_factorsehingga memetakan ke ruang koordinat target.
Token kondisioning yang ditambahkan membawa kontennya di clean_latents dan placeholder nol di latents, sedangkan slot keyframe membawa benihnya di latents dan nol di clean_latents — latents yang dikembalikan adalah campuran berisik dari keduanya (lihat langkah noising di akhir metode ini).
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]]
Parameter
- conditions (
LTX2VideoConditionatauList[LTX2VideoCondition], opsional, defaultNone) — Daftar instance kondisi gambar/video. - height (
int, opsional, default512) — Tinggi yang diinginkan dalam piksel. - width (
int, opsional, default768) — Lebar yang diinginkan dalam piksel. - num_frames (
int, opsional, default121) — Jumlah frame yang diinginkan dalam video yang dihasilkan. - device (
torch.device, opsional, defaultNone) — Perangkat tempat tensor gambar/video yang telah dipreprocess ditempatkan.
Mengembalikan
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Mengembalikan 4-tuple dari daftar dengan panjang len(conditions) sebagai berikut:
- Daftar pertama adalah daftar tensor video yang telah dipreprocess dengan bentuk [batch_size=1, num_channels, num_frames, height, width].
- Daftar kedua adalah daftar kekuatan kondisioning.
- Daftar ketiga adalah daftar indeks ruang laten untuk setiap kondisi.
- Daftar keempat adalah daftar jumlah frame (yang telah dipangkas) dalam ruang piksel per kondisi. Hal ini diperlukan untuk semantik koordinat keyframe (keyframe dengan satu frame piksel memiliki jangkauan temporal yang dijepit).
Memproses prapengolahan gambar/video kondisi menjadi tensor torch.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Potong urutan kondisioning menjadi jumlah frame yang diizinkan.
Jalankan upsampler pada latents yang dinormalisasi, dengan melakukan round-trip melalui ruang latens VAE mentah seperti yang diharapkan.
LTX2DFRPipelineOutput
kelas diffusers.LTX2DFRPipelineOutput
< source >( frames: Tensoraudio: Tensorkeyframes: typing.Optional[torch.Tensor] = Nonekeyframe_positions: list[int] | None = None )
Parameter
- frames (
torch.Tensor,np.ndarray, atau list[list[PIL.Image.Image]]) — Video yang telah didenoi. Output laten adalah kanvas yang belum dipangkas, dengan bentuk(batch_size, num_channels, latent_frames, latent_height, latent_width). - audio (
torch.Tensor,np.ndarray) — Latent audio atau waveform yang menyertai. - keyframes (
torch.Tensor, opsional) — Latent keyframe yang dihasilkan atau dibawa, dengan bentuk(batch_size, num_channels, num_keyframes, latent_height, latent_width).Noneketikaoutput_type != "latent", atau ketika pass tidak menghasilkan slot (misalnya epilog bertile). - keyframe_positions (
list[int], opsional) — Indeks frame piksel dari setiap keyframe pada kanvas pass ini;Nonesetiap kalikeyframesadalahNone. Setelah sebuah putaran temporal, nilai-nilai ini tidak dapat diturunkan kembali darinum_framesasli dan harus diteruskan ke tahap berikutnya.
Kelas output untuk pipeline DFR.
LTX2LatentUpsamplePipeline
kelas 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
Parameter
- video (
list[PipelineImageInput], opsional) — Video yang akan di-upsample (misalnya output tahap pertama LTX 2.0). Jika tidak diberikan,latentsharus diberikan. - height (
int, opsional, default512) — Tinggi video input dalam piksel (bukan video yang dihasilkan, yang akan memiliki resolusi lebih besar). - width (
int, opsional, default768) — Lebar video input dalam piksel (bukan video yang dihasilkan, yang akan memiliki resolusi lebih besar). - num_frames (
int, opsional, default121) — Jumlah frame dalam video input. - spatial_patch_size (
int, opsional, default1) — Ukuran patch spasial dari latens video. Digunakan saatlatentsdiberikan jika unpacking diperlukan. - temporal_patch_size (
int, opsional, default1) — Ukuran patch temporal dari latens video. Digunakan saatlatentsdiberikan jika unpacking diperlukan. - latents (
torch.Tensor, opsional) — Latens video yang telah dibuat sebelumnya. Ini dapat diberikan sebagai pengganti argumenvideo. Dapat berupa urutan patch dengan bentuk(batch_size, seq_len, hidden_dim)atau latens video dengan bentuk(batch_size, latent_channels, latent_frames, latent_height, latent_width). - latents_normalized (
bool, opsional, defaultFalse) — Jikalatentsdiberikan, apakahlatentsdinormalisasi menggunakan mean dan std laten VAE. JikaTrue,latentsakan didenormalisasi sebelum diberikan ke latent upsampler. - decode_timestep (
float, defaultnya0.0) — Timestep di mana video yang dihasilkan didekode. - decode_noise_scale (
float, defaultnyaNone) — Faktor interpolasi antara noise acak dan latents yang telah dinoise pada timestep decode. - adain_factor (
float, opsional, default0.0) — Faktor blending Adaptive Instance Normalization (AdaIN) antara latents yang di-upsample dan latents asli. Harus berada dalam rentang [-10.0, 10.0]; memberikan 0.0 (default) berarti AdaIN tidak dilakukan. - tone_map_compression_ratio (
float, opsional, default0.0) — Kekuatan kompresi untuk tone mapping, yang akan mengurangi rentang dinamis dari nilai laten. Ini berguna untuk meregularisasi laten dengan varians tinggi atau untuk mengondisikan output selama generasi. Harus berada dalam [0, 1], di mana 0.0 (default) berarti tone mapping tidak diterapkan dan 1.0 sesuai dengan efek kompresi penuh. - generator (
torch.Generatorataulist[torch.Generator], opsional) — Satu atau daftar generator torch untuk membuat proses generasi menjadi deterministik. - output_type (
str, opsional, defaultnya"pil") — Format output dari generate image. Pilih antara PIL:PIL.Image.Imageataunp.array. - return_dict (
bool, opsional, defaultTrue) — Apakah akan mengembalikan~pipelines.ltx.LTXPipelineOutputalih-alih tuple biasa.
Mengembalikan
~pipelines.ltx.LTXPipelineOutput atau tuple
Jika return_dict adalah True, maka ~pipelines.ltx.LTXPipelineOutput yang dikembalikan, selain itu sebuah tuple yang dikembalikan di mana elemen pertama adalah video yang telah di-upsample.
Fungsi yang dipanggil saat memanggil pipeline untuk generasi.
Contoh:
>>> 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
Parameter
- latents (
torch.Tensor) — Latents input untuk dinormalisasi - reference_latents (
torch.Tensor) — Latens referensi yang menyediakan statistik gaya. - factor (
float) — Faktor pencampuran antara latensi asli dan latensi yang ditransformasi. Rentang: -10.0 hingga 10.0, Default: 1.0
Mengembalikan
torch.Tensor
Tensor laten yang ditransformasi
Menerapkan Adaptive Instance Normalization (AdaIN) ke tensor laten berdasarkan statistik dari tensor laten referensi.
tone_map_latents
< source >( latents: Tensorcompression: float )
Menerapkan fungsi tone-mapping non-linear ke nilai laten untuk mengurangi rentang dinamisnya dengan cara yang halus secara perseptual menggunakan kompresi berbasis sigmoid.
Hal ini berguna untuk meregularisasi latens dengan varians tinggi atau untuk mengondisikan output selama generasi, terutama
saat mengendalikan perilaku dinamis dengan faktor compression.
LTX2VideoDiffusionDecodePipeline
kelas diffusers.LTX2VideoDiffusionDecodePipeline
< source >( diffusion_decoder: LTX2VideoDiffusionDecoderModelschedulervae: AutoencoderKLLTX2Video = None )
Parameter
- diffusion_decoder (LTX2VideoDiffusionDecoderModel) — Dekoder video difusi.
- scheduler (FlowMatchEulerDiscreteScheduler) — Scheduler yang menggerakkan langkah-langkah denoising decoder.
- vae (AutoencoderKLLTX2Video, opsional) — Hanya digunakan untuk statistik laten yang dipakai untuk menormalisasi kembali. Jika diabaikan, pipeline akan kembali ke nilai bawaan LTX-2, sehingga alur kerja yang hanya melakukan decode tidak perlu memuat autoencoder kedua.
Decode latens video LTX-2 dengan decoder difusi yang diperkenalkan dalam LTX-2.5.
Berbeda dengan decoder konvolusional, decoder ini sendiri merupakan model difusi kecil: ia menghilangkan noise pada piksel yang dikondisikan pada volume konteks yang dibangun dari latents, sehingga memerlukan scheduler dan generator. Pasangkan dengan pipeline LTX-2 mana pun yang dijalankan dengan output_type="latent", dengan meneruskan denormalize=False karena jalur tersebut sudah menerapkan statistik 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
Parameter
- latents (
torch.Tensor) — Latents dengan bentuk(B, C, F, H, W). Perhatikan bahwa eksekusi pipeline LTX-2 denganoutput_type="latent"mengembalikan latents yang sudah dinormalisasi, jadi gunakandenormalize=Falseuntuk kasus tersebut. - generator (
torch.Generator, opsional) — Decoder mengambil sampel noise yang akan dinoise-kan, sehingga berikan generator untuk membuat decoding dapat direproduksi. - output_type (
str, opsional, defaultnya"pil") — Format output dari video yang didekodekan. Pilih antara"pil","np","pt"dan"latent". - return_dict (
bool, opsional, defaultTrue) — Apakah akan mengembalikanLTX2VideoDecodeOutputalih-alih tuple biasa. - denormalize (
bool, opsional, defaultTrue) — Apakah statistik laten akan diterapkan sebelum decoding. Atur keFalsejika latens sudah dinormalisasi.
Mengembalikan
LTX2VideoDecodeOutput atau tuple
LTX2DurationHead
kelas 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 )
Parameter
- video_cross_attention_dim (
int, defaultnya4096) — Lebar dari output konektor video. - audio_cross_attention_dim (
int, defaultnya2048) — Lebar keluaran konektor audio. - pooler_hidden_dim (
int, defaultnya256) — Dimensi tersembunyi bersama yang menjadi target proyeksi kedua modalitas. - num_queries (
int, defaultnya1) — Jumlah query pooling yang dapat dipelajari. - num_pooler_heads (
int, defaultnya4) — Kepala perhatian yang digunakan oleh pooler. - mlp_hidden_dim (
int, defaultnya256) — Lebar tersembunyi dari MLP output. Dinamai dengan akhiran_dimuntuk menghindari bentrok dengan submodulmlp_hidden, yang jika tidak akan dibayangi oleh nilai config ini olehConfigMixin.__getattr__.
Memprediksi durasi alami dari shot yang tersirat oleh caption, dari output konektor teks LTX-2.
Head bersifat agnostik terhadap modalitas: Anda dapat meneruskan salah satu atau kedua output konektor video dan audio. Proyeksi input yang spesifik untuk modalitas memetakan setiap stream ke dimensi pooler bersama, embedding modalitas yang dapat dipelajari memberi label pada stream agar pooler dapat membedakannya, dan MLP kecil mengubah vektor yang telah di-pool menjadi log-durasi. Target regresi dilatih dalam log-detik, sehingga forward melakukan eksponensial dan pemanggil selalu mendapatkan detik.
Tersedia mulai dari checkpoint LTX-2.5.
forward
< source >( video_tokens: typing.Optional[torch.Tensor] = Noneaudio_tokens: typing.Optional[torch.Tensor] = None ) → torch.Tensor of shape (batch_size,)
Parameter
- video_tokens (
torch.Tensordengan bentuk(batch_size, seq_len, video_cross_attention_dim), opsional) — Output konektor video. - audio_tokens (
torch.Tensordengan bentuk(batch_size, seq_len, audio_cross_attention_dim), opsional) — Output konektor audio.
Mengembalikan
torch.Tensor dengan bentuk (batch_size,)
durasi prediksi dalam detik.
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
Parameter
- video_tokens (
torch.Tensor, opsional) — Output konektor video untuk satu prompt. - audio_tokens (
torch.Tensor, opsional) — Output konektor audio untuk satu prompt. - frame_rate (
float) — Jumlah frame per detik yang digunakan untuk mengonversi durasi prediksi menjadi jumlah frame. - temporal_compression_ratio (
int) — Rasio kompresi temporal VAE, yang mendefinisikan grid frame. - min_seconds (
float, defaultnya1.0) — Batas bawah pada prediksi. - max_seconds (
float, defaultnya20.0) — Batas atas prediksi.
Mengembalikan
int
jumlah frame yang berada pada grid temporal VAE.
Memprediksi jumlah frame dari token konektor, dibatasi pada [min_seconds, max_seconds] dan diselaraskan ke grid temporal kausal VAE (k * temporal_compression_ratio + 1).
Clamp diterapkan sebelum snapping: jumlah frame yang di-clamp belum tentu sejajar dengan grid, sehingga melakukan snapping terlebih dahulu akan menghasilkan nilai yang berbeda. Karena snapping membulatkan ke bawah, hasilnya bisa jatuh di bawah nilai minimum; ketika hal itu terjadi, hasil akan di-snap ke atas ke titik grid berikutnya, sehingga jumlah frame tetap berada dalam batas yang ditentukan.
Batas yang sempit dapat dikonversi menjadi jendela frame yang sama sekali tidak mengandung titik grid — pada 24 fps, [1.0s, 1.02s] dibulatkan menjadi [24, 24], dan 24 bukan 8k + 1. Titik grid terdekat digunakan dan peringatan dicatat, karena
melebihi batas kurang dari satu langkah grid lebih baik daripada menolak untuk menghasilkan. Jumlah yang dikembalikan oleh karena itu selalu berada di
grid, tetapi dalam kasus ini mungkin jatuh tepat di luar batas yang diminta.
LTX2PipelineOutput
kelas diffusers.pipelines.ltx2.LTX2PipelineOutput
< source >( frames: Tensoraudio: Tensor )
Parameter
- frames (
torch.Tensor,np.ndarray, atau list[list[PIL.Image.Image]]) — Daftar output video - Dapat berupa daftar bersarang dengan panjangbatch_size,di mana setiap sub-daftar berisi urutan gambar PIL yang telah didenois dengan panjangnum_frames.Dapat juga berupa array NumPy atau tensor Torch dengan bentuk(batch_size, num_frames, channels, height, width). - audio (
torch.Tensor,np.ndarray) — TODO
Kelas output untuk pipeline LTX.
LTX2ModularPipeline
kelas 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 )
ModularPipeline untuk LTX-2 (generasi video + audio bersama).
LTX2AutoBlocks
Auto blocks untuk LTX-2 yang mendukung text-to-video, image-to-video, condition-to-video, dan in-context (IC-LoRA) generation (video + audio bersama).
Alur kerja yang didukung:
text2video: membutuhkanpromptimage2video: membutuhkanimage,promptcondition: membutuhkanconditions,promptin_context: membutuhkanreference_conditions,num_frames,prompt
Komponen:
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)
Inputs:
prompt (str, optional):
The prompt or prompts to guide image generation.
conditions (list, optional): LTX2VideoCondition (or list of them) placing image/video conditions at latent frame indices of the
generated video.
enable_prompt_enhancement (bool, optional, defaults to False):
Whether to run the prompt enhancer. Opt-in, matching the Lightricks reference pipelines.
system_prompt (str, optional):
System prompt for enhancement. Defaults to LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT when a PIL.Image.Image condition frame is available, else LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT.
prompt_max_new_tokens (int, optional):
Maximum number of new tokens to generate during prompt enhancement. Defaults to 600, the LTX-2.5 Gemma-4
enhancer’s budget.
prompt_enhancement_kwargs (dict, optional):
Keyword arguments for the enhancer’s .generate call. Defaults to greedy decoding.
prompt_enhancement_seed (int, optional, defaults to 10):
Random seed for prompt enhancement (inert under LTX-2.5’s greedy decoding).
generator (Generator, optional):
Torch generator for deterministic generation.
image (Image | list, optional):
Reference image(s) for denoising. Can be a single image or list of images.
negative_prompt (str, optional):
The prompt or prompts not to guide the image generation.
max_sequence_length (int, optional, defaults to 1024):
Maximum sequence length for prompt encoding.
min_seconds (float, optional, defaults to 1.0):
Lower bound on the auto-predicted duration.
max_seconds (float, optional, defaults to 20.0):
Upper bound on the auto-predicted duration. Must be strictly greater than min_seconds.
frame_rate (float, optional, defaults to 24.0):
Frames per second of the generated video.
height (int, optional, defaults to 512):
The height in pixels of the generated image.
width (int, optional, defaults to 704):
The width in pixels of the generated image.
image_crf (int, optional):
H.264 CRF used to re-compress the conditioning image before VAE encode, matching the compression the
model was trained against. None (default) resolves from the text-encoder generation (33 through
LTX-2.3, 18 for LTX-2.5). Pass 0 to skip re-compression. Requires a PIL.Image.Image when
re-compression runs.
num_frames (int, optional):
The number of frames in the generated video. Omit to auto-predict via the duration_head (see LTX2AutoDurationStep).
reference_conditions (list, optional): LTX2ReferenceCondition (or list of them) whose videos are encoded into extra latent tokens the IC-LoRA
adapter attends to.
reference_downscale_factor (int, optional, defaults to 1):
Ratio between the target and reference resolutions; 2 means the reference is preprocessed at half the
target resolution. Spatial coordinates are scaled by this factor so the reference tokens land in the
target coordinate space. Must match the factor the IC-LoRA was trained with.
conditioning_attention_strength (float, optional, defaults to 1.0):
Scalar in [0, 1] controlling how strongly the noisy tokens and reference tokens attend to each other. 1.0
(default) leaves attention unmasked.
conditioning_attention_mask (Tensor, optional):
Optional pixel-space mask of shape (1, 1, F, H, W) with values in [0, 1] giving spatially varying
attention strength. Downsampled to the reference’s latent grid and multiplied by conditioning_attention_strength.
motion_speed (float, optional, defaults to 1.0):
Speed of the motion relative to real time. The positional embeddings are conditioned on frame_rate / motion_speed, so values below 1 slow the motion down, e.g. 0.2 for the Slow-Motion-Control LoRA’s 5x
slow motion. frame_rate stays the playback rate.
num_videos_per_prompt (int, optional, defaults to 1):
The number of images to generate per prompt.
condition_latents (list, optional):
Per-condition normalized VAE latents of shape [1, C, F, H, W].
condition_strengths (list, optional):
Per-condition conditioning strengths.
condition_indices (list, optional):
Per-condition latent frame index at which the condition is applied.
condition_pixel_frames (list, optional):
Per-condition trimmed pixel frame count, used to clamp single-frame keyframe coords.
reference_latents (Tensor, optional):
Packed reference tokens of shape [1, total_reference_tokens, C], or None when no reference conditions
were supplied (LTX2AutoReferenceEncoderStep is skipped).
reference_coords (Tensor, optional):
RoPE coordinates for the reference tokens.
reference_token_counts (list, optional):
Per-reference token counts, in reference_conditions order.
latents (Tensor):
Pre-generated noisy latents for image generation.
noise_scale (float, optional):
Initial noise level for the un-conditioned tokens. None (default) resolves to sigmas[0] when custom sigmas are supplied, else 1.0.
sigmas (list, optional):
Custom sigmas for the denoising process.
reference_cross_mask (Tensor, optional):
Per-reference-token noisy<->reference attention strengths of shape [1, num_ref_tokens].
num_inference_steps (int):
The number of denoising steps.
timesteps (Tensor):
Timesteps for the denoising process.
audio_latents (Tensor):
Optional pre-encoded audio latents; random noise is used when not provided.
*denoiser_input_fields (None,optional):
conditional model inputs for the denoiser: e.g. prompt_embeds, negative_prompt_embeds, etc.
use_cross_timestep (bool,optional, defaults to True):
Whether to condition the transformer on a separate per-token cross timestep (LTX-2.3+).
attention_kwargs (dict,optional):
Additional kwargs for attention processors.
image_latents (Tensor,optional):
VAE-encoded reference-image latents used for image-to-video conditioning.
output_type (str,optional, defaults to pil):
Output format: ‘pil’, ‘np’, ‘pt’.
decode_timestep (None,optional, defaults to 0.0):
The timestep at which the VAE decodes the final latents.
decode_noise_scale (None,optional*):
Noise interpolation factor applied to the latents at the decode timestep.
Output:
videos (list):
Video yang dihasilkan.
audio (Tensor):
Bentuk gelombang audio yang dihasilkan.
LTX25ModularPipeline
kelas 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 )
ModularPipeline untuk LTX-2.5 (generasi video + audio bersama).
Identik dengan LTX2ModularPipeline kecuali blok default-nya melakukan dekoding dengan diffusion video decoder, yang merupakan default native dari LTX-2.5 ke atas. Checkpoint diarahkan ke sini melalui modular_model_index.json.
LTX25AutoBlocks
Auto blocks untuk LTX-2.5 yang mendukung text-to-video, image-to-video, condition-to-video, dan in-context (IC-LoRA) generation (video + audio secara bersama). Identik dengan LTX2AutoBlocks kecuali bahwa video decoder-nya adalah LTX2DiffusionVaeDecoderStep, karena diffusion decoder adalah default bawaan mulai dari LTX-2.5. Untuk melakukan decode dengan convolutional VAE, ganti decode block: blocks.sub_blocks["decode"] = LTX2AutoDecoderStep().
Alur kerja yang didukung:
text2video: membutuhkanpromptimage2video: membutuhkanimage,promptcondition: membutuhkanconditions,promptin_context: membutuhkanreference_conditions,num_frames,prompt
Komponen:
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)
Inputs:
prompt (str, optional):
The prompt or prompts to guide image generation.
conditions (list, optional): LTX2VideoCondition (or list of them) placing image/video conditions at latent frame indices of the
generated video.
enable_prompt_enhancement (bool, optional, defaults to False):
Whether to run the prompt enhancer. Opt-in, matching the Lightricks reference pipelines.
system_prompt (str, optional):
System prompt for enhancement. Defaults to LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT when a PIL.Image.Image condition frame is available, else LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT.
prompt_max_new_tokens (int, optional):
Maximum number of new tokens to generate during prompt enhancement. Defaults to 600, the LTX-2.5 Gemma-4
enhancer’s budget.
prompt_enhancement_kwargs (dict, optional):
Keyword arguments for the enhancer’s .generate call. Defaults to greedy decoding.
prompt_enhancement_seed (int, optional, defaults to 10):
Random seed for prompt enhancement (inert under LTX-2.5’s greedy decoding).
generator (Generator, optional):
Torch generator for deterministic generation.
image (Image | list, optional):
Reference image(s) for denoising. Can be a single image or list of images.
negative_prompt (str, optional):
The prompt or prompts not to guide the image generation.
max_sequence_length (int, optional, defaults to 1024):
Maximum sequence length for prompt encoding.
min_seconds (float, optional, defaults to 1.0):
Lower bound on the auto-predicted duration.
max_seconds (float, optional, defaults to 20.0):
Upper bound on the auto-predicted duration. Must be strictly greater than min_seconds.
frame_rate (float, optional, defaults to 24.0):
Frames per second of the generated video.
height (int, optional, defaults to 512):
The height in pixels of the generated image.
width (int, optional, defaults to 704):
The width in pixels of the generated image.
image_crf (int, optional):
H.264 CRF used to re-compress the conditioning image before VAE encode, matching the compression the
model was trained against. None (default) resolves from the text-encoder generation (33 through
LTX-2.3, 18 for LTX-2.5). Pass 0 to skip re-compression. Requires a PIL.Image.Image when
re-compression runs.
num_frames (int, optional):
The number of frames in the generated video. Omit to auto-predict via the duration_head (see LTX2AutoDurationStep).
reference_conditions (list, optional): LTX2ReferenceCondition (or list of them) whose videos are encoded into extra latent tokens the IC-LoRA
adapter attends to.
reference_downscale_factor (int, optional, defaults to 1):
Ratio between the target and reference resolutions; 2 means the reference is preprocessed at half the
target resolution. Spatial coordinates are scaled by this factor so the reference tokens land in the
target coordinate space. Must match the factor the IC-LoRA was trained with.
conditioning_attention_strength (float, optional, defaults to 1.0):
Scalar in [0, 1] controlling how strongly the noisy tokens and reference tokens attend to each other. 1.0
(default) leaves attention unmasked.
conditioning_attention_mask (Tensor, optional):
Optional pixel-space mask of shape (1, 1, F, H, W) with values in [0, 1] giving spatially varying
attention strength. Downsampled to the reference’s latent grid and multiplied by conditioning_attention_strength.
motion_speed (float, optional, defaults to 1.0):
Speed of the motion relative to real time. The positional embeddings are conditioned on frame_rate / motion_speed, so values below 1 slow the motion down, e.g. 0.2 for the Slow-Motion-Control LoRA’s 5x
slow motion. frame_rate stays the playback rate.
num_videos_per_prompt (int, optional, defaults to 1):
The number of images to generate per prompt.
condition_latents (list, optional):
Per-condition normalized VAE latents of shape [1, C, F, H, W].
condition_strengths (list, optional):
Per-condition conditioning strengths.
condition_indices (list, optional):
Per-condition latent frame index at which the condition is applied.
condition_pixel_frames (list, optional):
Per-condition trimmed pixel frame count, used to clamp single-frame keyframe coords.
reference_latents (Tensor, optional):
Packed reference tokens of shape [1, total_reference_tokens, C], or None when no reference conditions
were supplied (LTX2AutoReferenceEncoderStep is skipped).
reference_coords (Tensor, optional):
RoPE coordinates for the reference tokens.
reference_token_counts (list, optional):
Per-reference token counts, in reference_conditions order.
latents (Tensor):
Pre-generated noisy latents for image generation.
noise_scale (float, optional):
Initial noise level for the un-conditioned tokens. None (default) resolves to sigmas[0] when custom sigmas are supplied, else 1.0.
sigmas (list, optional):
Custom sigmas for the denoising process.
reference_cross_mask (Tensor, optional):
Per-reference-token noisy<->reference attention strengths of shape [1, num_ref_tokens].
num_inference_steps (int):
The number of denoising steps.
timesteps (Tensor):
Timesteps for the denoising process.
audio_latents (Tensor):
Optional pre-encoded audio latents; random noise is used when not provided.
*denoiser_input_fields (None,optional):
conditional model inputs for the denoiser: e.g. prompt_embeds, negative_prompt_embeds, etc.
use_cross_timestep (bool,optional, defaults to True):
Whether to condition the transformer on a separate per-token cross timestep (LTX-2.3+).
attention_kwargs (dict,optional):
Additional kwargs for attention processors.
image_latents (Tensor,optional):
VAE-encoded reference-image latents used for image-to-video conditioning.
output_type (str,optional*, defaults to pil):
Output format: ‘pil’, ‘np’, ‘pt’.
Output:
videos (list):
Video yang dihasilkan.
audio (Tensor):
Bentuk gelombang audio yang dihasilkan.