# # مرخّص بموجب ترخيص Apache الإصدار 2.0 (المسمى "الترخيص") # لا يجوز لك استخدام هذا الملف إلا وفقاً لشروط الترخيص. # يمكنك الحصول على نسخة من الترخيص في # # http://www.apache.org/licenses/LICENSE-2.0 # # ما لم يقتضِ ذلك القانون المعمول به أو ما اتُّفق عليه كتابياً، البرمجيات # تُوزَّع بموجب الرخصة على أساس "كما هي"، # بلا أي ضمانات أو شروط من أي نوع، سواء صريحة أو ضمنية. # راجع الترخيص لمعرفة اللغة المحددة التي تحكم الصلاحيات و # قيود بموجب الترخيص. --> # LTX-2 [LTX-2](https://hf.co/papers/2601.03233) هو نموذج أساسي يعتمد على DiT، صُمم لتوليد فيديو وصوت متزامنين ضمن نموذج واحد. يجمع بين العناصر الأساسية لتوليد الفيديو الحديث، مع أوزان مفتوحة وتركيز على التنفيذ العملي محليًا. يمكنك العثور على جميع نقاط التفتيش الأصلية لنموذج LTX-Video تحت منظمة [Lightricks](https://huggingface.co/Lightricks). يمكن العثور على قاعدة الكود الأصلية لـ LTX-2 [هنا](https://github.com/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 مع تعزيز الملمس والحدة. استخدام نموذجي لخط أنابيب تحويل النص إلى فيديو على مرحلتين ```py 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", ) ``` ## توليد نقطة تحقق مُصغّرة أسرع خط أنابيب لتوليد مرحلتين باستخدام نقطة تحقق مُقطّرة. ```py 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): ```py 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", ) ``` يمكنك استخدام كل من شروط الصور والفيديو: ```py 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](https://huggingface.co/papers/2207.12598) القياسي حيث يتم توليد المخرجات المُزعزَعة (الأضعف) باستخدام الموجه السلبي. 2. الإرشاد المكاني-الزمني (STG): [STG](https://huggingface.co/papers/2411.18664) يتخلى عن المخرجات المضطربة الناتجة عن اختصار عمليات الانتباه الذاتي (self-attention) ويستبدلها بقيم الانتباه بدلاً من ذلك. الفكرة هي أن هذا يؤدي إلى إنشاء فيديوهات أكثر حدة واتساق مكاني-زمني أفضل. 3. إرشادات عزل النمط: تتجه بعيداً عن المخرجات المضطربة الناتجة عن تعطيل الانتباه المتقاطع بين الأنماط (من الصوت إلى الفيديو ومن الفيديو إلى الصوت). هذا الإرشاد أكثر تحديداً لنماذج [LTX-2.X](https://huggingface.co/papers/2601.03233)، على أساس أن ذلك يُنتج اتساقاً أفضل بين الصوت والفيديو المولَّدين. تُتحكَّم هذه المعايير عبر الحجج `guidance_scale` و`stg_scale` و`modality_scale`، ويمكن ضبطها بشكل منفصل للفيديو والصوت. بالإضافة إلى ذلك، فيما يتعلق بتقنية STG، يجب تحديد فهارس كتل التحويل (transformer blocks) التي يتم فيها تجاوز الانتباه الذاتي (self-attention) عبر الحجة `spatio_temporal_guidance_blocks`. كما تدعم خطوط أنابيب LTX-2.X ميزة [إعادة تحجيم التوجيه](https://huggingface.co/papers/2305.08891) (guidance rescaling) للمساعدة في تقليل الإفراط في التعرض للضوء (over-exposure)، والذي قد يكون مشكلة عند ضبط مقاييس التوجيه على قيم عالية. ```py 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 حساسة لأسلوب صياغة الأوامر. راجع [دليل صياغة الأوامر الرسمي](https://ltx.io/model/model-blog/prompting-guide-for-ltx-2) للحصول على توصيات حول كيفية كتابة أمر جيد. كما يمكن تحسين جودة العينات باستخدام تعزيز الأوامر، حيث تُعزَّز الأوامر المُدخلة باستخدام مُشفِّر النص الخاص بالخطوة (وهو نموذج [Gemma 3](https://huggingface.co/google/gemma-3-12b-it-qat-q4_0-unquantized) افتراضيًا) بناءً على أمر نظام. يجب أن يكون مكوّن `processor` الاختياري في الخطوة حاضرًا لاستخدام تعزيز الأوامر. فعّله باستخدام `enable_prompt_enhancement=True` و`system_prompt` (اختياري، ويتوافق مع خطوط Lightricks المرجعية): ```py 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`](https://huggingface.co/Lightricks/LTX-2.5-Diffusers) كلا التحوّليين: التحوّلي **المُقطّر** DiT الموجود في `transformer/`، وهو ما يشير إليه `model_index.json`، والتحوّلي DiT الكامل/SFT الموجود في `transformer_full/`، والذي يجب تحميله بشكل صريح (انظر [التحوّلي الكامل / SFT](#full--sft-transformer)). تم تكوين `scheduler/` في المستودع لنقطة الفحص المُقطّرة (`use_dynamic_shifting=False`، `shift_terminal=None`) بحيث يُستخدم جدول sigma الخاص به كما هو مُعطى بالضبط. كما أن كل ما يحتاجه [التوليد على مرحلتين](#two-stage-generation-for-ltx-25) مُشغّل هناك أيضاً: مجلد فرعي `latent_upsampler/` وLoRA المُقطّر للمرحلة 2، `ltx-2.5-22b-distilled-lora-450-bf16.safetensors`، في جذر المستودع. يعتمد الاستدلال المُقطَّر على جدول صيغ صريح بدلاً من عدد الخطوات، ويُنفَّذ دون توجيه (`guidance_scale=1.0`، لذا لا يُستخدم `negative_prompt`). إن مررت `num_inference_steps` بدلاً من ذلك، فستمنح النموذج جدولاً خطياً عاماً وستتسبب في خسارة الجودة بصمت: ```py 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 في الأمر، لأن المحوّل مُقطّر بالفعل؛ وهذا هو [إنشاء نقطة تحقق مُقطّرة](#distilled-checkpoint-generation) بأوزان LTX-2.5. - **المرحلة 1 الكاملة/التدريب الدقيق + المرحلة 2 المستخلصة عبر LoRA** — [التوليد على مرحلتين](#two-stages-generation) كما هو موضح في أعلى هذه الصفحة، باستخدام `transformer_full/` وLoRA المرفقة. راجع [ما يلي](#stage-2-with-the-distilled-lora) لمعرفة ما يتغير. تعمل المرحلة 1 عند نصف الدقة المستهدفة، ثم يضاعف مُوسِّع الدقة هذه القيمة، وتُحسّن المرحلة 2 النتيجة عند الدقة الكاملة — للفيديو *والصوت* معًا، حيث يُعاد توليد البذرة لكليهما من الكمونيات (latents) الخاصة بالمرحلة 1 عند `noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0]`. يجب أن تكون الارتفاع والعرض قابلين للقسمة على 64، لأن المرحلة 1 تُنصّف كل محور ولا بد أن تستقر على الشبكة المكانية الخاصة بـ VAE. ```py 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", ) ``` عندما يأتي الطول من [رأس المدة](#automatic-duration-for-ltx-25) بدلاً من `num_frames` صريح، دع المرحلة 1 تتخذ القرار وتستعيد الطول المحقق من متغيراتها الكامنة (`[B, C, F, H, W]`) قبل تشغيل المرحلة 2، بدلاً من التنبؤ مرة ثانية: ```py num_frames = (video_latent.shape[2] - 1) * pipe.vae_temporal_compression_ratio + 1 ``` #### المرحلة 2 باستخدام LoRA المُقطّر لتنفيذ [التوليد على مرحلتين](#two-stages-generation) بدلاً من ذلك — DiT كامل/SFT للمرحلة 1، وLoRA مُقطّر للمرحلة 2 — ابنِ خط الأنابيب كما في [المحوّل الكامل / SFT](#full--sft-transformer) وولّد كامنات المرحلة 1 باستخدام ذلك المكدس التوجيهي. ثم يختلف أمران عن LTX-2.0/2.3. إذ يقيم LoRA في مستودع diffusers نفسه بدلاً من كونه بجانب الأوزان الأصلية، وتنعكس طريقة قلب المجدول: يأتي LTX-2.5 مع إعداد مجدول *مُقطّر*، لذا فإن المرحلة 1 هي التي فعّلت الإزاحة الديناميكية، وتُطفئ المرحلة 2 ذلك مجدداً. ```py 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](/docs/diffusers/v0.43.0/ar/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video)). وهو ما تستخدمه خطوط الأنابيب لفك الترميز، لذا فإن كل مقتطف أعلاه يستخدمه بالفعل، وهو الوحيد من الاثنين الذي يدعم التقطيع (`pipe.vae.enable_tiling()`)، وهو ما يجعل عادةً ملاءمة الدقة العالية ممكنة. - `diffusion_decoder/` — [LTX2VideoDiffusionDecoderModel](/docs/diffusers/v0.43.0/ar/api/models/ltx2_diffusion_decoder#diffusers.LTX2VideoDiffusionDecoderModel). وهو نموذج انتشار بحد ذاته وليس مكوّنًا في خط المعالجة، لذا لا يُمرَّر كـ`vae`: شغّل خط المعالجة باستخدام `output_type="latent"` ثم مرّر الكمونيات إلى [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline). تمر عملية الترميز دائمًا عبر `vae/`، لذا لا تتأثر شروط الصورة أو الفيديو بالاختيار. يحدث تغييران عند فك الترميز باستخدام مُفكّك التشتت. كما أن `output_type="latent"` يتخطى مُصنّع الصوت أيضاً، لذا يعود الصوت على شكل كامنات ويجب إكماله يدوياً، ومعالج NATTEN مطلوب فعلياً عند دقات الفيديو: ```py 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", ) ``` لدمج هذا مع [التوليد على مرحلتين](#two-stage-generation-for-ltx-25)، اطلب من *المرحلة 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](/docs/diffusers/v0.43.0/ar/api/models/ltx2_diffusion_decoder#diffusers.LTX2VideoDiffusionDecoderModel) لمعرفة واجهات الانتباه الخلفية، وتفاصيل التقطيع، وبقية سلوك فك الترميز. ### تحويلة كاملة / تحويل مُدرب `transformer_full/` غير مُشار إليه في `model_index.json`، لذا حمّله صراحةً. كما أنه يحتاج إلى مُجدول مختلف ومجموعة توجيه حقيقية: `scheduler/` المرفق مُهيأ للنقطة الفاحصة المُقطّرة، والقيم الافتراضية للتوجيه هي قيم عامة من حقبة LTX-2.0 تُبقي تشغيل LTX-2.5 SFT مرئيًا دون توجيه كافٍ دون رفع أي تنبيه. توصيات [Multimodal Guidance](#multimodal-guidance) تنطبق هنا دون تغيير، بما في ذلك STG على الكتلة `28`: ```py 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، حيث يعمل نفس نقطة التفتيش لمشفّر النص كمعزّز (انظر [تعزيز الأوامر](#prompt-enhancement) أعلاه)، لم يتم تدريب مشفّر النص المُحسَّن في 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=` صريحاً للتجاوز: ```py 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` تلقائيًا افتراضيًا** — احذفه وسيختار النموذج الطول: ```py video, audio = pipe(prompt=prompt, output_type="np", return_dict=False) ``` لضبط الطول بنفسك، مرّر `num_frames` بشكل صريح. فالعدد الصحيح يتفوق دائمًا على الرأس: ```py 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` لتقييد التنبؤ. يتم ضبط التنبؤ الخام ضمن النطاق، ثم تحويله إلى إطارات: ```py 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`. يُستخدم أقرب نقطة في الشبكة ويُسجَّل تحذير، لذا قد تقع الطول المُعاد خارج الحدود الضيقة جدًا. لفحص تنبؤ دون توليد فيديو، استدعِ الرأس مباشرةً. كل ما يحتاجه متاح: ```py 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`، بينما يتبع طول الصوت، و[رأس المدة](#automatic-duration-for-ltx-25)، والفيديو المُعاد إلى `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`](https://huggingface.co/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` وحده هو الذي يحرّك التأثير. ```py 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 إطارًا في الثانية) ولا يتغير سوى إيقاع الحركة. في [التوليد على مرحلتين](#two-stage-generation-for-ltx-25)، مرّر نفس قيمة `motion_speed` إلى **المرحلتين**. تعيد المرحلة 2 إزالة الضوضاء من الفيديو، وسيؤدي تشغيلها على محور الزمن الحقيقي إلى إلغاء تأثير الحركة البطيئة. يقوم [المحرك المرجعي](https://huggingface.co/Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control/blob/main/distilled_speed_demo.py) بالشيء نفسه عن طريق تغليف كائن المرحلة الذي تشترك فيه كلتا المرحلتين. `motion_speed` هو أيضًا مدخل من مدخلات الوحدات النمطية الخاصة بـ LTX-2 / LTX-2.5، ويتم تمريره إلى خط الأنابيب النمطي بالطريقة نفسها. ### LTX-2.5 المعياري يتوفر LTX-2.5 أيضًا كخط أنابيب معياري. يستخدم مجموعة الكتل الافتراضية فاحص التشتت ويتنبأ بمدة الفيديو عند إغفال `num_frames`. يطبّق التوجيه بشكل منفصل على الفيديو والصوت من خلال مكوّني `guider` و`audio_guider`. راجع [LTX2Guidance](/docs/diffusers/v0.43.0/ar/api/modular_diffusers/guiders#diffusers.LTX2Guidance) لمعرفة معاملات التوجيه المتاحة. بشكل افتراضي، سيحمّل خط الأنابيب المعياري معزّز المعالج ومعالجه من مستودع [google/gemma-4-E2B-it](https://huggingface.co/google/gemma-4-E2B-it). فيما يلي مثال معياري لتحويل النص إلى فيديو: ```py 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: ```py 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](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2AutoBlocks)، [LTX25AutoBlocks](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX25AutoBlocks)). ### التصيير الدقيق للتشتت (DFR) لـ LTX-2.5 `LTX2DFRPipeline` يقدّم زمن التنفيذ مقابل دقة التفاصيل. كل استدعاء لـ`__call__` هو **مرحلة إزالة ضوضاء واحدة** عند `height` × `width`: فهي تولّد الفيديو بالإضافة إلى **فتحات إطارات أساسية** بإطار بكسل واحد إضافي، أو تعيد إزالة الضوضاء عن الكمونيات المُدخلة المُستمدّة من تلك الفتحات. يركّب المستدعون المراحل بالطريقة ذاتها كما في خطوط أنابيب LTX ذات المرحلتين الأخرى — هذه الخط، [LTX2LatentUpsamplePipeline](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2LatentUpsamplePipeline)، ثم هذه الخط مرة أخرى، ثم [LTX2DFRTemporalRefinePipeline](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.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. ```py 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](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.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()](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.rebuild_epilogue_keyframes)؛ لا تقم أبداً بالتوسيع الكامن لإطارات الخاتمة)، ثم: ```py 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](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline). ```py 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2.py#L209) **المعاملات:** transformer ([LTXVideoTransformer3DModel](/docs/diffusers/v0.43.0/ar/api/models/ltx_video_transformer3d#diffusers.LTXVideoTransformer3DModel)) : بنية Transformer شرطية لإزالة الضوضاء من كامنات الفيديو المُرمّزة. scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : مُجدوِل يُستخدم بالاقتران مع `transformer` لإزالة الضوضاء من كامنات الصورة المُرمَّزة. vae ([AutoencoderKLLTXVideo](/docs/diffusers/v0.43.0/ar/api/models/autoencoderkl_ltx_video#diffusers.AutoencoderKLLTXVideo)) : نموذج الترميز التحويلي التبايني (VAE) لتشفير الصور وفك تشفيرها إلى التمثيلات الكامنة ومنها. text_encoder (`T5EncoderModel`) : [T5](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5EncoderModel)، وتحديداً النسخة [google/t5-v1_1-xxl](https://huggingface.co/google/t5-v1_1-xxl). tokenizer (`CLIPTokenizer`) : مُقسِّم من الفئة [CLIPTokenizer](https://huggingface.co/docs/transformers/en/model_doc/clip#transformers.CLIPTokenizer). tokenizer (`T5TokenizerFast`) : مُرمِّز ثانٍ من الفئة [T5TokenizerFast](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5TokenizerFast). connectors (`LTX2TextConnectors`) : مجموعة من وصلات النص المستخدمة لتكييف حالات المُشفِّر النصي المخفية لكلٍّ من فرعي الفيديو والصوت. خط أنابيب لتوليد الفيديو من النص. مرجع: https://github.com/Lightricks/LTX-Video #### __call__[[diffusers.LTX2Pipeline.__call__]] ```python __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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2.py#L929) **المعاملات:** 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](https://huggingface.co/papers/2207.12598). يُعرَّف `guidance_scale` على أنه `w` من المعادلة 2. في [Imagen Paper](https://huggingface.co/papers/2205.11487). يتم تفعيل مقياس التوجيه عن طريق تعيين `guidance_scale > 1`. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنص `prompt`، وعادةً على حساب انخفاض جودة الصورة. يُستخدم لنمط الفيديو (يوجد قيمة منفصلة `audio_guidance_scale` لنمط الصوت). stg_scale (`float`, *اختياري*, القيمة الافتراضية `0.0`) : مقياس التوجيه للفيديو للتوجيه المكاني-الزمني (STG)، المقترح في [Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling](https://arxiv.org/abs/2411.18664). يستخدم 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](https://huggingface.co/papers/2305.08891) `guidance_scale` is defined as `φ` in equation 16. of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). 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](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا. 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](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` أو `np.array`. return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع `~pipelines.ltx.LTX2PipelineOutput` بدلاً من tuple عادي. attention_kwargs (`dict`، *اختياري*) : قاموس kwargs يُمرَّر إلى `AttentionProcessor` إذا تم تحديده، كما هو معرَّف تحت `self.processor` في [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py). 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` حيث يكون العنصر الأول قائمة تحتوي على الصور المولّدة. الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد. أمثلة: ```py >>> 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2.py#L367) **المعاملات:** 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2.py#L574) يعزز `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]] ```python 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/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_image2video.py#L229) خط أنابيب لتوليد الفيديو من الصور. مرجع: https://github.com/Lightricks/LTX-Video TODO #### __call__[[diffusers.LTX2ImageToVideoPipeline.__call__]] ```python __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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_image2video.py#L983) **المعاملات:** 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](https://huggingface.co/papers/2207.12598). يُعرَّف `guidance_scale` على أنه `w` من المعادلة 2. في [Imagen Paper](https://huggingface.co/papers/2205.11487). يتم تفعيل مقياس التوجيه عن طريق تعيين `guidance_scale > 1`. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنص `prompt`، وعادةً على حساب انخفاض جودة الصورة. يُستخدم لنمط الفيديو (يوجد قيمة منفصلة `audio_guidance_scale` لنمط الصوت). stg_scale (`float`, *اختياري*, القيمة الافتراضية `0.0`) : مقياس التوجيه للفيديو للتوجيه المكاني-الزمني (STG)، المقترح في [Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling](https://arxiv.org/abs/2411.18664). يستخدم 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](https://huggingface.co/papers/2305.08891) `guidance_scale` is defined as `φ` in equation 16. of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). 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](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا. 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](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` أو `np.array`. return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع `~pipelines.ltx.LTX2PipelineOutput` بدلاً من tuple عادي. attention_kwargs (`dict`، *اختياري*) : قاموس kwargs يُمرَّر إلى `AttentionProcessor` إذا تم تحديده، كما هو معرَّف تحت `self.processor` في [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py). 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` حيث يكون العنصر الأول قائمة تحتوي على الصور المولّدة. الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد. أمثلة: ```py >>> 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_image2video.py#L372) **المعاملات:** 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_image2video.py#L580) يعزز `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]] ```python 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/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L266) خط أنابيب لتوليد الفيديو يتيح إدراج شروط الصور في أجزاء اختيارية من الفيديو. مرجع: https://github.com/Lightricks/LTX-Video TODO #### __call__[[diffusers.LTX2ConditionPipeline.__call__]] ```python __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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L1348) **المعاملات:** 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](https://huggingface.co/papers/2207.12598). يُعرَّف `guidance_scale` على أنه `w` من المعادلة 2. في [Imagen Paper](https://huggingface.co/papers/2205.11487). يتم تفعيل مقياس التوجيه عن طريق تعيين `guidance_scale > 1`. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنص `prompt`، وعادةً على حساب انخفاض جودة الصورة. يُستخدم لنمط الفيديو (يوجد قيمة منفصلة `audio_guidance_scale` لنمط الصوت). stg_scale (`float`, *اختياري*, القيمة الافتراضية `0.0`) : مقياس التوجيه للفيديو للتوجيه المكاني-الزمني (STG)، المقترح في [Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling](https://arxiv.org/abs/2411.18664). يستخدم 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](https://huggingface.co/papers/2305.08891) `guidance_scale` is defined as `φ` in equation 16. of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). 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](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا. 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](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` أو `np.array`. return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع `~pipelines.ltx.LTX2PipelineOutput` بدلاً من tuple عادي. attention_kwargs (`dict`، *اختياري*) : قاموس kwargs يُمرَّر إلى `AttentionProcessor` إذا تم تحديده، كما هو معرَّف تحت `self.processor` في [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py). 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` حيث يكون العنصر الأول قائمة تحتوي على الصور المولّدة. الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد. أمثلة: ```py >>> 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L964) **المعاملات:** 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L419) **المعاملات:** 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L627) يعزز `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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L1071) جهّز كامنات الفيديو الضوضائية، مع تطبيق شروط الإطارات. تُطبَّق شروط الإطار الأول (`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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L846) **المعاملات:** 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]] ```python trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L829) **المعاملات:** start_frame (int) : رقم الإطار المستهدف للإطار الأول في التسلسل. sequence_num_frames (int) : عدد الإطارات في التسلسل. target_num_frames (int) : العدد المستهدف للإطارات في الفيديو المولّد. **يعيد:** `int` طول التسلسل المحدّث اقتصاص تسلسل الشرط إلى عدد الإطارات المسموح به. ## LTX2DFRPipeline[[diffusers.LTX2DFRPipeline]] #### diffusers.LTX2DFRPipeline[[diffusers.LTX2DFRPipeline]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L122) **المعاملات:** scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : مُجدوِل يُستخدم بالاقتران مع `transformer` لإزالة الضوضاء من كامنات الفيديو المُرمَّزة. vae ([AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/ar/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video)) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير مقاطع الفيديو إلى تمثيلات كامنة ومنها. audio_vae ([AutoencoderKLLTX2Audio](/docs/diffusers/v0.43.0/ar/api/models/autoencoderkl_audio_ltx_2#diffusers.AutoencoderKLLTX2Audio)) : نموذج VAE صوتي لتشفير وفك تشفير مطيافات الصوت. text_encoder (`Gemma3ForConditionalGeneration` أو `Gemma4UnifiedForConditionalGeneration`) : نموذج مُشفِّر للنص. tokenizer (`GemmaTokenizer` أو `GemmaTokenizerFast`) : مُجزِّئ (Tokenizer) لمُشفِّر النص. connectors (`LTX2TextConnectors`) : مجموعة من وصلات النص المستخدمة لتكييف حالات المُشفِّر النصي المخفية لكلٍّ من فرعي الفيديو والصوت. transformer ([LTX2VideoTransformer3DModel](/docs/diffusers/v0.43.0/ar/api/models/ltx2_video_transformer3d#diffusers.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](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2LatentUpsamplePipeline) مكانياً، ثم هذا الخطّ الأنابيب مجدداً بدقة كاملة مع الفتحات المُوسَّعة ومرجع IC-LoRA، ثم [LTX2DFRTemporalRefinePipeline](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.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__]] ```python __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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L1522) **المعاملات:** 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()](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.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](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.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](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput) أو `tuple` إذا كان `return_dict` هو `True`، يُعاد [LTX2DFRPipelineOutput](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput)، وإلا يُعاد `tuple` من `(video, audio, keyframes, keyframe_positions)`. الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد. مرور إزالة ضوضاء واحد عند `height` × `width`. قم بتجميع المراحل في المستدعي: هذا الخط الأنابيب بدقة نصفية، ثم توسعة مكانية، ثم هذا الخط الأنابيب مرة أخرى مع `latents` / `keyframes_latents` / `reference_latents`، ثم [LTX2DFRTemporalRefinePipeline](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2DFRTemporalRefinePipeline) لكل جولة زمنية. أمثلة: ```py >>> 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L1225) **المعاملات:** 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](/docs/diffusers/v0.43.0/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) وتتخذ خطوة Euler كما هي. أما تحسين الزمن فيستبدلها بـ `LTXEulerAncestralRFScheduler` (`eta=0.5`)؛ إذ تعيد تلك الخطوة إضافة الضوضاء إلى كل رمز، لذا يُعاد تطبيق مزج الشرط بعدها وإلا تآكلت نقاط التثبيت عند الفواصل بقوة 0.95. #### encode_conditions[[diffusers.LTX2DFRPipeline.encode_conditions]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L1189) معالجة الشروط الإطارية مسبقاً وتشفيرها باستخدام VAE، مع تحديد موضعها حسب الإطار البكسلي. يعيد `(pixel_frame_index, latent, strength, num_pixel_frames)` لكل شرط، جاهزةً لـ `condition_latents` في [prepare_latents()](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.prepare_latents). يُبقي الترميز منفصلاً عن التوزيع لأن جولات التحسين الزمني تضاعف موضع الشرط بمعامل `2 ** round` وتعيد ضبطه لكل بلاطة، ولا ينبغي إعادة ترميز نفس الإطار الثابت مرةً واحدة لكل بلاطة من أجل ذلك. المؤشر المُعاد يقع على شبكة البكسل الخاصة بـ`num_frames`؛ ونقله إلى لوحة محسّنة هو من مسؤولية المُستدعي. #### encode_prompt[[diffusers.LTX2DFRPipeline.encode_prompt]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L529) **المعاملات:** 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L389) يعزز `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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L886) **المعاملات:** 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L707) **المعاملات:** 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]] ```python rebuild_epilogue_keyframes(keyframe_latents: Tensor, decode_timestep: float, decode_noise_scale: float, seed: int, device: device, dtype: dtype) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L1454) **المعاملات:** 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]] ```python trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L689) **المعاملات:** start_frame (int) : رقم الإطار المستهدف للإطار الأول في التسلسل. sequence_num_frames (int) : عدد الإطارات في التسلسل. target_num_frames (int) : العدد المستهدف للإطارات في الفيديو المولّد. **يعيد:** `int` طول التسلسل المحدّث اقتصاص تسلسل الشرط إلى عدد الإطارات المسموح به. ## LTX2DFRTemporalRefinePipeline[[diffusers.LTX2DFRTemporalRefinePipeline]] #### diffusers.LTX2DFRTemporalRefinePipeline[[diffusers.LTX2DFRTemporalRefinePipeline]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L151) **المعاملات:** scheduler (`LTXEulerAncestralRFScheduler`) : مُجدول أويلر الأسلاف في معادلة التدفق المُصحَّح. أنشئه باستخدام `eta=0.5` ليتطابق مع الوصفة الزمنية لـ DFR. vae ([AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/ar/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video)) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير مقاطع الفيديو إلى تمثيلات كامنة ومنها. audio_vae ([AutoencoderKLLTX2Audio](/docs/diffusers/v0.43.0/ar/api/models/autoencoderkl_audio_ltx_2#diffusers.AutoencoderKLLTX2Audio)) : نموذج VAE صوتي لتشفير وفك تشفير مطيافات الصوت. text_encoder (`Gemma3ForConditionalGeneration` أو `Gemma4UnifiedForConditionalGeneration`) : نموذج مُشفِّر للنص. tokenizer (`GemmaTokenizer` أو `GemmaTokenizerFast`) : مُجزِّئ (Tokenizer) لمُشفِّر النص. connectors (`LTX2TextConnectors`) : مجموعة من وصلات النص المستخدمة لتكييف حالات المُشفِّر النصي المخفية لكلٍّ من فرعي الفيديو والصوت. transformer ([LTX2VideoTransformer3DModel](/docs/diffusers/v0.43.0/ar/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel)) : بنية Transformer شرطية لإزالة الضوضاء من كامنات الفيديو المُرمّزة. vocoder (`LTX2Vocoder` أو `LTX2VocoderWithBWE`) : مُصوِّت (Vocoder) لتحويل مطيافات ميل (mel spectrograms) إلى موجات صوتية. temporal_latent_upsampler (`LTX2LatentUpsamplerModel`) : مُوسِّع كامن زمني بمعامل x2 يُطبَّق في بداية الجولة. جولة واحدة من تحسين DFR الزمني: استيفاء اللوحة x2 في الزمن، وتقسيمها عند حدود الإطارات المفتاحية، وإزالة الضوضاء الأصلية لكل قطعة، ثم دمجها عبر إسقاط المقدمة الخاصة بالقطعة اللاحقة، وأخيرًا دمج حقيبة الإطار المفتاحي المحمول. المجدول هو `LTXEulerAncestralRFScheduler` (الافتراضي `eta=0.5`). تبقى المرحلة 1 / المرحلة 2 / الخاتمة المكانية على [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) عبر [LTX2DFRPipeline](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2DFRPipeline). استدعِ هذا الخطّ مرة واحدة لكل جولة؛ يقوم المستدعي بالتكرار لـ 2x / 4x. القيم الواردة من `latents` / `keyframes_latents` / `audio_latents` خام (غير مُعايرة)، بما يتوافق مع [LTX2Pipeline](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2Pipeline). يجب أن تكون `keyframe_positions` هي الموضعات المُعادَة من المرور السابق — إذ لا يمكن إعادة اشتقاقها من `num_frames` الأصلية بعد تنفيذ جولة. #### __call__[[diffusers.LTX2DFRTemporalRefinePipeline.__call__]] ```python __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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L1349) **المعاملات:** 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](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.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](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput) أو `tuple` إذا كان `return_dict` هو `True`، يُعاد [LTX2DFRPipelineOutput](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput)، وإلا يُعاد `tuple` من `(video, audio, keyframes, keyframe_positions)`. نفّذ جولة واحدة من التحسين الزمني. أمثلة: ```py >>> 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L1138) **المعاملات:** 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](/docs/diffusers/v0.43.0/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) وتتخذ خطوة Euler كما هي. أما تحسين الزمن فيستبدلها بـ `LTXEulerAncestralRFScheduler` (`eta=0.5`)؛ إذ تعيد تلك الخطوة إضافة الضوضاء إلى كل رمز، لذا يُعاد تطبيق مزج الشرط بعدها وإلا تآكلت نقاط التثبيت عند الفواصل بقوة 0.95. #### encode_conditions[[diffusers.LTX2DFRTemporalRefinePipeline.encode_conditions]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L1101) معالجة الشروط الإطارية مسبقاً وتشفيرها باستخدام VAE، مع تحديد موضعها حسب الإطار البكسلي. يعيد `(pixel_frame_index, latent, strength, num_pixel_frames)` لكل شرط، جاهزةً لـ `condition_latents` في [prepare_latents()](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.prepare_latents). يُبقي الترميز منفصلاً عن التوزيع لأن جولات التحسين الزمني تضاعف موضع الشرط بمعامل `2 ** round` وتعيد ضبطه لكل بلاطة، ولا ينبغي إعادة ترميز نفس الإطار الثابت مرةً واحدة لكل بلاطة من أجل ذلك. المؤشر المُعاد يقع على شبكة البكسل الخاصة بـ`num_frames`؛ ونقله إلى لوحة محسّنة هو من مسؤولية المُستدعي. #### encode_prompt[[diffusers.LTX2DFRTemporalRefinePipeline.encode_prompt]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L470) **المعاملات:** 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L828) **المعاملات:** 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L648) **المعاملات:** 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]] ```python trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L630) **المعاملات:** start_frame (int) : رقم الإطار المستهدف للإطار الأول في التسلسل. sequence_num_frames (int) : عدد الإطارات في التسلسل. target_num_frames (int) : العدد المستهدف للإطارات في الفيديو المولّد. **يعيد:** `int` طول التسلسل المحدّث اقتصاص تسلسل الشرط إلى عدد الإطارات المسموح به. #### upsample_latents[[diffusers.LTX2DFRTemporalRefinePipeline.upsample_latents]] ```python upsample_latents(latents: Tensor, upsampler: LTX2LatentUpsamplerModel) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L1090) شغّل `upsampler` على الكمونيات المعيارية، مع المرور ذهاباً وإياباً عبر فضاء الكمون الخام الخاص بـ VAE كما يتوقع ذلك. ## LTX2DFRPipelineOutput[[diffusers.LTX2DFRPipelineOutput]] #### diffusers.LTX2DFRPipelineOutput[[diffusers.LTX2DFRPipelineOutput]] ```python diffusers.LTX2DFRPipelineOutput(frames: Tensor, audio: Tensor, keyframes: typing.Optional[torch.Tensor] = None, keyframe_positions: list[int] | None = None) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_output.py#L27) **المعاملات:** 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]] ```python diffusers.LTX2LatentUpsamplePipeline(vae: AutoencoderKLLTX2Video, latent_upsampler: LTX2LatentUpsamplerModel) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_latent_upsample.py#L104) #### __call__[[diffusers.LTX2LatentUpsamplePipeline.__call__]] ```python __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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_latent_upsample.py#L264) **المعاملات:** 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](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا. output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة الناتجة عن عملية التوليد. اختر بين [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` أو `np.array`. return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع `~pipelines.ltx.LTXPipelineOutput` بدلاً من tuple عادي. **يعيد:** `~pipelines.ltx.LTXPipelineOutput` أو `tuple` إذا كان `return_dict` هو `True`، يُعاد `~pipelines.ltx.LTXPipelineOutput`، وإلا يُعاد `tuple` يكون عنصره الأول هو الفيديو المُوسَّع. الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد. أمثلة: ```py >>> 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]] ```python adain_filter_latent(latents: Tensor, reference_latents: Tensor, factor: float = 1.0) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_latent_upsample.py#L168) **المعاملات:** 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]] ```python tone_map_latents(latents: Tensor, compression: float) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_latent_upsample.py#L196) **المعاملات:** 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]] ```python diffusers.LTX2VideoDiffusionDecodePipeline(diffusion_decoder: LTX2VideoDiffusionDecoderModel, scheduler, vae: AutoencoderKLLTX2Video = None) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_diffusion_decode.py#L27) **المعاملات:** diffusion_decoder ([LTX2VideoDiffusionDecoderModel](/docs/diffusers/v0.43.0/ar/api/models/ltx2_diffusion_decoder#diffusers.LTX2VideoDiffusionDecoderModel)) : مُفكّك الفيديو الانتشاري. scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : المجدول الذي يقود خطوات إزالة الضوضاء في المُفكِّك. vae ([AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/ar/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video)، *اختياري*) : يُستشار فقط من أجل الإحصاءات الكامنة المستخدمة في إزالة التطبيع. عند إهماله، يعود خط المعالجة إلى القيم الافتراضية الخاصة بـ LTX-2، لذا لا يحتاج سير عمل فك الترميز فقط إلى تحميل مُشفِّر-مفكِّك ثانٍ. فكّ تشفير كامنات فيديو LTX-2 باستخدام مُفكّك الانتشار المُقدَّم في LTX-2.5. على عكس مُفكِّك الالتفاف، فإن هذا المُفكِّك هو في حد ذاته نموذج انتشار صغير: فهو يُزيل الضوضاء من البكسلات مشروطًا بحجم سياق مبني من الكمونيات، لذا فهو يحتاج إلى مُجدوِل ومولِّد. اقرنه بأي مسار تنفيذ لـ LTX-2 يعمل مع `output_type="latent"`، مع تمرير `denormalize=False` لأن ذلك المسار طبّق بالفعل إحصاءات الكمونيات. #### __call__[[diffusers.LTX2VideoDiffusionDecodePipeline.__call__]] ```python __call__(latents: Tensor, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str = 'pil', return_dict: bool = True, denormalize: bool = True) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_ltx2_diffusion_decode.py#L79) **المعاملات:** 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/duration_head.py#L81) **المعاملات:** 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]] ```python forward(video_tokens: typing.Optional[torch.Tensor] = None, audio_tokens: typing.Optional[torch.Tensor] = None) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/duration_head.py#L134) **المعاملات:** 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/duration_head.py#L172) **المعاملات:** 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]] ```python diffusers.pipelines.ltx2.LTX2PipelineOutput(frames: Tensor, audio: Tensor) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ltx2/pipeline_output.py#L9) **المعاملات:** 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/ltx2/modular_pipeline.py#L26) ModularPipeline لـ LTX-2 (توليد مشترك للفيديو والصوت). ## LTX2AutoBlocks[[diffusers.LTX2AutoBlocks]] #### diffusers.LTX2AutoBlocks[[diffusers.LTX2AutoBlocks]] ```python diffusers.LTX2AutoBlocks() ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/ltx2/modular_blocks_ltx2.py#L1761) كتل تلقائية لنموذج 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]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/ltx2/modular_pipeline.py#L125) ModularPipeline لـ LTX-2.5 (توليد مشترك للفيديو والصوت). مماثل لـ [LTX2ModularPipeline](/docs/diffusers/v0.43.0/ar/api/pipelines/ltx2#diffusers.LTX2ModularPipeline) باستثناء أن كتله الافتراضية تقوم بفك الترميز باستخدام مُفك ترميز الفيديو الانتشاري، وهو الافتراضي الأصلي من LTX-2.5 فصاعدًا. يتم توجيه نقطة التفتيش إلى هنا عبر `modular_model_index.json`. ## LTX25AutoBlocks[[diffusers.LTX25AutoBlocks]] #### diffusers.LTX25AutoBlocks[[diffusers.LTX25AutoBlocks]] ```python diffusers.LTX25AutoBlocks() ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/ltx2/modular_blocks_ltx25.py#L215) كتل تلقائية لنموذج 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`): موجة الصوت المولّدة.