Buckets:
Apache Lisansı, 2.0 Sürümü ("Lisans") altında lisanslanmıştır;
bu dosyayı, Lisansa uygun olarak kullanabilirsiniz.
Lisansın bir kopyasını şu adresten edinebilirsiniz
http://www.apache.org/licenses/LICENSE-2.0
Uygulanabilir yasa gerektirmedikçe veya yazılı olarak anlaşılmadıkça, yazılım
Lisans kapsamında dağıtılan, "OLDUĞU GİBİ" esasına göre dağıtılır,
HİÇBİR TÜR AÇIK VEYA ZIMMİ GARANTİ VEYA ŞART İÇERMEZ.
İzinleri ve
lisans kapsamındaki kısıtlamalar. -->
LTX-2
LTX-2, tek bir model içinde senkronize video ve ses üretmek üzere tasarlanmış, DiT tabanlı bir temel modeldir. Modern video üretiminin temel yapı taşlarını bir araya getirir; açık ağırlıklara sahiptir ve pratik, yerel çalıştırma odaklıdır.
Tüm orijinal LTX-Video checkpoint'lerini Lightricks kuruluşu altında bulabilirsiniz.
LTX-2'nin orijinal kod tabanı burada bulunabilir.
İki Aşamalı Üretim
Ortak LTX2Pipeline / LTX2ImageToVideoPipeline __call__ varsayılanları LTX-2.5 referansıyla eşleşir (num_inference_steps=30; num_frames, bir duration_head varsa isteğe bağlıdır, yoksa 121 değerine geri düşer). Aşağıdaki örnekler, LTX-2.0/2.3 için de bu varsayılanları kullanır.
Üretim kalitesinde üretim elde etmek için önerilen pipeline, bu pipeline iki aşamadan oluşur:
- Aşama 1: Sınıflandırıcı-ücretsiz yönlendirme (CFG) ile difüzyon örneklemesi kullanarak hedef çözünürlükte bir video üretin. Bu aşama, metin/görsel koşullandırmaya uyan tutarlı bir düşük gürültülü video dizisi üretir.
- Aşama 2: Aşama 1 çıktısını 2 kat büyütüp detayları, sadakati ve görsel kaliteyi iyileştirmek için damıtılmış bir LoRA modeliyle rafine edin. Aşama 2, Aşama 1'deki yapıyı korurken doku ve keskinliği artırmak için daha hafif bir CFG uygulayabilir.
Metinden videoya iki aşamalı hattın örnek kullanımı
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",
)
Distilled checkpoint oluşturma
Distille edilmiş bir kontrol noktası (checkpoint) kullanan en hızlı iki aşamalı üretim hattı.
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",
)
Koşul Boru Hattı Üretimi
Görsel ve/veya video koşullarını keyfi latent indekslerde belirtmek için LTX2ConditionPipeline kullanabilirsiniz. Örneğin, ilk-son-kare-ten-videoya (FLF2V) üretimi gerçekleştirmek için hem ilk kare hem de son kare koşulunu belirtebiliriz:
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",
)
Hem görüntü hem de video koşullarını kullanabilirsiniz:
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",
)
Koşullandırma gizli kareler üzerinden yapıldığından, bir görüntü koşulu için belirtilen gizli kareye karşılık gelen 8 veri uzayı karesi genellikle statik olacaktır.
Çok Modlu Yönlendirme
LTX-2.X pipeline'leri çok modlu yönlendirmeyi destekler. Üç terimden oluşur ve hepsi CFG tarzı bir güncelleme kuralı kullanır:
- Classifier-Free Guidance (CFG): standart CFG, burada bozulmuş ("daha zayıf") çıktı negatif istem kullanılarak üretilir.
- Spatio-Temporal Guidance (STG): STG, self-attention işlemlerini kısaltarak oluşturulan bozulmuş çıktıdan uzaklaşır ve bunun yerine dikkat değerlerini kullanır. Bu yaklaşımın, daha keskin videolar ve daha iyi uzamsal-zamansal tutarlılık sağlaması amaçlanmaktadır.
- Modality İzolasyonu Rehberliği: çapraz modalite (ses-videodan ve video-sese) çapraz dikkatin devre dışı bırakılmasıyla oluşturulan bozulmuş çıktıdan uzaklaşır. Bu rehberlik, üretilen ses ve video arasında daha iyi tutarlılık sağladığı fikriyle LTX-2.X modellerine daha özeldir.
Bu değerler guidance_scale, stg_scale ve modality_scale argümanları ile kontrol edilir ve video ile ses için ayrı ayrı ayarlanabilir. Ayrıca STG için, öz-dikkatin atlanacağı transformer blok indekslerinin spatio_temporal_guidance_blocks argümanı üzerinden belirtilmesi gerekir. LTX-2.X pipeline'ları, yüksek guidance ölçeklerinde karşılaşılabilecek aşırı pozlama sorununu azaltmaya yardımcı olmak için guidance rescaling özelliğini de destekler.
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",
)
İstem Geliştirme
LTX-2.X modelleri istem yazım stiline duyarlıdır. İyi bir istem nasıl yazılır konusunda öneriler için resmî istem kılavuzuna bakın. İstem geliştirme, verilen istemlerin bir sistem istemiyle birlikte hattın metin kodlayıcısı (varsayılan olarak bir Gemma 3 modeli) kullanılarak geliştirilmesi, örnek kalitesini de artırabilir. İstem geliştirmeyi kullanmak için isteğe bağlı processor hattı bileşeninin mevcut olması gerekir. Bunu enable_prompt_enhancement=True ve bir system_prompt ile etkinleştirin (isteğe bağlı, Lightricks referans hatlarıyla uyumlu):
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, LTX-2.3 ile aynı LTX2Pipeline/LTX2VideoTransformer3DModel/AutoencoderKLLTX2Video/vb. sınıflarını yeniden kullanır — bunun için ayrı bir pipeline sınıfı yoktur. Kullanıcıya yansıyan fark metin kodlayıcıdır: LTX-2.5, Gemma 3 yerine Gemma 4 (gemma4_unified) checkpoint'i ile eşleştirilmiştir. Bu, dönüştürülmüş bir LTX-2.5 checkpoint'i üzerinde from_pretrained çağrıldığında (transformers Auto* sınıfları aracılığıyla) otomatik olarak yüklenir, bu nedenle çıkarım sırasında ek bir kurulum gerekmez — yalnızca from_pretrained çağrısını bir LTX-2.3 deposu yerine bir LTX-2.5 deposuna yönlendirin.
Lightricks/LTX-2.5-Diffusers her iki transformer'ı da içerir: model_index.json'in işaret ettiği, transformer/ içindeki distilled DiT ve açıkça yüklenmesi gereken (bkz. Full / SFT transformer), transformer_full/ içindeki full/SFT DiT. Repo'nun scheduler/ dizini, sigma zamanlamasının tam olarak verildiği gibi kullanılabilmesi için distilled checkpoint'e göre yapılandırılmıştır (use_dynamic_shifting=False, shift_terminal=None). two-stage generation için gereken her şey de orada mevcuttur: bir latent_upsampler/ alt dizini ve repo kökünde bulunan stage 2 distilled LoRA, ltx-2.5-22b-distilled-lora-450-bf16.safetensors.
Distilled inference, adım sayısı yerine açık bir sigma zamanlaması tarafından yönlendirilir ve rehbersiz çalışır (guidance_scale=1.0, bu nedenle negative_prompt kullanılmaz). Bunun yerine num_inference_steps geçirilirse modele genel bir doğrusal zamanlama verilir ve sessizce kalite kaybına yol açılır:
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",
)
LTX-2.5 için iki aşamalı üretim
LTX-2.5, iki aşamalı varyantların her ikisini de destekler ve DISTILLED_SIGMA_VALUES / STAGE_2_DISTILLED_SIGMA_VALUES onun referans zamanlamalarıdır:
- Distilled checkpoint, her iki aşama — varsayılan
transformer/için referans tarif ve aşağıda gösterilen tarif. Transformer zaten distile edildiği için 2. aşama LoRA devreye girmiyor; bu, LTX-2.5 ağırlıklarıyla Distilled checkpoint generation. - Tam/SFT 1. aşama + damıtılmış LoRA 2. aşama — Bu sayfanın başında anlatıldığı gibi İki Aşamalı Üretim,
transformer_full/ve pakette gelen LoRA kullanılarak. Ne değiştiğini görmek için aşağıya bakın.
Stage 1, hedef çözünürlüğün yarısında çalışır; upsampler bunu ikiye katlar ve stage 2, tam çözünürlükte inceltme yapar — video ve ses, ikisi de noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0] değerinde stage 1 latentlerinden yeniden tohumlanır. Stage 1 her ekseni yarıya indirdiği ve yine de VAE'nin uzamsal ızgarasına oturması gerektiği için yükseklik ve genişlik 64'e tam bölünmelidir.
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",
)
Uzunluk açık bir num_frames yerine duration head'den geliyorsa, ikinci aşama çalışmadan önce ikinci kez tahmin etmek yerine, birinci aşamanın karar vermesini sağlayın ve gerçekleşen uzunluğu latentlerinden ([B, C, F, H, W]) kurtarın:
num_frames = (video_latent.shape[2] - 1) * pipe.vae_temporal_compression_ratio + 1
Damıtılmış LoRA ile Aşama 2
Bunun yerine Two-stages Generation çalıştırmak için — 1. aşama için full/SFT DiT, 2. aşama için distilled LoRA — Full / SFT transformer bölümündeki gibi pipeline'ı oluşturun ve 1. aşama latentlerini bu guidance yığınıyla üretin. Ardından LTX-2.0/2.3'ten iki şey farklılaşır. LoRA, orijinal ağırlıkların yanında değil, doğrudan diffusers deposunun içinde yer alır ve scheduler yönü tersine döner: LTX-2.5, distilled scheduler yapılandırmasını içerir; bu nedenle 1. aşama dynamic shifting'i açan aşamadır ve 2. aşama bunu tekrar kapatır.
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
)
Yukarıdaki damıtılmış tariften farklı olarak, upsample adımı ve stage 2 çağrısı değiştirilmedi: aynı sigmas=STAGE_2_DISTILLED_SIGMA_VALUES, aynı noise_scale ve guidance_scale=1.0, çünkü stage 2 her halükârda damıtılmış bir model çalıştırıyor.
Dolanımsal ve difüzyon çözme
LTX-2.5, aynı gizli uzay üzerinde iki video çözücüyle birlikte gelir, bu nedenle gizli değişkenler (latents) bunlar arasında değiştirilebilir:
vae/— konvolüsyonel VAE (AutoencoderKLLTX2Video). Pipeline'lerin çözümleme (decode) işlemi için kullandığı bileşen budur; bu nedenle yukarıdaki tüm kod parçacıkları zaten onu kullanmaktadır ve ikisi arasında tiling (pipe.vae.enable_tiling()) özelliğini destekleyen tek bileşen de odur. Genellikle yüksek çözünürlüklü çıktıların belleğe sığmasını sağlayan şey de budur.diffusion_decoder/— LTX2VideoDiffusionDecoderModel. Bir pipeline bileşeni değil, kendi başına bir difüzyon modeli olduğu içinvaeolarak geçirilmez: pipeline'ıoutput_type="latent"ile çalıştırın ve latentleri LTX2VideoDiffusionDecodePipeline'a iletin.
Kodlama her zaman vae/ üzerinden geçer, bu nedenle görüntü ve video koşullandırma seçimi etkilenmez.
Difüzyon çözücüyle çözümleme yaptığınızda iki şey değişir. output_type="latent" ayrıca vokal kodlayıcıyı da atlar, bu yüzden ses latent olarak geri döner ve elle tamamlanması gerekir; NATTEN işlemcisi ise video çözünürlüklerinde fiilen zorunludur:
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",
)
Bunu iki aşamalı üretim ile birleştirmek için, 2. aşamadan output_type="latent" isteyin ve bunu çözümlen.
decoder.enable_tiling(), konvolüsyonel VAE için pipe.vae.enable_tiling()'in yaptığı gibi, yüksek çözünürlüklü bir çözmenin bellekte kalmasını sağlar. Çözmenin bellek ağırlıklı kısmı olan son yukarı örneklemeye (upsampling) aşaması ve difüzyon aşaması, ardından birleştirilen üst üste binen karolar üzerinde çalışır; böylece tepe bellek, video boyutu yerine karo boyutuyla sınırlanır. Tiling yalnızca latent bir karoyu aştığında devreye girer ve karo ile örtüşme boyutları tile_sample_min_* / tile_sample_stride_* argümanları üzerinden ayarlanabilir (varsayılanlar referans uygulamasıyla eşleşir). Difüzyon aşaması her karoyu ayrı ayrı gürültüden arındırdığı için, karolu bir çözüm, karosuz sonucu tam olarak yeniden üretmez.
Tek bir kartta, decoder'ın kendi payına düşen alanı (headroom) gerektirmesi nedeniyle, pipeline'ı decode işleminden önce kenara çekmek de faydalıdır (pipe.scheduler ve vokoderin output_sampling_rate değerlerini yakaladıktan sonra pipe.to("cpu") ve torch.cuda.empty_cache() çağrılır). Dikkat (attention) arka uçları, karolama (tiling) detayları ve decoder'ın davranışının geri kalanı için LTX2VideoDiffusionDecoderModel sınıfına bakın.
Tam / SFT dönüştürücü
transformer_full/, model_index.json tarafından referans alınmadığı için açıkça yüklenmelidir. Ayrıca farklı bir zamanlayıcı ve gerçek bir yönlendirme yığınına ihtiyaç duyar: teslim edilen scheduler/, damıtılmış kontrol noktası için yapılandırılmıştır ve yönlendirme varsayılanları, LTX-2.5 SFT çalıştırmasını hiçbir uyarı vermeden belirgin şekilde yetersiz yönlendirilmiş bırakacak LTX-2.0 dönemi genel ayarlardır. Çok Modlu Yönlendirme önerileri burada aynen geçerlidir, 28 bloğunda STG dahil olmak üzere:
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,
)
sigmas buraya bırakılır — tam DiT, zamanlamasını scheduler'dan alır.
LTX-2.5 için Prompt Geliştirme
LTX-2.5 için prompt iyileştirme kullanımı şiddetle önerilir; etkinleştirmek için enable_prompt_enhancement=True parametresini iletin (Lightricks referans pipeline'ları ile aynı). LTX-2.0/2.3'te aynı metin kodlayıcı kontrol noktası iyileştirici olarak da görev yaparken (bkz. yukarıdaki Prompt Enhancement), LTX-2.5'in ince ayarlı metin kodlayıcısı iyileştirme için eğitilmemiştir. Bunun yerine iyileştirme, ayrı, hazır bir google/gemma-4-E2B-it kontrol noktası kullanır. Bunu pipeline'ın isteğe bağlı prompt_enhancer/processor bileşenlerine yükleyin, ardından iyileştirmeyi etkinleştirin — pipeline varsayılan olarak LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT ve Gemma 4 tarifesini (do_sample=False, no_repeat_ngram_size=5, max_new_tokens=600) kullanır. Değiştirmek için açık bir system_prompt= iletin:
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",
)
Aynı durum, LTX2ImageToVideoPipeline ile görüntüden videoya dönüşüm için de geçerlidir: pipe.prompt_enhancer/pipe.processor alanlarını aynı şekilde ayarlayın ve enable_prompt_enhancement=True parametresini iletin (LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT kullanılarak, hem referans görüntüye hem de metin istemine koşullandırma yapılır) — yine, üzerine yazmak istemedikçe system_prompt= parametresine gerek yoktur.
LTX-2.5 için otomatik süre
LTX-2.5 checkpoint'ları, transformer'ın koşullandığı aynı metin-connector çıktısından, betimlenen çekimin ne kadar uzun olması gerektiğini tahmin eden küçük bir duration_head içerir. Yüklenen pipeline'da bu var ise, num_frames varsayılan olarak otomatik tahmin edilir — bu parametreyi atladığınızda model uzunluğu kendisi seçer:
video, audio = pipe(prompt=prompt, output_type="np", return_dict=False)
Uzunluğu kendiniz belirlemek için num_frames parametresini açıkça iletin. Bir tamsayı, başlık (head) değerine her zaman öncelik kazanır:
video, audio = pipe(prompt=prompt, num_frames=121, output_type="np", return_dict=False)
LTX-2.0 veya LTX-2.3 checkpoint'lerinden yüklenen Pipelines'lerde süre başlığı (duration head) bulunmaz ve önceki varsayılan olan 121 kare korunur; bu nedenle bunlar için hiçbir şey değişmez.
Tahmini sınırlamak için min_seconds / max_seconds geçirin. Ham tahmin aralığa sıkıştırılır, ardından karelere dönüştürülür:
video, audio = pipe(
prompt=prompt,
min_seconds=2.0,
max_seconds=10.0,
frame_rate=frame_rate,
output_type="np",
return_dict=False,
)
Tahmini kare sayıları, VAE'nin nedensel zaman ızgarasına (8k + 1) oturtulduğundan, gerçekleşen süre kuantize edilir — 24 fps'de adım başına yaklaşık 0,33 sn — ve başlık saniye değil kare tahmin ettiği için frame_rate ile birlikte kayar. min_seconds, max_seconds'ten kesin olarak küçük olmalıdır. Bu sınırlar, num_frames açıkça ayarlandığında yok sayılır.
Bir grid adımından daha dar sınırlar tam olarak sağlanamayabilir: 24 fps’de [1.0s, 1.02s] [24, 24] kareye dönüşür ve 24, 8k + 1 değildir. En yakın grid noktası kullanılır ve bir uyarı kaydedilir; bu nedenle döndürülen uzunluk, bu kadar sıkı sınırların hemen dışına çıkabilir.
Bir video oluşturmadan bir tahmini incelemek için başlığı doğrudan çağırın. İhtiyaç duyduğu her şey herkese açıktır:
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")
2.5 kontrol noktasının dönüştürülmesi, başlığı --full_pipeline ile otomatik olarak veya --duration_head ile tek başına seçer. 2.5'ten önceki kontrol noktalarında bu tür ağırlıklar yoktur ve dönüştürme işlemi bileşeni atlar, hata vermez.
LTX-2.5 için hareket hızı
LTX-2, her video jetonunu saniye cinsinden bir zaman eksenine yerleştirir; bu eksen varsayılan olarak oynatma hızı olan frame_rate parametresinden türetilir. motion_speed (varsayılan 1.0) bu iki kavramı ayırır: zaman ekseni frame_rate / motion_speed değerine göre koşullanırken, ses uzunluğu, duration head ve döndürülen video hâlâ frame_rate değerine uyar. frame_rate=24.0 ve motion_speed=0.2 değerleriyle model, eylemin 120 fps'de kaydedildiğini ve sonucun 24 fps'de oynatılacağını öğrenir; bu da 5x yavaş çekim etkisi verir.
Temel model yaklaşık 24/25/30/60 fps civarında eğitildiğinden, 1.0'dan uzak hızlar yalnızca bunlar için eğitilmiş bir adaptörle anlam kazanır; örneğin Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control (gated: önce Hub'da lisansını kabul edin). motion_speed olmadan bu LoRA, düz bir LoRA olarak yüklenir ve hiçbir hareket kontrolü sağlamaz. Model kartı, LoRA gücü 1.0 iken 1.0, 0.5, 0.2, 0.1, 0.05 ve 0.025 hızlarını önerir. Etkiyi yalnızca motion_speed parametresi yönettiğinden, hız ifadelerini ("slow motion", "high fps") prompt'tan çıkarın ve hızlar arasında aynı başlığı yeniden kullanın.
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",
)
Her iki klip de 121 kare sürer (24 fps'de yaklaşık 5 saniye) ve yalnızca hareketin temposu değişir. İki aşamalı üretimde, aynı motion_speed değerini her iki aşamaya da iletin. 2. aşama videoyu yeniden gürültüden arındırır ve gerçek zamanlı eksen üzerinde çalışırsa yavaş hareketi geri alır. Referans sürücü, her iki geçişin paylaştığı aşama nesnesini sarmalayarak aynı işi yapar.
motion_speed, LTX-2 / LTX-2.5 modüler bloklarının da bir girdisidir ve modüler pipeline'a aynı şekilde iletilir.
LTX-2.5 Modüler
LTX-2.5 ayrıca modüler bir pipeline olarak da kullanılabilir. Varsayılan blok seti, num_frames parametresi atlandığında difüzyon çözücüsünü kullanır ve video süresini tahmin eder. guider ve audio_guider bileşenleri aracılığıyla yönlendirmeyi video ve ses için ayrı ayrı uygular. Kullanılabilir yönlendirme parametreleri için LTX2Guidance bölümüne bakın. Varsayılan olarak, modüler pipeline, prompt geliştiriciyi ve işleyiciyi google/gemma-4-E2B-it deposundan indirir. Aşağıda T2V modüler bir örnek yer almaktadır:
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",
)
Modüler pipeline, sağlanan girdilere göre iş akışlarını otomatik olarak değiştirir. Örneğin, image sağlanırsa bir I2V iş akışı kullanılır:
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",
)
Desteklenen iş akışlarını her blok setinin belgelerinde görebilirsiniz (ör. LTX2AutoBlocks, LTX25AutoBlocks).
LTX-2.5 için Diffusion Fidelity Rendering (DFR)
LTX2DFRPipeline, duvar saati süresini detay sadakatiyle takas eder. Her __call__, height × width çözünürlüğünde tek bir gürültü azaltma geçişidir: video ile birlikte, bu yuvalardan tohumlanan ek tek piksellik kare anahtar kare yuvalarını üretir veya bu yuvalardan tohumlanan sağlanan latentleri yeniden gürültü azaltır. Çağıranlar, diğer LTX iki aşamalı boru hatlarında olduğu gibi aşamaları aynı şekilde birleştirir: bu boru hattı, LTX2LatentUpsamplePipeline, yine bu boru hattı ve ardından her zaman turu için LTX2DFRTemporalRefinePipeline.
Bir slot, bir piksel çerçevesi satın almak için tam bir latent çerçeve kadar token harcar; bu da o konumdaki etkin zaman sıkıştırmayı gevşetir — böylece çevresindeki video, ara değerlenmiş (interpolated) çerçeveler yerine gerçekten yeni çerçevelere koşullandırılır. Slot konumları, VAE'nin zaman sınırına hizalı bir segment ızgarasından gelir (istek daha az dolgu gerektiren 24 veya 32 piksel çerçevesi). Tuval, içsel olarak segmentlerin tam sayısına doldurulur; output_type="latent" bu doldurulmuş ızgarayı döndürür, böylece dolgu üzerindeki bir slot düşürülmez. VAE çözümü öncesinde trim_canvas ile kırpın.
Bunun, use_keyframes_abs_pos_embedding ayarını belirleyen bir transformer yapılandırması gerektirir; bu ayar, tek piksellik kare latentlerini öğrenilmiş bir gömme ile işaretler. LTX-2.5 kontrol noktaları bunu içerir; pipeline, yorumlayamayacağı jetonlara jeton bütçesini harcamak yerine, daha eski her şeyde hata fırlatır.
Ekstra jetonlar için bütçe ayarlayın: her slot bir latent karelik ek kapasite sağlar, bu nedenle 2. aşama, eşdeğer iki aşamalı damıtılmış geçişten daha uzun bir dizi çalıştırır — 1024x1536 / 121 karede +%31 (24576 -> 32256 jeton, 24 karelik segment ızgarasında 5 slot). Zirve aktivasyon belleği buna göre ölçeklenir, bu yüzden düz damıtılmış tarife sığan bir çözünürlük, DFR altında enable_sequential_cpu_offload, vae.enable_tiling() veya daha küçük bir tuval gerektirebilir.
Composition, keyframes ve keyframe_positions için return_dict=True kullanır (return_dict=False, aynı dört alanı bir tuple olarak döndürür).
Aşağıdaki tam tarif, başlamak için değer olanıdır: 1088×1920 görüntüden videoya, bir x2 zamansal iyileştirme turu ve 2. aşamada x2 uzamsal detaylandırma IC-LoRA.
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 ve width nihai çıktı değil, bu geçişin boyutlarıdır. 1. aşama 1080p tuvalin yarısında (544×960); 2. aşama 1088×1920 çözünürlükte çalışır. Her biri, VAE'nin uzamsal sıkıştırma oranına (LTX-2.5'te tek geçiş için 32; 1. aşama 1080p'nin yarısı olduğunda 64) tam bölünmelidir. Bu nedenle 1080p 1920×1088 ve 4K 3840×2176 olarak ayarlanır. Her geçiş, sabit bir damıtılmış zaman çizelgesi (sigmas) çalıştırdığı için num_inference_steps parametresi yoktur; damıtılmış zaman çizelgeleri rehberlik olmadan eğitildiği için negative_prompt veya guidance_scale de yoktur. Teslim edilen ses, 1. aşamanın sesidir; sonraki geçişler, video dalının çapraz modallı dikkat (cross-modal attention) kullanabilmesi için yine bir ses akışı çalıştırır; ancak dalga formu (waveform) 1. aşamadan sonra iyileştirilmez.
Uzaysal detaylandırma. 2x uzaysal detaylandırma IC-LoRA'sını, 1. aşamanın ardından adlandırılmış bir adaptör olarak yükleyin ve yalnızca 2. aşama için etkinleştirin (set_adapters(["detailing"], adapter_weights=[0.5])). 2. aşama, 1. aşamanın yarı çözünürlüklü latentini reference_latents olarak dikkate alır. 1. aşama ve zamansal turlar, adaptör kapalıyken çalışır. LoRA'yı 1. aşamadan önce yüklerseniz, transformer.disable_adapters() onu kapatır ve set_adapters onu geri açmaz — 2. aşamadan önce transformer.enable_adapters() çağrısını yapın veya tarife uygun şekilde ağırlıkları 1. aşamadan sonra yükleyin. reference_downscale_factor (varsayılan 2), referans jetonlarının uzaysal koordinatlarını hedefin koordinat uzayına ölçekler.
Zamansal iyileştirme. LTX2DFRTemporalRefinePipeline tek bir turdur: zamansal olarak örneklemeyi artırır, ana kare dikişlerinde karolar oluşturur, LTXEulerAncestralRFScheduler ile atal gürültü azaltma yapar (eta=0.5), sonraki karonun giriş kısmını atarak birleştirir ve taşıma ana karesi çantasını birleştirir. Bu zamanlayıcıyı kendiniz oluşturun — tur, başka bir şeyle reddedilir, çünkü deterministik bir adım tamamlanana kadar çalışır ve yalnızca daha yumuşak bir tuval döndürür. Tur başına bir kez pipeline'ı çağırın; 2x / 4x için döngüye girin ve round_index parametresini iletin. Bir turdan sonra keyframe_positions, orijinal num_frames değerinden yeniden türetilemez ve iletilmelidir. Her karo, kendi oynatma penceresini kapsayan dondurulmuş 1. aşama sesinin dilimini alır. source_seconds, 1. aşamanın süresidir ve turlar arasında sabit kalır, bu nedenle sonraki turlar varsayılanı almak yerine bunu açıkça iletmelidir.
Muxing'den bağımsız olarak, oynatma 30'un üzerinde olduğunda koşullandırma fps'i her zaman 60'tır: RoPE zamanı pixel_frame / fps olduğundan, 120 fps'lik bir zaman tabanı, eğitim dağılımına kıyasla her token'ın zamansal aralığını yarıya indirirken 48 fps bu aralığı uzatır. İkisi de 60 olduklarını iddia eder ve çözümlenen kareleri oynatma hızında işler.
Üçüncü uzamsal aşama. Bunu birleştirin; dördüncü bir boru hattı yoktur. sadece videoyu uzamsal olarak örnekleme artırın, RGB'de taşıma ana karelerini yeniden oluşturun (decode → Lanczos ×2 → encode yoluyla rebuild_epilogue_keyframes(); epilog ana karelerini asla latent olarak örnekleme artırmayın), ardından:
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()
İki eksen farklı biçimde dikişlenir. Uzamsal bir sınırın ne tarafında bilinen bir cevap bulunduğundan, bu örtüşmeler trapezoidal ağırlıklarla birleştirilir. Zamanla ilgili karolar, son rafine etme turunun ana kare dikişlerinde kesilir.
Diffusion decoder ile çözümleme. Maksimum detay sadakati için output_type="latent" üzerinde kalın ve (zaten normalizasyonu kaldırılmış, muhtemelen trim_canvas uygulanmış) latentleri LTX2VideoDiffusionDecodePipeline'e iletin.
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[[diffusers.LTX2Pipeline]]
diffusers.LTX2Pipeline[[diffusers.LTX2Pipeline]]
diffusers.LTX2Pipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)
Parametreler:
transformer (LTXVideoTransformer3DModel) : Kodlanmış video latentlerini gürültüden arındırmak için kullanılan koşullu Transformer mimarisi.
scheduler (FlowMatchEulerDiscreteScheduler) : Kodlanmış görüntü latentlerini gürültüden arındırmak için transformer ile birlikte kullanılacak bir zamanlayıcı.
vae (AutoencoderKLLTXVideo) : Görüntüleri latent temsillere kodlamak ve latent temsillerden görüntülere çözmek için kullanılan Varyasyonel Oto-Kodlayıcı (VAE) Modeli.
text_encoder (T5EncoderModel) : T5, özellikle google/t5-v1_1-xxl varyantı.
tokenizer (CLIPTokenizer) : CLIPTokenizer sınıfının tokenizer'ı.
tokenizer (T5TokenizerFast) : T5TokenizerFast sınıfının ikinci Tokenizer'ı.
connectors (LTX2TextConnectors) : Video ve ses dalları için metin kodlayıcı gizli durumlarını uyarlamakta kullanılan metin konnektör yığını.
Metinden videoya üretim için Pipeline.
Referans: https://github.com/Lightricks/LTX-Video
call[[diffusers.LTX2Pipeline.call]]
__call__(prompt: str | list[str] = None, negative_prompt: str | list[str] | None = None, height: int = 512, width: int = 768, num_frames: int | None = None, min_seconds: float = 1.0, max_seconds: float = 20.0, frame_rate: float = 24.0, motion_speed: float = 1.0, num_inference_steps: int = 30, sigmas: list[float] | None = None, timesteps: list = None, guidance_scale: float = 3.0, stg_scale: float = 1.0, modality_scale: float = 3.0, guidance_rescale: float = 0.7, audio_guidance_scale: float | None = 7.0, audio_stg_scale: float | None = 1.0, audio_modality_scale: float | None = 3.0, audio_guidance_rescale: float | None = 0.7, spatio_temporal_guidance_blocks: list[int] | None = [28], noise_scale: float = 0.0, num_videos_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 1024)
Parametreler:
prompt (str veya list[str], isteğe bağlı) : Görsel üretimi yönlendirmek için istem veya istemler. Tanımlanmamışsa, bunun yerine prompt_embeds geçirilmelidir.
negative_prompt (str veya list[str], isteğe bağlı) : Görsel üretimi yönlendirmemek için kullanılan istem veya istemler. Tanımlanmamışsa bunun yerine negative_prompt_embeds parametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (guidance_scale < 1) yok sayılır.
height (int, isteğe bağlı, varsayılan 512) : Üretilen görüntünün piksel cinsinden yüksekliği. En iyi sonuçlar için bu değer varsayılan olarak 480 olarak ayarlanır.
width (int, isteğe bağlı, varsayılan 768) : Üretilen görüntünün piksel cinsinden genişliği. En iyi sonuçlar için bu değer varsayılan olarak 848 olarak ayarlanır.
num_frames (int, isteğe bağlı) : Üretilecek video kare sayısı. Belirtilmezse, bu hattın duration_head bileşeni varsa (LTX-2.5 kontrol noktaları ve sonrası) otomatik tahmin edilen bir süreye, aksi halde 121 değerine ayarlanır. Uzunluğu açıkça belirlemek için bir tamsayı geçin. Otomatik tahmin edilen sayılar, VAE'nin nedensel zaman ızgarasına oturtulduğundan, gerçekleşen süre kuantize edilir (24 fps'de yaklaşık 0,33 sn).
min_seconds (float, opsiyonel, varsayılan 1.0) : num_frames atlandığında ve bir duration_head mevcut olduğunda, otomatik tahmin edilen sürenin alt sınırı. num_frames açıkça ayarlandığında yok sayılır.
max_seconds (float, opsiyonel, varsayılan 20.0) : num_frames atlandığında ve bir duration_head mevcut olduğunda, otomatik tahmin edilen sürenin üst sınırı. num_frames açıkça ayarlandığında yok sayılır. min_seconds değerinden kesinlikle büyük olmalıdır.
frame_rate (float, isteğe bağlı, varsayılan 24.0) : Üretilen videonun saniyede kare (FPS) sayısı.
motion_speed (float, isteğe bağlı, varsayılan 1.0) : Gerçek zamana göre hareket hızı. Konumsal gömlemeler frame_rate / motion_speed değerine göre koşullandırılır, bu nedenle 1'in altındaki değerler hareketi yavaşlatır; örneğin Slow-Motion-Control LoRA'sının 5x yavaş hareketi için 0.2. frame_rate oynatma hızı olarak kalır: ses süresi ve tahmini kare sayısı buna göre belirlenir.
num_inference_steps (int, isteğe bağlı, varsayılan 30) : Gürültü azaltma adım sayısı. Daha fazla gürültü azaltma adımı genellikle daha yavaş çıkarım pahasına daha yüksek kaliteli bir görüntüye yol açar.
sigmas (List[float], isteğe bağlı) : set_timesteps metodunda sigmas argümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel sigmalar. Tanımlanmamışsa, num_inference_steps geçirildiğinde varsayılan davranış kullanılacaktır.
timesteps (list[int], isteğe bağlı) : set_timesteps metodunda timesteps argümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel zaman adımları. Tanımlanmamışsa, num_inference_steps geçirildiğinde varsayılan davranış kullanılacaktır. Azalan sırada olmalıdır.
guidance_scale (float, isteğe bağlı, varsayılan 4.0) : Classifier-Free Diffusion Guidance'de tanımlanan yönlendirme ölçeği. guidance_scale, Imagen Paper'daki 2. denklemindeki w olarak tanımlanır. Yönlendirme ölçeği, guidance_scale > 1 olarak ayarlanarak etkinleştirilir. Daha yüksek yönlendirme ölçeği, genellikle daha düşük görüntü kalitesi pahasına, prompt ile yakından ilişkili görüntülerin üretilmesini teşvik eder. Video modu için kullanılır (ses modu için ayrı bir audio_guidance_scale değeri vardır).
stg_scale (float, opsiyonel, varsayılan 0.0) : Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling makalesinde önerilen Spatio-Temporal Guidance (STG) için video yönlendirme ölçeği. STG, gürültü giderme modelinin bozulmuş bir versiyonundan gelen zayıf bir örnekten örnekleri uzaklaştıran CFG benzeri bir tahmin kullanır. STG'nin etkinleştirilmesi, ek bir gürültü giderme model ileri geçişine neden olur; 0.0 varsayılan değeri, STG'nin devre dışı bırakıldığını ifade eder.
modality_scale (float, opsiyonel, varsayılan 1.0) : LTX-2.X modallite izolasyonu yönlendirmesi için video yönlendirme ölçeği. Bu yöntemde, çapraz modallite (sesten videoya ve videodan sese) çapraz dikkati devre dışı bırakılarak gürültü giderme modeli tarafından üretilen daha zayıf bir örnekten, CFG benzeri bir tahmin kullanılarak örneği uzaklaştırırız. Modallite yönlendirmesini etkinleştirmek, ek bir gürültü giderme modeli ileri geçişine neden olur; 1.0 varsayılan değeri, modallite yönlendirmesinin devre dışı olduğunu ifade eder.
guidance_rescale (float, isteğe bağlı, varsayılan 0.0) : Common Diffusion Noise Schedules and Sample Steps are Flawed makalesinde önerilen guidance rescale faktörü. guidance_scale, Common Diffusion Noise Schedules and Sample Steps are Flawed makalesindeki 16. denklemde φ olarak tanımlanmıştır. Guidance rescale faktörü, sıfır terminal SNR kullanıldığında aşırı pozlamayı düzeltmelidir. Video modalitesi için kullanılır.
audio_guidance_scale (float, isteğe bağlı, varsayılan None) : Negatif istem açısından CFG için ses yönlendirme ölçeği. CFG güncelleme kuralı video ve ses için aynıdır, ancak yönlendirme ölçeği için farklı değerler kullanılabilir. LTX-2.X yazarları, audio_guidance_scale'ın video guidance_scale'ına göre daha yüksek olması gerektiğini önermektedir (ör. LTX-2.3 için video için 3.0, ses için 7.0 önerilmektedir). None ise, video değeri olan guidance_scale varsayılan olarak kullanılır.
audio_stg_scale (float, isteğe bağlı, varsayılan None) : STG için ses yönlendirme ölçeği. CFG'de olduğu gibi, STG güncelleme kuralı video ve ses için aksi belirtilmedikçe aynıdır. LTX-2.3 için hem video hem de ses için 1.0 değeri önerilir. None ise, video değeri olan stg_scale varsayılan olarak kullanılır.
audio_modality_scale (float, opsiyonel, varsayılan None) : LTX-2.X modallite izolasyonu yönlendirmesi için ses yönlendirme ölçeği. CFG'de olduğu gibi, modallite yönlendirme kuralı video ve ses için aksi belirtilmedikçe aynıdır. LTX-2.3 için hem video hem de ses için 3.0 değeri önerilir. None ise, video değeri olan modality_scale varsayılan olarak kullanılır.
audio_guidance_rescale (float, isteğe bağlı, varsayılan None) : Ses modallitesi için ayrı bir yönlendirme yeniden ölçeklendirme faktörü. None ise, varsayılan olarak video değeri olan guidance_rescale kullanılır.
spatio_temporal_guidance_blocks (list[int], isteğe bağlı, varsayılan None) : STG'nin uygulanacağı, sıfır tabanlı dönüştürücü blok dizinleri. STG kullanılıyorsa (stg_scale veya audio_stg_scale 0'dan büyükse) sağlanmalıdır. LTX-2.0 için [29] değeri, LTX-2.3 için ise [28] değeri önerilir.
noise_scale (float, opsiyonel, varsayılan 0.0) : Her zaman adımında rastgele gürültü ile gürültüsü azaltılmış latentler arasındaki interpolasyon katsayısı. Gürültü azaltma işlemine devam etmeden önce latents ve audio_latents değerlerine gürültü uygulanır.
num_videos_per_prompt (int, isteğe bağlı, varsayılan 1) : Her istem için üretilecek video sayısı.
generator (torch.Generator veya list[torch.Generator], isteğe bağlı) : Üretimi deterministik hale getirmek için bir veya torch üreteci(leri) listesi.
latents (torch.Tensor, isteğe bağlı) : Video üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenen önceden oluşturulmuş gürültülü latentler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklem yoluyla bir latent tensörü oluşturulur.
audio_latents (torch.Tensor, isteğe bağlı) : Ses üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenen önceden oluşturulmuş gürültülü latentler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklem yoluyla bir latent tensörü oluşturulur.
prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.
prompt_attention_mask (torch.Tensor, isteğe bağlı) : Metin gömme (embedding) için önceden oluşturulmuş dikkat maskesi (attention mask).
negative_prompt_embeds (torch.FloatTensor, isteğe bağlı) : Önceden oluşturulmuş negatif metin gömme değerleri. PixArt-Sigma için bu negatif istem "" olmalıdır. Sağlanmazsa, negative_prompt_embeds, negative_prompt girdi argümanından oluşturulur.
negative_prompt_attention_mask (torch.FloatTensor, isteğe bağlı) : Negatif metin gömme vektörleri için önceden oluşturulmuş dikkat maskesi.
decode_timestep (float, varsayılan 0.0) : Üretilen videonun çözümlendiği zaman adımı.
decode_noise_scale (float, varsayılan None) : Çözme zaman adımında rastgele gürültü ile gürültüsü azaltılmış latentler arasındaki interpolasyon katsayısı.
use_cross_timestep (bool opsiyonel, varsayılan True) : Çapraz dikkat modülasyon parametrelerini hesaplanırken çapraz modalite (video için çapraz modalite ses, ve bunun tersi) sigma'sının kullanılıp kullanılmayacağı. True LTX-2.3/2.5 davranışıdır; False ise eski LTX-2.0 davranışıdır.
system_prompt (str, isteğe bağlı, varsayılan None) : Prompt iyileştirme için kullanılacak isteğe bağlı sistem promptu. Sistem promptu, prompt iyileştirici tarafından (bir Gemma koşullu üretim modeli -- yapılandırılmışsa özel prompt_enhancer bileşeni, değilse ana text_encoder) orijinal prompt'tan koşullu üretim için iyileştirilmiş bir prompt üretmek üzere kullanılır. Sağlanmazsa ve özel bir prompt_enhancer yapılandırılmışsa (LTX-2.5), varsayılan olarak LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT (kaynağı diffusers.pipelines.ltx2.utils) kullanılır -- bkz. enable_prompt_enhancement.
enable_prompt_enhancement (bool, isteğe bağlı, varsayılan False) : İstem güçlendirmesinin çalıştırılıp çalıştırılmayacağını belirtir. Lightricks referans boru hatlarıyla uyumlu olacak şekilde isteğe bağlıdır. True olduğunda ve system_prompt atlandığında, özel bir prompt_enhancer yapılandırılmışsa LTX-2.5 LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT kullanır; LTX-2.0/2.3 için açık bir system_prompt gereklidir.
prompt_max_new_tokens (int, isteğe bağlı, varsayılan None) : İstem güçlendirme (prompt enhancement) sırasında oluşturulacak en fazla yeni jeton sayısı. Belirtilmezse, LTX-2.5 için ayrılmış Gemma 4 prompt_enhancer durumunda 600, LTX-2.0/2.3 için Gemma 3 text_encoder yedeği durumunda 512 kullanılır.
prompt_enhancement_kwargs (dict[str, Any], isteğe bağlı, varsayılan None) : Prompt geliştiricisinin .generate çağrısı için anahtar kelime argümanları. Verilmezse, her zaman geliştirmeyi yapan modelle eşleşir: özel bir prompt_enhancer (LTX-2.5) kullanıldığında do_sample=False, no_repeat_ngram_size=5 (açgözlü) veya text_encoder yedeği (LTX-2.0/2.3) için do_sample=True, temperature=0.7. Daha fazla ayrıntı için https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate adresine bakın.
prompt_enhancement_seed (int, isteğe bağlı, varsayılan 10) : İstem geliştirme sırasında herhangi bir rastgele işlem için rastgele tohum.
output_type (str, isteğe bağlı, varsayılan "pil") : Üretilen görüntünün çıktı biçimi. PIL: PIL.Image.Image veya np.array arasında seçim yapın.
return_dict (bool, isteğe bağlı, varsayılan True) : Düz bir tuple yerine ~pipelines.ltx.LTX2PipelineOutput döndürülecek mi?
attention_kwargs (dict, isteğe bağlı) : Belirtilirse, diffusers.models.attention_processor içinde self.processor altında tanımlanan AttentionProcessor'a iletilen bir kwargs sözlüğü.
callback_on_step_end (Callable, isteğe bağlı) : Çıkarım sırasında her gürültü azaltma adımının sonunda çağrılan bir işlev. İşlev aşağıdaki argümanlarla çağrılır: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs, callback_on_step_end_tensor_inputs tarafından belirtilen tüm tensörlerin listesini içerir.
callback_on_step_end_tensor_inputs (List, optional, defaults to ["latents"]) : The list of tensor inputs for the callback_on_step_end function. The tensors specified in the list will be passed as callback_kwargs argument. You will only be able to include variables listed in the ._callback_tensor_inputs attribute of your pipeline class.
max_sequence_length (int, isteğe bağlı, varsayılan 1024) : prompt ile kullanılacak maksimum dizi uzunluğu.
Dönüş: ~pipelines.ltx.LTX2PipelineOutput veya tuple
return_dict True ise ~pipelines.ltx.LTX2PipelineOutput döndürülür, aksi halde ilk öğesi üretilen görüntülerin listesini içeren bir tuple döndürülür.
Üretim için pipeline çağrıldığında tetiklenen işlev.
Örnekler:
>>> 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[[diffusers.LTX2Pipeline.encode_prompt]]
encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, scale_factor: int = 8, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
Parametreler:
prompt (str veya list[str], isteğe bağlı) : kodlanacak istem
negative_prompt (str veya list[str], isteğe bağlı) : Görsel üretimi yönlendirmemek için kullanılan istem veya istemler. Tanımlanmazsa, bunun yerine negative_prompt_embeds parametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (yani guidance_scale değeri 1'den küçükse) yok sayılır.
do_classifier_free_guidance (bool, isteğe bağlı, varsayılan True) : Sınıflandırıcı serbest yönlendirmenin (classifier free guidance) kullanılıp kullanılmayacağı.
num_videos_per_prompt (int, opsiyonel, varsayılan 1) : Her istem için oluşturulması gereken video sayısı. Sonuç gömme vektörlerinin yerleştirileceği torch cihazı
prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.
negative_prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş negatif metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, negative_prompt_embeds, negative_prompt girdi argümanından oluşturulur.
device : (torch.device, isteğe bağlı): torch cihazı
dtype : (torch.dtype, isteğe bağlı): torch dtype
İsteği metin kodlayıcı gizli durumlarına kodlar.
enhance_prompt[[diffusers.LTX2Pipeline.enhance_prompt]]
enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)
Sağlanan prompt değerini, prompt geliştiriciden (bir Gemma koşullu üretim modeli) ve bir sistem promptundan yararlanarak yeni bir prompt üreterek geliştirir. image sağlandığında, geliştirici bu referans kareye de (I2V / anahtar kare tarzı geliştirme) koşullandırılır. Yapılandırılmışsa (ör. metin kodlayıcısı geliştirme için eğitilmemiş olan LTX-2.5) özel prompt_enhancer bileşeni kullanılır, aksi takdirde ana text_encoder (kendi geliştiricileri olarak da görev yapan LTX-2.0/2.3) kullanılır.
Mesaj şablonları, çözümleme kwargs'ları, yanıt temizleme ve görüntü uzun kenar hazırlığı ltx-core / ltx-pipelines ile eşleşir (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ImageToVideoPipeline[[diffusers.LTX2ImageToVideoPipeline]]
diffusers.LTX2ImageToVideoPipeline[[diffusers.LTX2ImageToVideoPipeline]]
diffusers.LTX2ImageToVideoPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)
Görselden video üretimi için pipeline.
Referans: https://github.com/Lightricks/LTX-Video
TODO
call[[diffusers.LTX2ImageToVideoPipeline.call]]
__call__(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, prompt: str | list[str] = None, negative_prompt: str | list[str] | None = None, height: int = 512, width: int = 768, num_frames: int | None = None, min_seconds: float = 1.0, max_seconds: float = 20.0, frame_rate: float = 24.0, motion_speed: float = 1.0, num_inference_steps: int = 30, sigmas: list[float] | None = None, timesteps: list[int] | None = None, guidance_scale: float = 3.0, stg_scale: float = 1.0, modality_scale: float = 3.0, guidance_rescale: float = 0.7, audio_guidance_scale: float | None = 7.0, audio_stg_scale: float | None = 1.0, audio_modality_scale: float | None = 3.0, audio_guidance_rescale: float | None = 0.7, spatio_temporal_guidance_blocks: list[int] | None = [28], noise_scale: float = 0.0, num_videos_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, image_crf: int | None = None, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 1024)
Parametreler:
image (PipelineImageInput) : Üretimi koşullandırmak için girdi olarak kullanılan görüntü. Bir görüntü, görüntü listesi veya torch.Tensor olmalıdır.
prompt (str veya list[str], isteğe bağlı) : Görsel üretimi yönlendirmek için istem veya istemler. Tanımlanmamışsa, bunun yerine prompt_embeds geçirilmelidir.
negative_prompt (str veya list[str], isteğe bağlı) : Görsel üretimi yönlendirmemek için kullanılan istem veya istemler. Tanımlanmamışsa bunun yerine negative_prompt_embeds parametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (guidance_scale < 1) yok sayılır.
height (int, isteğe bağlı, varsayılan 512) : Üretilen görüntünün piksel cinsinden yüksekliği. En iyi sonuçlar için bu değer varsayılan olarak 480 olarak ayarlanır.
width (int, isteğe bağlı, varsayılan 768) : Üretilen görüntünün piksel cinsinden genişliği. En iyi sonuçlar için bu değer varsayılan olarak 848 olarak ayarlanır.
num_frames (int, isteğe bağlı) : Üretilecek video kare sayısı. Belirtilmezse, bu hattın duration_head bileşeni varsa (LTX-2.5 kontrol noktaları ve sonrası) otomatik tahmin edilen bir süreye, aksi halde 121 değerine ayarlanır. Uzunluğu açıkça belirlemek için bir tamsayı geçin. Otomatik tahmin edilen sayılar, VAE'nin nedensel zaman ızgarasına oturtulduğundan, gerçekleşen süre kuantize edilir (24 fps'de yaklaşık 0,33 sn).
min_seconds (float, opsiyonel, varsayılan 1.0) : num_frames atlandığında ve bir duration_head mevcut olduğunda, otomatik tahmin edilen sürenin alt sınırı. num_frames açıkça ayarlandığında yok sayılır.
max_seconds (float, opsiyonel, varsayılan 20.0) : num_frames atlandığında ve bir duration_head mevcut olduğunda, otomatik tahmin edilen sürenin üst sınırı. num_frames açıkça ayarlandığında yok sayılır. min_seconds değerinden kesinlikle büyük olmalıdır.
frame_rate (float, isteğe bağlı, varsayılan 24.0) : Üretilen videonun saniyede kare (FPS) sayısı.
motion_speed (float, isteğe bağlı, varsayılan 1.0) : Gerçek zamana göre hareket hızı. Konumsal gömlemeler frame_rate / motion_speed değerine göre koşullandırılır, bu nedenle 1'in altındaki değerler hareketi yavaşlatır; örneğin Slow-Motion-Control LoRA'sının 5x yavaş hareketi için 0.2. frame_rate oynatma hızı olarak kalır: ses süresi ve tahmini kare sayısı buna göre belirlenir.
num_inference_steps (int, isteğe bağlı, varsayılan 30) : Gürültü azaltma adım sayısı. Daha fazla gürültü azaltma adımı genellikle daha yavaş çıkarım pahasına daha yüksek kaliteli bir görüntüye yol açar.
sigmas (List[float], isteğe bağlı) : set_timesteps metodunda sigmas argümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel sigmalar. Tanımlanmamışsa, num_inference_steps geçirildiğinde varsayılan davranış kullanılacaktır.
timesteps (List[int], isteğe bağlı) : set_timesteps metodunda timesteps argümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel zaman adımları. Tanımlanmamışsa, num_inference_steps geçirildiğinde varsayılan davranış kullanılacaktır. Azalan sırada olmalıdır.
guidance_scale (float, isteğe bağlı, varsayılan 4.0) : Classifier-Free Diffusion Guidance'de tanımlanan yönlendirme ölçeği. guidance_scale, Imagen Paper'daki 2. denklemindeki w olarak tanımlanır. Yönlendirme ölçeği, guidance_scale > 1 olarak ayarlanarak etkinleştirilir. Daha yüksek yönlendirme ölçeği, genellikle daha düşük görüntü kalitesi pahasına, prompt ile yakından ilişkili görüntülerin üretilmesini teşvik eder. Video modu için kullanılır (ses modu için ayrı bir audio_guidance_scale değeri vardır).
stg_scale (float, opsiyonel, varsayılan 0.0) : Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling makalesinde önerilen Spatio-Temporal Guidance (STG) için video yönlendirme ölçeği. STG, gürültü giderme modelinin bozulmuş bir versiyonundan gelen zayıf bir örnekten örnekleri uzaklaştıran CFG benzeri bir tahmin kullanır. STG'nin etkinleştirilmesi, ek bir gürültü giderme model ileri geçişine neden olur; 0.0 varsayılan değeri, STG'nin devre dışı bırakıldığını ifade eder.
modality_scale (float, opsiyonel, varsayılan 1.0) : LTX-2.X modallite izolasyonu yönlendirmesi için video yönlendirme ölçeği. Bu yöntemde, çapraz modallite (sesten videoya ve videodan sese) çapraz dikkati devre dışı bırakılarak gürültü giderme modeli tarafından üretilen daha zayıf bir örnekten, CFG benzeri bir tahmin kullanılarak örneği uzaklaştırırız. Modallite yönlendirmesini etkinleştirmek, ek bir gürültü giderme modeli ileri geçişine neden olur; 1.0 varsayılan değeri, modallite yönlendirmesinin devre dışı olduğunu ifade eder.
guidance_rescale (float, isteğe bağlı, varsayılan 0.0) : Common Diffusion Noise Schedules and Sample Steps are Flawed makalesinde önerilen guidance rescale faktörü. guidance_scale, Common Diffusion Noise Schedules and Sample Steps are Flawed makalesindeki 16. denklemde φ olarak tanımlanmıştır. Guidance rescale faktörü, sıfır terminal SNR kullanıldığında aşırı pozlamayı düzeltmelidir. Video modalitesi için kullanılır.
audio_guidance_scale (float, isteğe bağlı, varsayılan None) : Negatif istem açısından CFG için ses yönlendirme ölçeği. CFG güncelleme kuralı video ve ses için aynıdır, ancak yönlendirme ölçeği için farklı değerler kullanılabilir. LTX-2.X yazarları, audio_guidance_scale'ın video guidance_scale'ına göre daha yüksek olması gerektiğini önermektedir (ör. LTX-2.3 için video için 3.0, ses için 7.0 önerilmektedir). None ise, video değeri olan guidance_scale varsayılan olarak kullanılır.
audio_stg_scale (float, isteğe bağlı, varsayılan None) : STG için ses yönlendirme ölçeği. CFG'de olduğu gibi, STG güncelleme kuralı video ve ses için aksi belirtilmedikçe aynıdır. LTX-2.3 için hem video hem de ses için 1.0 değeri önerilir. None ise, video değeri olan stg_scale varsayılan olarak kullanılır.
audio_modality_scale (float, opsiyonel, varsayılan None) : LTX-2.X modallite izolasyonu yönlendirmesi için ses yönlendirme ölçeği. CFG'de olduğu gibi, modallite yönlendirme kuralı video ve ses için aksi belirtilmedikçe aynıdır. LTX-2.3 için hem video hem de ses için 3.0 değeri önerilir. None ise, video değeri olan modality_scale varsayılan olarak kullanılır.
audio_guidance_rescale (float, isteğe bağlı, varsayılan None) : Ses modallitesi için ayrı bir yönlendirme yeniden ölçeklendirme faktörü. None ise, varsayılan olarak video değeri olan guidance_rescale kullanılır.
spatio_temporal_guidance_blocks (list[int], isteğe bağlı, varsayılan None) : STG'nin uygulanacağı, sıfır tabanlı dönüştürücü blok dizinleri. STG kullanılıyorsa (stg_scale veya audio_stg_scale 0'dan büyükse) sağlanmalıdır. LTX-2.0 için [29] değeri, LTX-2.3 için ise [28] değeri önerilir.
noise_scale (float, opsiyonel, varsayılan 0.0) : Her zaman adımında rastgele gürültü ile gürültüsü azaltılmış latentler arasındaki interpolasyon katsayısı. Gürültü azaltma işlemine devam etmeden önce latents ve audio_latents değerlerine gürültü uygulanır.
num_videos_per_prompt (int, isteğe bağlı, varsayılan 1) : Her istem için üretilecek video sayısı.
generator (torch.Generator veya list[torch.Generator], isteğe bağlı) : Üretimi deterministik hale getirmek için bir veya torch üreteci(leri) listesi.
latents (torch.Tensor, isteğe bağlı) : Video üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenen önceden oluşturulmuş gürültülü latentler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklem yoluyla bir latent tensörü oluşturulur.
audio_latents (torch.Tensor, isteğe bağlı) : Ses üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenen önceden oluşturulmuş gürültülü latentler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklem yoluyla bir latent tensörü oluşturulur.
prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.
prompt_attention_mask (torch.Tensor, isteğe bağlı) : Metin gömme (embedding) için önceden oluşturulmuş dikkat maskesi (attention mask).
negative_prompt_embeds (torch.FloatTensor, isteğe bağlı) : Önceden oluşturulmuş negatif metin gömme değerleri. PixArt-Sigma için bu negatif istem "" olmalıdır. Sağlanmazsa, negative_prompt_embeds, negative_prompt girdi argümanından oluşturulur.
negative_prompt_attention_mask (torch.FloatTensor, isteğe bağlı) : Negatif metin gömme vektörleri için önceden oluşturulmuş dikkat maskesi.
decode_timestep (float, varsayılan 0.0) : Üretilen videonun çözümlendiği zaman adımı.
decode_noise_scale (float, varsayılan None) : Çözme zaman adımında rastgele gürültü ile gürültüsü azaltılmış latentler arasındaki interpolasyon katsayısı.
use_cross_timestep (bool opsiyonel, varsayılan True) : Çapraz dikkat modülasyon parametrelerini hesaplanırken çapraz modalite (video için çapraz modalite ses, ve bunun tersi) sigma'sının kullanılıp kullanılmayacağı. True LTX-2.3/2.5 davranışıdır; False ise eski LTX-2.0 davranışıdır.
system_prompt (str, isteğe bağlı, varsayılan None) : İsteğin iyileştirilmesi için kullanılacak isteğe bağlı sistem istemi. Sistem istemi, orijinal prompt ve koşullu üretimi belirlemek için ilk image kullanılarak iyileştirilmiş bir istem üretmek için istem iyileştirici tarafından (bir Gemma koşullu üretim modeli -- yapılandırılmışsa özel prompt_enhancer bileşeni, değilse ana text_encoder) kullanılacaktır. Sağlanmazsa ve özel bir prompt_enhancer yapılandırılmışsa (LTX-2.5), varsayılan olarak LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT ( diffusers.pipelines.ltx2.utils içinden ) kullanılır -- bkz. enable_prompt_enhancement.
enable_prompt_enhancement (bool, isteğe bağlı, varsayılan False) : İstem güçlendirmesinin çalıştırılıp çalıştırılmayacağını belirtir. Lightricks referans boru hatlarıyla uyumlu olacak şekilde isteğe bağlıdır. True olduğunda ve system_prompt atlandığında, özel bir prompt_enhancer yapılandırılmışsa LTX-2.5 LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT kullanır; LTX-2.0/2.3 için açık bir system_prompt gereklidir.
prompt_max_new_tokens (int, isteğe bağlı, varsayılan None) : İstem güçlendirme (prompt enhancement) sırasında oluşturulacak en fazla yeni jeton sayısı. Belirtilmezse, LTX-2.5 için ayrılmış Gemma 4 prompt_enhancer durumunda 600, LTX-2.0/2.3 için Gemma 3 text_encoder yedeği durumunda 512 kullanılır.
prompt_enhancement_kwargs (dict[str, Any], isteğe bağlı, varsayılan None) : Prompt geliştiricisinin .generate çağrısı için anahtar kelime argümanları. Verilmezse, her zaman geliştirmeyi yapan modelle eşleşir: özel bir prompt_enhancer (LTX-2.5) kullanıldığında do_sample=False, no_repeat_ngram_size=3 (açgözlü) veya text_encoder yedeği (LTX-2.0/2.3) için do_sample=True, temperature=0.7. Daha fazla ayrıntı için https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate adresine bakın.
prompt_enhancement_seed (int, isteğe bağlı, varsayılan 10) : İstem geliştirme sırasında herhangi bir rastgele işlem için rastgele tohum.
image_crf (int, isteğe bağlı, varsayılan None) : VAE kodlamadan önce koşullandırma image'ının yeniden sıkıştırılmasında kullanılan ve modelin eğitim sırasında karşılaştığı sıkıştırmayla eşleşen H.264 CRF değeri. None, "model varsayılanını kullan" anlamına gelir (LTX-2.3'e kadar 33, LTX-2.5 için 18). Yeniden sıkıştırmayı atlamak için 0 geçirin. Yeniden sıkıştırma çalıştığında PIL.Image.Image gerektirir.
output_type (str, isteğe bağlı, varsayılan "pil") : Üretilen görüntünün çıktı biçimi. PIL: PIL.Image.Image veya np.array arasında seçim yapın.
return_dict (bool, isteğe bağlı, varsayılan True) : Düz bir tuple yerine ~pipelines.ltx.LTX2PipelineOutput döndürülecek mi?
attention_kwargs (dict, isteğe bağlı) : Belirtilirse, diffusers.models.attention_processor içinde self.processor altında tanımlanan AttentionProcessor'a iletilen bir kwargs sözlüğü.
callback_on_step_end (Callable, isteğe bağlı) : Çıkarım sırasında her gürültü azaltma adımının sonunda çağrılan bir işlev. İşlev aşağıdaki argümanlarla çağrılır: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs, callback_on_step_end_tensor_inputs tarafından belirtilen tüm tensörlerin listesini içerir.
callback_on_step_end_tensor_inputs (List, optional) : The list of tensor inputs for the callback_on_step_end function. The tensors specified in the list will be passed as callback_kwargs argument. You will only be able to include variables listed in the ._callback_tensor_inputs attribute of your pipeline class.
max_sequence_length (int, isteğe bağlı, varsayılan 1024) : prompt ile kullanılacak maksimum dizi uzunluğu.
Dönüş: ~pipelines.ltx.LTX2PipelineOutput veya tuple
return_dict True ise ~pipelines.ltx.LTX2PipelineOutput döndürülür, aksi halde ilk öğesi üretilen görüntülerin listesini içeren bir tuple döndürülür.
Üretim için pipeline çağrıldığında tetiklenen işlev.
Örnekler:
>>> 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[[diffusers.LTX2ImageToVideoPipeline.encode_prompt]]
encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, scale_factor: int = 8, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
Parametreler:
prompt (str veya list[str], isteğe bağlı) : kodlanacak istem
negative_prompt (str veya list[str], isteğe bağlı) : Görsel üretimi yönlendirmemek için kullanılan istem veya istemler. Tanımlanmazsa, bunun yerine negative_prompt_embeds parametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (yani guidance_scale değeri 1'den küçükse) yok sayılır.
do_classifier_free_guidance (bool, isteğe bağlı, varsayılan True) : Sınıflandırıcı serbest yönlendirmenin (classifier free guidance) kullanılıp kullanılmayacağı.
num_videos_per_prompt (int, opsiyonel, varsayılan 1) : Her istem için oluşturulması gereken video sayısı. Sonuç gömme vektörlerinin yerleştirileceği torch cihazı
prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.
negative_prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş negatif metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, negative_prompt_embeds, negative_prompt girdi argümanından oluşturulur.
device : (torch.device, isteğe bağlı): torch cihazı
dtype : (torch.dtype, isteğe bağlı): torch dtype
İsteği metin kodlayıcı gizli durumlarına kodlar.
enhance_prompt[[diffusers.LTX2ImageToVideoPipeline.enhance_prompt]]
enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)
Sağlanan prompt değerini, prompt geliştiriciden (bir Gemma koşullu üretim modeli) ve bir sistem promptundan yararlanarak yeni bir prompt üreterek geliştirir. image sağlandığında, geliştirici bu referans kareye de (I2V / anahtar kare tarzı geliştirme) koşullandırılır. Yapılandırılmışsa (ör. metin kodlayıcısı geliştirme için eğitilmemiş olan LTX-2.5) özel prompt_enhancer bileşeni kullanılır, aksi takdirde ana text_encoder (kendi geliştiricileri olarak da görev yapan LTX-2.0/2.3) kullanılır.
Mesaj şablonları, çözümleme kwargs'ları, yanıt temizleme ve görüntü uzun kenar hazırlığı ltx-core / ltx-pipelines ile eşleşir (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ConditionPipeline[[diffusers.LTX2ConditionPipeline]]
diffusers.LTX2ConditionPipeline[[diffusers.LTX2ConditionPipeline]]
diffusers.LTX2ConditionPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, audio_scheduler: diffusers.schedulers.scheduling_flow_match_euler_discrete.FlowMatchEulerDiscreteScheduler | None = None, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)
Görsel koşulların videonun keyfi kısımlarına yerleştirilmesine izin veren video üretimi için pipeline.
Referans: https://github.com/Lightricks/LTX-Video
TODO
call[[diffusers.LTX2ConditionPipeline.call]]
__call__(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, prompt: str | list[str] = None, negative_prompt: str | list[str] | None = None, height: int = 512, width: int = 768, num_frames: int | None = None, min_seconds: float = 1.0, max_seconds: float = 20.0, frame_rate: float = 24.0, motion_speed: float = 1.0, num_inference_steps: int = 30, sigmas: list[float] | None = None, timesteps: list[float] | None = None, guidance_scale: float = 3.0, stg_scale: float = 1.0, modality_scale: float = 3.0, guidance_rescale: float = 0.7, audio_guidance_scale: float | None = 7.0, audio_stg_scale: float | None = 1.0, audio_modality_scale: float | None = 3.0, audio_guidance_rescale: float | None = 0.7, spatio_temporal_guidance_blocks: list[int] | None = [28], noise_scale: float | None = None, num_videos_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 1024)
Parametreler:
conditions (List[LTXVideoCondition], *optional*) : Video üretimi için çerçeve koşullandırma öğelerinin listesi.
prompt (str veya List[str], isteğe bağlı) : Görsel üretimi yönlendirmek için istem veya istemler. Tanımlanmamışsa, bunun yerine prompt_embeds geçirilmelidir.
negative_prompt (str veya List[str], isteğe bağlı) : Görsel üretimi yönlendirmemek için kullanılan istem veya istemler. Tanımlanmamışsa bunun yerine negative_prompt_embeds parametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (guidance_scale < 1) yok sayılır.
height (int, isteğe bağlı, varsayılan 512) : Üretilen görüntünün piksel cinsinden yüksekliği. En iyi sonuçlar için bu değer varsayılan olarak 480 olarak ayarlanır.
width (int, isteğe bağlı, varsayılan 768) : Üretilen görüntünün piksel cinsinden genişliği. En iyi sonuçlar için bu değer varsayılan olarak 848 olarak ayarlanır.
num_frames (int, isteğe bağlı) : Üretilecek video kare sayısı. Belirtilmezse, bu hattın duration_head bileşeni varsa (LTX-2.5 kontrol noktaları ve sonrası) otomatik tahmin edilen bir süreye, aksi halde 121 değerine ayarlanır. Uzunluğu açıkça belirlemek için bir tamsayı geçin. Otomatik tahmin edilen sayılar, VAE'nin nedensel zaman ızgarasına oturtulduğundan, gerçekleşen süre kuantize edilir (24 fps'de yaklaşık 0,33 sn).
min_seconds (float, opsiyonel, varsayılan 1.0) : num_frames atlandığında ve bir duration_head mevcut olduğunda, otomatik tahmin edilen sürenin alt sınırı. num_frames açıkça ayarlandığında yok sayılır.
max_seconds (float, opsiyonel, varsayılan 20.0) : num_frames atlandığında ve bir duration_head mevcut olduğunda, otomatik tahmin edilen sürenin üst sınırı. num_frames açıkça ayarlandığında yok sayılır. min_seconds değerinden kesinlikle büyük olmalıdır.
frame_rate (float, isteğe bağlı, varsayılan 24.0) : Üretilen videonun saniyede kare (FPS) sayısı.
motion_speed (float, isteğe bağlı, varsayılan 1.0) : Gerçek zamana göre hareket hızı. Konumsal gömlemeler frame_rate / motion_speed değerine göre koşullandırılır, bu nedenle 1'in altındaki değerler hareketi yavaşlatır; örneğin Slow-Motion-Control LoRA'sının 5x yavaş hareketi için 0.2. frame_rate oynatma hızı olarak kalır: ses süresi ve tahmini kare sayısı buna göre belirlenir.
num_inference_steps (int, isteğe bağlı, varsayılan 30) : Gürültü azaltma adım sayısı. Daha fazla gürültü azaltma adımı genellikle daha yavaş çıkarım pahasına daha yüksek kaliteli bir görüntüye yol açar.
sigmas (List[float], isteğe bağlı) : set_timesteps metodunda sigmas argümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel sigmalar. Tanımlanmamışsa, num_inference_steps geçirildiğinde varsayılan davranış kullanılacaktır.
timesteps (List[int], isteğe bağlı) : set_timesteps metodunda timesteps argümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel zaman adımları. Tanımlanmamışsa, num_inference_steps geçirildiğinde varsayılan davranış kullanılacaktır. Azalan sırada olmalıdır.
guidance_scale (float, isteğe bağlı, varsayılan 4.0) : Classifier-Free Diffusion Guidance'de tanımlanan yönlendirme ölçeği. guidance_scale, Imagen Paper'daki 2. denklemindeki w olarak tanımlanır. Yönlendirme ölçeği, guidance_scale > 1 olarak ayarlanarak etkinleştirilir. Daha yüksek yönlendirme ölçeği, genellikle daha düşük görüntü kalitesi pahasına, prompt ile yakından ilişkili görüntülerin üretilmesini teşvik eder. Video modu için kullanılır (ses modu için ayrı bir audio_guidance_scale değeri vardır).
stg_scale (float, opsiyonel, varsayılan 0.0) : Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling makalesinde önerilen Spatio-Temporal Guidance (STG) için video yönlendirme ölçeği. STG, gürültü giderme modelinin bozulmuş bir versiyonundan gelen zayıf bir örnekten örnekleri uzaklaştıran CFG benzeri bir tahmin kullanır. STG'nin etkinleştirilmesi, ek bir gürültü giderme model ileri geçişine neden olur; 0.0 varsayılan değeri, STG'nin devre dışı bırakıldığını ifade eder.
modality_scale (float, opsiyonel, varsayılan 1.0) : LTX-2.X modallite izolasyonu yönlendirmesi için video yönlendirme ölçeği. Bu yöntemde, çapraz modallite (sesten videoya ve videodan sese) çapraz dikkati devre dışı bırakılarak gürültü giderme modeli tarafından üretilen daha zayıf bir örnekten, CFG benzeri bir tahmin kullanılarak örneği uzaklaştırırız. Modallite yönlendirmesini etkinleştirmek, ek bir gürültü giderme modeli ileri geçişine neden olur; 1.0 varsayılan değeri, modallite yönlendirmesinin devre dışı olduğunu ifade eder.
guidance_rescale (float, isteğe bağlı, varsayılan 0.0) : Common Diffusion Noise Schedules and Sample Steps are Flawed makalesinde önerilen guidance rescale faktörü. guidance_scale, Common Diffusion Noise Schedules and Sample Steps are Flawed makalesindeki 16. denklemde φ olarak tanımlanmıştır. Guidance rescale faktörü, sıfır terminal SNR kullanıldığında aşırı pozlamayı düzeltmelidir. Video modalitesi için kullanılır.
audio_guidance_scale (float, isteğe bağlı, varsayılan None) : Negatif istem açısından CFG için ses yönlendirme ölçeği. CFG güncelleme kuralı video ve ses için aynıdır, ancak yönlendirme ölçeği için farklı değerler kullanılabilir. LTX-2.X yazarları, audio_guidance_scale'ın video guidance_scale'ına göre daha yüksek olması gerektiğini önermektedir (ör. LTX-2.3 için video için 3.0, ses için 7.0 önerilmektedir). None ise, video değeri olan guidance_scale varsayılan olarak kullanılır.
audio_stg_scale (float, isteğe bağlı, varsayılan None) : STG için ses yönlendirme ölçeği. CFG'de olduğu gibi, STG güncelleme kuralı video ve ses için aksi belirtilmedikçe aynıdır. LTX-2.3 için hem video hem de ses için 1.0 değeri önerilir. None ise, video değeri olan stg_scale varsayılan olarak kullanılır.
audio_modality_scale (float, opsiyonel, varsayılan None) : LTX-2.X modallite izolasyonu yönlendirmesi için ses yönlendirme ölçeği. CFG'de olduğu gibi, modallite yönlendirme kuralı video ve ses için aksi belirtilmedikçe aynıdır. LTX-2.3 için hem video hem de ses için 3.0 değeri önerilir. None ise, video değeri olan modality_scale varsayılan olarak kullanılır.
audio_guidance_rescale (float, isteğe bağlı, varsayılan None) : Ses modallitesi için ayrı bir yönlendirme yeniden ölçeklendirme faktörü. None ise, varsayılan olarak video değeri olan guidance_rescale kullanılır.
spatio_temporal_guidance_blocks (list[int], isteğe bağlı, varsayılan None) : STG'nin uygulanacağı, sıfır tabanlı dönüştürücü blok dizinleri. STG kullanılıyorsa (stg_scale veya audio_stg_scale 0'dan büyükse) sağlanmalıdır. LTX-2.0 için [29] değeri, LTX-2.3 için ise [28] değeri önerilir.
noise_scale (float, isteğe bağlı, varsayılan None) : Her zaman adımında rastgele gürültü ile gürültüsü azaltılmış latentler arasındaki interpolasyon katsayısı. Gürültü azaltma işlemine devam etmeden önce latents ve audio_latents değerlerine gürültü uygulanır. Ayarlanmazsa, sigma zaman çizelgesinden çıkarılır.
num_videos_per_prompt (int, isteğe bağlı, varsayılan 1) : Her istem için üretilecek video sayısı.
generator (torch.Generator veya List[torch.Generator], isteğe bağlı) : Üretimi deterministik hale getirmek için bir veya bir torch üreteci listesi.
latents (torch.Tensor, isteğe bağlı) : Video üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenen önceden oluşturulmuş gürültülü latentler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklem yoluyla bir latent tensörü oluşturulur.
audio_latents (torch.Tensor, isteğe bağlı) : Ses üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenen önceden oluşturulmuş gürültülü latentler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklem yoluyla bir latent tensörü oluşturulur.
prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.
prompt_attention_mask (torch.Tensor, isteğe bağlı) : Metin gömme (embedding) için önceden oluşturulmuş dikkat maskesi (attention mask).
negative_prompt_embeds (torch.FloatTensor, isteğe bağlı) : Önceden oluşturulmuş negatif metin gömme değerleri. PixArt-Sigma için bu negatif istem "" olmalıdır. Sağlanmazsa, negative_prompt_embeds, negative_prompt girdi argümanından oluşturulur.
negative_prompt_attention_mask (torch.FloatTensor, isteğe bağlı) : Negatif metin gömme vektörleri için önceden oluşturulmuş dikkat maskesi.
decode_timestep (float, varsayılan 0.0) : Üretilen videonun çözümlendiği zaman adımı.
decode_noise_scale (float, varsayılan None) : Çözme zaman adımında rastgele gürültü ile gürültüsü azaltılmış latentler arasındaki interpolasyon katsayısı.
use_cross_timestep (bool opsiyonel, varsayılan True) : Çapraz dikkat modülasyon parametrelerini hesaplanırken çapraz modalite (video için çapraz modalite ses, ve bunun tersi) sigma'sının kullanılıp kullanılmayacağı. True LTX-2.3/2.5 davranışıdır; False ise eski LTX-2.0 davranışıdır.
system_prompt (str, isteğe bağlı, varsayılan None) : İsteğin iyileştirilmesi için kullanılacak isteğe bağlı sistem istemi. Sistem istemi, orijinal prompt'ten (ve mevcut ise bir koşullandırma görselinden) üretimi koşullandırmak üzere iyileştirilmiş bir istem oluşturmak için istem iyileştirici tarafından (yapılandırılmışsa özel prompt_enhancer bileşeni, değilse ana text_encoder) kullanılır. Sağlanmazsa ve özel bir prompt_enhancer yapılandırılmışsa (LTX-2.5), bir koşullandırma görseli mevcut olduğunda varsayılan olarak LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, aksi takdirde LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT kullanılır -- bkz. enable_prompt_enhancement.
enable_prompt_enhancement (bool, isteğe bağlı, varsayılan False) : İstem güçlendirmesinin çalıştırılıp çalıştırılmayacağını belirtir. Lightricks referans boru hatlarıyla uyumlu olacak şekilde isteğe bağlıdır. True olduğunda ve system_prompt atlandığında, LTX-2.5, koşullandırma görüntüsünün mevcut olup olmadığına bağlı olarak LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT / LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT değerlerinden birini seçer.
prompt_max_new_tokens (int, isteğe bağlı, varsayılan None) : İstem güçlendirme (prompt enhancement) sırasında oluşturulacak en fazla yeni jeton sayısı. Belirtilmezse, LTX-2.5 için ayrılmış Gemma 4 prompt_enhancer durumunda 600, LTX-2.0/2.3 için Gemma 3 text_encoder yedeği durumunda 512 kullanılır.
prompt_enhancement_kwargs (dict[str, Any], isteğe bağlı, varsayılan None) : Prompt geliştiricisinin .generate çağrısı için anahtar kelime argümanları. Verilmezse, her zaman geliştirmeyi yapan modelle eşleşir: özel bir prompt_enhancer (LTX-2.5) kullanıldığında do_sample=False, no_repeat_ngram_size=5 (açgözlü) veya text_encoder yedeği (LTX-2.0/2.3) için do_sample=True, temperature=0.7. Daha fazla ayrıntı için https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate adresine bakın.
prompt_enhancement_seed (int, isteğe bağlı, varsayılan 10) : İstem geliştirme sırasında herhangi bir rastgele işlem için rastgele tohum.
output_type (str, isteğe bağlı, varsayılan "pil") : Üretilen görüntünün çıktı biçimi. PIL: PIL.Image.Image veya np.array arasında seçim yapın.
return_dict (bool, isteğe bağlı, varsayılan True) : Düz bir tuple yerine ~pipelines.ltx.LTX2PipelineOutput döndürülecek mi?
attention_kwargs (dict, isteğe bağlı) : Belirtilirse, diffusers.models.attention_processor içinde self.processor altında tanımlanan AttentionProcessor'a iletilen bir kwargs sözlüğü.
callback_on_step_end (Callable, isteğe bağlı) : Çıkarım sırasında her gürültü azaltma adımının sonunda çağrılan bir işlev. İşlev aşağıdaki argümanlarla çağrılır: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs, callback_on_step_end_tensor_inputs tarafından belirtilen tüm tensörlerin listesini içerir.
callback_on_step_end_tensor_inputs (List, optional) : The list of tensor inputs for the callback_on_step_end function. The tensors specified in the list will be passed as callback_kwargs argument. You will only be able to include variables listed in the ._callback_tensor_inputs attribute of your pipeline class.
max_sequence_length (int, isteğe bağlı, varsayılan 1024) : prompt ile kullanılacak maksimum dizi uzunluğu.
Dönüş: ~pipelines.ltx.LTX2PipelineOutput veya tuple
return_dict True ise ~pipelines.ltx.LTX2PipelineOutput döndürülür, aksi halde ilk öğesi üretilen görüntülerin listesini içeren bir tuple döndürülür.
Üretim için pipeline çağrıldığında tetiklenen işlev.
Örnekler:
>>> 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[[diffusers.LTX2ConditionPipeline.apply_first_frame_conditioning]]
apply_first_frame_conditioning(latents: Tensor, conditioning_mask: Tensor, condition_latents: list, condition_strengths: list, condition_indices: list, latent_height: int, latent_width: int)
Parametreler:
latents (torch.Tensor) : [batch_size, patch_seq_len, hidden_dim] biçiminde başlangıç paketlenmiş (patch'lenmiş) latentler.
conditioning_mask (torch.Tensor) : [batch_size, patch_seq_len, 1] biçiminde, [0, 1] aralığında değerler içeren başlangıç paketlenmiş (patchify edilmiş) koşullama maskesi; burada 0, gürültü giderme modeli çıktısının tamamen kullanılacağını, 1 ise koşulun tamamen kullanılacağını belirtir.
Dönüş: Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
Şu içeriklere sahip bir 3'lü tensör döndürür:
- İlk kare koşulları uygulanmış paketlenmiş video latantları.
- İlk kare güçleri uygulanmış paketlenmiş koşullama maskesi.
- İlk kare konumlarındaki temiz koşullama latentleri (diğer yerlerde sıfır).
İlk kare görsel koşullandırmayı, ilk kare konumlarındaki jetonları (token) üzerine yazarak uygulayın.
Burada yalnızca latent_idx == 0 koşuluna sahip koşullar uygulanır (referans uygulamadaki VideoConditionByLatentIndex ile uyumlu olarak). Sıfır olmayan latent indekslerdeki koşullar, prepare_keyframe_extras aracılığıyla ayrı ana kare jetonları olarak eklenir (VideoConditionByKeyframeIndex ile uyumlu olarak) ve burada atlanır.
encode_prompt[[diffusers.LTX2ConditionPipeline.encode_prompt]]
encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, scale_factor: int = 8, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
Parametreler:
prompt (str veya list[str], isteğe bağlı) : kodlanacak istem
negative_prompt (str veya list[str], isteğe bağlı) : Görsel üretimi yönlendirmemek için kullanılan istem veya istemler. Tanımlanmazsa, bunun yerine negative_prompt_embeds parametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (yani guidance_scale değeri 1'den küçükse) yok sayılır.
do_classifier_free_guidance (bool, isteğe bağlı, varsayılan True) : Sınıflandırıcı serbest yönlendirmenin (classifier free guidance) kullanılıp kullanılmayacağı.
num_videos_per_prompt (int, opsiyonel, varsayılan 1) : Her istem için oluşturulması gereken video sayısı. Sonuç gömme vektörlerinin yerleştirileceği torch cihazı
prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.
negative_prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş negatif metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, negative_prompt_embeds, negative_prompt girdi argümanından oluşturulur.
device : (torch.device, isteğe bağlı): torch cihazı
dtype : (torch.dtype, isteğe bağlı): torch dtype
İsteği metin kodlayıcı gizli durumlarına kodlar.
enhance_prompt[[diffusers.LTX2ConditionPipeline.enhance_prompt]]
enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)
Sağlanan prompt değerini, prompt geliştiriciden (bir Gemma koşullu üretim modeli) ve bir sistem promptundan yararlanarak yeni bir prompt üreterek geliştirir. image sağlandığında, geliştirici bu referans kareye de (I2V / anahtar kare tarzı geliştirme) koşullandırılır. Yapılandırılmışsa (ör. metin kodlayıcısı geliştirme için eğitilmemiş olan LTX-2.5) özel prompt_enhancer bileşeni kullanılır, aksi takdirde ana text_encoder (kendi geliştiricileri olarak da görev yapan LTX-2.0/2.3) kullanılır.
Mesaj şablonları, çözümleme kwargs'ları, yanıt temizleme ve görüntü uzun kenar hazırlığı ltx-core / ltx-pipelines ile eşleşir (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
prepare_latents[[diffusers.LTX2ConditionPipeline.prepare_latents]]
prepare_latents(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, batch_size: int = 1, num_channels_latents: int = 128, height: int = 512, width: int = 768, num_frames: int = 121, frame_rate: float = 24.0, noise_scale: float = 1.0, dtype: typing.Optional[torch.dtype] = None, device: typing.Optional[torch.device] = None, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None)
Gürültülü video latentlerini hazırlayın ve çerçeve koşullarını uygulayın.
İlk kare koşulları (latent_idx == 0), ilk kare konumlarındaki tokenların üzerine yazılarak uygulanır (VideoConditionByLatentIndex semantiği). İlk kare dışı koşullar (latent_idx > 0), token başına conditioning_mask = strength ile ana latent dizisine eklenir (VideoConditionByKeyframeIndex semantiği) — ardından gürültü kaldırma döngüsünün mevcut timestep formülü t * (1 - conditioning_mask) ve son işlem karışımı denoised * (1 - conditioning_mask) + clean * conditioning_mask, bu koşulları adımlar boyunca yönlendirir.
4'lü bir demet döndürür:
latents: paketli gürültülü latentler (temel tokenler + dizilim boyutuna katlanmış herhangi bir ana kare tokeni).conditioning_mask:[0, 1]aralığında değerlere sahip paketlenmiş koşullama maskesi — ilk kare konumlarında1, ana kare konumlarındastrength, diğer yerlerde0.clean_latents: koşullu konumlardaki temiz koşul değerleri (diğer yerlerde sıfır);latentsile aynı şekle sahiptir.keyframe_coords:video_coords'e eklenmek üzere[B, 3, num_keyframe_patches, 2]konumsal koordinatlar veya ilk kare dışındaki koşullar yoksaNone.
preprocess_conditions[[diffusers.LTX2ConditionPipeline.preprocess_conditions]]
preprocess_conditions(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, device: typing.Optional[torch.device] = None)
Parametreler:
conditions (LTX2VideoCondition veya List[LTX2VideoCondition], opsiyonel, varsayılan None) : Görsel/video koşul örneklerinin listesi.
height (int, isteğe bağlı, varsayılan 512) : Piksel cinsinden istenen yükseklik.
width (int, isteğe bağlı, varsayılan 768) : İstenen piksel cinsinden genişlik.
num_frames (int, isteğe bağlı, varsayılan 121) : Üretilen videodaki istenen kare sayısı.
device (torch.device, isteğe bağlı, varsayılan None) : Ön işlenmiş görüntü/video tensörlerinin yerleştirileceği cihaz.
Dönüş: Tuple[List[torch.Tensor], List[float], List[int], List[int]]
len(conditions) uzunluğunda listelerden oluşan 4'lü bir demet döndürür:
- İlk liste, [batch_size=1, num_channels, num_frames, height, width] biçiminde ön işlenmiş video tensörlerinin listesidir.
- İkinci liste, koşullama güçlerinin listesidir.
- Üçüncü liste, her koşul için gizli uzay indekslerinin listesidir.
- Dördüncü liste, koşul başına (kırpılmış) piksel-uzay kare sayılarının listesidir. Bu, anahtar kare koordinat anlambilisi için gereklidir (tek piksel kareli anahtar karelerin sınırlanmış bir zaman aralığı vardır).
Koşul görüntülerini/videolarını torch tensörlerine ön işler.
trim_conditioning_sequence[[diffusers.LTX2ConditionPipeline.trim_conditioning_sequence]]
trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int)
Parametreler:
start_frame (int) : Sıradaki ilk kare için hedef kare numarası.
sequence_num_frames (int) : Sıradaki kare sayısı.
target_num_frames (int) : Üretilen videodaki hedef kare sayısı.
Dönüş: int
güncellenmiş dizi uzunluğu
Koşullandırma dizisini izin verilen kare sayısına kırpın.
LTX2DFRPipeline[[diffusers.LTX2DFRPipeline]]
diffusers.LTX2DFRPipeline[[diffusers.LTX2DFRPipeline]]
diffusers.LTX2DFRPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)
Parametreler:
scheduler (FlowMatchEulerDiscreteScheduler) : Kodlanmış video latentlerini gürültüden arındırmak için transformer ile birlikte kullanılacak bir zamanlayıcı.
vae (AutoencoderKLLTX2Video) : Videoları latent temsillere kodlamak ve latent temsillerden çözmek için kullanılan Varyasyonel Oto-Kodlayıcı (VAE) Modeli.
audio_vae (AutoencoderKLLTX2Audio) : Ses spektrogramlarını kodlamak ve çözmek için kullanılan ses VAE'si.
text_encoder (Gemma3ForConditionalGeneration veya Gemma4UnifiedForConditionalGeneration) : Metin kodlayıcı modeli.
tokenizer (GemmaTokenizer veya GemmaTokenizerFast) : Metin kodlayıcı için tokenizer.
connectors (LTX2TextConnectors) : Video ve ses dalları için metin kodlayıcı gizli durumlarını uyarlamakta kullanılan metin konnektör yığını.
transformer (LTX2VideoTransformer3DModel) : Kodlanmış video latentlerini gürültüden arındırmak için kullanılan koşullu Transformer mimarisi.
vocoder (LTX2Vocoder veya LTX2VocoderWithBWE) : Mel spektrogramlarını ses dalga formlarına dönüştürmek için kullanılan Vocoder.
processor (ProcessorMixin, isteğe bağlı) : Prompt iyileştirme sohbet şablonlaması için kullanılan işlemci.
prompt_enhancer (Gemma4ForConditionalGeneration, isteğe bağlı) : Özel istem geliştirme modeli (LTX-2.5).
duration_head (LTX2DurationHead, isteğe bağlı) : num_frames sağlanmadığında, prompt gömlemelerinden num_frames değerini tahmin eder.
LTX-2.5 ile tek bir Diffusion Fidelity Rendering (DFR) gürültü azaltma geçişi için pipeline.
Bir geçiş, videoyu ve ekli tek piksellik kare anahtar kare yuvalarını üretir veya bu yuvalardan tohumlanan sağlanan latentleri yeniden gürültüden arındırır. Çağıranlar aşamaları birleştirir: bu hattı yarı çözünürlükte, LTX2LatentUpsamplePipeline ile uzamsal olarak, ardından yükseltilmiş yuvalar ve bir IC-LoRA referansıyla tam çözünürlükte bu hattı tekrar, her zamanlama rafineleme turu için de LTX2DFRTemporalRefinePipeline ile. 1080p tarifi için LTX-2 belgelerine bakın.
Slot konumları, VAE'nin zamansal sınırına hizalı bir segment ızgarasından (resolve_canvas) gelir. Tuval, tam sayı segmente yastıklanır; output_type="latent" bu yastıklanmış ızgarayı döndürür, böylece yastıkta bir slot düşmez. VAE çözümü öncesinde trim_canvas ile kırpın.
generate_slots=True olduğunda, use_keyframes_abs_pos_embedding ayarını belirleyen bir transformer gerektirir (LTX-2.5 ve sonrası).
Referans: https://github.com/Lightricks/LTX-2
call[[diffusers.LTX2DFRPipeline.call]]
__call__(prompt: str | list[str] = None, conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 704, width: int = 1216, num_frames: int | None = None, frame_rate: float = 24.0, min_seconds: float = 1.0, max_seconds: float = 20.0, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, keyframes_latents: typing.Optional[torch.Tensor] = None, keyframe_positions: list[int] | None = None, reference_latents: typing.Optional[torch.Tensor] = None, reference_downscale_factor: int = 2, guidance_keyframe_latents: typing.Optional[torch.Tensor] = None, guidance_keyframe_positions: list[int] | None = None, guidance_keyframe_strength: float = 1.0, generate_slots: bool = True, sigmas: list = [1.0, 0.99375, 0.9875, 0.98125, 0.975, 0.909375, 0.725, 0.421875], noise_scale: float | None = None, freeze_audio: bool = False, video_tiles: list[diffusers.pipelines.ltx2.dfr_layout.LTX2DFREpilogueTile] | None = None, num_videos_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 1024)
Parametreler:
prompt (str veya List[str], isteğe bağlı) : Video üretimini yönlendirmek için istem veya istemler. Tanımlanmamışsa, prompt_embeds parametresinin geçirilmesi gerekir.
conditions (LTX2VideoCondition veya List[LTX2VideoCondition], opsiyonel) : Kare düzeyinde görüntü veya video koşulları. index, bu geçişin num_frames değerindeki bir latent indeksidir.
height (int, isteğe bağlı, varsayılan 704) : bu geçişin piksel cinsinden yüksekliği, nihai birleşik çıktı değil.
width (int, isteğe bağlı, varsayılan 1216) : Bu geçişin piksel cinsinden genişliği.
num_frames (int, isteğe bağlı) : Bu geçişin, dahili tuval dolgusundan önceki piksel kare sayısı. Verilmezse, süre duration_head tarafından istemden tahmin edilir. (num_frames - 1) % 8 == 0 koşulunu sağlamalıdır.
frame_rate (float, isteğe bağlı, varsayılan 24.0) : Bu geçişin oynatma fps değeri. Bu değer 30'un üzerindeyse RoPE zamanı 60'a sabitlenir.
min_seconds (float, opsiyonel, varsayılan 1.0) : num_frames atlandığında otomatik tahmin edilen sürenin alt sınırı.
max_seconds (float, isteğe bağlı, varsayılan 20.0) : num_frames atlandığında otomatik tahmin edilen sürenin üst sınırı.
latents (torch.Tensor, isteğe bağlı) : Yeniden gürültüden arındırılacak (2. aşama / epilog) ham (batch_size, channels, frames, height, width) video latentleri.
audio_latents (torch.Tensor, isteğe bağlı) : Ham, paketlenmemiş (batch_size, channels, length, mel_bins) ses latentleri. 2. aşama hâlâ ortak bir ses geçişi çalıştırır; birleştirilmiş bir tarifin teslim edilen dalga formu 1. aşamanınkidir ve çağıran bunu korur.
keyframes_latents (torch.Tensor, isteğe bağlı) : generate_slots=True kullanıldığında kullanılan ham (batch_size, channels, num_slots, height, width) slot başlangıçları.
keyframe_positions (list[int], isteğe bağlı) : Üretilen slotların piksel-kare indeksleri. Varsayılan olarak resolve_canvas(num_frames) değerini alır.
reference_latents (torch.Tensor, isteğe bağlı) : Ham IC-LoRA referans videosu (genellikle 1. aşamanın kareleri).
reference_downscale_factor (int, isteğe bağlı, varsayılan 2) : Bu geçiş ile referans çözünürlük arasındaki oran, referans token koordinatlarını ölçeklemek için kullanılır.
guidance_keyframe_latents (torch.Tensor, isteğe bağlı) : Ham sabitlenmiş yönlendirme anahtar kareleri (batch_size, channels, K, height, width) — epilog yolu. Üretilmemiş yuvalar.
guidance_keyframe_positions (list[int], isteğe bağlı) : guidance_keyframe_latents için piksel-kare dizinleri.
guidance_keyframe_strength (float, isteğe bağlı, varsayılan 1.0) : Sabitlenmiş yönlendirme anahtar kareleri için koşullandırma gücü.
generate_slots (bool, isteğe bağlı, varsayılan True) : Üretilen keyframe-slot jetonlarını ekler. Epilog bunu False olarak ayarlar ve bunun yerine guidance_keyframe_latents sabitlenir.
sigmas (list[float], isteğe bağlı) : Bu geçiş için, son 0.0 değerini içermeyen gürültü zamanlaması.
noise_scale (float, isteğe bağlı) : Koşulsuz tokenlerin başladığı gürültü seviyesi. Varsayılan olarak sigmas[0]'dır.
freeze_audio (bool, isteğe bağlı, varsayılan False) : Sesi sigma 0'da tutar (epilog / dondurulmuş bir 1. aşama dalga formunu takip ederken).
video_tiles (list[LTX2DFREpilogueTile], opsiyonel) : epilogue_tiles() kaynaklı epilog döşemeleri, böylece tek bir ileri geçiş için çok büyük olan bir çözünürlük bile tek bir tuval üzerinde adım atabilir: her adım, her döşe için dönüştürücüyü bir kez çalıştırır ve tahminleri harmanlar. Yerleşim, planın kendisi yerine bu geçişin kendi RoPE koordinatlarına karşı bir token planına çözümlendiği için iletir — koordinatlar yalnızca prepare_latents() çalıştıktan sonra var olur.
num_videos_per_prompt (int, isteğe bağlı, varsayılan 1) : Her istem için üretilecek video sayısı.
generator (torch.Generator veya list[torch.Generator], isteğe bağlı) : Yeniden üretilebilirlik için rastgele üreteç(ler).
prompt_embeds (torch.Tensor, isteğe bağlı) : Önceden oluşturulmuş metin gömme değerleri.
prompt_attention_mask (torch.Tensor, isteğe bağlı) : Metin gömme (embedding) için önceden oluşturulmuş dikkat maskesi (attention mask).
decode_timestep (float, varsayılan 0.0) : Üretilen videonun çözümlendiği zaman adımı.
decode_noise_scale (float, varsayılan None) : Çözümleme sırasında gürültü ölçeği.
use_cross_timestep (bool, isteğe bağlı, varsayılan True) : Çapraz dikkat modülasyonu için çapraz modalite sigma kullanılacak mı. LTX-2.3+ için True.
system_prompt (str, isteğe bağlı) : İsteği iyileştirme için isteğe bağlı sistem istemi. enable_prompt_enhancement bölümüne bakın.
enable_prompt_enhancement (bool, isteğe bağlı, varsayılan False) : İstem güçlendirmesinin çalıştırılıp çalıştırılmayacağı.
prompt_max_new_tokens (int, isteğe bağlı) : İstem güçlendirmesi sırasında oluşturulacak yeni jetonların maksimum sayısı.
prompt_enhancement_kwargs (dict[str, Any], isteğe bağlı) : Prompt geliştiricisinin .generate çağrısı için anahtar kelime argümanları.
prompt_enhancement_seed (int, isteğe bağlı, varsayılan 10) : İstem geliştirme sırasında herhangi bir rastgele işlem için rastgele tohum.
output_type (str, isteğe bağlı, varsayılan "pil") : Çıktı biçimi. "pil", "np", "pt" veya "latent" seçin. Latent çıktı, kırpılmamış tuvaldir.
return_dict (bool, isteğe bağlı, varsayılan True) : Bir LTX2DFRPipelineOutput döndürülecek mi yoksa düz bir (frames, audio, keyframes, keyframe_positions) demeti mi döndürülecek?
attention_kwargs (dict, isteğe bağlı) : Dikkat işlemcisine (attention processor) iletilen ek kwargs.
callback_on_step_end (Callable, isteğe bağlı) : Her gürültü azaltma adımının sonunda çağrılan bir işlev.
callback_on_step_end_tensor_inputs (List, isteğe bağlı, varsayılan ["latents"]) : Geri çağrı işlevi için girdi tensörleri.
max_sequence_length (int, isteğe bağlı, varsayılan 1024) : Metin istemi için maksimum dizi uzunluğu.
Dönüş: LTX2DFRPipelineOutput veya tuple
return_dict True ise LTX2DFRPipelineOutput döndürülür, aksi takdirde (video, audio, keyframes, keyframe_positions) içeren bir tuple döndürülür.
Üretim için pipeline çağrıldığında tetiklenen işlev.
height × width çözünürlüğünde tek bir denoise geçişi. Aşamaları çağıran tarafta birleştirin: bu pipeline yarı çözünürlükte, uzamsal upsample, ardından latents / keyframes_latents / reference_latents ile bu pipeline tekrar, ve her zaman turu için LTX2DFRTemporalRefinePipeline.
Örnekler:
>>> 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[[diffusers.LTX2DFRPipeline.denoise]]
denoise(latents: Tensor, conditioning_mask: Tensor, clean_latents: Tensor, video_coords: Tensor, keyframes_mask: Tensor, prompt_embeds: Tensor, audio_prompt_embeds: Tensor, prompt_attention_mask: Tensor, sigmas: list, frame_rate: float, audio_latents: Tensor, freeze_audio: bool = False, video_tile_plan: list | None = None, generator: typing.Optional[torch.Generator] = None, use_cross_timestep: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, progress_bar = None, step_offset: int = 0, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] | None = None)
Parametreler:
sigmas (list[float]) : Bu geçiş için, son 0.0 değeri hariç gürültü zamanlaması.
freeze_audio (bool, isteğe bağlı, varsayılan False) : audio_latents'i temiz tutar (timestep/sigma 0, ses Euler adımı yok) ancak ses-videodan çapraz dikkat (cross-attention) çalışmaya devam eder. audio_latents None ise yok sayılır.
video_tile_plan (list, isteğe bağlı) : video_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan] içinden tile başına token planı. Verildiğinde, her adım transformer'ı tile başına bir kez çalıştırır ve tahminleri birleştirir; böylece örnekleyici yine tek bir tam tuval üzerinde adım atar ve tile'lar her adımda örtüşme bölgelerinde uyumlu kalır.
generator (torch.Generator, isteğe bağlı) : LTXEulerAncestralRFScheduler.step() iletilir. Zaman karoları, atal çekimlerin bir akış paylaşmaması ve bir sonraki karonun başlangıç gürültüleme işlemi tarafından okunan durumu tüketmemesi için karo başına bir tohum geçirir. Distilled Euler bunu okumaz.
step_offset (int) : Bu geçişin ilk adımının, hattın tüm zaman çizelgesi içindeki indeksi; callback_on_step_end ve ortak ilerleme çubuğu için kullanılır.
sigmas üzerinde tek bir DFR gürültü azaltma geçişi çalıştırın ve her ikisi de hâlâ paketlenmiş olan (latents, audio_latents) değerlerini döndürün.
Distilled schedule, classifier-free guidance kullanılmadan çalıştığı için her adımda tek bir transformer çağrısı yapılır. Her geçişte her iki akış da çalıştırılır, çünkü video dalı, ürettiği sesin atıldığı yerlerde bile cross-modal attention'a ihtiyaç duyar. freeze_audio=True, ses akışını sigma 0'da tutar (Euler adımı uygulanmaz) böylece video hâlâ ona cross-attend edebilir — temporal refine karoları ve epilogue, her karo farklı bir ses realizasyonu yeniden gürültüden arındırmadan stage-1 konuşmasını takip etmek için bunu kullanır.
x0 koşullandırma karışımından sonra hız (latents - denoised) / sigma olduğundan, bir RF adımı olan x0 = x - σ v karıştırılmış denoised değerini geri kazanır. 1. aşama / 2. aşama / epilog FlowMatchEulerDiscreteScheduler kullanmaya devam eder ve bu Euler adımını olduğu gibi alır. Zamanla iyileştirme, LTXEulerAncestralRFScheduler (eta=0.5) ile değiştirilir; bu adım her token’ı yeniden gürültüler, bu nedenle koşullandırma karışımı sonrasında yeniden uygulanmalıdır, aksi takdirde 0.95 gücündeki dikiş çapaları aşınır.
encode_conditions[[diffusers.LTX2DFRPipeline.encode_conditions]]
encode_conditions(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None, height: int, width: int, num_frames: int, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None, generator: typing.Optional[torch.Generator] = None)
Piksel çerçevesiyle konumlandırılmış çerçeve koşullarını ön işleyin ve VAE ile kodlayın.
Koşul başına (pixel_frame_index, latent, strength, num_pixel_frames) döndürür ve prepare_latents()'in condition_latents parametresi için kullanıma hazırdır. Kodlama, yerleştirmeden ayrı tutulur çünkü zamanlama refine turları, bir koşulun konumunu 2 ** round ile ölçekler ve her karoyu yeniden taban alır; bu işlemi yapmak için aynı sabit görüntüyü her karo için yeniden kodlamamalıdır.
Döndürülen indeks, num_frames'in kendi piksel ızgarasındadır; bunu rafine edilmiş bir tuvale taşımak çağrıcının görevidir.
encode_prompt[[diffusers.LTX2DFRPipeline.encode_prompt]]
encode_prompt(prompt: str | list[str], num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
Parametreler:
prompt (str veya list[str], isteğe bağlı) : kodlanacak istem
num_videos_per_prompt (int, isteğe bağlı, varsayılan 1) : Her istem için oluşturulması gereken video sayısı.
prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.
prompt_attention_mask (torch.Tensor, isteğe bağlı) : prompt_embeds için önceden oluşturulmuş dikkat maskesi.
device : (torch.device, isteğe bağlı): torch cihazı
dtype : (torch.dtype, isteğe bağlı): torch dtype
İsteği metin kodlayıcı gizli durumlarına kodlar.
DFR, sınıflandırıcı-ücretsiz yönlendirme olmadan kullanılacak şekilde eğitilmiş damıtılmış sigma zamanlamasını çalıştırır, bu nedenle burada negatif bir dal yoktur.
enhance_prompt[[diffusers.LTX2DFRPipeline.enhance_prompt]]
enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)
Sağlanan prompt değerini, prompt geliştiriciden (bir Gemma koşullu üretim modeli) ve bir sistem promptundan yararlanarak yeni bir prompt üreterek geliştirir. image sağlandığında, geliştirici bu referans kareye de (I2V / anahtar kare tarzı geliştirme) koşullandırılır. Yapılandırılmışsa (ör. metin kodlayıcısı geliştirme için eğitilmemiş olan LTX-2.5) özel prompt_enhancer bileşeni kullanılır, aksi takdirde ana text_encoder (kendi geliştiricileri olarak da görev yapan LTX-2.0/2.3) kullanılır.
Mesaj şablonları, çözümleme kwargs'ları, yanıt temizleme ve görüntü uzun kenar hazırlığı ltx-core / ltx-pipelines ile eşleşir (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
prepare_latents[[diffusers.LTX2DFRPipeline.prepare_latents]]
prepare_latents(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, condition_latents: list[tuple[int, torch.Tensor, float, int]] | None = None, keyframe_latents: list[tuple[int, torch.Tensor, float]] | None = None, slot_frame_indices: list[int] | None = None, slot_initial_latents: typing.Optional[torch.Tensor] = None, reference_latents: typing.Optional[torch.Tensor] = None, reference_downscale_factor: int = 1, batch_size: int = 1, num_channels_latents: int = 128, height: int = 512, width: int = 768, num_frames: int = 121, frame_rate: float = 24.0, noise_scale: float = 1.0, dtype: typing.Optional[torch.dtype] = None, device: typing.Optional[torch.device] = None, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None, latents_normalized: bool = True)
Parametreler:
conditions (list[LTX2VideoCondition], isteğe bağlı) : Latent indekse göre konumlandırılmış, kare düzeyinde görüntü / video koşulları.
condition_latents (list[tuple[int, torch.Tensor, float, int]], isteğe bağlı) : conditions için önceden kodlanmış yer tutucu, (pixel_frame_index, latent, strength, num_pixel_frames) biçiminde. Zamanla rafineleme turu, bir koşulun konumunu 2 ** round ile ölçekler ve sonuç genellikle bir latent sınırına denk gelmez; orada yalnızca eklenmiş bir anahtar kare belirteci bulunabilir ve bu, piksel bazında yerleştirilir. pixel_frame_index == 0 hâlâ "ilk kareyi değiştir" anlamına gelir.
keyframe_latents (list[tuple[int, torch.Tensor, float]], isteğe bağlı) : (pixel_frame_index, latent, strength) biçiminde, latent'in (batch_size, num_channels_latents, 1, latent_height, latent_width) şekline sahip olduğu, önceden kodlanmış ana kare yönlendirmesi. Önceki turdan taşınan dikiş ana karelerini sabitlemek için zamanla iyileştirme turlarında kullanılır.
slot_frame_indices (list[int], isteğe bağlı) : Üretilen ana kare yuvalarının piksel-kare konumları.
slot_initial_latents (torch.Tensor, isteğe bağlı) : Gürültü eklenmeden önce slot token'larına yazılan (batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width) içeriği.
reference_latents (torch.Tensor, isteğe bağlı) : (batch_size, num_channels_latents, F, H, W) IC-LoRA referans latent.
reference_downscale_factor (int, varsayılan 1) : Hedef çözünürlük ile referans çözünürlük arasındaki oran.
latents (torch.Tensor, isteğe bağlı) : (batch_size, num_channels_latents, F, H, W) temel tokenlar için başlangıç içeriği. Halka açık pipeline latentleri ham (normalleştirilmemiş) değerlerdir; bu sınırdan geçerken latents_normalized=False parametresini iletin. Zaten VAE-normalize edilmiş uzayda dönen döngüler varsayılan değeri korur.
latents_normalized (bool, varsayılan True) : latents, slot_initial_latents, reference_latents ve keyframe_latents değerlerinin VAE-normalize edilip edilmediğini belirtir. Dahili karolar döngüleri True geçirir; her pipeline __call__ False geçirir.
noise_scale (float, varsayılan 1.0) : Koşulsuz tokenlerin başlatıldığı gürültü seviyesi, yani zamanlamanın ilk sigma değeri.
Dönüş: 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, paketlenmiş dizide üretilen anahtar kare slot tokenlerini indeksler; slot istenmediğinde None değerini alır.
Bir DFR gürültü azaltma geçişi için gürültülü paketlenmiş video latentlerini hazırlayın.
Paketlenmiş dizi [base | keyframes | slots | reference] biçiminde yerleştirilir:
- Taban jetonlar,
latentsverildiğinde bunlardan tohumlanan hedef gizli ızgarayı kapsar. index == 0koşuluna sahip kareler, temiz hedefi ilk kare konumlarında ayarlar;index > 0koşuluna sahip olanlar vekeyframe_latentsiçindeki her giriş, token başına koşullama maskesi kendi gücüne eşit olacak şekilde ek anahtar kare tokenları olarak eklenir.slot_frame_indices, her konum için bir latent karelik üretilmiş ana kare token'ı ekler; koşullama maskesi0(tamamen gürültüden arındırılmış) ve RoPE zaman kapsamı tam olarak bir piksel karesidir. DFR'e ek karelerini veren ana kare yuvaları bunlardır;slot_initial_latentsiçeriklerini başlatır.reference_latents, 1. aşamanın yarı çözünürlüklü latentini, uzamsal koordinatları hedef koordinat uzayına eşleyecek şekildereference_downscale_factorile ölçeklenmiş, tamamen temiz bir IC-LoRA referansı olarak ekler.
Eklenen koşullama jetonları içeriklerini clean_latents içinde taşırken latents içinde sıfır bir yer tutucu bulundurur; anahtar kare yuvaları ise tohumlarını latents içinde, sıfırları ise clean_latents içinde taşır -- döndürülen latents, bu ikisinin gürültülü karışımıdır (bu yöntemin sonundaki gürültüleme adımına bakın).
preprocess_conditions[[diffusers.LTX2DFRPipeline.preprocess_conditions]]
preprocess_conditions(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, device: typing.Optional[torch.device] = None)
Parametreler:
conditions (LTX2VideoCondition veya List[LTX2VideoCondition], opsiyonel, varsayılan None) : Görsel/video koşul örneklerinin listesi.
height (int, isteğe bağlı, varsayılan 512) : Piksel cinsinden istenen yükseklik.
width (int, isteğe bağlı, varsayılan 768) : İstenen piksel cinsinden genişlik.
num_frames (int, isteğe bağlı, varsayılan 121) : Üretilen videodaki istenen kare sayısı.
device (torch.device, isteğe bağlı, varsayılan None) : Ön işlenmiş görüntü/video tensörlerinin yerleştirileceği cihaz.
Dönüş: Tuple[List[torch.Tensor], List[float], List[int], List[int]]
len(conditions) uzunluğunda listelerden oluşan 4'lü bir demet döndürür:
- İlk liste, [batch_size=1, num_channels, num_frames, height, width] biçiminde ön işlenmiş video tensörlerinin listesidir.
- İkinci liste, koşullama güçlerinin listesidir.
- Üçüncü liste, her koşul için gizli uzay indekslerinin listesidir.
- Dördüncü liste, koşul başına (kırpılmış) piksel-uzay kare sayılarının listesidir. Bu, anahtar kare koordinat anlambilisi için gereklidir (tek piksel kareli anahtar karelerin sınırlanmış bir zaman aralığı vardır).
Koşul görüntülerini/videolarını torch tensörlerine ön işler.
rebuild_epilogue_keyframes[[diffusers.LTX2DFRPipeline.rebuild_epilogue_keyframes]]
rebuild_epilogue_keyframes(keyframe_latents: Tensor, decode_timestep: float, decode_noise_scale: float, seed: int, device: device, dtype: dtype)
Parametreler:
keyframe_latents (torch.Tensor) : Önceki bir geçişin döndürdüğü gibi, ham (batch_size, C, K, H, W) anahtar kareleri.
seed (int) : Temel tohum; i. düzlem seed + 4000 + i altında çözümlenir, bu nedenle bir düzlemin pikselleri, ondan önce kaç düzlemin çözümlendiğinden bağımsızdır.
Dönüş: torch.Tensor
Ham (batch_size, C, K, 2H, 2W) latentleri, guidance_keyframe_latents olarak doğrudan geri geçirilmeye hazır.
Taşıma ana karelerini RGB yoluyla iki kat çözünürlükte yeniden kodlayın.
Bu kareler, refine turlarının zaten belirlediği karelerdir; bu nedenle epilogue onlara üretilmeleri istenmek yerine verilir. Piksele çözme, Lanczos ile x2 büyütme ve yeniden kodlama, kareyi korurken onu çıktı ızgarasına yerleştirir; bu da epilogue'un onu tamamen temiz bir şekilde sabitlemesini sağlar.
Her düzlem, kendi tek karelik klipi olarak çözümlenir. VAE nedenseldir (causal), bu yüzden yığılmış bir çözümleme, komşu düzlemlerin birbirine sızmasına neden olur -- bunlar bağımsız statik görüntülerdir, bir dizi değildir.
trim_conditioning_sequence[[diffusers.LTX2DFRPipeline.trim_conditioning_sequence]]
trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int)
Parametreler:
start_frame (int) : Sıradaki ilk kare için hedef kare numarası.
sequence_num_frames (int) : Sıradaki kare sayısı.
target_num_frames (int) : Üretilen videodaki hedef kare sayısı.
Dönüş: int
güncellenmiş dizi uzunluğu
Koşullandırma dizisini izin verilen kare sayısına kırpın.
LTX2DFRTemporalRefinePipeline[[diffusers.LTX2DFRTemporalRefinePipeline]]
diffusers.LTX2DFRTemporalRefinePipeline[[diffusers.LTX2DFRTemporalRefinePipeline]]
diffusers.LTX2DFRTemporalRefinePipeline(scheduler: LTXEulerAncestralRFScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, temporal_latent_upsampler: LTX2LatentUpsamplerModel)
Parametreler:
scheduler (LTXEulerAncestralRFScheduler) : Düzleştirilmiş akış parametrelendirmesindeki atal Euler zamanlayıcısı. DFR zaman tariflemesiyle eşleşmesi için eta=0.5 ile oluşturun.
vae (AutoencoderKLLTX2Video) : Videoları latent temsillere kodlamak ve latent temsillerden çözmek için kullanılan Varyasyonel Oto-Kodlayıcı (VAE) Modeli.
audio_vae (AutoencoderKLLTX2Audio) : Ses spektrogramlarını kodlamak ve çözmek için kullanılan ses VAE'si.
text_encoder (Gemma3ForConditionalGeneration veya Gemma4UnifiedForConditionalGeneration) : Metin kodlayıcı modeli.
tokenizer (GemmaTokenizer veya GemmaTokenizerFast) : Metin kodlayıcı için tokenizer.
connectors (LTX2TextConnectors) : Video ve ses dalları için metin kodlayıcı gizli durumlarını uyarlamakta kullanılan metin konnektör yığını.
transformer (LTX2VideoTransformer3DModel) : Kodlanmış video latentlerini gürültüden arındırmak için kullanılan koşullu Transformer mimarisi.
vocoder (LTX2Vocoder veya LTX2VocoderWithBWE) : Mel spektrogramlarını ses dalga formlarına dönüştürmek için kullanılan Vocoder.
temporal_latent_upsampler (LTX2LatentUpsamplerModel) : Turun başlangıcında uygulanan zamansal x2 latent yükseltici.
Bir zaman DFR rafineleme turu: tuvali zaman boyunca x2 oranında içsel değerle, anahtar kare dikişlerinde karolar oluştur, her karoyu atal gürültü azaltma ile işle, sonraki karenin giriş kısmını atarak birleştir ve taşıma anahtar kare çantasını birleştir.
Zamanlayıcı LTXEulerAncestralRFScheduler'dir (varsayılan olarak eta=0.5). 1. aşama / 2. aşama / uzamsal epilog, LTX2DFRPipeline üzerinden FlowMatchEulerDiscreteScheduler'da kalır. Bu hattı tur başına bir kez çağırın; 2x / 4x için döngüyü çağıran yürütür.
Gelen latents / keyframes_latents / audio_latents ham (normalizasyonu kaldırılmış) olup LTX2Pipeline ile uyumludur. keyframe_positions, önceki geçişin döndürdüğü konumlar olmalıdır; bir tur çalıştıktan sonra orijinal num_frames değerinden yeniden türetilemezler.
call[[diffusers.LTX2DFRTemporalRefinePipeline.call]]
__call__(prompt: str | list[str] = None, latents: Tensor = None, keyframes_latents: Tensor = None, keyframe_positions: list = None, audio_latents: Tensor = None, conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 704, width: int = 1216, num_frames: int = 121, frame_rate: float = 24.0, source_seconds: float | None = None, condition_num_frames: int | None = None, round_index: int = 1, sigmas: list = [0.975, 0.909375, 0.725, 0.421875], noise_scale: float | None = None, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 1024)
Parametreler:
prompt (str veya List[str], isteğe bağlı) : Video üretimini yönlendirmek için istem veya istemler. Tanımlanmamışsa, prompt_embeds parametresinin geçirilmesi gerekir.
latents (torch.Tensor) : input tuvalinin ham video latentleri, (batch_size, channels, frames, height, width).
keyframes_latents (torch.Tensor) : Önceki geçişten gelen ham taşıma anahtar kareleri (batch_size, channels, K, height, width).
keyframe_positions (list[int]) : girdi tuvalinde keyframes_latents için piksel-kare indeksleri.
audio_latents (torch.Tensor) : Donmuş 1. aşama ses, paketi açılmış ve normalizasyonu kaldırılmış. Her karoya, oynatma penceresini kapsayan dilim verilir; döndürülen ses, karo başına yeniden gürültü azaltma değil, bu dalga formudur.
conditions (LTX2VideoCondition veya List[LTX2VideoCondition], opsiyonel) : condition_num_frames üzerinde (orijinal istek) indekslenen kare düzeyinde koşullar. Her tur, bir koşulun piksel konumunu 2 ** round_index ile ölçekler.
height (int, isteğe bağlı, varsayılan 704) : Bu geçişin piksel yüksekliği (gelen video ile aynı).
width (int, isteğe bağlı, varsayılan 1216) : Bu geçişin piksel genişliği.
num_frames (int, isteğe bağlı, varsayılan 121) : girdi tuvalinin (kırpmadan önce) piksel kare sayısı.
frame_rate (float, isteğe bağlı, varsayılan 24.0) : girdinin oynatma fps değeri. Round bunu ikiye katlar.
source_seconds (float, isteğe bağlı) : Donmuş 1. aşama sesinin süresi. Varsayılan olarak num_frames / frame_rate değerini alır; bu, ilk tur için doğrudur. Sonraki turlarda, karoların kaymaması için orijinal 1. aşama süresinin geçirilmesi gerekir.
condition_num_frames (int, isteğe bağlı) : conditions'ı kodlamak için kullanılan orijinal üretim num_frames. Varsayılan olarak num_frames'tür. Dolgu veya önceki bir turdan sonra, index=-1'in dolgulu kuyruğa sarmalamaması için orijinal isteği iletin.
round_index (int, isteğe bağlı, varsayılan 1) : 1 tabanlı tur numarası. Karo, atal gürültüyü seed + 1000 * round_index + tile olarak tohumlar ve koşullar 2 ** round_index ile ölçeklenir.
sigmas (list[float], isteğe bağlı) : Bu turun karoları için damıtılmış zaman çizelgesi, son 0.0 değeri hariç.
noise_scale (float, isteğe bağlı) : Koşulsuz tokenlerin başladığı gürültü seviyesi. Varsayılan olarak sigmas[0]'dır.
generator (torch.Generator veya list[torch.Generator], isteğe bağlı) : Yeniden üretilebilirlik için rastgele üreteç(ler). Atasal çekimler, bu üretecin initial_seed() değerinden türetilen, karoya özgü ayrı bir tohum kullanır.
prompt_embeds (torch.Tensor, isteğe bağlı) : Önceden oluşturulmuş metin gömme değerleri.
prompt_attention_mask (torch.Tensor, isteğe bağlı) : Metin gömme (embedding) için önceden oluşturulmuş dikkat maskesi (attention mask).
decode_timestep (float, varsayılan 0.0) : Üretilen videonun çözümlendiği zaman adımı.
decode_noise_scale (float, varsayılan None) : Çözümleme sırasında gürültü ölçeği.
use_cross_timestep (bool, isteğe bağlı, varsayılan True) : Çapraz dikkat modülasyonu için çapraz modalite sigma kullanılacak mı. LTX-2.3+ için True.
output_type (str, isteğe bağlı, varsayılan "pil") : Çıktı biçimi. "pil", "np", "pt" veya "latent" seçin. Latent çıktı, kırpılmamış tuvaldir.
return_dict (bool, isteğe bağlı, varsayılan True) : Bir LTX2DFRPipelineOutput döndürülecek mi yoksa düz bir (frames, audio, keyframes, keyframe_positions) demeti mi döndürülecek?
attention_kwargs (dict, isteğe bağlı) : Dikkat işlemcisine (attention processor) iletilen ek kwargs.
callback_on_step_end (Callable, isteğe bağlı) : Her gürültü azaltma adımının sonunda, her karot üzerinde çağrılan bir işlev.
callback_on_step_end_tensor_inputs (List, isteğe bağlı, varsayılan ["latents"]) : Geri çağrı işlevi için girdi tensörleri.
max_sequence_length (int, isteğe bağlı, varsayılan 1024) : Metin istemi için maksimum dizi uzunluğu.
Dönüş: LTX2DFRPipelineOutput veya tuple
return_dict True ise LTX2DFRPipelineOutput döndürülür, aksi takdirde (video, audio, keyframes, keyframe_positions) içeren bir tuple döndürülür.
Bir zamanlama rafineleme turu çalıştırın.
Örnekler:
>>> 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[[diffusers.LTX2DFRTemporalRefinePipeline.denoise]]
denoise(latents: Tensor, conditioning_mask: Tensor, clean_latents: Tensor, video_coords: Tensor, keyframes_mask: Tensor, prompt_embeds: Tensor, audio_prompt_embeds: Tensor, prompt_attention_mask: Tensor, sigmas: list, frame_rate: float, audio_latents: Tensor, freeze_audio: bool = False, video_tile_plan: list | None = None, generator: typing.Optional[torch.Generator] = None, use_cross_timestep: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, progress_bar = None, step_offset: int = 0, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] | None = None)
Parametreler:
sigmas (list[float]) : Bu geçiş için, son 0.0 değeri hariç gürültü zamanlaması.
freeze_audio (bool, isteğe bağlı, varsayılan False) : audio_latents'i temiz tutar (timestep/sigma 0, ses Euler adımı yok) ancak ses-videodan çapraz dikkat (cross-attention) çalışmaya devam eder. audio_latents None ise yok sayılır.
video_tile_plan (list, isteğe bağlı) : video_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan] içinden tile başına token planı. Verildiğinde, her adım transformer'ı tile başına bir kez çalıştırır ve tahminleri birleştirir; böylece örnekleyici yine tek bir tam tuval üzerinde adım atar ve tile'lar her adımda örtüşme bölgelerinde uyumlu kalır.
generator (torch.Generator, isteğe bağlı) : LTXEulerAncestralRFScheduler.step() iletilir. Zaman karoları, atal çekimlerin bir akış paylaşmaması ve bir sonraki karonun başlangıç gürültüleme işlemi tarafından okunan durumu tüketmemesi için karo başına bir tohum geçirir. Distilled Euler bunu okumaz.
step_offset (int) : Bu geçişin ilk adımının, hattın tüm zaman çizelgesi içindeki indeksi; callback_on_step_end ve ortak ilerleme çubuğu için kullanılır.
sigmas üzerinde tek bir DFR gürültü azaltma geçişi çalıştırın ve her ikisi de hâlâ paketlenmiş olan (latents, audio_latents) değerlerini döndürün.
Distilled schedule, classifier-free guidance kullanılmadan çalıştığı için her adımda tek bir transformer çağrısı yapılır. Her geçişte her iki akış da çalıştırılır, çünkü video dalı, ürettiği sesin atıldığı yerlerde bile cross-modal attention'a ihtiyaç duyar. freeze_audio=True, ses akışını sigma 0'da tutar (Euler adımı uygulanmaz) böylece video hâlâ ona cross-attend edebilir — temporal refine karoları ve epilogue, her karo farklı bir ses realizasyonu yeniden gürültüden arındırmadan stage-1 konuşmasını takip etmek için bunu kullanır.
x0 koşullandırma karışımından sonra hız (latents - denoised) / sigma olduğundan, bir RF adımı olan x0 = x - σ v karıştırılmış denoised değerini geri kazanır. 1. aşama / 2. aşama / epilog FlowMatchEulerDiscreteScheduler kullanmaya devam eder ve bu Euler adımını olduğu gibi alır. Zamanla iyileştirme, LTXEulerAncestralRFScheduler (eta=0.5) ile değiştirilir; bu adım her token’ı yeniden gürültüler, bu nedenle koşullandırma karışımı sonrasında yeniden uygulanmalıdır, aksi takdirde 0.95 gücündeki dikiş çapaları aşınır.
encode_conditions[[diffusers.LTX2DFRTemporalRefinePipeline.encode_conditions]]
encode_conditions(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None, height: int, width: int, num_frames: int, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None, generator: typing.Optional[torch.Generator] = None)
Piksel çerçevesiyle konumlandırılmış çerçeve koşullarını ön işleyin ve VAE ile kodlayın.
Koşul başına (pixel_frame_index, latent, strength, num_pixel_frames) döndürür ve prepare_latents()'in condition_latents parametresi için kullanıma hazırdır. Kodlama, yerleştirmeden ayrı tutulur çünkü zamanlama refine turları, bir koşulun konumunu 2 ** round ile ölçekler ve her karoyu yeniden taban alır; bu işlemi yapmak için aynı sabit görüntüyü her karo için yeniden kodlamamalıdır.
Döndürülen indeks, num_frames'in kendi piksel ızgarasındadır; bunu rafine edilmiş bir tuvale taşımak çağrıcının görevidir.
encode_prompt[[diffusers.LTX2DFRTemporalRefinePipeline.encode_prompt]]
encode_prompt(prompt: str | list[str], num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
Parametreler:
prompt (str veya list[str], isteğe bağlı) : kodlanacak istem
num_videos_per_prompt (int, isteğe bağlı, varsayılan 1) : Her istem için oluşturulması gereken video sayısı.
prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.
prompt_attention_mask (torch.Tensor, isteğe bağlı) : prompt_embeds için önceden oluşturulmuş dikkat maskesi.
device : (torch.device, isteğe bağlı): torch cihazı
dtype : (torch.dtype, isteğe bağlı): torch dtype
İsteği metin kodlayıcı gizli durumlarına kodlar.
DFR, sınıflandırıcı-ücretsiz yönlendirme olmadan kullanılacak şekilde eğitilmiş damıtılmış sigma zamanlamasını çalıştırır, bu nedenle burada negatif bir dal yoktur.
prepare_latents[[diffusers.LTX2DFRTemporalRefinePipeline.prepare_latents]]
prepare_latents(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, condition_latents: list[tuple[int, torch.Tensor, float, int]] | None = None, keyframe_latents: list[tuple[int, torch.Tensor, float]] | None = None, slot_frame_indices: list[int] | None = None, slot_initial_latents: typing.Optional[torch.Tensor] = None, reference_latents: typing.Optional[torch.Tensor] = None, reference_downscale_factor: int = 1, batch_size: int = 1, num_channels_latents: int = 128, height: int = 512, width: int = 768, num_frames: int = 121, frame_rate: float = 24.0, noise_scale: float = 1.0, dtype: typing.Optional[torch.dtype] = None, device: typing.Optional[torch.device] = None, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None, latents_normalized: bool = True)
Parametreler:
conditions (list[LTX2VideoCondition], isteğe bağlı) : Latent indekse göre konumlandırılmış, kare düzeyinde görüntü / video koşulları.
condition_latents (list[tuple[int, torch.Tensor, float, int]], isteğe bağlı) : conditions için önceden kodlanmış yer tutucu, (pixel_frame_index, latent, strength, num_pixel_frames) biçiminde. Zamanla rafineleme turu, bir koşulun konumunu 2 ** round ile ölçekler ve sonuç genellikle bir latent sınırına denk gelmez; orada yalnızca eklenmiş bir anahtar kare belirteci bulunabilir ve bu, piksel bazında yerleştirilir. pixel_frame_index == 0 hâlâ "ilk kareyi değiştir" anlamına gelir.
keyframe_latents (list[tuple[int, torch.Tensor, float]], isteğe bağlı) : (pixel_frame_index, latent, strength) biçiminde, latent'in (batch_size, num_channels_latents, 1, latent_height, latent_width) şekline sahip olduğu, önceden kodlanmış ana kare yönlendirmesi. Önceki turdan taşınan dikiş ana karelerini sabitlemek için zamanla iyileştirme turlarında kullanılır.
slot_frame_indices (list[int], isteğe bağlı) : Üretilen ana kare yuvalarının piksel-kare konumları.
slot_initial_latents (torch.Tensor, isteğe bağlı) : Gürültü eklenmeden önce slot token'larına yazılan (batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width) içeriği.
reference_latents (torch.Tensor, isteğe bağlı) : (batch_size, num_channels_latents, F, H, W) IC-LoRA referans latent.
reference_downscale_factor (int, varsayılan 1) : Hedef çözünürlük ile referans çözünürlük arasındaki oran.
latents (torch.Tensor, isteğe bağlı) : (batch_size, num_channels_latents, F, H, W) temel tokenlar için başlangıç içeriği. Halka açık pipeline latentleri ham (normalleştirilmemiş) değerlerdir; bu sınırdan geçerken latents_normalized=False parametresini iletin. Zaten VAE-normalize edilmiş uzayda dönen döngüler varsayılan değeri korur.
latents_normalized (bool, varsayılan True) : latents, slot_initial_latents, reference_latents ve keyframe_latents değerlerinin VAE-normalize edilip edilmediğini belirtir. Dahili karolar döngüleri True geçirir; her pipeline __call__ False geçirir.
noise_scale (float, varsayılan 1.0) : Koşulsuz tokenlerin başlatıldığı gürültü seviyesi, yani zamanlamanın ilk sigma değeri.
Dönüş: 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, paketlenmiş dizide üretilen anahtar kare slot tokenlerini indeksler; slot istenmediğinde None değerini alır.
Bir DFR gürültü azaltma geçişi için gürültülü paketlenmiş video latentlerini hazırlayın.
Paketlenmiş dizi [base | keyframes | slots | reference] biçiminde yerleştirilir:
- Taban jetonlar,
latentsverildiğinde bunlardan tohumlanan hedef gizli ızgarayı kapsar. index == 0koşuluna sahip kareler, temiz hedefi ilk kare konumlarında ayarlar;index > 0koşuluna sahip olanlar vekeyframe_latentsiçindeki her giriş, token başına koşullama maskesi kendi gücüne eşit olacak şekilde ek anahtar kare tokenları olarak eklenir.slot_frame_indices, her konum için bir latent karelik üretilmiş ana kare token'ı ekler; koşullama maskesi0(tamamen gürültüden arındırılmış) ve RoPE zaman kapsamı tam olarak bir piksel karesidir. DFR'e ek karelerini veren ana kare yuvaları bunlardır;slot_initial_latentsiçeriklerini başlatır.reference_latents, 1. aşamanın yarı çözünürlüklü latentini, uzamsal koordinatları hedef koordinat uzayına eşleyecek şekildereference_downscale_factorile ölçeklenmiş, tamamen temiz bir IC-LoRA referansı olarak ekler.
Eklenen koşullama jetonları içeriklerini clean_latents içinde taşırken latents içinde sıfır bir yer tutucu bulundurur; anahtar kare yuvaları ise tohumlarını latents içinde, sıfırları ise clean_latents içinde taşır -- döndürülen latents, bu ikisinin gürültülü karışımıdır (bu yöntemin sonundaki gürültüleme adımına bakın).
preprocess_conditions[[diffusers.LTX2DFRTemporalRefinePipeline.preprocess_conditions]]
preprocess_conditions(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, device: typing.Optional[torch.device] = None)
Parametreler:
conditions (LTX2VideoCondition veya List[LTX2VideoCondition], opsiyonel, varsayılan None) : Görsel/video koşul örneklerinin listesi.
height (int, isteğe bağlı, varsayılan 512) : Piksel cinsinden istenen yükseklik.
width (int, isteğe bağlı, varsayılan 768) : İstenen piksel cinsinden genişlik.
num_frames (int, isteğe bağlı, varsayılan 121) : Üretilen videodaki istenen kare sayısı.
device (torch.device, isteğe bağlı, varsayılan None) : Ön işlenmiş görüntü/video tensörlerinin yerleştirileceği cihaz.
Dönüş: Tuple[List[torch.Tensor], List[float], List[int], List[int]]
len(conditions) uzunluğunda listelerden oluşan 4'lü bir demet döndürür:
- İlk liste, [batch_size=1, num_channels, num_frames, height, width] biçiminde ön işlenmiş video tensörlerinin listesidir.
- İkinci liste, koşullama güçlerinin listesidir.
- Üçüncü liste, her koşul için gizli uzay indekslerinin listesidir.
- Dördüncü liste, koşul başına (kırpılmış) piksel-uzay kare sayılarının listesidir. Bu, anahtar kare koordinat anlambilisi için gereklidir (tek piksel kareli anahtar karelerin sınırlanmış bir zaman aralığı vardır).
Koşul görüntülerini/videolarını torch tensörlerine ön işler.
trim_conditioning_sequence[[diffusers.LTX2DFRTemporalRefinePipeline.trim_conditioning_sequence]]
trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int)
Parametreler:
start_frame (int) : Sıradaki ilk kare için hedef kare numarası.
sequence_num_frames (int) : Sıradaki kare sayısı.
target_num_frames (int) : Üretilen videodaki hedef kare sayısı.
Dönüş: int
güncellenmiş dizi uzunluğu
Koşullandırma dizisini izin verilen kare sayısına kırpın.
upsample_latents[[diffusers.LTX2DFRTemporalRefinePipeline.upsample_latents]]
upsample_latents(latents: Tensor, upsampler: LTX2LatentUpsamplerModel)
upsampler'ı normalize edilmiş latentler üzerinde çalıştırın; beklediği gibi ham VAE latent uzayından geçiş yapın.
LTX2DFRPipelineOutput[[diffusers.LTX2DFRPipelineOutput]]
diffusers.LTX2DFRPipelineOutput[[diffusers.LTX2DFRPipelineOutput]]
diffusers.LTX2DFRPipelineOutput(frames: Tensor, audio: Tensor, keyframes: typing.Optional[torch.Tensor] = None, keyframe_positions: list[int] | None = None)
Parametreler:
frames (torch.Tensor, np.ndarray veya list[list[PIL.Image.Image]]) : Gürültüsü azaltılmış video. Latent çıktı, kırpılmamış tuvaldir, şekli (batch_size, num_channels, latent_frames, latent_height, latent_width).
audio (torch.Tensor, np.ndarray) : Eşlik eden ses latentleri veya dalga formu.
keyframes (torch.Tensor, isteğe bağlı) : (batch_size, num_channels, num_keyframes, latent_height, latent_width) biçiminde üretilen veya taşınan anahtar kare latentleri. output_type != "latent" olduğunda veya geçiş yuva üretmediğinde (ör. karolalı epilog) None.
keyframe_positions (list[int], isteğe bağlı) : Bu geçişin tuvalindeki her anahtar kare için piksel-kare indeksi; keyframes None olduğunda None. Zaman turundan sonra bunlar orijinal num_frames değerinden yeniden türetilemez ve bir sonraki aşamaya aktarılmalıdır.
DFR hatları için çıktı sınıfı.
LTX2LatentUpsamplePipeline[[diffusers.LTX2LatentUpsamplePipeline]]
diffusers.LTX2LatentUpsamplePipeline[[diffusers.LTX2LatentUpsamplePipeline]]
diffusers.LTX2LatentUpsamplePipeline(vae: AutoencoderKLLTX2Video, latent_upsampler: LTX2LatentUpsamplerModel)
call[[diffusers.LTX2LatentUpsamplePipeline.call]]
__call__(video: list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, spatial_patch_size: int = 1, temporal_patch_size: int = 1, latents: typing.Optional[torch.Tensor] = None, latents_normalized: bool = False, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, adain_factor: float = 0.0, tone_map_compression_ratio: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str | None = 'pil', return_dict: bool = True)
Parametreler:
video (list[PipelineImageInput], isteğe bağlı) : Yukarı örneklemesi yapılacak video (örneğin bir LTX 2.0 ilk aşama çıktısı). Sağlanmazsa, latents sağlanmalıdır.
height (int, isteğe bağlı, varsayılan 512) : Girdi videosunun piksel cinsinden yüksekliği (daha yüksek bir çözünürlüğe sahip olacak olan üretilen video değil).
width (int, isteğe bağlı, varsayılan 768) : Girdi videosunun piksel cinsinden genişliği (daha yüksek bir çözünürlüğe sahip olacak üretilen video değil).
num_frames (int, isteğe bağlı, varsayılan 121) : Girdi videosundaki kare sayısı.
spatial_patch_size (int, isteğe bağlı, varsayılan 1) : Video latentlerinin uzamsal yama boyutu. latents sağlandığında, açma işlemi gerekiyorsa kullanılır.
temporal_patch_size (int, isteğe bağlı, varsayılan 1) : Video latentlerinin zamansal yama boyutu. latents sağlandığında ve açma işlemi gerekiyorsa kullanılır.
latents (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş video latentleri. Bu, video argümanı yerine sağlanabilir. Şekli (batch_size, seq_len, hidden_dim) olan bir yama dizisi veya (batch_size, latent_channels, latent_frames, latent_height, latent_width) şeklinde bir video latent'i olabilir.
latents_normalized (bool, isteğe bağlı, varsayılan False) : latents sağlanırsa, latents'in VAE latent ortalama ve standart sapması kullanılarak normalize edilip edilmediğini belirtir. True ise, latents, latent upsampler'a sağlanmadan önce denormalize edilir.
decode_timestep (float, varsayılan 0.0) : Üretilen videonun çözümlendiği zaman adımı.
decode_noise_scale (float, varsayılan None) : Çözme zaman adımında rastgele gürültü ile gürültüsü azaltılmış latentler arasındaki interpolasyon katsayısı.
adain_factor (float, opsiyonel, varsayılan 0.0) : Yukarı örneklenmiş ve orijinal latentler arasında Adaptive Instance Normalization (AdaIN) karıştırma faktörü. [-10.0, 10.0] aralığında olmalıdır; 0.0 (varsayılan) verilmesi, AdaIN'in uygulanmadığı anlamına gelir.
tone_map_compression_ratio (float, opsiyonel, varsayılan 0.0) : Ton eşleştirmesi için sıkıştırma gücü, bu değer latent değerlerin dinamik aralığını azaltır. Bu, yüksek varyanslı latentleri düzenlemek veya üretim sırasında çıktıları koşullandırmak için faydalıdır. [0, 1] aralığında olmalıdır; 0.0 (varsayılan) ton eşleştirmesinin uygulanmadığını, 1.0 ise tam sıkıştırma etkisine karşılık geldiğini belirtir.
generator (torch.Generator veya list[torch.Generator], isteğe bağlı) : Üretimi deterministik hale getirmek için bir veya torch üreteci(leri) listesi.
output_type (str, isteğe bağlı, varsayılan "pil") : Üretilen görüntünün çıktı biçimi. PIL: PIL.Image.Image veya np.array arasında seçim yapın.
return_dict (bool, isteğe bağlı, varsayılan True) : Düz bir tuple yerine ~pipelines.ltx.LTXPipelineOutput döndürülecek mi?
Dönüş: ~pipelines.ltx.LTXPipelineOutput veya tuple
return_dict True ise ~pipelines.ltx.LTXPipelineOutput döndürülür, aksi halde ilk öğesi örneklemesi artırılmış video olan bir tuple döndürülür.
Üretim için pipeline çağrıldığında tetiklenen işlev.
Örnekler:
>>> 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[[diffusers.LTX2LatentUpsamplePipeline.adain_filter_latent]]
adain_filter_latent(latents: Tensor, reference_latents: Tensor, factor: float = 1.0)
Parametreler:
latents (torch.Tensor) : Normalize edilecek girdi latentleri
reference_latents (torch.Tensor) : Stil istatistiklerini sağlayan referans latentler.
factor (float) : Orijinal ve dönüştürülmüş latent arasındaki karışım faktörü. Aralık: -10.0 ile 10.0, Varsayılan: 1.0
Dönüş: torch.Tensor
Dönüştürülmüş gizli tensör
Referans latent tensörden gelen istatistiklere dayanarak, bir latent tensöre Adaptif Örnek Normalizasyonu (AdaIN) uygular.
tone_map_latents[[diffusers.LTX2LatentUpsamplePipeline.tone_map_latents]]
tone_map_latents(latents: Tensor, compression: float)
Parametreler:
latents : torch.Tensor İsteğe bağlı şekle sahip girdi latent tensörü. Yaklaşık olarak [-1, 1] veya [0, 1] aralığında olması beklenir.
compression : float [0, 1] aralığında sıkıştırma gücü. - 0.0: Ton eşleme yok (kimlik dönüşümü) - 1.0: Tam sıkıştırma etkisi
Dönüş:
torch.Tensor Girdi ile aynı şekle sahip ton eşlemeli latent tensör.
Sigmoid tabanlı bir sıkıştırma kullanarak gizli değerlerin dinamik aralığını algısal olarak pürüzsüz bir şekilde azaltmak için doğrusal olmayan bir ton eşleme fonksiyonu uygular.
Bu, özellikle compression faktörü ile dinamik davranışı kontrol ederken, yüksek varyanslı latentleri düzenlemek veya üretim sırasında çıktıları koşullandırmak için kullanışlıdır.
LTX2VideoDiffusionDecodePipeline[[diffusers.LTX2VideoDiffusionDecodePipeline]]
diffusers.LTX2VideoDiffusionDecodePipeline[[diffusers.LTX2VideoDiffusionDecodePipeline]]
diffusers.LTX2VideoDiffusionDecodePipeline(diffusion_decoder: LTX2VideoDiffusionDecoderModel, scheduler, vae: AutoencoderKLLTX2Video = None)
Parametreler:
diffusion_decoder (LTX2VideoDiffusionDecoderModel) : Difüzyon video kodlayıcısı.
scheduler (FlowMatchEulerDiscreteScheduler) : Dekoderin gürültü azaltma adımlarını sürdüren zamanlayıcı.
vae (AutoencoderKLLTX2Video, isteğe bağlı) : Yalnızca normalizasyonu kaldırılacak gizli istatistikler için sorgulanır. Atlandığında, pipeline LTX-2 varsayılanlarına geri döner; bu nedenle yalnızca çözümleme iş akışının ikinci bir otoenkoder yüklemesi gerekmez.
LTX-2.5'te tanıtılan difüzyon çözücü ile LTX-2 video latentlerini çözümlen.
Bir konvolüsyonel çözücüden farklı olarak bu, kendisi küçük bir difüzyon modelidir: latentlerden oluşturulan bir bağlam hacmine koşullu olarak pikselleri gürültüden arındırır, bu nedenle bir zamanlayıcıya (scheduler) ve bir üreteceğe (generator) ihtiyaç duyar. output_type="latent" ile çalıştırılan herhangi bir LTX-2 hattıyla eşleştirin; bu yol zaten latent istatistiklerini uyguladığı için denormalize=False parametresini iletin.
call[[diffusers.LTX2VideoDiffusionDecodePipeline.call]]
__call__(latents: Tensor, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str = 'pil', return_dict: bool = True, denormalize: bool = True)
Parametreler:
latents (torch.Tensor) : (B, C, F, H, W) biçiminde latents. output_type="latent" ile çalıştırılan bir LTX-2 hattının, zaten normalizasyonu kaldırılmış latents döndürdüğünü unutmayın; bu nedenle bunlar için denormalize=False parametresini iletin.
generator (torch.Generator, isteğe bağlı) : Dekoder, gürültüyü azalttığı gürültüyü örnekler, bu nedenle çözmenin tekrarlanabilir olmasını sağlamak için bir üreteç geçin.
output_type (str, isteğe bağlı, varsayılan "pil") : Çözümlenen videonun çıktı biçimi. "pil", "np", "pt" ve "latent" seçeneklerinden birini seçin.
return_dict (bool, isteğe bağlı, varsayılan True) : Düz bir tuple yerine LTX2VideoDecodeOutput döndürülüp döndürülmemesi.
denormalize (bool, isteğe bağlı, varsayılan True) : Çözümleme (decoding) öncesinde latent istatistiklerin uygulanıp uygulanmayacağı. Latentler zaten normalleştirilmemişse (denormalized) False olarak ayarlayın.
Dönüş: LTX2VideoDecodeOutput veya tuple
LTX2DurationHead[[diffusers.pipelines.ltx2.LTX2DurationHead]]
diffusers.pipelines.ltx2.LTX2DurationHead[[diffusers.pipelines.ltx2.LTX2DurationHead]]
diffusers.pipelines.ltx2.LTX2DurationHead(video_cross_attention_dim: int = 4096, audio_cross_attention_dim: int = 2048, pooler_hidden_dim: int = 256, num_queries: int = 1, num_pooler_heads: int = 4, mlp_hidden_dim: int = 256)
Parametreler:
video_cross_attention_dim (int, varsayılan 4096) : Video bağlayıcısı çıktısının genişliği.
audio_cross_attention_dim (int, varsayılan 2048) : Ses konnektörünün çıktı genişliği.
pooler_hidden_dim (int, varsayılan 256) : Her iki modalitenin de projelendirildiği ortak gizli boyut.
num_queries (int, varsayılan 1) : Öğrenilebilir havuzlama sorgularının sayısı.
num_pooler_heads (int, varsayılan 4) : Pooler tarafından kullanılan dikkat başlıkları.
mlp_hidden_dim (int, varsayılan 256) : Çıktı MLP'sinin gizli genişliği. mlp_hidden alt modülüyle çakışmayı önlemek için _dim son ekiyle adlandırılmıştır; aksi halde ConfigMixin.__getattr__ bu yapılandırma değeriyle gölgeleme yapardı.
LTX-2 metin bağlayıcı çıktılarından, bir başlığın ima ettiği çekimin doğal süresini tahmin eder.
Baş (head), modallardan bağımsızdır: video ve ses konnektör çıktılarından birini veya her ikisini de iletebilirsiniz. Modala özgü giriş projeksiyonları her akışı ortak bir pooler boyutuna eşler, öğrenilebilir modal gömme (embedding) değerleri akışları etiketleyerek pooler'ın onları ayırt etmesini sağlar ve küçük bir MLP, havuzlanmış (pooled) vektörü log-süre (log-duration) değerine dönüştürür. Regresyon hedefi log-saniye cinsinden eğitildiğinden forward üstel (exponentiate) işlemini uygular ve çağıranlar her zaman saniye cinsinden değer alır.
LTX-2.5 kontrol noktalarından itibaren sunulur.
forward[[diffusers.pipelines.ltx2.LTX2DurationHead.forward]]
forward(video_tokens: typing.Optional[torch.Tensor] = None, audio_tokens: typing.Optional[torch.Tensor] = None)
Parametreler:
video_tokens (torch.Tensor, şekli (batch_size, seq_len, video_cross_attention_dim), isteğe bağlı) : Video bağlayıcı çıktısı.
audio_tokens (torch.Tensor, şekli (batch_size, seq_len, audio_cross_attention_dim), isteğe bağlı) : Ses konnektörü çıktısı.
Dönüş: torch.Tensor, şekli (batch_size,)
saniye cinsinden tahmini süre.
predict_num_frames[[diffusers.pipelines.ltx2.LTX2DurationHead.predict_num_frames]]
predict_num_frames(video_tokens: typing.Optional[torch.Tensor] = None, audio_tokens: typing.Optional[torch.Tensor] = None, frame_rate: float, temporal_compression_ratio: int, min_seconds: float = 1.0, max_seconds: float = 20.0)
Parametreler:
video_tokens (torch.Tensor, isteğe bağlı) : Tek bir istem için video bağlayıcı çıktısı.
audio_tokens (torch.Tensor, isteğe bağlı) : Tek bir istem için ses bağlantı noktası çıktısı.
frame_rate (float) : Tahmin edilen süreyi kare sayısına dönüştürmek için kullanılan saniye başına kare sayısı.
temporal_compression_ratio (int) : Kare ızgarasını tanımlayan VAE'nin zamansal sıkıştırma oranı.
min_seconds (float, varsayılan 1.0) : Tahmin için alt sınır.
max_seconds (float, varsayılan 20.0) : Tahmin için üst sınır.
Dönüş: int
VAE'nin zamansal ızgarasında yer alan bir kare sayısı.
Bağlayıcı jetonlardan bir kare sayısı tahmin eder; sonuç [min_seconds, max_seconds] aralığına sıkıştırılır ve VAE'nin nedensel zaman ızgarasına (k * temporal_compression_ratio + 1) hizalanır.
Clamp, snapping uygulanmadan önce uygulanır: clamp edilmiş kare sayısı mutlaka ızgarayla hizalı olmayacağından, önce snapping uygulanması farklı bir sonuç verir. Snapping aşağı yuvarladığı için minimum değerin altına inebilir; bu durumda sonuç, kare sayısının sınırlar içinde kalmasını sağlamak için bir sonraki ızgara noktasına yukarı doğru snaplenir.
Dar sınırlar, hiç ızgara noktası içermeyen bir kare penceresine dönüşebilir -- 24 fps'de [1.0s, 1.02s] [24, 24] olarak yuvarlanır ve 24, 8k + 1 değildir. En yakın ızgara noktası kullanılır ve bir uyarı kaydedilir, çünkü bir ızgara adımından az aşmak, üretimi reddetmekten iyidir. Bu nedenle döndürülen sayı her zaman ızgarada olur, ancak bu durumda istenen sınırların hemen dışında kalabilir.
LTX2PipelineOutput[[diffusers.pipelines.ltx2.LTX2PipelineOutput]]
diffusers.pipelines.ltx2.LTX2PipelineOutput[[diffusers.pipelines.ltx2.LTX2PipelineOutput]]
diffusers.pipelines.ltx2.LTX2PipelineOutput(frames: Tensor, audio: Tensor)
Parametreler:
frames (torch.Tensor, np.ndarray veya list[list[PIL.Image.Image]]) : Video çıktıları listesi - batch_size, uzunluğunda iç içe geçmiş bir liste olabilir; her alt liste, num_frames. uzunluğunda gürültüsü azaltılmış PIL görüntü dizileri içerir. Ayrıca (batch_size, num_frames, channels, height, width) biçiminde bir NumPy dizi veya Torch tensörü de olabilir.
audio (torch.Tensor, np.ndarray) : TODO
LTX pipeline'leri için çıktı sınıfı.
LTX2ModularPipeline[[diffusers.LTX2ModularPipeline]]
diffusers.LTX2ModularPipeline[[diffusers.LTX2ModularPipeline]]
diffusers.LTX2ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
LTX-2 için bir ModularPipeline (ortak video + ses üretimi).
LTX2AutoBlocks[[diffusers.LTX2AutoBlocks]]
diffusers.LTX2AutoBlocks[[diffusers.LTX2AutoBlocks]]
diffusers.LTX2AutoBlocks()
LTX-2 için metinden videoya, görüntüden videoya, koşula videoya ve bağlam içi (IC-LoRA) üretimini (ortak video + ses) destekleyen otomatik bloklar.
Desteklenen iş akışları:
text2video:promptgerektiririmage2video:imagevepromptgerektirircondition:conditionsvepromptgerektiririn_context:reference_conditions,num_frames,promptgerektirir
Bileşenler: 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.
Çıktılar: videos (list): Oluşturulan videolar. audio (Tensor): Oluşturulan ses dalgası.
LTX25ModularPipeline[[diffusers.LTX25ModularPipeline]]
diffusers.LTX25ModularPipeline[[diffusers.LTX25ModularPipeline]]
diffusers.LTX25ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
LTX-2.5 için bir ModularPipeline (ortak video + ses üretimi).
LTX2ModularPipeline ile aynıdır; ancak varsayılan blokları, LTX-2.5 ve sonrası için yerel varsayılan olan difüzyon video kodlayıcısıyla çözer. Bir checkpoint, modular_model_index.json üzerinden buraya yönlendirilir.
LTX25AutoBlocks[[diffusers.LTX25AutoBlocks]]
diffusers.LTX25AutoBlocks[[diffusers.LTX25AutoBlocks]]
diffusers.LTX25AutoBlocks()
LTX-2.5 için metinden videoya, görüntüden videoya, koşula dayalı videoya ve bağlam içi (IC-LoRA) üretimi (ortak video + ses) destekleyen otomatik bloklar. LTX2AutoBlocks ile aynıdır; ancak LTX-2.5 ve sonrası için yerel varsayılan olan difüzyon çözücü olduğundan, video çözücü LTX2DiffusionVaeDecoderStep'tir. Bunun yerine konvolüsyonel VAE ile çözmek için çözümleme bloğunu değiştirin: blocks.sub_blocks["decode"] = LTX2AutoDecoderStep().
Desteklenen iş akışları:
text2video:promptgerektiririmage2video:imagevepromptgerektirircondition:conditionsvepromptgerektiririn_context:reference_conditions,num_frames,promptgerektirir
Bileşenler: 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'.
Çıktılar: videos (list): Oluşturulan videolar. audio (Tensor): Oluşturulan ses dalgası.
Xet Storage Details
- Size:
- 237 kB
- Xet hash:
- 1733131dfdaafd615689e1822ba544fb165ede0ce62b6bd5780292b072f783c8
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.