Diffusers documentation
LTX-2
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 boru hattını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 boru hattı bileşeninin mevcut olması gerekir. Bunu enable_prompt_enhancement=True ve bir system_prompt ile etkinleştirin (isteğe bağlı, Lightricks referans boru 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 dosyasının işaret ettiği, transformer/ içindeki distilled DiT ve açıkça yüklenmesi gereken, transformer_full/ içindeki tam/SFT DiT (bkz. Full / SFT transformer). Repo’daki scheduler/ konfigürasyonu, sigma zamanlamasının aynen kullanılması için distilled checkpoint’e göre ayarlanmıştır (use_dynamic_shifting=False, shift_terminal=None). two-stage generation için gereken her şey de orada mevcuttur: bir latent_upsampler/ alt klasörü ve repo kökünde bulunan 2. aşama distilled LoRA’sı, 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 + 1Damı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 değerinden kesinlikle 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 ile 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 çerçeve kadar eklenir, 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 bir 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 için tek geçişte 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
sınıf diffusers.LTX2Pipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
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
transformerile birlikte kullanılacak bir zamanlayıcı. - vae (AutoencoderKLLTXVideo) — Görselleri latent temsillere kodlamak ve latent temsillerden çözmek için 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 tokenization aracı. - tokenizer (
T5TokenizerFast) — Sınıfı T5TokenizerFast olan ikinci Tokenizer. - connectors (
LTX2TextConnectors) — Video ve audio 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__
< source >( prompt: str | list[str] = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 512width: int = 768num_frames: int | None = Nonemin_seconds: float = 1.0max_seconds: float = 20.0frame_rate: float = 24.0motion_speed: float = 1.0num_inference_steps: int = 30sigmas: list[float] | None = Nonetimesteps: list = Noneguidance_scale: float = 3.0stg_scale: float = 1.0modality_scale: float = 3.0guidance_rescale: float = 0.7audio_guidance_scale: float | None = 7.0audio_stg_scale: float | None = 1.0audio_modality_scale: float | None = 3.0audio_guidance_rescale: float | None = 0.7spatio_temporal_guidance_blocks: list[int] | None = [28]noise_scale: float = 0.0num_videos_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10output_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Parametreler
- prompt (
strveyalist[str], isteğe bağlı) — Görsel üretimi yönlendirmek için istem veya istemler. Tanımlanmadıysa bunun yerineprompt_embedsgeçirilmelidir. - negative_prompt (
strveyalist[str], isteğe bağlı) — Görsel üretimini yönlendirmemek için kullanılan istem veya istemler. Tanımlanmazsa, bunun yerinenegative_prompt_embedsparametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (guidance_scale < 1) yok sayılır. - height (
int, isteğe bağlı, varsayılan512) — Oluşturulan görüntünün piksel cinsinden yüksekliği. En iyi sonuçlar için varsayılan olarak 480 olarak ayarlanır. - width (
int, isteğe bağlı, varsayılan768) — Oluşturulan 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ınduration_headbileşeni varsa (LTX-2.5 kontrol noktaları ve sonrası) otomatik tahmin edilen bir süreye, aksi halde121değerine ayarlanır. Süreyi 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, isteğe bağlı, varsayılan1.0) —num_framesatlandığında ve birduration_headmevcut olduğunda, otomatik tahmin edilen sürenin alt sınırı.num_framesaçıkça ayarlandığında yok sayılır. - max_seconds (
float, isteğe bağlı, varsayılan20.0) —num_framesatlandığında ve birduration_headmevcut olduğunda, otomatik tahmin edilen sürenin üst sınırı.num_framesaçıkça ayarlandığında yok sayılır.min_secondsdeğerinden kesinlikle büyük olmalıdır. - frame_rate (
float, isteğe bağlı, varsayılan24.0) — Oluşturulan videonun saniyede kare sayısı (FPS). - motion_speed (
float, isteğe bağlı, varsayılan1.0) — Gerçek zamana göre hareket hızı. Konumsal gömlemelerframe_rate / motion_speeddeğ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çin0.2.frame_rateoynatma 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_timestepsmetodundasigmasargümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel sigmalar. Tanımlanmamışsa,num_inference_stepsgeçirildiğinde varsayılan davranış kullanılacaktır. - timesteps (
list[int], isteğe bağlı) —timestepsargümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel zaman adımları.set_timestepsyönteminde. Tanımlanmamışsa,num_inference_stepsgeçirildiğinde varsayılan davranış kullanılacaktır. Azalan sırada olmalıdır. - guidance_scale (
float, isteğe bağlı, varsayılan4.0) — Classifier-Free Diffusion Guidance'de tanımlandığı gibi yönlendirme ölçeği.guidance_scale, Imagen Paper'deki 2. denkleminw'si olarak tanımlanır. Yönlendirme ölçeği,guidance_scale > 1olarak ayarlanarak etkinleştirilir. Daha yüksek yönlendirme ölçeği, genellikle daha düşük görüntü kalitesi pahasına,promptile yakından ilişkili görüntülerin üretilmesini teşvik eder. Video modallitesi için kullanılır (ses modallitesi için ayrı biraudio_guidance_scaledeğeri vardır). - stg_scale (
float, isteğe bağlı, varsayılan0.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.0varsayılan değeri, STG'nin devre dışı bırakıldığını ifade eder. - modality_scale (
float, isteğe bağlı, varsayılan1.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.0varsayı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ü, zero terminal SNR kullanılırken aşırı pozlamayı düzeltmelidir. Video modali için kullanılır. - audio_guidance_scale (
float, isteğe bağlı, varsayılanNone) — Negatif prompt 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'in videoguidance_scale'ine göre daha yüksek olması gerektiğini önermektedir (ör. LTX-2.3 için video için 3.0 ve ses için 7.0 önerilmektedir).Noneise, video değeri olanguidance_scalevarsayılan olarak kullanılır. - audio_stg_scale (
float, isteğe bağlı, varsayılanNone) — 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.Noneise, video değeri olanstg_scalevarsayılan olarak kullanılır. - audio_modality_scale (
float, isteğe bağlı, varsayılanNone) — 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.Noneise, video değeri olanmodality_scalevarsayılan olarak kullanılır. - audio_guidance_rescale (
float, isteğe bağlı, varsayılanNone) — Ses modallitesi için ayrı bir rehberlik yeniden ölçekleme faktörü.Noneise, varsayılan olarak video değeri olanguidance_rescalekullanılır. - spatio_temporal_guidance_blocks (
list[int], isteğe bağlı, varsayılanNone) — STG'nin uygulanacağı, sıfır tabanlı transformer blok indeksleri. STG kullanılıyorsa (stg_scaleveyaaudio_stg_scale0'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ılan0.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ünün, gürültü azaltma işlemine devam etmeden öncelatentsveaudio_latentsüzerine uygulanması. - num_videos_per_prompt (
int, isteğe bağlı, varsayılan 1) — Her prompt için üretilecek video sayısı. - generator (
torch.Generatorveyalist[torch.Generator], isteğe bağlı) — Üretimi deterministik hale getirmek için bir veya torch üreteci listesi. - latents (
torch.Tensor, isteğe bağlı) — Video üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenmiş önceden oluşturulmuş gürültülü latensler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgelegeneratorkullanılarak örneklemeye dayalı bir latens 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 örneklenmiş önceden oluşturulmuş gürültülü latentler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgelegeneratorkullanılarak örneklemeye dayalı bir latent tensörü oluşturulur. - prompt_embeds (
torch.Tensor, isteğe bağlı) — Önceden oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. prompt ağırlıklandırma. Sağlanmazsa, metin gömme değerleripromptgirdi 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. - 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_promptgirdi 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ılan0.0) — Üretilen videonun çözümlendiği zaman adımı. - decode_noise_scale (
float, varsayılanNone) — Çö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 (
boolisteğe bağlı, varsayılanTrue) — Çapraz dikkat modülasyon parametrelerini hesaplarırken çapraz modalite (video için çapraz modalite ses, ses için video) sigma değerinin kullanılıp kullanılmayacağını belirtir.TrueLTX-2.3/2.5 davranışıdır;Falseise eski LTX-2.0 davranışıdır. - system_prompt (
str, isteğe bağlı, varsayılanNone) — İsteği iyileştirmek için kullanılacak isteğe bağlı sistem istemi. Sistem istemi, orijinalprompt'ten koşullu üretim için iyileştirilmiş bir istem üretmek üzere istem iyileştirici tarafından (bir Gemma koşullu üretim modeli — yapılandırılmışsa özelprompt_enhancerbileşeni, değilse anatext_encoder) kullanılır. Sağlanmaz ve özel birprompt_enhanceryapılandırılmışsa (LTX-2.5), varsayılan olarakLTX2_5_T2V_DEFAULT_SYSTEM_PROMPT(diffusers.pipelines.ltx2.utilsiçinden) kullanılır — bkz.enable_prompt_enhancement. - enable_prompt_enhancement (
bool, isteğe bağlı, varsayılanFalse) — İstem güçlendirme çalıştırılacak mı. Lightricks referans boru hatlarıyla uyumlu şekilde isteğe bağlıdır.Trueolduğunda vesystem_promptatlandığında, özel birprompt_enhanceryapılandırılmışsa LTX-2.5LTX2_5_T2V_DEFAULT_SYSTEM_PROMPTkullanır; LTX-2.0/2.3 için açık birsystem_promptgereklidir. - prompt_max_new_tokens (
int, isteğe bağlı, varsayılanNone) — İpucu geliştirme (prompt enhancement) sırasında oluşturulacak en fazla yeni token sayısı. Belirtilmezse, özel Gemma 4prompt_enhancer(LTX-2.5) için 600 veya Gemma 3text_encoderyedeği (LTX-2.0/2.3) için 512 kullanılır. - prompt_enhancement_kwargs (
dict[str, Any], isteğe bağlı, varsayılanNone) — İpucu geliştiricisinin.generateçağrısı için anahtar kelime argümanları. Verilmezse, her zaman geliştirme işlemini yapan modelle eşleşir: özel birprompt_enhancer(LTX-2.5) kullanıldığındado_sample=False, no_repeat_ngram_size=5(açgözlü) veyatext_encoderyedeği (LTX-2.0/2.3) içindo_sample=True, temperature=0.7. Daha fazla ayrıntı için bkz. https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate. - prompt_enhancement_seed (
int, isteğe bağlı, varsayılan10) — İ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") — Görsel oluşturma çıktısının biçimi. Şunlardan birini seçin: PIL:PIL.Image.Imageveyanp.array. - return_dict (
bool, isteğe bağlı, varsayılanTrue) — Düz bir tuple yerine~pipelines.ltx.LTX2PipelineOutputdöndürülüp döndürülmemesi. - attention_kwargs (
dict, isteğe bağlı) — Belirtilirse, diffusers.models.attention_processor içindekiself.processoraltında tanımlananAttentionProcessor'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_inputstarafı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 thecallback_on_step_endfunction. The tensors specified in the list will be passed ascallback_kwargsargument. You will only be able to include variables listed in the._callback_tensor_inputsattribute of your pipeline class. - max_sequence_length (
int, isteğe bağlı, varsayılan1024) —promptile kullanılacak maksimum dizi uzunluğu.
Dönüş değeri
~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
< source >( prompt: str | list[str]negative_prompt: str | list[str] | None = Nonedo_classifier_free_guidance: bool = Truenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024scale_factor: int = 8device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Parametreler
- prompt (
strveyalist[str], isteğe bağlı) — kodlanacak prompt - negative_prompt (
strveyalist[str], isteğe bağlı) — Görsel üretimini yönlendirmemek için kullanılan istem veya istemler. Tanımlanmamışsa, bunun yerinenegative_prompt_embedsparametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (yaniguidance_scaledeğeri1'den küçükse) yok sayılır. - do_classifier_free_guidance (
bool, isteğe bağlı, varsayılanTrue) — Classifier free guidance kullanılacak mı? - num_videos_per_prompt (
int, isteğe bağlı, varsayılan 1) — Her prompt 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ı) — Önceden oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. prompt ağırlıklandırma. Sağlanmazsa, metin gömme değerleripromptgirdi argümanından oluşturulur. - negative_prompt_embeds (
torch.Tensor, isteğe bağlı) — Önceden 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_promptgirdi 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
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
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 halde 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
sınıf diffusers.LTX2ImageToVideoPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
Görselden video üretimi için pipeline.
Referans: https://github.com/Lightricks/LTX-Video
TODO
__call__
< source >( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Noneprompt: str | list[str] = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 512width: int = 768num_frames: int | None = Nonemin_seconds: float = 1.0max_seconds: float = 20.0frame_rate: float = 24.0motion_speed: float = 1.0num_inference_steps: int = 30sigmas: list[float] | None = Nonetimesteps: list[int] | None = Noneguidance_scale: float = 3.0stg_scale: float = 1.0modality_scale: float = 3.0guidance_rescale: float = 0.7audio_guidance_scale: float | None = 7.0audio_stg_scale: float | None = 1.0audio_modality_scale: float | None = 3.0audio_guidance_rescale: float | None = 0.7spatio_temporal_guidance_blocks: list[int] | None = [28]noise_scale: float = 0.0num_videos_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10image_crf: int | None = Noneoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Parametreler
- image (
PipelineImageInput) — Üretimin koşullandırılacağı girdi görüntüsü. Bir görüntü, görüntü listesi veyatorch.Tensorolmalıdır. - prompt (
strveyalist[str], isteğe bağlı) — Görsel üretimi yönlendirmek için istem veya istemler. Tanımlanmadıysa bunun yerineprompt_embedsgeçirilmelidir. - negative_prompt (
strveyalist[str], isteğe bağlı) — Görsel üretimini yönlendirmemek için kullanılan istem veya istemler. Tanımlanmazsa, bunun yerinenegative_prompt_embedsparametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (guidance_scale < 1) yok sayılır. - height (
int, isteğe bağlı, varsayılan512) — Oluşturulan görüntünün piksel cinsinden yüksekliği. En iyi sonuçlar için varsayılan olarak 480 olarak ayarlanır. - width (
int, isteğe bağlı, varsayılan768) — Oluşturulan 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ınduration_headbileşeni varsa (LTX-2.5 kontrol noktaları ve sonrası) otomatik tahmin edilen bir süreye, aksi halde121değerine ayarlanır. Süreyi 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, isteğe bağlı, varsayılan1.0) —num_framesatlandığında ve birduration_headmevcut olduğunda, otomatik tahmin edilen sürenin alt sınırı.num_framesaçıkça ayarlandığında yok sayılır. - max_seconds (
float, isteğe bağlı, varsayılan20.0) —num_framesatlandığında ve birduration_headmevcut olduğunda, otomatik tahmin edilen sürenin üst sınırı.num_framesaçıkça ayarlandığında yok sayılır.min_secondsdeğerinden kesinlikle büyük olmalıdır. - frame_rate (
float, isteğe bağlı, varsayılan24.0) — Oluşturulan videonun saniyede kare sayısı (FPS). - motion_speed (
float, isteğe bağlı, varsayılan1.0) — Gerçek zamana göre hareket hızı. Konumsal gömlemelerframe_rate / motion_speeddeğ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çin0.2.frame_rateoynatma 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_timestepsmetodundasigmasargümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel sigmalar. Tanımlanmamışsa,num_inference_stepsgeçirildiğinde varsayılan davranış kullanılacaktır. - timesteps (
List[int], isteğe bağlı) —timestepsargümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel zaman adımları.set_timestepsyönteminde. Tanımlanmamışsa,num_inference_stepsgeçirildiğinde varsayılan davranış kullanılacaktır. Azalan sırada olmalıdır. - guidance_scale (
float, isteğe bağlı, varsayılan4.0) — Classifier-Free Diffusion Guidance'de tanımlandığı gibi yönlendirme ölçeği.guidance_scale, Imagen Paper'deki 2. denkleminw'si olarak tanımlanır. Yönlendirme ölçeği,guidance_scale > 1olarak ayarlanarak etkinleştirilir. Daha yüksek yönlendirme ölçeği, genellikle daha düşük görüntü kalitesi pahasına,promptile yakından ilişkili görüntülerin üretilmesini teşvik eder. Video modallitesi için kullanılır (ses modallitesi için ayrı biraudio_guidance_scaledeğeri vardır). - stg_scale (
float, isteğe bağlı, varsayılan0.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.0varsayılan değeri, STG'nin devre dışı bırakıldığını ifade eder. - modality_scale (
float, isteğe bağlı, varsayılan1.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.0varsayı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ü, zero terminal SNR kullanılırken aşırı pozlamayı düzeltmelidir. Video modali için kullanılır. - audio_guidance_scale (
float, isteğe bağlı, varsayılanNone) — Negatif prompt 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'in videoguidance_scale'ine göre daha yüksek olması gerektiğini önermektedir (ör. LTX-2.3 için video için 3.0 ve ses için 7.0 önerilmektedir).Noneise, video değeri olanguidance_scalevarsayılan olarak kullanılır. - audio_stg_scale (
float, isteğe bağlı, varsayılanNone) — 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.Noneise, video değeri olanstg_scalevarsayılan olarak kullanılır. - audio_modality_scale (
float, isteğe bağlı, varsayılanNone) — 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.Noneise, video değeri olanmodality_scalevarsayılan olarak kullanılır. - audio_guidance_rescale (
float, isteğe bağlı, varsayılanNone) — Ses modallitesi için ayrı bir rehberlik yeniden ölçekleme faktörü.Noneise, varsayılan olarak video değeri olanguidance_rescalekullanılır. - spatio_temporal_guidance_blocks (
list[int], isteğe bağlı, varsayılanNone) — STG'nin uygulanacağı, sıfır tabanlı transformer blok indeksleri. STG kullanılıyorsa (stg_scaleveyaaudio_stg_scale0'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ılan0.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ünün, gürültü azaltma işlemine devam etmeden öncelatentsveaudio_latentsüzerine uygulanması. - num_videos_per_prompt (
int, isteğe bağlı, varsayılan 1) — Her prompt için üretilecek video sayısı. - generator (
torch.Generatorveyalist[torch.Generator], isteğe bağlı) — Üretimi deterministik hale getirmek için bir veya torch üreteci listesi. - latents (
torch.Tensor, isteğe bağlı) — Video üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenmiş önceden oluşturulmuş gürültülü latensler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgelegeneratorkullanılarak örneklemeye dayalı bir latens 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 örneklenmiş önceden oluşturulmuş gürültülü latentler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgelegeneratorkullanılarak örneklemeye dayalı bir latent tensörü oluşturulur. - prompt_embeds (
torch.Tensor, isteğe bağlı) — Önceden oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. prompt ağırlıklandırma. Sağlanmazsa, metin gömme değerleripromptgirdi 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. - 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_promptgirdi 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ılan0.0) — Üretilen videonun çözümlendiği zaman adımı. - decode_noise_scale (
float, varsayılanNone) — Çö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 (
boolisteğe bağlı, varsayılanTrue) — Çapraz dikkat modülasyon parametrelerini hesaplarırken çapraz modalite (video için çapraz modalite ses, ses için video) sigma değerinin kullanılıp kullanılmayacağını belirtir.TrueLTX-2.3/2.5 davranışıdır;Falseise eski LTX-2.0 davranışıdır. - system_prompt (
str, isteğe bağlı, varsayılanNone) — İstemci iyileştirme için kullanılacak isteğe bağlı sistem istemcisi. Sistem istemcisi, istemci iyileştirici tarafından (bir Gemma koşullu üretim modeli — yapılandırılmışsa özelprompt_enhancerbileşeni, değilse anatext_encoder) orijinalpromptve üretimi koşullandırmak için ilkimagekullanılarak iyileştirilmiş bir istemci oluşturmak için kullanılır. Sağlanmazsa ve özel birprompt_enhanceryapılandırılmışsa (LTX-2.5), varsayılan olarakLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT(kaynağıdiffusers.pipelines.ltx2.utils) kullanılır — bkz.enable_prompt_enhancement. - enable_prompt_enhancement (
bool, isteğe bağlı, varsayılanFalse) — İstem güçlendirme çalıştırılacak mı. Lightricks referans boru hatlarıyla uyumlu şekilde isteğe bağlıdır.Trueolduğunda vesystem_promptatlandığında, özel birprompt_enhanceryapılandırılmışsa LTX-2.5LTX2_5_I2V_DEFAULT_SYSTEM_PROMPTkullanır; LTX-2.0/2.3 için açık birsystem_promptgereklidir. - prompt_max_new_tokens (
int, isteğe bağlı, varsayılanNone) — İpucu geliştirme (prompt enhancement) sırasında oluşturulacak en fazla yeni token sayısı. Belirtilmezse, özel Gemma 4prompt_enhancer(LTX-2.5) için 600 veya Gemma 3text_encoderyedeği (LTX-2.0/2.3) için 512 kullanılır. - prompt_enhancement_kwargs (
dict[str, Any], isteğe bağlı, varsayılanNone) — İpucu geliştiricisinin.generateçağrısı için anahtar kelime argümanları. Verilmezse, her zaman geliştirme işlemini yapan modelle eşleşir: özel birprompt_enhancer(LTX-2.5) kullanıldığındado_sample=False, no_repeat_ngram_size=3(açgözlü) veyatext_encoderyedeği (LTX-2.0/2.3) içindo_sample=True, temperature=0.7. Daha fazla ayrıntı için bkz. https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate. - prompt_enhancement_seed (
int, isteğe bağlı, varsayılan10) — İstem geliştirme sırasında herhangi bir rastgele işlem için rastgele tohum. - image_crf (
int, isteğe bağlı, varsayılanNone) — VAE kodlamadan önce koşullandırmaimage'ını yeniden sıkıştırmak için kullanılan H.264 CRF değeri; modelin eğitim sırasında karşılaştığı sıkıştırma ile eşleşir.None, “model varsayılanını kullan” demektir (LTX-2.3'e kadar 33, LTX-2.5 için 18). Yeniden sıkıştırma atlanacaksa0geçirin. Yeniden sıkıştırma çalıştığındaPIL.Image.Imagegerektirir. - output_type (
str, isteğe bağlı, varsayılan"pil") — Görsel oluşturma çıktısının biçimi. Şunlardan birini seçin: PIL:PIL.Image.Imageveyanp.array. - return_dict (
bool, isteğe bağlı, varsayılanTrue) — Düz bir tuple yerine~pipelines.ltx.LTX2PipelineOutputdöndürülüp döndürülmemesi. - attention_kwargs (
dict, isteğe bağlı) — Belirtilirse, diffusers.models.attention_processor içindekiself.processoraltında tanımlananAttentionProcessor'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_inputstarafından belirtilen tüm tensörlerin listesini içerir. - callback_on_step_end_tensor_inputs (
List, optional) — The list of tensor inputs for thecallback_on_step_endfunction. The tensors specified in the list will be passed ascallback_kwargsargument. You will only be able to include variables listed in the._callback_tensor_inputsattribute of your pipeline class. - max_sequence_length (
int, isteğe bağlı, varsayılan1024) —promptile kullanılacak maksimum dizi uzunluğu.
Dönüş değeri
~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
< source >( prompt: str | list[str]negative_prompt: str | list[str] | None = Nonedo_classifier_free_guidance: bool = Truenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024scale_factor: int = 8device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Parametreler
- prompt (
strveyalist[str], isteğe bağlı) — kodlanacak prompt - negative_prompt (
strveyalist[str], isteğe bağlı) — Görsel üretimini yönlendirmemek için kullanılan istem veya istemler. Tanımlanmamışsa, bunun yerinenegative_prompt_embedsparametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (yaniguidance_scaledeğeri1'den küçükse) yok sayılır. - do_classifier_free_guidance (
bool, isteğe bağlı, varsayılanTrue) — Classifier free guidance kullanılacak mı? - num_videos_per_prompt (
int, isteğe bağlı, varsayılan 1) — Her prompt 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ı) — Önceden oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. prompt ağırlıklandırma. Sağlanmazsa, metin gömme değerleripromptgirdi argümanından oluşturulur. - negative_prompt_embeds (
torch.Tensor, isteğe bağlı) — Önceden 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_promptgirdi 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
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
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 halde 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
sınıf diffusers.LTX2ConditionPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEaudio_scheduler: diffusers.schedulers.scheduling_flow_match_euler_discrete.FlowMatchEulerDiscreteScheduler | None = Noneprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
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__
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneprompt: str | list[str] = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 512width: int = 768num_frames: int | None = Nonemin_seconds: float = 1.0max_seconds: float = 20.0frame_rate: float = 24.0motion_speed: float = 1.0num_inference_steps: int = 30sigmas: list[float] | None = Nonetimesteps: list[float] | None = Noneguidance_scale: float = 3.0stg_scale: float = 1.0modality_scale: float = 3.0guidance_rescale: float = 0.7audio_guidance_scale: float | None = 7.0audio_stg_scale: float | None = 1.0audio_modality_scale: float | None = 3.0audio_guidance_rescale: float | None = 0.7spatio_temporal_guidance_blocks: list[int] | None = [28]noise_scale: float | None = Nonenum_videos_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10output_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Parametreler
- conditions (
List[LTXVideoCondition], *optional*) — Video üretimi için kare koşullandırma öğelerinin listesi. - prompt (
strveyaList[str], isteğe bağlı) — Görsel üretimi yönlendirmek için istem veya istemler. Tanımlanmadıysa bunun yerineprompt_embedsgeçirilmelidir. - negative_prompt (
strveyaList[str], isteğe bağlı) — Görsel üretimini yönlendirmemesi gereken istem veya istemler. Tanımlanmazsa, bunun yerinenegative_prompt_embedsparametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (guidance_scale < 1) yok sayılır. - height (
int, isteğe bağlı, varsayılan512) — Oluşturulan görüntünün piksel cinsinden yüksekliği. En iyi sonuçlar için varsayılan olarak 480 olarak ayarlanır. - width (
int, isteğe bağlı, varsayılan768) — Oluşturulan 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ınduration_headbileşeni varsa (LTX-2.5 kontrol noktaları ve sonrası) otomatik tahmin edilen bir süreye, aksi halde121değerine ayarlanır. Süreyi 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, isteğe bağlı, varsayılan1.0) —num_framesatlandığında ve birduration_headmevcut olduğunda, otomatik tahmin edilen sürenin alt sınırı.num_framesaçıkça ayarlandığında yok sayılır. - max_seconds (
float, isteğe bağlı, varsayılan20.0) —num_framesatlandığında ve birduration_headmevcut olduğunda, otomatik tahmin edilen sürenin üst sınırı.num_framesaçıkça ayarlandığında yok sayılır.min_secondsdeğerinden kesinlikle büyük olmalıdır. - frame_rate (
float, isteğe bağlı, varsayılan24.0) — Oluşturulan videonun saniyede kare sayısı (FPS). - motion_speed (
float, isteğe bağlı, varsayılan1.0) — Gerçek zamana göre hareket hızı. Konumsal gömlemelerframe_rate / motion_speeddeğ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çin0.2.frame_rateoynatma 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_timestepsmetodundasigmasargümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel sigmalar. Tanımlanmamışsa,num_inference_stepsgeçirildiğinde varsayılan davranış kullanılacaktır. - timesteps (
List[int], isteğe bağlı) —timestepsargümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel zaman adımları.set_timestepsyönteminde. Tanımlanmamışsa,num_inference_stepsgeçirildiğinde varsayılan davranış kullanılacaktır. Azalan sırada olmalıdır. - guidance_scale (
float, isteğe bağlı, varsayılan4.0) — Classifier-Free Diffusion Guidance'de tanımlandığı gibi yönlendirme ölçeği.guidance_scale, Imagen Paper'deki 2. denkleminw'si olarak tanımlanır. Yönlendirme ölçeği,guidance_scale > 1olarak ayarlanarak etkinleştirilir. Daha yüksek yönlendirme ölçeği, genellikle daha düşük görüntü kalitesi pahasına,promptile yakından ilişkili görüntülerin üretilmesini teşvik eder. Video modallitesi için kullanılır (ses modallitesi için ayrı biraudio_guidance_scaledeğeri vardır). - stg_scale (
float, isteğe bağlı, varsayılan0.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.0varsayılan değeri, STG'nin devre dışı bırakıldığını ifade eder. - modality_scale (
float, isteğe bağlı, varsayılan1.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.0varsayı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ü, zero terminal SNR kullanılırken aşırı pozlamayı düzeltmelidir. Video modali için kullanılır. - audio_guidance_scale (
float, isteğe bağlı, varsayılanNone) — Negatif prompt 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'in videoguidance_scale'ine göre daha yüksek olması gerektiğini önermektedir (ör. LTX-2.3 için video için 3.0 ve ses için 7.0 önerilmektedir).Noneise, video değeri olanguidance_scalevarsayılan olarak kullanılır. - audio_stg_scale (
float, isteğe bağlı, varsayılanNone) — 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.Noneise, video değeri olanstg_scalevarsayılan olarak kullanılır. - audio_modality_scale (
float, isteğe bağlı, varsayılanNone) — 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.Noneise, video değeri olanmodality_scalevarsayılan olarak kullanılır. - audio_guidance_rescale (
float, isteğe bağlı, varsayılanNone) — Ses modallitesi için ayrı bir rehberlik yeniden ölçekleme faktörü.Noneise, varsayılan olarak video değeri olanguidance_rescalekullanılır. - spatio_temporal_guidance_blocks (
list[int], isteğe bağlı, varsayılanNone) — STG'nin uygulanacağı, sıfır tabanlı transformer blok indeksleri. STG kullanılıyorsa (stg_scaleveyaaudio_stg_scale0'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ılanNone) — 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ünün, gürültü azaltma işlemine devam etmeden öncelatentsveaudio_latentsüzerine uygulanması. Ayarlanmazsa, sigma zaman çizelgesinden çıkarılır. - num_videos_per_prompt (
int, isteğe bağlı, varsayılan 1) — Her prompt için üretilecek video sayısı. - generator (
torch.GeneratorveyaList[torch.Generator], isteğe bağlı) — Üretimi deterministik hale getirmek için bir veya torch üreteci listesi. - latents (
torch.Tensor, isteğe bağlı) — Video üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenmiş önceden oluşturulmuş gürültülü latensler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgelegeneratorkullanılarak örneklemeye dayalı bir latens 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 örneklenmiş önceden oluşturulmuş gürültülü latentler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgelegeneratorkullanılarak örneklemeye dayalı bir latent tensörü oluşturulur. - prompt_embeds (
torch.Tensor, isteğe bağlı) — Önceden oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. prompt ağırlıklandırma. Sağlanmazsa, metin gömme değerleripromptgirdi 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. - 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_promptgirdi 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ılan0.0) — Üretilen videonun çözümlendiği zaman adımı. - decode_noise_scale (
float, varsayılanNone) — Çö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 (
boolisteğe bağlı, varsayılanTrue) — Çapraz dikkat modülasyon parametrelerini hesaplarırken çapraz modalite (video için çapraz modalite ses, ses için video) sigma değerinin kullanılıp kullanılmayacağını belirtir.TrueLTX-2.3/2.5 davranışıdır;Falseise eski LTX-2.0 davranışıdır. - system_prompt (
str, isteğe bağlı, varsayılanNone) — İsteği iyileştirmek için kullanılacak isteğe bağlı sistem istemi. Sistem istemi, orijinalprompt'ten (ve mevcut ise bir koşullandırma görselinden) üretimi koşullandırmak için iyileştirilmiş bir istem oluşturmak üzere istem iyileştirici tarafından (bir Gemma koşullu üretim modeli — yapılandırılmışsa özelprompt_enhancerbileşeni, değilse anatext_encoder) kullanılır. Sağlanmazsa ve özel birprompt_enhanceryapılandırılmışsa (LTX-2.5), bir koşullandırma görseli mevcut olduğunda varsayılan olarakLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, aksi takdirdeLTX2_5_T2V_DEFAULT_SYSTEM_PROMPTkullanılır — bkz.enable_prompt_enhancement. - enable_prompt_enhancement (
bool, isteğe bağlı, varsayılanFalse) — İstem güçlendirme çalıştırılacak mı. Lightricks referans boru hatlarıyla uyumlu şekilde isteğe bağlıdır.Trueolduğunda vesystem_promptatlandığında, LTX-2.5, koşullandırma görüntüsünün mevcut olup olmadığına göreLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT/LTX2_5_T2V_DEFAULT_SYSTEM_PROMPTdeğerlerinden birini seçer. - prompt_max_new_tokens (
int, isteğe bağlı, varsayılanNone) — İpucu geliştirme (prompt enhancement) sırasında oluşturulacak en fazla yeni token sayısı. Belirtilmezse, özel Gemma 4prompt_enhancer(LTX-2.5) için 600 veya Gemma 3text_encoderyedeği (LTX-2.0/2.3) için 512 kullanılır. - prompt_enhancement_kwargs (
dict[str, Any], isteğe bağlı, varsayılanNone) — İpucu geliştiricisinin.generateçağrısı için anahtar kelime argümanları. Verilmezse, her zaman geliştirme işlemini yapan modelle eşleşir: özel birprompt_enhancer(LTX-2.5) kullanıldığındado_sample=False, no_repeat_ngram_size=5(açgözlü) veyatext_encoderyedeği (LTX-2.0/2.3) içindo_sample=True, temperature=0.7. Daha fazla ayrıntı için bkz. https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate. - prompt_enhancement_seed (
int, isteğe bağlı, varsayılan10) — İ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") — Görsel oluşturma çıktısının biçimi. Şunlardan birini seçin: PIL:PIL.Image.Imageveyanp.array. - return_dict (
bool, isteğe bağlı, varsayılanTrue) — Düz bir tuple yerine~pipelines.ltx.LTX2PipelineOutputdöndürülüp döndürülmemesi. - attention_kwargs (
dict, isteğe bağlı) — Belirtilirse, diffusers.models.attention_processor içindekiself.processoraltında tanımlananAttentionProcessor'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_inputstarafından belirtilen tüm tensörlerin listesini içerir. - callback_on_step_end_tensor_inputs (
List, optional) — The list of tensor inputs for thecallback_on_step_endfunction. The tensors specified in the list will be passed ascallback_kwargsargument. You will only be able to include variables listed in the._callback_tensor_inputsattribute of your pipeline class. - max_sequence_length (
int, isteğe bağlı, varsayılan1024) —promptile kullanılacak maksimum dizi uzunluğu.
Dönüş değeri
~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
< source >( latents: Tensorconditioning_mask: Tensorcondition_latents: listcondition_strengths: listcondition_indices: listlatent_height: intlatent_width: int ) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
Parametreler
- latents (
torch.Tensor) — [batch_size, patch_seq_len, hidden_dim] biçiminde başlangıç paketlenmiş (patchified) latents. - conditioning_mask (
torch.Tensor) — [batch_size, patch_seq_len, 1] biçiminde, değerleri [0, 1] aralığında olan başlangıç paketlenmiş (patchified) koşullama maskesi. Burada 0, gürültü giderme modelinin çıktısının tamamen kullanılacağını; 1 ise koşulun tamamen kullanılacağını belirtir.
Dönüş değeri
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 eşleşir). Sıfır olmayan latent indekslerdeki koşullar, prepare_keyframe_extras aracılığıyla ayrı ana kare jetonları olarak eklenir (VideoConditionByKeyframeIndex ile eşleşir) ve burada atlanır.
encode_prompt
< source >( prompt: str | list[str]negative_prompt: str | list[str] | None = Nonedo_classifier_free_guidance: bool = Truenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024scale_factor: int = 8device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Parametreler
- prompt (
strveyalist[str], isteğe bağlı) — kodlanacak prompt - negative_prompt (
strveyalist[str], isteğe bağlı) — Görsel üretimini yönlendirmemek için kullanılan istem veya istemler. Tanımlanmamışsa, bunun yerinenegative_prompt_embedsparametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (yaniguidance_scaledeğeri1'den küçükse) yok sayılır. - do_classifier_free_guidance (
bool, isteğe bağlı, varsayılanTrue) — Classifier free guidance kullanılacak mı? - num_videos_per_prompt (
int, isteğe bağlı, varsayılan 1) — Her prompt 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ı) — Önceden oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. prompt ağırlıklandırma. Sağlanmazsa, metin gömme değerleripromptgirdi argümanından oluşturulur. - negative_prompt_embeds (
torch.Tensor, isteğe bağlı) — Önceden 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_promptgirdi 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
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
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 halde 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
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Nonebatch_size: int = 1num_channels_latents: int = 128height: int = 512width: int = 768num_frames: int = 121frame_rate: float = 24.0noise_scale: float = 1.0dtype: typing.Optional[torch.dtype] = Nonedevice: typing.Optional[torch.device] = Nonegenerator: typing.Optional[torch.Generator] = Nonelatents: typing.Optional[torch.Tensor] = None )
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) — gürültü kaldırma döngüsünün mevcut zaman adımı 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ü latensler (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, ya da ilk kare dışındaki koşullar yoksaNone.
preprocess_conditions
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 512width: int = 768num_frames: int = 121device: typing.Optional[torch.device] = None ) → Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Parametreler
- conditions (
LTX2VideoConditionveyaList[LTX2VideoCondition], opsiyonel, varsayılanNone) — Görsel/video koşul örneklerinin listesi. - height (
int, isteğe bağlı, varsayılan512) — Piksel cinsinden istenen yükseklik. - width (
int, isteğe bağlı, varsayılan768) — İstenen piksel cinsinden genişlik. - num_frames (
int, isteğe bağlı, varsayılan121) — Oluşturulan videodaki istenen kare sayısı. - device (
torch.device, isteğe bağlı, varsayılanNone) — Ön işlenmiş görüntü/video tensörlerinin yerleştirileceği cihaz.
Dönüş değeri
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
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Koşullandırma dizisini izin verilen kare sayısına kırpın.
LTX2DFRPipeline
sınıf diffusers.LTX2DFRPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
Parametreler
- scheduler (FlowMatchEulerDiscreteScheduler) —
Kodlanmış video latentlerini gürültüden arındırmak için
transformerile birlikte kullanılacak bir zamanlayıcı. - vae (AutoencoderKLLTX2Video) — Video'ları latent temsillere kodlamak ve latent temsillerden video'ları çözmek için Varyasyonel Oto-Kodlayıcı (VAE) Modeli.
- audio_vae (AutoencoderKLLTX2Audio) — Ses spektrogramlarını kodlamak ve çözmek için kullanılan Ses VAE'si.
- text_encoder (
Gemma3ForConditionalGenerationveyaGemma4UnifiedForConditionalGeneration) — Metin kodlayıcı modeli. - tokenizer (
GemmaTokenizerveyaGemmaTokenizerFast) — Metin kodlayıcı için tokenleştirici. - connectors (
LTX2TextConnectors) — Video ve audio 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 (
LTX2VocoderveyaLTX2VocoderWithBWE) — Mel spektrogramlarını ses dalga formlarına dönüştürmek için kullanılan vokoder. - processor (
ProcessorMixin, isteğe bağlı) — İstem geliştirme sohbet şablonlaması için kullanılan işlemci. - prompt_enhancer (
Gemma4ForConditionalGeneration, isteğe bağlı) — Özel prompt iyileştirme modeli (LTX-2.5). - duration_head (
LTX2DurationHead, isteğe bağlı) —num_framessağlanmadığında, prompt gömlemelerindennum_framesdeğ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 ekstra 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 tam çözünürlükte yükseltilmiş yuvalar ve bir IC-LoRA referansıyla 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__
< source >( prompt: str | list[str] = Noneconditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 704width: int = 1216num_frames: int | None = Noneframe_rate: float = 24.0min_seconds: float = 1.0max_seconds: float = 20.0latents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Nonekeyframes_latents: typing.Optional[torch.Tensor] = Nonekeyframe_positions: list[int] | None = Nonereference_latents: typing.Optional[torch.Tensor] = Nonereference_downscale_factor: int = 2guidance_keyframe_latents: typing.Optional[torch.Tensor] = Noneguidance_keyframe_positions: list[int] | None = Noneguidance_keyframe_strength: float = 1.0generate_slots: bool = Truesigmas: list = [1.0, 0.99375, 0.9875, 0.98125, 0.975, 0.909375, 0.725, 0.421875]noise_scale: float | None = Nonefreeze_audio: bool = Falsevideo_tiles: list[diffusers.pipelines.ltx2.dfr_layout.LTX2DFREpilogueTile] | None = Nonenum_videos_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10output_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 1024 ) → LTX2DFRPipelineOutput or tuple
Parametreler
- prompt (
strveyaList[str], isteğe bağlı) — Video üretimini yönlendirmek için istem veya istemler. Tanımlanmadıysa,prompt_embedsparametresinin geçirilmesi gerekir. - conditions (
LTX2VideoConditionveyaList[LTX2VideoCondition], isteğe bağlı) — Kare düzeyinde görüntü veya video koşulları.index, bu geçişinnum_framesdeğerindeki bir latent indeksidir. - height (
int, isteğe bağlı, varsayılan704) — Son bileşik çıktı değil, bu geçişin piksel cinsinden yüksekliği. - width (
int, isteğe bağlı, varsayılan1216) — Bu geçişin piksel cinsinden genişliği. - num_frames (
int, isteğe bağlı) — Bu geçişin, iç tuval dolgusundan önceki piksel kare sayısı. Verilmezse, süreduration_headtarafından istemden tahmin edilir.(num_frames - 1) % 8 == 0koşulunu sağlamalıdır. - frame_rate (
float, isteğe bağlı, varsayılan24.0) — Bu geçişin oynatma fps değeri. Bu değer 30'un üzerindeyse RoPE zamanı 60'a sabitlenir. - min_seconds (
float, isteğe bağlı, varsayılan1.0) —num_framesatlandığında otomatik tahmin edilen sürenin alt sınırı. - max_seconds (
float, isteğe bağlı, varsayılan20.0) —num_framesatlandığı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 latents. - 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; ancak birleştirilmiş bir tarifin teslim edilen dalga formu 1. aşamanınkidir ve çağıran tarafından saklanır. - keyframes_latents (
torch.Tensor, isteğe bağlı) —generate_slots=Truekullanıldığında kullanılan ham(batch_size, channels, num_slots, height, width)slot başlangıç değerleri. - keyframe_positions (
list[int], isteğe bağlı) — Oluşturulan slotların piksel-kare dizinleri. Varsayılan olarakresolve_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ılan2) — 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ş rehberlik ana kareleri(batch_size, channels, K, height, width)— epilog yolu. Üretilmemiş yuvalar. - guidance_keyframe_positions (
list[int], isteğe bağlı) —guidance_keyframe_latentsiçin piksel-kare dizinleri. - guidance_keyframe_strength (
float, isteğe bağlı, varsayılan1.0) — Sabitlenmiş yönlendirme anahtar kareleri için koşullandırma gücü. - generate_slots (
bool, isteğe bağlı, varsayılanTrue) — Üretilen keyframe-slot jetonlarını ekler. Epilog bu değeriFalseolarak ayarlar ve bunun yerineguidance_keyframe_latentssabitlenir. - sigmas (
list[float], isteğe bağlı) — Bu geçiş için, son0.0değeri hariç gürültü zamanlaması. - noise_scale (
float, isteğe bağlı) — Koşulsuz tokenlerin başladığı gürültü seviyesi. Varsayılan değerisigmas[0]'dır. - freeze_audio (
bool, isteğe bağlı, varsayılanFalse) — Ses sinyalini sigma 0'da sabit tutar (epilog / dondurulmuş bir 1. aşama dalga formunu takip ederken). - video_tiles (
list[LTX2DFREpilogueTile], isteğe bağlı) —epilogue_tiles()işlevinden gelen 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 tuvalde adım atabilir: her adım, her döşeme 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 belirteç 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 prompt için üretilecek video sayısı. - generator (
torch.Generatorveyalist[torch.Generator], isteğe bağlı) — Tekrarlanabilirlik 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. - decode_timestep (
float, varsayılan0.0) — Üretilen videonun çözümlendiği zaman adımı. - decode_noise_scale (
float, varsayılanNone) — Çözme sırasında gürültü ölçeği. - use_cross_timestep (
bool, isteğe bağlı, varsayılanTrue) — Çapraz dikkat modülasyonu için çapraz modalite sigma kullanılacak mı. LTX-2.3+ içinTrue. - system_prompt (
str, isteğe bağlı) — İsteğe bağlı prompt iyileştirme sistem promptu.enable_prompt_enhancementbölümüne bakın. - enable_prompt_enhancement (
bool, isteğe bağlı, varsayılanFalse) — Prompt enhancement çalıştırılacak mı. - prompt_max_new_tokens (
int, isteğe bağlı) — İpucu geliştirme (prompt enhancement) sırasında oluşturulacak en fazla yeni token 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ılan10) — İ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ılanTrue) — 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 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"]) — Çağrı geri (callback) fonksiyonu için girdi tensörleri. - max_sequence_length (
int, isteğe bağlı, varsayılan1024) — Metin istemi için maksimum dizi uzunluğu.
Dönüş değeri
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
< source >( latents: Tensorconditioning_mask: Tensorclean_latents: Tensorvideo_coords: Tensorkeyframes_mask: Tensorprompt_embeds: Tensoraudio_prompt_embeds: Tensorprompt_attention_mask: Tensorsigmas: listframe_rate: floataudio_latents: Tensorfreeze_audio: bool = Falsevideo_tile_plan: list | None = Nonegenerator: typing.Optional[torch.Generator] = Noneuse_cross_timestep: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Noneprogress_bar = Nonestep_offset: int = 0callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] | None = None )
Parametreler
- sigmas (
list[float]) — Bu geçiş için, son0.0değeri hariç gürültü zamanlaması. - freeze_audio (
bool, isteğe bağlı, varsayılanFalse) — Ses-eğik dikkat (cross-attention) çalışmaya devam ederkenaudio_latents’i temiz tutar (timestep/sigma 0, ses Euler adımı yok).audio_latentsNoneise 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 gelen karot başına token planı. Verildiğinde, her adım dönüştürücüyü karot başına bir kez çalıştırır ve tahminleri harmanlar; böylece örnekleyici yine de tek bir tam tuval üzerinde adım atar ve karotlar 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) — Hattın tüm zaman çizelgesi içinde bu geçişin ilk adımının indeksi;callback_on_step_endve paylaşılan 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 kullanılır, bu nedenle 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ı yok) 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. Zamanlı 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 halde 0.95 gücündeki dikiş çapaları aşınır.
encode_conditions
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | Noneheight: intwidth: intnum_frames: intdevice: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = Nonegenerator: typing.Optional[torch.Generator] = None )
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ü
zamanla rafineleme turları, bir koşulun konumunu 2 ** round ile ölçekler ve karot başına yeniden tabanlar; bu işlemi yapmak için aynı sabit görüntüyü karot başına bir kez 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
< source >( prompt: str | list[str]num_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Parametreler
- prompt (
strveyalist[str], isteğe bağlı) — kodlanacak prompt - 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ı) — Önceden oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. prompt ağırlıklandırma. Sağlanmazsa, metin gömme değerleripromptgirdi argümanından oluşturulur. - prompt_attention_mask (
torch.Tensor, isteğe bağlı) —prompt_embedsiç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
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
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 halde 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
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Nonecondition_latents: list[tuple[int, torch.Tensor, float, int]] | None = Nonekeyframe_latents: list[tuple[int, torch.Tensor, float]] | None = Noneslot_frame_indices: list[int] | None = Noneslot_initial_latents: typing.Optional[torch.Tensor] = Nonereference_latents: typing.Optional[torch.Tensor] = Nonereference_downscale_factor: int = 1batch_size: int = 1num_channels_latents: int = 128height: int = 512width: int = 768num_frames: int = 121frame_rate: float = 24.0noise_scale: float = 1.0dtype: typing.Optional[torch.dtype] = Nonedevice: typing.Optional[torch.device] = Nonegenerator: typing.Optional[torch.Generator] = Nonelatents: typing.Optional[torch.Tensor] = Nonelatents_normalized: bool = True ) → tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, slice | None]
Parametreler
- conditions (
list[LTX2VideoCondition], isteğe bağlı) — Latent indekse göre konumlandırılan kare düzeyinde görüntü / video koşulları. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], isteğe bağlı) —conditionsiçin önceden kodlanmış yer tutucu,(pixel_frame_index, latent, strength, num_pixel_frames)biçiminde. Zamanla rafineleme turu, bir koşulun konumunu2 ** roundile ölçeklediği ve sonucun genellikle bir latent sınırına denk gelmediği için latent değil piksel indeksi kullanılır — sadece eklenmiş bir anahtar kare belirteci orada durabilir ve piksel bazında yerleştirilir.pixel_frame_index == 0hâlâ “ilk kareyi değiştir” anlamına gelir. - keyframe_latents (
list[tuple[int, torch.Tensor, float]], isteğe bağlı) — Zaten kodlanmış ana kare yönlendirmesi,(pixel_frame_index, latent, strength)biçiminde; buradalatent(batch_size, num_channels_latents, 1, latent_height, latent_width)şekline sahiptir. Ö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ı) — Oluşturulan anahtar kare yuvalarının piksel-kare konumları. - slot_initial_latents (
torch.Tensor, isteğe bağlı) —(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)içeriği, gürültü eklenmeden önce slot tokenlarına yazılır. - 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ılan1) — 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 latents ham (normalleştirilmemiş) değerlerdir; bu sınırdan geçerkenlatents_normalized=Falseparametresini iletin. Zaten VAE-normalize uzayda döngü yapan tile döngüleri varsayılan değeri korur. - latents_normalized (
bool, varsayılanTrue) —latents,slot_initial_latents,reference_latentsvekeyframe_latentsdeğerlerinin zaten VAE-normalize edilip edilmediğini belirtir. Dahili karolar döngüleriTruegeçirir; her pipeline__call__Falsegeçirir. - noise_scale (
float, varsayılan1.0) — Koşulsuz tokenlerin başlatıldığı gürültü seviyesi, yani zamanlamanın ilk sigma değeri.
Dönüş değeri
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. Bunlar, DFR'e ek kareleri veren ana kare yuvalarıdır;slot_initial_latentsbu yuvaların içeriğini başlatır.reference_latents, 1. aşamanın yarı çözünürlüklü latentini tamamen temiz bir IC-LoRA referansı olarak ekler; bu referans, hedef koordinat uzayına eşlenebilmesi için uzamsal koordinatlarıreference_downscale_factorile ölçeklenir.
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 ve sıfırları 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
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 512width: int = 768num_frames: int = 121device: typing.Optional[torch.device] = None ) → Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Parametreler
- conditions (
LTX2VideoConditionveyaList[LTX2VideoCondition], opsiyonel, varsayılanNone) — Görsel/video koşul örneklerinin listesi. - height (
int, isteğe bağlı, varsayılan512) — Piksel cinsinden istenen yükseklik. - width (
int, isteğe bağlı, varsayılan768) — İstenen piksel cinsinden genişlik. - num_frames (
int, isteğe bağlı, varsayılan121) — Oluşturulan videodaki istenen kare sayısı. - device (
torch.device, isteğe bağlı, varsayılanNone) — Ön işlenmiş görüntü/video tensörlerinin yerleştirileceği cihaz.
Dönüş değeri
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
< source >( keyframe_latents: Tensordecode_timestep: floatdecode_noise_scale: floatseed: intdevice: devicedtype: dtype ) → torch.Tensor
Parametreler
- keyframe_latents (
torch.Tensor) — Önceki bir geçişin döndürdüğü gibi, ham(batch_size, C, K, H, W)anahtar kareleri taşır. - seed (
int) — Temel tohum;i. düzlemseed + 4000 + ialtında çözümlenir, böylece bir düzlemin pikselleri, ondan önce kaç düzlem çözümlendiğinden bağımsızdır.
Dönüş değeri
torch.Tensor
Ham (batch_size, C, K, 2H, 2W) latentleri, doğrudan guidance_keyframe_latents olarak 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 bunları üretmesi istenmek yerine verilir. Piksele çözme, Lanczos ile x2 ölçekleme 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
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Koşullandırma dizisini izin verilen kare sayısına kırpın.
LTX2DFRTemporalRefinePipeline
sınıf diffusers.LTX2DFRTemporalRefinePipeline
< source >( scheduler: LTXEulerAncestralRFSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEtemporal_latent_upsampler: LTX2LatentUpsamplerModel )
Parametreler
- scheduler (
LTXEulerAncestralRFScheduler) — Rectified-flow parametrelendirmesindeki Ancestral Euler zamanlayıcısı. DFR zaman tarifesiyle eşleşmesi içineta=0.5ile oluşturulur. - vae (AutoencoderKLLTX2Video) — Video'ları latent temsillere kodlamak ve latent temsillerden video'ları çözmek için Varyasyonel Oto-Kodlayıcı (VAE) Modeli.
- audio_vae (AutoencoderKLLTX2Audio) — Ses spektrogramlarını kodlamak ve çözmek için kullanılan Ses VAE'si.
- text_encoder (
Gemma3ForConditionalGenerationveyaGemma4UnifiedForConditionalGeneration) — Metin kodlayıcı modeli. - tokenizer (
GemmaTokenizerveyaGemmaTokenizerFast) — Metin kodlayıcı için tokenleştirici. - connectors (
LTX2TextConnectors) — Video ve audio 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 (
LTX2VocoderveyaLTX2VocoderWithBWE) — Mel spektrogramlarını ses dalga formlarına dönüştürmek için kullanılan vokoder. - temporal_latent_upsampler (
LTX2LatentUpsamplerModel) — Turunun başlangıcında uygulanan zamansal x2 latent upsampler.
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. / 2. aşama / uzamsal epilog, LTX2DFRPipeline üzerinden FlowMatchEulerDiscreteScheduler'da kalır. Bu hattı tur başına bir kez çağırın; çağıran taraf 2x / 4x için döngüye girer.
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__
< source >( prompt: str | list[str] = Nonelatents: Tensor = Nonekeyframes_latents: Tensor = Nonekeyframe_positions: list = Noneaudio_latents: Tensor = Noneconditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 704width: int = 1216num_frames: int = 121frame_rate: float = 24.0source_seconds: float | None = Nonecondition_num_frames: int | None = Noneround_index: int = 1sigmas: list = [0.975, 0.909375, 0.725, 0.421875]noise_scale: float | None = Nonegenerator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Trueoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 1024 ) → LTX2DFRPipelineOutput or tuple
Parametreler
- prompt (
strveyaList[str], isteğe bağlı) — Video üretimini yönlendirmek için istem veya istemler. Tanımlanmadıysa,prompt_embedsparametresinin geçirilmesi gerekir. - latents (
torch.Tensor) — input tuvalinin ham video latentsleri,(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 tuvalindekeyframes_latentsiçin piksel-kare indeksleri. - audio_latents (
torch.Tensor) — Donmuş 1. aşama sesi, 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 (
LTX2VideoConditionveyaList[LTX2VideoCondition], isteğe bağlı) —condition_num_frames(orijinal istek) üzerinde indekslenen kare düzeyi koşulları. Her turda bir koşulun piksel konumu2 ** round_indexile ölçeklenir. - height (
int, isteğe bağlı, varsayılan704) — Bu geçişin piksel yüksekliği (gelen videoyla aynı). - width (
int, isteğe bağlı, varsayılan1216) — Bu geçişin piksel genişliği. - num_frames (
int, isteğe bağlı, varsayılan121) — girdi tuvalinin piksel kare sayısı (kırpılmamış). - frame_rate (
float, isteğe bağlı, varsayılan24.0) — girdinin oynatma fps değeri. Yuvarlama bunu ikiye katlar. - source_seconds (
float, isteğe bağlı) — Dondurulmuş 1. aşama sesinin süresi. Varsayılan değerinum_frames / frame_rate'tir ve bu, ilk tur için doğrudur; sonraki turlarda karoların kaymaması için orijinal 1. aşama süresi geçirilmelidir. - condition_num_frames (
int, isteğe bağlı) —conditionskodlamak için kullanılan orijinal üretimnum_frames. Varsayılan değerinum_frames'tir. Dolgu (padding) veya önceki bir turdan sonra,index=-1'in dolgulu kuyruğa sarmalamasını önlemek için orijinal isteği iletin. - round_index (
int, isteğe bağlı, varsayılan1) — 1 tabanlı tur numarası. Karo, atal gürültüyüseed + 1000 * round_index + tileolarak tohumlar ve koşullar2 ** round_indexile ölçeklenir. - sigmas (
list[float], isteğe bağlı) — Bu turun karoları için damıtılmış zaman çizelgesi, son0.0değeri hariç. - noise_scale (
float, isteğe bağlı) — Koşulsuz tokenlerin başladığı gürültü seviyesi. Varsayılan değerisigmas[0]'dır. - generator (
torch.Generatorveyalist[torch.Generator], isteğe bağlı) — Tekrarlanabilirlik için rastgele üreteç(ler). Atal çekimleri, bu üretecininitial_seed()değerinden türetilen, karoya özel 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. - decode_timestep (
float, varsayılan0.0) — Üretilen videonun çözümlendiği zaman adımı. - decode_noise_scale (
float, varsayılanNone) — Çözme sırasında gürültü ölçeği. - use_cross_timestep (
bool, isteğe bağlı, varsayılanTrue) — Çapraz dikkat modülasyonu için çapraz modalite sigma kullanılacak mı. LTX-2.3+ içinTrue. - 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ılanTrue) — 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 iletilen ek kwargs. - callback_on_step_end (
Callable, isteğe bağlı) — Her gürültü azaltma adımının sonunda, tüm karolar boyunca çağrılan bir işlev. - callback_on_step_end_tensor_inputs (
List, isteğe bağlı, varsayılan["latents"]) — Çağrı geri (callback) fonksiyonu için girdi tensörleri. - max_sequence_length (
int, isteğe bağlı, varsayılan1024) — Metin istemi için maksimum dizi uzunluğu.
Dönüş değeri
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
< source >( latents: Tensorconditioning_mask: Tensorclean_latents: Tensorvideo_coords: Tensorkeyframes_mask: Tensorprompt_embeds: Tensoraudio_prompt_embeds: Tensorprompt_attention_mask: Tensorsigmas: listframe_rate: floataudio_latents: Tensorfreeze_audio: bool = Falsevideo_tile_plan: list | None = Nonegenerator: typing.Optional[torch.Generator] = Noneuse_cross_timestep: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Noneprogress_bar = Nonestep_offset: int = 0callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] | None = None )
Parametreler
- sigmas (
list[float]) — Bu geçiş için, son0.0değeri hariç gürültü zamanlaması. - freeze_audio (
bool, isteğe bağlı, varsayılanFalse) — Ses-eğik dikkat (cross-attention) çalışmaya devam ederkenaudio_latents’i temiz tutar (timestep/sigma 0, ses Euler adımı yok).audio_latentsNoneise 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 gelen karot başına token planı. Verildiğinde, her adım dönüştürücüyü karot başına bir kez çalıştırır ve tahminleri harmanlar; böylece örnekleyici yine de tek bir tam tuval üzerinde adım atar ve karotlar 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) — Hattın tüm zaman çizelgesi içinde bu geçişin ilk adımının indeksi;callback_on_step_endve paylaşılan 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 kullanılır, bu nedenle 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ı yok) 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. Zamanlı 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 halde 0.95 gücündeki dikiş çapaları aşınır.
encode_conditions
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | Noneheight: intwidth: intnum_frames: intdevice: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = Nonegenerator: typing.Optional[torch.Generator] = None )
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ü
zamanla rafineleme turları, bir koşulun konumunu 2 ** round ile ölçekler ve karot başına yeniden tabanlar; bu işlemi yapmak için aynı sabit görüntüyü karot başına bir kez 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
< source >( prompt: str | list[str]num_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Parametreler
- prompt (
strveyalist[str], isteğe bağlı) — kodlanacak prompt - 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ı) — Önceden oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. prompt ağırlıklandırma. Sağlanmazsa, metin gömme değerleripromptgirdi argümanından oluşturulur. - prompt_attention_mask (
torch.Tensor, isteğe bağlı) —prompt_embedsiç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
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Nonecondition_latents: list[tuple[int, torch.Tensor, float, int]] | None = Nonekeyframe_latents: list[tuple[int, torch.Tensor, float]] | None = Noneslot_frame_indices: list[int] | None = Noneslot_initial_latents: typing.Optional[torch.Tensor] = Nonereference_latents: typing.Optional[torch.Tensor] = Nonereference_downscale_factor: int = 1batch_size: int = 1num_channels_latents: int = 128height: int = 512width: int = 768num_frames: int = 121frame_rate: float = 24.0noise_scale: float = 1.0dtype: typing.Optional[torch.dtype] = Nonedevice: typing.Optional[torch.device] = Nonegenerator: typing.Optional[torch.Generator] = Nonelatents: typing.Optional[torch.Tensor] = Nonelatents_normalized: bool = True ) → tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, slice | None]
Parametreler
- conditions (
list[LTX2VideoCondition], isteğe bağlı) — Latent indekse göre konumlandırılan kare düzeyinde görüntü / video koşulları. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], isteğe bağlı) —conditionsiçin önceden kodlanmış yer tutucu,(pixel_frame_index, latent, strength, num_pixel_frames)biçiminde. Zamanla rafineleme turu, bir koşulun konumunu2 ** roundile ölçeklediği ve sonucun genellikle bir latent sınırına denk gelmediği için latent değil piksel indeksi kullanılır — sadece eklenmiş bir anahtar kare belirteci orada durabilir ve piksel bazında yerleştirilir.pixel_frame_index == 0hâlâ “ilk kareyi değiştir” anlamına gelir. - keyframe_latents (
list[tuple[int, torch.Tensor, float]], isteğe bağlı) — Zaten kodlanmış ana kare yönlendirmesi,(pixel_frame_index, latent, strength)biçiminde; buradalatent(batch_size, num_channels_latents, 1, latent_height, latent_width)şekline sahiptir. Ö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ı) — Oluşturulan anahtar kare yuvalarının piksel-kare konumları. - slot_initial_latents (
torch.Tensor, isteğe bağlı) —(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)içeriği, gürültü eklenmeden önce slot tokenlarına yazılır. - 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ılan1) — 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 latents ham (normalleştirilmemiş) değerlerdir; bu sınırdan geçerkenlatents_normalized=Falseparametresini iletin. Zaten VAE-normalize uzayda döngü yapan tile döngüleri varsayılan değeri korur. - latents_normalized (
bool, varsayılanTrue) —latents,slot_initial_latents,reference_latentsvekeyframe_latentsdeğerlerinin zaten VAE-normalize edilip edilmediğini belirtir. Dahili karolar döngüleriTruegeçirir; her pipeline__call__Falsegeçirir. - noise_scale (
float, varsayılan1.0) — Koşulsuz tokenlerin başlatıldığı gürültü seviyesi, yani zamanlamanın ilk sigma değeri.
Dönüş değeri
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. Bunlar, DFR'e ek kareleri veren ana kare yuvalarıdır;slot_initial_latentsbu yuvaların içeriğini başlatır.reference_latents, 1. aşamanın yarı çözünürlüklü latentini tamamen temiz bir IC-LoRA referansı olarak ekler; bu referans, hedef koordinat uzayına eşlenebilmesi için uzamsal koordinatlarıreference_downscale_factorile ölçeklenir.
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 ve sıfırları 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
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 512width: int = 768num_frames: int = 121device: typing.Optional[torch.device] = None ) → Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Parametreler
- conditions (
LTX2VideoConditionveyaList[LTX2VideoCondition], opsiyonel, varsayılanNone) — Görsel/video koşul örneklerinin listesi. - height (
int, isteğe bağlı, varsayılan512) — Piksel cinsinden istenen yükseklik. - width (
int, isteğe bağlı, varsayılan768) — İstenen piksel cinsinden genişlik. - num_frames (
int, isteğe bağlı, varsayılan121) — Oluşturulan videodaki istenen kare sayısı. - device (
torch.device, isteğe bağlı, varsayılanNone) — Ön işlenmiş görüntü/video tensörlerinin yerleştirileceği cihaz.
Dönüş değeri
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
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Koşullandırma dizisini izin verilen kare sayısına kırpın.
upsampler'ı normalize edilmiş latentler üzerinde çalıştırın; beklediği gibi ham VAE latent uzayından geçiş yapın.
LTX2DFRPipelineOutput
sınıf diffusers.LTX2DFRPipelineOutput
< source >( frames: Tensoraudio: Tensorkeyframes: typing.Optional[torch.Tensor] = Nonekeyframe_positions: list[int] | None = None )
Parametreler
- frames (
torch.Tensor,np.ndarrayveya 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ı) — Şekli(batch_size, num_channels, num_keyframes, latent_height, latent_width)olan üretilmiş 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;keyframesNoneolduğundaNone. Zaman turundan sonra bunlar orijinalnum_framesdeğerinden yeniden türetilemez ve sonraki aşamaya aktarılmalıdır.
DFR hatları için çıktı sınıfı.
LTX2LatentUpsamplePipeline
sınıf diffusers.LTX2LatentUpsamplePipeline
< source >( vae: AutoencoderKLLTX2Videolatent_upsampler: LTX2LatentUpsamplerModel )
__call__
< source >( video: list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]] | None = Noneheight: int = 512width: int = 768num_frames: int = 121spatial_patch_size: int = 1temporal_patch_size: int = 1latents: typing.Optional[torch.Tensor] = Nonelatents_normalized: bool = Falsedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneadain_factor: float = 0.0tone_map_compression_ratio: float = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneoutput_type: str | None = 'pil'return_dict: bool = True ) → ~pipelines.ltx.LTXPipelineOutput or tuple
Parametreler
- video (
list[PipelineImageInput], isteğe bağlı) — Yukarı örneklenmesi gereken video (örneğin bir LTX 2.0 ilk aşama çıktısı). Sağlanmazsa,latentssağlanmalıdır. - height (
int, isteğe bağlı, varsayılan512) — 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ılan768) — Girdi videosunun piksel cinsinden genişliği (daha yüksek bir çözünürlüğe sahip olacak olan üretilen video değil). - num_frames (
int, isteğe bağlı, varsayılan121) — Girdi videosundaki kare sayısı. - spatial_patch_size (
int, isteğe bağlı, varsayılan1) — Video latentlerinin uzamsal yama boyutu.latentssağlandığında, açma işlemi gerekiyorsa kullanılır. - temporal_patch_size (
int, isteğe bağlı, varsayılan1) — Video latentlerinin zamansal yama boyutu.latentssağlandığında ve açma işlemi gerekiyorsa kullanılır. - latents (
torch.Tensor, isteğe bağlı) — Önceden oluşturulmuş video latentsleri. Bu,videoargü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ılanFalse) —latentssağlanıyorsa,latents'in VAE latent ortalama ve standart sapması kullanılarak normalize edilip edilmediğini belirtir.Trueise,latents, latent upsampler'a sağlanmadan önce denormalize edilir. - decode_timestep (
float, varsayılan0.0) — Üretilen videonun çözümlendiği zaman adımı. - decode_noise_scale (
float, varsayılanNone) — Çö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, isteğe bağlı, varsayılan0.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, isteğe bağlı, varsayılan0.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 kullanışlı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.Generatorveyalist[torch.Generator], isteğe bağlı) — Üretimi deterministik hale getirmek için bir veya torch üreteci listesi. - output_type (
str, isteğe bağlı, varsayılan"pil") — Görsel oluşturma çıktısının biçimi. Şunlardan birini seçin: PIL:PIL.Image.Imageveyanp.array. - return_dict (
bool, isteğe bağlı, varsayılanTrue) — Düz bir tuple yerine~pipelines.ltx.LTXPipelineOutputdöndürülüp döndürülmemesi.
Dönüş değeri
~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
< source >( latents: Tensorreference_latents: Tensorfactor: float = 1.0 ) → torch.Tensor
Parametreler
- latents (
torch.Tensor) — Normalizasyon için girdi latensleri - reference_latents (
torch.Tensor) — Stil istatistiklerini sağlayan referans latentleri. - 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üş değeri
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
< source >( latents: Tensorcompression: float )
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
sınıf diffusers.LTX2VideoDiffusionDecodePipeline
< source >( diffusion_decoder: LTX2VideoDiffusionDecoderModelschedulervae: AutoencoderKLLTX2Video = None )
Parametreler
- diffusion_decoder (LTX2VideoDiffusionDecoderModel) — Difüzyon video çözücü.
- scheduler (FlowMatchEulerDiscreteScheduler) — Çözücünün gürültü azaltma adımlarını sürdüren zamanlayıcı.
- vae (AutoencoderKLLTX2Video, isteğe bağlı) — Yalnızca normalizasyonu kaldırma için kullanılan gizli istatistikler için başvurulur. 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__
< source >( latents: Tensorgenerator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneoutput_type: str = 'pil'return_dict: bool = Truedenormalize: bool = True ) → LTX2VideoDecodeOutput or tuple
Parametreler
- latents (
torch.Tensor) — Latents of shape(B, C, F, H, W). Note that an LTX-2 pipeline run withoutput_type="latent"returns latents that are already denormalized, so passdenormalize=Falsefor those. - generator (
torch.Generator, isteğe bağlı) — Çözücü, gürültüyü azalttığı gürültüyü örnekler; bu nedenle çözmenin tekrarlanabilir olması 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ılanTrue) — Düz bir tuple yerineLTX2VideoDecodeOutputdöndürülüp döndürülmemesi. - denormalize (
bool, isteğe bağlı, varsayılanTrue) — Çözümleme (decoding) öncesinde latent istatistiklerin uygulanıp uygulanmayacağı. Latentler zaten normalleştirilmişse (denormalized)Falseolarak ayarlayın.
Dönüş değeri
LTX2VideoDecodeOutput veya tuple
LTX2DurationHead
sınıf diffusers.pipelines.ltx2.LTX2DurationHead
< source >( video_cross_attention_dim: int = 4096audio_cross_attention_dim: int = 2048pooler_hidden_dim: int = 256num_queries: int = 1num_pooler_heads: int = 4mlp_hidden_dim: int = 256 )
Parametreler
- video_cross_attention_dim (
int, varsayılan4096) — Video bağlayıcısının çıktı genişliği. - audio_cross_attention_dim (
int, varsayılan2048) — Ses bağlayıcısı çıktısının genişliği. - pooler_hidden_dim (
int, varsayılan256) — Her iki modalitenin de projekte edildiği ortak gizli boyut. - num_queries (
int, varsayılan1) — Öğrenilebilir havuzlama sorgularının sayısı. - num_pooler_heads (
int, varsayılan4) — Pooler tarafından kullanılan dikkat başlıkları. - mlp_hidden_dim (
int, varsayılan256) — Çıktı MLP'sinin gizli genişliği.mlp_hiddenalt modülüyle çakışmayı önlemek için_dimson ekiyle adlandırılmıştır; aksi haldeConfigMixin.__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), modaliteden bağımsızdır: video ve ses konnektör çıktılarından birini veya her ikisini de iletin. Modallere özgü giriş projeksiyonları her akışı ortak bir pooler boyutuna eşler, öğrenilebilir modalite 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. Geri dönüş hedefi (regression target) 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
< source >( video_tokens: typing.Optional[torch.Tensor] = Noneaudio_tokens: typing.Optional[torch.Tensor] = None ) → torch.Tensor of shape (batch_size,)
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 bağlayıcı çıktısı.
Dönüş değeri
torch.Tensor, şekli (batch_size,)
saniye cinsinden tahmini süre.
predict_num_frames
< source >( video_tokens: typing.Optional[torch.Tensor] = Noneaudio_tokens: typing.Optional[torch.Tensor] = Noneframe_rate: floattemporal_compression_ratio: intmin_seconds: float = 1.0max_seconds: float = 20.0 ) → int
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 konnektörü çı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ılan1.0) — Tahminin alt sınırı. - max_seconds (
float, varsayılan20.0) — Tahminin üst sınırı.
Dönüş değeri
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ı 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] aralığı [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 daha 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
sınıf diffusers.pipelines.ltx2.LTX2PipelineOutput
< source >( frames: Tensoraudio: Tensor )
Parametreler
- frames (
torch.Tensor,np.ndarray, or list[list[PIL.Image.Image]]) — List of video outputs - It can be a nested list of lengthbatch_size,with each sub-list containing denoised PIL image sequences of lengthnum_frames.It can also be a NumPy array or Torch tensor of shape(batch_size, num_frames, channels, height, width). - audio (
torch.Tensor,np.ndarray) — TODO
LTX pipeline'leri için çıktı sınıfı.
LTX2ModularPipeline
sınıf diffusers.LTX2ModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
LTX-2 için bir ModularPipeline (ortak video + ses üretimi).
LTX2AutoBlocks
LTX-2 için metinden videoya, görüntüden videoya, koşula videoya ve bağlam içi (IC-LoRA) üretimi (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)
Girdiler:
prompt (str, isteğe bağlı):
Görsel üretimi yönlendirmek için istem veya istemler.
conditions (list, isteğe bağlı): LTX2VideoCondition (veya bunların listesi), üretilen videonun gizli kare indekslerinde görsel/video koşullarını yerleştiren.
enable_prompt_enhancement (bool, isteğe bağlı, varsayılan olarak False):
İstem iyileştiricisinin çalıştırılıp çalıştırılmayacağı. Lightricks referans hatlarıyla uyumlu şekilde, seçmeli olarak etkinleştirilir.
system_prompt (str, isteğe bağlı):
İyileştirme için sistem istemi. Bir PIL.Image.Image koşul karesi mevcut olduğunda varsayılan olarak LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, aksi halde LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT kullanılır.
prompt_max_new_tokens (int, isteğe bağlı):
İstem iyileştirme sırasında üretilecek en fazla yeni jeton sayısı. Varsayılan olarak 600, LTX-2.5 Gemma-4 iyileştiricisinin bütçesidir.
prompt_enhancement_kwargs (dict, isteğe bağlı):
İyileştiricinin .generate çağrısı için anahtar kelime argümanları. Varsayılan olarak açgözlü çözümlendirme kullanılır.
prompt_enhancement_seed (int, isteğe bağlı, varsayılan olarak 10):
İstem iyileştirme için rastgele tohum (LTX-2.5'in açgözlü çözümlendirmesi altında etkisizdir).
generator (Generator, isteğe bağlı):
Belirleyici üretim için Torch üreteci.
image (Image | list, isteğe bağlı):
Gürültü azaltma için referans görsel(ler). Tek bir görsel veya görseller listesi olabilir.
negative_prompt (str, isteğe bağlı):
Görsel üretimini yönlendirmemek için istem veya istemler.
max_sequence_length (int, isteğe bağlı, varsayılan olarak 1024):
İstem kodlaması için maksimum dizi uzunluğu.
min_seconds (float, isteğe bağlı, varsayılan olarak 1.0):
Otomatik tahmin edilen süre için alt sınır.
max_seconds (float, isteğe bağlı, varsayılan olarak 20.0):
Otomatik tahmin edilen süre için üst sınır. min_seconds değerinden kesinlikle büyük olmalıdır.
frame_rate (float, isteğe bağlı, varsayılan olarak 24.0):
Üretilen videonun saniyedeki kare sayısı.
height (int, isteğe bağlı, varsayılan olarak 512):
Üretilen görselin piksel cinsinden yüksekliği.
width (int, isteğe bağlı, varsayılan olarak 704):
Üretilen görselin piksel cinsinden genişliği.
image_crf (int, isteğe bağlı):
VAE kodlamadan önce koşullandırma image dosyasını yeniden sıkıştırmak için kullanılan H.264 CRF değeri; modelin eğitim sırasında karşılaştığı sıkıştırma ile eşleşir. None (varsayılan), metin kodlayıcı üretiminden çözülür (LTX-2.3'e kadar 33, LTX-2.5 için 18). Yeniden sıkıştırmanın atlanması için 0 geçin. Yeniden sıkıştırma çalıştığında bir PIL.Image.Image gerektirir.
num_frames (int, isteğe bağlı):
Üretilen videodaki kare sayısı. duration_head ile otomatik tahmin için atlayın (bkz. LTX2AutoDurationStep).
reference_conditions (list, isteğe bağlı): LTX2ReferenceCondition (veya bunların listesi), videoları IC-LoRA adaptörünün dikkat ettiği ek gizli jetonlara kodlanan.
reference_downscale_factor (int, isteğe bağlı, varsayılan olarak 1):
Hedef ve referans çözünürlükleri arasındaki oran; 2, referansın hedef çözünürlüğün yarısında ön işlendiği anlamına gelir. Uzamsal koordinatlar bu faktörle ölçeklenir, böylece referans jetonları hedef koordinat uzayına yerleşir. IC-LoRA'nın eğitim sırasında kullandığı faktörle eşleşmelidir.
conditioning_attention_strength (float, isteğe bağlı, varsayılan olarak 1.0):
Gürültülü jetonların ve referans jetonlarının birbirine ne kadar güçlü dikkat ettiğini kontrol eden [0, 1] aralığında bir skaler. 1.0 (varsayılan), dikkati maskesiz bırakır.
conditioning_attention_mask (Tensor, isteğe bağlı):
(1, 1, F, H, W) biçiminde, [0, 1] aralığında değerlere sahip, uzamsal olarak değişen dikkat gücü veren isteğe bağlı piksel uzaylı maskesi. Referansın gizli ızgarasına indirgenir ve conditioning_attention_strength ile çarpılır.
motion_speed (float, isteğe bağlı, varsayılan olarak 1.0):
Gerçek zamana göre hareket hızı. Konumsal gömüler frame_rate / motion_speed değerine koşullandırılır, bu nedenle 1'den küçük 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.
num_videos_per_prompt (int, isteğe bağlı, varsayılan olarak 1):
İstem başına üretilecek görsel sayısı.
condition_latents (list, isteğe bağlı):
Koşul başına [1, C, F, H, W] biçiminde normalize edilmiş VAE gizli değerleri.
condition_strengths (list, isteğe bağlı):
Koşul başına koşullandırma güçleri.
condition_indices (list, isteğe bağlı):
Koşulun uygulandığı koşul başına gizli kare indeksi.
condition_pixel_frames (list, isteğe bağlı):
Koşul başına kırpılmış piksel kare sayısı, tek kareli anahtar kare koordinatlarını sınırlamak için kullanılır.
reference_latents (Tensor, isteğe bağlı):
[1, total_reference_tokens, C] biçiminde paketlenmiş referans jetonları veya referans koşulları sağlanmadığında None (LTX2AutoReferenceEncoderStep atlanır).
reference_coords (Tensor, isteğe bağlı):
Referans jetonları için RoPE koordinatları.
reference_token_counts (list, isteğe bağlı):
reference_conditions sırasındaki referans başına jeton sayıları.
latents (Tensor):
Görsel üretimi için önceden üretilmiş gürültülü gizli değerler.
noise_scale (float, isteğe bağlı):
Koşulsuz jetonlar için başlangıç gürültü seviyesi. None (varsayılan), özel sigmas sağlandığında sigmas[0] olarak çözülür, aksi halde 1.0'dır.
sigmas (list, isteğe bağlı):
Gürültü azaltma süreci için özel sigmalar.
reference_cross_mask (Tensor, isteğe bağlı):
[1, num_ref_tokens] biçiminde, referans jetonu başına gürültülü<->referans dikkat güçleri.
num_inference_steps (int):
Gürültü azaltma adım sayısı.
timesteps (Tensor):
Gürültü azaltma süreci için zaman adımları.
audio_latents (Tensor):
İsteğe bağlı önceden kodlanmış ses gizli değerleri; sağlanmadığında rastgele gürültü kullanılır.
*denoiser_input_fields (None,isteğe bağlı):
Gürültü azaltıcı için koşullu model girdileri: örn. prompt_embeds, negative_prompt_embeds vb.
use_cross_timestep (bool,isteğe bağlı, varsayılan olarak True):
Dönüştürücünün ayrı bir jeton başına çapraz zaman adımına koşullandırılıp koşulandırılmayacağı (LTX-2.3+).
attention_kwargs (dict,isteğe bağlı):
Dikkat işlemcileri için ek anahtar kelime argümanları.
image_latents (Tensor,isteğe bağlı):
Görselden videoya koşullandırma için kullanılan VAE kodlu referans görsel gizli değerleri.
output_type (str,isteğe bağlı, varsayılan olarak pil):
Çıktı biçimi: ‘pil’, ‘np’, ‘pt’.
decode_timestep (None,isteğe bağlı, varsayılan olarak 0.0):
VAE'nin son gizli değerleri çözdüğü zaman adımı.
decode_noise_scale (None,isteğe bağlı*):
Çözümleme zaman adımındaki gizli değerlere uygulanan gürültü interpolasyon faktörü.
Çıktılar:
videos (list):
Oluşturulan videolar.
audio (Tensor):
Oluşturulan ses dalgası.
LTX25ModularPipeline
sınıf diffusers.LTX25ModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
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 kontrol noktası, modular_model_index.json üzerinden buraya yönlendirilir.
LTX25AutoBlocks
LTX-2.5 için metinden videoya, görüntüden videoya, koşula dayalı videoya ve bağlam içi (IC-LoRA) üretime (ortak video + ses) destek veren 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)
Girdiler:
prompt (str, isteğe bağlı):
Görsel üretimi yönlendirmek için istem veya istemler.
conditions (list, isteğe bağlı): LTX2VideoCondition (veya bunların listesi), üretilen videonun gizli kare indekslerinde görsel/video koşullarını yerleştiren.
enable_prompt_enhancement (bool, isteğe bağlı, varsayılan olarak False):
İstem iyileştiricinin çalıştırılıp çalıştırılmayacağı. Lightricks referans hatlarıyla uyumlu şekilde, seçmeli olarak etkinleştirilir.
system_prompt (str, isteğe bağlı):
İyileştirme için sistem istemi. Bir PIL.Image.Image koşul karesi mevcut olduğunda varsayılan olarak LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, aksi halde LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT kullanılır.
prompt_max_new_tokens (int, isteğe bağlı):
İstem iyileştirme sırasında üretilecek yeni jetonların maksimum sayısı. Varsayılan olarak 600'dür, bu da LTX-2.5 Gemma-4 iyileştiricisinin bütçesidir.
prompt_enhancement_kwargs (dict, isteğe bağlı):
İyileştiricinin .generate çağrısı için anahtar kelime argümanları. Varsayılan olarak açgözlü çözümlendirme kullanılır.
prompt_enhancement_seed (int, isteğe bağlı, varsayılan olarak 10):
İstem iyileştirme için rastgele tohum (LTX-2.5'in açgözlü çözümlendirmesi altında etkisizdir).
generator (Generator, isteğe bağlı):
Belirleyici üretim için Torch üreteci.
image (Image | list, isteğe bağlı):
Gürültü azaltma için referans görsel(ler). Tek bir görsel veya görseller listesi olabilir.
negative_prompt (str, isteğe bağlı):
Görsel üretimini yönlendirmemek için istem veya istemler.
max_sequence_length (int, isteğe bağlı, varsayılan olarak 1024):
İstem kodlaması için maksimum dizi uzunluğu.
min_seconds (float, isteğe bağlı, varsayılan olarak 1.0):
Otomatik tahmin edilen sürenin alt sınırı.
max_seconds (float, isteğe bağlı, varsayılan olarak 20.0):
Otomatik tahmin edilen sürenin üst sınırı. min_seconds değerinden kesinlikle büyük olmalıdır.
frame_rate (float, isteğe bağlı, varsayılan olarak 24.0):
Üretilen videonun saniyedeki kare sayısı.
height (int, isteğe bağlı, varsayılan olarak 512):
Üretilen görselin piksel cinsinden yüksekliği.
width (int, isteğe bağlı, varsayılan olarak 704):
Üretilen görselin piksel cinsinden genişliği.
image_crf (int, isteğe bağlı):
VAE kodlamadan önce koşullandırma image'ının yeniden sıkıştırılmasında kullanılan H.264 CRF değeri; modelin eğitim sırasında karşılaştığı sıkıştırmayla eşleşir. None (varsayılan), metin kodlayıcı üretiminden çözülür (LTX-2.3'e kadar 33, LTX-2.5 için 18). Yeniden sıkıştırmayı atlamak için 0 geçin. Yeniden sıkıştırma çalıştığında bir PIL.Image.Image gerektirir.
num_frames (int, isteğe bağlı):
Üretilen videodaki kare sayısı. duration_head ile otomatik tahmin için atlayın (bkz. LTX2AutoDurationStep).
reference_conditions (list, isteğe bağlı): LTX2ReferenceCondition (veya bunların listesi), videoları IC-LoRA adaptörünün dikkat ettiği ek gizli jetonlara kodlanan.
reference_downscale_factor (int, isteğe bağlı, varsayılan olarak 1):
Hedef ve referans çözünürlükleri arasındaki oran; 2, referansın hedef çözünürlüğün yarısında ön işlendiği anlamına gelir. Uzamsal koordinatlar bu faktörle ölçeklenir, böylece referans jetonları hedef koordinat uzayına yerleşir. IC-LoRA'nın eğitim sırasında kullandığı faktörle eşleşmelidir.
conditioning_attention_strength (float, isteğe bağlı, varsayılan olarak 1.0):
Gürültülü jetonların ve referans jetonlarının birbirine ne kadar güçlü dikkat ettiğini kontrol eden [0, 1] aralığında bir skaler. 1.0 (varsayılan), dikkati maskesiz bırakır.
conditioning_attention_mask (Tensor, isteğe bağlı):
(1, 1, F, H, W) biçiminde, [0, 1] aralığında değerlere sahip, uzamsal olarak değişen dikkat gücü veren isteğe bağlı piksel uzaylı maskesi. Referansın gizli ızgarasına indirgenir ve conditioning_attention_strength ile çarpılır.
motion_speed (float, isteğe bağlı, varsayılan olarak 1.0):
Gerçek zamana göre hareket hızı. Konumsal gömüler frame_rate / motion_speed değerine koşullandırılır, bu nedenle 1'den küçük 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.
num_videos_per_prompt (int, isteğe bağlı, varsayılan olarak 1):
İstem başına üretilecek görsel sayısı.
condition_latents (list, isteğe bağlı):
Koşul başına [1, C, F, H, W] biçiminde normalize edilmiş VAE gizli değerleri.
condition_strengths (list, isteğe bağlı):
Koşul başına koşullandırma güçleri.
condition_indices (list, isteğe bağlı):
Koşulun uygulandığı koşul başına gizli kare indeksi.
condition_pixel_frames (list, isteğe bağlı):
Koşul başına kırpılmış piksel kare sayısı, tek kareli anahtar kare koordinatlarını sınırlamak için kullanılır.
reference_latents (Tensor, isteğe bağlı):
[1, total_reference_tokens, C] biçiminde paketlenmiş referans jetonları veya referans koşulları sağlanmadığında None (LTX2AutoReferenceEncoderStep atlanır).
reference_coords (Tensor, isteğe bağlı):
Referans jetonları için RoPE koordinatları.
reference_token_counts (list, isteğe bağlı):
reference_conditions sırasındaki referans başına jeton sayıları.
latents (Tensor):
Görsel üretimi için önceden üretilmiş gürültülü gizli değerler.
noise_scale (float, isteğe bağlı):
Koşulsuz jetonlar için başlangıç gürültü seviyesi. None (varsayılan), özel sigmas sağlandığında sigmas[0] olarak çözülür, aksi halde 1.0'dır.
sigmas (list, isteğe bağlı):
Gürültü azaltma süreci için özel sigmalar.
reference_cross_mask (Tensor, isteğe bağlı):
[1, num_ref_tokens] biçiminde, referans jetonu başına gürültülü<->referans dikkat güçleri.
num_inference_steps (int):
Gürültü azaltma adım sayısı.
timesteps (Tensor):
Gürültü azaltma süreci için zaman adımları.
audio_latents (Tensor):
İsteğe bağlı önceden kodlanmış ses gizli değerleri; sağlanmadığında rastgele gürültü kullanılır.
*denoiser_input_fields (None,isteğe bağlı):
Gürültü azaltıcı için koşullu model girdileri: örn. prompt_embeds, negative_prompt_embeds vb.
use_cross_timestep (bool,isteğe bağlı, varsayılan olarak True):
Dönüştürücünün ayrı bir jeton başına çapraz zaman adımına koşullandırılıp koşulandırılmayacağı (LTX-2.3+).
attention_kwargs (dict,isteğe bağlı):
Dikkat işlemcileri için ek anahtar kelime argümanları.
image_latents (Tensor,isteğe bağlı):
Görselden videoya koşullandırma için kullanılan VAE kodlu referans görsel gizli değerleri.
output_type (str,isteğe bağlı*, varsayılan olarak pil):
Çıktı biçimi: ‘pil’, ‘np’, ‘pt’.
Çıktılar:
videos (list):
Oluşturulan videolar.
audio (Tensor):
Oluşturulan ses dalgası.