Hugging Face's logo

Diffusers documentation

LTX-2

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

LTX-2

LoRA

LTX-2 هو نموذج أساسي يعتمد على DiT، صُمم لتوليد فيديو وصوت متزامنين ضمن نموذج واحد. يجمع بين العناصر الأساسية لتوليد الفيديو الحديث، مع أوزان مفتوحة وتركيز على التنفيذ العملي محليًا.

يمكنك العثور على جميع نقاط التفتيش الأصلية لنموذج LTX-Video تحت منظمة Lightricks.

يمكن العثور على قاعدة الكود الأصلية لـ LTX-2 هنا.

التوليد على مرحلتين

تتطابق القيم الافتراضية المشتركة لـ __call__ في LTX2Pipeline / LTX2ImageToVideoPipeline مع مرجع LTX-2.5 (num_inference_steps=30؛ أما num_frames فهي اختيارية عند وجود duration_head، وإلا فإنها تعود إلى 121). تستخدم الأمثلة أدناه تلك القيم الافتراضية أيضًا لـ LTX-2.0/2.3.

خط أنابيب موصى به لتحقيق توليد بجودة إنتاجية، يتكون هذا الخط من مرحلتين:

  • المرحلة 1: توليد فيديو بالدقة المستهدفة باستخدام أخذ عينات الانتشار مع التوجيه الحر من التصنيف (CFG). تنتج هذه المرحلة تسلسل فيديو متماسكًا منخفض الضوضاء يحترم شروط النص/الصورة.
  • المرحلة 2: زيادة دقة مخرجات المرحلة 1 بمعامل 2، وتحسين التفاصيل باستخدام نموذج LoRA مُقطّر لتحسين الدقة والجودة البصرية. قد تطبّق المرحلة 2 إعدادات CFG أخف للحفاظ على البنية من المرحلة 1 مع تعزيز الملمس والحدة.

استخدام نموذجي لخط أنابيب تحويل النص إلى فيديو على مرحلتين

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",
)

توليد نقطة تحقق مُصغّرة

أسرع خط أنابيب لتوليد مرحلتين باستخدام نقطة تحقق مُقطّرة.

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",
)

توليد خط أنابيب الشرط

يمكنك استخدام LTX2ConditionPipeline لتحديد شروط الصورة و/أو الفيديو عند فهارس كامنة (latent indices) اختيارية. على سبيل المثال، يمكننا تحديد شرط للإطار الأول والإطار الأخير معًا لتنفيذ توليد فيديو من الإطار الأول إلى الأخير (FLF2V):

import torch
from diffusers import LTX2ConditionPipeline, LTX2LatentUpsamplePipeline
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2VideoCondition
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES, STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video
from diffusers.utils import load_image

device = "cuda"  # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "rootonchair/LTX-2-19b-distilled"

pipe = LTX2ConditionPipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()

prompt = (
    "CG animation style, a small blue bird takes off from the ground, flapping its wings. The bird's feathers are "
    "delicate, with a unique pattern on its chest. The background shows a blue sky with white clouds under bright "
    "sunshine. The camera follows the bird upward, capturing its flight and the vastness of the sky from a close-up, "
    "low-angle perspective."
)

first_image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_first_frame.png",
)
last_image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_last_frame.png",
)
first_cond = LTX2VideoCondition(frames=first_image, index=0, strength=1.0)
last_cond = LTX2VideoCondition(frames=last_image, index=-1, strength=1.0)
conditions = [first_cond, last_cond]

frame_rate = 24.0
video_latent, audio_latent = pipe(
    conditions=conditions,
    prompt=prompt,
    width=width,
    height=height,
    num_frames=121,
    frame_rate=frame_rate,
    num_inference_steps=8,
    sigmas=DISTILLED_SIGMA_VALUES,
    guidance_scale=1.0,
    generator=generator,
    output_type="latent",
    return_dict=False,
)

latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
    model_path,
    subfolder="latent_upsampler",
    dtype=torch.bfloat16,
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
upsample_pipe.enable_model_cpu_offload(device=device)
upscaled_video_latent = upsample_pipe(
    latents=video_latent,
    output_type="latent",
    return_dict=False,
)[0]

video, audio = pipe(
    latents=upscaled_video_latent,
    audio_latents=audio_latent,
    prompt=prompt,
    width=width * 2,
    height=height * 2,
    num_inference_steps=3,
    sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
    generator=generator,
    guidance_scale=1.0,
    output_type="np",
    return_dict=False,
)

encode_video(
    video[0],
    fps=frame_rate,
    audio=audio[0].float().cpu(),
    audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
    output_path="ltx2_distilled_flf2v.mp4",
)

يمكنك استخدام كل من شروط الصور والفيديو:

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",
)

بما أن عملية التكييف تتم عبر الإطارات الكامنة، فإن الإطارات الثمانية في فضاء البيانات المقابلة للإطار الكامن المحدد لشرط الصورة تميل إلى أن تكون ثابتة.

إرشادات متعددة الوسائط

تدعم خطوط أنابيب LTX-2.X التوجيه متعدد الوسائط. يتكون من ثلاثة مصطلحات، جميعها تستخدم قاعدة تحديث بنمط CFG:

  1. الإرشاد الحر من التصنيف (CFG): CFG القياسي حيث يتم توليد المخرجات المُزعزعة (الأضعف) باستخدام الموجه السلبي.
  2. الإرشاد المكاني-الزمني (STG): STG يتخلى عن المخرجات المضطربة الناتجة عن اختصار عمليات الانتباه الذاتي (self-attention) ويستبدلها بقيم الانتباه بدلاً من ذلك. الفكرة هي أن هذا يؤدي إلى إنشاء فيديوهات أكثر حدة واتساق مكاني-زمني أفضل.
  3. إرشادات عزل النمط: تتجه بعيداً عن المخرجات المضطربة الناتجة عن تعطيل الانتباه المتقاطع بين الأنماط (من الصوت إلى الفيديو ومن الفيديو إلى الصوت). هذا الإرشاد أكثر تحديداً لنماذج LTX-2.X، على أساس أن ذلك يُنتج اتساقاً أفضل بين الصوت والفيديو المولَّدين.

تُتحكَّم هذه المعايير عبر الحجج guidance_scale وstg_scale وmodality_scale، ويمكن ضبطها بشكل منفصل للفيديو والصوت. بالإضافة إلى ذلك، فيما يتعلق بتقنية STG، يجب تحديد فهارس كتل التحويل (transformer blocks) التي يتم فيها تجاوز الانتباه الذاتي (self-attention) عبر الحجة spatio_temporal_guidance_blocks. كما تدعم خطوط أنابيب LTX-2.X ميزة إعادة تحجيم التوجيه (guidance rescaling) للمساعدة في تقليل الإفراط في التعرض للضوء (over-exposure)، والذي قد يكون مشكلة عند ضبط مقاييس التوجيه على قيم عالية.

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",
)

تحسين الأوامر

تكون نماذج LTX-2.X حساسة لأسلوب صياغة الأوامر. راجع دليل صياغة الأوامر الرسمي للحصول على توصيات حول كيفية كتابة أمر جيد. كما يمكن تحسين جودة العينات باستخدام تعزيز الأوامر، حيث تُعزَّز الأوامر المُدخلة باستخدام مُشفِّر النص الخاص بالخطوة (وهو نموذج Gemma 3 افتراضيًا) بناءً على أمر نظام. يجب أن يكون مكوّن processor الاختياري في الخطوة حاضرًا لاستخدام تعزيز الأوامر. فعّله باستخدام enable_prompt_enhancement=True وsystem_prompt (اختياري، ويتوافق مع خطوط Lightricks المرجعية):

import torch
from transformers import Gemma3Processor
from diffusers import LTX2Pipeline
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT, T2V_DEFAULT_SYSTEM_PROMPT

device = "cuda"  # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "diffusers/LTX-2.3-Diffusers"

pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_model_cpu_offload(device=device)
pipe.vae.enable_tiling()
if getattr(pipe, "processor", None) is None:
    processor = Gemma3Processor.from_pretrained("google/gemma-3-12b-it-qat-q4_0-unquantized")
    pipe.processor = processor

prompt = (
    "An astronaut hatches from a fragile egg on the surface of the Moon, the shell cracking and peeling apart in "
    "gentle low-gravity motion. Fine lunar dust lifts and drifts outward with each movement, floating in slow arcs "
    "before settling back onto the ground. The astronaut pushes free in a deliberate, weightless motion, small "
    "fragments of the egg tumbling and spinning through the air. In the background, the deep darkness of space subtly "
    "shifts as stars glide with the camera's movement, emphasizing vast depth and scale. The camera performs a "
    "smooth, cinematic slow push-in, with natural parallax between the foreground dust, the astronaut, and the "
    "distant starfield. Ultra-realistic detail, physically accurate low-gravity motion, cinematic lighting, and a "
    "breath-taking, movie-like shot."
)

video, audio = pipe(
    prompt=prompt,
    negative_prompt=DEFAULT_NEGATIVE_PROMPT,
    width=width,
    height=height,
    num_frames=121,
    frame_rate=frame_rate,
    num_inference_steps=30,
    guidance_scale=3.0,
    stg_scale=1.0,
    modality_scale=3.0,
    guidance_rescale=0.7,
    audio_guidance_scale=7.0,
    audio_stg_scale=1.0,
    audio_modality_scale=3.0,
    audio_guidance_rescale=0.7,
    spatio_temporal_guidance_blocks=[28],
    use_cross_timestep=True,
    enable_prompt_enhancement=True,
    system_prompt=T2V_DEFAULT_SYSTEM_PROMPT,
    generator=generator,
    output_type="np",
    return_dict=False,
)

encode_video(
    video[0],
    fps=frame_rate,
    audio=audio[0].float().cpu(),
    audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
    output_path="ltx2_3_t2v_stage_1.mp4",
)

LTX-2.5

يعيد LTX-2.5 استخدام نفس فئات LTX2Pipeline/LTX2VideoTransformer3DModel/AutoencoderKLLTX2Video/إلخ. المستخدمة في LTX-2.3 — فلا توجد فئة خط أنابيب منفصلة له. الفرق الظاهر للمستخدم هو مُشفّر النص: إذ يُقرَن LTX-2.5 بنقطة تحقق Gemma 4 (gemma4_unified) بدلاً من Gemma 3. يتم تحميل هذا تلقائياً عند استدعاء from_pretrained على نقطة تحقق LTX-2.5 مُحوَّلة (عبر فئات Auto* في transformers)، لذا لا حاجة إلى إعداد إضافي وقت الاستدلال — فقط وجّه from_pretrained إلى مستودع LTX-2.5 بدلاً من مستودع LTX-2.3.

يُشغّل Lightricks/LTX-2.5-Diffusers كلا التحوّليين: التحوّلي المُقطّر DiT الموجود في transformer/، وهو ما يشير إليه model_index.json، والتحوّلي DiT الكامل/SFT الموجود في transformer_full/، والذي يجب تحميله بشكل صريح (انظر التحوّلي الكامل / SFT). تم تكوين scheduler/ في المستودع لنقطة الفحص المُقطّرة (use_dynamic_shifting=False، shift_terminal=None) بحيث يُستخدم جدول sigma الخاص به كما هو مُعطى بالضبط. كما أن كل ما يحتاجه التوليد على مرحلتين مُشغّل هناك أيضاً: مجلد فرعي latent_upsampler/ وLoRA المُقطّر للمرحلة 2، ltx-2.5-22b-distilled-lora-450-bf16.safetensors، في جذر المستودع.

يعتمد الاستدلال المُقطَّر على جدول صيغ صريح بدلاً من عدد الخطوات، ويُنفَّذ دون توجيه (guidance_scale=1.0، لذا لا يُستخدم negative_prompt). إن مررت num_inference_steps بدلاً من ذلك، فستمنح النموذج جدولاً خطياً عاماً وستتسبب في خسارة الجودة بصمت:

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

يدعم LTX-2.5 كلا من المتغيرات ذات المرحلتين، وتُعدّ DISTILLED_SIGMA_VALUES / STAGE_2_DISTILLED_SIGMA_VALUES جداولها المرجعية:

  • نقطة تحقق مُقطّرة، كلا المرحلتين — الوصفة المرجعية الافتراضية لـtransformer/، وهي الوصفة المعروضة أدناه. لا تدخل مرحلة 2 من LoRA في الأمر، لأن المحوّل مُقطّر بالفعل؛ وهذا هو إنشاء نقطة تحقق مُقطّرة بأوزان LTX-2.5.
  • المرحلة 1 الكاملة/التدريب الدقيق + المرحلة 2 المستخلصة عبر LoRA — التوليد على مرحلتين كما هو موضح في أعلى هذه الصفحة، باستخدام transformer_full/ وLoRA المرفقة. راجع ما يلي لمعرفة ما يتغير.

تعمل المرحلة 1 عند نصف الدقة المستهدفة، ثم يضاعف مُوسِّع الدقة هذه القيمة، وتُحسّن المرحلة 2 النتيجة عند الدقة الكاملة — للفيديو والصوت معًا، حيث يُعاد توليد البذرة لكليهما من الكمونيات (latents) الخاصة بالمرحلة 1 عند noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0]. يجب أن تكون الارتفاع والعرض قابلين للقسمة على 64، لأن المرحلة 1 تُنصّف كل محور ولا بد أن تستقر على الشبكة المكانية الخاصة بـ VAE.

import torch
from diffusers.pipelines.ltx2 import LTX2Pipeline, LTX2LatentUpsamplePipeline
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES, STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video

device = "cuda"  # or "mps", "xpu", "cpu"
width = 1536
height = 1024
num_frames = 121
frame_rate = 24.0
model_path = "Lightricks/LTX-2.5-Diffusers"

# One generator for the whole call, threaded through both stages, so stage 2 continues the noise
# stream instead of repeating stage 1's draw.
generator = torch.Generator(device).manual_seed(42)

pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)

prompt = "A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees."

# Stage 1: half resolution, 8 distilled sigmas
video_latent, audio_latent = pipe(
    prompt=prompt,
    width=width // 2,
    height=height // 2,
    num_frames=num_frames,
    frame_rate=frame_rate,
    sigmas=DISTILLED_SIGMA_VALUES,
    guidance_scale=1.0,
    audio_guidance_scale=1.0,
    generator=generator,
    output_type="latent",
    return_dict=False,
)

latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
    model_path,
    subfolder="latent_upsampler",
    dtype=torch.bfloat16,
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
upsample_pipe.enable_model_cpu_offload(device=device)
# `latents_normalized=False`: `output_type="latent"` already applied the latent statistics, and the
# upsampler is trained on denormalized latents. Stage 2 renormalizes them in `prepare_latents`.
upscaled_video_latent = upsample_pipe(
    latents=video_latent,
    latents_normalized=False,
    output_type="latent",
    return_dict=False,
)[0]

# Stage 2: full resolution, 3 sigmas, reseeded from stage 1. Pass `num_frames` explicitly here --
# omitting it would run the duration head a second time instead of using the stage 1 length.
pipe.vae.enable_tiling()
video, audio = pipe(
    prompt=prompt,
    latents=upscaled_video_latent,
    audio_latents=audio_latent,
    width=width,
    height=height,
    num_frames=num_frames,
    frame_rate=frame_rate,
    sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
    noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0],  # renoise with the stage 2 entry sigma
    guidance_scale=1.0,
    audio_guidance_scale=1.0,
    generator=generator,
    output_type="np",
    return_dict=False,
)

encode_video(
    video[0],
    fps=frame_rate,
    audio=audio[0].float().cpu(),
    audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
    output_path="ltx2_5_t2v_two_stages.mp4",
)

عندما يأتي الطول من رأس المدة بدلاً من num_frames صريح، دع المرحلة 1 تتخذ القرار وتستعيد الطول المحقق من متغيراتها الكامنة ([B, C, F, H, W]) قبل تشغيل المرحلة 2، بدلاً من التنبؤ مرة ثانية:

num_frames = (video_latent.shape[2] - 1) * pipe.vae_temporal_compression_ratio + 1

المرحلة 2 باستخدام LoRA المُقطّر

لتنفيذ التوليد على مرحلتين بدلاً من ذلك — DiT كامل/SFT للمرحلة 1، وLoRA مُقطّر للمرحلة 2 — ابنِ خط الأنابيب كما في المحوّل الكامل / SFT وولّد كامنات المرحلة 1 باستخدام ذلك المكدس التوجيهي. ثم يختلف أمران عن LTX-2.0/2.3. إذ يقيم LoRA في مستودع diffusers نفسه بدلاً من كونه بجانب الأوزان الأصلية، وتنعكس طريقة قلب المجدول: يأتي LTX-2.5 مع إعداد مجدول مُقطّر، لذا فإن المرحلة 1 هي التي فعّلت الإزاحة الديناميكية، وتُطفئ المرحلة 2 ذلك مجدداً.

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
)

لا يتغير خطو التوسيع والاستدعاء الخاص بالمرحلة 2 عن الوصفة المُصغَّرة أعلاه: نفس sigmas=STAGE_2_DISTILLED_SIGMA_VALUES، ونفس noise_scale، وguidance_scale=1.0، لأن المرحلة 2 تشغّل نموذجًا مُصغَّرًا في كلتا الحالتين.

فك الترميز التلافيفي والتفشّي

يأتي LTX-2.5 مع مُفكّكي فيديو يعملان على نفس الفضاء الكامن، لذا يمكن تبادل الكامنات بينهما:

  • vae/ — VAE الالتواي (AutoencoderKLLTX2Video). وهو ما تستخدمه خطوط الأنابيب لفك الترميز، لذا فإن كل مقتطف أعلاه يستخدمه بالفعل، وهو الوحيد من الاثنين الذي يدعم التقطيع (pipe.vae.enable_tiling())، وهو ما يجعل عادةً ملاءمة الدقة العالية ممكنة.
  • diffusion_decoder/ — LTX2VideoDiffusionDecoderModel. وهو نموذج انتشار بحد ذاته وليس مكوّنًا في خط المعالجة، لذا لا يُمرَّر كـvae: شغّل خط المعالجة باستخدام output_type="latent" ثم مرّر الكمونيات إلى LTX2VideoDiffusionDecodePipeline.

تمر عملية الترميز دائمًا عبر vae/، لذا لا تتأثر شروط الصورة أو الفيديو بالاختيار.

يحدث تغييران عند فك الترميز باستخدام مُفكّك التشتت. كما أن output_type="latent" يتخطى مُصنّع الصوت أيضاً، لذا يعود الصوت على شكل كامنات ويجب إكماله يدوياً، ومعالج NATTEN مطلوب فعلياً عند دقات الفيديو:

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",
)

لدمج هذا مع التوليد على مرحلتين، اطلب من المرحلة 2 استخدام output_type="latent" ثم فكّ تشفير الناتج.

decoder.enable_tiling() هو ما يُبقي فك الترميز عالي الدقة في الذاكرة، بنفس الطريقة التي يعمل بها pipe.vae.enable_tiling() بالنسبة إلى VAE التكاملي. الجزء المهيمن على الذاكرة في فك الترميز — مرحلة رفع العينة الأخيرة ومرحلة الانتشار — يعمل بعد ذلك على بلاطات متداخلة تُدمج معًا مرة أخرى، بحيث تكون ذروة الذاكرة محصورة بحجم البلاطة بدلاً من حجم الفيديو. لا يبدأ التقطيع إلا عندما يتجاوز الكمون (latent) بلاطة واحدة، ويمكن ضبط أحجام البلاطة والتداخل عبر الحجج tile_sample_min_* / tile_sample_stride_* (القيم الافتراضية تتطابق مع التنفيذ المرجعي). نظرًا لأن مرحلة الانتشار تُزيل الضوضاء من كل بلاطة بشكل منفصل، فإن فك الترميز المقطّع لا يُعيد إنتاج النتيجة غير المقطّعة بدقة.

على بطاقة واحدة، من المفيد أيضًا نقل خط الأنابيب خارج المسار قبل فك الترميز (pipe.to("cpu") وtorch.cuda.empty_cache()، بعد التقاط pipe.scheduler وoutput_sampling_rate الخاص بمُصنِّع الصوت)، لأن مُفكِّك الترميز يحتاج إلى مساحة عمل خاصة به. راجع LTX2VideoDiffusionDecoderModel لمعرفة واجهات الانتباه الخلفية، وتفاصيل التقطيع، وبقية سلوك مُفكِّك الترميز.

تحويلة كاملة / تحويل مُدرب

transformer_full/ غير مُشار إليه في model_index.json، لذا حمّله صراحةً. كما أنه يحتاج إلى مُجدول مختلف ومجموعة توجيه حقيقية: scheduler/ المرفق مُهيأ للنقطة الفاحصة المُقطّرة، والقيم الافتراضية للتوجيه هي قيم عامة من حقبة LTX-2.0 تُبقي تشغيل LTX-2.5 SFT مرئيًا دون توجيه كافٍ دون رفع أي تنبيه. توصيات Multimodal Guidance تنطبق هنا دون تغيير، بما في ذلك STG على الكتلة 28:

import torch
from diffusers import FlowMatchEulerDiscreteScheduler, LTX2Pipeline, LTX2VideoTransformer3DModel
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT

device = "cuda"  # or "mps", "xpu", "cpu"
model_path = "Lightricks/LTX-2.5-Diffusers"

# Passing `transformer=` keeps `from_pretrained` from fetching the distilled folder as well.
transformer = LTX2VideoTransformer3DModel.from_pretrained(
    model_path, subfolder="transformer_full", dtype=torch.bfloat16
)
pipe = LTX2Pipeline.from_pretrained(model_path, transformer=transformer, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()

# Re-enable dynamic shifting and the terminal shift, which the distilled configuration turns off.
pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(
    pipe.scheduler.config, use_dynamic_shifting=True, shift_terminal=0.1
)

video, audio = pipe(
    prompt="A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees.",
    negative_prompt=DEFAULT_NEGATIVE_PROMPT,
    width=768,
    height=512,
    num_frames=121,
    frame_rate=24.0,
    num_inference_steps=30,
    guidance_scale=3.0,
    stg_scale=1.0,
    modality_scale=3.0,
    guidance_rescale=0.7,
    audio_guidance_scale=7.0,
    audio_stg_scale=1.0,
    audio_modality_scale=3.0,
    audio_guidance_rescale=0.7,
    spatio_temporal_guidance_blocks=[28],
    use_cross_timestep=True,
    generator=torch.Generator(device).manual_seed(42),
    output_type="np",
    return_dict=False,
)

أزل sigmas من هنا — فـ DiT الكامل يستلم جدوله من المُجدوِل.

تحسين الأوامر النصية لـ LTX-2.5

يُوصى بشدة باستخدام تعزيز الأوامر (prompt enhancement) مع LTX-2.5؛ مرّر enable_prompt_enhancement=True للتفعيل (على غرار خطوط أنابيب Lightricks المرجعية). على عكس LTX-2.0/2.3، حيث يعمل نفس نقطة التفتيش لمشفّر النص أيضًا كمعزّز (انظر تعزيز الأوامر أعلاه)، لم يتم تدريب مشفّر النص المُحسّن في LTX-2.5 لأغراض التعزيز. بدلاً من ذلك، يستخدم التعزيز نقطة تفتيش منفصلة جاهزة من google/gemma-4-E2B-it. حمّلها في مكوّنات prompt_enhancer/processor الاختيارية في خط الأنابيب، ثم فعّل التعزيز — حيث يعتمد خط الأنابيب افتراضيًا على LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT وصفة Gemma 4 (do_sample=False، no_repeat_ngram_size=5، max_new_tokens=600). مرّر system_prompt= صريحًا للتجاوز:

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",
)

ينطبق الأمر نفسه على تحويل الصورة إلى فيديو باستخدام LTX2ImageToVideoPipeline: اضبط pipe.prompt_enhancer/pipe.processor بالطريقة نفسها، ونقل enable_prompt_enhancement=True (باستخدام LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT، مع اشتراط كل من الصورة المرجعية وموجّه النص) — مرة أخرى، لا حاجة إلى system_prompt= ما لم ترغب في تجاوزها.

المدة الزمنية التلقائية لـ LTX-2.5

تأتي نقاط التفتيش الخاصة بـ LTX-2.5 برأس مدة صغير duration_head يتنبأ بمدى طول اللقطة الموصوفة، انطلاقًا من مخرج الوصل النصي نفسه الذي يُشترط عليه المحوّل. عندما يحتوي خط الأنابيب المحمّل على هذا الرأس، يتم التنبؤ بـnum_frames تلقائيًا افتراضيًا — احذفه وسيختار النموذج الطول:

video, audio = pipe(prompt=prompt, output_type="np", return_dict=False)

لضبط الطول بنفسك، مرّر num_frames بشكل صريح. فالعدد الصحيح يتفوق دائمًا على الرأس:

video, audio = pipe(prompt=prompt, num_frames=121, output_type="np", return_dict=False)

لا تحتوي خطوط الأنابيب المحمّلة من نقاط التفتيش LTX-2.0 أو LTX-2.3 على رأس مدة، وتحتفظ بالافتراضي السابق البالغ 121 إطارًا، لذا لا يغيّر هذا شيئًا بالنسبة لها.

مرّر min_seconds / max_seconds لتقييد التنبؤ. يتم ضبط التنبؤ الخام ضمن النطاق، ثم تحويله إلى إطارات:

video, audio = pipe(
    prompt=prompt,
    min_seconds=2.0,
    max_seconds=10.0,
    frame_rate=frame_rate,
    output_type="np",
    return_dict=False,
)

تُثبَّت أعداد الإطارات المتوقعة على الشبكة الزمنية السببية الخاصة بـ VAE (8k + 1)، لذا فإن المدة الزمنية الفعلية تكون مُكمَّمة — بمعدل يقارب 0.33 ثانية لكل خطوة عند 24 إطارًا في الثانية — وتتناسب مع frame_rate، لأن الرأس يتنبأ بالثواني وليس بالإطارات. يجب أن يكون min_seconds أقل بصرامة من max_seconds. وتُتجاهل هذه الحدود عندما يتم تعيين num_frames بشكل صريح.

قد لا يمكن تحقيق الحدود الأضيق من خطوة شبكة واحدة بدقة: عند 24 إطارًا في الثانية، يتحول [1.0s, 1.02s] إلى [24, 24] إطارًا، و24 ليست 8k + 1. يُستخدم أقرب نقطة في الشبكة ويُسجَّل تحذير، لذا قد تقع الطول المُعاد خارج الحدود الضيقة جدًا.

لفحص تنبؤ دون توليد فيديو، استدعِ الرأس مباشرةً. كل ما يحتاجه متاح:

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، يتم اختيار الرأس تلقائيًا باستخدام --full_pipeline، أو بشكل مستقل باستخدام --duration_head. أما نقاط التفتيش السابقة لإصدار 2.5 فلا تحتوي على أوزان من هذا النوع، لذا يتخطى التحويل هذا المكوّن بدلاً من الفشل.

سرعة الحركة في LTX-2.5

يضع LTX-2 كل رمز فيديو على محور زمني بالثواني، يُشتق افتراضيًا من frame_rate، أي معدل التشغيل. يُميّز motion_speed (الافتراضي 1.0) بين الأمرين: يُشترط محور الزمن على frame_rate / motion_speed، بينما يتبع طول الصوت، ورأس المدة، والفيديو المُعاد إلى frame_rate. عند frame_rate=24.0 وmotion_speed=0.2، يُخبر النموذج بأن الحركة تم التقاطها بمعدل 120 إطارًا في الثانية وأن النتيجة تُشغَّل بمعدل 24 إطارًا في الثانية، مما يمنح حركة بطيئة بمقدار 5 أضعاف.

يُدرَّب النموذج الأساسي على سرعات حوالي 24/25/30/60 إطارًا في الثانية، لذا فإن السرعات التي تبتعد كثيرًا عن 1.0 لا معنى لها إلا مع مُكيّف مُدرَّب خصيصًا لها، مثل Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control (مقيّد: يجب قبول ترخيصه على Hub أولاً). بدون motion_speed، يُحمَّل ذلك LoRA كـ LoRA عادي ولا يوفر أيًا من التحكم في الحركة. يقترح بطاقة النموذج سرعات 1.0، 0.5، 0.2، 0.1، 0.05 و0.025، عند قوة LoRA مقدارها 1.0. اترك كلمات السرعة (“slow motion”، “high fps”) خارج الأمر النصي، وأعد استخدام نفس الوصف عبر السرعات المختلفة، لأن motion_speed وحده هو الذي يحرّك التأثير.

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",
    )

تستمر المقطعان 121 إطارًا (حوالي 5 ثوانٍ عند 24 إطارًا في الثانية) ولا يتغير سوى إيقاع الحركة. في التوليد على مرحلتين، مرّر نفس قيمة motion_speed إلى المرحلتين. تعيد المرحلة 2 إزالة الضوضاء من الفيديو، وسيؤدي تشغيلها على محور الزمن الحقيقي إلى إلغاء تأثير الحركة البطيئة. يقوم المحرك المرجعي بالشيء نفسه عن طريق تغليف كائن المرحلة الذي تشترك فيه كلتا المرحلتين.

motion_speed هو أيضًا مدخل من مدخلات الوحدات النمطية الخاصة بـ LTX-2 / LTX-2.5، ويتم تمريره إلى خط الأنابيب النمطي بالطريقة نفسها.

LTX-2.5 المعياري

يتوفر LTX-2.5 أيضًا كخط أنابيب معياري. يستخدم مجموعة الكتل الافتراضية فاحص التشتت ويتنبأ بمدة الفيديو عند إغفال num_frames. يطبّق التوجيه بشكل منفصل على الفيديو والصوت من خلال مكوّني guider وaudio_guider. راجع LTX2Guidance لمعرفة معاملات التوجيه المتاحة. بشكل افتراضي، سيحمّل خط الأنابيب المعياري معزّز المعالج ومعالجه من مستودع google/gemma-4-E2B-it. فيما يلي مثال معياري لتحويل النص إلى فيديو:

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",
)

ستقوم خط الأنابيب المعيارية تلقائياً بتبديل سير العمل بناءً على المدخلات المُقدَّمة. على سبيل المثال، إذا تم تقديم image، فسيتم استخدام سير عمل I2V:

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",
)

يمكنك الاطلاع على سير العمل المدعومة في توثيق كل مجموعة كتل (مثل LTX2AutoBlocks، LTX25AutoBlocks).

التصيير الدقيق للتشتت (DFR) لـ LTX-2.5

LTX2DFRPipeline يقدّم زمن التنفيذ مقابل دقة التفاصيل. كل استدعاء لـ__call__ هو مرحلة إزالة ضوضاء واحدة عند height × width: فهي تولّد الفيديو بالإضافة إلى فتحات إطارات أساسية بإطار بكسل واحد إضافي، أو تعيد إزالة الضوضاء عن الكمونيات المُدخلة المُستمدّة من تلك الفتحات. يركّب المستدعون المراحل بالطريقة ذاتها كما في خطوط أنابيب LTX ذات المرحلتين الأخرى — هذه الخط، LTX2LatentUpsamplePipeline، ثم هذه الخط مرة أخرى، ثم LTX2DFRTemporalRefinePipeline لكل جولة زمنية.

تكلف كل فتحة إطارًا كاملاً من الرموز الكامنة لشراء إطار بكسل واحد، مما يخفف الضغط الزمني الفعّال عند ذلك الموقع — وبالتالي يُشترط الفيديو المحيط على إطارات جديدة حقيقية بدلاً من إطارات مُستوفاة. تأتي مواقع الفتحات من شبكة مقاطع مُحاذاة للحد الزمني الخاص بـ VAE (24 أو 32 إطار بكسل، أيهما يُقلل من الحشو المطلوب). يتم حشو اللوحة داخليًا إلى عدد صحيح من المقاطع؛ ويعيد output_type="latent" تلك الشبكة المحشوة حتى لا تُهمل فتحة تقع على الحشو. قم بقصّ اللوحة باستخدام trim_canvas قبل فك ترميز VAE.

يتطلب هذا نموذج تحويل (transformer) يحدد في ملفه الإعدادي use_keyframes_abs_pos_embedding، وهو ما يُعلّم الإحداثيات الكامنة (latents) الخاصة بإطارات بكسل واحد باستخدام تضمين (embedding) متعلّم. تأتي نقاط التفتيش (checkpoints) الخاصة بنسخة LTX-2.5 بهذا الإعداد مسبقًا؛ بينما يثير خط الأنابيب (pipeline) استثناءً عند استخدام أي نسخة أقدم، بدلًا من إهدار ميزانية الرموز (token budget) على رموز لا يمكنه تفسيرها.

خصص ميزانيةً للرموز الإضافية: كل خانة تضيف ما يعادل إطار كامن واحد، لذا فإن المرحلة 2 تشغّل تسلسلاً أطول من المرور المُقطّر ذي المرحلتين المكافئ — بزيادة 31% عند دقة 1024x1536 / 121 إطارًا (24576 -> 32256 رمزًا، 5 خانات على شبكة مقاطع من 24 إطارًا). تتناسب ذروة ذاكرة التفعيل مع ذلك، لذا قد تحتاج الدقة التي تتسع للتشغيل المُقطّر العادي إلى enable_sequential_cpu_offload أو vae.enable_tiling() أو مساحة عمل أصغر تحت DFR.

تستخدم التركيب return_dict=True لـ keyframes و keyframe_positions (يعيد return_dict=False نفس الحقول الأربعة كـ tuple).

الوصفة الكاملة أدناه هي التي يستحق البدء منها: تحويل صورة إلى فيديو بدقة 1088×1920، مع جولة واحدة من التحسين الزمني x2، وتطبيق IC-LoRA للتفاصيل المكانية x2 في المرحلة 2.

import torch
from diffusers import (
    LTX2DFRPipeline,
    LTX2DFRTemporalRefinePipeline,
    LTX2LatentUpsamplePipeline,
    LTXEulerAncestralRFScheduler,
)
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.utils import trim_canvas
from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2VideoCondition
from diffusers.pipelines.ltx2.utils import STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video, load_image

pipe = LTX2DFRPipeline.from_pretrained("Lightricks/LTX-2.5-Diffusers", torch_dtype=torch.bfloat16)
latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
    "Lightricks/LTX-2.5-Diffusers", subfolder="latent_upsampler", torch_dtype=torch.bfloat16
)
# The x2 temporal upsampler is not in the published `model_index.json` — convert it with
# `--temporal_latent_upsampler`.
temporal_latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
    "path/to/converted/temporal_latent_upsampler", torch_dtype=torch.bfloat16
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
temporal_pipe = LTX2DFRTemporalRefinePipeline(
    scheduler=LTXEulerAncestralRFScheduler(eta=0.5),
    vae=pipe.vae,
    audio_vae=pipe.audio_vae,
    text_encoder=pipe.text_encoder,
    tokenizer=pipe.tokenizer,
    connectors=pipe.connectors,
    transformer=pipe.transformer,
    vocoder=pipe.vocoder,
    temporal_latent_upsampler=temporal_latent_upsampler,
)

# All three pipelines share the same components, so place them together. Do not call
# `enable_model_cpu_offload()` on one of them: its hooks would own modules the other two also call,
# and `temporal_latent_upsampler` — held only by `temporal_pipe` — would never reach the device.
pipe.to("cuda")
upsample_pipe.to("cuda")
temporal_pipe.to("cuda")

image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png")
prompt = "A tabby cat stretching in a sunlit window, dust motes drifting in the light"
conditions = [LTX2VideoCondition(frames=image, index=0, strength=1.0)]
height, width = 1088, 1920
frame_rate = 24.0
generator = torch.Generator(device="cuda").manual_seed(0)

num_frames = 121
out = pipe(
    prompt=prompt,
    conditions=conditions,
    height=height // 2,
    width=width // 2,
    num_frames=num_frames,
    frame_rate=frame_rate,
    generator=generator,
    output_type="latent",
)
up_video = upsample_pipe(latents=out.frames, output_type="latent", return_dict=False)[0]
up_keyframes = upsample_pipe(latents=out.keyframes, output_type="latent", return_dict=False)[0]

# Load after stage 1 so the adapter is never disabled. `set_adapters` does not re-enable a
# transformer that already had `disable_adapters()` called on it.
pipe.load_lora_weights("Lightricks/LTX-2.5-22b-IC-LoRA-Pixel-Spatial-Upscaler", adapter_name="detailing")
pipe.set_adapters(["detailing"], adapter_weights=[0.5])
out2 = pipe(
    prompt=prompt,
    conditions=conditions,
    latents=up_video,
    audio_latents=out.audio,
    keyframes_latents=up_keyframes,
    keyframe_positions=out.keyframe_positions,
    reference_latents=out.frames,
    height=height,
    width=width,
    num_frames=num_frames,
    frame_rate=frame_rate,
    noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0],
    sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
    generator=generator,
    output_type="latent",
)
pipe.transformer.disable_adapters()

# `num_frames` here is the *padded* canvas the latents actually cover, which `resolve_canvas` may have
# grown past the 121 that were asked for. `condition_num_frames` stays the original request so a
# negative `condition.index` does not wrap onto the pad.
ratio = pipe.vae.temporal_compression_ratio
canvas_frames = (out2.frames.shape[2] - 1) * ratio + 1
out3 = temporal_pipe(
    latents=out2.frames,
    keyframes_latents=out2.keyframes,
    keyframe_positions=out2.keyframe_positions,
    audio_latents=out.audio,
    prompt=prompt,
    conditions=conditions,
    height=height,
    width=width,
    num_frames=canvas_frames,
    frame_rate=frame_rate,
    source_seconds=canvas_frames / frame_rate,
    condition_num_frames=num_frames,
    generator=generator,
    output_type="latent",
)

# Keep the padded canvas until decode so a slot on the pad is not dropped. `trim_canvas` counts *pixel*
# frames, and the round mapped `N -> 2 (N - 1) + 1`.
playback_fps = frame_rate * 2
requested_frames = (num_frames - 1) * 2 + 1
video_latents = trim_canvas(out3.frames, requested_frames, ratio)
timestep = None
if pipe.vae.config.timestep_conditioning:
    timestep = torch.zeros(video_latents.shape[0], device=video_latents.device, dtype=pipe.vae.dtype)
video = pipe.vae.decode(video_latents.to(pipe.vae.dtype), timestep, return_dict=False)[0]
video = pipe.video_processor.postprocess_video(video, output_type="np")

# Audio is stage 1's. Cut it to the video's duration so a muxed container does not outlast the picture.
audio = pipe.vocoder(pipe.audio_vae.decode(out.audio.to(pipe.audio_vae.dtype), return_dict=False)[0])
audio_samples = round(requested_frames / playback_fps * pipe.vocoder.config.output_sampling_rate)
audio = audio[..., : min(audio.shape[-1], audio_samples)]

encode_video(
    video[0],
    fps=playback_fps,
    audio=audio[0].float().cpu(),
    audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
    output_path="ltx2_5_dfr.mp4",
)

height وwidth هما هذه المارّة، وليسا المخرَج النهائي. تعمل المرحلة 1 على نصف مساحة 1080p (544×960)؛ وتعمل المرحلة 2 على 1088×1920. يجب أن يكون كلٌّ منهما قابلاً للقسمة على نسبة الضغط المكاني الخاصة بـ VAE (32 في LTX-2.5 لمارّة واحدة؛ و64 عندما تكون المرحلة 1 نصف 1080p). ولهذا السبب تكون 1080p هي 1920×1088 و4K هي 3840×2176. تعمل كل مارّة بجدول مُقطَّر ثابت (sigmas)، لذا لا يوجد num_inference_steps؛ وقد تم تدريب الجداول المُقطَّرة دون توجيه، لذا لا يوجد negative_prompt أو guidance_scale أيضاً. الصوت المُرفق هو صوت المرحلة 1 — لا تزال المارات اللاحقة تشغّل تدفّقاً صوتياً حتى تمتلك فرع الفيديو انتباهاً بين الوسائط؛ لكن الموجة نفسها لا تُحسَّن بعد المرحلة 1.

التفاصيل المكانية. حمّل IC-LoRA للتفاصيل المكانية بمقياس 2x تحت مُكيّف مُسمّى بعد المرحلة 1 وفعّله للمرحلة 2 فقط (set_adapters(["detailing"], adapter_weights=[0.5])). ثم تنتبه المرحلة 2 إلى الكامن بنصف الدقة الخاص بالمرحلة 1 بوصفه reference_latents. تعمل المرحلة 1 والجولات الزمنية مع تعطيل المُكيّف. إذا قمت بتحميل LoRA قبل المرحلة 1، فإن transformer.disable_adapters() يُعطّله، وset_adapters لا يعيد تفعيله — استدعِ transformer.enable_adapters() قبل المرحلة 2، أو حمّل الأوزان بعد المرحلة 1 كما في الوصفة. يُقيّم reference_downscale_factor (الافتراضي 2) الإحداثيات المكانية لرموز المرجع إلى فضاء إحداثيات الهدف.

التحسين الزمني. LTX2DFRTemporalRefinePipeline هي جولة واحدة: رفع عينة زمنيًا، تقطيع عند حدود الإطارات المفتاحية، إزالة الضوضاء الأصلية باستخدام LTXEulerAncestralRFScheduler (eta=0.5)، ثم دمج القطع عبر إسقاط المقدمة الزمنية للقطعة اللاحقة، ودمج حزمة الإطارات المفتاحية المنقولة. أنشئ هذا المجدول بنفسك — فسيُرفض تنفيذ الجولة مع أي شيء آخر، لأن خطوة حتمية ستستمر حتى الاكتمال ولن تُرجع سوى لوحة ألوان أكثر نعومة. استدعِ خط الأنابيب مرة واحدة لكل جولة؛ ونفّذ حلقة للتكرار 2x / 4x مع تمرير round_index. بعد الجولة، لا يمكن إعادة اشتقاق keyframe_positions من num_frames الأصلية، ويجب تمريرها صراحةً. تُسلَّم كل قطعة الجزء من الصوت المجمّد في المرحلة الأولى الذي يغطي نافذة تشغيلها الخاصة. source_seconds هي مدة المرحلة الأولى وتبقى ثابتة عبر الجولات، لذا يجب على الجولات اللاحقة تمريرها صراحةً بدلاً من الاعتماد على القيمة الافتراضية.

تكون قيمة fps الشرطية 60 دائمًا عندما يكون معدل التشغيل أعلى من 30، بغض النظر عن عملية الدمج (muxing): فزمن RoPE هو pixel_frame / fps، لذا فإن أساس زمني بمعدل 120 fps سيقلل النطاق الزمني لكل رمز إلى النصف مقارنةً بالتوزيع المُدرَّب عليه، بينما سيؤدي معدل 48 fps إلى إطالته. كلاهما يدّعي أن قيمته 60 ويعامل الإطارات المُفكَّكة بمعدل التشغيل.

مرحلة مكانية ثالثة. قم بتكوينها؛ لا توجد خط أنابيب رابع. قم بالتوسيع المكاني لـالفيديو فقط، وأعد بناء إطارات النقل في RGB (decode → Lanczos ×2 → encode عبر rebuild_epilogue_keyframes()؛ لا تقم أبداً بالتوسيع الكامن لإطارات الخاتمة)، ثم:

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

تُخاط المحوران بطرق مختلفة. لا يحمل أي جانب من حدود الفضاء إجابة معروفة، لذا تُدمج تلك التداخلات بأوزان شبه منحرفة. أما البلاطات الزمنية فتُقطع على فواصل الإطارات المفتاحية لجولة التصفية الأخيرة.

فك الترميز باستخدام مُفكّك التشتت. للحصول على أعلى دقة في التفاصيل، ابقَ على output_type="latent" وقدم المتغيرات الكامنة (المُعاد تطبيعها مسبقًا، وقد تكون trim_canvas) إلى LTX2VideoDiffusionDecodePipeline.

from diffusers import LTX2VideoDiffusionDecodePipeline
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoDiffusionDecoderModel

decoder = LTX2VideoDiffusionDecoderModel.from_pretrained(
    "Lightricks/LTX-2.5-Diffusers", subfolder="diffusion_decoder", dtype=torch.bfloat16
)
decode_pipe = LTX2VideoDiffusionDecodePipeline(
    diffusion_decoder=decoder, scheduler=pipe.scheduler, vae=pipe.vae
)
decode_pipe.enable_model_cpu_offload()
# `denormalize=False`: the `output_type="latent"` path already applied the latent statistics.
video = decode_pipe(latents=out3.frames, denormalize=False, output_type="np", return_dict=False)[0]

LTX2Pipeline

فئة diffusers.LTX2Pipeline

< >

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

المعاملات

  • transformer (LTXVideoTransformer3DModel) — بنية Transformer شرطية لإزالة الضوضاء من كامنات الفيديو المُرمّزة.
  • scheduler (FlowMatchEulerDiscreteScheduler) — جدول زمني يُستخدم بالاقتران مع transformer لإزالة الضوضاء من كائنات الصورة المُرمّزة.
  • vae (AutoencoderKLLTXVideo) — نموذج الترميز التبايني التلقائي (VAE) لتشفير الصور وفك تشفيرها إلى التمثيلات الكامنة ومنها.
  • text_encoder (T5EncoderModel) — T5، وتحديداً النسخة google/t5-v1_1-xxl.
  • tokenizer (CLIPTokenizer) — مقسّم من الفئة CLIPTokenizer.
  • tokenizer (T5TokenizerFast) — المُرمِّز الثاني من الفئة T5TokenizerFast.
  • connectors (LTX2TextConnectors) — مكدس موصلات النص المستخدم لتكييف حالات المُشفِّر النصي المخفية لفروع الفيديو والصوت.

خط أنابيب لتوليد الفيديو من النص.

مرجع: https://github.com/Lightricks/LTX-Video

__call__

< >

( 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

المعاملات

  • prompt (str أو list[str]، اختياري) — الموجّه أو الموجّهات التي توجّه توليد الصورة. إذا لم يُعرَّف، يجب تمرير prompt_embeds بدلاً من ذلك.
  • negative_prompt (str أو list[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الصورة. إذا لم يُعرَّف، يجب تمرير negative_prompt_embeds بدلاً منه. يتم تجاهله عند عدم استخدام التوجيه (guidance_scale < 1).
  • height (int، اختياري، القيمة الافتراضية 512) — ارتفاع الصورة المولّدة بالبكسلات. يتم ضبطه على 480 افتراضيًا للحصول على أفضل النتائج.
  • width (int، اختياري، القيمة الافتراضية 768) — عرض الصورة المولدة بالبكسل. يتم ضبطه على 848 افتراضيًا للحصول على أفضل النتائج.
  • num_frames (int, اختياري) — عدد إطارات الفيديو التي سيتم توليدها. إذا لم يُقدَّم، فسيتم افتراض مدة مُقدَّرة تلقائيًا عندما يحتوي هذا الخطّ الأنابيب على مكوّن duration_head (نقاط التفتيش LTX-2.5 وما بعدها)، وإلا فسيكون الافتراضي 121. مرّر عددًا صحيحًا لتحديد الطول صراحةً. تُقَدَّم الأعداد المُقدَّرة تلقائيًا إلى الشبكة الزمنية السببية الخاصة بـ VAE، لذا تكون المدة المحققة مُكمَّمة (حوالي 0.33 ثانية عند 24 إطارًا في الثانية).
  • min_seconds (float، اختياري، القيمة الافتراضية 1.0) — الحد الأدنى للمدة المتوقعة تلقائيًا عندما يُستغنى عن num_frames ويتوفر duration_head. يُتجاهل هذا المعامل عند تحديد num_frames صراحةً.
  • max_seconds (float, اختياري، القيمة الافتراضية 20.0) — الحد الأعلى للمدة المتوقعة تلقائيًا عند إغفال num_frames ووجود duration_head. يُتجاهل عند تعيين num_frames صراحةً. يجب أن يكون أكبر بوضوح من min_seconds.
  • frame_rate (float، اختياري، القيمة الافتراضية 24.0) — عدد الإطارات في الثانية (FPS) للفيديو المولّد.
  • motion_speed (float، اختياري، القيمة الافتراضية 1.0) — سرعة الحركة مقارنةً بالوقت الحقيقي. تُشترط التضمينات الموضعية على frame_rate / motion_speed، لذا فإن القيم الأقل من 1 تُبطئ الحركة، على سبيل المثال 0.2 لحركة بطيئة بمقدار 5 أضعاف في LoRA الخاص بالتحكم بالحركة البطيئة. يبقى frame_rate معدل التشغيل: مدة الصوت وعدد الإطارات المتوقع يتبعانه.
  • num_inference_steps (int، اختياري، القيمة الافتراضية 30) — عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة بجودة أعلى على حساب بطء الاستدلال.
  • sigmas (List[float]، اختياري) — قيم sigmas مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل sigmas في طريقة set_timesteps الخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير num_inference_steps.
  • timesteps (list[int], اختياري) — خطوات زمنية مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل timesteps في طريقة set_timesteps الخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير num_inference_steps. يجب أن تكون بترتيب تنازلي.
  • guidance_scale (float، اختياري، القيمة الافتراضية 4.0) — مقياس التوجيه كما هو مُعرَّف في Classifier-Free Diffusion Guidance. يُعرَّف guidance_scale على أنه w من المعادلة 2 في Imagen Paper. يتم تفعيل مقياس التوجيه عن طريق تعيين guidance_scale > 1. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بـ prompt النصي، وعادةً على حساب انخفاض جودة الصورة. يُستخدم لوضع الفيديو (يوجد قيمة منفصلة audio_guidance_scale لوضع الصوت).
  • stg_scale (float، اختياري، القيمة الافتراضية 0.0) — مقياس التوجيه للفيديو للتوجيه المكاني-الزمني (STG)، المقترح في Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. يستخدم STG تقديراً يشبه CFG حيث نحرّك العينة بعيداً عن عينة ضعيفة من نسخة مُعطَّبة من نموذج إزالة الضوضاء. تفعيل STG سيؤدي إلى مرور إضافي للأمام في نموذج إزالة الضوضاء؛ القيمة الافتراضية 0.0 تعني أن STG معطَّل.
  • modality_scale (float, اختياري، القيمة الافتراضية 1.0) — مقياس التوجيه للفيديو لعزل الأنماط في LTX-2.X، حيث نُبعد العينة عن عينة أضعف يولدها نموذج إزالة الضوضاء مع تعطيل الانتباه المتقاطع بين الأنماط (من الصوت إلى الفيديو ومن الفيديو إلى الصوت) باستخدام تقدير يشبه CFG. سيؤدي تفعيل توجيه النمط إلى إجراء تمريرة أمامية إضافية لنموذج إزالة الضوضاء؛ تعني القيمة الافتراضية 1.0 أن توجيه النمط معطّل.
  • guidance_rescale (float, optional, defaults to 0.0) — Guidance rescale factor proposed by Common Diffusion Noise Schedules and Sample Steps are Flawed guidance_scale is defined as φ in equation 16. of Common Diffusion Noise Schedules and Sample Steps are Flawed. Guidance rescale factor should fix overexposure when using zero terminal SNR. Used for the video modality.
  • audio_guidance_scale (float, اختياري القيمة الافتراضية None) — مقياس التوجيه الصوتي لـ CFG فيما يتعلق بالموجّه السلبي. قاعدة تحديث CFG هي نفسها للفيديو والصوت، لكن يمكن استخدام قيم مختلفة لمقياس التوجيه. يقترح مؤلفو LTX-2.X أن يكون audio_guidance_scale أعلى نسبيًا من guidance_scale الخاص بالفيديو (على سبيل المثال، يقترحون 3.0 للفيديو و 7.0 للصوت في LTX-2.3). إذا كانت None، فإن القيمة الافتراضية هي قيمة الفيديو guidance_scale.
  • audio_stg_scale (float, اختياري، القيمة الافتراضية None) — مقياس التوجيه الصوتي لـ STG. وكما هو الحال مع CFG، فإن قاعدة التحديث الخاصة بـ STG متطابقة في الغالب لكل من الفيديو والصوت. بالنسبة إلى LTX-2.3، يُقترح استخدام قيمة 1.0 لكل من الفيديو والصوت. إذا كانت None، فإن القيمة الافتراضية هي قيمة الفيديو stg_scale.
  • audio_modality_scale (float, اختياري، القيمة الافتراضية None) — مقياس التوجيه الصوتي لعزل الأنماط في LTX-2.X. وكما هو الحال مع CFG، فإن قاعدة توجيه النمط متطابقة في الغالب لكل من الفيديو والصوت. بالنسبة إلى LTX-2.3، يُقترح استخدام القيمة 3.0 لكل من الفيديو والصوت. إذا كانت None، فإن القيمة الافتراضية هي قيمة الفيديو modality_scale.
  • audio_guidance_rescale (float, اختياري، القيمة الافتراضية None) — عامل إعادة تحجيم إرشادي منفصل لنمط الصوت. إذا كانت القيمة None، فإن القيمة الافتراضية هي قيمة الفيديو guidance_rescale.
  • spatio_temporal_guidance_blocks (list[int]، اختياري، القيمة الافتراضية None) — فهارس كتل التحوّل (transformer blocks) بدءًا من الصفر التي تُطبَّق عليها STG. يجب تقديم هذه القيمة إذا تم استخدام STG (عندما تكون stg_scale أو audio_stg_scale أكبر من 0). يُوصى بقيمة [29] لـ LTX-2.0 ويُوصى بقيمة [28] لـ LTX-2.3.
  • noise_scale (float، اختياري، القيمة الافتراضية 0.0) — عامل الاستيفاء بين الضوضاء العشوائية واللاتنتات منزوعة الضوضاء في كل خطوة زمنية. تطبيق الضوضاء على latents وaudio_latents قبل مواصلة إزالة الضوضاء.
  • num_videos_per_prompt (int، اختياري، القيمة الافتراضية 1) — عدد مقاطع الفيديو التي سيتم توليدها لكل موجه.
  • generator (torch.Generator أو list[torch.Generator]، اختياري) — مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا.
  • latents (torch.Tensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الفيديو. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم إنشاء كائن latents عن طريق الاستخراج باستخدام generator العشوائي المُقدَّم.
  • audio_latents (torch.Tensor، اختياري) — كعوب ضوضائية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصوت. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم إنشاء كعوب باستخدام العينة عبر المولّد العشوائي generator المُقدَّم.
  • prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخال prompt.
  • prompt_attention_mask (torch.Tensor، اختياري) — قناع الانتباه المُولَّد مسبقًا لتضمينات النص.
  • negative_prompt_embeds (torch.FloatTensor، اختياري) — تضمينات نصية سالبة مُولّدة مسبقًا. بالنسبة إلى PixArt-Sigma، يجب أن يكون هذا الموجه السلبي "". إذا لم يُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخال negative_prompt.
  • negative_prompt_attention_mask (torch.FloatTensor، اختياري) — قناع انتباه مُولّد مسبقًا لتضمينات النص السلبية.
  • decode_timestep (float، القيمة الافتراضية 0.0) — خطوة الزمن التي يتم عندها فك ترميز الفيديو المولّد.
  • decode_noise_scale (float، القيمة الافتراضية None) — عامل الاستيفاء بين الضوضاء العشوائية واللاتنتات المُزالة الضوضاء عند خطوة فك الترميز.
  • use_cross_timestep (bool اختياري، القيمة الافتراضية True) — ما إذا كان سيتم استخدام قيمة sigma الخاصة بالوضع المتقاطع (الصوت هو الوضع المتقاطع للفيديو، والعكس صحيح) عند حساب معاملات تعديل الانتباه المتقاطع. True هو سلوك LTX-2.3/2.5؛ وFalse هو سلوك LTX-2.0 القديم.
  • system_prompt (str، اختياري، القيمة الافتراضية None) — موجّه نظام اختياري يُستخدم لتحسين الموجّه. سيُستخدم موجّه النظام من قِبل مُحسّن الموجّه (نموذج توليد مشروط من Gemma — مكوّن prompt_enhancer المخصص إذا كان مُهيأً، وإلا فـ text_encoder الرئيسي) لتوليد موجّه محسّن من الموجّه الأصلي prompt لغرض تكييف التوليد. إذا لم يُقدَّم ولم يكن هناك prompt_enhancer مخصص مُهيأ (LTX-2.5)، تكون القيمة الافتراضية LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT (من diffusers.pipelines.ltx2.utils) — راجع enable_prompt_enhancement.
  • enable_prompt_enhancement (bool, اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تشغيل تعزيز الأوامر. خيار اختياري، بما يتوافق مع خطوط أنابيب Lightricks المرجعية. عند تعيين True وإهمال system_prompt، يستخدم LTX-2.5 LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT إذا تم تكوين prompt_enhancer مخصص؛ بينما تتطلب إصدارات LTX-2.0/2.3 تحديد system_prompt صراحةً.
  • prompt_max_new_tokens (int, اختياري، القيمة الافتراضية None) — الحد الأقصى لعدد الرموز الجديدة التي سيتم توليدها عند تنفيذ تعزيز الاستعلام. إذا لم يتم تقديمه، يتم استخدام 600 لمُحسِّن الاستعلام المخصص Gemma 4 prompt_enhancer (LTX-2.5) أو 512 كبديل لمُشفِّر النص Gemma 3 text_encoder (LTX-2.0/2.3).
  • prompt_enhancement_kwargs (dict[str, Any], اختياري، القيمة الافتراضية None) — حجج الكلمات المفتاحية لاستدعاء .generate في معزّز الأوامر. إذا لم تُقدَّم، فإنها تتطابق دائمًا مع النموذج الذي يقوم بالتعزيز: do_sample=False, no_repeat_ngram_size=5 (طامع) عند استخدام prompt_enhancer مخصص (LTX-2.5)، أو do_sample=True, temperature=0.7 لـ text_encoder الاحتياطي (LTX-2.0/2.3). راجع https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate لمزيد من التفاصيل.
  • prompt_enhancement_seed (int، اختياري، القيمة الافتراضية 10) — البذرة العشوائية لأي عمليات عشوائية أثناء تعزيز الاستعلام.
  • output_type (str، اختياري، القيمة الافتراضية "pil") — صيغة مخرجات توليد الصورة. اختر بين PIL: PIL.Image.Image أو np.array.
  • return_dict (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب إرجاع ~pipelines.ltx.LTX2PipelineOutput بدلاً من tuple عادي.
  • attention_kwargs (dict، اختياري) — قاموس kwargs يُمرَّر إلى AttentionProcessor إذا تم تحديده، كما هو معرَّف تحت self.processor في diffusers.models.attention_processor.
  • callback_on_step_end (Callable، اختياري) — دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء أثناء الاستدلال. تُستدعى الدالة بالحجج التالية: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). ستتضمن callback_kwargs قائمة بجميع المصفوفات كما حددتها callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (List، اختياري، القيمة الافتراضية ["latents"]) — قائمة مدخلات المصفوفات (tensors) لدالة callback_on_step_end. سيتم تمرير المصفوفات المحددة في القائمة كمعامل callback_kwargs. لن تتمكن من تضمين سوى المتغيرات المدرجة في خاصية ._callback_tensor_inputs لفئة خط الأنابيب (pipeline) الخاص بك.
  • max_sequence_length (int، اختياري، القيمة الافتراضية 1024) — أقصى طول تسلسل يُستخدم مع prompt.

يعيد

~pipelines.ltx.LTX2PipelineOutput أو tuple

إذا كان return_dict هو True، يُعاد ~pipelines.ltx.LTX2PipelineOutput، وإلا يُعاد tuple يكون عنصره الأول قائمة تحتوي على الصور المولّدة.

الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.

أمثلة:

>>> 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

< >

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

المعاملات

  • prompt (str أو list[str]، اختياري) — الموجّه الذي سيتم ترميزه
  • negative_prompt (str أو list[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الصورة. إذا لم يُعرَّف، يجب تمرير negative_prompt_embeds بدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كان guidance_scale أقل من 1).
  • do_classifier_free_guidance (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم استخدام classifier free guidance أم لا.
  • num_videos_per_prompt (int، اختياري، القيمة الافتراضية 1) — عدد الفيديوهات التي يجب توليدها لكل موجه. جهاز torch الذي سيتم وضع التضمينات الناتجة عليه
  • prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخال prompt.
  • negative_prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخال negative_prompt.
  • device — (torch.device، اختياري): جهاز torch
  • dtype — (torch.dtype، اختياري): نوع بيانات torch

يقوم بتشفير الموجه إلى حالات مخفية لمشفّر النص.

enhance_prompt

< >

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

يعزز prompt المُقدَّم من خلال توليد موجه جديد باستخدام معزز الموجه (نموذج توليد مشروط من Gemma) انطلاقًا منه ومن موجه نظام. عند تقديم image، يُشترط المعزز أيضًا على ذلك الإطار المرجعي (تعزيز بأسلوب I2V / الإطار المفتاحي). يستخدم مكوّن prompt_enhancer المخصص إذا كان مُهيّأً (مثل LTX-2.5، حيث لم يُدرَّب مُشفِّر النص الخاص به على التعزيز)، وإلا فإنه يعود إلى text_encoder الرئيسي (LTX-2.0/2.3، الذي يعمل كمعزز خاص به).

تتطابق قوالب الرسائل، وltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt) مع معاملات فك الترميز، وتنظيف الاستجابة، وتجهيز الجانب الطويل للصورة.

LTX2ImageToVideoPipeline

فئة diffusers.LTX2ImageToVideoPipeline

< >

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

خط أنابيب لتوليد الفيديو من الصور.

مرجع: https://github.com/Lightricks/LTX-Video

TODO

__call__

< >

( 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

المعاملات

  • image (PipelineImageInput) — الصورة المدخلة التي تُشترط عليها عملية التوليد. يجب أن تكون صورة، أو قائمة من الصور، أو torch.Tensor.
  • prompt (str أو list[str]، اختياري) — الموجّه أو الموجّهات التي توجّه توليد الصورة. إذا لم يُعرَّف، يجب تمرير prompt_embeds بدلاً من ذلك.
  • negative_prompt (str أو list[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الصورة. إذا لم يُعرَّف، يجب تمرير negative_prompt_embeds بدلاً منه. يتم تجاهله عند عدم استخدام التوجيه (guidance_scale < 1).
  • height (int، اختياري، القيمة الافتراضية 512) — ارتفاع الصورة المولّدة بالبكسلات. يتم ضبطه على 480 افتراضيًا للحصول على أفضل النتائج.
  • width (int، اختياري، القيمة الافتراضية 768) — عرض الصورة المولدة بالبكسل. يتم ضبطه على 848 افتراضيًا للحصول على أفضل النتائج.
  • num_frames (int, اختياري) — عدد إطارات الفيديو التي سيتم توليدها. إذا لم يُقدَّم، فسيتم افتراض مدة مُقدَّرة تلقائيًا عندما يحتوي هذا الخطّ الأنابيب على مكوّن duration_head (نقاط التفتيش LTX-2.5 وما بعدها)، وإلا فسيكون الافتراضي 121. مرّر عددًا صحيحًا لتحديد الطول صراحةً. تُقَدَّم الأعداد المُقدَّرة تلقائيًا إلى الشبكة الزمنية السببية الخاصة بـ VAE، لذا تكون المدة المحققة مُكمَّمة (حوالي 0.33 ثانية عند 24 إطارًا في الثانية).
  • min_seconds (float، اختياري، القيمة الافتراضية 1.0) — الحد الأدنى للمدة المتوقعة تلقائيًا عندما يُستغنى عن num_frames ويتوفر duration_head. يُتجاهل هذا المعامل عند تحديد num_frames صراحةً.
  • max_seconds (float, اختياري، القيمة الافتراضية 20.0) — الحد الأعلى للمدة المتوقعة تلقائيًا عند إغفال num_frames ووجود duration_head. يُتجاهل عند تعيين num_frames صراحةً. يجب أن يكون أكبر بوضوح من min_seconds.
  • frame_rate (float، اختياري، القيمة الافتراضية 24.0) — عدد الإطارات في الثانية (FPS) للفيديو المولّد.
  • motion_speed (float، اختياري، القيمة الافتراضية 1.0) — سرعة الحركة مقارنةً بالوقت الحقيقي. تُشترط التضمينات الموضعية على frame_rate / motion_speed، لذا فإن القيم الأقل من 1 تُبطئ الحركة، على سبيل المثال 0.2 لحركة بطيئة بمقدار 5 أضعاف في LoRA الخاص بالتحكم بالحركة البطيئة. يبقى frame_rate معدل التشغيل: مدة الصوت وعدد الإطارات المتوقع يتبعانه.
  • num_inference_steps (int، اختياري، القيمة الافتراضية 30) — عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة بجودة أعلى على حساب بطء الاستدلال.
  • sigmas (List[float]، اختياري) — قيم sigmas مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل sigmas في طريقة set_timesteps الخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير num_inference_steps.
  • timesteps (List[int]، اختياري) — خطوات زمنية مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل timesteps في طريقة set_timesteps الخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير num_inference_steps. يجب أن تكون بترتيب تنازلي.
  • guidance_scale (float، اختياري، القيمة الافتراضية 4.0) — مقياس التوجيه كما هو مُعرَّف في Classifier-Free Diffusion Guidance. يُعرَّف guidance_scale على أنه w من المعادلة 2 في Imagen Paper. يتم تفعيل مقياس التوجيه عن طريق تعيين guidance_scale > 1. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بـ prompt النصي، وعادةً على حساب انخفاض جودة الصورة. يُستخدم لوضع الفيديو (يوجد قيمة منفصلة audio_guidance_scale لوضع الصوت).
  • stg_scale (float، اختياري، القيمة الافتراضية 0.0) — مقياس التوجيه للفيديو للتوجيه المكاني-الزمني (STG)، المقترح في Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. يستخدم STG تقديراً يشبه CFG حيث نحرّك العينة بعيداً عن عينة ضعيفة من نسخة مُعطَّبة من نموذج إزالة الضوضاء. تفعيل STG سيؤدي إلى مرور إضافي للأمام في نموذج إزالة الضوضاء؛ القيمة الافتراضية 0.0 تعني أن STG معطَّل.
  • modality_scale (float, اختياري، القيمة الافتراضية 1.0) — مقياس التوجيه للفيديو لعزل الأنماط في LTX-2.X، حيث نُبعد العينة عن عينة أضعف يولدها نموذج إزالة الضوضاء مع تعطيل الانتباه المتقاطع بين الأنماط (من الصوت إلى الفيديو ومن الفيديو إلى الصوت) باستخدام تقدير يشبه CFG. سيؤدي تفعيل توجيه النمط إلى إجراء تمريرة أمامية إضافية لنموذج إزالة الضوضاء؛ تعني القيمة الافتراضية 1.0 أن توجيه النمط معطّل.
  • guidance_rescale (float, optional, defaults to 0.0) — Guidance rescale factor proposed by Common Diffusion Noise Schedules and Sample Steps are Flawed guidance_scale is defined as φ in equation 16. of Common Diffusion Noise Schedules and Sample Steps are Flawed. Guidance rescale factor should fix overexposure when using zero terminal SNR. Used for the video modality.
  • audio_guidance_scale (float, اختياري القيمة الافتراضية None) — مقياس التوجيه الصوتي لـ CFG فيما يتعلق بالموجّه السلبي. قاعدة تحديث CFG هي نفسها للفيديو والصوت، لكن يمكن استخدام قيم مختلفة لمقياس التوجيه. يقترح مؤلفو LTX-2.X أن يكون audio_guidance_scale أعلى نسبيًا من guidance_scale الخاص بالفيديو (على سبيل المثال، يقترحون 3.0 للفيديو و 7.0 للصوت في LTX-2.3). إذا كانت None، فإن القيمة الافتراضية هي قيمة الفيديو guidance_scale.
  • audio_stg_scale (float, اختياري، القيمة الافتراضية None) — مقياس التوجيه الصوتي لـ STG. وكما هو الحال مع CFG، فإن قاعدة التحديث الخاصة بـ STG متطابقة في الغالب لكل من الفيديو والصوت. بالنسبة إلى LTX-2.3، يُقترح استخدام قيمة 1.0 لكل من الفيديو والصوت. إذا كانت None، فإن القيمة الافتراضية هي قيمة الفيديو stg_scale.
  • audio_modality_scale (float, اختياري، القيمة الافتراضية None) — مقياس التوجيه الصوتي لعزل الأنماط في LTX-2.X. وكما هو الحال مع CFG، فإن قاعدة توجيه النمط متطابقة في الغالب لكل من الفيديو والصوت. بالنسبة إلى LTX-2.3، يُقترح استخدام القيمة 3.0 لكل من الفيديو والصوت. إذا كانت None، فإن القيمة الافتراضية هي قيمة الفيديو modality_scale.
  • audio_guidance_rescale (float, اختياري، القيمة الافتراضية None) — عامل إعادة تحجيم إرشادي منفصل لنمط الصوت. إذا كانت القيمة None، فإن القيمة الافتراضية هي قيمة الفيديو guidance_rescale.
  • spatio_temporal_guidance_blocks (list[int]، اختياري، القيمة الافتراضية None) — فهارس كتل التحوّل (transformer blocks) بدءًا من الصفر التي تُطبَّق عليها STG. يجب تقديم هذه القيمة إذا تم استخدام STG (عندما تكون stg_scale أو audio_stg_scale أكبر من 0). يُوصى بقيمة [29] لـ LTX-2.0 ويُوصى بقيمة [28] لـ LTX-2.3.
  • noise_scale (float، اختياري، القيمة الافتراضية 0.0) — عامل الاستيفاء بين الضوضاء العشوائية واللاتنتات منزوعة الضوضاء في كل خطوة زمنية. تطبيق الضوضاء على latents وaudio_latents قبل مواصلة إزالة الضوضاء.
  • num_videos_per_prompt (int، اختياري، القيمة الافتراضية 1) — عدد مقاطع الفيديو التي سيتم توليدها لكل موجه.
  • generator (torch.Generator أو list[torch.Generator]، اختياري) — مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا.
  • latents (torch.Tensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الفيديو. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم إنشاء كائن latents عن طريق الاستخراج باستخدام generator العشوائي المُقدَّم.
  • audio_latents (torch.Tensor، اختياري) — كعوب ضوضائية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصوت. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم إنشاء كعوب باستخدام العينة عبر المولّد العشوائي generator المُقدَّم.
  • prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخال prompt.
  • prompt_attention_mask (torch.Tensor، اختياري) — قناع الانتباه المُولَّد مسبقًا لتضمينات النص.
  • negative_prompt_embeds (torch.FloatTensor، اختياري) — تضمينات نصية سالبة مُولّدة مسبقًا. بالنسبة إلى PixArt-Sigma، يجب أن يكون هذا الموجه السلبي "". إذا لم يُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخال negative_prompt.
  • negative_prompt_attention_mask (torch.FloatTensor، اختياري) — قناع انتباه مُولّد مسبقًا لتضمينات النص السلبية.
  • decode_timestep (float، القيمة الافتراضية 0.0) — خطوة الزمن التي يتم عندها فك ترميز الفيديو المولّد.
  • decode_noise_scale (float، القيمة الافتراضية None) — عامل الاستيفاء بين الضوضاء العشوائية واللاتنتات المُزالة الضوضاء عند خطوة فك الترميز.
  • use_cross_timestep (bool اختياري، القيمة الافتراضية True) — ما إذا كان سيتم استخدام قيمة sigma الخاصة بالوضع المتقاطع (الصوت هو الوضع المتقاطع للفيديو، والعكس صحيح) عند حساب معاملات تعديل الانتباه المتقاطع. True هو سلوك LTX-2.3/2.5؛ وFalse هو سلوك LTX-2.0 القديم.
  • system_prompt (str، اختياري، القيمة الافتراضية None) — موجّه نظام اختياري يُستخدم لتحسين الموجّه. سيُستخدم موجّه النظام من قِبل مُحسّن الموجّه (نموذج توليد مشروط من Gemma — مكوّن prompt_enhancer المخصص إذا كان مُهيأً، وإلا فـ text_encoder الرئيسي) لتوليد موجّه محسّن من الموجّه الأصلي prompt والأول image لتوجيه التوليد. إذا لم يُقدَّم وكان prompt_enhancer مخصصاً مُهيأً (LTX-2.5)، تكون القيمة الافتراضية LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT (من diffusers.pipelines.ltx2.utils) — راجع enable_prompt_enhancement.
  • enable_prompt_enhancement (bool, اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تشغيل تعزيز الأوامر. خيار اختياري، بما يتوافق مع خطوط أنابيب Lightricks المرجعية. عند تعيين True وإهمال system_prompt، يستخدم LTX-2.5 LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT إذا تم تكوين prompt_enhancer مخصص؛ بينما تتطلب إصدارات LTX-2.0/2.3 تحديد system_prompt صراحةً.
  • prompt_max_new_tokens (int, اختياري، القيمة الافتراضية None) — الحد الأقصى لعدد الرموز الجديدة التي سيتم توليدها عند تنفيذ تعزيز الاستعلام. إذا لم يتم تقديمه، يتم استخدام 600 لمُحسِّن الاستعلام المخصص Gemma 4 prompt_enhancer (LTX-2.5) أو 512 كبديل لمُشفِّر النص Gemma 3 text_encoder (LTX-2.0/2.3).
  • prompt_enhancement_kwargs (dict[str, Any], اختياري، القيمة الافتراضية None) — حجج الكلمات المفتاحية لاستدعاء .generate في معزّز الأوامر. إذا لم تُقدَّم، فإنها تتطابق دائمًا مع النموذج الذي يقوم بالتعزيز: do_sample=False, no_repeat_ngram_size=3 (طامع) عند استخدام prompt_enhancer مخصص (LTX-2.5)، أو do_sample=True, temperature=0.7 لـ text_encoder الاحتياطي (LTX-2.0/2.3). راجع https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate لمزيد من التفاصيل.
  • prompt_enhancement_seed (int، اختياري، القيمة الافتراضية 10) — البذرة العشوائية لأي عمليات عشوائية أثناء تعزيز الاستعلام.
  • image_crf (int, اختياري، القيمة الافتراضية None) — قيمة H.264 CRF المستخدمة لإعادة ضغط صورة image الشرطية قبل ترميز VAE، بما يتوافق مع الضغط الذي تم تدريب النموذج عليه. تعني None “استخدام القيمة الافتراضية للنموذج” (33 حتى LTX-2.3، و18 لـ LTX-2.5). مرر 0 لتخطي إعادة الضغط. يتطلب وجود PIL.Image.Image عند تنفيذ إعادة الضغط.
  • output_type (str، اختياري، القيمة الافتراضية "pil") — صيغة مخرجات توليد الصورة. اختر بين PIL: PIL.Image.Image أو np.array.
  • return_dict (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب إرجاع ~pipelines.ltx.LTX2PipelineOutput بدلاً من tuple عادي.
  • attention_kwargs (dict، اختياري) — قاموس kwargs يُمرَّر إلى AttentionProcessor إذا تم تحديده، كما هو معرَّف تحت self.processor في diffusers.models.attention_processor.
  • callback_on_step_end (Callable، اختياري) — دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء أثناء الاستدلال. تُستدعى الدالة بالحجج التالية: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). ستتضمن callback_kwargs قائمة بجميع المصفوفات كما حددتها callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (List, اختياري) — قائمة مدخلات المصفوفات (tensors) لدالة callback_on_step_end. سيتم تمرير المصفوفات المحددة في القائمة كحجة callback_kwargs. لن تتمكن من تضمين سوى المتغيرات المدرجة في خاصية ._callback_tensor_inputs لفئة خط الأنابيب (pipeline) الخاص بك.
  • max_sequence_length (int، اختياري، القيمة الافتراضية 1024) — أقصى طول تسلسل يُستخدم مع prompt.

يعيد

~pipelines.ltx.LTX2PipelineOutput أو tuple

إذا كان return_dict هو True، يُعاد ~pipelines.ltx.LTX2PipelineOutput، وإلا يُعاد tuple يكون عنصره الأول قائمة تحتوي على الصور المولّدة.

الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.

أمثلة:

>>> 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

< >

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

المعاملات

  • prompt (str أو list[str]، اختياري) — الموجّه الذي سيتم ترميزه
  • negative_prompt (str أو list[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الصورة. إذا لم يُعرَّف، يجب تمرير negative_prompt_embeds بدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كان guidance_scale أقل من 1).
  • do_classifier_free_guidance (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم استخدام classifier free guidance أم لا.
  • num_videos_per_prompt (int، اختياري، القيمة الافتراضية 1) — عدد الفيديوهات التي يجب توليدها لكل موجه. جهاز torch الذي سيتم وضع التضمينات الناتجة عليه
  • prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخال prompt.
  • negative_prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخال negative_prompt.
  • device — (torch.device، اختياري): جهاز torch
  • dtype — (torch.dtype، اختياري): نوع بيانات torch

يقوم بتشفير الموجه إلى حالات مخفية لمشفّر النص.

enhance_prompt

< >

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

يعزز prompt المُقدَّم من خلال توليد موجه جديد باستخدام معزز الموجه (نموذج توليد مشروط من Gemma) انطلاقًا منه ومن موجه نظام. عند تقديم image، يُشترط المعزز أيضًا على ذلك الإطار المرجعي (تعزيز بأسلوب I2V / الإطار المفتاحي). يستخدم مكوّن prompt_enhancer المخصص إذا كان مُهيّأً (مثل LTX-2.5، حيث لم يُدرَّب مُشفِّر النص الخاص به على التعزيز)، وإلا فإنه يعود إلى text_encoder الرئيسي (LTX-2.0/2.3، الذي يعمل كمعزز خاص به).

تتطابق قوالب الرسائل، وltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt) مع معاملات فك الترميز، وتنظيف الاستجابة، وتجهيز الجانب الطويل للصورة.

LTX2ConditionPipeline

فئة diffusers.LTX2ConditionPipeline

< >

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

خط أنابيب لتوليد الفيديو يتيح إدراج شروط الصور في أجزاء اختيارية من الفيديو.

مرجع: https://github.com/Lightricks/LTX-Video

TODO

__call__

< >

( 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

المعاملات

  • conditions (List[LTXVideoCondition], *optional*) — قائمة عناصر تكييف الإطارات لتوليد الفيديو.
  • prompt (str أو List[str]، اختياري) — الموجّه أو الموجّهات التي توجّه توليد الصورة. إذا لم يُعرَّف، يجب تمرير prompt_embeds بدلاً من ذلك.
  • negative_prompt (str أو List[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الصورة. إذا لم يُعرَّف، يجب تمرير negative_prompt_embeds بدلاً منه. يتم تجاهله عند عدم استخدام التوجيه (guidance_scale < 1).
  • height (int، اختياري، القيمة الافتراضية 512) — ارتفاع الصورة المولّدة بالبكسلات. يتم ضبطه على 480 افتراضيًا للحصول على أفضل النتائج.
  • width (int، اختياري، القيمة الافتراضية 768) — عرض الصورة المولدة بالبكسل. يتم ضبطه على 848 افتراضيًا للحصول على أفضل النتائج.
  • num_frames (int, اختياري) — عدد إطارات الفيديو التي سيتم توليدها. إذا لم يُقدَّم، فسيتم افتراض مدة مُقدَّرة تلقائيًا عندما يحتوي هذا الخطّ الأنابيب على مكوّن duration_head (نقاط التفتيش LTX-2.5 وما بعدها)، وإلا فسيكون الافتراضي 121. مرّر عددًا صحيحًا لتحديد الطول صراحةً. تُقَدَّم الأعداد المُقدَّرة تلقائيًا إلى الشبكة الزمنية السببية الخاصة بـ VAE، لذا تكون المدة المحققة مُكمَّمة (حوالي 0.33 ثانية عند 24 إطارًا في الثانية).
  • min_seconds (float، اختياري، القيمة الافتراضية 1.0) — الحد الأدنى للمدة المتوقعة تلقائيًا عندما يُستغنى عن num_frames ويتوفر duration_head. يُتجاهل هذا المعامل عند تحديد num_frames صراحةً.
  • max_seconds (float, اختياري، القيمة الافتراضية 20.0) — الحد الأعلى للمدة المتوقعة تلقائيًا عند إغفال num_frames ووجود duration_head. يُتجاهل عند تعيين num_frames صراحةً. يجب أن يكون أكبر بوضوح من min_seconds.
  • frame_rate (float، اختياري، القيمة الافتراضية 24.0) — عدد الإطارات في الثانية (FPS) للفيديو المولّد.
  • motion_speed (float، اختياري، القيمة الافتراضية 1.0) — سرعة الحركة مقارنةً بالوقت الحقيقي. تُشترط التضمينات الموضعية على frame_rate / motion_speed، لذا فإن القيم الأقل من 1 تُبطئ الحركة، على سبيل المثال 0.2 لحركة بطيئة بمقدار 5 أضعاف في LoRA الخاص بالتحكم بالحركة البطيئة. يبقى frame_rate معدل التشغيل: مدة الصوت وعدد الإطارات المتوقع يتبعانه.
  • num_inference_steps (int، اختياري، القيمة الافتراضية 30) — عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة بجودة أعلى على حساب بطء الاستدلال.
  • sigmas (List[float]، اختياري) — قيم sigmas مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل sigmas في طريقة set_timesteps الخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير num_inference_steps.
  • timesteps (List[int]، اختياري) — خطوات زمنية مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل timesteps في طريقة set_timesteps الخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير num_inference_steps. يجب أن تكون بترتيب تنازلي.
  • guidance_scale (float، اختياري، القيمة الافتراضية 4.0) — مقياس التوجيه كما هو مُعرَّف في Classifier-Free Diffusion Guidance. يُعرَّف guidance_scale على أنه w من المعادلة 2 في Imagen Paper. يتم تفعيل مقياس التوجيه عن طريق تعيين guidance_scale > 1. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بـ prompt النصي، وعادةً على حساب انخفاض جودة الصورة. يُستخدم لوضع الفيديو (يوجد قيمة منفصلة audio_guidance_scale لوضع الصوت).
  • stg_scale (float، اختياري، القيمة الافتراضية 0.0) — مقياس التوجيه للفيديو للتوجيه المكاني-الزمني (STG)، المقترح في Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. يستخدم STG تقديراً يشبه CFG حيث نحرّك العينة بعيداً عن عينة ضعيفة من نسخة مُعطَّبة من نموذج إزالة الضوضاء. تفعيل STG سيؤدي إلى مرور إضافي للأمام في نموذج إزالة الضوضاء؛ القيمة الافتراضية 0.0 تعني أن STG معطَّل.
  • modality_scale (float, اختياري، القيمة الافتراضية 1.0) — مقياس التوجيه للفيديو لعزل الأنماط في LTX-2.X، حيث نُبعد العينة عن عينة أضعف يولدها نموذج إزالة الضوضاء مع تعطيل الانتباه المتقاطع بين الأنماط (من الصوت إلى الفيديو ومن الفيديو إلى الصوت) باستخدام تقدير يشبه CFG. سيؤدي تفعيل توجيه النمط إلى إجراء تمريرة أمامية إضافية لنموذج إزالة الضوضاء؛ تعني القيمة الافتراضية 1.0 أن توجيه النمط معطّل.
  • guidance_rescale (float, optional, defaults to 0.0) — Guidance rescale factor proposed by Common Diffusion Noise Schedules and Sample Steps are Flawed guidance_scale is defined as φ in equation 16. of Common Diffusion Noise Schedules and Sample Steps are Flawed. Guidance rescale factor should fix overexposure when using zero terminal SNR. Used for the video modality.
  • audio_guidance_scale (float, اختياري القيمة الافتراضية None) — مقياس التوجيه الصوتي لـ CFG فيما يتعلق بالموجّه السلبي. قاعدة تحديث CFG هي نفسها للفيديو والصوت، لكن يمكن استخدام قيم مختلفة لمقياس التوجيه. يقترح مؤلفو LTX-2.X أن يكون audio_guidance_scale أعلى نسبيًا من guidance_scale الخاص بالفيديو (على سبيل المثال، يقترحون 3.0 للفيديو و 7.0 للصوت في LTX-2.3). إذا كانت None، فإن القيمة الافتراضية هي قيمة الفيديو guidance_scale.
  • audio_stg_scale (float, اختياري، القيمة الافتراضية None) — مقياس التوجيه الصوتي لـ STG. وكما هو الحال مع CFG، فإن قاعدة التحديث الخاصة بـ STG متطابقة في الغالب لكل من الفيديو والصوت. بالنسبة إلى LTX-2.3، يُقترح استخدام قيمة 1.0 لكل من الفيديو والصوت. إذا كانت None، فإن القيمة الافتراضية هي قيمة الفيديو stg_scale.
  • audio_modality_scale (float, اختياري، القيمة الافتراضية None) — مقياس التوجيه الصوتي لعزل الأنماط في LTX-2.X. وكما هو الحال مع CFG، فإن قاعدة توجيه النمط متطابقة في الغالب لكل من الفيديو والصوت. بالنسبة إلى LTX-2.3، يُقترح استخدام القيمة 3.0 لكل من الفيديو والصوت. إذا كانت None، فإن القيمة الافتراضية هي قيمة الفيديو modality_scale.
  • audio_guidance_rescale (float, اختياري، القيمة الافتراضية None) — عامل إعادة تحجيم إرشادي منفصل لنمط الصوت. إذا كانت القيمة None، فإن القيمة الافتراضية هي قيمة الفيديو guidance_rescale.
  • spatio_temporal_guidance_blocks (list[int]، اختياري، القيمة الافتراضية None) — فهارس كتل التحوّل (transformer blocks) بدءًا من الصفر التي تُطبَّق عليها STG. يجب تقديم هذه القيمة إذا تم استخدام STG (عندما تكون stg_scale أو audio_stg_scale أكبر من 0). يُوصى بقيمة [29] لـ LTX-2.0 ويُوصى بقيمة [28] لـ LTX-2.3.
  • noise_scale (float، اختياري، القيمة الافتراضية None) — عامل الاستيفاء بين الضوضاء العشوائية واللاتنتات المُزالة الضوضاء في كل خطوة زمنية. تطبيق الضوضاء على latents وaudio_latents قبل مواصلة إزالة الضوضاء. إذا لم يتم ضبطه، فسيتم استنتاجه من جدول سيجما.
  • num_videos_per_prompt (int، اختياري، القيمة الافتراضية 1) — عدد مقاطع الفيديو التي سيتم توليدها لكل موجه.
  • generator (torch.Generator أو List[torch.Generator]، اختياري) — مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا.
  • latents (torch.Tensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الفيديو. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم إنشاء كائن latents عن طريق الاستخراج باستخدام generator العشوائي المُقدَّم.
  • audio_latents (torch.Tensor، اختياري) — كعوب ضوضائية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصوت. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم إنشاء كعوب باستخدام العينة عبر المولّد العشوائي generator المُقدَّم.
  • prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخال prompt.
  • prompt_attention_mask (torch.Tensor، اختياري) — قناع الانتباه المُولَّد مسبقًا لتضمينات النص.
  • negative_prompt_embeds (torch.FloatTensor، اختياري) — تضمينات نصية سالبة مُولّدة مسبقًا. بالنسبة إلى PixArt-Sigma، يجب أن يكون هذا الموجه السلبي "". إذا لم يُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخال negative_prompt.
  • negative_prompt_attention_mask (torch.FloatTensor، اختياري) — قناع انتباه مُولّد مسبقًا لتضمينات النص السلبية.
  • decode_timestep (float، القيمة الافتراضية 0.0) — خطوة الزمن التي يتم عندها فك ترميز الفيديو المولّد.
  • decode_noise_scale (float، القيمة الافتراضية None) — عامل الاستيفاء بين الضوضاء العشوائية واللاتنتات المُزالة الضوضاء عند خطوة فك الترميز.
  • use_cross_timestep (bool اختياري، القيمة الافتراضية True) — ما إذا كان سيتم استخدام قيمة sigma الخاصة بالوضع المتقاطع (الصوت هو الوضع المتقاطع للفيديو، والعكس صحيح) عند حساب معاملات تعديل الانتباه المتقاطع. True هو سلوك LTX-2.3/2.5؛ وFalse هو سلوك LTX-2.0 القديم.
  • system_prompt (str، اختياري، القيمة الافتراضية None) — موجّه نظام اختياري يُستخدم لتحسين الموجّه. سيُستخدم موجّه النظام من قِبل مُحسّن الموجّه (نموذج توليف شرطي من Gemma — مكوّن prompt_enhancer المخصص إذا كان مُهيأً، وإلا فـ text_encoder الرئيسي) لتوليد موجّه محسّن من الموجّه الأصلي prompt (وصورة شرطية عندما تكون متاحة) لتوجيه عملية التوليف. إذا لم يُقدَّم وتم تهيئة prompt_enhancer مخصص (LTX-2.5)، تكون القيمة الافتراضية LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT عندما تكون صورة شرطية متاحة، وإلا LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT — راجع enable_prompt_enhancement.
  • enable_prompt_enhancement (bool, اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تشغيل تعزيز الأوامر. خيار اختياري، يتوافق مع خطوط أنابيب Lightricks المرجعية. عند تعيين True وإهمال system_prompt، يختار LTX-2.5 بين LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT / LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT بناءً على توفر صورة شرطيّة.
  • prompt_max_new_tokens (int, اختياري، القيمة الافتراضية None) — الحد الأقصى لعدد الرموز الجديدة التي سيتم توليدها عند تنفيذ تعزيز الاستعلام. إذا لم يتم تقديمه، يتم استخدام 600 لمُحسِّن الاستعلام المخصص Gemma 4 prompt_enhancer (LTX-2.5) أو 512 كبديل لمُشفِّر النص Gemma 3 text_encoder (LTX-2.0/2.3).
  • prompt_enhancement_kwargs (dict[str, Any], اختياري، القيمة الافتراضية None) — حجج الكلمات المفتاحية لاستدعاء .generate في معزّز الأوامر. إذا لم تُقدَّم، فإنها تتطابق دائمًا مع النموذج الذي يقوم بالتعزيز: do_sample=False, no_repeat_ngram_size=5 (طامع) عند استخدام prompt_enhancer مخصص (LTX-2.5)، أو do_sample=True, temperature=0.7 لـ text_encoder الاحتياطي (LTX-2.0/2.3). راجع https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate لمزيد من التفاصيل.
  • prompt_enhancement_seed (int، اختياري، القيمة الافتراضية 10) — البذرة العشوائية لأي عمليات عشوائية أثناء تعزيز الاستعلام.
  • output_type (str، اختياري، القيمة الافتراضية "pil") — صيغة مخرجات توليد الصورة. اختر بين PIL: PIL.Image.Image أو np.array.
  • return_dict (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب إرجاع ~pipelines.ltx.LTX2PipelineOutput بدلاً من tuple عادي.
  • attention_kwargs (dict، اختياري) — قاموس kwargs يُمرَّر إلى AttentionProcessor إذا تم تحديده، كما هو معرَّف تحت self.processor في diffusers.models.attention_processor.
  • callback_on_step_end (Callable، اختياري) — دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء أثناء الاستدلال. تُستدعى الدالة بالحجج التالية: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). ستتضمن callback_kwargs قائمة بجميع المصفوفات كما حددتها callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (List, اختياري) — قائمة مدخلات المصفوفات (tensors) لدالة callback_on_step_end. سيتم تمرير المصفوفات المحددة في القائمة كحجة callback_kwargs. لن تتمكن من تضمين سوى المتغيرات المدرجة في خاصية ._callback_tensor_inputs لفئة خط الأنابيب (pipeline) الخاص بك.
  • max_sequence_length (int، اختياري، القيمة الافتراضية 1024) — أقصى طول تسلسل يُستخدم مع prompt.

يعيد

~pipelines.ltx.LTX2PipelineOutput أو tuple

إذا كان return_dict هو True، يُعاد ~pipelines.ltx.LTX2PipelineOutput، وإلا يُعاد tuple يكون عنصره الأول قائمة تحتوي على الصور المولّدة.

الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.

أمثلة:

>>> 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

< >

( latents: Tensorconditioning_mask: Tensorcondition_latents: listcondition_strengths: listcondition_indices: listlatent_height: intlatent_width: int ) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor]

المعاملات

  • latents (torch.Tensor) — القيم الكامنة الأولية المُجمّعة (المُقسّمة إلى بقع) ذات الشكل [batch_size, patch_seq_len, hidden_dim].
  • conditioning_mask (torch.Tensor) — قناع التكييف المعبأ (المقسّم إلى رقعات) الأولي ذو الشكل [batch_size, patch_seq_len, 1] بقيم ضمن [0, 1] حيث يعني 0 أن مخرج نموذج إزالة الضوضاء سيُستخدم بالكامل، ويعني 1 أن شرط التكييف سيُستخدم بالكامل.

يعيد

Tuple[torch.Tensor, torch.Tensor, torch.Tensor]

يعيد ثلاثية من الموترات حيث:

  1. كائنات الفيديو المعبأة مع تطبيق شروط الإطار الأول.
  2. قناع التعبئة الشرطي مع تطبيق قوى الإطار الأول.
  3. كعوب الشرط النظيفة في مواضع الإطار الأول (صفوف في المواضع الأخرى).

طبّق التكييف البصري للإطار الأول عن طريق تجاوز الرموز عند مواضع الإطار الأول.

تُطبَّق هنا فقط الشروط التي يكون فيها latent_idx == 0 (مطابقةً لـVideoConditionByLatentIndex في التنفيذ المرجعي). أما الشروط عند فهارس كامنة غير صفرية فتُضاف كرموز إطارات أساسية منفصلة عبر prepare_keyframe_extras (مطابقةً لـVideoConditionByKeyframeIndex) وتُتخطى هنا.

encode_prompt

< >

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

المعاملات

  • prompt (str أو list[str]، اختياري) — الموجّه الذي سيتم ترميزه
  • negative_prompt (str أو list[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الصورة. إذا لم يُعرَّف، يجب تمرير negative_prompt_embeds بدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كان guidance_scale أقل من 1).
  • do_classifier_free_guidance (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم استخدام classifier free guidance أم لا.
  • num_videos_per_prompt (int، اختياري، القيمة الافتراضية 1) — عدد الفيديوهات التي يجب توليدها لكل موجه. جهاز torch الذي سيتم وضع التضمينات الناتجة عليه
  • prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخال prompt.
  • negative_prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخال negative_prompt.
  • device — (torch.device، اختياري): جهاز torch
  • dtype — (torch.dtype، اختياري): نوع بيانات torch

يقوم بتشفير الموجه إلى حالات مخفية لمشفّر النص.

enhance_prompt

< >

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

يعزز prompt المُقدَّم من خلال توليد موجه جديد باستخدام معزز الموجه (نموذج توليد مشروط من Gemma) انطلاقًا منه ومن موجه نظام. عند تقديم image، يُشترط المعزز أيضًا على ذلك الإطار المرجعي (تعزيز بأسلوب I2V / الإطار المفتاحي). يستخدم مكوّن prompt_enhancer المخصص إذا كان مُهيّأً (مثل LTX-2.5، حيث لم يُدرَّب مُشفِّر النص الخاص به على التعزيز)، وإلا فإنه يعود إلى text_encoder الرئيسي (LTX-2.0/2.3، الذي يعمل كمعزز خاص به).

تتطابق قوالب الرسائل، وltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt) مع معاملات فك الترميز، وتنظيف الاستجابة، وتجهيز الجانب الطويل للصورة.

prepare_latents

< >

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

جهّز كامنات الفيديو الضوضائية، مع تطبيق شروط الإطارات.

تُطبَّق شروط الإطار الأول (latent_idx == 0) عن طريق تجاوز الرموز الموجودة في مواضع الإطار الأول (بمفهوم VideoConditionByLatentIndex). أما شروط غير الإطار الأول (latent_idx > 0) فتُدمج مع تسلسل الكامنة الرئيسي مع conditioning_mask = strength لكل رمز (بمفهوم VideoConditionByKeyframeIndex) — ثم تتولى معادلة الخطوة الزمنية الموجودة مسبقاً في حلقة إزالة الضوضاء t * (1 - conditioning_mask) وخلط ما بعد المعالجة denoised * (1 - conditioning_mask) + clean * conditioning_mask إدارتها عبر الخطوات.

يعيد رباعيًا رباعيًا:

  • latents: كامنات ضجيج مُجمّعة (رموز الأساس + أي رموز إطارات مفتاحية مُلحقة على بُعد التسلسل).
  • conditioning_mask: قناع تكييف مُجمَّع بقيم ضمن [0, 1] — 1 في مواضع الإطار الأول، strength في مواضع الإطارات الرئيسية، و0 في بقية المواضع.
  • clean_latents: قيم الشرط النظيفة عند المواضع المشروطة (أصفار في المواضع الأخرى)؛ بنفس شكل latents.
  • keyframe_coords: إحداثيات موضعية [B, 3, num_keyframe_patches, 2] لإضافتها إلى video_coords، أو None إذا لم تكن هناك شروط غير إطار البداية.

preprocess_conditions

< >

( 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]]

المعاملات

  • conditions (LTX2VideoCondition أو List[LTX2VideoCondition]، اختياري، القيمة الافتراضية None) — قائمة من حالات الصورة/الفيديو.
  • height (int، اختياري، القيمة الافتراضية 512) — الارتفاع المطلوب بالبكسل.
  • width (int، اختياري، القيمة الافتراضية 768) — العرض المطلوب بالبكسل.
  • num_frames (int، اختياري، القيمة الافتراضية 121) — عدد الإطارات المطلوب في الفيديو المولّد.
  • device (torch.device، اختياري، القيمة الافتراضية None) — الجهاز الذي سيتم وضع تينسورات الصور/الفيديو المُعالَجة مسبقًا عليه.

يعيد

Tuple[List[torch.Tensor], List[float], List[int], List[int]]

يعيد رباعيًا من قوائم بطول len(conditions) على النحو التالي:

  1. القائمة الأولى هي قائمة من متجهات الفيديو المُعالَجة مسبقًا على شكل [batch_size=1, num_channels, num_frames, height, width].
  2. القائمة الثانية هي قائمة لقوى التكييف.
  3. القائمة الثالثة هي قائمة فهارس فضاء الكمون لكل شرط.
  4. القائمة الرابعة هي قائمة بعدد الإطارات (المقصوصة) في فضاء البكسلات لكل حالة. وهذا ضروري لدلالات إحداثيات الإطارات الرئيسية (فالإطارات الرئيسية ذات البكسل الواحد لها امتداد زمني مُقيَّد).

يعالج صور/فيديوهات الشرط مسبقاً إلى متجهات torch.

trim_conditioning_sequence

< >

( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int

المعاملات

  • start_frame (int) — رقم الإطار المستهدف للإطار الأول في التسلسل.
  • sequence_num_frames (int) — عدد الإطارات في التسلسل.
  • target_num_frames (int) — عدد الإطارات المستهدف في الفيديو المولّد.

يعيد

int

طول التسلسل المحدّث

اقتصاص تسلسل الشرط إلى عدد الإطارات المسموح به.

LTX2DFRPipeline

فئة diffusers.LTX2DFRPipeline

< >

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

المعاملات

  • scheduler (FlowMatchEulerDiscreteScheduler) — جدول زمني يُستخدم بالاقتران مع transformer لإزالة الضوضاء من كائنات الفيديو المُرمّزة.
  • vae (AutoencoderKLLTX2Video) — نموذج الترميز التبايني التلقائي (VAE) لتشفير وفك تشفير مقاطع الفيديو إلى تمثيلات كامنة ومنها.
  • audio_vae (AutoencoderKLLTX2Audio) — نموذج VAE للصوت لتشفير وفك تشفير مطيافات الصوت.
  • text_encoder (Gemma3ForConditionalGeneration أو Gemma4UnifiedForConditionalGeneration) — نموذج ترميز النص.
  • tokenizer (GemmaTokenizer أو GemmaTokenizerFast) — مُجزِّئ (Tokenizer) لمُشفِّر النص.
  • connectors (LTX2TextConnectors) — مكدس موصلات النص المستخدم لتكييف حالات المُشفِّر النصي المخفية لفروع الفيديو والصوت.
  • transformer (LTX2VideoTransformer3DModel) — بنية Transformer شرطية لإزالة الضوضاء من كامنات الفيديو المُرمّزة.
  • vocoder (LTX2Vocoder أو LTX2VocoderWithBWE) — مُصوِّغ صوتي لتحويل مطياف الميّل إلى موجات صوتية.
  • processor (ProcessorMixin، اختياري) — المعالج المستخدم لتحسين الأوامر عبر قوالب الدردشة.
  • prompt_enhancer (Gemma4ForConditionalGeneration، اختياري) — نموذج مخصص لتعزيز الأوامر (LTX-2.5).
  • duration_head (LTX2DurationHead، اختياري) — يتنبأ بـnum_frames من تمثيلات الموجه (prompt embeddings) عندما لا يُزود بـnum_frames.

خط أنابيب لمرحلة إزالة الضوضاء الواحدة في عرض الدقة الانتشارية (DFR) باستخدام LTX-2.5.

تولّد كل تمريرة فيديو و فتحات إطارات أساسية إضافية ذات بكسل واحد، أو تعيد إزالة الضوضاء عن الكمونيات المُقدَّمة المُستبَدة من تلك الفتحات. يركّب المستدعون المراحل: هذا الخطّ الأنابيب بدقة نصفية، LTX2LatentUpsamplePipeline مكانياً، ثم هذا الخطّ الأنابيب مجدداً بدقة كاملة مع الفتحات المُوسَّعة ومرجع IC-LoRA، ثم LTX2DFRTemporalRefinePipeline لكل جولة تحسين زمني. راجع وثائق LTX-2 للحصول على وصفة 1080p.

تأتي مواضع الفتحات من شبكة مقاطع مُحاذاة للحد الزمني الخاص بـ VAE (resolve_canvas). يتم توسيد اللوحة إلى عدد صحيح من المقاطع؛ ويعيد output_type="latent" تلك الشبكة الموسَّدة حتى لا تُهمل الفتحة الواقعة على التوسيد. استخدم trim_canvas قبل فك ترميز VAE.

يتطلب محوّلاً (transformer) يحدد في ملفه الإعدادي use_keyframes_abs_pos_embedding (LTX-2.5 وما بعده) عند تعيين generate_slots=True.

مرجع: https://github.com/Lightricks/LTX-2

__call__

< >

( 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

المعاملات

  • prompt (str أو List[str]، اختياري) — الموجّه أو الموجّهات التي توجّه توليد الفيديو. إذا لم يُعرَّف، يجب تمرير prompt_embeds.
  • conditions (LTX2VideoCondition أو List[LTX2VideoCondition]، اختياري) — شروط على مستوى الإطار على شكل صورة أو فيديو. index هو فهرس كامن على num_frames لهذا المرور.
  • height (int، اختياري، القيمة الافتراضية 704) — الارتفاع بالبكسلات لـ هذه المرحلة، وليس المخرج النهائي المُركَّب.
  • width (int، اختياري، القيمة الافتراضية 1216) — العرض بالبكسل لهذا المرور.
  • num_frames (int, اختياري) — عدد إطارات البكسل لهذا المرور، قبل توسيط اللوحة الداخلية. إذا لم يُقدَّم، يتم التنبؤ بالمدة من الأمر بواسطة duration_head. يجب أن يحقق الشرط (num_frames - 1) % 8 == 0.
  • frame_rate (float، اختياري، القيمة الافتراضية 24.0) — معدل الإطارات في الثانية (fps) لهذا المسار. يتم تثبيت زمن RoPE على 60 عندما يتجاوز هذا المعدل 30.
  • min_seconds (float، اختياري، القيمة الافتراضية 1.0) — الحد الأدنى للمدة التي يتم التنبؤ بها تلقائيًا عند إغفال num_frames.
  • max_seconds (float، اختياري، القيمة الافتراضية 20.0) — الحد الأعلى للمدة المتوقعة تلقائيًا عند إغفال num_frames.
  • latents (torch.Tensor، اختياري) — كائنات فيديو خام بأبعاد (batch_size, channels, frames, height, width) لإعادة إزالة الضوضاء (المرحلة 2 / الخاتمة).
  • audio_latents (torch.Tensor، اختياري) — كائنات صوت خام غير مُفككة البنية (batch_size, channels, length, mel_bins). ما يزال المرحلتان 2 تنفّذ مرورًا مشتركًا للصوت؛ أمّا الموجة الصوتية المُرسَلة لوصفة مُركّبة فهي من المرحلة 1، والتي يحتفظ بها المُستدعي.
  • keyframes_latents (torch.Tensor، اختياري) — قيم البداية الخام للفجوات بأبعاد (batch_size, channels, num_slots, height, width)، تُستخدم عند تعيين generate_slots=True.
  • keyframe_positions (list[int]، اختياري) — فهارس إطارات البكسل للفتحات المولّدة. القيمة الافتراضية هي resolve_canvas(num_frames).
  • reference_latents (torch.Tensor، اختياري) — فيديو IC-LoRA المرجعي الخام (عادةً إطارات المرحلة 1).
  • reference_downscale_factor (int، اختياري، القيمة الافتراضية 2) — النسبة بين هذه المرحلة ودقة المرجع، وتُستخدم لتغيير حجم إحداثيات الرموز المرجعية.
  • guidance_keyframe_latents (torch.Tensor، اختياري) — إطارات توجيه خام مثبتة (batch_size, channels, K, height, width) — مسار الخاتمة. ليست فتحات مولّدة.
  • guidance_keyframe_positions (list[int]، اختياري) — فهارس إطارات البكسل الخاصة بـ guidance_keyframe_latents.
  • guidance_keyframe_strength (float، اختياري، القيمة الافتراضية 1.0) — قوة التكييف لإطارات التوجيه المثبتة.
  • generate_slots (bool، اختياري، القيمة الافتراضية True) — إضافة رموز فتحات الإطارات المفتاحية المولّدة. يحدد الخاتمة هذه القيمة على False ويثبّت guidance_keyframe_latents بدلاً من ذلك.
  • sigmas (list[float]، اختياري) — جدول الضوضاء لهذا المرور، دون القيمة النهائية 0.0.
  • noise_scale (float، اختياري) — مستوى الضوضاء الذي تبدأ منه الرموز غير المشروطة. القيمة الافتراضية هي sigmas[0].
  • freeze_audio (bool، اختياري، القيمة الافتراضية False) — إبقاء الصوت عند قيمة sigma 0 (في مرحلة الخاتمة / عند اتباع موجة صوتية من المرحلة الأولى المجمّدة).
  • video_tiles (list[LTX2DFREpilogueTile]، اختياري) — تقسيم مرحلة الخاتمة من epilogue_tiles()، بحيث يمكن أن تتقدم لوحة واحدة خطوةً واحدة حتى لو كانت الدقة كبيرة جداً لتُعالج في تمريرة أمامية واحدة: كل خطوة تُشغّل المحوّل مرةً واحدة لكل بلاطة وتدمج التنبؤات. يتم تحويل ذلك إلى خطة رموز مقابل إحداثيات RoPE الخاصة بتمريرة هذا المسار، ولهذا السبب يُمرر التخطيط بدلاً من الخطة — الإحداثيات لا توجد إلا بعد تشغيل prepare_latents().
  • num_videos_per_prompt (int، اختياري، القيمة الافتراضية 1) — عدد مقاطع الفيديو التي سيتم توليدها لكل موجه.
  • generator (torch.Generator أو list[torch.Generator]، اختياري) — مولّد عشوائي أو مولّدات عشوائية للتكرارية.
  • prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية مُولّدة مسبقًا.
  • prompt_attention_mask (torch.Tensor، اختياري) — قناع الانتباه المُولَّد مسبقًا لتضمينات النص.
  • decode_timestep (float، القيمة الافتراضية 0.0) — خطوة الزمن التي يتم عندها فك ترميز الفيديو المولّد.
  • decode_noise_scale (float، القيمة الافتراضية None) — مقياس الضوضاء عند فك الترميز.
  • use_cross_timestep (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم استخدام sigma بين الوسائط (cross-modality) لتعديل الانتباه المتقاطع (cross attention). True لنسخ LTX-2.3 وما بعدها.
  • system_prompt (str، اختياري) — موجّه نظام اختياري لتعزيز الموجّه. راجع enable_prompt_enhancement.
  • enable_prompt_enhancement (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تشغيل تعزيز الاستعلام.
  • prompt_max_new_tokens (int, اختياري) — الحد الأقصى لعدد الرموز الجديدة التي سيتم توليدها عند تنفيذ تعزيز الاستعلام.
  • prompt_enhancement_kwargs (dict[str, Any], اختياري) — حجج الكلمات المفتاحية لاستدعاء .generate في معزّز الأوامر.
  • prompt_enhancement_seed (int، اختياري، القيمة الافتراضية 10) — البذرة العشوائية لأي عمليات عشوائية أثناء تعزيز الاستعلام.
  • output_type (str، اختياري، الافتراضي "pil") — صيغة الإخراج. اختر "pil" أو "np" أو "pt" أو "latent". الإخراج الكامن هو اللوحة غير المقصوصة.
  • return_dict (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب إرجاع LTX2DFRPipelineOutput أو مجرد مجموعة (frames, audio, keyframes, keyframe_positions).
  • attention_kwargs (dict، اختياري) — معاملات إضافية تُمرَّر إلى معالج الانتباه.
  • callback_on_step_end (Callable، اختياري) — دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء.
  • callback_on_step_end_tensor_inputs (List، اختياري، القيمة الافتراضية ["latents"]) — مدخلات المصفوفات (Tensors) لدالة الاستدعاء (callback).
  • max_sequence_length (int، اختياري، القيمة الافتراضية 1024) — أقصى طول للسلسلة الخاصة بالموجّه النصي.

يعيد

LTX2DFRPipelineOutput أو tuple

إذا كان return_dict هو True، يُعاد LTX2DFRPipelineOutput، وإلا يُعاد tuple من (video, audio, keyframes, keyframe_positions).

الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.

مرور إزالة ضوضاء واحد عند height × width. قم بتجميع المراحل في المستدعي: هذا الخط الأنابيب بدقة نصفية، ثم تكبير مكاني، ثم هذا الخط الأنابيب مرة أخرى مع latents / keyframes_latents / reference_latents، ثم LTX2DFRTemporalRefinePipeline لكل جولة زمنية.

أمثلة:

>>> 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",
... )

إزالة الضوضاء

< >

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

المعاملات

  • sigmas (list[float]) — جدول الضوضاء لهذا المرور، دون القيمة النهائية 0.0.
  • freeze_audio (bool، اختياري، القيمة الافتراضية False) — يُبقي audio_latents نظيفًا (خطوة زمنية/سيجما 0، بدون خطوة أويلر للصوت) مع الاستمرار في تشغيل الانتباه المتقاطع من الصوت إلى الفيديو. يُتجاهل عندما تكون audio_latents هي None.
  • video_tile_plan (list، اختياري) — خطة الرموز لكل بلاطة من video_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. عند تقديمه، يعمل المحوّل مرة واحدة لكل بلاطة في كل خطوة، ثم يمزج التنبؤات، بحيث لا يزال المُعيّن يتقدم على لوحة كاملة واحدة، وتتفق البلاطات على مناطق تداخلها في كل خطوة.
  • generator (torch.Generator، اختياري) — يُمرَّر إلى LTXEulerAncestralRFScheduler.step(). تمرّ البلاطات الزمنية ببذرة لكل بلاطة حتى لا تتشارك السحوبات الأصلية تدفّقًا واحدًا أو تستهلك الحالة التي تقرأها الضوضاء الأولية للبلاطة التالية. لا يقرأ Euler المُقطّر هذا المعامل.
  • step_offset (int) — مؤشر الخطوة الأولى لهذا المرور ضمن الجدول الزمني الكامل للخط، ويُستخدم في callback_on_step_end وشريط التقدم المشترك.

نفّذ مسار إزالة ضوضاء واحدًا لـ DFR على sigmas وأعد (latents, audio_latents)، وكلاهما ما يزال مضغوطًا.

يُستخدم الجدول المُقطَّر دون إرشاد حر من المُصنِّف، لذا فإن كل خطوة تتطلب استدعاءً واحدًا فقط لتحويلة. تُنفَّذ كلتا البعثات في كل مرور، لأن فرع الفيديو يحتاج إلى الانتباه بين الوسائط حتى في الحالات التي يُتخلَّى فيها عن الصوت الذي ينتجه. يحافظ freeze_audio=True على مسار الصوت عند قيمة سيجما صفر (بدون خطوة أويلر) بحيث لا يزال بإمكان الفيديو الانتباه إليه عبر الوسائط — وتستخدم بلاطات التزويد الزمني والفصل الختامي هذا لمتابعة الكلام من المرحلة الأولى دون أن تعيد كل بلاطة إزالة الضوضاء عن تجسيد صوتي مختلف.

بعد مزج شرط x0، تكون السرعة (latents - denoised) / sigma لذا يستعيد خطوة RF x0 = x - σ v القيمة denoised الممزوجة. تحافظ المرحلتان 1 / 2 / الخاتمة على FlowMatchEulerDiscreteScheduler وتتخذ خطوة أويلر تلك كما هي. أما تحسين الزمن فيستبدلها بـ LTXEulerAncestralRFScheduler (eta=0.5)؛ إذ تعيد تلك الخطوة إضافة الضوضاء إلى كل رمز، لذا يُعاد تطبيق مزج الشرط بعدها وإلا تآكلت نقاط التثبيت عند الفواصل بقوة 0.95.

encode_conditions

< >

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

معالجة الشروط الإطارية مسبقاً وتشفيرها باستخدام VAE، مع تحديد موضعها حسب الإطار البكسلي.

يعيد (pixel_frame_index, latent, strength, num_pixel_frames) لكل شرط، جاهزًا لـ condition_latents الخاص بـ prepare_latents(). يُحافظ على فصل الترميز عن التوزيع لأن جولات التحسين الزمني تضاعف موضع الشرط بمعامل 2 ** round وتعيد ضبطه لكل بلاطة، ولا ينبغي إعادة ترميز نفس الإطار الثابت مرة واحدة لكل بلاطة لتحقيق ذلك.

المؤشر المُعاد يقع على شبكة بكسلات num_frames الخاصة به؛ ونقله إلى لوحة محسّنة هو من مسؤولية المُستدعي.

encode_prompt

< >

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

المعاملات

  • prompt (str أو list[str]، اختياري) — الموجّه الذي سيتم ترميزه
  • num_videos_per_prompt (int، اختياري، القيمة الافتراضية 1) — عدد الفيديوهات التي يجب توليدها لكل موجه.
  • prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخال prompt.
  • prompt_attention_mask (torch.Tensor، اختياري) — قناع الانتباه المُولَّد مسبقًا لـprompt_embeds.
  • device — (torch.device، اختياري): جهاز torch
  • dtype — (torch.dtype، اختياري): نوع بيانات torch

يقوم بتشفير الموجه إلى حالات مخفية لمشفّر النص.

تُنفّذ DFR جدول سيجما المُقطّر، والذي تم تدريبه ليُستخدم دون إرشاد حرّ من المُصنّف، لذا لا يوجد فرع سلبي هنا.

enhance_prompt

< >

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

يعزز prompt المُقدَّم من خلال توليد موجه جديد باستخدام معزز الموجه (نموذج توليد مشروط من Gemma) انطلاقًا منه ومن موجه نظام. عند تقديم image، يُشترط المعزز أيضًا على ذلك الإطار المرجعي (تعزيز بأسلوب I2V / الإطار المفتاحي). يستخدم مكوّن prompt_enhancer المخصص إذا كان مُهيّأً (مثل LTX-2.5، حيث لم يُدرَّب مُشفِّر النص الخاص به على التعزيز)، وإلا فإنه يعود إلى text_encoder الرئيسي (LTX-2.0/2.3، الذي يعمل كمعزز خاص به).

تتطابق قوالب الرسائل، وltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt) مع معاملات فك الترميز، وتنظيف الاستجابة، وتجهيز الجانب الطويل للصورة.

prepare_latents

< >

( 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]

المعاملات

  • conditions (list[LTX2VideoCondition]، اختياري) — شروط الصور/الفيديو على مستوى الإطار، موضوعة حسب فهرس الكمون.
  • condition_latents (list[tuple[int, torch.Tensor, float, int]], اختياري) — بديل مُرمَّز مسبقًا لـ conditions، على شكل (pixel_frame_index, latent, strength, num_pixel_frames). يُستخدم فهرس البكسل بدلاً من فهرس الكامنة، لأن جولة التزويد الزمني تضاعف موضع الشرط بمعامل 2 ** round، ولا يهبط الناتج عادةً على حدّ الكامنة — فإنما يمكن لرمز إطار مفتاحي مُضاف أن يستقر هناك، ويُوضع وفق البكسل. لا يزال pixel_frame_index == 0 يعني «استبدال الإطار الأول».
  • keyframe_latents (list[tuple[int, torch.Tensor, float]], اختياري) — إرشادات الإطارات الرئيسية المُرمّزة مسبقًا على شكل (pixel_frame_index, latent, strength)، حيث يكون شكل latent (batch_size, num_channels_latents, 1, latent_height, latent_width). تُستخدم في جولات التزويد الزمني لتثبيت الإطارات الرئيسية عند نقاط الالتحام المنقولة من الجولة السابقة.
  • slot_frame_indices (list[int]، اختياري) — مواضع الإطارات البكسلية للفواصل الرئيسية المولّدة.
  • slot_initial_latents (torch.Tensor، اختياري) — (batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width) المحتوى الذي يُكتب في رموز الفتحات قبل إضافة الضوضاء.
  • reference_latents (torch.Tensor، اختياري) — (batch_size, num_channels_latents, F, H, W) متغير كامن مرجعي لـ IC-LoRA.
  • reference_downscale_factor (int، القيمة الافتراضية 1) — النسبة بين الدقة المستهدفة ودقة المرجع.
  • latents (torch.Tensor، اختياري) — (batch_size, num_channels_latents, F, H, W) المحتوى الأولي للرموز الأساسية. كائنات latents في خط الأنابيب العام تكون خامّة (غير مُعايرة)؛ مرّر latents_normalized=False عند تلك النقطة. حلقات البلاطات التي تعمل بالفعل في فضاء مُعاير بواسطة VAE تُبقي على القيمة الافتراضية.
  • latents_normalized (bool، القيمة الافتراضية True) — ما إذا كانت latents وslot_initial_latents وreference_latents وkeyframe_latents مُطبَّعة مسبقًا بواسطة VAE. تمر حلقات البلاطات الداخلية القيمة True؛ بينما تمر كل خط أنابيب عبر __call__ القيمة False.
  • noise_scale (float، القيمة الافتراضية 1.0) — مستوى الضوضاء الذي تُهيَّأ به الرموز غير المشروطة، أي أول قيمة سيغما في الجدول الزمني.

يعيد

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 رموز فتحات الإطارات المفتاحية المولّدة في التسلسل المُجمَّع، أو None عندما لم تُطلب أي فتحات.

جهّز كامنات الفيديو المعبّأة المشوّشة لمرور إزالة الضوضاء واحد في DFR.

يتم تخطيط التسلسل المُجمَّع على النحو التالي: [base | keyframes | slots | reference]:

  • تغطي الرموز الأساسية الشبكة الكامنة المستهدفة، وتُزرع من latents عند توفيرها.
  • تُحدّد الشروط الإطارية التي يكون فيها index == 0 الهدف النظيف في مواضع الإطار الأول؛ أما تلك التي يكون فيها index > 0 وكل عنصر من عناصر keyframe_latents فتُضاف كرموز إطارات رئيسية إضافية مع قناع تكييف لكل رمز يساوي قوته.
  • slot_frame_indices يضيف ما يعادل إطار كامن واحد من الرموز الرئيسية المولَّدة لكل موضع، مع قناع تكييف 0 (مُزيل الضوضاء بالكامل) ومدى زمني لـ RoPE يساوي إطار بكسل واحد بالضبط. هذه هي فتحات الإطارات الرئيسية التي تمنح DFR إطاراتها الإضافية؛ ويحدد slot_initial_latents محتواها.
  • reference_latents يضيف كامن نصف الدقة الخاص بالمرحلة الأولى كمرجع نظيف بالكامل لـ IC-LoRA، مع تحديث الإحداثيات المكانية بمعامل reference_downscale_factor بحيث تتطابق مع فضاء الإحداثيات المستهدف.

تحمل رموز الشرط المضافة محتواها في clean_latents وتحتوي على قيمة صفرية في latents، بينما تحمل خانات الإطارات الرئيسية بذرتها في latents وتحتوي على قيم صفرية في clean_latents — حيث تكون latents المُعادّة هي مزيج مُضجَم من الاثنين (انظر خطوة الإضجيج في نهاية هذه الطريقة).

preprocess_conditions

< >

( 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]]

المعاملات

  • conditions (LTX2VideoCondition أو List[LTX2VideoCondition]، اختياري، القيمة الافتراضية None) — قائمة من حالات الصورة/الفيديو.
  • height (int، اختياري، القيمة الافتراضية 512) — الارتفاع المطلوب بالبكسل.
  • width (int، اختياري، القيمة الافتراضية 768) — العرض المطلوب بالبكسل.
  • num_frames (int، اختياري، القيمة الافتراضية 121) — عدد الإطارات المطلوب في الفيديو المولّد.
  • device (torch.device، اختياري، القيمة الافتراضية None) — الجهاز الذي سيتم وضع تينسورات الصور/الفيديو المُعالَجة مسبقًا عليه.

يعيد

Tuple[List[torch.Tensor], List[float], List[int], List[int]]

يعيد رباعيًا من قوائم بطول len(conditions) على النحو التالي:

  1. القائمة الأولى هي قائمة من متجهات الفيديو المُعالَجة مسبقًا على شكل [batch_size=1, num_channels, num_frames, height, width].
  2. القائمة الثانية هي قائمة لقوى التكييف.
  3. القائمة الثالثة هي قائمة فهارس فضاء الكمون لكل شرط.
  4. القائمة الرابعة هي قائمة بعدد الإطارات (المقصوصة) في فضاء البكسلات لكل حالة. وهذا ضروري لدلالات إحداثيات الإطارات الرئيسية (فالإطارات الرئيسية ذات البكسل الواحد لها امتداد زمني مُقيَّد).

يعالج صور/فيديوهات الشرط مسبقاً إلى متجهات torch.

rebuild_epilogue_keyframes

< >

( keyframe_latents: Tensordecode_timestep: floatdecode_noise_scale: floatseed: intdevice: devicedtype: dtype ) → torch.Tensor

المعاملات

  • keyframe_latents (torch.Tensor) — إطارات أساسية خام بصيغة (batch_size, C, K, H, W)، كما أعادها مسار سابق.
  • seed (int) — البذرة الأساسية؛ تُفكّك المستوية i تحت seed + 4000 + i، لذا لا تعتمد بكسلات المستوية على عدد المستويات التي فُكّكت قبلها.

يعيد

torch.Tensor

خام (batch_size, C, K, 2H, 2W)، جاهزة للإدخال مباشرةً مرة أخرى كـ guidance_keyframe_latents.

أعد ترميز إطارات النقل الحاملة (carry keyframes) بدقة مضاعفة عبر قناة RGB.

هذه إطارات استقرت عليها جولات التكرار بالفعل، لذا يُقدَّم لها في الخاتمة بدلاً من طلب توليدها. فك الترميز إلى بكسلات، ثم التوسيع بمعامل x2 باستخدام Lanczos، ثم الترميز مرة أخرى يحافظ على الإطار مع وضعه على شبكة الإخراج، وهو ما يتيح للخاتمة تثبيته بشكل نظيف تماماً.

يتم فك ترميز كل مستوى كقطعة فيديو مستقلة من إطار واحد. نظرًا لأن VAE سببي، فإن فك الترميز المتراكم سيؤدي إلى تسرب المستويات المجاورة إلى بعضها البعض — فهي صور ثابتة مستقلة وليست تسلسلًا.

trim_conditioning_sequence

< >

( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int

المعاملات

  • start_frame (int) — رقم الإطار المستهدف للإطار الأول في التسلسل.
  • sequence_num_frames (int) — عدد الإطارات في التسلسل.
  • target_num_frames (int) — عدد الإطارات المستهدف في الفيديو المولّد.

يعيد

int

طول التسلسل المحدّث

اقتصاص تسلسل الشرط إلى عدد الإطارات المسموح به.

LTX2DFRTemporalRefinePipeline

فئة diffusers.LTX2DFRTemporalRefinePipeline

< >

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

المعاملات

  • scheduler (LTXEulerAncestralRFScheduler) — مجدول Euler السلفي في معلمات التدفق المُصحَّح. أنشئه باستخدام eta=0.5 ليتطابق مع الوصفة الزمنية لـ DFR.
  • vae (AutoencoderKLLTX2Video) — نموذج الترميز التبايني التلقائي (VAE) لتشفير وفك تشفير مقاطع الفيديو إلى تمثيلات كامنة ومنها.
  • audio_vae (AutoencoderKLLTX2Audio) — نموذج VAE للصوت لتشفير وفك تشفير مطيافات الصوت.
  • text_encoder (Gemma3ForConditionalGeneration أو Gemma4UnifiedForConditionalGeneration) — نموذج ترميز النص.
  • tokenizer (GemmaTokenizer أو GemmaTokenizerFast) — مُجزِّئ (Tokenizer) لمُشفِّر النص.
  • connectors (LTX2TextConnectors) — مكدس موصلات النص المستخدم لتكييف حالات المُشفِّر النصي المخفية لفروع الفيديو والصوت.
  • transformer (LTX2VideoTransformer3DModel) — بنية Transformer شرطية لإزالة الضوضاء من كامنات الفيديو المُرمّزة.
  • vocoder (LTX2Vocoder أو LTX2VocoderWithBWE) — مُصوِّغ صوتي لتحويل مطياف الميّل إلى موجات صوتية.
  • temporal_latent_upsampler (LTX2LatentUpsamplerModel) — مضاعِف كامن زمني بمعامل x2 يُطبَّق في بداية الجولة.

جولة واحدة من تحسين DFR الزمني: استيفاء اللوحة x2 في الزمن، وتبليطها عند فواصل الإطارات المفتاحية، وإزالة الضوضاء الأصلية لكل بلاطة، ثم الخياطة عبر إسقاط مقدمة البلاطة اللاحقة، ودمج حقيبة الإطار المفتاحي المحمول.

المجدول هو LTXEulerAncestralRFScheduler (الافتراضي eta=0.5). تبقى المرحلة 1 / المرحلة 2 / الخاتمة المكانية على FlowMatchEulerDiscreteScheduler عبر LTX2DFRPipeline. استدعِ هذا الخطّ مرة واحدة لكل جولة؛ يقوم المستدعي بالتكرار لـ 2x / 4x.

القيم الواردة من latents / keyframes_latents / audio_latents خام (غير مُعايرة)، بما يتوافق مع LTX2Pipeline. يجب أن تكون keyframe_positions هي الموضعات المُعادَة من المرور السابق — إذ لا يمكن إعادة اشتقاقها من num_frames الأصلية بعد تنفيذ جولة.

__call__

< >

( 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

المعاملات

  • prompt (str أو List[str]، اختياري) — الموجّه أو الموجّهات التي توجّه توليد الفيديو. إذا لم يُعرَّف، يجب تمرير prompt_embeds.
  • latents (torch.Tensor) — كائنات الفيديو الخام (Raw video latents) الخاصة بلوحة الإدخال، بأبعاد (batch_size, channels, frames, height, width).
  • keyframes_latents (torch.Tensor) — إطارات المفتاح الخام (batch_size, channels, K, height, width) من المرور السابق.
  • keyframe_positions (list[int]) — فهارس الإطارات البكسلية لـkeyframes_latents على لوحة الإدخال.
  • audio_latents (torch.Tensor) — صوت المرحلة الأولى المجمّد، بعد فكّ الحزم وإزالة التطبيع. يُسلَّم لكل بلاطة الجزء الذي يغطي نافذة تشغيله؛ والصوت المُعاد هو هذا الموجة الصوتية، وليس إعادة إزالة ضوضاء لكل بلاطة على حدة.
  • conditions (LTX2VideoCondition أو List[LTX2VideoCondition]، اختياري) — شروط على مستوى الإطار مُفهرسة على condition_num_frames (الطلب الأصلي). في كل جولة، يتم توسيع موضع بكسل الشرط بمعامل 2 ** round_index.
  • height (int، اختياري، القيمة الافتراضية 704) — ارتفاع البكسلات لهذا المرور (نفس الفيديو الوارد).
  • width (int، اختياري، القيمة الافتراضية 1216) — عرض البكسلات لهذا المرور.
  • num_frames (int، اختياري، القيمة الافتراضية 121) — عدد إطارات البكسلات في لوحة الإدخال (قبل القص).
  • frame_rate (float، اختياري، القيمة الافتراضية 24.0) — معدل الإطارات في الثانية (fps) أثناء تشغيل المدخلات. يقوم هذا الإعداد بمضاعفة القيمة.
  • source_seconds (float, اختياري) — مدة مرحلة 1 الصوتية المجمّدة. القيمة الافتراضية هي num_frames / frame_rate، وهي صحيحة للجولة الأولى؛ أما الجولات اللاحقة فيجب أن تمرر مدة مرحلة 1 الأصلية حتى لا تنحرف البلاطات.
  • condition_num_frames (int, اختياري) — عدد الإطارات الأصلي num_frames المستخدم لتشفير conditions. القيمة الافتراضية هي num_frames. بعد إضافة الحشو أو جولة سابقة، مرّر الطلب الأصلي حتى لا يلتف index=-1 إلى ذيل الحشو.
  • round_index (int، اختياري، القيمة الافتراضية 1) — رقم الجولة يبدأ من 1. تُزرع الضوضاء الأصلية (ancestral noise) على شكل seed + 1000 * round_index + tile، وتُضبط الشروط (conditions) بمعامل 2 ** round_index.
  • sigmas (list[float]، اختياري) — الجدول المُصغَّر لبلاطات هذه الجولة، دون القيمة النهائية 0.0.
  • noise_scale (float، اختياري) — مستوى الضوضاء الذي تبدأ منه الرموز غير المشروطة. القيمة الافتراضية هي sigmas[0].
  • generator (torch.Generator أو list[torch.Generator]، اختياري) — مولّد عشوائي أو مولّدات عشوائية لضمان قابلية التكرار. تستخدم السحوبات الأصلية بذرة مستقلة لكل بلاطة مشتقة من initial_seed() لهذا المولّد.
  • prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية مُولّدة مسبقًا.
  • prompt_attention_mask (torch.Tensor، اختياري) — قناع الانتباه المُولَّد مسبقًا لتضمينات النص.
  • decode_timestep (float، القيمة الافتراضية 0.0) — خطوة الزمن التي يتم عندها فك ترميز الفيديو المولّد.
  • decode_noise_scale (float، القيمة الافتراضية None) — مقياس الضوضاء عند فك الترميز.
  • use_cross_timestep (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم استخدام sigma بين الوسائط (cross-modality) لتعديل الانتباه المتقاطع (cross attention). True لنسخ LTX-2.3 وما بعدها.
  • output_type (str، اختياري، الافتراضي "pil") — صيغة الإخراج. اختر "pil" أو "np" أو "pt" أو "latent". الإخراج الكامن هو اللوحة غير المقصوصة.
  • return_dict (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب إرجاع LTX2DFRPipelineOutput أو مجرد مجموعة (frames, audio, keyframes, keyframe_positions).
  • attention_kwargs (dict، اختياري) — معاملات إضافية تُمرَّر إلى معالج الانتباه.
  • callback_on_step_end (Callable، اختياري) — دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء، عبر كل بلاطة.
  • callback_on_step_end_tensor_inputs (List، اختياري، القيمة الافتراضية ["latents"]) — مدخلات المصفوفات (Tensors) لدالة الاستدعاء (callback).
  • max_sequence_length (int، اختياري، القيمة الافتراضية 1024) — أقصى طول للسلسلة الخاصة بالموجّه النصي.

يعيد

LTX2DFRPipelineOutput أو tuple

إذا كان return_dict هو True، يُعاد LTX2DFRPipelineOutput، وإلا يُعاد tuple من (video, audio, keyframes, keyframe_positions).

نفّذ جولة واحدة من التحسين الزمني.

أمثلة:

>>> 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",
... )

إزالة الضوضاء

< >

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

المعاملات

  • sigmas (list[float]) — جدول الضوضاء لهذا المرور، دون القيمة النهائية 0.0.
  • freeze_audio (bool، اختياري، القيمة الافتراضية False) — يُبقي audio_latents نظيفًا (خطوة زمنية/سيجما 0، بدون خطوة أويلر للصوت) مع الاستمرار في تشغيل الانتباه المتقاطع من الصوت إلى الفيديو. يُتجاهل عندما تكون audio_latents هي None.
  • video_tile_plan (list، اختياري) — خطة الرموز لكل بلاطة من video_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. عند تقديمه، يعمل المحوّل مرة واحدة لكل بلاطة في كل خطوة، ثم يمزج التنبؤات، بحيث لا يزال المُعيّن يتقدم على لوحة كاملة واحدة، وتتفق البلاطات على مناطق تداخلها في كل خطوة.
  • generator (torch.Generator، اختياري) — يُمرَّر إلى LTXEulerAncestralRFScheduler.step(). تمرّ البلاطات الزمنية ببذرة لكل بلاطة حتى لا تتشارك السحوبات الأصلية تدفّقًا واحدًا أو تستهلك الحالة التي تقرأها الضوضاء الأولية للبلاطة التالية. لا يقرأ Euler المُقطّر هذا المعامل.
  • step_offset (int) — مؤشر الخطوة الأولى لهذا المرور ضمن الجدول الزمني الكامل للخط، ويُستخدم في callback_on_step_end وشريط التقدم المشترك.

نفّذ مسار إزالة ضوضاء واحدًا لـ DFR على sigmas وأعد (latents, audio_latents)، وكلاهما ما يزال مضغوطًا.

يُستخدم الجدول المُقطَّر دون إرشاد حر من المُصنِّف، لذا فإن كل خطوة تتطلب استدعاءً واحدًا فقط لتحويلة. تُنفَّذ كلتا البعثات في كل مرور، لأن فرع الفيديو يحتاج إلى الانتباه بين الوسائط حتى في الحالات التي يُتخلَّى فيها عن الصوت الذي ينتجه. يحافظ freeze_audio=True على مسار الصوت عند قيمة سيجما صفر (بدون خطوة أويلر) بحيث لا يزال بإمكان الفيديو الانتباه إليه عبر الوسائط — وتستخدم بلاطات التزويد الزمني والفصل الختامي هذا لمتابعة الكلام من المرحلة الأولى دون أن تعيد كل بلاطة إزالة الضوضاء عن تجسيد صوتي مختلف.

بعد مزج شرط x0، تكون السرعة (latents - denoised) / sigma لذا يستعيد خطوة RF x0 = x - σ v القيمة denoised الممزوجة. تحافظ المرحلتان 1 / 2 / الخاتمة على FlowMatchEulerDiscreteScheduler وتتخذ خطوة أويلر تلك كما هي. أما تحسين الزمن فيستبدلها بـ LTXEulerAncestralRFScheduler (eta=0.5)؛ إذ تعيد تلك الخطوة إضافة الضوضاء إلى كل رمز، لذا يُعاد تطبيق مزج الشرط بعدها وإلا تآكلت نقاط التثبيت عند الفواصل بقوة 0.95.

encode_conditions

< >

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

معالجة الشروط الإطارية مسبقاً وتشفيرها باستخدام VAE، مع تحديد موضعها حسب الإطار البكسلي.

يعيد (pixel_frame_index, latent, strength, num_pixel_frames) لكل شرط، جاهزًا لـ condition_latents الخاص بـ prepare_latents(). يُحافظ على فصل الترميز عن التوزيع لأن جولات التحسين الزمني تضاعف موضع الشرط بمعامل 2 ** round وتعيد ضبطه لكل بلاطة، ولا ينبغي إعادة ترميز نفس الإطار الثابت مرة واحدة لكل بلاطة لتحقيق ذلك.

المؤشر المُعاد يقع على شبكة بكسلات num_frames الخاصة به؛ ونقله إلى لوحة محسّنة هو من مسؤولية المُستدعي.

encode_prompt

< >

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

المعاملات

  • prompt (str أو list[str]، اختياري) — الموجّه الذي سيتم ترميزه
  • num_videos_per_prompt (int، اختياري، القيمة الافتراضية 1) — عدد الفيديوهات التي يجب توليدها لكل موجه.
  • prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخال prompt.
  • prompt_attention_mask (torch.Tensor، اختياري) — قناع الانتباه المُولَّد مسبقًا لـprompt_embeds.
  • device — (torch.device، اختياري): جهاز torch
  • dtype — (torch.dtype، اختياري): نوع بيانات torch

يقوم بتشفير الموجه إلى حالات مخفية لمشفّر النص.

تُنفّذ DFR جدول سيجما المُقطّر، والذي تم تدريبه ليُستخدم دون إرشاد حرّ من المُصنّف، لذا لا يوجد فرع سلبي هنا.

prepare_latents

< >

( 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]

المعاملات

  • conditions (list[LTX2VideoCondition]، اختياري) — شروط الصور/الفيديو على مستوى الإطار، موضوعة حسب فهرس الكمون.
  • condition_latents (list[tuple[int, torch.Tensor, float, int]], اختياري) — بديل مُرمَّز مسبقًا لـ conditions، على شكل (pixel_frame_index, latent, strength, num_pixel_frames). يُستخدم فهرس البكسل بدلاً من فهرس الكامنة، لأن جولة التزويد الزمني تضاعف موضع الشرط بمعامل 2 ** round، ولا يهبط الناتج عادةً على حدّ الكامنة — فإنما يمكن لرمز إطار مفتاحي مُضاف أن يستقر هناك، ويُوضع وفق البكسل. لا يزال pixel_frame_index == 0 يعني «استبدال الإطار الأول».
  • keyframe_latents (list[tuple[int, torch.Tensor, float]], اختياري) — إرشادات الإطارات الرئيسية المُرمّزة مسبقًا على شكل (pixel_frame_index, latent, strength)، حيث يكون شكل latent (batch_size, num_channels_latents, 1, latent_height, latent_width). تُستخدم في جولات التزويد الزمني لتثبيت الإطارات الرئيسية عند نقاط الالتحام المنقولة من الجولة السابقة.
  • slot_frame_indices (list[int]، اختياري) — مواضع الإطارات البكسلية للفواصل الرئيسية المولّدة.
  • slot_initial_latents (torch.Tensor، اختياري) — (batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width) المحتوى الذي يُكتب في رموز الفتحات قبل إضافة الضوضاء.
  • reference_latents (torch.Tensor، اختياري) — (batch_size, num_channels_latents, F, H, W) متغير كامن مرجعي لـ IC-LoRA.
  • reference_downscale_factor (int، القيمة الافتراضية 1) — النسبة بين الدقة المستهدفة ودقة المرجع.
  • latents (torch.Tensor، اختياري) — (batch_size, num_channels_latents, F, H, W) المحتوى الأولي للرموز الأساسية. كائنات latents في خط الأنابيب العام تكون خامّة (غير مُعايرة)؛ مرّر latents_normalized=False عند تلك النقطة. حلقات البلاطات التي تعمل بالفعل في فضاء مُعاير بواسطة VAE تُبقي على القيمة الافتراضية.
  • latents_normalized (bool، القيمة الافتراضية True) — ما إذا كانت latents وslot_initial_latents وreference_latents وkeyframe_latents مُطبَّعة مسبقًا بواسطة VAE. تمر حلقات البلاطات الداخلية القيمة True؛ بينما تمر كل خط أنابيب عبر __call__ القيمة False.
  • noise_scale (float، القيمة الافتراضية 1.0) — مستوى الضوضاء الذي تُهيَّأ به الرموز غير المشروطة، أي أول قيمة سيغما في الجدول الزمني.

يعيد

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 رموز فتحات الإطارات المفتاحية المولّدة في التسلسل المُجمَّع، أو None عندما لم تُطلب أي فتحات.

جهّز كامنات الفيديو المعبّأة المشوّشة لمرور إزالة الضوضاء واحد في DFR.

يتم تخطيط التسلسل المُجمَّع على النحو التالي: [base | keyframes | slots | reference]:

  • تغطي الرموز الأساسية الشبكة الكامنة المستهدفة، وتُزرع من latents عند توفيرها.
  • تُحدّد الشروط الإطارية التي يكون فيها index == 0 الهدف النظيف في مواضع الإطار الأول؛ أما تلك التي يكون فيها index > 0 وكل عنصر من عناصر keyframe_latents فتُضاف كرموز إطارات رئيسية إضافية مع قناع تكييف لكل رمز يساوي قوته.
  • slot_frame_indices يضيف ما يعادل إطار كامن واحد من الرموز الرئيسية المولَّدة لكل موضع، مع قناع تكييف 0 (مُزيل الضوضاء بالكامل) ومدى زمني لـ RoPE يساوي إطار بكسل واحد بالضبط. هذه هي فتحات الإطارات الرئيسية التي تمنح DFR إطاراتها الإضافية؛ ويحدد slot_initial_latents محتواها.
  • reference_latents يضيف كامن نصف الدقة الخاص بالمرحلة الأولى كمرجع نظيف بالكامل لـ IC-LoRA، مع تحديث الإحداثيات المكانية بمعامل reference_downscale_factor بحيث تتطابق مع فضاء الإحداثيات المستهدف.

تحمل رموز الشرط المضافة محتواها في clean_latents وتحتوي على قيمة صفرية في latents، بينما تحمل خانات الإطارات الرئيسية بذرتها في latents وتحتوي على قيم صفرية في clean_latents — حيث تكون latents المُعادّة هي مزيج مُضجَم من الاثنين (انظر خطوة الإضجيج في نهاية هذه الطريقة).

preprocess_conditions

< >

( 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]]

المعاملات

  • conditions (LTX2VideoCondition أو List[LTX2VideoCondition]، اختياري، القيمة الافتراضية None) — قائمة من حالات الصورة/الفيديو.
  • height (int، اختياري، القيمة الافتراضية 512) — الارتفاع المطلوب بالبكسل.
  • width (int، اختياري، القيمة الافتراضية 768) — العرض المطلوب بالبكسل.
  • num_frames (int، اختياري، القيمة الافتراضية 121) — عدد الإطارات المطلوب في الفيديو المولّد.
  • device (torch.device، اختياري، القيمة الافتراضية None) — الجهاز الذي سيتم وضع تينسورات الصور/الفيديو المُعالَجة مسبقًا عليه.

يعيد

Tuple[List[torch.Tensor], List[float], List[int], List[int]]

يعيد رباعيًا من قوائم بطول len(conditions) على النحو التالي:

  1. القائمة الأولى هي قائمة من متجهات الفيديو المُعالَجة مسبقًا على شكل [batch_size=1, num_channels, num_frames, height, width].
  2. القائمة الثانية هي قائمة لقوى التكييف.
  3. القائمة الثالثة هي قائمة فهارس فضاء الكمون لكل شرط.
  4. القائمة الرابعة هي قائمة بعدد الإطارات (المقصوصة) في فضاء البكسلات لكل حالة. وهذا ضروري لدلالات إحداثيات الإطارات الرئيسية (فالإطارات الرئيسية ذات البكسل الواحد لها امتداد زمني مُقيَّد).

يعالج صور/فيديوهات الشرط مسبقاً إلى متجهات torch.

trim_conditioning_sequence

< >

( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int

المعاملات

  • start_frame (int) — رقم الإطار المستهدف للإطار الأول في التسلسل.
  • sequence_num_frames (int) — عدد الإطارات في التسلسل.
  • target_num_frames (int) — عدد الإطارات المستهدف في الفيديو المولّد.

يعيد

int

طول التسلسل المحدّث

اقتصاص تسلسل الشرط إلى عدد الإطارات المسموح به.

upsample_latents

< >

( latents: Tensorupsampler: LTX2LatentUpsamplerModel )

شغّل upsampler على الكمونيات المعيارية، مع المرور ذهاباً وإياباً عبر فضاء الكمون الخام الخاص بـ VAE كما يتوقع ذلك.

LTX2DFRPipelineOutput

فئة diffusers.LTX2DFRPipelineOutput

< >

( frames: Tensoraudio: Tensorkeyframes: typing.Optional[torch.Tensor] = Nonekeyframe_positions: list[int] | None = None )

المعاملات

  • frames (torch.Tensor أو np.ndarray أو list[list[PIL.Image.Image]]) — فيديو بعد إزالة الضوضاء. المخرجات الكامنة هي اللوحة غير المقصوصة، وشكلها (batch_size, num_channels, latent_frames, latent_height, latent_width).
  • audio (torch.Tensor، np.ndarray) — كائنات صوتية مرافقة أو موجة صوتية.
  • keyframes (torch.Tensor، اختياري) — كواتم الإطارات المفتاحية المولّدة أو المنقولة، بأبعاد (batch_size, num_channels, num_keyframes, latent_height, latent_width). تكون None عندما output_type != "latent"، أو عندما لا ينتج المسار فتحات (مثلًا، خاتمة مُقسّمة).
  • keyframe_positions (list[int], اختياري) — مؤشر إطار البكسل لكل إطار رئيسي على لوحة هذه المرحلة؛ None في كل مرة يكون فيها keyframes هو None. بعد جولة زمنية، لا يمكن إعادة اشتقاق هذه القيم من num_frames الأصلية، ويجب تمريرها إلى المرحلة التالية.

فئة الإخراج لخطوط أنابيب DFR.

LTX2LatentUpsamplePipeline

فئة diffusers.LTX2LatentUpsamplePipeline

< >

( vae: AutoencoderKLLTX2Videolatent_upsampler: LTX2LatentUpsamplerModel )

__call__

< >

( 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

المعاملات

  • video (list[PipelineImageInput], اختياري) — الفيديو الذي سيتم رفع دقته (مثل مخرج المرحلة الأولى من LTX 2.0). إذا لم يُقدَّم، فيجب تقديم latents.
  • height (int، اختياري، القيمة الافتراضية 512) — ارتفاع الفيديو المُدخل بالبكسل (وليس الفيديو المُولَّد، الذي سيكون بدقة أعلى).
  • width (int، اختياري، القيمة الافتراضية 768) — العرض بالبكسلات للفيديو المُدخل (وليس الفيديو المُولَّد، الذي سيكون بدقة أعلى).
  • num_frames (int، اختياري، القيمة الافتراضية 121) — عدد الإطارات في الفيديو المُدخل.
  • spatial_patch_size (int, اختياري، القيمة الافتراضية 1) — حجم البقعة المكانية (spatial patch) للكائنات الكامنة (latents) في الفيديو. يُستخدم عند تقديم latents إذا كان فك التغليف (unpacking) ضرورياً.
  • temporal_patch_size (int, اختياري، القيمة الافتراضية 1) — حجم البقعة الزمنية (temporal patch) لمتغيرات الفيديو (video latents). يُستخدم عند تقديم latents إذا كان فك التغليف (unpacking) ضرورياً.
  • latents (torch.Tensor، اختياري) — كائنات فيديو مُولّدة مسبقًا. يمكن تقديم هذا بدلاً من الحجة video. يمكن أن يكون إما تسلسلًا من البقع (patches) بشكل (batch_size, seq_len, hidden_dim) أو كائن فيديو (video latent) بشكل (batch_size, latent_channels, latent_frames, latent_height, latent_width).
  • latents_normalized (bool، اختياري، القيمة الافتراضية False) — إذا تم توفير latents، فإن هذا يحدد ما إذا كانت latents مُطبَّعة باستخدام متوسط وانحراف VAE الكامن. إذا كانت True، فسيتم إلغاء تطبيع latents قبل تقديمها إلى مُوسِّع الكامن.
  • decode_timestep (float، القيمة الافتراضية 0.0) — خطوة الزمن التي يتم عندها فك ترميز الفيديو المولّد.
  • decode_noise_scale (float، القيمة الافتراضية None) — عامل الاستيفاء بين الضوضاء العشوائية واللاتنتات المُزالة الضوضاء عند خطوة فك الترميز.
  • adain_factor (float، اختياري، القيمة الافتراضية 0.0) — معامل المزج في تطبيع الأمثلة التكيفية (AdaIN) بين الكمون المُوسَّع والكمون الأصلي. يجب أن يكون ضمن النطاق [-10.0, 10.0]؛ حيث يعني تقديم القيمة 0.0 (الافتراضية) عدم إجراء عملية AdaIN.
  • tone_map_compression_ratio (float, اختياري، القيمة الافتراضية 0.0) — قوة الضغط الخاصة بتعيين النغمات، والتي تقلل من المدى الديناميكي للقيم الكامنة. يُعد هذا مفيدًا لتنظيم القيم الكامنة عالية التباين أو لتكييف المخرجات أثناء التوليد. يجب أن تكون القيمة ضمن المجال [0, 1]، حيث تعني 0.0 (القيمة الافتراضية) عدم تطبيق تعيين النغمات، بينما تقابل 1.0 تأثير الضغط الكامل.
  • generator (torch.Generator أو list[torch.Generator]، اختياري) — مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا.
  • output_type (str، اختياري، القيمة الافتراضية "pil") — صيغة مخرجات توليد الصورة. اختر بين PIL: PIL.Image.Image أو np.array.
  • return_dict (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب إرجاع ~pipelines.ltx.LTXPipelineOutput بدلاً من tuple عادي.

يعيد

~pipelines.ltx.LTXPipelineOutput أو tuple

إذا كان return_dict هو True، يُعاد ~pipelines.ltx.LTXPipelineOutput، وإلا يُعاد tuple يكون عنصره الأول هو الفيديو المُوسَّع.

الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.

أمثلة:

>>> 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

< >

( latents: Tensorreference_latents: Tensorfactor: float = 1.0 ) → torch.Tensor

المعاملات

  • latents (torch.Tensor) — القيم الكامنة المدخلة التي يجب تطبيعها
  • reference_latents (torch.Tensor) — القيم الكامنة المرجعية التي توفر إحصاءات الأسلوب.
  • factor (float) — معامل الدمج بين الحالة الكامنة الأصلية والحالة الكامنة المحوّلة. النطاق: من -10.0 إلى 10.0، الافتراضي: 1.0

يعيد

torch.Tensor

الموتر الكامن المُحوَّل

يطبّق تطبيع الأمثلة التكيفية (AdaIN) على متجه كامن (latent tensor) بناءً على الإحصاءات المستخرجة من متجه كامن مرجعي.

tone_map_latents

< >

( latents: Tensorcompression: float )

المعاملات

  • latents — torch.Tensor مصفوفة الكامنة (Latent) المدخلة ذات الشكل التعسفي. يُتوقع أن تكون قيمها تقريبًا ضمن النطاق [-1, 1] أو [0, 1].
  • compression — float قوة الضغط في المدى [0, 1].
    • 0.0: لا يوجد تحويل نبرة (تحويل هوية)
    • 1.0: تأثير الضغط الكامل

يطبّق دالة خرائط نغمات غير خطية على القيم الكامنة لتقليل نطاقها الديناميكي بطريقة سلسة إدراكياً باستخدام ضغط يعتمد على دالة سيجمويد.

يُعدّ هذا مفيدًا لتنظيم الكامنات عالية التباين أو لتوجيه المخرجات أثناء التوليد، لا سيما عند التحكم في السلوك الديناميكي باستخدام معامل compression.

LTX2VideoDiffusionDecodePipeline

فئة diffusers.LTX2VideoDiffusionDecodePipeline

< >

( diffusion_decoder: LTX2VideoDiffusionDecoderModelschedulervae: AutoencoderKLLTX2Video = None )

المعاملات

  • diffusion_decoder (LTX2VideoDiffusionDecoderModel) — فكّ الترميز التوزيعي للفيديو.
  • scheduler (FlowMatchEulerDiscreteScheduler) — المجدول الذي يقود خطوات إزالة الضوضاء في المُفكِّك.
  • vae (AutoencoderKLLTX2Video، اختياري) — يُستشار فقط من أجل الإحصاءات الكامنة المستخدمة في إزالة التطبيع. عند إهماله، يعود خط المعالجة إلى القيم الافتراضية لـ LTX-2، لذا لا يحتاج سير عمل فك الترميز فقط إلى تحميل مُشفِّر-مفكِّك ثانٍ.

فكّ تشفير كامنات فيديو LTX-2 باستخدام مُفكّك الانتشار المُقدَّم في LTX-2.5.

على عكس مُفكِّك الالتفاف، فإن هذا المُفكِّك هو في حد ذاته نموذج انتشار صغير: فهو يُزيل الضوضاء من البكسلات مشروطًا بحجم سياق مبني من الكمونيات، لذا فهو يحتاج إلى مُجدوِل ومولِّد. اقرنه مع أي مسار تنفيذ لـ LTX-2 يعمل بـ output_type="latent"، مع تمرير denormalize=False لأن ذلك المسار طبّق بالفعل إحصاءات الكمونيات.

__call__

< >

( latents: Tensorgenerator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneoutput_type: str = 'pil'return_dict: bool = Truedenormalize: bool = True ) → LTX2VideoDecodeOutput or tuple

المعاملات

  • latents (torch.Tensor) — القيم الكامنة ذات الشكل (B, C, F, H, W). لاحظ أن تشغيل خط أنابيب LTX-2 مع output_type="latent" يعيد قيمًا كامنة تمت تطبيعها مسبقًا، لذا مرّر denormalize=False لتلك القيم.
  • generator (torch.Generator، اختياري) — ينشئ المُفكِّك الضوضاء التي سيقوم بإزالتها، لذا مرِّر مُولِّدًا لجعل عملية فك الترميز قابلة للتكرار.
  • output_type (str، اختياري، الافتراضي "pil") — صيغة مخرجات الفيديو المُفكَّك. اختر بين "pil" و"np" و"pt" و"latent".
  • return_dict (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب إرجاع LTX2VideoDecodeOutput بدلاً من tuple عادي.
  • denormalize (bool، اختياري، الافتراضي True) — ما إذا كان سيتم تطبيق إحصاءات الكمون قبل فك الترميز. اضبطه على False إذا كانت الكمونات مفككة الترميز بالفعل.

يعيد

LTX2VideoDecodeOutput أو tuple

LTX2DurationHead

فئة diffusers.pipelines.ltx2.LTX2DurationHead

< >

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

المعاملات

  • video_cross_attention_dim (int، القيمة الافتراضية 4096) — عرض مخرج موصل الفيديو.
  • audio_cross_attention_dim (int، القيمة الافتراضية 2048) — عرض مخرج وصلة الصوت.
  • pooler_hidden_dim (int، القيمة الافتراضية 256) — البُعد المخفي المشترك الذي تُسقط إليه كلا الحالتين.
  • num_queries (int، القيمة الافتراضية 1) — عدد استعلامات التجميع القابلة للتعلم.
  • num_pooler_heads (int، القيمة الافتراضية 4) — رؤوس الانتباه التي يستخدمها المُجمِّع.
  • mlp_hidden_dim (int، القيمة الافتراضية 256) — العرض الخفي لشبكة MLP المخرجات. تم تسميتها بلاحقة _dim لتجنب التعارض مع وحدة الفرع mlp_hidden، والتي كان ConfigMixin.__getattr__ ستخفيها بقيمة الإعداد هذه.

يتنبأ بالمدة الطبيعية للقطّة المستنتجة من الوصف النصي، انطلاقًا من مخرجات مُوصِل النص في LTX-2.

الرأس مستقل عن النمط: مرّر أيًا من مخرجات الوصلة الخاصة بالفيديو والصوت أو كلاهما معًا. تُخضع الإسقاطات المدخلة المحددة لكل نمط كل تدفق إلى بُعد مجمّع مشترك، وتُوسم التدفقات بتضمينات نمطية قابلة للتعلم بحيث يستطيع المجمع التمييز بينها، ويحوّل شبكة عصبية صغيرة (MLP) المتجه المجمّع إلى مدة على مقياس لوغاريتمي. يُدرَّب هدف الانحدار بالثواني اللوغاريتمية، لذا يُجري forward عملية الأس (exponentiation) ليحصل المستدعون دائمًا على القيمة بالثواني.

يُشحن من نقاط التفتيش LTX-2.5 فصاعدًا.

forward

< >

( video_tokens: typing.Optional[torch.Tensor] = Noneaudio_tokens: typing.Optional[torch.Tensor] = None ) → torch.Tensor of shape (batch_size,)

المعاملات

  • video_tokens (torch.Tensor من الشكل (batch_size, seq_len, video_cross_attention_dim)، اختياري) — مخرج مُوصِل الفيديو.
  • audio_tokens (torch.Tensor من الشكل (batch_size, seq_len, audio_cross_attention_dim)، اختياري) — مخرج مُوصِل الصوت.

يعيد

torch.Tensor من الشكل (batch_size,)

المدة المتوقعة بالثواني.

predict_num_frames

< >

( 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

المعاملات

  • video_tokens (torch.Tensor، اختياري) — مخرج مُوصِل الفيديو لموجّه واحد.
  • audio_tokens (torch.Tensor، اختياري) — مخرج مُوصِل الصوت لطلب واحد.
  • frame_rate (float) — عدد الإطارات في الثانية المستخدمة لتحويل المدة المتوقعة إلى عدد إطارات.
  • temporal_compression_ratio (int) — نسبة الضغط الزمني الخاصة بـ VAE، والتي تحدد شبكة الإطارات.
  • min_seconds (float، القيمة الافتراضية 1.0) — الحد الأدنى للتنبؤ.
  • max_seconds (float، القيمة الافتراضية 20.0) — الحد الأعلى للتنبؤ.

يعيد

int

عدد إطارات يقع على الشبكة الزمنية الخاصة بـ VAE.

يتنبأ بعدد الإطارات من رموز الوصلة، مع تقييده ضمن [min_seconds, max_seconds] ومحاذاته إلى الشبكة الزمنية السببية الخاصة بـ VAE (k * temporal_compression_ratio + 1).

يُطبَّق التقييد قبل المحاذاة: العدد المُقيَّد للإطارات لا يكون بالضرورة محاذاةً مع الشبكة، لذا فإن المحاذاة أولاً ستعطي نتيجة مختلفة. وبما أن المحاذاة تُقرّب إلى الأسفل، فقد تهبط دون الحد الأدنى؛ وعندما يحدث ذلك، تُحاذاة النتيجة إلى أعلى نحو نقطة الشبكة التالية، بحيث يبقى عدد الإطارات ضمن الحدود.

يمكن أن تتحول الحدود الضيقة إلى نافذة إطار لا تحتوي على أي نقطة شبكة على الإطلاق — عند 24 إطارًا في الثانية، يُقرَّب [1.0s, 1.02s] إلى [24, 24]، و24 ليست 8k + 1. تُستخدم أقرب نقطة شبكة ويُسجَّل تحذير، لأن تجاوزًا بأقل من خطوة شبكة واحدة أفضل من رفض التوليد. لذلك يكون العدد المُعاد دائمًا على الشبكة، لكنه قد يقع خارج الحدود المطلوبة بقليل في هذه الحالة.

LTX2PipelineOutput

فئة diffusers.pipelines.ltx2.LTX2PipelineOutput

< >

( frames: Tensoraudio: Tensor )

المعاملات

  • frames (torch.Tensor أو np.ndarray أو قائمة[قائمة[PIL.Image.Image]]) — قائمة من مخرجات الفيديو - يمكن أن تكون قائمة متداخلة بطول batch_size, حيث تحتوي كل قائمة فرعية على سلاسل صور PIL منزوعة الضوضاء بطول num_frames. كما يمكن أن تكون مصفوفة NumPy أو متجه Torch من الشكل (batch_size, num_frames, channels, height, width).
  • audio (torch.Tensor، np.ndarray) — TODO

فئة الإخراج لخطوط أنابيب LTX.

LTX2ModularPipeline

فئة diffusers.LTX2ModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

ModularPipeline لـ LTX-2 (توليد مشترك للفيديو والصوت).

LTX2AutoBlocks

فئة diffusers.LTX2AutoBlocks

< >

( )

كتل تلقائية لنموذج LTX-2 تدعم التوليد من النص إلى الفيديو، ومن الصورة إلى الفيديو، ومن الشرط إلى الفيديو، والتوليد في السياق (IC-LoRA) (فيديو وصوت مشترك).

سير العمل المدعومة:

  • text2video: يتطلب prompt
  • image2video: يتطلب image، prompt
  • condition: يتطلب conditions، prompt
  • in_context: يتطلب reference_conditions، num_frames، prompt

المكوّنات: 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)

المُدخلات: prompt (str, اختياري): الموجّه أو الموجّهات لتوجيه توليد الصورة. conditions (list, اختياري): LTX2VideoCondition (أو قائمة منها) لوضع شروط الصورة/الفيديو عند فهارس الإطارات الكامنة للفيديو المولّد. enable_prompt_enhancement (bool, اختياري, الافتراضي False): ما إذا كان سيتم تشغيل معزّز الموجّه. خيار اختياري، بما يتوافق مع خطوط أنابيب Lightricks المرجعية. system_prompt (str, اختياري): موجّه النظام للتحسين. الافتراضي هو LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT عندما يكون إطار شرط PIL.Image.Image متاحًا، وإلا LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT. prompt_max_new_tokens (int, اختياري): الحد الأقصى لعدد الرموز الجديدة التي سيتم توليدها أثناء تحسين الموجّه. الافتراضي هو 600، وهو ميزانية معزّز LTX-2.5 Gemma-4. prompt_enhancement_kwargs (dict, اختياري): حجج الكلمات المفتاحية لاستدعاء .generate الخاص بالمعزّز. الافتراضي هو فك الترميز الجشع. prompt_enhancement_seed (int, اختياري, الافتراضي 10): البذرة العشوائية لتحسين الموجّه (غير فعّالة تحت فك الترميز الجشع في LTX-2.5). generator (Generator, اختياري): مولّد Torch للتوليد الحتمي. image (Image | list, اختياري): صورة أو صور مرجعية لإزالة الضوضاء. يمكن أن تكون صورة واحدة أو قائمة من الصور. negative_prompt (str, اختياري): الموجّه أو الموجّهات التي لا يجب أن توجّه توليد الصورة. max_sequence_length (int, اختياري, الافتراضي 1024): الطول الأقصى للتسلسل لتشفير الموجّه. min_seconds (float, اختياري, الافتراضي 1.0): الحد الأدنى للمدة المتوقعة تلقائيًا. max_seconds (float, اختياري, الافتراضي 20.0): الحد الأقصى للمدة المتوقعة تلقائيًا. يجب أن يكون أكبر بصرامة من min_seconds. frame_rate (float, اختياري, الافتراضي 24.0): عدد الإطارات في الثانية للفيديو المولّد. height (int, اختياري, الافتراضي 512): الارتفاع بالبكسل للصورة المولّدة. width (int, اختياري, الافتراضي 704): العرض بالبكسل للصورة المولّدة. image_crf (int, اختياري): قيمة H.264 CRF المستخدمة لإعادة ضغط صورة الشرط image قبل ترميز VAE، بما يتوافق مع الضغط الذي تم تدريب النموذج ضده. None (الافتراضي) يُحدَّد من توليد مُشفّر النص (33 حتى LTX-2.3، و18 لـ LTX-2.5). مرّر 0 لتخطي إعادة الضغط. يتطلب PIL.Image.Image عند تشغيل إعادة الضغط. num_frames (int, اختياري): عدد الإطارات في الفيديو المولّد. اتركه فارغًا للتوقع التلقائي عبر duration_head (انظر LTX2AutoDurationStep). reference_conditions (list, اختياري): LTX2ReferenceCondition (أو قائمة منها) يتم ترميز فيديوهاتها إلى رموز كامنة إضافية يتفاعل معها مكيّف IC-LoRA. reference_downscale_factor (int, اختياري, الافتراضي 1): النسبة بين دقة الهدف ودقة المرجع؛ 2 تعني أن المرجع يُعالج مسبقًا عند نصف دقة الهدف. تُقاس الإحداثيات المكانية بهذا العامل بحيث تهبط رموز المرجع في فضاء إحداثيات الهدف. يجب أن يتطابق مع العامل الذي تم تدريب IC-LoRA به. conditioning_attention_strength (float, اختياري, الافتراضي 1.0): مقياس في [0, 1] يتحكم في مدى تفاعل الرموز الضوضائية ورموز المرجع مع بعضها البعض. 1.0 (الافتراضي) يترك الانتباه غير مقنّع. conditioning_attention_mask (Tensor, اختياري): قناع اختياري في فضاء البكسل من الشكل (1, 1, F, H, W) بقيم في [0, 1] يعطي قوة انتباه متغيرة مكانيًا. يُصغَّر إلى الشبكة الكامنة للمرجع ويُضرب في conditioning_attention_strength. motion_speed (float, اختياري, الافتراضي 1.0): سرعة الحركة مقارنة بالوقت الحقيقي. تُشترط التضمينات الموضعية على frame_rate / motion_speed، لذا فإن القيم أقل من 1 تُبطئ الحركة، مثل 0.2 لحركة بطيئة 5x في LoRA الخاص بـ Slow-Motion-Control. يبقى frame_rate معدل التشغيل. num_videos_per_prompt (int, اختياري, الافتراضي 1): عدد الصور التي سيتم توليدها لكل موجّه. condition_latents (list, اختياري): قيم VAE الكامنة المعيارية لكل شرط من الشكل [1, C, F, H, W]. condition_strengths (list, اختياري): قوى الشرط لكل شرط. condition_indices (list, اختياري): فهرس الإطار الكامن لكل شرط حيث يُطبَّق الشرط. condition_pixel_frames (list, اختياري): عدد إطارات البكسل المقصوصة لكل شرط، يُستخدم لتقييد إحداثيات إطار المفتاح الأحادي. reference_latents (Tensor, اختياري): رموز مرجعية مغلّفة من الشكل [1, total_reference_tokens, C]، أو None عندما لا يتم تقديم شروط مرجعية (يُتخطى LTX2AutoReferenceEncoderStep). reference_coords (Tensor, اختياري): إحداثيات RoPE لرموز المرجع. reference_token_counts (list, اختياري): عدد الرموز لكل مرجع، بترتيب reference_conditions. latents (Tensor): قيم كامنة ضوضائية مولّدة مسبقًا لتوليد الصورة. noise_scale (float, اختياري): مستوى الضوضاء الأولي للرموز غير المشروطة. None (الافتراضي) يُحدَّد إلى sigmas[0] عندما يتم تقديم sigmas مخصصة، وإلا 1.0. sigmas (list, اختياري): قيم sigmas مخصصة لعملية إزالة الضوضاء. reference_cross_mask (Tensor, اختياري): قوى انتباه ضوضائي<->مرجعي لكل رمز مرجعي من الشكل [1, num_ref_tokens]. num_inference_steps (int): عدد خطوات إزالة الضوضاء. timesteps (Tensor): خطوات الزمن لعملية إزالة الضوضاء. audio_latents (Tensor): قيم كامنة صوتية مُرمَّزة مسبقًا اختيارية؛ تُستخدم ضوضاء عشوائية عندما لا يتم تقديمها. *denoiser_input_fields (None,اختياري): مدخلات النموذج الشرطية لمزيل الضوضاء: مثل prompt_embeds، negative_prompt_embeds، إلخ. use_cross_timestep (bool,اختياري, الافتراضي True): ما إذا كان سيتم اشتراط المحوّل على خطوة زمنية متقاطعة منفصلة لكل رمز (LTX-2.3+). attention_kwargs (dict,اختياري): حجج إضافية لمعالجات الانتباه. image_latents (Tensor,اختياري): قيم كامنة لصورة مرجعية مُرمَّزة بـ VAE تُستخدم لاشتراط الصورة إلى الفيديو. output_type (str,اختياري, الافتراضي pil): صيغة الإخراج: ‘pil’، ‘np’، ‘pt’. decode_timestep (None,اختياري, الافتراضي 0.0): خطوة الزمن التي يقوم فيها VAE بفك ترميز القيم الكامنة النهائية. decode_noise_scale (None,اختياري*): عامل استيفاء الضوضاء المطبَّق على القيم الكامنة عند خطوة فك الترميز.

المخرجات: فيديوهات (list): الفيديوهات المولّدة. صوت (Tensor): موجة الصوت المولّدة.

LTX25ModularPipeline

فئة diffusers.LTX25ModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

ModularPipeline لـ LTX-2.5 (توليد مشترك للفيديو والصوت).

مماثل لـ LTX2ModularPipeline باستثناء أن كتله الافتراضية تقوم بفك الترميز باستخدام مُفك ترميز الفيديو الانتشاري، وهو الإعداد الافتراضي الأصلي بدءًا من LTX-2.5. يتم توجيه نقطة التفتيش إلى هنا عبر modular_model_index.json.

LTX25AutoBlocks

فئة diffusers.LTX25AutoBlocks

< >

( )

كتل تلقائية لنموذج LTX-2.5 تدعم التوليد من النص إلى الفيديو، ومن الصورة إلى الفيديو، ومن الشرط إلى الفيديو، والتوليد في السياق (IC-LoRA) (فيديو وصوت معاً). هي مطابقة تماماً لـLTX2AutoBlocks باستثناء أن فاحش الفيديو هو LTX2DiffusionVaeDecoderStep، لأن فاحش الانتشار هو الافتراضي الأصلي بدءاً من LTX-2.5. لتفكيك الترميز باستخدام VAE التوافقي بدلاً من ذلك، استبدل كتلة التفكيك: blocks.sub_blocks["decode"] = LTX2AutoDecoderStep().

سير العمل المدعومة:

  • text2video: يتطلب prompt
  • image2video: يتطلب image، prompt
  • condition: يتطلب conditions، prompt
  • in_context: يتطلب reference_conditions، num_frames، prompt

المكوّنات: 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)

المُدخلات: prompt (str, اختياري): الموجّه أو الموجّهات لتوجيه توليد الصورة. conditions (list, اختياري): LTX2VideoCondition (أو قائمة منها) لوضع شروط الصورة/الفيديو عند فهارس الإطارات الكامنة للفيديو المولّد. enable_prompt_enhancement (bool, اختياري, الافتراضي False): ما إذا كان سيتم تشغيل معزّز الموجّه. خيار اختياري، بما يتوافق مع خطوط أنابيب Lightricks المرجعية. system_prompt (str, اختياري): موجّه النظام للتحسين. الافتراضي هو LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT عندما يكون إطار شرط PIL.Image.Image متاحا، وإلا LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT. prompt_max_new_tokens (int, اختياري): الحد الأقصى لعدد الرموز الجديدة التي سيتم توليدها أثناء تحسين الموجّه. الافتراضي هو 600، وهو ميزانية معزّز LTX-2.5 Gemma-4. prompt_enhancement_kwargs (dict, اختياري): حجج الكلمات المفتاحية لاستدعاء .generate الخاص بالمعزّز. الافتراضي هو فك الترميز الجشع. prompt_enhancement_seed (int, اختياري, الافتراضي 10): البذرة العشوائية لتحسين الموجّه (غير فعّالة تحت فك الترميز الجشع في LTX-2.5). generator (Generator, اختياري): مولّد Torch للتوليد الحتمي. image (Image | list, اختياري): صورة أو صور مرجعية لإزالة الضوضاء. يمكن أن تكون صورة واحدة أو قائمة من الصور. negative_prompt (str, اختياري): الموجّه أو الموجّهات التي لا يجب أن توجّه توليد الصورة. max_sequence_length (int, اختياري, الافتراضي 1024): الطول الأقصى للتسلسل لترميز الموجّه. min_seconds (float, اختياري, الافتراضي 1.0): الحد الأدنى للمدة المتوقعة تلقائيا. max_seconds (float, اختياري, الافتراضي 20.0): الحد الأقصى للمدة المتوقعة تلقائيا. يجب أن يكون أكبر بصرامة من min_seconds. frame_rate (float, اختياري, الافتراضي 24.0): عدد الإطارات في الثانية للفيديو المولّد. height (int, اختياري, الافتراضي 512): الارتفاع بالبكسل للصورة المولّدة. width (int, اختياري, الافتراضي 704): العرض بالبكسل للصورة المولّدة. image_crf (int, اختياري): قيمة H.264 CRF المستخدمة لإعادة ضغط صورة الشرط image قبل ترميز VAE، بما يتوافق مع الضغط الذي تم تدريب النموذج ضده. None (الافتراضي) يُستنتج من توليد مرمّز النص (33 حتى LTX-2.3، و18 لـ LTX-2.5). مرّر 0 لتخطي إعادة الضغط. يتطلب PIL.Image.Image عند تشغيل إعادة الضغط. num_frames (int, اختياري): عدد الإطارات في الفيديو المولّد. اتركه فارغا للتوقع التلقائي عبر duration_head (انظر LTX2AutoDurationStep). reference_conditions (list, اختياري): LTX2ReferenceCondition (أو قائمة منها) يتم ترميز فيديوهاتها إلى رموز كامنة إضافية يتفاعل معها مكيّف IC-LoRA. reference_downscale_factor (int, اختياري, الافتراضي 1): النسبة بين دقة الهدف ودقة المرجع؛ 2 تعني أن المرجع يُعالج مسبقا عند نصف دقة الهدف. تُقاس الإحداثيات المكانية بهذا العامل بحيث تهبط رموز المرجع في فضاء إحداثيات الهدف. يجب أن يتطابق مع العامل الذي تم تدريب IC-LoRA به. conditioning_attention_strength (float, اختياري, الافتراضي 1.0): مقياس في [0, 1] يتحكم في مدى تفاعل الرموز الضوضائية ورموز المرجع مع بعضها البعض. 1.0 (الافتراضي) يترك الانتباه غير مقنّع. conditioning_attention_mask (Tensor, اختياري): قناع اختياري في فضاء البكسل من الشكل (1, 1, F, H, W) بقيم في [0, 1] يعطي قوة انتباه متغيرة مكانيا. يُصغّر إلى الشبكة الكامنة للمرجع ويُضرب في conditioning_attention_strength. motion_speed (float, اختياري, الافتراضي 1.0): سرعة الحركة مقارنة بالوقت الحقيقي. تُشترط التضمينات الموضعية على frame_rate / motion_speed، لذا فإن القيم الأقل من 1 تُبطئ الحركة، على سبيل المثال 0.2 لحركة بطيئة 5x في LoRA الخاص بـ Slow-Motion-Control. يبقى frame_rate معدل التشغيل. num_videos_per_prompt (int, اختياري, الافتراضي 1): عدد الصور التي سيتم توليدها لكل موجّه. condition_latents (list, اختياري): قيم كامنة مُطبّعة لـ VAE لكل شرط من الشكل [1, C, F, H, W]. condition_strengths (list, اختياري): قوى الشرط لكل شرط. condition_indices (list, اختياري): فهرس الإطار الكامن لكل شرط حيث يُطبَّق الشرط. condition_pixel_frames (list, اختياري): عدد إطارات البكسل المقصوصة لكل شرط، يُستخدم لتقييد إحداثيات الإطارات الرئيسية أحادية الإطار. reference_latents (Tensor, اختياري): رموز مرجعية مُجمّعة من الشكل [1, total_reference_tokens, C]، أو None عندما لا يتم تقديم شروط مرجعية (يتم تخطي LTX2AutoReferenceEncoderStep). reference_coords (Tensor, اختياري): إحداثيات RoPE لرموز المرجع. reference_token_counts (list, اختياري): عدد الرموز لكل مرجع، بترتيب reference_conditions. latents (Tensor): قيم كامنة ضوضائية مولّدة مسبقا لتوليد الصورة. noise_scale (float, اختياري): مستوى الضوضاء الأولي للرموز غير المشروطة. None (الافتراضي) يُستنتج إلى sigmas[0] عندما يتم تقديم sigmas مخصصة، وإلا 1.0. sigmas (list, اختياري): قيم sigmas مخصصة لعملية إزالة الضوضاء. reference_cross_mask (Tensor, اختياري): قوى انتباه ضوضائي<->مرجعي لكل رمز مرجعي من الشكل [1, num_ref_tokens]. num_inference_steps (int): عدد خطوات إزالة الضوضاء. timesteps (Tensor): خطوات الزمن لعملية إزالة الضوضاء. audio_latents (Tensor): قيم كامنة صوتية مرمّزة مسبقا اختيارية؛ تُستخدم ضوضاء عشوائية عندما لا يتم تقديمها. *denoiser_input_fields (None,اختياري): مدخلات النموذج الشرطية لمزيل الضوضاء: على سبيل المثال prompt_embeds، negative_prompt_embeds، إلخ. use_cross_timestep (bool,اختياري, الافتراضي True): ما إذا كان سيتم اشتراط المحوّل على خطوة زمنية متقاطعة منفصلة لكل رمز (LTX-2.3+). attention_kwargs (dict,اختياري): حجج إضافية لمعالجات الانتباه. image_latents (Tensor,اختياري): قيم كامنة لصور مرجعية مرمّزة بـ VAE تُستخدم لاشتراط الصورة إلى الفيديو. output_type (str,اختياري*، الافتراضي pil): صيغة الإخراج: ‘pil’، ‘np’، ‘pt’.

المخرجات: فيديوهات (list): الفيديوهات المولّدة. صوت (Tensor): موجة الصوت المولّدة.

Update on GitHub

←لاتيه LTXVideo→