diffusers/main/ar/api/pipelines/ltx2.md

مرخّص بموجب ترخيص Apache الإصدار 2.0 (المسمى "الترخيص")

لا يجوز لك استخدام هذا الملف إلا وفقاً لشروط الترخيص.

يمكنك الحصول على نسخة من الترخيص في

http://www.apache.org/licenses/LICENSE-2.0

ما لم يقتضِ ذلك القانون المعمول به أو ما اتُّفق عليه كتابياً، البرمجيات

تُوزَّع بموجب الرخصة على أساس "كما هي"،

بلا أي ضمانات أو شروط من أي نوع، سواء صريحة أو ضمنية.

راجع الترخيص لمعرفة اللغة المحددة التي تحكم الصلاحيات و

قيود بموجب الترخيص. -->

LTX-2

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 الخاص بـ vocoder)، لأن فك الترميز يحتاج إلى مساحة عمل خاصة به. راجع 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

يُوصى بشدة باستخدام تعزيز الأوامر لـ 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. اترك كلمات السرعة ("حركة بطيئة"، "إطارات في الثانية عالية") خارج الأمر النصي، وأعد استخدام نفس الوصف عبر السرعات المختلفة، لأن 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]]

diffusers.LTX2Pipeline[[diffusers.LTX2Pipeline]]

diffusers.LTX2Pipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)

المصدر

المعاملات:

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[[diffusers.LTX2Pipeline.call]]

__call__(prompt: str | list[str] = None, negative_prompt: str | list[str] | None = None, height: int = 512, width: int = 768, num_frames: int | None = None, min_seconds: float = 1.0, max_seconds: float = 20.0, frame_rate: float = 24.0, motion_speed: float = 1.0, num_inference_steps: int = 30, sigmas: list[float] | None = None, timesteps: list[int] = None, guidance_scale: float = 3.0, stg_scale: float = 1.0, modality_scale: float = 3.0, guidance_rescale: float = 0.7, audio_guidance_scale: float | None = 7.0, audio_stg_scale: float | None = 1.0, audio_modality_scale: float | None = 3.0, audio_guidance_rescale: float | None = 0.7, spatio_temporal_guidance_blocks: list[int] | None = [28], noise_scale: float = 0.0, num_videos_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 1024)

المصدر

المعاملات:

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، اختياري) : كامنات ضجيج مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الفيديو. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم توليد كامنات من خلال الاستخراج باستخدام 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 لمُحسِّن الاستعلام prompt_enhancer المخصص لنموذج Gemma 4 (LTX-2.5) أو 512 كبديل لمُشفِّر النص text_encoder في Gemma 3 (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[[diffusers.LTX2Pipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, scale_factor: int = 8, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)

المصدر

المعاملات:

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 dtype

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

enhance_prompt[[diffusers.LTX2Pipeline.enhance_prompt]]

enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)

المصدر

يعزز 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]]

diffusers.LTX2ImageToVideoPipeline[[diffusers.LTX2ImageToVideoPipeline]]

diffusers.LTX2ImageToVideoPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)

المصدر

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

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

TODO

call[[diffusers.LTX2ImageToVideoPipeline.call]]

__call__(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, prompt: str | list[str] = None, negative_prompt: str | list[str] | None = None, height: int = 512, width: int = 768, num_frames: int | None = None, min_seconds: float = 1.0, max_seconds: float = 20.0, frame_rate: float = 24.0, motion_speed: float = 1.0, num_inference_steps: int = 30, sigmas: list[float] | None = None, timesteps: list[int] | None = None, guidance_scale: float = 3.0, stg_scale: float = 1.0, modality_scale: float = 3.0, guidance_rescale: float = 0.7, audio_guidance_scale: float | None = 7.0, audio_stg_scale: float | None = 1.0, audio_modality_scale: float | None = 3.0, audio_guidance_rescale: float | None = 0.7, spatio_temporal_guidance_blocks: list[int] | None = [28], noise_scale: float = 0.0, num_videos_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, image_crf: int | None = None, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 1024)

المصدر

المعاملات:

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، اختياري) : كامنات ضجيج مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الفيديو. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم توليد كامنات من خلال الاستخراج باستخدام 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 لمُحسِّن الاستعلام prompt_enhancer المخصص لنموذج Gemma 4 (LTX-2.5) أو 512 كبديل لمُشفِّر النص text_encoder في Gemma 3 (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[[diffusers.LTX2ImageToVideoPipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, scale_factor: int = 8, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)

المصدر

المعاملات:

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 dtype

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

enhance_prompt[[diffusers.LTX2ImageToVideoPipeline.enhance_prompt]]

enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)

المصدر

يعزز 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]]

diffusers.LTX2ConditionPipeline[[diffusers.LTX2ConditionPipeline]]

diffusers.LTX2ConditionPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, audio_scheduler: diffusers.schedulers.scheduling_flow_match_euler_discrete.FlowMatchEulerDiscreteScheduler | None = None, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)

المصدر

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

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

TODO

call[[diffusers.LTX2ConditionPipeline.call]]

__call__(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, prompt: str | list[str] = None, negative_prompt: str | list[str] | None = None, height: int = 512, width: int = 768, num_frames: int | None = None, min_seconds: float = 1.0, max_seconds: float = 20.0, frame_rate: float = 24.0, motion_speed: float = 1.0, num_inference_steps: int = 30, sigmas: list[float] | None = None, timesteps: list[float] | None = None, guidance_scale: float = 3.0, stg_scale: float = 1.0, modality_scale: float = 3.0, guidance_rescale: float = 0.7, audio_guidance_scale: float | None = 7.0, audio_stg_scale: float | None = 1.0, audio_modality_scale: float | None = 3.0, audio_guidance_rescale: float | None = 0.7, spatio_temporal_guidance_blocks: list[int] | None = [28], noise_scale: float | None = None, num_videos_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 1024)

المصدر

المعاملات:

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، اختياري) : كامنات ضجيج مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الفيديو. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم توليد كامنات من خلال الاستخراج باستخدام 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 لمُحسِّن الاستعلام prompt_enhancer المخصص لنموذج Gemma 4 (LTX-2.5) أو 512 كبديل لمُشفِّر النص text_encoder في Gemma 3 (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[[diffusers.LTX2ConditionPipeline.apply_first_frame_conditioning]]

apply_first_frame_conditioning(latents: Tensor, conditioning_mask: Tensor, condition_latents: list[torch.Tensor], condition_strengths: list[float], condition_indices: list[int], latent_height: int, latent_width: int)

المصدر

المعاملات:

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[[diffusers.LTX2ConditionPipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, scale_factor: int = 8, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)

المصدر

المعاملات:

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 dtype

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

enhance_prompt[[diffusers.LTX2ConditionPipeline.enhance_prompt]]

enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)

المصدر

يعزز 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[[diffusers.LTX2ConditionPipeline.prepare_latents]]

prepare_latents(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, batch_size: int = 1, num_channels_latents: int = 128, height: int = 512, width: int = 768, num_frames: int = 121, frame_rate: float = 24.0, noise_scale: float = 1.0, dtype: typing.Optional[torch.dtype] = None, device: typing.Optional[torch.device] = None, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None)

المصدر

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

تُطبَّق شروط الإطار الأول (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[[diffusers.LTX2ConditionPipeline.preprocess_conditions]]

preprocess_conditions(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, device: typing.Optional[torch.device] = None)

المصدر

المعاملات:

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[[diffusers.LTX2ConditionPipeline.trim_conditioning_sequence]]

trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int)

المصدر

المعاملات:

start_frame (int) : رقم الإطار المستهدف للإطار الأول في التسلسل.

sequence_num_frames (int) : عدد الإطارات في التسلسل.

target_num_frames (int) : العدد المستهدف للإطارات في الفيديو المولّد.

يعيد: int

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

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

LTX2DFRPipeline[[diffusers.LTX2DFRPipeline]]

diffusers.LTX2DFRPipeline[[diffusers.LTX2DFRPipeline]]

diffusers.LTX2DFRPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)

المصدر

المعاملات:

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) : مُصوِّت (Vocoder) لتحويل مطيافات ميل (mel spectrograms) إلى موجات صوتية.

processor (ProcessorMixin، اختياري) : المعالج المستخدم لتحسين الأوامر في القوالب الدردشية.

prompt_enhancer (Gemma4ForConditionalGeneration، اختياري) : نموذج مخصص لتعزيز الأوامر (LTX-2.5).

duration_head (LTX2DurationHead، اختياري) : يتنبأ بـnum_frames من تضمينات الموجه عندما لا يُزود بـ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[[diffusers.LTX2DFRPipeline.call]]

__call__(prompt: str | list[str] = None, conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 704, width: int = 1216, num_frames: int | None = None, frame_rate: float = 24.0, min_seconds: float = 1.0, max_seconds: float = 20.0, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, keyframes_latents: typing.Optional[torch.Tensor] = None, keyframe_positions: list[int] | None = None, reference_latents: typing.Optional[torch.Tensor] = None, reference_downscale_factor: int = 2, guidance_keyframe_latents: typing.Optional[torch.Tensor] = None, guidance_keyframe_positions: list[int] | None = None, guidance_keyframe_strength: float = 1.0, generate_slots: bool = True, sigmas: list[float] = [1.0, 0.99375, 0.9875, 0.98125, 0.975, 0.909375, 0.725, 0.421875], noise_scale: float | None = None, freeze_audio: bool = False, video_tiles: list[diffusers.pipelines.ltx2.dfr_layout.LTX2DFREpilogueTile] | None = None, num_videos_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 1024)

المصدر

المعاملات:

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). ما يزال المرحلتان الثانية تنفّذ مسارًا صوتيًا مشتركًا؛ الموجة الصوتية المرفقة لوصفة مُركّبة هي تلك الخاصة بالمرحلة الأولى، والتي يحتفظ بها المستدعي.

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) : تثبيت الصوت عند سيجما 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) : ما إذا كان سيتم استخدام سيجما بين الوسائط (cross-modality sigma) لتعديل الانتباه المتقاطع (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"]) : مدخلات Tensor لدالة الاستدعاء.

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

إزالة الضوضاء[[diffusers.LTX2DFRPipeline.denoise]]

denoise(latents: Tensor, conditioning_mask: Tensor, clean_latents: Tensor, video_coords: Tensor, keyframes_mask: Tensor, prompt_embeds: Tensor, audio_prompt_embeds: Tensor, prompt_attention_mask: Tensor, sigmas: list[float], frame_rate: float, audio_latents: Tensor, freeze_audio: bool = False, video_tile_plan: list | None = None, generator: typing.Optional[torch.Generator] = None, use_cross_timestep: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, progress_bar = None, step_offset: int = 0, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] | None = None)

المصدر

المعاملات:

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 وتتخذ خطوة Euler كما هي. أما تحسين الزمن فيستبدلها بـ LTXEulerAncestralRFScheduler (eta=0.5)؛ إذ تعيد تلك الخطوة إضافة الضوضاء إلى كل رمز، لذا يُعاد تطبيق مزج الشرط بعدها وإلا تآكلت نقاط التثبيت عند الفواصل بقوة 0.95.

encode_conditions[[diffusers.LTX2DFRPipeline.encode_conditions]]

encode_conditions(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None, height: int, width: int, num_frames: int, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None, generator: typing.Optional[torch.Generator] = None)

المصدر

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

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

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

encode_prompt[[diffusers.LTX2DFRPipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)

المصدر

المعاملات:

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 dtype

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

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

enhance_prompt[[diffusers.LTX2DFRPipeline.enhance_prompt]]

enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)

المصدر

يعزز 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[[diffusers.LTX2DFRPipeline.prepare_latents]]

prepare_latents(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, condition_latents: list[tuple[int, torch.Tensor, float, int]] | None = None, keyframe_latents: list[tuple[int, torch.Tensor, float]] | None = None, slot_frame_indices: list[int] | None = None, slot_initial_latents: typing.Optional[torch.Tensor] = None, reference_latents: typing.Optional[torch.Tensor] = None, reference_downscale_factor: int = 1, batch_size: int = 1, num_channels_latents: int = 128, height: int = 512, width: int = 768, num_frames: int = 121, frame_rate: float = 24.0, noise_scale: float = 1.0, dtype: typing.Optional[torch.dtype] = None, device: typing.Optional[torch.device] = None, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None, latents_normalized: bool = True)

المصدر

المعاملات:

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_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[[diffusers.LTX2DFRPipeline.preprocess_conditions]]

preprocess_conditions(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, device: typing.Optional[torch.device] = None)

المصدر

المعاملات:

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[[diffusers.LTX2DFRPipeline.rebuild_epilogue_keyframes]]

rebuild_epilogue_keyframes(keyframe_latents: Tensor, decode_timestep: float, decode_noise_scale: float, seed: int, device: device, dtype: dtype)

المصدر

المعاملات:

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[[diffusers.LTX2DFRPipeline.trim_conditioning_sequence]]

trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int)

المصدر

المعاملات:

start_frame (int) : رقم الإطار المستهدف للإطار الأول في التسلسل.

sequence_num_frames (int) : عدد الإطارات في التسلسل.

target_num_frames (int) : العدد المستهدف للإطارات في الفيديو المولّد.

يعيد: int

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

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

LTX2DFRTemporalRefinePipeline[[diffusers.LTX2DFRTemporalRefinePipeline]]

diffusers.LTX2DFRTemporalRefinePipeline[[diffusers.LTX2DFRTemporalRefinePipeline]]

diffusers.LTX2DFRTemporalRefinePipeline(scheduler: LTXEulerAncestralRFScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, temporal_latent_upsampler: LTX2LatentUpsamplerModel)

المصدر

المعاملات:

scheduler (LTXEulerAncestralRFScheduler) : مُجدول أويلر الأسلاف في معادلة التدفق المُصحَّح. أنشئه باستخدام 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) : مُصوِّت (Vocoder) لتحويل مطيافات ميل (mel spectrograms) إلى موجات صوتية.

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[[diffusers.LTX2DFRTemporalRefinePipeline.call]]

__call__(prompt: str | list[str] = None, latents: Tensor = None, keyframes_latents: Tensor = None, keyframe_positions: list[int] = None, audio_latents: Tensor = None, conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 704, width: int = 1216, num_frames: int = 121, frame_rate: float = 24.0, source_seconds: float | None = None, condition_num_frames: int | None = None, round_index: int = 1, sigmas: list[float] = [0.975, 0.909375, 0.725, 0.421875], noise_scale: float | None = None, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 1024)

المصدر

المعاملات:

prompt (str أو List[str]، اختياري) : الأمر أو الأوامر التي تُوجّه توليد الفيديو. إذا لم يُعرَّف، يجب تمرير prompt_embeds.

latents (torch.Tensor) : كامنات الفيديو الخام للوحة input، (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) الخاص بـ input. يقوم الدالة round بمضاعفته.

source_seconds (float, اختياري) : مدة مرحلة الصوت الأولى المجمّدة. القيمة الافتراضية هي num_frames / frame_rate، وهي صحيحة للجولة الأولى؛ أما الجولات اللاحقة فيجب أن تمرر مدة المرحلة الأولى الأصلية حتى لا تنحرف البلاطات.

condition_num_frames (int, اختياري) : قيمة num_frames الأصلية المستخدمة لتشفير conditions. القيمة الافتراضية هي num_frames. بعد إضافة الحشو أو جولة سابقة، مرّر الطلب الأصلي حتى لا يلتف index=-1 إلى نهاية الحشو.

round_index (int، اختياري، القيمة الافتراضية 1) : رقم الجولة بدءًا من 1. تُزرع ضوضاء الأسلاف البذرية على شكل seed + 1000 * round_index + tile، وتُضبط الشروط بمعامل 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) : ما إذا كان سيتم استخدام سيجما بين الوسائط (cross-modality sigma) لتعديل الانتباه المتقاطع (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"]) : مدخلات Tensor لدالة الاستدعاء.

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

إزالة الضوضاء[[diffusers.LTX2DFRTemporalRefinePipeline.denoise]]

denoise(latents: Tensor, conditioning_mask: Tensor, clean_latents: Tensor, video_coords: Tensor, keyframes_mask: Tensor, prompt_embeds: Tensor, audio_prompt_embeds: Tensor, prompt_attention_mask: Tensor, sigmas: list[float], frame_rate: float, audio_latents: Tensor, freeze_audio: bool = False, video_tile_plan: list | None = None, generator: typing.Optional[torch.Generator] = None, use_cross_timestep: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, progress_bar = None, step_offset: int = 0, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] | None = None)

المصدر

المعاملات:

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 وتتخذ خطوة Euler كما هي. أما تحسين الزمن فيستبدلها بـ LTXEulerAncestralRFScheduler (eta=0.5)؛ إذ تعيد تلك الخطوة إضافة الضوضاء إلى كل رمز، لذا يُعاد تطبيق مزج الشرط بعدها وإلا تآكلت نقاط التثبيت عند الفواصل بقوة 0.95.

encode_conditions[[diffusers.LTX2DFRTemporalRefinePipeline.encode_conditions]]

encode_conditions(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None, height: int, width: int, num_frames: int, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None, generator: typing.Optional[torch.Generator] = None)

المصدر

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

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

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

encode_prompt[[diffusers.LTX2DFRTemporalRefinePipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)

المصدر

المعاملات:

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 dtype

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

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

prepare_latents[[diffusers.LTX2DFRTemporalRefinePipeline.prepare_latents]]

prepare_latents(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, condition_latents: list[tuple[int, torch.Tensor, float, int]] | None = None, keyframe_latents: list[tuple[int, torch.Tensor, float]] | None = None, slot_frame_indices: list[int] | None = None, slot_initial_latents: typing.Optional[torch.Tensor] = None, reference_latents: typing.Optional[torch.Tensor] = None, reference_downscale_factor: int = 1, batch_size: int = 1, num_channels_latents: int = 128, height: int = 512, width: int = 768, num_frames: int = 121, frame_rate: float = 24.0, noise_scale: float = 1.0, dtype: typing.Optional[torch.dtype] = None, device: typing.Optional[torch.device] = None, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None, latents_normalized: bool = True)

المصدر

المعاملات:

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_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[[diffusers.LTX2DFRTemporalRefinePipeline.preprocess_conditions]]

preprocess_conditions(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, device: typing.Optional[torch.device] = None)

المصدر

المعاملات:

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[[diffusers.LTX2DFRTemporalRefinePipeline.trim_conditioning_sequence]]

trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int)

المصدر

المعاملات:

start_frame (int) : رقم الإطار المستهدف للإطار الأول في التسلسل.

sequence_num_frames (int) : عدد الإطارات في التسلسل.

target_num_frames (int) : العدد المستهدف للإطارات في الفيديو المولّد.

يعيد: int

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

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

upsample_latents[[diffusers.LTX2DFRTemporalRefinePipeline.upsample_latents]]

upsample_latents(latents: Tensor, upsampler: LTX2LatentUpsamplerModel)

المصدر

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

LTX2DFRPipelineOutput[[diffusers.LTX2DFRPipelineOutput]]

diffusers.LTX2DFRPipelineOutput[[diffusers.LTX2DFRPipelineOutput]]

diffusers.LTX2DFRPipelineOutput(frames: Tensor, audio: Tensor, keyframes: typing.Optional[torch.Tensor] = None, keyframe_positions: list[int] | None = None)

المصدر

المعاملات:

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

diffusers.LTX2LatentUpsamplePipeline[[diffusers.LTX2LatentUpsamplePipeline]]

diffusers.LTX2LatentUpsamplePipeline(vae: AutoencoderKLLTX2Video, latent_upsampler: LTX2LatentUpsamplerModel)

المصدر

call[[diffusers.LTX2LatentUpsamplePipeline.call]]

__call__(video: list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, spatial_patch_size: int = 1, temporal_patch_size: int = 1, latents: typing.Optional[torch.Tensor] = None, latents_normalized: bool = False, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, adain_factor: float = 0.0, tone_map_compression_ratio: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str | None = 'pil', return_dict: bool = True)

المصدر

المعاملات:

video (list[PipelineImageInput]، اختياري) : الفيديو الذي سيتم رفع دقته (مثل مخرج المرحلة الأولى من LTX 2.0). إذا لم يُقدَّم، فيجب تقديم latents.

height (int، اختياري، القيمة الافتراضية 512) : ارتفاع الفيديو المدخل بالبكسل (وليس الفيديو المولّد، الذي سيكون بدقة أعلى).

width (int، اختياري، القيمة الافتراضية 768) : عرض الفيديو المُدخل بالبكسل (وليس الفيديو المُولَّد، الذي سيكون بدقة أعلى).

num_frames (int، اختياري، القيمة الافتراضية 121) : عدد الإطارات في الفيديو المُدخل.

spatial_patch_size (int، اختياري، القيمة الافتراضية 1) : حجم البقعة المكانية (spatial patch size) لمتغيرات الفيديو (video 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) أو كامن فيديو بشكل (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 (الافتراضية) عدم إجراء تطبيع الأمثلة التكيفية.

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[[diffusers.LTX2LatentUpsamplePipeline.adain_filter_latent]]

adain_filter_latent(latents: Tensor, reference_latents: Tensor, factor: float = 1.0)

المصدر

المعاملات:

latents (torch.Tensor) : الكامنات المدخلة التي يجب تطبيعها

reference_latents (torch.Tensor) : الكامنات المرجعية التي توفر إحصاءات الأسلوب.

factor (float) : معامل الدمج بين الحالة الكامنة الأصلية والحالة الكامنة المحوّلة. النطاق: من -10.0 إلى 10.0، الافتراضي: 1.0

يعيد: torch.Tensor

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

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

tone_map_latents[[diffusers.LTX2LatentUpsamplePipeline.tone_map_latents]]

tone_map_latents(latents: Tensor, compression: float)

المصدر

المعاملات:

latents : torch.Tensor متجه كامن (latent tensor) مدخل ذو شكل تعسفي. يُتوقع أن يكون ضمن النطاق [-1, 1] أو [0, 1] تقريبًا.

compression : float قوة الضغط في المدى [0, 1]. - 0.0: لا يوجد تطبيق للتون-مابينغ (تحويل هوية) - 1.0: تأثير ضغط كامل

يعيد:

torch.Tensor متجه كامن مُعاد ضبط تدرّجه اللوني (tone-mapped) بنفس شكل المدخلات.

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

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

LTX2VideoDiffusionDecodePipeline[[diffusers.LTX2VideoDiffusionDecodePipeline]]

diffusers.LTX2VideoDiffusionDecodePipeline[[diffusers.LTX2VideoDiffusionDecodePipeline]]

diffusers.LTX2VideoDiffusionDecodePipeline(diffusion_decoder: LTX2VideoDiffusionDecoderModel, scheduler, vae: AutoencoderKLLTX2Video = None)

المصدر

المعاملات:

diffusion_decoder (LTX2VideoDiffusionDecoderModel) : مُفكّك الفيديو الانتشاري.

scheduler (FlowMatchEulerDiscreteScheduler) : المجدول الذي يقود خطوات إزالة الضوضاء في المُفكِّك.

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

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

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

call[[diffusers.LTX2VideoDiffusionDecodePipeline.call]]

__call__(latents: Tensor, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str = 'pil', return_dict: bool = True, denormalize: bool = True)

المصدر

المعاملات:

latents (torch.Tensor) : متغيرات (Latents) بأبعاد (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]]

diffusers.pipelines.ltx2.LTX2DurationHead[[diffusers.pipelines.ltx2.LTX2DurationHead]]

diffusers.pipelines.ltx2.LTX2DurationHead(video_cross_attention_dim: int = 4096, audio_cross_attention_dim: int = 2048, pooler_hidden_dim: int = 256, num_queries: int = 1, num_pooler_heads: int = 4, mlp_hidden_dim: int = 256)

المصدر

المعاملات:

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[[diffusers.pipelines.ltx2.LTX2DurationHead.forward]]

forward(video_tokens: typing.Optional[torch.Tensor] = None, audio_tokens: typing.Optional[torch.Tensor] = None)

المصدر

المعاملات:

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[[diffusers.pipelines.ltx2.LTX2DurationHead.predict_num_frames]]

predict_num_frames(video_tokens: typing.Optional[torch.Tensor] = None, audio_tokens: typing.Optional[torch.Tensor] = None, frame_rate: float, temporal_compression_ratio: int, min_seconds: float = 1.0, max_seconds: float = 20.0)

المصدر

المعاملات:

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

diffusers.pipelines.ltx2.LTX2PipelineOutput[[diffusers.pipelines.ltx2.LTX2PipelineOutput]]

diffusers.pipelines.ltx2.LTX2PipelineOutput(frames: Tensor, audio: Tensor)

المصدر

المعاملات:

frames (torch.Tensor، np.ndarray، أو list[list[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]]

diffusers.LTX2ModularPipeline[[diffusers.LTX2ModularPipeline]]

diffusers.LTX2ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)

المصدر

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

LTX2AutoBlocks[[diffusers.LTX2AutoBlocks]]

diffusers.LTX2AutoBlocks[[diffusers.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]]

diffusers.LTX25ModularPipeline[[diffusers.LTX25ModularPipeline]]

diffusers.LTX25ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)

المصدر

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

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

LTX25AutoBlocks[[diffusers.LTX25AutoBlocks]]

diffusers.LTX25AutoBlocks[[diffusers.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): موجة الصوت المولّدة.