Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: run LTX-2.5 on the Video page (#13463)
Daniel Hane4609246ebd5
diff --git a/studio/backend/core/inference/diffusion_content.py b/studio/backend/core/inference/diffusion_content.pyindex aec30261ac9..761355b9c1e 100644--- a/studio/backend/core/inference/diffusion_content.py+++ b/studio/backend/core/inference/diffusion_content.py@@ -46,6 +46,7 @@ SAME_ARCH_VARIANTS: dict[str, frozenset[str]] = {_VIDEO_FAMILIES = frozenset({"ltx-2",+ "ltx-2.5","wan2.2-ti2v-5b","wan2.2-t2v-a14b","wan2.1-t2v-1.3b",@@ -332,13 +333,12 @@ def _match_dit(s: dict[str, list[int]]) -> Optional[CheckpointInfo]:or "audio_caption_projection" in tops):if is_ltx25_dit_keys(keys):- # No family: the ltx-2 name must not revive it.+ # Its own family: the LTX-2 assembly cannot build this DiT (no FFN bias), so the name never routes it there.return CheckpointInfo(ROLE_DIT,- None,- None,- "an LTX-2.5 audio-video diffusion transformer, which Studio does not support yet "- "(use LTX-2.3 for now)",+ LTX25_VARIANT,+ family_page(LTX25_VARIANT),+ "an LTX-2.5 audio-video diffusion transformer","diffusers" if "proj_in" in tops else "comfy",LTX25_VARIANT,)diff --git a/studio/backend/core/inference/diffusion_preview_factors.py b/studio/backend/core/inference/diffusion_preview_factors.pyindex 15bafe57952..9f79a0ef454 100644--- a/studio/backend/core/inference/diffusion_preview_factors.py+++ b/studio/backend/core/inference/diffusion_preview_factors.py@@ -21,6 +21,8 @@ FAMILY_FACTORS = {"hunyuanvideo-1.5": "hv15","hunyuanvideo-1.5-720p": "hv15","ltx-2": "ltx2",+ # 2.5 keeps the 2.3 conv VAE encoder (byte-identical weights), so the same latent space.+ "ltx-2.5": "ltx2",}FACTORS: dict = {diff --git a/studio/backend/core/inference/diffusion_transformer_quant.py b/studio/backend/core/inference/diffusion_transformer_quant.pyindex ed4c1d731a0..0cfd7cf1c23 100644--- a/studio/backend/core/inference/diffusion_transformer_quant.py+++ b/studio/backend/core/inference/diffusion_transformer_quant.py@@ -148,6 +148,7 @@ _INT8_FAMILY_EXCLUDE_NAME_TOKENS: dict[str, tuple[str, ...]] = {"minimax-h3": _MINIMAX_H3_INT8_EXCLUDES,"ltx-2": _LTX2_INT8_EXCLUDES,"ltx-2.3": _LTX2_INT8_EXCLUDES, # same audiovisual DiT+ "ltx-2.5": _LTX2_INT8_EXCLUDES, # the 2.3 DiT less the video FFN bias}diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.pyindex c10bd6a1282..b99cdfedac6 100644--- a/studio/backend/core/inference/video.py+++ b/studio/backend/core/inference/video.py@@ -200,8 +200,12 @@ from .video_families import (VIDEO_GENERATION_BUSY_MSG,VIDEO_MODEL_CHANGED_MSG,VIDEO_NOT_LOADED_MSG,- assert_local_pipeline_not_ltx25,+ LTX_FAMILIES,+ assert_local_pipeline_family,assert_ltx_pick_supported,+ assert_supported_ltx_version,+ ltx_family_by_name,+ local_ltx_pipeline_family,pipeline_available_video_families,VideoFamily,default_video_generation_params,@@ -273,6 +277,9 @@ _TRUSTED_NON_GGUF_VIDEO_REPOS = frozenset("lightricks/ltx-2","lightricks/ltx-2.3","lightricks/ltx-2.3-fp8",+ # LTX-2.5: the Diffusers pack (safetensors + configs, no remote code) and the split single-file repo.+ "lightricks/ltx-2.5-diffusers",+ "lightricks/ltx-2.5",# Wan2.2 official diffusers base repos: safetensors-only, no remote code."wan-ai/wan2.2-ti2v-5b-diffusers","wan-ai/wan2.2-t2v-a14b-diffusers",@@ -1088,11 +1095,6 @@ def assert_first_frame_pipeline_available(fam: VideoFamily) -> None:)-def _refuse_local_ltx25_pipeline(repo_id: str, gguf_filename: Optional[str]) -> None:- if not gguf_filename:- assert_local_pipeline_not_ltx25(repo_id)--def _detect_load_family(repo_id: str,gguf_filename: Optional[str],@@ -1102,10 +1104,29 @@ def _detect_load_family() -> Optional[VideoFamily]:# An explicit pipeline load never opens the filename, so it must not vouch for the repo.ltx_file = None if str(model_kind or "").strip().lower() == "pipeline" else gguf_filename- _refuse_local_ltx25_pipeline(repo_id, ltx_file)- fam = _resolve_load_family(repo_id, gguf_filename, family_override, display_repo_id)- # After resolution: family_override="ltx-2" must not load LTX-2.5, and a non-LTX pick never trips on the name.- assert_ltx_pick_supported(fam.name if fam else None, repo_id, ltx_file, display_repo_id)+ fam, by_content = _resolve_load_family_with_source(+ repo_id, gguf_filename, family_override, display_repo_id, ltx_file = ltx_file+ )+ if fam is not None and fam.name == "ltx-2.5" and not ltx_file:+ from .video_ltx25 import LTX25_SINGLE_FILE_REPO, is_ltx25_single_file_base+ if is_ltx25_single_file_base(repo_id):+ # No model_index.json there: a pipeline load would stage ~29 GB of companions and then fail.+ raise ValueError(+ f"'{repo_id}' ships LTX-2.5 as single files, not a Diffusers pipeline. Pick one of its DiT files "+ f"(diffusion_models/), or load {LTX25_SINGLE_FILE_REPO}-Diffusers."+ )+ if fam is not None and fam.name in LTX_FAMILIES:+ # A local diffusers folder's model_index.json outranks its name, as a file's header does.+ by_content = by_content or (not ltx_file and local_ltx_pipeline_family(repo_id) is not None)+ # After resolution: an LTX family never loads the other release's weights (LTX-2.5 never reaches the 2.3+ # assembly), and a release after 2.5 is refused. A local diffusers folder answers by its model_index.json.+ if not ltx_file:+ assert_local_pipeline_family(repo_id, fam.name)+ if by_content:+ # The header decided the family; only an unknown release named by the pick is still refused.+ assert_supported_ltx_version(repo_id, ltx_file, display_repo_id)+ else:+ assert_ltx_pick_supported(fam.name, repo_id, ltx_file, display_repo_id)return fam@@ -1119,8 +1140,74 @@ def _resolve_load_family(repo id first, then the picked filename -- a local directory or genericallynamed repo often carries the family token only in the checkpoint filename,and the worker must resolve the same family the validator accepted."""+ return _resolve_load_family_with_source(+ repo_id, gguf_filename, family_override, display_repo_id, ltx_file = gguf_filename+ )[0]+++def _assert_local_ltx_header_matches(+ repo_id: str, gguf_filename: Optional[str], family: str+) -> None:+ """A forced LTX family still never loads the other release's weights: a local file's header names its release."""+ from .diffusion_content import inspect_checkpoint, local_pick_file+ from .video_families import LTX25_FAMILY, wrong_ltx_family_message++ path = local_pick_file(repo_id, gguf_filename)+ if not path:+ return+ found = inspect_checkpoint(path).family+ if found in LTX_FAMILIES and found != family:+ version = "2.5" if found == LTX25_FAMILY else "2.3"+ raise ValueError(+ wrong_ltx_family_message(+ version, family, f"'{os.path.basename(path)}' (by its weights)"+ )+ )+++def _ltx25_dev_load(+ fam: Any,+ kind: str,+ gguf_filename: Optional[str],+ repo_id: Optional[str],+ display_repo_id: Optional[str] = None,+) -> bool:+ """Whether an LTX-2.5 load is the dev DiT (single stage, no latent upsampler). A pipeline load opens no single file,+ so its repo names the variant (the official pack is distilled); a single file decides by its own name first."""+ if getattr(fam, "name", None) != "ltx-2.5":+ return False+ from .video_families import ltx25_is_dev++ if kind == "pipeline":+ return ltx25_is_dev(display_repo_id, repo_id)+ return ltx25_is_dev(gguf_filename, repo_id)+++def _stop_ltx25_encoder(client: Any) -> None:+ if client is None:+ return+ try:+ client.close()+ except Exception as exc: # noqa: BLE001 -- cleanup is best-effort+ logger.warning("video.ltx25_te: could not stop a pending encoder worker: %s", exc)+++def _resolve_load_family_with_source(+ repo_id: str,+ gguf_filename: Optional[str],+ family_override: Optional[str],+ display_repo_id: Optional[str] = None,+ *,+ ltx_file: Optional[str] = None,+) -> tuple[Optional[VideoFamily], bool]:+ """``_resolve_load_family`` plus whether a local file's header decided the family."""if family_override:- return detect_video_family(repo_id, family_override)+ fam = detect_video_family(repo_id, family_override)+ if fam is not None and fam.name in LTX_FAMILIES:+ # ltx_file, not the raw filename: an explicit pipeline load never opens a child file, so its folder answers+ # by its model_index.json instead.+ _assert_local_ltx_header_matches(repo_id, ltx_file, fam.name)+ return fam, Falsefam = ((display_repo_id and detect_video_family(display_repo_id))or detect_video_family(repo_id)@@ -1133,6 +1220,14 @@ def _resolve_load_family(arch = _picked_gguf_arch(repo_id, gguf_filename)if arch:fam = detect_video_family(repo_id, override = arch)+ if fam is not None and fam.name in LTX_FAMILIES:+ # Both LTX families share the "ltx" tokens, so the release decides: a local diffusers folder by its+ # model_index.json, else the picked file's own version token, else the display / repo id.+ named = (+ local_ltx_pipeline_family(repo_id) if not ltx_file else None+ ) or ltx_family_by_name(repo_id, ltx_file, display_repo_id)+ if named is not None and named != fam.name:+ fam = detect_video_family("", override = named) or famfrom .diffusion_content import SAME_ARCH_VARIANTS, local_pick_file, resolve_family_with_content# Same layout, different model: the picked file's own name outranks its repo or folder (a Wan2.1 14B GGUF in a@@ -1154,17 +1249,18 @@ def _resolve_load_family(path = local_pick_file(repo_id, gguf_filename)if path:file_fam = detect_video_family(os.path.basename(path))- name, _ = resolve_family_with_content(+ name, by_content = resolve_family_with_content(fam.name if fam else None,path,"video",file_family = file_fam.name if file_fam else None,)if name is None:- return None+ return None, by_contentif fam is None or fam.name != name:fam = detect_video_family("", override = name)- return fam+ return fam, by_content+ return fam, Falsedef _ensure_mp4_encoder_available() -> None:@@ -1323,6 +1419,8 @@ def _note_sd_cpp_accelerator_failure(# "Not read yet", distinct from None, the real answer for a binary the installer does not own._UNREAD_ACCELERATOR = object()+# _close_pending_ltx25_encoder's default: stop the pending worker whichever load started it.+_ANY_LOAD = object()def _h3_te_canonical(repo_id: Optional[str]) -> str:@@ -1947,6 +2045,9 @@ def _video_seed_stays_resident(mib_per_gb = 1000.0**3 / (1024.0 * 1024.0)text_encoder_gb = components[1] * te_scale * dtype_scalecompanions_gb = text_encoder_gb + components[2] * vae_scale+ if getattr(fam, "name", None) == "ltx-2.5":+ from .video_ltx25 import LTX25_WORKER_RESIDENT_GB+ companions_gb += LTX25_WORKER_RESIDENT_GBmodel_dense_mib = int((denoiser_gb + companions_gb) * mib_per_gb)device_memory = settled_snapshot_device_memory(target)if reclaimable_mib > 0 and device_memory.free_mib is not None:@@ -2701,6 +2802,9 @@ class VideoBackend:self._load_token = 0self._cancel_event = threading.Event()self._active_generate_cancel: Optional[threading.Event] = None+ # (load token, client) of an LTX-2.5 Gemma 4 encoder worker whose load has not committed yet; a failed load stops+ # it.+ self._ltx25_pending_encoder: Optional[tuple[Optional[int], Any]] = None# How many unloads / superseding loads are waiting on _generate_lock to free this pipeline. A generation queued# behind the active one holds no cancel event yet, so without this fence it could win the lock after an eject# and denoise a whole new clip against a pipeline being freed. A count, so concurrent teardowns each own their@@ -2934,9 +3038,9 @@ class VideoBackend:f"repos, and local paths; '{base_repo}' is neither.")if base_repo and base_repo.strip():- # The companion supplies the text encoder / VAE, so an LTX-2.5 base is refused like an LTX-2.5 pick.+ # The companion supplies the text encoder / VAE, so it must be the picked release's own base.assert_ltx_pick_supported(fam.name, base_repo)- assert_local_pipeline_not_ltx25(base_repo)+ assert_local_pipeline_family(base_repo, fam.name)# A local base_repo loads as a full pipeline (needs model_index.json); reject a non-pipeline one here, before# the load.from core.inference.diffusion import _assert_local_base_is_pipeline@@ -2946,7 +3050,14 @@ class VideoBackend:if kind in ("gguf", "single_file")else ())- _assert_local_base_is_pipeline(base_repo, excluded_components = excluded)+ # A local copy of the split LTX-2.5 release has no model_index.json by design: its companion files beside the+ # DiTs are the base (assemble_ltx25_single_file_pipeline).+ split_ltx25_base = False+ if fam.name == "ltx-2.5" and kind in ("gguf", "single_file") and base_repo:+ from .video_ltx25 import is_ltx25_single_file_base+ split_ltx25_base = is_ltx25_single_file_base(base_repo)+ if not split_ltx25_base:+ _assert_local_base_is_pipeline(base_repo, excluded_components = excluded)if kind in ("gguf", "single_file") and not gguf_filename:raise ValueError("A gguf/single_file load needs the checkpoint filename.")local_file = Path(repo_id).expanduser().is_file()@@ -3016,7 +3127,11 @@ class VideoBackend:normalize_transformer_quant(transformer_quant)# Reject a malformed text_encoder_quant the same way. Every kind: an unsupported scheme is a bad request# regardless of whether this family has a hosted quantized encoder for it.- normalize_te_quant(text_encoder_quant)+ if normalize_te_quant(text_encoder_quant) is not None and fam.name == "ltx-2.5":+ raise ValueError(+ "LTX-2.5's Gemma 4 text encoder runs in its own worker at bf16, so a text encoder "+ "precision cannot be applied to it yet. Leave the text encoder precision unset."+ )_ensure_mp4_encoder_available()return fam@@ -3128,7 +3243,11 @@ class VideoBackend:self._cancel_event = cancel_eventself._loading = _VideoLoadingState(repo_id = repo_id,- base_repo = fam.base_repo,+ # A split LTX-2.5 single-file pick reads its companions from its own repo, not the pack.+ base_repo = resolve_video_base_repo(fam, base_repo, repo_id)+ if fam.name == "ltx-2.5"+ and resolve_video_model_kind(gguf_filename, model_kind) != "pipeline"+ else fam.base_repo,asset_repos = claimed_assets,)@@ -3192,6 +3311,13 @@ class VideoBackend:allow_network = not local_files_only,)kind = resolve_video_model_kind(kwargs.get("gguf_filename"), kwargs.get("model_kind"))+ ltx25_dev = _ltx25_dev_load(+ fam,+ kind,+ kwargs.get("gguf_filename"),+ kwargs["repo_id"],+ kwargs.get("display_repo_id"),+ )from .video_minimax_h3 import is_h3_nativeif is_h3_native(fam, kind):@@ -3210,7 +3336,7 @@ class VideoBackend:base = (kwargs["repo_id"]if kind == "pipeline"- else resolve_video_base_repo(fam, kwargs.get("base_repo"))+ else resolve_video_base_repo(fam, kwargs.get("base_repo"), kwargs.get("repo_id")))kwargs["base_repo"] = base# Before the plan: it stages the partition the file serves (transformer_ref/ for ref2va).@@ -3308,6 +3434,7 @@ class VideoBackend:h3_task = kwargs.get("h3_task"),h3_te_scheme = h3_te_scheme,local_files_only = local_files_only,+ ltx25_dev = ltx25_dev,)with self._lock:if self._load_token == token and self._loading is not None:@@ -3405,6 +3532,7 @@ class VideoBackend:h3_task = kwargs.get("h3_task"),h3_te_scheme = h3_te_scheme,local_files_only = local_files_only,+ ltx25_dev = ltx25_dev,)with self._lock:if self._load_token == token and self._loading is not None:@@ -3483,6 +3611,7 @@ class VideoBackend:h3_task = kwargs.get("h3_task"),cancel_event = cancel_event,local_files_only = local_files_only,+ ltx25_dev = ltx25_dev,)# The 2.3 assembly pulls per component from the hub id (its snapshot lacks the base VAEs), so it only gets# the warmed cache.@@ -3495,6 +3624,8 @@ class VideoBackend:# A failed/cancelled load never commits _VideoLoadState, so roll back the process-wide speed globals here# (token-scoped).self._rollback_precommit_globals(token)+ # Token-scoped: a newer LTX-2.5 load may already hold the slot with its own worker.+ self._close_pending_ltx25_encoder(token)if self._load_token != token:returnlogger.error("video.load_failed: %s", exc)@@ -4078,6 +4209,17 @@ class VideoBackend:from .gpu_arbiter import VIDEO, release_ifrelease_if(VIDEO, lambda: token is None or token == self._load_token)+ def _close_pending_ltx25_encoder(self, token: Any = _ANY_LOAD) -> None:+ """Stop an LTX-2.5 encoder worker whose load never committed (failed, cancelled or superseded).++ With ``token``, only the worker that load started: a newer load's worker is left alone."""+ with self._lock:+ pending = self._ltx25_pending_encoder+ if pending is None or (token is not _ANY_LOAD and pending[0] != token):+ return+ self._ltx25_pending_encoder = None+ _stop_ltx25_encoder(pending[1])+def _rollback_precommit_globals(self, token: Optional[int]) -> None:"""Restore process-wide speed globals (cudnn.benchmark / TF32 / the compiledGGUF dequantizer) for a load that died BEFORE committing _VideoLoadState.@@ -4957,6 +5099,8 @@ class VideoBackend:skip_transformer_weights: bool = False,skip_transformer_components: tuple[str, ...] = (),h3_task: Optional[str] = None,+ ltx25_shards: Optional[dict[str, frozenset[str]]] = None,+ ltx25_dev: bool = False,) -> list[tuple[str, int]]:"""The (rfilename, size) list a load actually needs from the base repo.@@ -4984,8 +5128,19 @@ class VideoBackend:from .diffusion_te_prequant import is_prequant_covered_weightfrom .video_minimax_h3 import H3_TASK_REFERENCES+ from .video_ltx25 import (+ is_ltx25_pack,+ is_ltx25_single_file_listing,+ ltx25_pack_files,+ ltx25_single_file_companions,+ )+siblings = list(info.siblings or [])- is_h3_modular = any(s.rfilename == "modular_model_index.json" for s in siblings)+ ltx25_pack = is_ltx25_pack(s.rfilename for s in siblings)+ # The LTX-2.5 pack ships a modular_model_index.json beside its model_index.json; it is not H3's layout.+ is_h3_modular = not ltx25_pack and any(+ s.rfilename == "modular_model_index.json" for s in siblings+ )h3_is_references = is_h3_modular and (h3_task or "").strip().lower() == H3_TASK_REFERENCESh3_denoiser_prefix = "transformer_ref/" if h3_is_references else "transformer/"# Which component's dense weight shards ``skip_transformer_weights`` drops. It has to be the partition this load@@ -5042,8 +5197,46 @@ class VideoBackend:if skip_te_components and is_prequant_covered_weight(name, skip_te_components):continuefiles.append((name, int(size)))+ if is_ltx25_single_file_listing(s.rfilename for s in siblings):+ # The split single-file release as a base: only the companion files beside the picked DiT.+ return ltx25_single_file_companions(files, dev = ltx25_dev)+ if ltx25_pack:+ # Unused components and the duplicate shard sets the LTX-2.5 pack ships (see ltx25_pack_files).+ files = ltx25_pack_files(files, ltx25_shards, dev = ltx25_dev)return files+ @staticmethod+ def _ltx25_plan_shards(+ info: Any, base: str, hf_token: Optional[str]+ ) -> Optional[dict[str, frozenset[str]]]:+ """For an LTX-2.5 pack, the shard set each component's ``*.index.json`` names, so a plan stages the copy the load+ opens (the pack ships two transformer sets); None for any other repo, or when an index cannot be read."""+ from .video_ltx25 import _PACK_SKIP_PREFIXES, is_ltx25_pack, ltx25_shards_from_indexes++ names = [s.rfilename for s in (info.siblings or [])]+ if not is_ltx25_pack(names):+ return None+ import json++ from utils.hf_xet_fallback import hf_hub_download_with_xet_fallback++ indexes: dict[str, Any] = {}+ try:+ for name in names:+ if (+ "/" in name+ and name.endswith(".safetensors.index.json")+ and not name.startswith(_PACK_SKIP_PREFIXES)+ ):+ local = hf_hub_download_with_xet_fallback(+ base, name, hf_token, reuse_other_cache_root = True+ )+ indexes[name] = json.loads(Path(local).read_text(encoding = "utf-8"))+ except Exception as exc: # noqa: BLE001 -- the plan falls back to ltx25_pack_files' listing-only choice+ logger.debug("video.ltx25_plan_shards: %s", exc)+ return None+ return ltx25_shards_from_indexes(indexes)+def _estimate_download_bytes(self,repo_id: str,@@ -5058,6 +5251,7 @@ class VideoBackend:h3_task: Optional[str] = None,h3_te_scheme: Optional[str] = None,local_files_only: bool = False,+ ltx25_dev: bool = False,) -> Optional[int]:"""Total bytes this load will pull (checkpoint + companions), or None.@@ -5103,6 +5297,8 @@ class VideoBackend:skip_transformer_weights = skip_transformer_weights,skip_transformer_components = skip_transformer_components,h3_task = h3_task,+ ltx25_dev = ltx25_dev,+ ltx25_shards = self._ltx25_plan_shards(info, base, hf_token),))return total or None@@ -5156,8 +5352,10 @@ class VideoBackend:if is_h3_native(fam, kind):return self._h3_native_download_plan(repo_id, gguf_filename or "", hf_token = hf_token)- base = repo_id if kind == "pipeline" else resolve_video_base_repo(fam, base_repo)+ base = repo_id if kind == "pipeline" else resolve_video_base_repo(fam, base_repo, repo_id)h3_task = _h3_single_file_task(fam, kind, gguf_filename, h3_task)+ # A dev LTX-2.5 load is single stage and never opens the latent upsampler.+ ltx25_dev = _ltx25_dev_load(fam, kind, gguf_filename, repo_id, display_repo_id)# The same resolution the load makes, so an H3 auto pick the loader will serve from a hosted checkpoint is not# staged dense here first: that is 66.3 GB the panel downloads and the load never opens, and the replacement# would then arrive outside this plan.@@ -5374,6 +5572,9 @@ class VideoBackend:),skip_transformer_components = _planned_denoiser_components(fam, kind),h3_task = h3_task,+ ltx25_dev = ltx25_dev,+ # The pack's indexes pick the transformer / connectors copy, as _predownload_base does.+ ltx25_shards = self._ltx25_plan_shards(info, base, hf_token),),revision = getattr(info, "sha", None),# A pipeline pick has no single file: the base IS the selected model (base = repo_id above). Under a@@ -5691,6 +5892,7 @@ class VideoBackend:h3_task: Optional[str] = None,cancel_event: Optional[threading.Event] = None,local_files_only: bool = False,+ ltx25_dev: bool = False,) -> Optional[str]:"""Pull exactly the base-repo files the load needs; return the local snapshot dir.@@ -5726,11 +5928,48 @@ class VideoBackend:skip_transformer_weights = skip_transformer_weights,skip_transformer_components = skip_transformer_components,h3_task = h3_task,+ ltx25_dev = ltx25_dev,+ )+ from .video_ltx25 import (+ is_ltx25_pack,+ is_ltx25_single_file_listing,+ ltx25_shards_from_indexes,+ )++ single_file_base = is_ltx25_single_file_listing(+ sib.rfilename for sib in (info.siblings or []))- if not any(name == "model_index.json" for name, _ in files):+ if not single_file_base and not any(name == "model_index.json" for name, _ in files):return Nonefrom utils.hf_xet_fallback import hf_hub_download_with_xet_fallback+ if is_ltx25_pack(name for name, _ in files) or is_ltx25_pack(+ sib.rfilename for sib in (info.siblings or [])+ ):+ import json++ # Read the shard indexes first so only the indexed copy of each duplicated weight set is fetched.+ indexes: dict[str, Any] = {}+ for name, _ in files:+ if name.endswith(".safetensors.index.json"):+ if cancel.is_set():+ raise RuntimeError(VIDEO_CANCELLED_MSG)+ local_index = hf_hub_download_with_xet_fallback(+ base, name, hf_token, cancel_event = cancel, reuse_other_cache_root = True+ )+ indexes[name] = json.loads(Path(local_index).read_text(encoding = "utf-8"))+ files = self._base_download_files(+ info,+ kind,+ ltx23 = ltx23,+ skip_te_components = skip_te_components,+ skip_transformer_weights = skip_transformer_weights,+ skip_transformer_components = skip_transformer_components,+ h3_task = h3_task,+ ltx25_dev = ltx25_dev,+ ltx25_shards = ltx25_shards_from_indexes(indexes),+ )+snapshot_root: Optional[str] = Noneroots: set[str] = set()for name, _ in files:@@ -5754,7 +5993,7 @@ class VideoBackend:except (IndexError, ValueError, OSError):root = ""roots.add(root)- if name == "model_index.json":+ if name == "model_index.json" or single_file_base:snapshot_root = root or None# Only hand back a snapshot the WHOLE set lives in. reuse_other_cache_root resolves per file, so a moved# cache can serve the manifest from the old root while the rest land in the live one, pointing@@ -5945,7 +6184,7 @@ class VideoBackend:except Exception: # noqa: BLE001 - never let log tidying stop a loadpass- base = repo_id if kind == "pipeline" else resolve_video_base_repo(fam, base_repo)+ base = repo_id if kind == "pipeline" else resolve_video_base_repo(fam, base_repo, repo_id)with self._lock:if _load_token is not None and _load_token != self._load_token:@@ -6119,6 +6358,9 @@ class VideoBackend:if fam.name == "ltx-2":# The file also bundles VAE / audio VAE / vocoder, priced as companions; connectors stay in.from .video_ltx2 import ltx23_is_dit_or_connector_key as ltx_keys+ if fam.name == "ltx-2.5":+ # Only the DiT: the pack's shared connectors are priced as companions.+ from .video_ltx2 import ltx23_is_dit_key as ltx_keysdef _price_checkpoint(path: Any) -> tuple[Optional[int], Any]:"""Resident MiB of one checkpoint file's DiT and its ComfyUI quant scan (None: a plain file)."""@@ -6219,6 +6461,21 @@ class VideoBackend:# pins the VAE to fp32 either way, so scaling it counts those bytes twice (2.8 GB on Wan TI2V-5B) against a# hard refusal.vae_gb = components[2] if components is not None else 0.0+ if components is not None and fam.name == "ltx-2.5":+ from .video_ltx25 import (+ LTX25_LATENT_UPSAMPLER_GB,+ LTX25_WORKER_RESIDENT_GB,+ ltx25_uses_upsampler,+ )++ # The encoder worker is a second process on the card: its CUDA context and allocator slack stay+ # resident on every tier, even when its weights are off the card.+ vae_gb += LTX25_WORKER_RESIDENT_GB+ # The table's companions include the latent upsampler, which a dev (single stage) load never attaches.+ if not ltx25_uses_upsampler(+ _ltx25_dev_load(fam, kind, gguf_filename, repo_id, display_repo_id)+ ):+ vae_gb -= LTX25_LATENT_UPSAMPLER_GBvae_scale = 1.0 if getattr(fam, "vae_force_fp32", False) else dtype_scalescaled_te_gb = text_encoder_gb * dtype_scalescaled_vae_gb = vae_gb * vae_scale@@ -6441,6 +6698,42 @@ class VideoBackend:# above and before any weight is materialised, on the plan the build actually peaks at.raise_on_unified_memory_shortfall(plan, family = getattr(fam, "name", None), logger = logger)+ # ── LTX-2.5: its Gemma 4 encoder loads in a sidecar worker, overlapping the DiT load below.+ ltx25_client = None+ ltx25_dev = False+ if fam.name == "ltx-2.5":+ from .video_families import ltx25_is_dev+ from .video_ltx25 import encoder_resident_for_plan, start_text_encoder++ ltx25_dev = _ltx25_dev_load(fam, kind, gguf_filename, repo_id, display_repo_id)+ # A stale load's pending worker goes only while this load is current; a superseded load that resumes here+ # must not stop the newer load's worker.+ with self._lock:+ if _load_token is not None and _load_token != self._load_token:+ raise RuntimeError("Video load was cancelled or superseded.")+ stale_encoder, self._ltx25_pending_encoder = self._ltx25_pending_encoder, None+ if stale_encoder is not None:+ _stop_ltx25_encoder(stale_encoder[1])+ ltx25_client = start_text_encoder(+ repo = _base_local_dir or (repo_id if kind == "pipeline" else base),+ hf_token = hf_token,+ cache_dir = hub_cache_dir(),+ local_files_only = local_files_only,+ device = str(target.torch_device),+ dtype = str(dtype).replace("torch.", ""),+ resident = encoder_resident_for_plan(plan),+ budget_mib = (getattr(plan, "estimates", None) or {}).get("safe_device_budget_mib"),+ )+ # Installed only while this load is current: a load superseded during the start must not overwrite the+ # newer load's worker (whose token-scoped cleanup could then never find it).+ with self._lock:+ superseded = _load_token is not None and _load_token != self._load_token+ if not superseded:+ self._ltx25_pending_encoder = (_load_token, ltx25_client)+ if superseded:+ _stop_ltx25_encoder(ltx25_client)+ raise RuntimeError("Video load was cancelled or superseded.")+# ── build the pipeline.from .ltx2_import_compat import ensure_ltx2_pipelines_importable, is_ltx2_pipeline_class@@ -6550,9 +6843,15 @@ class VideoBackend:# no-op there -- but the flag is carried rather than defaulted so the top-up can never become the# one call that reaches the Hub.local_files_only = local_files_only,+ ltx25_dev = ltx25_dev,)or _base_local_dir)+ if ltx25_client is not None:+ from .video_ltx25 import LTX25_NONE_COMPONENTS++ # The encoder runs in the worker; the enhancer, processor and duration head are never used.+ pipe_kwargs.update({name: None for name in LTX25_NONE_COMPONENTS})if kind == "pipeline":# The pre-downloaded snapshot dir keeps from_pretrained off the hub; hub id when pre-download was skipped.pipe = pipeline_cls.from_pretrained(_base_local_dir or repo_id, **pipe_kwargs)@@ -6686,6 +6985,68 @@ class VideoBackend:device = ltx23_device,text_encoder_device = ltx23_te_device,)+ elif fam.name == "ltx-2.5":+ # The split 2.5 DiT (bf16, int8-convrot or GGUF); connectors, VAEs, vocoder and upsampler come from the+ # pack, the encoder from the worker.+ from .video_ltx25 import (+ is_ltx25_single_file_base,+ load_ltx25_comfy_transformer,+ load_ltx25_transformer,+ )++ if comfy_scan is not None and is_ltx25_single_file_base(_base_local_dir or base):+ # The int8-convrot files quantize the text connectors too, and the pack-free assembly reads them from+ # the DiT file: refuse before the DiT is read.+ raise ValueError(+ "This LTX-2.5 file stores its text connectors quantized, which the single-file assembly does "+ "not dequantize. Load it on the Lightricks/LTX-2.5-Diffusers base (base_repo), or pick the "+ "bf16 DiT or a GGUF quant."+ )+ if comfy_scan is not None:+ ltx25_transformer = load_ltx25_comfy_transformer(+ checkpoint_path,+ comfy_scan,+ base_repo = _base_local_dir or base,+ torch_dtype = dtype,+ hf_token = hf_token,+ cache_dir = hub_cache_dir(),+ local_files_only = local_files_only,+ **_video_comfy_backends(+ fam, base, target, plan, bf16_plan, keep = comfy_keep+ ),+ family = fam.name,+ target = target,+ logger = logger,+ )+ else:+ ltx25_transformer = load_ltx25_transformer(+ checkpoint_path,+ base_repo = _base_local_dir or base,+ torch_dtype = dtype,+ is_gguf = kind == "gguf",+ hf_token = hf_token,+ cache_dir = hub_cache_dir(),+ local_files_only = local_files_only,+ )+ from .video_ltx25 import (+ assemble_ltx25_single_file_pipeline,+ is_ltx25_single_file_base,+ )++ if is_ltx25_single_file_base(_base_local_dir or base):+ # The split single-file release: every component from the files beside the DiT, no pack.+ pipe = assemble_ltx25_single_file_pipeline(+ ltx25_transformer,+ checkpoint_path,+ base = _base_local_dir or base,+ torch_dtype = dtype,+ hf_token = hf_token,+ local_files_only = local_files_only,+ )+ else:+ pipe = pipeline_cls.from_pretrained(+ _base_local_dir or base, **{**pipe_kwargs, "transformer": ltx25_transformer}+ )else:def _load_expert(path: Any, scan: Any, subfolder: str) -> Any:@@ -6730,6 +7091,19 @@ class VideoBackend:if vae is not None and getattr(vae, "dtype", None) is not torch.float32:vae.to(torch.float32)+ if ltx25_client is not None:+ from .video_ltx25 import attach_to_pipeline+ attach_to_pipeline(+ pipe,+ ltx25_client,+ dev = ltx25_dev,+ base_repo = _base_local_dir or (repo_id if kind == "pipeline" else base),+ torch_dtype = dtype,+ hf_token = hf_token,+ cache_dir = hub_cache_dir(),+ local_files_only = local_files_only,+ )+if _load_token is not None and _load_token != self._load_token:del pipeclear_gpu_cache()@@ -7046,6 +7420,7 @@ class VideoBackend:repo_id,base,fallback = (fam.default_steps, fam.default_guidance),+ family = fam.name,)static_plan = auto_static_skip_plan((repo_id, base), skip_tier(speed_mode, effective_speed), default_cache_steps@@ -7167,7 +7542,7 @@ class VideoBackend:# quadratic math backend.target = types.SimpleNamespace(device = target.device, dtype = dtype),)- if fam.name == "ltx-2":+ if fam.name in LTX_FAMILIES:# Token counts depend only on (w, h, frames), so static compile: one recompile per shape, ~1.3x faster.ltx_dit = getattr(view, fam.denoiser_attr, None)if ltx_dit is not None:@@ -7187,7 +7562,7 @@ class VideoBackend:offload_active = plan.offload_policy != "none",cuda_graph_default = False,)- if fam.name == "ltx-2" and applied.get("compiled"):+ if fam.name in LTX_FAMILIES and applied.get("compiled"):from .video_ltx2 import install_stg_compile_adapterinstall_stg_compile_adapter(getattr(view, fam.denoiser_attr, None))if not getattr(fam, "cudnn_benchmark", True) and applied.get("cudnn_benchmark"):@@ -7242,6 +7617,10 @@ class VideoBackend:placement_device = target.torch_device,logger = logger,)+ ltx25_upsampler = getattr(pipe, "_unsloth_ltx25_upsampler", None)+ if ltx25_upsampler is not None and offload_policy == OFFLOAD_NONE:+ # ~1 GB; resident with the rest, else render() moves it in for the upsample only.+ ltx25_upsampler.to(target.torch_device)if (offload_policy == plan.offload_policyand vram_floor_mib is not None@@ -7381,6 +7760,9 @@ class VideoBackend:)apply_comfy_flow_shift(pipe, getattr(fam, "comfy_flow_shift", None), logger)+ if ltx25_client is not None:+ # The worker loaded the Gemma 4 encoder while the DiT loaded; a failure there fails this load.+ ltx25_client.wait_ready(self._cancel_event if _load_token is not None else None)from . import diffusion_prompt_cachediffusion_prompt_cache.install(@@ -7471,6 +7853,13 @@ class VideoBackend:bg_compile = load_bg_compile,)self._precommit_globals = None+ pending_encoder = self._ltx25_pending_encoder+ if (+ ltx25_client is not None+ and pending_encoder is not None+ and pending_encoder[1] is ltx25_client+ ):+ self._ltx25_pending_encoder = Nonelogger.info("video.loaded: %s (%s, %s, offload=%s, speed=%s, quant=%s)",repo_id,@@ -9255,12 +9644,15 @@ class VideoBackend:out_fps = (fam.default_fps if fam.name == "minimax-h3" else int(fps or fam.default_fps))+ # The same identifiers, in the same order, as the status defaults the UI shows.default_steps, default_guidance = default_video_generation_params(state.variant_id,state.gguf_filename,+ state.display_repo_id,state.repo_id,state.base_repo,fallback = (fam.default_steps, fam.default_guidance),+ family = fam.name,)steps = int(steps or default_steps)guidance = float(default_guidance if guidance is None else guidance)@@ -9554,12 +9946,13 @@ class VideoBackend:if fam.modular_workflow:kwargs["output"] = ["videos", "audio", "sampling_rate"]# Auto-blocks distinguish omitted conditioning from empty conditioning.- if first_pil is not None:+ # LTX-2.5 conditions through its own render (LTX2ConditionPipeline), not an image kwarg.+ if first_pil is not None and fam.name != "ltx-2.5":kwargs["image"] = first_pilfor key, value in i2v_extra.items():if key in call_params:kwargs[key] = value- if last_pil is not None:+ if last_pil is not None and video_family_accepts_last_frame(fam):kwargs["last_image"] = last_pilif references:from .video_minimax_h3 import h3_diffusers_references@@ -9573,6 +9966,28 @@ class VideoBackend:if callable(setter) and value is not None:setter(float(value))+ # What the clip records; LTX-2.5's two-stage render reports its stage-2 steps in the progress below.+ recorded_steps = steps+ ltx25_render_call = None+ if fam.name == "ltx-2.5":+ from .video_ltx2 import ensure_recompile_limit as ltx25_recompile_limit+ from .video_ltx25 import render as ltx25_render, stage_steps++ ltx25_dev = bool(getattr(pipe, "_unsloth_ltx25_dev", False))+ steps = sum(stage_steps(steps, dev = ltx25_dev))+ ltx25_recompile_limit()++ def ltx25_render_call() -> Any:+ return ltx25_render(+ pipe,+ kwargs,+ dev = ltx25_dev,+ image = first_pil,+ upsampler = getattr(pipe, "_unsloth_ltx25_upsampler", None),+ on_step = kwargs.get("callback_on_step_end"),+ cancel = cancel,+ )+started = time.monotonic()self._gen = {"active": True,@@ -9792,7 +10207,12 @@ class VideoBackend:)try:with grad_ctx, protect_ctx, progress_ctx(), sigma_ctx:- output = render_thread.run("video", lambda: pipe(**kwargs))+ output = render_thread.run(+ "video",+ ltx25_render_call+ if ltx25_render_call is not None+ else (lambda: pipe(**kwargs)),+ )except _VideoGenerationCancelled:# Unwinding by exception skips maybe_free_model_hooks(); under offload the onloaded modules would# stay on the GPU.@@ -9879,7 +10299,7 @@ class VideoBackend:"duration_s": duration_s,"has_audio": bool(audio_track is not None),"conditioning": conditioning,- "steps": steps,+ "steps": recorded_steps,"guidance": guidance,# The EFFECTIVE negative prompt, like guidance beside it: a guidance-distilled family normalises it# away above, so the sidecar records what conditioned the clip instead of what the caller happened@@ -9940,6 +10360,10 @@ class VideoBackend:has_keyframes = bool(first_frame or last_frame),has_last_frame = bool(last_frame),)+ if fam.name == "ltx-2.5":+ return VideoBackend._resolve_ltx25_first_frame(+ fam, first_frame, last_frame, width, height+ )first = last = Noneif first_frame or last_frame:from .diffusion import decode_b64_image@@ -9977,6 +10401,35 @@ class VideoBackend:conditioning = h3_conditioning_mode(has_first = first is not None, has_last = last is not None)return first, last, width, height, conditioning+ @staticmethod+ def _resolve_ltx25_first_frame(+ fam: VideoFamily,+ first_frame: Optional[str],+ last_frame: Optional[str],+ width: Optional[int],+ height: Optional[int],+ ) -> tuple[Any, Any, int, int, str]:+ """LTX-2.5 image-to-video: a first frame only, on a "match source" canvas when no size is given."""+ from .video_ltx25 import ltx25_canvas_for_aspect, prepare_ltx25_first_frame++ if last_frame:+ raise ValueError(+ "LTX-2.5 animates from a start frame only; it takes no end frame. Remove the end frame."+ )+ first = None+ if first_frame:+ from .diffusion import decode_b64_image+ first = decode_b64_image(first_frame, mode = "RGB")+ if (width is None or height is None) and first is not None:+ width, height = ltx25_canvas_for_aspect(*first.size)+ else:+ default_w, default_h = fam.resolution_presets[0]+ width, height = snap_video_size(fam, width or default_w, height or default_h)+ if first is not None:+ # Fitted to the canvas later, by LTX2ConditionPipeline after its CRF round trip, as the reference does.+ first = prepare_ltx25_first_frame(first)+ return first, None, width, height, h3_conditioning_mode(has_first = first is not None)+@staticmethoddef _resolve_flow_shifts(fam: VideoFamily,@@ -10586,6 +11039,9 @@ class VideoBackend:from . import diffusion_prompt_cachediffusion_prompt_cache.release(getattr(state, "pipe", None))+ if getattr(getattr(state, "family", None), "name", None) == "ltx-2.5":+ from .video_ltx25 import close_encoder+ close_encoder(getattr(state, "pipe", None))# A pinner still copying would hold its chunks past release_pinned_host_memory().stop_background_pins(getattr(state, "pipe", None))# Before clear_gpu_cache(), or the graph pool stays reserved.@@ -10629,6 +11085,12 @@ class VideoBackend:# Fence generations queued behind the active one too: they hold no cancel event, so the signal cannot reach# them.self._teardown_waiters += 1+ # A cancelled LTX-2.5 load's encoder worker: the load thread may sit in from_pretrained for minutes, so stop+ # the worker now rather than when that thread unwinds.+ pending_encoder = getattr(self, "_ltx25_pending_encoder", None)+ self._ltx25_pending_encoder = None+ if pending_encoder is not None:+ _stop_ltx25_encoder(pending_encoder[1])# Barrier: wait for the signalled generation to exit before freeing the pipeline, else we report the VRAM free# while the clip still holds it.with self._generate_lock:@@ -10700,6 +11162,7 @@ class VideoBackend:state.repo_id,state.base_repo,fallback = (fam.default_steps, fam.default_guidance),+ family = fam.name,)return {"loaded": True,@@ -10764,8 +11227,8 @@ class VideoBackend:"resolution_multiple": fam.resolution_multiple,"resolution_presets": [list(p) for p in fam.resolution_presets],# Let the frontend preview the backend-owned "match source" rule.- "canvas_short_edge": H3_CANVAS_SHORT_EDGE if fam.supports_keyframes else None,- "canvas_max_pixels": H3_CANVAS_MAX_PIXELS if fam.supports_keyframes else None,+ "canvas_short_edge": _keyframe_canvas(fam)[0],+ "canvas_max_pixels": _keyframe_canvas(fam)[1],"canvas_from_presets": video_family_uses_i2v_pipeline(fam),"flow_shift": fam.default_flow_shift,"audio_flow_shift": fam.default_audio_flow_shift,@@ -10777,6 +11240,16 @@ class VideoBackend:}+def _keyframe_canvas(fam: Any) -> tuple[Optional[int], Optional[int]]:+ """(short edge, max pixels) of the family's "match source" keyframe canvas, or (None, None)."""+ if not getattr(fam, "supports_keyframes", False):+ return None, None+ if getattr(fam, "name", None) == "ltx-2.5":+ from .video_ltx25 import LTX25_CANVAS_MAX_PIXELS, LTX25_CANVAS_SHORT_EDGE+ return LTX25_CANVAS_SHORT_EDGE, LTX25_CANVAS_MAX_PIXELS+ return H3_CANVAS_SHORT_EDGE, H3_CANVAS_MAX_PIXELS++def _sd_cpp_cudnn_status(state: Any) -> dict[str, Any]:"""Whether the native runtime's sd.cpp children run attention on cuDNN; nulls for every other runtime."""cudnn = getattr(getattr(state, "pipe", None), "cudnn", None)diff --git a/studio/backend/core/inference/video_families.py b/studio/backend/core/inference/video_families.pyindex 9c1f7e01aa7..e9ccc8885c9 100644--- a/studio/backend/core/inference/video_families.py+++ b/studio/backend/core/inference/video_families.py@@ -36,11 +36,12 @@ VIDEO_CANCELLED_MSG = "Video generation was cancelled."VIDEO_GENERATION_BUSY_MSG = "A video generation is already in progress."VIDEO_MODEL_CHANGED_MSG = "The requested video model changed before generation was reserved."-# One LTX version token: ltx / ltxv / ltx-video, optional separator, major 2, then ".N" / "_N" (minor), "N" ending the+# One LTX version token: ltx / ltxv / ltx-video, optional separator, major 2, then ".N" / "_N" (minor, any digits, so+# "ltx-2.10" reads as 2.10), "N" ending the# token ("ltx25"), or nothing ("ltx-2-19b" = 2.0). Anything else ("ltx-24fps", "ltx-transformer") is no name evidence,# as is a bare "ltx23" / "ltx-23" (no release uses that spelling, so it cannot outrank the repo)._LTX_VERSION = re.compile(- r"(?<![a-z0-9])ltx(?:v|[-_ ]?video)?[-_ ]?2(?:[._]([0-9])(?![0-9])|([0-9])(?![0-9a-z])|(?![0-9a-z]|[._][0-9]))"+ r"(?<![a-z0-9])ltx(?:v|[-_ ]?video)?[-_ ]?2(?:[._]([0-9]+)(?![0-9])|([0-9])(?![0-9a-z])|(?![0-9a-z]|[._][0-9]))")@@ -51,83 +52,172 @@ def ltx_name_version(name: Optional[str]) -> Optional[str]:return None+# Family per LTX release: 2.0 / 2.3 run the LTX-2 assembly, 2.5 (diffusers called its pre-release "2.4") its own family.+LTX2_FAMILY = "ltx-2"+LTX25_FAMILY = "ltx-2.5"+LTX_FAMILIES = (LTX2_FAMILY, LTX25_FAMILY)+++def ltx_family_for_version(version: Optional[str]) -> Optional[str]:+ """``ltx-2`` for 2.0-2.3, ``ltx-2.5`` for 2.4 / 2.5, None for a release Studio does not know (2.6+)."""+ if not version:+ return None+ minor = int(version[2:])+ if minor <= 3:+ return LTX2_FAMILY+ if minor <= 5:+ return LTX25_FAMILY+ return None++def unsupported_ltx_version(*names: Optional[str]) -> Optional[str]:- # LTX > 2.3 (diffusers calls the 2.5 pre-release "2.4") is not drop-in LTX-2.+ # Releases after 2.5 are unknown: neither LTX family can claim their weights.for name in names:version = ltx_name_version(name)- if version is not None and int(version[2:]) >= 4:+ if version is not None and ltx_family_for_version(version) is None:return versionreturn Nonedef unsupported_ltx_message(version: str, subject: str) -> str:return (- f"{subject} is LTX-{version}, which Studio does not support yet. LTX-{version} is not a drop-in LTX-2.3: "- "it uses a new Gemma 4 text encoder, a new video decoder and its own sampling schedule, so loading it as "- "LTX-2 would fail or produce a broken video. Use LTX-2.3 (Lightricks/LTX-2.3 or unsloth/LTX-2.3-GGUF) "- "for now."+ f"{subject} is LTX-{version}, which Studio does not support yet. Studio runs LTX-2.0 / LTX-2.3 "+ "(Lightricks/LTX-2.3 or unsloth/LTX-2.3-GGUF) and LTX-2.5 (Lightricks/LTX-2.5-Diffusers).")-def assert_supported_ltx_version(+def wrong_ltx_family_message(version: str, family: str, subject: str) -> str:+ expected = ltx_family_for_version(version)+ return (+ f"{subject} is LTX-{version}, which loads as the '{expected}' family, not '{family}'. "+ "LTX-2.5 is not a drop-in LTX-2.3 (Gemma 4 text encoder, no video FFN bias, keyframe position "+ "embedding), so one family cannot load the other's weights. Pick the "+ f"'{expected}' family, or leave the family on Auto."+ )+++def _ltx_leaf(name: Optional[str]) -> str:+ # Last segment only: a local parent folder must not decide.+ return os.path.basename((name or "").replace("\\", "/").rstrip("/"))+++def ltx_pick_version(repo_id: Optional[str],filename: Optional[str] = None,display_repo_id: Optional[str] = None,-) -> None:- """A file whose own name has a versioned LTX token decides alone (an ltx-2.3 file in an ``ltx-2.5-tests`` folder- loads); any other file name (``model``, ``ltx-transformer``) defers to the repo / display id."""-- def leaf(name: Optional[str]) -> str:- # Last segment only: a local parent folder must not decide.- return os.path.basename((name or "").replace("\\", "/").rstrip("/"))-- base = leaf(filename)+) -> Optional[tuple[str, str]]:+ """``(version, shown)`` the pick's names declare. A file whose own name has a versioned LTX token decides alone+ (an ltx-2.3 file in an ``ltx-2.5-tests`` folder is 2.3); any other file name (``model``, ``ltx-transformer``)+ defers to the display id, then the repo id."""+ base = _ltx_leaf(filename)if ltx_name_version(base) is not None:picks: tuple[tuple[str, Optional[str]], ...] = ((base, filename),)else:picks = ((base, filename),- (leaf(display_repo_id), display_repo_id),- (leaf(repo_id), repo_id),+ (_ltx_leaf(display_repo_id), display_repo_id),+ (_ltx_leaf(repo_id), repo_id),)for name, shown in picks:- version = unsupported_ltx_version(name)+ version = ltx_name_version(name)if version is not None:- raise ValueError(unsupported_ltx_message(version, f"'{shown}'"))+ return version, str(shown)+ return None-def assert_ltx_pick_supported(- family: Optional[str],+def assert_supported_ltx_version(repo_id: Optional[str],filename: Optional[str] = None,display_repo_id: Optional[str] = None,) -> None:- """Name guard for a pick already resolved to ``family``; a non-LTX family never trips on an ltx-2.5 token."""- if family == "ltx-2":- assert_supported_ltx_version(repo_id, filename, display_repo_id)+ """Refuse a pick whose names declare an LTX release no family supports (2.6 and later)."""+ found = ltx_pick_version(repo_id, filename, display_repo_id)+ if found is not None and ltx_family_for_version(found[0]) is None:+ raise ValueError(unsupported_ltx_message(found[0], f"'{found[1]}'"))-def assert_local_pipeline_not_ltx25(path: Optional[str]) -> None:- """Refuse a local diffusers LTX-2.5 folder whose name does not say so; unreadable passes."""+def ltx_family_by_name(+ repo_id: Optional[str],+ filename: Optional[str] = None,+ display_repo_id: Optional[str] = None,+) -> Optional[str]:+ """The LTX family the pick's names declare, or None (no versioned LTX token, or an unknown release)."""+ found = ltx_pick_version(repo_id, filename, display_repo_id)+ return ltx_family_for_version(found[0]) if found is not None else None+++def assert_ltx_pick_supported(+ family: Optional[str],+ repo_id: Optional[str],+ filename: Optional[str] = None,+ display_repo_id: Optional[str] = None,+) -> None:+ """Name guard for a pick already resolved to ``family``: an LTX family never loads another release's weights+ (LTX-2.5 never reaches the 2.3 assembly, and the reverse), and a release after 2.5 is refused. A non-LTX family+ never trips on an LTX token."""+ if family not in LTX_FAMILIES:+ return+ found = ltx_pick_version(repo_id, filename, display_repo_id)+ if found is None:+ return+ version, shown = found+ expected = ltx_family_for_version(version)+ if expected is None:+ raise ValueError(unsupported_ltx_message(version, f"'{shown}'"))+ if expected != family:+ raise ValueError(wrong_ltx_family_message(version, family, f"'{shown}'"))+++def local_ltx_pipeline_family(path: Optional[str]) -> Optional[str]:+ """The LTX family a local diffusers folder's ``model_index.json`` declares: ``ltx-2.5`` for a Gemma 4 encoder or a+ ``diffusion_decoder`` / ``duration_head`` component, ``ltx-2`` for any other LTX2 pipeline; None when the folder+ has no readable LTX2 index."""import jsonfrom pathlib import Pathtry:index = Path(str(path or "")).expanduser() / "model_index.json"if not path or not index.is_file():- return+ return Nonespec = json.loads(index.read_text(encoding = "utf-8"))except (OSError, ValueError, TypeError):- return+ return Noneif not isinstance(spec, dict) or not str(spec.get("_class_name", "")).startswith("LTX2"):- return+ return Noneencoder = spec.get("text_encoder")encoder_class = encoder[1] if isinstance(encoder, list) and len(encoder) == 2 else ""+ # An empty or null component entry is absent, like a malformed text_encoder above.if str(encoder_class).startswith("Gemma4") or any(- isinstance(spec.get(k), list) and spec.get(k)[0]+ isinstance(spec.get(k), list) and bool(spec.get(k)) and spec.get(k)[0]for k in ("diffusion_decoder", "duration_head")):- raise ValueError(unsupported_ltx_message("2.5", f"'{path}' (by its model_index.json)"))+ return LTX25_FAMILY+ return LTX2_FAMILY+++def assert_local_pipeline_family(path: Optional[str], family: Optional[str]) -> None:+ """Refuse a local diffusers LTX folder whose ``model_index.json`` declares the other LTX family."""+ if family not in LTX_FAMILIES:+ return+ declared = local_ltx_pipeline_family(path)+ if declared is not None and declared != family:+ version = "2.5" if declared == LTX25_FAMILY else "2.3"+ raise ValueError(+ wrong_ltx_family_message(version, family, f"'{path}' (by its model_index.json)")+ )+++def ltx25_training_message(subject: str) -> str:+ return (+ f"{subject} is LTX-2.5, which Studio can run on the Video page but cannot train yet. "+ "Train on LTX-2 (Lightricks/LTX-2) instead."+ )+++def assert_local_pipeline_not_ltx25(path: Optional[str]) -> None:+ """Training guard: refuse a local diffusers LTX-2.5 folder whose name does not say so; unreadable passes."""+ if local_ltx_pipeline_family(path) == LTX25_FAMILY:+ raise ValueError(ltx25_training_message(f"'{path}' (by its model_index.json)"))@dataclass(frozen = True)@@ -238,6 +328,8 @@ class VideoFamily:default_audio_flow_shift: Optional[float] = None# First/last-frame conditioning: the request may carry keyframe images.supports_keyframes: bool = False+ # False for a keyframe family that takes a first frame only (LTX-2.5); MiniMax-H3 takes both.+ accepts_last_frame: bool = True# Diffusers class serving a first-frame request over the loaded pipeline's components (video_i2v).i2v_pipeline_class: Optional[str] = Nonei2v_pipeline_config: tuple[tuple[str, object], ...] = field(default_factory = tuple)@@ -374,6 +466,35 @@ _FAMILIES: tuple[VideoFamily, ...] = (supports_references = True,supports_cfg = False,),+ # LTX-2.5 (diffusers >= 0.40): the 22B LTX-2.3 DiT without the video FFN bias plus a keyframe position embedding,+ # conditioned by a fine-tuned Gemma 4 12B (Gemma4UnifiedForConditionalGeneration, transformers >= 5.10.1). That+ # encoder runs in a spawned worker on the .venv_t5_510 sidecar (video_ltx25_te_worker); everything else runs here.+ # Defaults are the reference two-stage distilled recipe (video_ltx25): 8 distilled sigmas at half resolution, x2+ # latent upsample, 3 sigmas at full resolution, CFG 1. Two stages need a 64 px canvas (32 px per stage), so the+ # reference 1280x720 resolves to the 1280x704 latent canvas it actually renders.+ VideoFamily(+ name = "ltx-2.5",+ pipeline_class = "LTX2Pipeline",+ transformer_class = "LTX2VideoTransformer3DModel",+ base_repo = "Lightricks/LTX-2.5-Diffusers",+ aliases = ("ltx2.5", "ltx25", "ltxv-2.5", "ltx-video-2.5"),+ has_audio = True,+ default_steps = 8,+ default_guidance = 1.0,+ default_num_frames = 121,+ default_fps = 24,+ frame_step = 8,+ resolution_multiple = 64,+ resolution_presets = ((1280, 704), (704, 1280), (960, 512), (768, 512)),+ # transformer 42.0 bf16 (both DiT files are 42,018,190,584 bytes); Gemma 4 12B 23.9 (text_encoder/ shards),+ # held by the encoder worker; VAE 1.45 + connectors 6.34 + latent upsampler 1.0 + audio VAE / vocoder 0.37.+ bf16_components_gb = (42.0, 23.9, 9.2),+ supports_keyframes = True,+ accepts_last_frame = False,+ # Same DiT layout as LTX-2.3, so the same measured knobs.+ cudnn_benchmark = False,+ filter_reduction_configs = True,+ ),# LTX-2 (diffusers >= 0.39): ~19B single-stream video DiT generating synchronized audio + video in one pass. The# Gemma3-12B encoder is stored fp32 on the hub (~49 GB download, ~24 GB resident bf16). The base repo carries the# dev config (40 steps, CFG 4).@@ -735,9 +856,17 @@ def pipeline_available_video_families(*, device: Optional[str] = None) -> tuple[)-def resolve_video_base_repo(fam: VideoFamily, base_repo: Optional[str]) -> str:- """The companion diffusers repo: caller-supplied if given, else the family fallback."""+def resolve_video_base_repo(+ fam: VideoFamily,+ base_repo: Optional[str],+ repo_id: Optional[str] = None,+) -> str:+ """The companion diffusers repo: caller-supplied if given, else the family fallback. An LTX-2.5 DiT picked from the+ split single-file release (or a local copy of it) defaults to that release, whose companion files sit beside it."""base = (base_repo or "").strip()+ if not base and fam.name == LTX25_FAMILY and repo_id:+ from .video_ltx25 import ltx25_default_base+ base = ltx25_default_base(repo_id) or ""return base or fam.base_repo@@ -1001,7 +1130,9 @@ def video_family_accepts_first_frame(fam: VideoFamily) -> bool:def video_family_accepts_last_frame(fam: VideoFamily) -> bool:- return bool(getattr(fam, "supports_keyframes", False))+ return bool(getattr(fam, "supports_keyframes", False)) and bool(+ getattr(fam, "accepts_last_frame", True)+ )def video_family_uses_i2v_pipeline(fam: VideoFamily) -> bool:@@ -1046,6 +1177,34 @@ def video_i2v_call_kwargs(fam: VideoFamily, *identifiers: Optional[str]) -> dictreturn {}+def snap_canvas_within_cap(+ width: float, height: float, multiple: int, max_pixels: int+) -> tuple[int, int]:+ """Snap a "match source" canvas to ``multiple`` without leaving ``max_pixels``: each side rounds to the nearest+ multiple, and when that rounding pushes the area past the cap a side rounds down instead (the largest area under+ the cap, then the aspect nearest the unsnapped one). The frontend's matchedCanvas mirrors this."""+ import math++ def down(value: float) -> int:+ return max(multiple, math.floor(value / multiple) * multiple)++ def near(value: float) -> int:+ return max(multiple, math.floor(value / multiple + 0.5) * multiple)++ w, h = near(width), near(height)+ if w * h <= max_pixels:+ return w, h+ target = math.log(width / height)+ fits = [+ (cw, ch)+ for cw, ch in ((down(width), h), (w, down(height)), (down(width), down(height)))+ if cw * ch <= max_pixels+ ]+ if not fits:+ return down(width), down(height)+ return max(fits, key = lambda wh: (wh[0] * wh[1], -abs(math.log(wh[0] / wh[1]) - target)))++def first_frame_canvas(fam: VideoFamily, aspect_width: float, aspect_height: float) -> tuple[int, int]:@@ -1201,13 +1360,18 @@ _NAME_SEGMENT_DEFAULT_KEYS = frozenset(def default_video_generation_params(- *identifiers: Optional[str], fallback: tuple[int, float] = (40, 4.0)+ *identifiers: Optional[str],+ fallback: tuple[int, float] = (40, 4.0),+ family: Optional[str] = None,) -> tuple[int, float]:"""Default ``(steps, guidance)`` for a loaded video model; the first identifiernaming a known variant wins, so a GGUF filename ('...distilled...Q4_K_M.gguf')beats the family base repo. ``fallback`` is used when no identifier names a variant --callers pass the resolved family's own default so a Wan model loaded from an opaque localpath under an explicit family_override still gets 50/5.0, not the hardcoded LTX 40/4.0."""+ if family == LTX25_FAMILY:+ # The generic table's "ltx" key is the LTX-2 dev recipe, and 2.5's Diffusers pack names no variant at all.+ return LTX25_DEV_DEFAULTS if ltx25_is_dev(*identifiers) else LTX25_DISTILLED_DEFAULTSvariant = video_generation_variant(*identifiers)for key, steps, guidance in _VIDEO_GENERATION_DEFAULTS:if key == variant:@@ -1215,6 +1379,26 @@ def default_video_generation_params(return fallback+# LTX-2.5 defaults: distilled = the reference two-stage recipe's 8 stage-1 sigmas at CFG 1; dev = the diffusers pipeline's+# SFT recipe (30 steps, CFG 3).+LTX25_DISTILLED_DEFAULTS: tuple[int, float] = (8, 1.0)+LTX25_DEV_DEFAULTS: tuple[int, float] = (30, 3.0)+_LTX25_DEV = re.compile(r"(?<![a-z0-9])(?:dev|full|sft)(?![a-z0-9])|transformer_full")+_LTX25_DISTILLED = re.compile(r"(?<![a-z0-9])distill")+++def ltx25_is_dev(*identifiers: Optional[str]) -> bool:+ """The first identifier naming a variant decides (selected file before repo); unnamed means distilled, which is+ what the Diffusers pack's default ``transformer/`` and the reference workflow ship."""+ for identifier in identifiers:+ leaf = _ltx_leaf(identifier).lower()+ if _LTX25_DISTILLED.search(leaf):+ return False+ if _LTX25_DEV.search(leaf):+ return True+ return False++def video_generation_variant(*identifiers: Optional[str]) -> Optional[str]:"""The ``_VIDEO_GENERATION_DEFAULTS`` key the first identifier naming one matches, or None; the precedence``default_video_generation_params`` uses, so every per-variant decision agrees with the defaults."""diff --git a/studio/backend/core/inference/video_ltx2.py b/studio/backend/core/inference/video_ltx2.pyindex 47bf8682e14..b0224cb8f74 100644--- a/studio/backend/core/inference/video_ltx2.py+++ b/studio/backend/core/inference/video_ltx2.py@@ -286,11 +286,13 @@ def is_ltx23_checkpoint(checkpoint_path: Path | str) -> bool:def assert_not_ltx25_checkpoint(checkpoint_path: Path | str) -> None:"""Catch a renamed LTX-2.5 file by header: ``is_ltx23_checkpoint`` counts modulation rows, and 2.5 keeps 2.3's nine."""from .diffusion_content import is_ltx25_checkpoint- from .video_families import unsupported_ltx_message+ from .video_families import LTX2_FAMILY, wrong_ltx_family_messageif is_ltx25_checkpoint(str(checkpoint_path)):raise ValueError(- unsupported_ltx_message("2.5", f"'{Path(str(checkpoint_path)).name}' (by its tensors)")+ wrong_ltx_family_message(+ "2.5", LTX2_FAMILY, f"'{Path(str(checkpoint_path)).name}' (by its tensors)"+ ))diff --git a/studio/backend/core/inference/video_ltx25.py b/studio/backend/core/inference/video_ltx25.pynew file mode 100644index 00000000000..1866c06e0cd--- /dev/null+++ b/studio/backend/core/inference/video_ltx25.py@@ -0,0 +1,1389 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""LTX-2.5 on diffusers' LTX-2 pipelines.++LTX-2.5 keeps the LTX-2.3 DiT layout (minus the video FFN bias, plus a keyframe position embedding) and the 2.3 conv+VAE, but conditions on a fine-tuned Gemma 4 12B (``Gemma4UnifiedForConditionalGeneration``) that only transformers+>= 5.10.1 provides. Studio's server runs an older transformers, so the encoder runs in a spawned worker on the+``.venv_t5_510`` sidecar (``video_ltx25_te_worker``) and hands back the packed prompt embeddings; ``pipe.encode_prompt``+is replaced by a call into that worker, and everything after it (connectors, DiT, VAE, vocoder) runs here.++Generation follows the reference two-stage distilled recipe: stage 1 at half resolution on the 8 distilled sigmas,+the latent x2 spatial upsampler, then stage 2 at full resolution on 0.85 / 0.725 / 0.421875 with the stage-1 audio+latents carried over, CFG 1 and every other guidance off, sampled euler-ancestral. Image-to-video conditions the first+latent frame through ``LTX2ConditionPipeline`` at CRF 18, strength 0.7 in stage 1 and 1.0 in stage 2. The dev (full)+DiT runs the pipeline's own single-stage SFT recipe instead.++Everything here is gated on the ``ltx-2.5`` family; no other family reaches this module.+"""++from __future__ import annotations++import os+import queue as _queue+import threading+import time+from pathlib import Path+from typing import Any, Callable, Optional++from loggers import get_logger++logger = get_logger(__name__)++# Reference recipe. Stage 1 is diffusers' DISTILLED_SIGMA_VALUES; stage 2 is the reference workflow's tail (diffusers'+# own STAGE_2_DISTILLED_SIGMA_VALUES starts at 0.909375 instead).+LTX25_STAGE1_SIGMAS: tuple[float, ...] = (+ 1.0,+ 0.99375,+ 0.9875,+ 0.98125,+ 0.975,+ 0.909375,+ 0.725,+ 0.421875,+)+LTX25_STAGE2_SIGMAS: tuple[float, ...] = (0.85, 0.725, 0.421875)+LTX25_IMAGE_CRF = 18+LTX25_STAGE1_IMAGE_STRENGTH = 0.7+LTX25_STAGE2_IMAGE_STRENGTH = 1.0+# Dev (full) DiT: the README's override of the distilled scheduler config.+LTX25_DEV_SCHEDULER_OVERRIDES: dict[str, Any] = {+ "use_dynamic_shifting": True,+ "shift_terminal": 0.1,+}++# Kill switches: "0" runs one full-resolution stage on the distilled sigmas; "euler" swaps the ancestral sampler for+# diffusers' deterministic Euler.+TWO_STAGE_ENV = "UNSLOTH_LTX25_TWO_STAGE"+SAMPLER_ENV = "UNSLOTH_LTX25_SAMPLER"+_OFF = ("0", "false", "no", "off")++# Pack components a load never reads: the dev DiT (single-file dev picks bring their own), the prompt enhancer and its+# processor (Studio never enhances), the diffusion decoder (conv decode is the pipeline default), the temporal+# upsampler (DFR only) and the duration head (Studio always passes num_frames).+_PACK_SKIP_PREFIXES = (+ "transformer_full/",+ "prompt_enhancer/",+ "processor/",+ "diffusion_decoder/",+ "temporal_latent_upsampler/",+ "duration_head/",+)+_PACK_MARKERS = ("duration_head/config.json", "diffusion_decoder/config.json")+# Components handed to from_pretrained as None: the Gemma 4 encoder lives in the worker, the rest is unused.+LTX25_NONE_COMPONENTS = (+ "text_encoder",+ "tokenizer",+ "processor",+ "prompt_enhancer",+ "duration_head",+)+LATENT_UPSAMPLER_SUBFOLDER = "latent_upsampler"+TEXT_ENCODER_MIN_TRANSFORMERS = "5.10.1"+# What the encoder worker holds on the card beyond its weights, on every plan tier: its CUDA context (~0.6 GB on+# Hopper / Blackwell) plus allocator slack. The weights are the family table's text-encoder term.+LTX25_WORKER_RESIDENT_GB = 1.0+# The pack's latent_upsampler/ (995,743,320 bytes), part of the family table's companions; only two-stage loads hold it.+LTX25_LATENT_UPSAMPLER_GB = 1.0++# The split single-file release. A DiT picked from it assembles from the companion files beside it (no Diffusers pack):+# connectors from the DiT file plus the encoder file's text projections, the conv VAE, the audio VAE + vocoder and the+# spatial upscaler. The encoder file embeds its own config and tokenizer.+LTX25_SINGLE_FILE_REPO = "Lightricks/LTX-2.5"+LTX25_SINGLE_TEXT_ENCODER = "text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors"+LTX25_SINGLE_VIDEO_VAE = "vae/ltx-2.5-video-vae-conv-bf16.safetensors"+LTX25_SINGLE_AUDIO_VAE = "vae/ltx-2.5-audio-vae-bf16.safetensors"+LTX25_SINGLE_UPSAMPLER = (+ "latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors"+)+LTX25_SINGLE_COMPANIONS = (+ LTX25_SINGLE_TEXT_ENCODER,+ LTX25_SINGLE_VIDEO_VAE,+ LTX25_SINGLE_AUDIO_VAE,+ LTX25_SINGLE_UPSAMPLER,+)+# Encoder file keys -> Gemma4UnifiedForConditionalGeneration keys (transformers ``key_mapping`` regexes).+LTX25_TEXT_ENCODER_KEY_MAPPING = {+ r"^model\.(layers|embed_tokens|norm)\b": r"model.language_model.\1",+ r"^audio_projector\.": "model.embed_audio.",+ r"^multi_modal_projector\.": "model.embed_vision.",+ r"^vision_model\.": "model.vision_embedder.",+}+LTX25_TEXT_PROJECTION_PREFIX = "text_embedding_projection."++# Lightricks/LTX-2.5-Diffusers transformer/config.json, latent_upsampler/config.json and scheduler config, for+# assembling without the pack. The connectors, conv VAE, audio VAE and vocoder configs equal the 2.3 ones in+# video_ltx2 (checked against the pack).+LTX25_TRANSFORMER_CONFIG: dict[str, Any] = {+ "activation_fn": "gelu-approximate",+ "attention_bias": True,+ "attention_head_dim": 128,+ "attention_out_bias": True,+ "audio_attention_head_dim": 64,+ "audio_cross_attention_dim": 2048,+ "audio_cross_attn_mod": True,+ "audio_ff_bias": True,+ "audio_gated_attn": True,+ "audio_hop_length": 160,+ "audio_in_channels": 128,+ "audio_num_attention_heads": 32,+ "audio_out_channels": 128,+ "audio_patch_size": 1,+ "audio_patch_size_t": 1,+ "audio_pos_embed_max_pos": 20,+ "audio_sampling_rate": 16000,+ "audio_scale_factor": 4,+ "base_height": 2048,+ "base_width": 2048,+ "caption_channels": 3840,+ "causal_offset": 1,+ "cross_attention_dim": 4096,+ "cross_attn_mod": True,+ "cross_attn_timestep_scale_multiplier": 1000,+ "ff_bias": False,+ "gated_attn": True,+ "in_channels": 128,+ "norm_elementwise_affine": False,+ "norm_eps": 1e-06,+ "num_attention_heads": 32,+ "num_layers": 48,+ "out_channels": 128,+ "patch_size": 1,+ "patch_size_t": 1,+ "perturbed_attn": True,+ "pos_embed_max_pos": 20,+ "qk_norm": "rms_norm_across_heads",+ "rope_double_precision": True,+ "rope_theta": 10000.0,+ "rope_type": "split",+ "timestep_scale_multiplier": 1000,+ "use_keyframes_abs_pos_embedding": True,+ "use_prompt_adaln_single": True,+ "use_prompt_embeddings": False,+ "vae_scale_factors": [8, 32, 32],+}+LTX25_UPSAMPLER_CONFIG: dict[str, Any] = {+ "dims": 3,+ "in_channels": 128,+ "mid_channels": 1024,+ "num_blocks_per_stage": 4,+ "rational_spatial_scale": 2.0,+ "spatial_upsample": True,+ "temporal_upsample": False,+ "use_rational_resampler": False,+}+LTX25_SCHEDULER_CONFIG: dict[str, Any] = {+ "base_image_seq_len": 1024,+ "base_shift": 0.95,+ "invert_sigmas": False,+ "max_image_seq_len": 4096,+ "max_shift": 2.05,+ "num_train_timesteps": 1000,+ "shift": 1.0,+ "shift_terminal": None,+ "stochastic_sampling": False,+ "time_shift_type": "exponential",+ "use_beta_sigmas": False,+ "use_dynamic_shifting": False,+ "use_exponential_sigmas": False,+ "use_karras_sigmas": False,+}+++def two_stage_enabled() -> bool:+ return (os.environ.get(TWO_STAGE_ENV) or "").strip().lower() not in _OFF+++def ancestral_enabled() -> bool:+ return (os.environ.get(SAMPLER_ENV) or "").strip().lower() != "euler"+++# ── image-to-video canvas ────────────────────────────────────────────────────++# "Match source" canvas: the default 1280x704 area on a 704 px short edge, 64 px units (two 32 px stages). Same shape+# of rule as MiniMax-H3's, so the frontend's preview (canvas_short_edge / canvas_max_pixels) applies unchanged.+LTX25_CANVAS_SHORT_EDGE = 704+LTX25_CANVAS_MAX_PIXELS = 1280 * 704+LTX25_CANVAS_MULTIPLE = 64+_MIN_ASPECT, _MAX_ASPECT = 0.25, 4.0+++def ltx25_canvas_for_aspect(aspect_width: float, aspect_height: float) -> tuple[int, int]:+ import math++ if aspect_width <= 0 or aspect_height <= 0:+ raise ValueError(+ f"The source image has no usable aspect ratio ({aspect_width}x{aspect_height})."+ )+ ratio = aspect_width / aspect_height+ if not _MIN_ASPECT <= ratio <= _MAX_ASPECT:+ raise ValueError(+ f"LTX-2.5 image-to-video takes aspect ratios from 1:4 to 4:1; this image is "+ f"{aspect_width:g}x{aspect_height:g} ({ratio:.2f}:1). Crop it first or pick a resolution preset."+ )+ short = float(LTX25_CANVAS_SHORT_EDGE)+ width, height = (short * ratio, short) if ratio >= 1.0 else (short, short / ratio)+ area = width * height+ if area > LTX25_CANVAS_MAX_PIXELS:+ scale = math.sqrt(LTX25_CANVAS_MAX_PIXELS / area)+ width, height = width * scale, height * scale++ from .video_families import snap_canvas_within_cap++ return snap_canvas_within_cap(width, height, LTX25_CANVAS_MULTIPLE, LTX25_CANVAS_MAX_PIXELS)+++# The reference image-to-video graph scales the start image's longer side to 1536 px (Lanczos) before the CRF 18 round+# trip; LTX2ConditionPipeline then applies the CRF and fits the result to each stage's canvas (bilinear cover + centre+# crop), in that order.+LTX25_FIRST_FRAME_LONG_EDGE = 1536+++def prepare_ltx25_first_frame(image: Any) -> Any:+ """The start image as the condition pipeline should receive it: longer side at ``LTX25_FIRST_FRAME_LONG_EDGE``,+ aspect kept, not yet cropped to the canvas."""+ from PIL import Image++ source_w, source_h = image.size+ scale = LTX25_FIRST_FRAME_LONG_EDGE / max(source_w, source_h)+ size = (max(1, round(source_w * scale)), max(1, round(source_h * scale)))+ return image if size == image.size else image.resize(size, Image.LANCZOS)+++# ── base-pack file selection ─────────────────────────────────────────────────+++def is_ltx25_pack(names: Any) -> bool:+ """Whether a Diffusers repo listing is an LTX-2.5 pack (it ships a duration head / diffusion decoder)."""+ return any(name in _PACK_MARKERS for name in names)+++def _component(name: str) -> str:+ return name.split("/", 1)[0] if "/" in name else ""+++def _shard_set(name: str) -> Optional[str]:+ """``-of-00008`` style shard-set key of a sharded weight file, or None."""+ leaf = name.rsplit("/", 1)[-1]+ if "-of-" not in leaf:+ return None+ return leaf.rsplit("-of-", 1)[1].split(".", 1)[0]+++def ltx25_pack_files(+ files: list[tuple[str, int]],+ shards: Optional[dict[str, frozenset[str]]] = None,+ dev: bool = False,+) -> list[tuple[str, int]]:+ """The files of an LTX-2.5 pack a load reads.++ Drops the unused components above, and the duplicate weight sets the pack ships: ``transformer/`` carries both a+ 4-shard and an 8-shard set and ``connectors/`` a sharded and an unsharded copy. With ``shards`` (component ->+ file names its ``*.index.json`` lists) only the indexed set stays. Without it (an index that could not be read)+ the unsharded copy goes when an index exists and the coarsest shard set is kept, the one the official indexes+ name. A ``dev`` load (single stage) also drops the latent upsampler, which only the two-stage recipe attaches."""+ names = {name for name, _ in files}+ kept: list[tuple[str, int]] = []+ by_component: dict[str, dict[str, list[tuple[str, int]]]] = {}+ skip = _PACK_SKIP_PREFIXES+ if not ltx25_uses_upsampler(dev):+ skip = skip + (f"{LATENT_UPSAMPLER_SUBFOLDER}/",)+ for name, size in files:+ if name.startswith(skip):+ continue+ component = _component(name)+ leaf = name.rsplit("/", 1)[-1]+ weight = leaf.endswith(".safetensors")+ if component and weight:+ index_name = None+ for candidate in names:+ if candidate.startswith(component + "/") and candidate.endswith(+ ".safetensors.index.json"+ ):+ index_name = candidate+ break+ if index_name is not None:+ if shards is not None and component in shards:+ if leaf in shards[component]:+ kept.append((name, size))+ continue+ key = _shard_set(name)+ if key is None:+ # an unsharded duplicate of an indexed component+ continue+ by_component.setdefault(component, {}).setdefault(key, []).append((name, size))+ continue+ kept.append((name, size))+ for sets in by_component.values():+ # No index read: one set, the coarsest split (the official pack indexes its 4-shard transformer, not the 8).+ best = min(sets.items(), key = lambda item: (len(item[1]), item[0]))[1]+ kept.extend(best)+ order = {name: i for i, (name, _) in enumerate(files)}+ return sorted(kept, key = lambda item: order.get(item[0], 0))+++def ltx25_shards_from_indexes(indexes: dict[str, Any]) -> dict[str, frozenset[str]]:+ """component -> the shard file names its parsed ``*.index.json`` (``{path: json}``) maps weights to."""+ out: dict[str, frozenset[str]] = {}+ for path, payload in indexes.items():+ weight_map = payload.get("weight_map") if isinstance(payload, dict) else None+ if not isinstance(weight_map, dict):+ continue+ out[_component(path)] = frozenset(str(v) for v in weight_map.values())+ return out+++# ── transformer from a single file / GGUF ────────────────────────────────────+++def load_ltx25_transformer(+ checkpoint_path: Path | str,+ *,+ base_repo: str,+ torch_dtype: Any,+ is_gguf: bool,+ hf_token: Optional[str],+ cache_dir: Optional[str] = None,+ local_files_only: bool = False,+ device: Optional[Any] = None,+) -> Any:+ """The LTX-2.5 DiT of a split single file or GGUF. Only the DiT keys are read; the connectors in the file are the+ pack's shared ``connectors/`` (loaded from the base like the VAEs). The base's ``transformer/config.json`` already+ carries the 2.5 deltas (``ff_bias=False``, ``use_keyframes_abs_pos_embedding=True``), so no overrides; the keys+ take the same ``prompt_adaln_single`` pre-rename the 2.3 assembly applies."""+ import diffusers+ from diffusers import LTX2VideoTransformer3DModel+ from diffusers.loaders.single_file_utils import load_single_file_checkpoint++ from .video_ltx2 import _ltx23_pre_convert, ltx23_is_dit_key++ state = load_single_file_checkpoint(str(checkpoint_path))+ dit_state = _ltx23_pre_convert({k: v for k, v in state.items() if ltx23_is_dit_key(k)})+ del state+ if any(k.endswith((".weight_scale", ".input_scale")) for k in dit_state):+ raise ValueError(+ "This LTX-2.5 checkpoint stores scaled fp8 weights, which this loader does not dequantize. Use the bf16 "+ "file, the int8-convrot file or a GGUF quant instead."+ )+ kwargs: dict[str, Any] = {+ "config": _transformer_config_source(base_repo),+ "subfolder": "transformer",+ "torch_dtype": torch_dtype,+ "token": hf_token,+ "cache_dir": cache_dir,+ "local_files_only": local_files_only,+ }+ if is_gguf:+ kwargs["quantization_config"] = diffusers.GGUFQuantizationConfig(compute_dtype = torch_dtype)+ elif device is not None:+ kwargs["device"] = device+ return LTX2VideoTransformer3DModel.from_single_file(dit_state, **kwargs)+++def load_ltx25_comfy_transformer(+ checkpoint_path: Path | str,+ scan: Any,+ *,+ base_repo: str,+ torch_dtype: Any,+ hf_token: Optional[str],+ cache_dir: Optional[str] = None,+ local_files_only: bool = False,+ int8_backend: Optional[str] = None,+ fp8_backend: Optional[str] = None,+ family: Optional[str] = None,+ target: Any = None,+ logger: Any = None,+) -> Any:+ """The DiT of an int8-convrot LTX-2.5 file (``...-int8-convrot``), keeping int8 / fp8 codes where+ ``load_comfy_quant_transformer`` can; same key handling as ``load_ltx25_transformer``."""+ from diffusers import LTX2VideoTransformer3DModel++ from .diffusion_comfy_quant import load_comfy_quant_transformer+ from .video_ltx2 import _ltx23_pre_convert, ltx23_is_dit_key++ return load_comfy_quant_transformer(+ LTX2VideoTransformer3DModel,+ str(checkpoint_path),+ scan,+ {+ "torch_dtype": torch_dtype,+ "config": _transformer_config_source(base_repo),+ "subfolder": "transformer",+ "token": hf_token,+ "cache_dir": cache_dir,+ "local_files_only": local_files_only,+ },+ int8_backend = int8_backend,+ fp8_backend = fp8_backend,+ family = family,+ target = target,+ logger = logger,+ keep_key = ltx23_is_dit_key,+ pre_convert = _ltx23_pre_convert,+ )+++def load_latent_upsampler(+ base_repo: str,+ *,+ torch_dtype: Any,+ hf_token: Optional[str],+ cache_dir: Optional[str] = None,+ local_files_only: bool = False,+) -> Any:+ from diffusers.pipelines.ltx2.latent_upsampler import LTX2LatentUpsamplerModel+ if is_ltx25_single_file_base(base_repo):+ from safetensors.torch import load_file++ from .video_ltx2 import _build_from_config++ path = ltx25_companion_path(base_repo, LTX25_SINGLE_UPSAMPLER, hf_token, local_files_only)+ return _build_from_config(+ LTX2LatentUpsamplerModel, LTX25_UPSAMPLER_CONFIG, load_file(path), {}, torch_dtype+ )+ return LTX2LatentUpsamplerModel.from_pretrained(+ base_repo,+ subfolder = LATENT_UPSAMPLER_SUBFOLDER,+ torch_dtype = torch_dtype,+ token = hf_token,+ cache_dir = cache_dir,+ local_files_only = local_files_only,+ )+++# ── the split single-file layout as its own base ────────────────────────────+++def is_ltx25_single_file_base(base: Optional[str]) -> bool:+ """Whether ``base`` is the split single-file release (hub id) or a local folder with its layout (the encoder file+ and the conv VAE beside the DiTs), rather than a Diffusers pack."""+ text = (base or "").strip()+ if not text:+ return False+ path = Path(text).expanduser()+ if path.is_dir():+ return (path / LTX25_SINGLE_TEXT_ENCODER).is_file() and (+ path / LTX25_SINGLE_VIDEO_VAE+ ).is_file()+ return text.lower() == LTX25_SINGLE_FILE_REPO.lower()+++def is_ltx25_single_file_listing(names: Any) -> bool:+ """Whether a repo listing is the split single-file release (it carries every companion file)."""+ present = set(names)+ return all(name in present for name in LTX25_SINGLE_COMPANIONS)+++def ltx25_uses_upsampler(dev: bool) -> bool:+ """Whether a load attaches the latent upsampler: only the two-stage distilled recipe runs it."""+ return not dev and two_stage_enabled()+++def ltx25_single_file_companions(+ files: list[tuple[str, int]], dev: bool = False+) -> list[tuple[str, int]]:+ """The (rfilename, size) entries a load from the single-file release reads besides the picked DiT."""+ wanted = set(LTX25_SINGLE_COMPANIONS)+ if not ltx25_uses_upsampler(dev):+ wanted.discard(LTX25_SINGLE_UPSAMPLER)+ return [(name, size) for name, size in files if name in wanted]+++def ltx25_default_base(repo_id: Optional[str]) -> Optional[str]:+ """A DiT picked from the single-file release (or a local copy of it) uses that release as its base."""+ return repo_id if is_ltx25_single_file_base(repo_id) else None+++def ltx25_companion_path(+ base: str,+ filename: str,+ hf_token: Optional[str],+ local_files_only: bool = False,+) -> str:+ """Local path of one companion file of a single-file base (downloaded into the hub cache when needed)."""+ path = Path(base).expanduser()+ if path.is_dir():+ target = path / filename+ if not target.is_file():+ raise FileNotFoundError(+ f"LTX-2.5 needs '{filename}' beside the DiT in '{base}', and it is missing."+ )+ return str(target)+ from utils.hf_xet_fallback import hf_hub_download_with_xet_fallback++ return hf_hub_download_with_xet_fallback(+ base,+ filename,+ hf_token,+ reuse_other_cache_root = True,+ local_files_only = local_files_only,+ )+++def ltx25_transformer_config_dir() -> str:+ """A local folder holding ``transformer/config.json`` (the pack's 2.5 transformer config), for+ ``from_single_file(config=...)`` when there is no pack to read it from."""+ import json+ import tempfile++ root = Path(tempfile.gettempdir()) / "unsloth_ltx25_config"+ target = root / "transformer" / "config.json"+ payload = json.dumps(+ {"_class_name": "LTX2VideoTransformer3DModel", **LTX25_TRANSFORMER_CONFIG},+ indent = 1,+ sort_keys = True,+ )+ if not target.is_file() or target.read_text(encoding = "utf-8") != payload:+ target.parent.mkdir(parents = True, exist_ok = True)+ # A per-call scratch name: two loads in one process (a superseded one still building) may both get here.+ fd, scratch = tempfile.mkstemp(dir = target.parent, prefix = "config.", suffix = ".tmp")+ try:+ with os.fdopen(fd, "w", encoding = "utf-8") as fh:+ fh.write(payload)+ os.replace(scratch, target)+ except BaseException:+ Path(scratch).unlink(missing_ok = True)+ raise+ return str(root)+++def _transformer_config_source(base_repo: str) -> str:+ return ltx25_transformer_config_dir() if is_ltx25_single_file_base(base_repo) else base_repo+++def _read_tensors(path: str, keep: Callable[[str], bool]) -> dict[str, Any]:+ """The tensors of ``path`` whose names pass ``keep``, read selectively (GGUF files are read whole)."""+ if not str(path).lower().endswith(".safetensors"):+ from diffusers.loaders.single_file_utils import load_single_file_checkpoint+ return {k: v for k, v in load_single_file_checkpoint(str(path)).items() if keep(k)}+ from safetensors import safe_open++ with safe_open(str(path), framework = "pt", device = "cpu") as handle:+ return {key: handle.get_tensor(key) for key in handle.keys() if keep(key)}+++def assemble_ltx25_single_file_pipeline(+ transformer: Any,+ checkpoint_path: Path | str,+ *,+ base: str,+ torch_dtype: Any,+ hf_token: Optional[str],+ local_files_only: bool = False,+) -> Any:+ """``LTX2Pipeline`` from the split single-file release: the given DiT, the connectors of the DiT file plus the+ encoder file's text projections, the conv VAE and the audio VAE + vocoder. Text encoder and tokenizer stay None+ (the worker owns them); the upsampler is loaded by ``attach_to_pipeline``."""+ from .ltx2_import_compat import ensure_ltx2_pipelines_importable++ ensure_ltx2_pipelines_importable(logger)+ from diffusers import FlowMatchEulerDiscreteScheduler, LTX2Pipeline+ from safetensors.torch import load_file++ from .video_ltx2 import (+ _CONNECTORS_CONFIG,+ _CONNECTORS_RENAME,+ _build_from_config,+ _checkpoint_group,+ load_ltx23_audio_vae_and_vocoder,+ load_ltx23_vae,+ )+ from diffusers.pipelines.ltx2.connectors import LTX2TextConnectors++ connector_state = {+ _checkpoint_group(key)[1]: value+ for key, value in _read_tensors(+ str(checkpoint_path), lambda key: _checkpoint_group(key)[0] == "connectors"+ ).items()+ }+ if not connector_state:+ raise ValueError(f"'{Path(str(checkpoint_path)).name}' carries no LTX-2.5 text connectors.")+ if any(+ name.endswith((".weight_scale", ".input_scale", ".comfy_quant")) for name in connector_state+ ):+ raise ValueError(+ "This LTX-2.5 file stores its text connectors quantized, which the single-file assembly does not "+ "dequantize. Load it on the Lightricks/LTX-2.5-Diffusers base (base_repo), or pick the bf16 DiT or a GGUF "+ "quant."+ )+ encoder_path = ltx25_companion_path(base, LTX25_SINGLE_TEXT_ENCODER, hf_token, local_files_only)+ connector_state.update(+ _read_tensors(encoder_path, lambda key: key.startswith(LTX25_TEXT_PROJECTION_PREFIX))+ )+ connectors = _build_from_config(+ LTX2TextConnectors, _CONNECTORS_CONFIG, connector_state, _CONNECTORS_RENAME, torch_dtype+ )+ vae = load_ltx23_vae(+ load_file(ltx25_companion_path(base, LTX25_SINGLE_VIDEO_VAE, hf_token, local_files_only)),+ variant = "distilled",+ torch_dtype = torch_dtype,+ hf_token = hf_token,+ local_files_only = local_files_only,+ )+ combined = load_file(+ ltx25_companion_path(base, LTX25_SINGLE_AUDIO_VAE, hf_token, local_files_only)+ )+ audio_vae, vocoder = load_ltx23_audio_vae_and_vocoder(+ {k[len("audio_vae.") :]: v for k, v in combined.items() if k.startswith("audio_vae.")},+ {k[len("vocoder.") :]: v for k, v in combined.items() if k.startswith("vocoder.")},+ variant = "distilled",+ torch_dtype = torch_dtype,+ hf_token = hf_token,+ local_files_only = local_files_only,+ )+ del combined+ logger.info("video.ltx25_single_file: assembled from %s", base)+ return LTX2Pipeline(+ scheduler = FlowMatchEulerDiscreteScheduler.from_config(LTX25_SCHEDULER_CONFIG),+ vae = vae,+ audio_vae = audio_vae,+ text_encoder = None,+ tokenizer = None,+ connectors = connectors,+ transformer = transformer,+ vocoder = vocoder,+ )+++# ── the Gemma 4 encoder worker ───────────────────────────────────────────────+++def encoder_resident_for_plan(plan: Any) -> bool:+ """Whether the encoder worker keeps Gemma 4 on the card, by the tier the memory plan budgeted.++ The plan prices the family's text encoder (the table's 23.9 GB) as if it were in-process: resident under ``none``+ and under ``group`` with resident companions, streamed under ``group`` with streamed text encoders and under+ ``streaming`` / ``sequential``, alone on the card under ``model``. The worker cannot stream, so on every tier that did+ not budget it resident it keeps the encoder on the host and onloads it only for an encode, when the card has room+ (else it encodes on the CPU; see ``video_ltx25_te_worker._encode_device``)."""+ from .diffusion_memory import OFFLOAD_GROUP, OFFLOAD_NONE++ policy = getattr(plan, "offload_policy", None)+ if policy == OFFLOAD_NONE:+ return True+ return policy == OFFLOAD_GROUP and not bool(getattr(plan, "stream_text_encoders", False))+++def sidecar_missing_message(venv_dir: str) -> str:+ return (+ "LTX-2.5's text encoder is a Gemma 4 model (Gemma4UnifiedForConditionalGeneration) that needs transformers "+ f">= {TEXT_ENCODER_MIN_TRANSFORMERS}. Studio keeps that in its transformers 5.10 sidecar at '{venv_dir}', "+ "which is missing and could not be installed. Re-run the Studio installer (or check the network so Studio "+ "can rebuild the sidecar), then load LTX-2.5 again."+ )+++def ensure_text_encoder_sidecar() -> str:+ """The ``.venv_t5_510`` dir, created / repaired the way the chat and training workers do it; RuntimeError naming+ the sidecar when it cannot be made usable."""+ from utils.transformers_version import _VENV_T5_510_DIR, _ensure_venv_t5_510_exists++ try:+ ok = _ensure_venv_t5_510_exists()+ except Exception as exc: # noqa: BLE001 -- surface as the named sidecar failure+ logger.warning("video.ltx25_te: sidecar check failed: %s", exc)+ ok = False+ if not ok:+ raise RuntimeError(sidecar_missing_message(_VENV_T5_510_DIR))+ return _VENV_T5_510_DIR+++def _server_reserved_mib(device: Optional[str]) -> Optional[int]:+ """What this (server) process holds on ``device`` right now, for the worker's budget check."""+ kind = str(device or "").split(":", 1)[0]+ if kind not in ("cuda", "xpu"):+ return None+ try:+ import torch+ return int(getattr(torch, kind).memory_reserved(torch.device(str(device)))) >> 20+ except Exception: # noqa: BLE001 -- unknown: the worker judges by free memory alone+ return None+++class TextEncoderWorkerError(RuntimeError):+ pass+++class Ltx25TextEncoderClient:+ """One spawned encoder worker for one loaded LTX-2.5 pipeline.++ ``start`` spawns it (the Gemma 4 load overlaps the DiT load); ``wait_ready`` blocks until it has the model;+ ``encode`` sends prompts and returns ``(prompt_embeds, attention_mask)`` on the host. A dead worker is restarted on+ the next encode. ``close`` stops it (unload / failed load)."""++ # Two recent encodes kept on the host: a re-render with the same prompt (seed sweeps) skips the worker.+ _CACHE_ENTRIES = 2++ def __init__(+ self,+ *,+ repo: str,+ hf_token: Optional[str],+ cache_dir: Optional[str],+ local_files_only: bool,+ device: str,+ dtype: str,+ resident: bool,+ venv_dir: str,+ cancel_event: Optional[threading.Event] = None,+ single_file: Optional[str] = None,+ budget_mib: Optional[int] = None,+ ) -> None:+ self.config = {+ "repo": repo,+ # The single-file release's encoder file (config and tokenizer embedded) instead of pack subfolders.+ "single_file": single_file,+ "key_mapping": dict(LTX25_TEXT_ENCODER_KEY_MAPPING) if single_file else None,+ "hf_token": hf_token,+ "cache_dir": cache_dir,+ "local_files_only": bool(local_files_only),+ "device": device,+ "dtype": dtype,+ "resident": bool(resident),+ "venv_dir": venv_dir,+ # The load's memory budget: a non-resident encoder onloads only into what the server leaves of it.+ "budget_mib": budget_mib,+ }+ self.cancel_event = cancel_event+ self._proc: Any = None+ self._cmd: Any = None+ self._resp: Any = None+ self._ready = False+ self._seq = 0+ self._lock = threading.Lock()+ self._cache: list[tuple[tuple, Any]] = []+ self.info: dict[str, Any] = {}+ self.last_encode: dict[str, Any] = {}++ # process management+ def start(self) -> None:+ import multiprocessing as mp++ from utils.hf_cache_settings import child_environment_for_spawn, get_hf_cache_paths+ from utils.native_path_leases import (+ native_path_secret_removed_for_child_start,+ run_without_native_path_secret,+ )++ ctx = mp.get_context("spawn")+ cache_env = get_hf_cache_paths().child_env({})+ with child_environment_for_spawn(cache_env), native_path_secret_removed_for_child_start():+ self._cmd = ctx.Queue()+ self._resp = ctx.Queue()+ proc = ctx.Process(+ target = run_without_native_path_secret,+ args = ("core.inference.video_ltx25_te_worker", "run_text_encoder_worker", cache_env),+ kwargs = {"cmd_queue": self._cmd, "resp_queue": self._resp, "config": self.config},+ daemon = True,+ )+ from utils.process_lifetime import spawn_on_lifetime_thread++ # The child arms PR_SET_PDEATHSIG, which follows the spawning THREAD: a load runs on a short-lived thread,+ # and a worker started there dies the moment the load returns.+ spawn_on_lifetime_thread(proc.start)+ self._proc = proc+ self._ready = False+ try:+ from utils.process_lifetime import adopt_pid+ adopt_pid(proc.pid)+ except Exception: # noqa: BLE001 -- the daemon flag still ties it to this process+ pass+ logger.info("video.ltx25_te: started the Gemma 4 encoder worker (pid %s)", proc.pid)++ def alive(self) -> bool:+ return self._proc is not None and self._proc.is_alive()++ def _get(+ self,+ cancel: Optional[threading.Event],+ what: str,+ timeout: Optional[float] = None,+ request_id: Optional[int] = None,+ ) -> dict:+ """The next worker reply. With ``request_id``, an error for another request (one a cancel abandoned) is skipped+ rather than raised, so it cannot fail the encode that follows."""+ began = time.monotonic()+ while True:+ if cancel is not None and cancel.is_set():+ from .video_families import VIDEO_CANCELLED_MSG+ raise RuntimeError(VIDEO_CANCELLED_MSG)+ try:+ msg = self._resp.get(timeout = 0.25)+ except _queue.Empty:+ if not self.alive():+ code = getattr(self._proc, "exitcode", None)+ self._proc = None+ raise TextEncoderWorkerError(+ f"The LTX-2.5 text encoder worker exited (code {code}) while {what}. Check the server log "+ "for its error; the next request restarts it."+ )+ if timeout is not None and time.monotonic() - began > timeout:+ raise TextEncoderWorkerError(+ f"The LTX-2.5 text encoder worker timed out while {what}."+ )+ continue+ if msg.get("type") == "error":+ if (+ request_id is not None+ and msg.get("id") is not None+ and msg.get("id") != request_id+ ):+ continue+ raise TextEncoderWorkerError(str(msg.get("error") or "unknown error"))+ return msg++ def wait_ready(self, cancel: Optional[threading.Event] = None) -> dict:+ if self._ready:+ return self.info+ msg = self._get(cancel, "loading the Gemma 4 encoder")+ if msg.get("type") != "ready":+ raise TextEncoderWorkerError(+ f"Unexpected reply from the text encoder worker: {msg.get('type')}"+ )+ self._ready = True+ self.info = {k: v for k, v in msg.items() if k != "type"}+ logger.info("video.ltx25_te: encoder ready %s", self.info)+ return self.info++ def close(self) -> None:+ proc, self._proc = self._proc, None+ self._ready = False+ self._cache.clear()+ if proc is None:+ return+ try:+ self._cmd.put({"type": "shutdown"})+ proc.join(timeout = 10)+ except Exception: # noqa: BLE001 -- fall through to terminate+ pass+ if proc.is_alive():+ proc.terminate()+ proc.join(timeout = 5)+ if proc.is_alive():+ proc.kill()+ logger.info("video.ltx25_te: encoder worker stopped")++ # encoding+ def encode(+ self,+ prompts: list[str],+ max_sequence_length: int,+ cancel: Optional[threading.Event] = None,+ ) -> tuple[Any, Any]:+ key = (tuple(prompts), int(max_sequence_length))+ with self._lock:+ for cached_key, value in self._cache:+ if cached_key == key:+ return value[0].clone(), value[1].clone()+ if not self.alive():+ logger.warning("video.ltx25_te: encoder worker not running; restarting it")+ self.start()+ cancel = cancel if cancel is not None else self.cancel_event+ self.wait_ready(cancel)+ self._seq += 1+ seq = self._seq+ self._cmd.put(+ {+ "type": "encode",+ "id": seq,+ "prompts": list(prompts),+ "max_sequence_length": int(max_sequence_length),+ "server_reserved_mib": _server_reserved_mib(self.config.get("device")),+ }+ )+ while True:+ msg = self._get(cancel, "encoding the prompt", request_id = seq)+ # A reply to a request a cancel abandoned arrives first; skip it.+ if msg.get("type") == "embeds" and msg.get("id") == seq:+ break+ embeds, mask = msg["embeds"], msg["mask"]+ self.last_encode = {+ k: v for k, v in msg.items() if k not in ("type", "id", "embeds", "mask")+ }+ logger.info(+ "video.ltx25_te: encoded on %s %s", self.last_encode.get("device"), self.last_encode+ )+ self._cache.append((key, (embeds, mask)))+ del self._cache[: -self._CACHE_ENTRIES]+ return embeds.clone(), mask.clone()+++def install_remote_encode_prompt(pipe: Any, client: Ltx25TextEncoderClient) -> None:+ """Replace ``pipe.encode_prompt`` with the worker round trip, keeping diffusers' signature and semantics (packed+ hidden states, left padding, CFG negative, ``num_videos_per_prompt`` repeat), so Studio's prompt cache wraps it+ like any other encoder."""++ def encode_prompt(+ prompt: Any = None,+ negative_prompt: Any = None,+ do_classifier_free_guidance: bool = True,+ num_videos_per_prompt: int = 1,+ prompt_embeds: Any = None,+ negative_prompt_embeds: Any = None,+ prompt_attention_mask: Any = None,+ negative_prompt_attention_mask: Any = None,+ max_sequence_length: int = 1024,+ scale_factor: int = 8,+ device: Any = None,+ dtype: Any = None,+ ) -> tuple[Any, Any, Any, Any]:+ device = device or pipe._execution_device+ dtype = dtype or getattr(getattr(pipe, "transformer", None), "dtype", None)++ def _one(texts: list[str]) -> tuple[Any, Any]:+ embeds, mask = client.encode(texts, max_sequence_length)+ batch = embeds.shape[0]+ embeds = embeds.to(device = device, dtype = dtype)+ mask = mask.to(device = device)+ seq_len = embeds.shape[1]+ embeds = embeds.repeat(1, num_videos_per_prompt, 1).view(+ batch * num_videos_per_prompt, seq_len, -1+ )+ mask = mask.view(batch, -1).repeat(num_videos_per_prompt, 1)+ return embeds, mask++ prompt = [prompt] if isinstance(prompt, str) else prompt+ batch_size = len(prompt) if prompt is not None else prompt_embeds.shape[0]+ if prompt_embeds is None:+ prompt_embeds, prompt_attention_mask = _one([p.strip() for p in prompt])+ if do_classifier_free_guidance and negative_prompt_embeds is None:+ negative_prompt = negative_prompt or ""+ negative_prompt = (+ batch_size * [negative_prompt]+ if isinstance(negative_prompt, str)+ else negative_prompt+ )+ if batch_size != len(negative_prompt):+ raise ValueError(+ f"`negative_prompt` has batch size {len(negative_prompt)}, but `prompt` has batch size "+ f"{batch_size}."+ )+ negative_prompt_embeds, negative_prompt_attention_mask = _one(+ [p.strip() for p in negative_prompt]+ )+ return (+ prompt_embeds,+ prompt_attention_mask,+ negative_prompt_embeds,+ negative_prompt_attention_mask,+ )++ pipe.encode_prompt = encode_prompt+ pipe._unsloth_ltx25_encoder = client+++def close_encoder(pipe: Any) -> None:+ client = getattr(pipe, "_unsloth_ltx25_encoder", None) if pipe is not None else None+ if client is not None:+ try:+ client.close()+ except Exception as exc: # noqa: BLE001 -- teardown is best-effort+ logger.warning("video.ltx25_te: could not stop the encoder worker: %s", exc)+++def start_text_encoder(+ *,+ repo: str,+ hf_token: Optional[str],+ cache_dir: Optional[str],+ local_files_only: bool,+ device: str,+ dtype: str,+ resident: bool,+ budget_mib: Optional[int] = None,+) -> Ltx25TextEncoderClient:+ """Check the sidecar (a named refusal before any weight is read), then spawn the encoder worker so the Gemma 4+ load overlaps the DiT load."""+ venv_dir = ensure_text_encoder_sidecar()+ client = Ltx25TextEncoderClient(+ repo = repo,+ hf_token = hf_token,+ cache_dir = cache_dir,+ local_files_only = local_files_only,+ device = device,+ dtype = dtype,+ resident = resident,+ venv_dir = venv_dir,+ single_file = LTX25_SINGLE_TEXT_ENCODER if is_ltx25_single_file_base(repo) else None,+ budget_mib = budget_mib,+ )+ client.start()+ return client+++def attach_to_pipeline(+ pipe: Any,+ client: Ltx25TextEncoderClient,+ *,+ dev: bool,+ base_repo: str,+ torch_dtype: Any,+ hf_token: Optional[str],+ cache_dir: Optional[str],+ local_files_only: bool,+) -> None:+ """Wire a freshly built pipe for LTX-2.5: the remote ``encode_prompt``, the variant's sampler and (distilled,+ two-stage) the latent upsampler, held beside the pipe so the memory plan leaves it alone."""+ install_remote_encode_prompt(pipe, client)+ pipe._unsloth_ltx25_dev = bool(dev)+ pipe._unsloth_ltx25_sampler = prepare_scheduler(pipe, dev = dev)+ pipe._unsloth_ltx25_upsampler = (+ load_latent_upsampler(+ base_repo,+ torch_dtype = torch_dtype,+ hf_token = hf_token,+ cache_dir = cache_dir,+ local_files_only = local_files_only,+ )+ if not dev and two_stage_enabled()+ else None+ )+++# ── sampler ──────────────────────────────────────────────────────────────────+++def make_ancestral_scheduler(base_scheduler: Any) -> Any:+ """``FlowMatchEulerDiscreteScheduler`` stepping euler-ancestral in its rectified-flow form (eta 1, s_noise 1):+ Euler down to ``sigma_down = sigma_next**2 / sigma``, then re-noise up to ``sigma_next``. The last step (to 0)+ is plain Euler. Tokens named by ``keep_tokens`` (the conditioned first latent frame of an image-to-video stage)+ take the deterministic Euler step, so the conditioning the pipeline blends in x0 space is not re-noised. Noise+ comes from ``noise_generator`` (the request's generator) for reproducible renders."""+ import torch+ from diffusers import FlowMatchEulerDiscreteScheduler+ from diffusers.utils.torch_utils import randn_tensor++ class LTX25EulerAncestralScheduler(FlowMatchEulerDiscreteScheduler):+ noise_generator: Any = None+ # (keep, total): when a sample has ``total`` tokens, its first ``keep`` step deterministically.+ keep_tokens: Optional[tuple[int, int]] = None++ def __deepcopy__(self, memo: dict) -> Any:+ # The pipelines deep-copy this for the audio stream; the generator is shared, not cloned, so the audio+ # draws continue the request's stream instead of replaying the video's.+ import copy++ new = self.__class__.__new__(self.__class__)+ memo[id(self)] = new+ for key, value in self.__dict__.items():+ setattr(new, key, value if key == "noise_generator" else copy.deepcopy(value, memo))+ return new++ def step(self, model_output, timestep, sample, *args: Any, **kwargs: Any): # type: ignore[override]+ return_dict = kwargs.get("return_dict", True)+ if self.step_index is None:+ self._init_step_index(timestep)+ index = self.step_index+ sigma = self.sigmas[index]+ sigma_next = self.sigmas[index + 1]+ work = sample.to(torch.float32)+ out = model_output.to(torch.float32)+ deterministic = work + (sigma_next - sigma) * out+ if float(sigma_next) <= 0.0 or float(sigma) <= 0.0:+ prev = deterministic+ else:+ denoised = work - sigma * out+ sigma_down = sigma_next * sigma_next / sigma+ ratio = sigma_down / sigma+ x_down = ratio * work + (1.0 - ratio) * denoised+ alpha_next = 1.0 - sigma_next+ alpha_down = 1.0 - sigma_down+ renoise = torch.sqrt(+ torch.clamp(+ sigma_next**2 - sigma_down**2 * alpha_next**2 / alpha_down**2, min = 0.0+ )+ )+ noise = randn_tensor(+ work.shape,+ generator = self.noise_generator,+ device = work.device,+ dtype = torch.float32,+ )+ prev = (alpha_next / alpha_down) * x_down + renoise * noise+ keep = self.keep_tokens+ if keep is not None and prev.ndim == 3 and prev.shape[1] == keep[1] and keep[0] > 0:+ prev[:, : keep[0]] = deterministic[:, : keep[0]]+ self._step_index += 1+ prev = prev.to(model_output.dtype)+ if not return_dict:+ return (prev,)+ from diffusers.schedulers.scheduling_flow_match_euler_discrete import (+ FlowMatchEulerDiscreteSchedulerOutput,+ )++ return FlowMatchEulerDiscreteSchedulerOutput(prev_sample = prev)++ return LTX25EulerAncestralScheduler.from_config(base_scheduler.config)+++def prepare_scheduler(pipe: Any, *, dev: bool) -> str:+ """The family's sampler on the loaded pipe: dev = diffusers Euler with the README's dynamic shifting, distilled =+ euler-ancestral (unless ``UNSLOTH_LTX25_SAMPLER=euler``). Returns its name for the status."""+ from diffusers import FlowMatchEulerDiscreteScheduler++ scheduler = pipe.scheduler+ if dev:+ pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(+ scheduler.config, **LTX25_DEV_SCHEDULER_OVERRIDES+ )+ return "euler"+ if ancestral_enabled():+ pipe.scheduler = make_ancestral_scheduler(scheduler)+ return "euler_ancestral"+ return "euler"+++# ── generation ───────────────────────────────────────────────────────────────+++def condition_pipe(pipe: Any) -> Any:+ """``LTX2ConditionPipeline`` over the loaded pipe's modules (built once), sharing its video processor so Studio's+ frame conversion applies, and its remote ``encode_prompt``."""+ cached = getattr(pipe, "_unsloth_ltx25_condition_pipe", None)+ if cached is not None:+ return cached+ import inspect++ from .ltx2_import_compat import ensure_ltx2_pipelines_importable++ ensure_ltx2_pipelines_importable(logger)+ from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2ConditionPipeline++ params = inspect.signature(LTX2ConditionPipeline.__init__).parameters+ components = {k: v for k, v in pipe.components.items() if k in params}+ cond = LTX2ConditionPipeline(**components)+ cond.video_processor = pipe.video_processor+ cond.encode_prompt = pipe.encode_prompt+ try:+ cond.set_progress_bar_config(disable = True)+ except Exception: # noqa: BLE001 -- cosmetic+ pass+ pipe._unsloth_ltx25_condition_pipe = cond+ return cond+++def _guidance_off(call_params: Any) -> dict[str, float]:+ keys = {+ "stg_scale": 0.0,+ "modality_scale": 1.0,+ "guidance_rescale": 0.0,+ "audio_guidance_scale": 1.0,+ "audio_stg_scale": 0.0,+ "audio_modality_scale": 1.0,+ "audio_guidance_rescale": 0.0,+ }+ return {k: v for k, v in keys.items() if k in call_params}+++def stage_steps(steps: int, *, dev: bool) -> tuple[int, int]:+ """(stage 1, stage 2) denoise steps a request runs."""+ if dev or not two_stage_enabled():+ return int(steps), 0+ return int(steps), len(LTX25_STAGE2_SIGMAS)+++def render(+ pipe: Any,+ kwargs: dict[str, Any],+ *,+ dev: bool,+ image: Any = None,+ upsampler: Any = None,+ on_step: Optional[Callable[..., Any]] = None,+ cancel: Optional[threading.Event] = None,+) -> Any:+ """Run one LTX-2.5 request. ``kwargs`` is the generic video call (prompt, size, frames, steps, guidance,+ frame_rate, generator, negative_prompt, callback); returns the final pipeline output (``.frames`` / ``.audio``)."""+ try:+ return _render(+ pipe, kwargs, dev = dev, image = image, upsampler = upsampler, on_step = on_step, cancel = cancel+ )+ finally:+ if image is not None:+ # The condition pipeline shares pipe's modules but not its offload-hook list, so on every exit (dev,+ # single stage, two stage, cancel) pipe's own hooks are reset here, or its last onloaded module stays on+ # the card.+ free = getattr(pipe, "maybe_free_model_hooks", None)+ if callable(free):+ try:+ free()+ except Exception: # noqa: BLE001 -- best-effort offload reset+ pass+++def _render(+ pipe: Any,+ kwargs: dict[str, Any],+ *,+ dev: bool,+ image: Any = None,+ upsampler: Any = None,+ on_step: Optional[Callable[..., Any]] = None,+ cancel: Optional[threading.Event] = None,+) -> Any:+ import inspect++ import torch++ from .video_ltx2 import ltx23_verbatim_sigmas++ client = getattr(pipe, "_unsloth_ltx25_encoder", None)+ if client is not None:+ client.cancel_event = cancel+ runner = pipe+ if image is not None:+ runner = condition_pipe(pipe)+ call_params = inspect.signature(runner.__call__).parameters+ width, height = int(kwargs["width"]), int(kwargs["height"])+ steps = int(kwargs.get("num_inference_steps") or 0)+ generator = kwargs.get("generator")+ scheduler = getattr(pipe, "scheduler", None)+ if hasattr(scheduler, "noise_generator"):+ scheduler.noise_generator = generator+ if runner is not pipe:+ runner.scheduler = scheduler++ base: dict[str, Any] = {+ k: v+ for k, v in kwargs.items()+ if k+ not in (+ "num_inference_steps",+ "width",+ "height",+ "callback_on_step_end",+ "image",+ "last_image",+ "sigmas",+ )+ and k in call_params+ }++ def _callback(offset: int) -> Optional[Callable[..., Any]]:+ if on_step is None:+ return None++ def _cb(p: Any, step_index: int, timestep: Any, callback_kwargs: dict) -> dict:+ result = on_step(p, offset + step_index, timestep, callback_kwargs)+ if getattr(p, "_interrupt", False) and runner is not pipe:+ pipe._interrupt = True+ return result++ return _cb++ def _conditions(strength: float) -> dict[str, Any]:+ if image is None:+ return {}+ from .ltx2_import_compat import ensure_ltx2_pipelines_importable++ ensure_ltx2_pipelines_importable(logger)+ from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2VideoCondition++ return {+ "conditions": [+ LTX2VideoCondition(frames = image, index = 0, strength = strength, crf = LTX25_IMAGE_CRF)+ ]+ }++ def _keep(stage_width: int, stage_height: int, frames: int) -> None:+ if not hasattr(scheduler, "keep_tokens"):+ return+ if image is None:+ scheduler.keep_tokens = None+ return+ spatial = int(getattr(runner, "vae_spatial_compression_ratio", 32) or 32)+ temporal = int(getattr(runner, "vae_temporal_compression_ratio", 8) or 8)+ per_frame = (stage_height // spatial) * (stage_width // spatial)+ latent_frames = (frames - 1) // temporal + 1+ scheduler.keep_tokens = (per_frame, per_frame * latent_frames)++ frames = int(kwargs.get("num_frames") or 121)+ if dev:+ call = dict(base, width = width, height = height, num_inference_steps = steps)+ call.update(_conditions(1.0))+ cb = _callback(0)+ if cb is not None:+ call["callback_on_step_end"] = cb+ _keep(width, height, frames)+ return runner(**call)++ distilled_sigmas = steps == len(LTX25_STAGE1_SIGMAS)+ guidance_off = _guidance_off(call_params)+ if not two_stage_enabled():+ call = dict(base, width = width, height = height, **guidance_off)+ if distilled_sigmas:+ call["sigmas"] = list(LTX25_STAGE1_SIGMAS)+ else:+ call["num_inference_steps"] = steps+ call.update(_conditions(1.0))+ cb = _callback(0)+ if cb is not None:+ call["callback_on_step_end"] = cb+ _keep(width, height, frames)+ with ltx23_verbatim_sigmas(pipe):+ return runner(**call)++ if upsampler is None:+ raise RuntimeError(+ "LTX-2.5's two-stage recipe needs the latent upsampler (latent_upsampler/ of the base pack), which "+ "is not loaded."+ )+ half_w, half_h = width // 2, height // 2+ stage1 = dict(+ base,+ width = half_w,+ height = half_h,+ output_type = "latent",+ return_dict = False,+ **guidance_off,+ )+ if distilled_sigmas:+ stage1["sigmas"] = list(LTX25_STAGE1_SIGMAS)+ else:+ stage1["num_inference_steps"] = steps+ stage1.update(_conditions(LTX25_STAGE1_IMAGE_STRENGTH))+ cb = _callback(0)+ if cb is not None:+ stage1["callback_on_step_end"] = cb+ _keep(half_w, half_h, frames)+ with ltx23_verbatim_sigmas(pipe):+ video_latents, audio_latents = runner(**stage1)+ if cancel is not None and cancel.is_set():+ from .video_families import VIDEO_CANCELLED_MSG+ raise RuntimeError(VIDEO_CANCELLED_MSG)++ with torch.inference_mode() if torch.is_inference_mode_enabled() else torch.no_grad():+ param = next(upsampler.parameters())+ # Saved before the move: Module.to() swaps the parameter's storage in place, so param.device follows it.+ home = param.device+ moved = home != video_latents.device+ if moved:+ upsampler.to(video_latents.device)+ try:+ upsampled = upsampler(video_latents.to(param.dtype))+ finally:+ if moved:+ upsampler.to(home)+ if cancel is not None and cancel.is_set():+ from .video_families import VIDEO_CANCELLED_MSG+ raise RuntimeError(VIDEO_CANCELLED_MSG)++ stage2 = dict(+ base,+ width = half_w * 2,+ height = half_h * 2,+ latents = upsampled,+ audio_latents = audio_latents,+ sigmas = list(LTX25_STAGE2_SIGMAS),+ noise_scale = LTX25_STAGE2_SIGMAS[0],+ **guidance_off,+ )+ stage2.update(_conditions(LTX25_STAGE2_IMAGE_STRENGTH))+ cb = _callback(steps)+ if cb is not None:+ stage2["callback_on_step_end"] = cb+ _keep(half_w * 2, half_h * 2, frames)+ with ltx23_verbatim_sigmas(pipe):+ return runner(**stage2)diff --git a/studio/backend/core/inference/video_ltx25_te_worker.py b/studio/backend/core/inference/video_ltx25_te_worker.pynew file mode 100644index 00000000000..5fe9e10ce04--- /dev/null+++ b/studio/backend/core/inference/video_ltx25_te_worker.py@@ -0,0 +1,350 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""LTX-2.5 Gemma 4 text encoder, in a spawned worker on the transformers 5.10 sidecar.++The server process runs Studio's default transformers, which has no ``Gemma4UnifiedForConditionalGeneration``. This+entry point runs in a fresh spawned interpreter: it prepends ``.venv_t5_510`` to ``sys.path`` BEFORE anything imports+transformers (the same activation the chat / training workers use), loads the encoder and tokenizer from the LTX-2.5+pack, and answers encode requests with the packed hidden states diffusers' ``LTX2Pipeline._get_gemma_prompt_embeds``+computes (every hidden state stacked on a last axis and flattened, left padding to ``max_sequence_length``).++Protocol (multiprocessing queues): the worker sends ``{"type": "ready", ...}`` once the model is loaded, then answers+``{"type": "encode", "id", "prompts", "max_sequence_length"}`` with ``{"type": "embeds", "id", "embeds", "mask"}``+(host tensors; bf16 ``[B, L, hidden * (layers + 1)]`` and int64 ``[B, L]``); ``{"type": "shutdown"}`` ends it. Any+failure is ``{"type": "error", "error": "..."}``. Must import nothing heavy at module level.+"""++from __future__ import annotations++import os+import sys+import traceback+from typing import Any, Optional++_BACKEND_PATH = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))+++def _version_tuple(text: str) -> tuple[int, ...]:+ out = []+ for part in str(text).split(".")[:3]:+ digits = "".join(ch for ch in part if ch.isdigit())+ out.append(int(digits) if digits else 0)+ return tuple(out)+++def _activate_sidecar(venv_dir: str) -> None:+ # A transformers already imported here (a parent __main__ re-imported by spawn) shadows the sidecar; the version+ # check in _load then names the problem.+ if not venv_dir or not os.path.isdir(venv_dir):+ raise RuntimeError(f"the transformers 5.10 sidecar is missing at '{venv_dir}'")+ if venv_dir not in sys.path:+ sys.path.insert(0, venv_dir)+ pythonpath = os.environ.get("PYTHONPATH", "")+ os.environ["PYTHONPATH"] = venv_dir + (os.pathsep + pythonpath if pythonpath else "")+++def _single_file_folder(config: dict) -> str:+ """A scratch folder that reads like a transformers checkpoint for the single-file release's encoder: its embedded+ config and tokenizer written out, the weights linked in (renamed at load by ``key_mapping``)."""+ import json+ import tempfile++ from safetensors import safe_open++ repo, name = config["repo"], config["single_file"]+ if os.path.isdir(os.path.expanduser(repo)):+ path = os.path.join(os.path.expanduser(repo), name)+ if not os.path.isfile(path):+ raise RuntimeError(f"'{name}' is missing from '{repo}'")+ else:+ from huggingface_hub import hf_hub_download+ path = hf_hub_download(+ repo,+ name,+ token = config.get("hf_token") or None,+ cache_dir = config.get("cache_dir") or None,+ local_files_only = bool(config.get("local_files_only")),+ )+ weights = os.path.realpath(path)+ folder = tempfile.mkdtemp(prefix = "unsloth_ltx25_te_")+ try:+ _link_weights(weights, os.path.join(folder, "model.safetensors"))+ except OSError:+ # The temp dir is on another volume than the weights, so no hard link: the scratch folder goes beside them.+ os.rmdir(folder)+ folder = tempfile.mkdtemp(prefix = ".unsloth_ltx25_te_", dir = os.path.dirname(weights))+ try:+ _link_weights(weights, os.path.join(folder, "model.safetensors"))+ except OSError as exc:+ os.rmdir(folder)+ raise RuntimeError(+ f"could not link '{name}' into a scratch checkpoint folder without copying it: {exc}"+ ) from exc+ try:+ with safe_open(path, framework = "pt", device = "cpu") as handle:+ meta = handle.metadata() or {}+ if "gemma_config" not in meta:+ raise RuntimeError(f"'{name}' has no embedded encoder config")+ with open(os.path.join(folder, "config.json"), "w", encoding = "utf-8") as fh:+ json.dump(json.loads(meta["gemma_config"]), fh)+ keys = set(handle.keys())+ for tensor_name, file_name in (+ ("tokenizer_json", "tokenizer.json"),+ ("hf_asset__tokenizer_config.json", "tokenizer_config.json"),+ ):+ if tensor_name not in keys:+ raise RuntimeError(f"'{name}' has no embedded {file_name}")+ with open(os.path.join(folder, file_name), "wb") as fh:+ fh.write(handle.get_tensor(tensor_name).numpy().tobytes())+ except BaseException:+ import shutil+ shutil.rmtree(folder, ignore_errors = True)+ raise+ return folder+++def _link_weights(src: str, dst: str) -> None:+ """Link ``src`` at ``dst`` without copying the 24 GB file: a symlink, else a hard link. Windows refuses symlinks+ without Developer Mode or administrator rights (WinError 1314); a hard link needs neither, only the same volume."""+ try:+ os.symlink(src, dst)+ except OSError:+ os.link(src, dst)+++def _load(config: dict) -> tuple[Any, Any]:+ import torch+ import transformers++ minimum = config.get("min_transformers") or "5.10.1"+ if _version_tuple(transformers.__version__) < _version_tuple(minimum):+ raise RuntimeError(+ f"the sidecar provides transformers {transformers.__version__}, but LTX-2.5's Gemma 4 encoder needs "+ f">= {minimum}"+ )+ model_cls = getattr(transformers, "Gemma4UnifiedForConditionalGeneration", None)+ if model_cls is None:+ raise RuntimeError(+ f"transformers {transformers.__version__} in the sidecar has no Gemma4UnifiedForConditionalGeneration"+ )+ dtype = getattr(torch, str(config.get("dtype") or "bfloat16"))+ common = {+ "token": config.get("hf_token") or None,+ "cache_dir": config.get("cache_dir") or None,+ "local_files_only": bool(config.get("local_files_only")),+ }+ if config.get("single_file"):+ import shutil+ folder = _single_file_folder(config)+ try:+ tokenizer = transformers.AutoTokenizer.from_pretrained(folder)+ model = model_cls.from_pretrained(+ folder, torch_dtype = dtype, key_mapping = config.get("key_mapping") or None+ )+ finally:+ shutil.rmtree(folder, ignore_errors = True)+ else:+ repo = config["repo"]+ tokenizer = transformers.AutoTokenizer.from_pretrained(+ repo, subfolder = "tokenizer", **common+ )+ model = model_cls.from_pretrained(+ repo, subfolder = "text_encoder", torch_dtype = dtype, **common+ )+ model.eval()+ model.requires_grad_(False)+ if config.get("resident"):+ model.to(config["device"])+ return tokenizer, model+++# Room an onloaded encode needs beyond the weights: every hidden state stacked for the packed embeddings (49 x 1024 x+# 3840 bf16 is ~0.4 GB per prompt, twice over while stacking) plus the forward's own activations.+ENCODE_MARGIN_MIB = 4096+# This process's own CUDA context, which the budget must also hold.+WORKER_CONTEXT_MIB = 768+++def _weights_mib(model: Any) -> int:+ total = 0+ for tensor in list(model.parameters()) + list(model.buffers()):+ total += tensor.numel() * tensor.element_size()+ return total >> 20+++def _encode_device(+ config: dict,+ model: Any,+ server_reserved_mib: Optional[int] = None,+) -> str:+ """Where a non-resident encoder runs this encode: the configured accelerator when it has room for the weights plus+ ``ENCODE_MARGIN_MIB``, else the CPU. Room is the card's free memory right now AND, when the server sent them, the+ load's memory budget minus what the server holds at this moment: the plan did not budget the encoder on the card,+ so it may only borrow budget the server is not using (encodes run before the denoise). An unreadable free count+ falls back to the budget alone; an XPU with neither reading encodes on the CPU."""+ device = str(config["device"])+ kind = device.split(":", 1)[0]+ # MPS shares host memory, so there is no card to keep the encoder off.+ if config.get("resident") or kind not in ("cuda", "xpu"):+ return device+ import torch++ need = _weights_mib(model) + ENCODE_MARGIN_MIB+ room: Optional[int] = None+ try:+ free, _total = getattr(torch, kind).mem_get_info(torch.device(device))+ room = free >> 20+ except Exception: # noqa: BLE001 -- judged by the budget alone+ pass+ budget = config.get("budget_mib")+ if budget is not None and server_reserved_mib is not None:+ allowed = int(budget) - int(server_reserved_mib) - WORKER_CONTEXT_MIB+ room = allowed if room is None else min(room, allowed)+ if room is None:+ return device if kind == "cuda" else "cpu"+ return device if room >= need else "cpu"+++def _memory_stats(device: str) -> dict:+ """This worker's own peaks: accelerator bytes since the last reset and the host resident set."""+ stats: dict = {}+ try:+ import torch+ if str(device).startswith("cuda") and torch.cuda.is_available():+ dev = torch.device(device)+ stats["gpu_peak_allocated_mib"] = torch.cuda.max_memory_allocated(dev) >> 20+ stats["gpu_peak_reserved_mib"] = torch.cuda.max_memory_reserved(dev) >> 20+ stats["gpu_allocated_mib"] = torch.cuda.memory_allocated(dev) >> 20+ torch.cuda.reset_peak_memory_stats(dev)+ except Exception: # noqa: BLE001 -- stats are best-effort+ pass+ try:+ import resource+ stats["host_peak_rss_mib"] = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss >> 10+ with open("/proc/self/statm", encoding = "ascii") as fh:+ stats["host_rss_mib"] = (int(fh.read().split()[1]) * os.sysconf("SC_PAGE_SIZE")) >> 20+ except Exception: # noqa: BLE001 -- not Linux+ pass+ return stats+++def _encode(+ tokenizer: Any, model: Any, config: dict, prompts: list, max_len: int+) -> tuple[Any, Any]:+ embeds, mask, _device = _encode_on(tokenizer, model, config, prompts, max_len)+ return embeds, mask+++def _encode_on(+ tokenizer: Any,+ model: Any,+ config: dict,+ prompts: list,+ max_len: int,+ server_reserved_mib: Optional[int] = None,+) -> tuple[Any, Any, str]:+ import torch++ resident = bool(config.get("resident"))+ device = _encode_device(config, model, server_reserved_mib)+ tokenizer.padding_side = "left"+ if tokenizer.pad_token is None:+ tokenizer.pad_token = tokenizer.eos_token+ inputs = tokenizer(+ [str(p).strip() for p in prompts],+ padding = "max_length",+ max_length = int(max_len),+ truncation = True,+ add_special_tokens = True,+ return_tensors = "pt",+ )+ onloaded = not resident and device != "cpu"+ if onloaded:+ model.to(device)+ try:+ with torch.inference_mode():+ ids = inputs.input_ids.to(device)+ mask = inputs.attention_mask.to(device)+ out = model(input_ids = ids, attention_mask = mask, output_hidden_states = True)+ stacked = torch.stack(out.hidden_states, dim = -1)+ embeds = stacked.flatten(2, 3).to(dtype = model.dtype)+ embeds_host = embeds.to("cpu")+ mask_host = mask.to("cpu")+ del out, stacked, embeds+ finally:+ if onloaded:+ model.to("cpu")+ # Return the encode's activations (and, onloaded, the weights) to the card: a resident worker otherwise keeps+ # ~1.7 GB cached through the denoise, an onloaded one the whole encoder.+ kind = str(device).split(":", 1)[0]+ accel = getattr(torch, kind, None) if kind in ("cuda", "xpu") else None+ if accel is not None and accel.is_available():+ accel.empty_cache()+ return embeds_host, mask_host, device+++def run_text_encoder_worker(*, cmd_queue: Any, resp_queue: Any, config: dict) -> None:+ if _BACKEND_PATH not in sys.path:+ sys.path.insert(0, _BACKEND_PATH)+ try:+ _activate_sidecar(config.get("venv_dir") or "")+ tokenizer, model = _load(config)+ import transformers++ resp_queue.put(+ {+ "type": "ready",+ "transformers": transformers.__version__,+ "model_type": getattr(model.config, "model_type", None),+ "hidden_size": getattr(+ getattr(model.config, "text_config", model.config), "hidden_size", None+ ),+ "resident": bool(config.get("resident")),+ **_memory_stats(config.get("device") or ""),+ }+ )+ except Exception as exc: # noqa: BLE001 -- every failure goes back to the server as a message+ resp_queue.put(+ {+ "type": "error",+ "error": f"LTX-2.5 text encoder failed to load: {exc}",+ "stack": traceback.format_exc(limit = 20),+ }+ )+ return+ while True:+ msg = cmd_queue.get()+ kind = msg.get("type") if isinstance(msg, dict) else None+ if kind == "shutdown" or kind is None:+ return+ if kind != "encode":+ continue+ try:+ embeds, mask, device = _encode_on(+ tokenizer,+ model,+ config,+ msg["prompts"],+ msg.get("max_sequence_length") or 1024,+ msg.get("server_reserved_mib"),+ )+ resp_queue.put(+ {+ "type": "embeds",+ "id": msg.get("id"),+ "embeds": embeds,+ "mask": mask,+ "device": device,+ **_memory_stats(config.get("device") or ""),+ }+ )+ except Exception as exc: # noqa: BLE001 -- report, keep serving+ resp_queue.put(+ {+ "type": "error",+ "id": msg.get("id"),+ "error": f"LTX-2.5 text encoder failed: {exc}",+ "stack": traceback.format_exc(limit = 20),+ }+ )diff --git a/studio/backend/core/inference/video_minimax_h3.py b/studio/backend/core/inference/video_minimax_h3.pyindex 15b94a0490c..a2ab6120e24 100644--- a/studio/backend/core/inference/video_minimax_h3.py+++ b/studio/backend/core/inference/video_minimax_h3.py@@ -472,10 +472,9 @@ def h3_canvas_for_aspect(aspect_width: float, aspect_height: float) -> tuple[intif area > H3_CANVAS_MAX_PIXELS:scale = math.sqrt(H3_CANVAS_MAX_PIXELS / area)width, height = width * scale, height * scale- snap = lambda v: max( # noqa: E731- H3_CANVAS_MULTIPLE, round(v / H3_CANVAS_MULTIPLE) * H3_CANVAS_MULTIPLE- )- return snap(width), snap(height)+ from .video_families import snap_canvas_within_cap++ return snap_canvas_within_cap(width, height, H3_CANVAS_MULTIPLE, H3_CANVAS_MAX_PIXELS)def fit_h3_keyframe(image: Any, width: int, height: int, *, anchor: str) -> Any:diff --git a/studio/backend/core/inference/video_vae_untiled.py b/studio/backend/core/inference/video_vae_untiled.pyindex 7e812614093..1628aae0c0e 100644--- a/studio/backend/core/inference/video_vae_untiled.py+++ b/studio/backend/core/inference/video_vae_untiled.py@@ -30,9 +30,12 @@ _OUTPUT_SCALE = {# LTX-2 / 2.3 holds every frame: peak per output frame x latent pixel, 0.102-0.105 MiB measured bf16 (B200)._BYTES_PER_FRAME_LATENT_PIXEL = {"ltx-2": 0.11 * 2**20,+ # Same conv decoder layout as 2.3 (vae/ of the Diffusers pack); unmeasured, priced as 2.3.+ "ltx-2.5": 0.11 * 2**20,}_TEMPORAL_SCALE = {"ltx-2": 8,+ "ltx-2.5": 8,}_MARGIN = 1.25_MARGIN_BYTES = 2 * 2**30diff --git a/studio/backend/tests/fixtures/ltx25_checkpoint_headers.json b/studio/backend/tests/fixtures/ltx25_checkpoint_headers.jsonnew file mode 100644index 00000000000..55e62b6dd02--- /dev/null+++ b/studio/backend/tests/fixtures/ltx25_checkpoint_headers.json@@ -0,0 +1,1016 @@+{+"Lightricks/LTX-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors": {+"meta": {+"model_version": "2.5.0"+},+"shapes": {+"model.diffusion_model.adaln_single.emb.timestep_embedder.linear_1.bias": [+4096+],+"model.diffusion_model.adaln_single.emb.timestep_embedder.linear_1.weight": [+4096,+256+],+"model.diffusion_model.adaln_single.emb.timestep_embedder.linear_2.bias": [+4096+],+"model.diffusion_model.adaln_single.emb.timestep_embedder.linear_2.weight": [+4096,+4096+],+"model.diffusion_model.adaln_single.linear.bias": [+36864+],+"model.diffusion_model.adaln_single.linear.weight": [+36864,+4096+],+"model.diffusion_model.audio_adaln_single.emb.timestep_embedder.linear_1.bias": [+2048+],+"model.diffusion_model.audio_adaln_single.emb.timestep_embedder.linear_1.weight": [+2048,+256+],+"model.diffusion_model.audio_adaln_single.emb.timestep_embedder.linear_2.bias": [+2048+],+"model.diffusion_model.audio_adaln_single.emb.timestep_embedder.linear_2.weight": [+2048,+2048+],+"model.diffusion_model.audio_adaln_single.linear.bias": [+18432+],+"model.diffusion_model.audio_adaln_single.linear.weight": [+18432,+2048+],+"model.diffusion_model.audio_patchify_proj.bias": [+2048+],+"model.diffusion_model.audio_patchify_proj.weight": [+2048,+128+],+"model.diffusion_model.audio_proj_out.bias": [+128+],+"model.diffusion_model.audio_proj_out.weight": [+128,+2048+],+"model.diffusion_model.audio_prompt_adaln_single.emb.timestep_embedder.linear_1.bias": [+2048+],+"model.diffusion_model.audio_prompt_adaln_single.emb.timestep_embedder.linear_1.weight": [+2048,+256+],+"model.diffusion_model.audio_prompt_adaln_single.emb.timestep_embedder.linear_2.bias": [+2048+],+"model.diffusion_model.audio_prompt_adaln_single.emb.timestep_embedder.linear_2.weight": [+2048,+2048+],+"model.diffusion_model.audio_prompt_adaln_single.linear.bias": [+4096+],+"model.diffusion_model.audio_prompt_adaln_single.linear.weight": [+4096,+2048+],+"model.diffusion_model.audio_scale_shift_table": [+2,+2048+],+"model.diffusion_model.av_ca_a2v_gate_adaln_single.emb.timestep_embedder.linear_1.bias": [+4096+],+"model.diffusion_model.av_ca_a2v_gate_adaln_single.emb.timestep_embedder.linear_1.weight": [+4096,+256+],+"model.diffusion_model.av_ca_a2v_gate_adaln_single.emb.timestep_embedder.linear_2.bias": [+4096+],+"model.diffusion_model.av_ca_a2v_gate_adaln_single.emb.timestep_embedder.linear_2.weight": [+4096,+4096+],+"model.diffusion_model.av_ca_a2v_gate_adaln_single.linear.bias": [+4096+],+"model.diffusion_model.av_ca_a2v_gate_adaln_single.linear.weight": [+4096,+4096+],+"model.diffusion_model.av_ca_audio_scale_shift_adaln_single.emb.timestep_embedder.linear_1.bias": [+2048+],+"model.diffusion_model.av_ca_audio_scale_shift_adaln_single.emb.timestep_embedder.linear_1.weight": [+2048,+256+],+"model.diffusion_model.av_ca_audio_scale_shift_adaln_single.emb.timestep_embedder.linear_2.bias": [+2048+],+"model.diffusion_model.av_ca_audio_scale_shift_adaln_single.emb.timestep_embedder.linear_2.weight": [+2048,+2048+],+"model.diffusion_model.av_ca_audio_scale_shift_adaln_single.linear.bias": [+8192+],+"model.diffusion_model.av_ca_audio_scale_shift_adaln_single.linear.weight": [+8192,+2048+],+"model.diffusion_model.av_ca_v2a_gate_adaln_single.emb.timestep_embedder.linear_1.bias": [+2048+],+"model.diffusion_model.av_ca_v2a_gate_adaln_single.emb.timestep_embedder.linear_1.weight": [+2048,+256+],+"model.diffusion_model.av_ca_v2a_gate_adaln_single.emb.timestep_embedder.linear_2.bias": [+2048+],+"model.diffusion_model.av_ca_v2a_gate_adaln_single.emb.timestep_embedder.linear_2.weight": [+2048,+2048+],+"model.diffusion_model.av_ca_v2a_gate_adaln_single.linear.bias": [+2048+],+"model.diffusion_model.av_ca_v2a_gate_adaln_single.linear.weight": [+2048,+2048+],+"model.diffusion_model.av_ca_video_scale_shift_adaln_single.emb.timestep_embedder.linear_1.bias": [+4096+],+"model.diffusion_model.av_ca_video_scale_shift_adaln_single.emb.timestep_embedder.linear_1.weight": [+4096,+256+],+"model.diffusion_model.av_ca_video_scale_shift_adaln_single.emb.timestep_embedder.linear_2.bias": [+4096+],+"model.diffusion_model.av_ca_video_scale_shift_adaln_single.emb.timestep_embedder.linear_2.weight": [+4096,+4096+],+"model.diffusion_model.av_ca_video_scale_shift_adaln_single.linear.bias": [+16384+],+"model.diffusion_model.av_ca_video_scale_shift_adaln_single.linear.weight": [+16384,+4096+],+"model.diffusion_model.keyframes_abs_pos_embedding": [+1,+4096+],+"model.diffusion_model.patchify_proj.bias": [+4096+],+"model.diffusion_model.patchify_proj.weight": [+4096,+128+],+"model.diffusion_model.proj_out.bias": [+128+],+"model.diffusion_model.proj_out.weight": [+128,+4096+],+"model.diffusion_model.prompt_adaln_single.emb.timestep_embedder.linear_1.bias": [+4096+],+"model.diffusion_model.prompt_adaln_single.emb.timestep_embedder.linear_1.weight": [+4096,+256+],+"model.diffusion_model.prompt_adaln_single.emb.timestep_embedder.linear_2.bias": [+4096+],+"model.diffusion_model.prompt_adaln_single.emb.timestep_embedder.linear_2.weight": [+4096,+4096+],+"model.diffusion_model.prompt_adaln_single.linear.bias": [+8192+],+"model.diffusion_model.prompt_adaln_single.linear.weight": [+8192,+4096+],+"model.diffusion_model.scale_shift_table": [+2,+4096+],+"model.diffusion_model.transformer_blocks.0.attn1.k_norm.weight": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn1.q_norm.weight": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn1.to_gate_logits.bias": [+32+],+"model.diffusion_model.transformer_blocks.0.attn1.to_gate_logits.weight": [+32,+4096+],+"model.diffusion_model.transformer_blocks.0.attn1.to_k.bias": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn1.to_k.weight": [+4096,+4096+],+"model.diffusion_model.transformer_blocks.0.attn1.to_out.0.bias": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn1.to_out.0.weight": [+4096,+4096+],+"model.diffusion_model.transformer_blocks.0.attn1.to_q.bias": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn1.to_q.weight": [+4096,+4096+],+"model.diffusion_model.transformer_blocks.0.attn1.to_v.bias": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn1.to_v.weight": [+4096,+4096+],+"model.diffusion_model.transformer_blocks.0.attn2.k_norm.weight": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn2.q_norm.weight": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn2.to_gate_logits.bias": [+32+],+"model.diffusion_model.transformer_blocks.0.attn2.to_gate_logits.weight": [+32,+4096+],+"model.diffusion_model.transformer_blocks.0.attn2.to_k.bias": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn2.to_k.weight": [+4096,+4096+],+"model.diffusion_model.transformer_blocks.0.attn2.to_out.0.bias": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn2.to_out.0.weight": [+4096,+4096+],+"model.diffusion_model.transformer_blocks.0.attn2.to_q.bias": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn2.to_q.weight": [+4096,+4096+],+"model.diffusion_model.transformer_blocks.0.attn2.to_v.bias": [+4096+],+"model.diffusion_model.transformer_blocks.0.attn2.to_v.weight": [+4096,+4096+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.k_norm.weight": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.q_norm.weight": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.to_gate_logits.bias": [+32+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.to_gate_logits.weight": [+32,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.to_k.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.to_k.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.to_out.0.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.to_out.0.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.to_q.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.to_q.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.to_v.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn1.to_v.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.k_norm.weight": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.q_norm.weight": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.to_gate_logits.bias": [+32+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.to_gate_logits.weight": [+32,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.to_k.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.to_k.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.to_out.0.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.to_out.0.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.to_q.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.to_q.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.to_v.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_attn2.to_v.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_ff.net.0.proj.bias": [+8192+],+"model.diffusion_model.transformer_blocks.0.audio_ff.net.0.proj.weight": [+8192,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_ff.net.2.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_ff.net.2.weight": [+2048,+8192+],+"model.diffusion_model.transformer_blocks.0.audio_prompt_scale_shift_table": [+2,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_scale_shift_table": [+9,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.k_norm.weight": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.q_norm.weight": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.to_gate_logits.bias": [+32+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.to_gate_logits.weight": [+32,+4096+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.to_k.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.to_k.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.to_out.0.bias": [+4096+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.to_out.0.weight": [+4096,+2048+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.to_q.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.to_q.weight": [+2048,+4096+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.to_v.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.audio_to_video_attn.to_v.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.ff.net.0.proj.weight": [+16384,+4096+],+"model.diffusion_model.transformer_blocks.0.ff.net.2.weight": [+4096,+16384+],+"model.diffusion_model.transformer_blocks.0.prompt_scale_shift_table": [+2,+4096+],+"model.diffusion_model.transformer_blocks.0.scale_shift_table": [+9,+4096+],+"model.diffusion_model.transformer_blocks.0.scale_shift_table_a2v_ca_audio": [+5,+2048+],+"model.diffusion_model.transformer_blocks.0.scale_shift_table_a2v_ca_video": [+5,+4096+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.k_norm.weight": [+2048+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.q_norm.weight": [+2048+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.to_gate_logits.bias": [+32+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.to_gate_logits.weight": [+32,+2048+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.to_k.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.to_k.weight": [+2048,+4096+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.to_out.0.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.to_out.0.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.to_q.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.to_q.weight": [+2048,+2048+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.to_v.bias": [+2048+],+"model.diffusion_model.transformer_blocks.0.video_to_audio_attn.to_v.weight": [+2048,+4096+]+}+},+"vantagewithai/LTX-2.5-GGUF/distilled/ltx-2.5-22b-distilled-transformer-Q4_K_M.gguf": {+"meta": {+"general.architecture": "ltxv"+},+"shapes": {+"adaln_single.emb.timestep_embedder.linear_1.bias": [+4096+],+"adaln_single.emb.timestep_embedder.linear_1.weight": [+4096,+256+],+"adaln_single.emb.timestep_embedder.linear_2.bias": [+4096+],+"adaln_single.emb.timestep_embedder.linear_2.weight": [+4096,+4096+],+"adaln_single.linear.bias": [+36864+],+"adaln_single.linear.weight": [+36864,+4096+],+"audio_adaln_single.emb.timestep_embedder.linear_1.bias": [+2048+],+"audio_adaln_single.emb.timestep_embedder.linear_1.weight": [+2048,+256+],+"audio_adaln_single.emb.timestep_embedder.linear_2.bias": [+2048+],+"audio_adaln_single.emb.timestep_embedder.linear_2.weight": [+2048,+2048+],+"audio_adaln_single.linear.bias": [+18432+],+"audio_adaln_single.linear.weight": [+18432,+2048+],+"audio_patchify_proj.bias": [+2048+],+"audio_patchify_proj.weight": [+2048,+128+],+"audio_proj_out.bias": [+128+],+"audio_proj_out.weight": [+128,+2048+],+"audio_prompt_adaln_single.emb.timestep_embedder.linear_1.bias": [+2048+],+"audio_prompt_adaln_single.emb.timestep_embedder.linear_1.weight": [+2048,+256+],+"audio_prompt_adaln_single.emb.timestep_embedder.linear_2.bias": [+2048+],+"audio_prompt_adaln_single.emb.timestep_embedder.linear_2.weight": [+2048,+2048+],+"audio_prompt_adaln_single.linear.bias": [+4096+],+"audio_prompt_adaln_single.linear.weight": [+4096,+2048+],+"audio_scale_shift_table": [+2,+2048+],+"av_ca_a2v_gate_adaln_single.emb.timestep_embedder.linear_1.bias": [+4096+],+"av_ca_a2v_gate_adaln_single.emb.timestep_embedder.linear_1.weight": [+4096,+256+],+"av_ca_a2v_gate_adaln_single.emb.timestep_embedder.linear_2.bias": [+4096+],+"av_ca_a2v_gate_adaln_single.emb.timestep_embedder.linear_2.weight": [+4096,+4096+],+"av_ca_a2v_gate_adaln_single.linear.bias": [+4096+],+"av_ca_a2v_gate_adaln_single.linear.weight": [+4096,+4096+],+"av_ca_audio_scale_shift_adaln_single.emb.timestep_embedder.linear_1.bias": [+2048+],+"av_ca_audio_scale_shift_adaln_single.emb.timestep_embedder.linear_1.weight": [+2048,+256+],+"av_ca_audio_scale_shift_adaln_single.emb.timestep_embedder.linear_2.bias": [+2048+],+"av_ca_audio_scale_shift_adaln_single.emb.timestep_embedder.linear_2.weight": [+2048,+2048+],+"av_ca_audio_scale_shift_adaln_single.linear.bias": [+8192+],+"av_ca_audio_scale_shift_adaln_single.linear.weight": [+8192,+2048+],+"av_ca_v2a_gate_adaln_single.emb.timestep_embedder.linear_1.bias": [+2048+],+"av_ca_v2a_gate_adaln_single.emb.timestep_embedder.linear_1.weight": [+2048,+256+],+"av_ca_v2a_gate_adaln_single.emb.timestep_embedder.linear_2.bias": [+2048+],+"av_ca_v2a_gate_adaln_single.emb.timestep_embedder.linear_2.weight": [+2048,+2048+],+"av_ca_v2a_gate_adaln_single.linear.bias": [+2048+],+"av_ca_v2a_gate_adaln_single.linear.weight": [+2048,+2048+],+"av_ca_video_scale_shift_adaln_single.emb.timestep_embedder.linear_1.bias": [+4096+],+"av_ca_video_scale_shift_adaln_single.emb.timestep_embedder.linear_1.weight": [+4096,+256+],+"av_ca_video_scale_shift_adaln_single.emb.timestep_embedder.linear_2.bias": [+4096+],+"av_ca_video_scale_shift_adaln_single.emb.timestep_embedder.linear_2.weight": [+4096,+4096+],+"av_ca_video_scale_shift_adaln_single.linear.bias": [+16384+],+"av_ca_video_scale_shift_adaln_single.linear.weight": [+16384,+4096+],+"keyframes_abs_pos_embedding": [+1,+4096+],+"patchify_proj.bias": [+4096+],+"patchify_proj.weight": [+4096,+128+],+"proj_out.bias": [+128+],+"proj_out.weight": [+128,+4096+],+"prompt_adaln_single.emb.timestep_embedder.linear_1.bias": [+4096+],+"prompt_adaln_single.emb.timestep_embedder.linear_1.weight": [+4096,+256+],+"prompt_adaln_single.emb.timestep_embedder.linear_2.bias": [+4096+],+"prompt_adaln_single.emb.timestep_embedder.linear_2.weight": [+4096,+4096+],+"prompt_adaln_single.linear.bias": [+8192+],+"prompt_adaln_single.linear.weight": [+8192,+4096+],+"scale_shift_table": [+2,+4096+],+"transformer_blocks.0.attn1.k_norm.weight": [+4096+],+"transformer_blocks.0.attn1.q_norm.weight": [+4096+],+"transformer_blocks.0.attn1.to_gate_logits.bias": [+32+],+"transformer_blocks.0.attn1.to_gate_logits.weight": [+32,+4096+],+"transformer_blocks.0.attn1.to_k.bias": [+4096+],+"transformer_blocks.0.attn1.to_k.weight": [+4096,+4096+],+"transformer_blocks.0.attn1.to_out.0.bias": [+4096+],+"transformer_blocks.0.attn1.to_out.0.weight": [+4096,+4096+],+"transformer_blocks.0.attn1.to_q.bias": [+4096+],+"transformer_blocks.0.attn1.to_q.weight": [+4096,+4096+],+"transformer_blocks.0.attn1.to_v.bias": [+4096+],+"transformer_blocks.0.attn1.to_v.weight": [+4096,+4096+],+"transformer_blocks.0.attn2.k_norm.weight": [+4096+],+"transformer_blocks.0.attn2.q_norm.weight": [+4096+],+"transformer_blocks.0.attn2.to_gate_logits.bias": [+32+],+"transformer_blocks.0.attn2.to_gate_logits.weight": [+32,+4096+],+"transformer_blocks.0.attn2.to_k.bias": [+4096+],+"transformer_blocks.0.attn2.to_k.weight": [+4096,+4096+],+"transformer_blocks.0.attn2.to_out.0.bias": [+4096+],+"transformer_blocks.0.attn2.to_out.0.weight": [+4096,+4096+],+"transformer_blocks.0.attn2.to_q.bias": [+4096+],+"transformer_blocks.0.attn2.to_q.weight": [+4096,+4096+],+"transformer_blocks.0.attn2.to_v.bias": [+4096+],+"transformer_blocks.0.attn2.to_v.weight": [+4096,+4096+],+"transformer_blocks.0.audio_attn1.k_norm.weight": [+2048+],+"transformer_blocks.0.audio_attn1.q_norm.weight": [+2048+],+"transformer_blocks.0.audio_attn1.to_gate_logits.bias": [+32+],+"transformer_blocks.0.audio_attn1.to_gate_logits.weight": [+32,+2048+],+"transformer_blocks.0.audio_attn1.to_k.bias": [+2048+],+"transformer_blocks.0.audio_attn1.to_k.weight": [+2048,+2048+],+"transformer_blocks.0.audio_attn1.to_out.0.bias": [+2048+],+"transformer_blocks.0.audio_attn1.to_out.0.weight": [+2048,+2048+],+"transformer_blocks.0.audio_attn1.to_q.bias": [+2048+],+"transformer_blocks.0.audio_attn1.to_q.weight": [+2048,+2048+],+"transformer_blocks.0.audio_attn1.to_v.bias": [+2048+],+"transformer_blocks.0.audio_attn1.to_v.weight": [+2048,+2048+],+"transformer_blocks.0.audio_attn2.k_norm.weight": [+2048+],+"transformer_blocks.0.audio_attn2.q_norm.weight": [+2048+],+"transformer_blocks.0.audio_attn2.to_gate_logits.bias": [+32+],+"transformer_blocks.0.audio_attn2.to_gate_logits.weight": [+32,+2048+],+"transformer_blocks.0.audio_attn2.to_k.bias": [+2048+],+"transformer_blocks.0.audio_attn2.to_k.weight": [+2048,+2048+],+"transformer_blocks.0.audio_attn2.to_out.0.bias": [+2048+],+"transformer_blocks.0.audio_attn2.to_out.0.weight": [+2048,+2048+],+"transformer_blocks.0.audio_attn2.to_q.bias": [+2048+],+"transformer_blocks.0.audio_attn2.to_q.weight": [+2048,+2048+],+"transformer_blocks.0.audio_attn2.to_v.bias": [+2048+],+"transformer_blocks.0.audio_attn2.to_v.weight": [+2048,+2048+],+"transformer_blocks.0.audio_ff.net.0.proj.bias": [+8192+],+"transformer_blocks.0.audio_ff.net.0.proj.weight": [+8192,+2048+],+"transformer_blocks.0.audio_ff.net.2.bias": [+2048+],+"transformer_blocks.0.audio_ff.net.2.weight": [+2048,+8192+],+"transformer_blocks.0.audio_prompt_scale_shift_table": [+2,+2048+],+"transformer_blocks.0.audio_scale_shift_table": [+9,+2048+],+"transformer_blocks.0.audio_to_video_attn.k_norm.weight": [+2048+],+"transformer_blocks.0.audio_to_video_attn.q_norm.weight": [+2048+],+"transformer_blocks.0.audio_to_video_attn.to_gate_logits.bias": [+32+],+"transformer_blocks.0.audio_to_video_attn.to_gate_logits.weight": [+32,+4096+],+"transformer_blocks.0.audio_to_video_attn.to_k.bias": [+2048+],+"transformer_blocks.0.audio_to_video_attn.to_k.weight": [+2048,+2048+],+"transformer_blocks.0.audio_to_video_attn.to_out.0.bias": [+4096+],+"transformer_blocks.0.audio_to_video_attn.to_out.0.weight": [+4096,+2048+],+"transformer_blocks.0.audio_to_video_attn.to_q.bias": [+2048+],+"transformer_blocks.0.audio_to_video_attn.to_q.weight": [+2048,+4096+],+"transformer_blocks.0.audio_to_video_attn.to_v.bias": [+2048+],+"transformer_blocks.0.audio_to_video_attn.to_v.weight": [+2048,+2048+],+"transformer_blocks.0.ff.net.0.proj.weight": [+16384,+4096+],+"transformer_blocks.0.ff.net.2.weight": [+4096,+16384+],+"transformer_blocks.0.prompt_scale_shift_table": [+2,+4096+],+"transformer_blocks.0.scale_shift_table": [+9,+4096+],+"transformer_blocks.0.scale_shift_table_a2v_ca_audio": [+5,+2048+],+"transformer_blocks.0.scale_shift_table_a2v_ca_video": [+5,+4096+],+"transformer_blocks.0.video_to_audio_attn.k_norm.weight": [+2048+],+"transformer_blocks.0.video_to_audio_attn.q_norm.weight": [+2048+],+"transformer_blocks.0.video_to_audio_attn.to_gate_logits.bias": [+32+],+"transformer_blocks.0.video_to_audio_attn.to_gate_logits.weight": [+32,+2048+],+"transformer_blocks.0.video_to_audio_attn.to_k.bias": [+2048+],+"transformer_blocks.0.video_to_audio_attn.to_k.weight": [+2048,+4096+],+"transformer_blocks.0.video_to_audio_attn.to_out.0.bias": [+2048+],+"transformer_blocks.0.video_to_audio_attn.to_out.0.weight": [+2048,+2048+],+"transformer_blocks.0.video_to_audio_attn.to_q.bias": [+2048+],+"transformer_blocks.0.video_to_audio_attn.to_q.weight": [+2048,+2048+],+"transformer_blocks.0.video_to_audio_attn.to_v.bias": [+2048+],+"transformer_blocks.0.video_to_audio_attn.to_v.weight": [+2048,+4096+]+}+}+}\ No newline at end of filediff --git a/studio/backend/tests/test_diffusion_memory.py b/studio/backend/tests/test_diffusion_memory.pyindex 8c2a0d25117..13ab4010fa0 100644--- a/studio/backend/tests/test_diffusion_memory.py+++ b/studio/backend/tests/test_diffusion_memory.py@@ -1445,6 +1445,8 @@ def test_unified_oversize_decision_matrix_for_the_real_video_families():# reaches H3 through the GGUF or prequantized artifacts instead."minimax-h3": {16, 24, 32, 64, 96, 128},"ltx-2": {16, 24, 32, 64, 96},+ # 75.1 GB of bf16 weights (the Gemma 4 encoder counted, though it lives in its worker process).+ "ltx-2.5": {16, 24, 32, 64, 96},"wan2.2-ti2v-5b": {16, 24, 32},"wan2.2-t2v-a14b": {16, 24, 32, 64, 96},# 14.7 GB (1.3B DiT + UMT5-XXL + the Wan2.1 VAE): plus overhead it just misses the ~14.4 GiBdiff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.pyindex c9129e7da48..0cffb0a1194 100644--- a/studio/backend/tests/test_video_backend.py+++ b/studio/backend/tests/test_video_backend.py@@ -637,6 +637,14 @@ def _load_h3_modular(backend, *, hf_token = None):return _FakeModularPipeline.instance+class _FakeLtx25Encoder:+ def wait_ready(self, cancel = None):+ return {}++ def close(self):+ pass++@pytest.fixturedef fake_runtime(monkeypatch):torch = types.ModuleType("torch")@@ -665,6 +673,11 @@ def fake_runtime(monkeypatch):monkeypatch.setitem(sys.modules, "torch", torch)monkeypatch.setitem(sys.modules, "diffusers", diffusers)monkeypatch.setattr("core.inference.video.clear_gpu_cache", lambda: None)+ # LTX-2.5's Gemma 4 encoder is a spawned worker on the transformers sidecar: never start one here.+ monkeypatch.setattr(+ "core.inference.video_ltx25.start_text_encoder", lambda **_kw: _FakeLtx25Encoder()+ )+ monkeypatch.setattr("core.inference.video_ltx25.attach_to_pipeline", lambda *_a, **_kw: None)# MP4 encode needs real frames + PyAV; the contract under test is the byte handoff, so stub the encoder.monkeypatch.setattr(VideoBackend, "_encode_mp4", staticmethod(lambda frames, fps, audio, pipe: b"MP4")@@ -8908,8 +8921,12 @@ def test_plan_is_unchanged_when_no_text_encoder_quant_is_requested(fake_runtime,continuecalls.clear()VideoBackend().load_pipeline(fam.base_repo, model_kind = "pipeline")+ # LTX-2.5's encoder runs in a second process; its CUDA context is priced on top of the table.+ from core.inference.video_ltx25 import LTX25_WORKER_RESIDENT_GB++ extra_gb = LTX25_WORKER_RESIDENT_GB if fam.name == "ltx-2.5" else 0.0assert calls[0]["model_dense_mib"] == int(- sum(fam.bf16_components_gb) * _MIB_PER_GB+ (sum(fam.bf16_components_gb) + extra_gb) * _MIB_PER_GB), fam.name@@ -13046,11 +13063,14 @@ def test_cudnn_benchmark_opt_out_families():"wan2.2-ti2v-5b","wan2.2-t2v-a14b","ltx-2",+ "ltx-2.5","hunyuanvideo-1.5","hunyuanvideo-1.5-720p",} <= offassert all(- fam.vae_force_fp32 or fam.name == "ltx-2" or fam.name.startswith("hunyuanvideo-1.5")+ fam.vae_force_fp32+ or fam.name in ("ltx-2", "ltx-2.5")+ or fam.name.startswith("hunyuanvideo-1.5")for fam in _FAMILIESif not fam.cudnn_benchmark)diff --git a/studio/backend/tests/test_video_families.py b/studio/backend/tests/test_video_families.pyindex 31aaa61ee94..274a19d5362 100644--- a/studio/backend/tests/test_video_families.py+++ b/studio/backend/tests/test_video_families.py@@ -180,6 +180,7 @@ def test_generation_defaults_distilled_vs_dev():def test_supported_names():assert supported_video_family_names() == ("minimax-h3",+ "ltx-2.5","ltx-2","wan2.2-ti2v-5b","wan2.2-t2v-a14b",diff --git a/studio/backend/tests/test_video_ltx25.py b/studio/backend/tests/test_video_ltx25.pynew file mode 100644index 00000000000..8b52c3c9a30--- /dev/null+++ b/studio/backend/tests/test_video_ltx25.py@@ -0,0 +1,2119 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""The ltx-2.5 video family: routing (names, model_index.json, headers), defaults, the base-pack file selection, the+Gemma 4 encoder worker path, the euler-ancestral sampler and the two-stage render orchestration. LTX-2.0 / 2.3 keep+resolving to ltx-2, and neither family ever loads the other's weights."""++from __future__ import annotations++import copy+import json+import queue+import struct+from pathlib import Path+from types import SimpleNamespace++import pytest++from core.inference import diffusion_content as dc+from core.inference import video_ltx25 as v25+from core.inference.video_families import (+ LTX25_FAMILY,+ assert_ltx_pick_supported,+ assert_supported_ltx_version,+ default_video_generation_params,+ detect_video_family,+ ltx25_is_dev,+ ltx_family_by_name,+ ltx_family_for_version,+ snap_num_frames,+ snap_video_size,+ unsupported_ltx_version,+)++_FIXTURES = Path(__file__).parent / "fixtures"+_FIXTURE = json.loads((_FIXTURES / "comfy_checkpoint_headers.json").read_text(encoding = "utf-8"))+# Range-read header of the official distilled DiT (Lightricks/LTX-2.5, via an ungated mirror), trimmed to the+# non-block tensors and block 0. Shapes only.+_LTX25_REAL = json.loads((_FIXTURES / "ltx25_checkpoint_headers.json").read_text(encoding = "utf-8"))+_LTX25_REAL_KEY = (+ "Lightricks/LTX-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors"+)++LTX25_NAMES = [+ "Lightricks/LTX-2.5-Diffusers",+ "Lightricks/LTX-2.5",+ "lightricks/ltx-2.5",+ "someone/LTX-2.5-GGUF",+ "Abiray/LTX-2.5-Distilled-GGUF",+ "ltx2.5",+ "LTX25",+ "LTX-Video-2.5",+]++LTX25_FILES = [+ ("Lightricks/LTX-2.5", "diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors"),+ ("Lightricks/LTX-2.5", "diffusion_models/ltx-2.5-22b-dev-transformer-bf16.safetensors"),+ ("Lightricks/LTX-2.5", "ltx-2.5-22b-distilled-transformer-comfy-int8-convrot.safetensors"),+ ("vantagewithai/LTX-2.5-GGUF", "distilled/ltx-2.5-22b-distilled-transformer-Q4_K_M.gguf"),+ ("Abiray/LTX-2.5-Distilled-GGUF", "LTX-2.5-Distilled-Q8_0.gguf"),+ ("someorg/quants", "ltx-2.5-22b-dev-transformer-Q4_K_M.gguf"),+]++LTX2X_NAMES = [+ "Lightricks/LTX-2",+ "Lightricks/LTX-2.3",+ "Lightricks/LTX-2.3-fp8",+ "unsloth/LTX-2-FP8",+ "unsloth/LTX-2.3-FP8",+ "unsloth/LTX-2.3-GGUF",+ "ltx-2-19b-dev.safetensors",+ "ltx-2.3-22b-distilled.safetensors",+ "LTX-2.3-22B-distilled-1.1-Q4_K_M.gguf",+ "ltxv",+ "ltx2",+]+++# ── release -> family ────────────────────────────────────────────────────────+++ "version, family",+ [+ ("2.0", "ltx-2"),+ ("2.3", "ltx-2"),+ ("2.4", "ltx-2.5"),+ ("2.5", "ltx-2.5"),+ ("2.6", None),+ ("2.9", None),+ ],+)+def test_release_maps_to_one_family(version, family):+ assert ltx_family_for_version(version) == family+++ "name, version",+ [+ ("Lightricks/LTX-2.10", "2.10"),+ ("ltx-2.12-22b-distilled.safetensors", "2.12"),+ ("ltx_2_10-dev", "2.10"),+ ],+)+def test_multi_digit_releases_are_refused_not_routed_to_ltx2(name, version):+ from core.inference.video import _detect_load_family++ assert unsupported_ltx_version(name) == version+ assert ltx_family_by_name(name) is None+ with pytest.raises(ValueError, match = f"LTX-{version}, which Studio does not support yet"):+ _detect_load_family(name, None, None)++[email protected]("name", LTX25_NAMES)+def test_ltx25_names_resolve_to_the_ltx25_family(name):+ from core.inference.video import _detect_load_family++ assert unsupported_ltx_version(name) is None+ assert ltx_family_by_name(name) == LTX25_FAMILY+ if name.lower() == v25.LTX25_SINGLE_FILE_REPO.lower():+ # The split release has no Diffusers pipeline: a load without a DiT file is refused before any download.+ with pytest.raises(ValueError, match = "single files, not a Diffusers pipeline"):+ _detect_load_family(name, None, None)+ with pytest.raises(ValueError, match = "single files, not a Diffusers pipeline"):+ _detect_load_family(name, "diffusion_models/x.safetensors", None, None, "pipeline")+ return+ assert _detect_load_family(name, None, None).name == LTX25_FAMILY++[email protected]("repo, filename", LTX25_FILES)+def test_ltx25_files_resolve_to_the_ltx25_family(repo, filename):+ from core.inference.video import _detect_load_family+ assert _detect_load_family(repo, filename, None).name == LTX25_FAMILY++[email protected]("name", LTX2X_NAMES)+def test_ltx2_and_ltx23_names_still_resolve_to_ltx2(name):+ from core.inference.video import _detect_load_family+ assert detect_video_family(name).name == "ltx-2"+ assert _detect_load_family(name, None, None).name == "ltx-2"++[email protected]("name", ["ltx-24fps-clip", "voltx-2.5", "ltx-23", "Lightricks/LTX-Video"])+def test_lookalikes_are_not_ltx25(name):+ assert ltx_family_by_name(name) != LTX25_FAMILY+++def test_later_releases_are_refused_by_name():+ from core.inference.video import _detect_load_family++ assert unsupported_ltx_version("ltx-2.6-test") == "2.6"+ with pytest.raises(ValueError, match = "LTX-2.6, which Studio does not support"):+ _detect_load_family("someone/LTX-2.6-GGUF", "model.gguf", None)+ with pytest.raises(ValueError, match = "LTX-2.6"):+ assert_supported_ltx_version("/models/x", "ltx-2.6-22b.safetensors")+++def test_picked_file_name_outranks_the_folder_both_ways():+ from core.inference.video import _detect_load_family++ assert (+ _detect_load_family("/models/ltx-2.5-tests", "ltx-2.3-22b-distilled.safetensors", None).name+ == "ltx-2"+ )+ assert (+ _detect_load_family(+ "/models/ltx-2.3-tests", "ltx-2.5-22b-distilled-transformer-bf16.safetensors", None+ ).name+ == LTX25_FAMILY+ )+ # A version-free file defers to the repo.+ assert _detect_load_family("Lightricks/LTX-2.5", "model.safetensors", None).name == LTX25_FAMILY+++def test_an_override_never_crosses_releases():+ from core.inference.video import _detect_load_family++ for override in ("ltx-2", "ltx-2.3", "ltxv"):+ with pytest.raises(ValueError, match = "loads as the 'ltx-2.5' family, not 'ltx-2'"):+ _detect_load_family("Lightricks/LTX-2.5-Diffusers", None, override)+ with pytest.raises(ValueError, match = "loads as the 'ltx-2' family, not 'ltx-2.5'"):+ _detect_load_family("Lightricks/LTX-2.3", "ltx-2.3-22b-distilled.safetensors", "ltx-2.5")+ assert _detect_load_family("Lightricks/LTX-2.5-Diffusers", None, "ltx-2.5").name == LTX25_FAMILY+ # A non-LTX family never trips on an LTX token.+ fam = _detect_load_family(+ "someone/wan-ltx-2.5-style",+ "wan-ltx-2.5-style.safetensors",+ "wan2.2-ti2v-5b",+ None,+ "single_file",+ )+ assert fam.name == "wan2.2-ti2v-5b"+ assert_ltx_pick_supported("wan2.2-ti2v-5b", "someone/ltx-2.5")+++def test_validate_load_request_accepts_the_official_picks():+ from core.inference.video import get_video_backend++ backend = get_video_backend()+ assert (+ backend.validate_load_request("Lightricks/LTX-2.5-Diffusers", model_kind = "pipeline").name+ == LTX25_FAMILY+ )+ fam = backend.validate_load_request(+ "Lightricks/LTX-2.5",+ gguf_filename = "diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors",+ model_kind = "single_file",+ )+ assert fam.name == LTX25_FAMILY+ with pytest.raises(ValueError, match = "'ltx-2.5' family, not 'ltx-2'"):+ backend.validate_load_request(+ "Lightricks/LTX-2.5",+ gguf_filename = "diffusion_models/ltx-2.5-22b-dev-transformer-bf16.safetensors",+ model_kind = "single_file",+ family_override = "ltx-2",+ )+++def test_companion_base_must_be_the_same_release(tmp_path, monkeypatch):+ import core.inference.diffusion as diffusion+ from core.inference.video import get_video_backend++ monkeypatch.setattr(diffusion, "_assert_local_base_is_pipeline", lambda *a, **k: None)+ backend = get_video_backend()+ ltx23 = dict(gguf_filename = "distilled/ltx-2.3-22b-distilled-Q4_K_M.gguf", model_kind = "gguf")+ with pytest.raises(ValueError, match = "LTX-2.5"):+ backend.validate_load_request(+ "unsloth/LTX-2.3-GGUF", base_repo = "unsloth/LTX-2.5-Diffusers", **ltx23+ )+ ltx25 = dict(+ gguf_filename = "distilled/ltx-2.5-22b-distilled-transformer-Q4_K_M.gguf", model_kind = "gguf"+ )+ with pytest.raises(ValueError, match = "'ltx-2' family, not 'ltx-2.5'"):+ backend.validate_load_request(+ "vantagewithai/LTX-2.5-GGUF", base_repo = "Lightricks/LTX-2", **ltx25+ )+ folder = tmp_path / "my-base"+ folder.mkdir()+ _write_index(folder, "Gemma4UnifiedForConditionalGeneration")+ with pytest.raises(ValueError, match = r"by its model_index\.json\) is LTX-2\.5"):+ backend.validate_load_request("unsloth/LTX-2.3-GGUF", base_repo = str(folder), **ltx23)+ backend.validate_load_request("vantagewithai/LTX-2.5-GGUF", base_repo = str(folder), **ltx25)+++def test_training_still_refuses_ltx25(tmp_path):+ from core.training.diffusion_train_common import resolve_trainable_family++ for family in (None, "ltx-2", "ltx-2.5"):+ with pytest.raises(ValueError, match = r"ltx-2\.5|LTX-2\.5"):+ resolve_trainable_family("Lightricks/LTX-2.5-Diffusers", family)+ folder = tmp_path / "my-video-base"+ folder.mkdir()+ _write_index(folder, "Gemma4UnifiedForConditionalGeneration")+ for family in (None, "ltx-2"):+ with pytest.raises(ValueError, match = "model_index.json"):+ resolve_trainable_family(str(folder), family)+ _write_index(folder, "Gemma3ForConditionalGeneration")+ assert resolve_trainable_family(str(folder), "ltx-2") == "ltx-2"+++# ── model_index.json ─────────────────────────────────────────────────────────+++def _write_index(folder: Path, encoder: str, **extra) -> None:+ index = {+ "_class_name": "LTX2Pipeline",+ "text_encoder": ["transformers", encoder],+ "transformer": ["diffusers", "LTX2VideoTransformer3DModel"],+ **extra,+ }+ (folder / "model_index.json").write_text(json.dumps(index), encoding = "utf-8")+++def test_empty_optional_components_count_as_absent(tmp_path):+ from core.inference.video_families import local_ltx_pipeline_family++ _write_index(+ tmp_path, "Gemma3ForConditionalGeneration", duration_head = [], diffusion_decoder = None+ )+ assert local_ltx_pipeline_family(str(tmp_path)) == "ltx-2"+ _write_index(+ tmp_path, "Gemma3ForConditionalGeneration", duration_head = ["diffusers", "LTX2DurationHead"]+ )+ assert local_ltx_pipeline_family(str(tmp_path)) == LTX25_FAMILY+++def test_a_forced_pipeline_load_ignores_a_child_files_header(tmp_path):+ from core.inference.video import _detect_load_family++ _write_index(tmp_path, "Gemma3ForConditionalGeneration")+ child = tmp_path / "ltx-2.5-extra.safetensors"+ _write_header_only_safetensors(child, _LTX25_REAL[_LTX25_REAL_KEY]["shapes"])+ # A pipeline load never opens the child, so the folder's model_index.json decides.+ assert _detect_load_family(str(tmp_path), child.name, "ltx-2", None, "pipeline").name == "ltx-2"+ with pytest.raises(ValueError, match = "'ltx-2.5' family, not 'ltx-2'"):+ _detect_load_family(str(tmp_path), child.name, "ltx-2", None, "single_file")+++def test_a_local_split_release_is_a_companion_base(tmp_path):+ from core.inference.video import get_video_backend++ split = tmp_path / "LTX-2.5-local"+ for name in (v25.LTX25_SINGLE_TEXT_ENCODER, v25.LTX25_SINGLE_VIDEO_VAE):+ (split / name).parent.mkdir(parents = True, exist_ok = True)+ (split / name).write_bytes(b"")+ assert v25.is_ltx25_single_file_base(str(split))+ ltx25 = dict(+ gguf_filename = "distilled/ltx-2.5-22b-distilled-transformer-Q4_K_M.gguf", model_kind = "gguf"+ )+ fam = get_video_backend().validate_load_request(+ "vantagewithai/LTX-2.5-GGUF", base_repo = str(split), **ltx25+ )+ assert fam.name == LTX25_FAMILY+ # Any other folder without a model_index.json is still refused as a base.+ other = tmp_path / "not-a-base"+ other.mkdir()+ with pytest.raises(ValueError):+ get_video_backend().validate_load_request(+ "vantagewithai/LTX-2.5-GGUF", base_repo = str(other), **ltx25+ )+++def test_local_diffusers_folder_answers_by_its_model_index(tmp_path):+ from core.inference.video import _detect_load_family++ folder = tmp_path / "my-ltx-video"+ folder.mkdir()+ _write_index(folder, "Gemma4UnifiedForConditionalGeneration")+ assert _detect_load_family(str(folder), None, None).name == LTX25_FAMILY+ with pytest.raises(ValueError, match = "model_index.json"):+ _detect_load_family(str(folder), None, "ltx-2")+ _write_index(folder, "Gemma3ForConditionalGeneration")+ assert _detect_load_family(str(folder), None, None).name == "ltx-2"+ with pytest.raises(ValueError, match = "model_index.json"):+ _detect_load_family(str(folder), None, "ltx-2.5")+ _write_index(+ folder, "Gemma3ForConditionalGeneration", duration_head = ["ltx2", "LTX2DurationHead"]+ )+ assert _detect_load_family(str(folder), None, None).name == LTX25_FAMILY+ _write_index(folder, "Gemma3ForConditionalGeneration", duration_head = [None, None])+ assert _detect_load_family(str(folder), None, None).name == "ltx-2"+ # A folder named after 2.3 still answers by its index.+ named = tmp_path / "ltx-2.3-copy"+ named.mkdir()+ _write_index(named, "Gemma4UnifiedForConditionalGeneration")+ assert _detect_load_family(str(named), None, None).name == LTX25_FAMILY+++# ── headers ──────────────────────────────────────────────────────────────────++_LTX23_KEYS = [+ "Lightricks/LTX-2.3/ltx-2.3-22b-distilled.safetensors",+ "Lightricks/LTX-2.3/ltx-2.3-22b-dev.safetensors",+ "Lightricks/LTX-2.3-fp8/ltx-2.3-22b-distilled-fp8.safetensors",+ "Kijai/LTX2.3_comfy/diffusion_models/ltx-2.3-22b-distilled-1.1_transformer_only_int8_convrot.safetensors",+ "Lightricks/LTX-2/ltx-2-19b-dev-fp4.safetensors",+ "QuantStack/LTX-2.3-GGUF/LTX-2.3-distilled-1.1/LTX-2.3-22B-distilled-1.1-Q4_K_M.gguf",+ "diffusers/ltx-2/LTX2VideoTransformer3DModel",+]+++def _shapes(key):+ entry = _FIXTURE[key]+ return (entry["shapes"], entry.get("meta")) if "shapes" in entry else (entry, None)+++def _as_ltx25(shapes):+ """A 2.x header with the 2.5 deltas: no video FFN bias, a keyframe position embedding."""+ prefix = (+ "model.diffusion_model."+ if any(k.startswith("model.diffusion_model.") for k in shapes)+ else ""+ )+ out = {+ k: v+ for k, v in shapes.items()+ if not (".ff.net." in k and k.endswith(".bias") and ".audio_ff." not in k)+ }+ out[f"{prefix}keyframes_abs_pos_embedding"] = [1, 4096]+ return out++[email protected]("key", _LTX23_KEYS)+def test_every_ltx2x_header_still_classifies_as_ltx2(key):+ shapes, meta = _shapes(key)+ assert dc.classify_tensors(shapes, meta).family == "ltx-2"++[email protected]("key", _LTX23_KEYS)+def test_ltx25_header_classifies_as_ltx25(key):+ shapes, meta = _shapes(key)+ info = dc.classify_tensors(_as_ltx25(shapes), meta)+ assert info.role == dc.ROLE_DIT and info.family == LTX25_FAMILY and info.page == dc.PAGE_VIDEO+ assert "LTX-2.5" in info.what+++def test_the_real_ltx25_header_classifies_as_ltx25():+ entry = _LTX25_REAL[_LTX25_REAL_KEY]+ shapes = entry["shapes"]+ assert "model.diffusion_model.keyframes_abs_pos_embedding" in shapes+ assert "model.diffusion_model.transformer_blocks.0.ff.net.0.proj.bias" not in shapes+ info = dc.classify_tensors(shapes, entry.get("meta"))+ assert info.family == LTX25_FAMILY and info.layout == "comfy"+ assert dc.is_ltx25_dit_keys([k[len("model.diffusion_model.") :] for k in shapes])+++def _write_header_only_safetensors(path: Path, shapes: dict) -> None:+ header = {k: {"dtype": "BF16", "shape": v, "data_offsets": [0, 0]} for k, v in shapes.items()}+ raw = json.dumps(header).encode()+ path.write_bytes(struct.pack("<Q", len(raw)) + raw)+++def test_renamed_local_ltx25_file_loads_as_ltx25_by_its_header(tmp_path):+ from core.inference.video import _detect_load_family+ from core.inference.video_ltx2 import assert_not_ltx25_checkpoint++ shapes = _LTX25_REAL[_LTX25_REAL_KEY]["shapes"]+ bad = tmp_path / "ltx-2.3-but-really-2.5.safetensors"+ _write_header_only_safetensors(bad, shapes)+ assert dc.resolve_family_with_content("ltx-2", str(bad), "video") == (LTX25_FAMILY, True)+ assert (+ _detect_load_family(str(tmp_path), bad.name, None, None, "single_file").name == LTX25_FAMILY+ )+ # Forced into ltx-2 it still never reaches the 2.3 assembly.+ with pytest.raises(ValueError, match = "'ltx-2.5' family, not 'ltx-2'"):+ assert_not_ltx25_checkpoint(bad)+ good23, _ = _shapes("Lightricks/LTX-2.3/ltx-2.3-22b-distilled.safetensors")+ good = tmp_path / "ltx-2.5-but-really-2.3.safetensors"+ _write_header_only_safetensors(good, good23)+ assert _detect_load_family(str(tmp_path), good.name, None, None, "single_file").name == "ltx-2"+++def test_a_forced_ltx_family_still_reads_a_local_header(tmp_path):+ from core.inference.video import _detect_load_family++ shapes23, _ = _shapes("Lightricks/LTX-2.3/ltx-2.3-22b-distilled.safetensors")+ v23 = tmp_path / "v23"+ v23.mkdir()+ _write_header_only_safetensors(v23 / "model.safetensors", shapes23)+ with pytest.raises(ValueError, match = "loads as the 'ltx-2' family, not 'ltx-2.5'"):+ _detect_load_family(str(v23), "model.safetensors", "ltx-2.5", None, "single_file")+ assert (+ _detect_load_family(str(v23), "model.safetensors", "ltx-2", None, "single_file").name+ == "ltx-2"+ )+ v25_dir = tmp_path / "v25"+ v25_dir.mkdir()+ _write_header_only_safetensors(+ v25_dir / "model.safetensors", _LTX25_REAL[_LTX25_REAL_KEY]["shapes"]+ )+ with pytest.raises(ValueError, match = "loads as the 'ltx-2.5' family, not 'ltx-2'"):+ _detect_load_family(str(v25_dir), "model.safetensors", "ltx-2", None, "single_file")+ assert (+ _detect_load_family(str(v25_dir), "model.safetensors", "ltx-2.5", None, "single_file").name+ == LTX25_FAMILY+ )+++# ── registry + defaults ──────────────────────────────────────────────────────+++def test_family_carries_the_reference_defaults():+ fam = detect_video_family("", override = LTX25_FAMILY)+ assert fam.base_repo == "Lightricks/LTX-2.5-Diffusers"+ assert (+ fam.pipeline_class == "LTX2Pipeline"+ and fam.transformer_class == "LTX2VideoTransformer3DModel"+ )+ assert fam.has_audio and fam.supports_keyframes and fam.supports_cfg+ assert (fam.default_steps, fam.default_guidance) == (8, 1.0)+ assert (fam.default_num_frames, fam.default_fps) == (121, 24)+ assert fam.resolution_presets[0] == (1280, 704)+ assert all(w % 64 == 0 and h % 64 == 0 for w, h in fam.resolution_presets)+ assert snap_video_size(fam, 1280, 720) == (1280, 704)+ assert snap_num_frames(fam, 121) == 121+ # Never the LTX-2 registry entry.+ assert detect_video_family("", override = "ltx-2").base_repo == "Lightricks/LTX-2"+++ "ids, expected",+ [+ (("Lightricks/LTX-2.5-Diffusers",), (8, 1.0)),+ (+ (+ None,+ "diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors",+ "Lightricks/LTX-2.5",+ ),+ (8, 1.0),+ ),+ (+ (None, "dev/ltx-2.5-22b-dev-transformer-Q4_K_M.gguf", "vantagewithai/LTX-2.5-GGUF"),+ (30, 3.0),+ ),+ ((None, "LTX-2.5-Distilled-Q4_K_M.gguf", "Abiray/LTX-2.5-Distilled-GGUF"), (8, 1.0)),+ (+ (None, "ltx-2.5-22b-dev-transformer-bf16.safetensors", "/home/me/distilled-models"),+ (30, 3.0),+ ),+ ],+)+def test_ltx25_generation_defaults(ids, expected):+ assert default_video_generation_params(*ids, fallback = (8, 1.0), family = LTX25_FAMILY) == expected+++def test_other_families_keep_their_defaults():+ assert default_video_generation_params("Lightricks/LTX-2") == (40, 4.0)+ assert default_video_generation_params(+ "ltx-2.3-22b-distilled.safetensors", "Lightricks/LTX-2.3"+ ) == (8, 1.0)+ assert default_video_generation_params("Lightricks/LTX-2", family = "ltx-2") == (40, 4.0)+++def test_dev_detection_reads_the_leaf_only():+ assert ltx25_is_dev("ltx-2.5-22b-dev-transformer-bf16.safetensors")+ assert ltx25_is_dev("transformer_full")+ assert not ltx25_is_dev("/home/dev/models/ltx-2.5-22b-distilled-transformer-bf16.safetensors")+ assert not ltx25_is_dev("Lightricks/LTX-2.5-Diffusers")+ assert not ltx25_is_dev(None, "devices/LTX-2.5")+++def test_keyframe_canvas_and_fit():+ from PIL import Image++ # Rounding both sides up must not leave the pixel cap (an aspect of ~0.3284 used to give 576x1664).+ for i in range(2500, 40001):+ ratio = i / 10000+ w, h = v25.ltx25_canvas_for_aspect(ratio, 1.0)+ assert w * h <= v25.LTX25_CANVAS_MAX_PIXELS, (ratio, w, h)+ assert w % 64 == 0 and h % 64 == 0+ assert v25.ltx25_canvas_for_aspect(1920, 1080) == (1280, 704)+ assert v25.ltx25_canvas_for_aspect(1080, 1920) == (704, 1280)+ w, h = v25.ltx25_canvas_for_aspect(1000, 1000)+ assert w % 64 == 0 and h % 64 == 0 and w == h+ with pytest.raises(ValueError, match = "1:4 to 4:1"):+ v25.ltx25_canvas_for_aspect(5000, 100)+ # The start image keeps its aspect: the condition pipeline crops it to each stage's canvas after the CRF.+ assert v25.prepare_ltx25_first_frame(Image.new("RGB", (300, 100))).size == (1536, 512)+ assert v25.prepare_ltx25_first_frame(Image.new("RGB", (1080, 3840))).size == (432, 1536)+ same = Image.new("RGB", (1536, 864))+ assert v25.prepare_ltx25_first_frame(same) is same+++def test_status_canvas_rule_per_family():+ from core.inference.video import _keyframe_canvas++ assert _keyframe_canvas(detect_video_family("", override = LTX25_FAMILY)) == (704, 1280 * 704)+ assert _keyframe_canvas(detect_video_family("", override = "ltx-2")) == (None, None)+ h3 = detect_video_family("", override = "minimax-h3")+ from core.inference.video_minimax_h3 import H3_CANVAS_MAX_PIXELS, H3_CANVAS_SHORT_EDGE++ assert _keyframe_canvas(h3) == (H3_CANVAS_SHORT_EDGE, H3_CANVAS_MAX_PIXELS)+++def test_last_frame_is_refused_and_canvas_follows_the_image():+ import base64+ import io++ from PIL import Image++ from core.inference.video import VideoBackend++ fam = detect_video_family("", override = LTX25_FAMILY)+ buf = io.BytesIO()+ Image.new("RGB", (1920, 1080), (10, 20, 30)).save(buf, format = "PNG")+ b64 = base64.b64encode(buf.getvalue()).decode()+ with pytest.raises(ValueError, match = "takes no last frame"):+ VideoBackend._resolve_keyframes(fam, None, b64, b64, None, None)+ # The same pure check the generate route applies before switching models; a first frame alone passes.+ from core.inference.video_families import (+ validate_video_keyframe_conditioning,+ video_family_accepts_first_frame,+ video_family_accepts_last_frame,+ video_family_uses_i2v_pipeline,+ )++ with pytest.raises(ValueError, match = "takes no last frame"):+ validate_video_keyframe_conditioning(fam, None, has_keyframes = True, has_last_frame = True)+ validate_video_keyframe_conditioning(fam, None, has_keyframes = True, has_last_frame = False)+ assert video_family_accepts_first_frame(fam) and not video_family_accepts_last_frame(fam)+ # Its first frame goes through its own two-stage render, not the generic image-to-video pipeline.+ assert not video_family_uses_i2v_pipeline(fam)+ h3 = detect_video_family("", override = "minimax-h3")+ assert video_family_accepts_last_frame(h3)+ first, last, w, h, mode = VideoBackend._resolve_keyframes(fam, None, b64, None, None, None)+ # The canvas is 1280x704; the image itself only gets its longer side at 1536, for the condition pipeline to fit.+ assert (w, h) == (1280, 704) and first.size == (1536, 864) and last is None and mode == "i2va"+ first, _, w, h, mode = VideoBackend._resolve_keyframes(fam, None, None, None, None, None)+ assert first is None and (w, h) == (1280, 704) and mode == "t2va"+++# ── base-pack file selection ─────────────────────────────────────────────────++# The real Lightricks/LTX-2.5-Diffusers listing (model_info, readable without accepting the gate).+_PACK = [+ ("README.md", 29971),+ ("audio_vae/config.json", 505),+ ("audio_vae/diffusion_pytorch_model.safetensors", 106507972),+ ("connectors/config.json", 817),+ ("connectors/diffusion_pytorch_model-00001-of-00002.safetensors", 4999998520),+ ("connectors/diffusion_pytorch_model-00002-of-00002.safetensors", 1344490576),+ ("connectors/diffusion_pytorch_model.safetensors", 6344489120),+ ("connectors/diffusion_pytorch_model.safetensors.index.json", 30629),+ ("diffusion_decoder/config.json", 1089),+ ("diffusion_decoder/diffusion_pytorch_model.safetensors", 834313392),+ ("duration_head/config.json", 251),+ ("duration_head/diffusion_pytorch_model.safetensors", 3808466),+ ("latent_upsampler/config.json", 301),+ ("latent_upsampler/diffusion_pytorch_model.safetensors", 995743320),+ ("ltx-2.5-22b-distilled-lora-450-bf16.safetensors", 9699368752),+ ("model_index.json", 971),+ ("processor/tokenizer.json", 32169626),+ ("prompt_enhancer/config.json", 5278),+ ("prompt_enhancer/model-00001-of-00003.safetensors", 1422130776),+ ("scheduler/scheduler_config.json", 489),+ ("temporal_latent_upsampler/config.json", 299),+ ("temporal_latent_upsampler/diffusion_pytorch_model.safetensors", 261943760),+ ("text_encoder/config.json", 4594),+ ("text_encoder/model-00001-of-00005.safetensors", 4961189118),+ ("text_encoder/model-00002-of-00005.safetensors", 4966688198),+ ("text_encoder/model-00003-of-00005.safetensors", 4884113678),+ ("text_encoder/model-00004-of-00005.safetensors", 4986341908),+ ("text_encoder/model-00005-of-00005.safetensors", 4121215522),+ ("text_encoder/model.safetensors.index.json", 66306),+ ("tokenizer/tokenizer.json", 32169626),+ ("tokenizer/tokenizer_config.json", 3735),+ ("transformer/config.json", 1440),+ *[+ (f"transformer/diffusion_pytorch_model-0000{i}-of-00004.safetensors", 9_900_000_000)+ for i in range(1, 5)+ ],+ *[+ (f"transformer/diffusion_pytorch_model-0000{i}-of-00008.safetensors", 4_950_000_000)+ for i in range(1, 9)+ ],+ ("transformer/diffusion_pytorch_model.safetensors.index.json", 446505),+ ("transformer_full/config.json", 1440),+ ("transformer_full/diffusion_pytorch_model-00001-of-00004.safetensors", 9932336016),+ ("vae/config.json", 1480),+ ("vae/diffusion_pytorch_model.safetensors", 1452233194),+ ("vocoder/config.json", 1478),+ ("vocoder/diffusion_pytorch_model.safetensors", 258305056),+ # The real pack also ships a modular index (MiniMax-H3's marker elsewhere in the plan).+ ("modular_model_index.json", 3093),+]+++def _info(files):+ return SimpleNamespace(siblings = [SimpleNamespace(rfilename = n, size = s) for n, s in files])+++def test_pack_download_keeps_only_what_a_load_reads():+ from core.inference.video import VideoBackend++ assert v25.is_ltx25_pack(n for n, _ in _PACK)+ names = {n for n, _ in VideoBackend._base_download_files(_info(_PACK), "pipeline")}+ for gone in (+ "transformer_full/",+ "prompt_enhancer/",+ "processor/",+ "diffusion_decoder/",+ "temporal_latent_upsampler/",+ "duration_head/",+ ):+ assert not any(n.startswith(gone) for n in names), gone+ assert "ltx-2.5-22b-distilled-lora-450-bf16.safetensors" not in names+ assert "connectors/diffusion_pytorch_model.safetensors" not in names+ assert "connectors/diffusion_pytorch_model-00001-of-00002.safetensors" in names+ transformer = sorted(+ n for n in names if n.startswith("transformer/") and n.endswith(".safetensors")+ )+ # No index read: the coarsest set, the one the official pack's index names.+ assert len(transformer) == 4 and all("-of-00004" in n for n in transformer)+ for kept in (+ "model_index.json",+ "connectors/config.json",+ "vocoder/diffusion_pytorch_model.safetensors",+ "audio_vae/diffusion_pytorch_model.safetensors",+ "latent_upsampler/diffusion_pytorch_model.safetensors",+ "text_encoder/model-00005-of-00005.safetensors",+ "tokenizer/tokenizer.json",+ "vae/diffusion_pytorch_model.safetensors",+ "transformer/config.json",+ ):+ assert kept in names+++def test_pack_download_follows_the_shard_index():+ from core.inference.video import VideoBackend++ shards = v25.ltx25_shards_from_indexes(+ {+ "transformer/diffusion_pytorch_model.safetensors.index.json": {+ "weight_map": {+ f"w{i}": f"diffusion_pytorch_model-0000{i}-of-00004.safetensors"+ for i in range(1, 5)+ }+ },+ "connectors/diffusion_pytorch_model.safetensors.index.json": {+ "weight_map": {"a": "diffusion_pytorch_model-00001-of-00002.safetensors"}+ },+ }+ )+ names = {+ n+ for n, _ in VideoBackend._base_download_files(_info(_PACK), "pipeline", ltx25_shards = shards)+ }+ transformer = sorted(+ n for n in names if n.startswith("transformer/") and n.endswith(".safetensors")+ )+ assert transformer == [+ f"transformer/diffusion_pytorch_model-0000{i}-of-00004.safetensors" for i in range(1, 5)+ ]+ assert {n for n in names if n.startswith("connectors/")} == {+ "connectors/config.json",+ "connectors/diffusion_pytorch_model-00001-of-00002.safetensors",+ "connectors/diffusion_pytorch_model.safetensors.index.json",+ }+++def test_download_plan_reads_the_pack_indexes(monkeypatch, tmp_path):+ from core.inference.video import VideoBackend+ from utils import hf_xet_fallback++ pack = _PACK+ indexes = {+ # Pointing at the 8-shard set proves the plan follows the index rather than the listing-only choice.+ "transformer/diffusion_pytorch_model.safetensors.index.json": {+ "weight_map": {+ f"w{i}": f"diffusion_pytorch_model-0000{i}-of-00008.safetensors"+ for i in range(1, 9)+ }+ },+ "connectors/diffusion_pytorch_model.safetensors.index.json": {+ "weight_map": {"a": "diffusion_pytorch_model-00001-of-00002.safetensors"}+ },+ }+ fetched = []++ def fake_download(repo, name, token, **_k):+ fetched.append((repo, name))+ component = name.split("/", 1)[0]+ payload = indexes.get(name) or {+ "weight_map": {+ n: n.split("/", 1)[1]+ for n, _ in pack+ if n.startswith(component + "/") and n.endswith(".safetensors") and "-of-" in n+ }+ }+ path = tmp_path / name.replace("/", "__")+ path.write_text(json.dumps(payload))+ return str(path)++ monkeypatch.setattr(hf_xet_fallback, "hf_hub_download_with_xet_fallback", fake_download)+ info = _info(pack)+ shards = VideoBackend._ltx25_plan_shards(info, "Lightricks/LTX-2.5-Diffusers", None)+ # Only the components a load stages: never transformer_full/.+ assert (+ "Lightricks/LTX-2.5-Diffusers",+ "transformer/diffusion_pytorch_model.safetensors.index.json",+ ) in fetched+ assert not any(n.startswith("transformer_full/") for _, n in fetched)+ names = {n for n, _ in VideoBackend._base_download_files(info, "pipeline", ltx25_shards = shards)}+ transformer = sorted(+ n for n in names if n.startswith("transformer/") and n.endswith(".safetensors")+ )+ assert transformer == [+ f"transformer/diffusion_pytorch_model-0000{i}-of-00008.safetensors" for i in range(1, 9)+ ]+ assert "text_encoder/model-00005-of-00005.safetensors" in names++ def offline(*_a, **_k):+ raise OSError("offline")++ monkeypatch.setattr(hf_xet_fallback, "hf_hub_download_with_xet_fallback", offline)+ assert VideoBackend._ltx25_plan_shards(info, "Lightricks/LTX-2.5-Diffusers", None) is None+ # Another family's repo never reads anything.+ fetched.clear()+ monkeypatch.setattr(hf_xet_fallback, "hf_hub_download_with_xet_fallback", fake_download)+ ltx2 = _info(+ [(n, sz) for n, sz in pack if not n.startswith(("duration_head/", "diffusion_decoder/"))]+ )+ assert VideoBackend._ltx25_plan_shards(ltx2, "Lightricks/LTX-2", None) is None and fetched == []+++def test_single_file_pick_skips_the_pack_dit():+ from core.inference.video import VideoBackend++ names = {n for n, _ in VideoBackend._base_download_files(_info(_PACK), "gguf")}+ assert "transformer/config.json" in names+ assert not any(n.startswith("transformer/") and n.endswith(".safetensors") for n in names)+ assert "latent_upsampler/diffusion_pytorch_model.safetensors" in names+++def test_dev_loads_skip_the_latent_upsampler(monkeypatch):+ from core.inference.video import VideoBackend, _ltx25_dev_load++ upsampler = "latent_upsampler/diffusion_pytorch_model.safetensors"+ dev = {n for n, _ in VideoBackend._base_download_files(_info(_PACK), "gguf", ltx25_dev = True)}+ assert upsampler not in dev and "vae/diffusion_pytorch_model.safetensors" in dev+ single = [+ n+ for n, _ in VideoBackend._base_download_files(+ _info(_SINGLE_REPO), "single_file", ltx25_dev = True+ )+ ]+ assert sorted(single) == sorted(set(v25.LTX25_SINGLE_COMPANIONS) - {v25.LTX25_SINGLE_UPSAMPLER})+ # The two-stage switch off: no load attaches the upsampler, so no plan stages it.+ monkeypatch.setenv(v25.TWO_STAGE_ENV, "0")+ assert upsampler not in {n for n, _ in VideoBackend._base_download_files(_info(_PACK), "gguf")}+ monkeypatch.delenv(v25.TWO_STAGE_ENV)+ fam = detect_video_family("", override = LTX25_FAMILY)+ assert _ltx25_dev_load(+ fam, "single_file", "ltx-2.5-22b-dev-bf16.safetensors", "Lightricks/LTX-2.5"+ )+ assert not _ltx25_dev_load(+ fam, "single_file", "ltx-2.5-22b-distilled-bf16.safetensors", "Lightricks/LTX-2.5"+ )+ # A pipeline decides by its display / repo id; the official pack is distilled.+ assert not _ltx25_dev_load(fam, "pipeline", None, "Lightricks/LTX-2.5-Diffusers")+ assert _ltx25_dev_load(fam, "pipeline", None, "/models/opaque", "someone/LTX-2.5-dev-Diffusers")+ assert not _ltx25_dev_load(+ detect_video_family("", override = "ltx-2"), "gguf", "ltx-2.3-dev.gguf", "x"+ )+++def test_other_packs_are_untouched():+ from core.inference.video import VideoBackend++ ltx2 = [+ (n, s)+ for n, s in _PACK+ if not n.startswith(("duration_head/", "diffusion_decoder/"))+ and n != "modular_model_index.json"+ ]+ assert not v25.is_ltx25_pack(n for n, _ in ltx2)+ names = {n for n, _ in VideoBackend._base_download_files(_info(ltx2), "pipeline")}+ assert "transformer_full/config.json" in names+ assert "connectors/diffusion_pytorch_model.safetensors" in names+++# ── the Gemma 4 encoder path ─────────────────────────────────────────────────+++def test_missing_sidecar_is_a_named_refusal(monkeypatch):+ import utils.transformers_version as tv++ monkeypatch.setattr(tv, "_ensure_venv_t5_510_exists", lambda: False)+ with pytest.raises(RuntimeError) as exc:+ v25.ensure_text_encoder_sidecar()+ text = str(exc.value)+ assert "Gemma4UnifiedForConditionalGeneration" in text and ".venv_t5_510" in text+ assert "5.10.1" in text+++def test_worker_reports_a_missing_sidecar_as_a_message(tmp_path):+ from core.inference import video_ltx25_te_worker as worker++ cmd, resp = queue.Queue(), queue.Queue()+ worker.run_text_encoder_worker(+ cmd_queue = cmd, resp_queue = resp, config = {"venv_dir": str(tmp_path / "nope"), "repo": "x"}+ )+ msg = resp.get_nowait()+ assert msg["type"] == "error" and "sidecar is missing" in msg["error"]+ assert worker._version_tuple("5.10.2") >= worker._version_tuple("5.10.1")+ assert worker._version_tuple("5.5.0") < worker._version_tuple("5.10.1")+++def test_worker_serves_encodes_until_shutdown(monkeypatch, tmp_path):+ import torch++ from core.inference import video_ltx25_te_worker as worker++ model = SimpleNamespace(+ config = SimpleNamespace(+ model_type = "gemma4_unified", text_config = SimpleNamespace(hidden_size = 4)+ )+ )+ monkeypatch.setattr(worker, "_activate_sidecar", lambda venv: None)+ monkeypatch.setattr(worker, "_load", lambda config: ("tok", model))+ monkeypatch.setattr(+ worker,+ "_encode_on",+ lambda tok, m, config, prompts, n, server_reserved_mib = None: (+ torch.ones(len(prompts), n, 8),+ torch.ones(len(prompts), n),+ "cpu",+ ),+ )+ cmd, resp = queue.Queue(), queue.Queue()+ cmd.put({"type": "encode", "id": 3, "prompts": ["a", "b"], "max_sequence_length": 5})+ cmd.put({"type": "shutdown"})+ worker.run_text_encoder_worker(+ cmd_queue = cmd, resp_queue = resp, config = {"venv_dir": str(tmp_path)}+ )+ ready = resp.get_nowait()+ assert (+ ready["type"] == "ready"+ and ready["model_type"] == "gemma4_unified"+ and ready["hidden_size"] == 4+ )+ out = resp.get_nowait()+ assert out["type"] == "embeds" and out["id"] == 3 and tuple(out["embeds"].shape) == (2, 5, 8)+ assert out["device"] == "cpu" and out.get("host_rss_mib", 0) > 0+++class _FakeClient:+ def __init__(self):+ self.calls = []++ def encode(+ self,+ texts,+ max_len,+ cancel = None,+ ):+ import torch++ self.calls.append((list(texts), max_len))+ n = len(texts)+ embeds = torch.arange(n, dtype = torch.float32).view(n, 1, 1).expand(n, max_len, 6).clone()+ return embeds, torch.ones(n, max_len, dtype = torch.long)+++def test_remote_encode_prompt_keeps_diffusers_semantics():+ import torch++ pipe = SimpleNamespace(+ _execution_device = torch.device("cpu"), transformer = SimpleNamespace(dtype = torch.bfloat16)+ )+ client = _FakeClient()+ v25.install_remote_encode_prompt(pipe, client)+ assert pipe._unsloth_ltx25_encoder is client+ pe, pm, ne, nm = pipe.encode_prompt(+ prompt = " a fox ",+ do_classifier_free_guidance = False,+ num_videos_per_prompt = 2,+ max_sequence_length = 4,+ )+ assert client.calls == [(["a fox"], 4)]+ assert pe.shape == (2, 4, 6) and pe.dtype == torch.bfloat16 and pm.shape == (2, 4)+ assert ne is None and nm is None+ client.calls.clear()+ pe, pm, ne, nm = pipe.encode_prompt(+ prompt = ["x"],+ negative_prompt = "blurry",+ do_classifier_free_guidance = True,+ max_sequence_length = 3,+ )+ assert client.calls == [(["x"], 3), (["blurry"], 3)]+ assert ne.shape == (1, 3, 6)+++def test_client_caches_recent_encodes_and_reports_a_dead_worker(monkeypatch):+ import torch++ client = v25.Ltx25TextEncoderClient(+ repo = "r",+ hf_token = None,+ cache_dir = None,+ local_files_only = True,+ device = "cpu",+ dtype = "bfloat16",+ resident = False,+ venv_dir = "/x",+ )+ client._cmd, client._resp = queue.Queue(), queue.Queue()+ client._proc = SimpleNamespace(is_alive = lambda: True, exitcode = None)+ client._ready = True++ def fake_put(msg):+ client._resp.put(+ {+ "type": "embeds",+ "id": msg["id"],+ "embeds": torch.zeros(1, 2, 3),+ "mask": torch.ones(1, 2),+ }+ )++ client._cmd.put = fake_put+ a = client.encode(["p"], 2)+ b = client.encode(["p"], 2)+ assert client._seq == 1 and torch.equal(a[0], b[0])+ client._proc = SimpleNamespace(is_alive = lambda: False, exitcode = -9)+ client._cmd.put = lambda msg: None+ monkeypatch.setattr(client, "start", lambda: None)+ with pytest.raises(v25.TextEncoderWorkerError, match = "exited"):+ client._get(None, "encoding")+++def test_an_abandoned_encodes_error_does_not_fail_the_next_one():+ import torch++ client = v25.Ltx25TextEncoderClient(+ repo = "r",+ hf_token = None,+ cache_dir = None,+ local_files_only = True,+ device = "cpu",+ dtype = "bfloat16",+ resident = False,+ venv_dir = "/x",+ )+ client._cmd, client._resp = queue.Queue(), queue.Queue()+ client._proc = SimpleNamespace(is_alive = lambda: True, exitcode = None)+ client._ready = True+ # Request 1 was abandoned by a cancel; its error arrives after request 2 was sent.+ client._seq = 1+ client._resp.put(+ {"type": "error", "id": 1, "error": "LTX-2.5 text encoder failed: CUDA out of memory"}+ )++ def fake_put(msg):+ client._resp.put(+ {+ "type": "embeds",+ "id": msg["id"],+ "embeds": torch.zeros(1, 2, 3),+ "mask": torch.ones(1, 2),+ }+ )++ client._cmd.put = fake_put+ embeds, _mask = client.encode(["p"], 2)+ assert embeds.shape == (1, 2, 3) and client._seq == 2+ # Its own error still fails it.+ client._cmd.put = lambda msg: client._resp.put(+ {"type": "error", "id": msg["id"], "error": "boom"}+ )+ with pytest.raises(v25.TextEncoderWorkerError, match = "boom"):+ client.encode(["q"], 2)+++# ── sampler ──────────────────────────────────────────────────────────────────+++def test_ancestral_step_matches_diffusers_rf_reference():+ import torch+ from diffusers import FlowMatchEulerDiscreteScheduler+ from diffusers.schedulers.scheduling_ltx_euler_ancestral_rf import LTXEulerAncestralRFScheduler++ base = FlowMatchEulerDiscreteScheduler(+ use_dynamic_shifting = False, shift = 1.0, shift_terminal = None+ )+ ours = v25.make_ancestral_scheduler(base)+ ref = LTXEulerAncestralRFScheduler(eta = 1.0, s_noise = 1.0)+ sigmas = list(v25.LTX25_STAGE2_SIGMAS)+ ours.set_timesteps(sigmas = sigmas, device = "cpu")+ ref.set_timesteps(sigmas = sigmas + [0.0], device = "cpu")+ torch.manual_seed(0)+ sample = torch.randn(1, 6, 4)+ a = b = sample+ g1, g2 = torch.Generator().manual_seed(5), torch.Generator().manual_seed(5)+ ours.noise_generator = g1+ for i in range(len(sigmas)):+ out = torch.randn(1, 6, 4, generator = torch.Generator().manual_seed(100 + i))+ a = ours.step(out, ours.timesteps[i], a, return_dict = False)[0]+ b = ref.step(out, ref.timesteps[i], b, generator = g2, return_dict = False)[0]+ torch.testing.assert_close(a, b)+++def test_keep_tokens_step_deterministically_and_copies_share_the_generator():+ import torch+ from diffusers import FlowMatchEulerDiscreteScheduler++ sched = v25.make_ancestral_scheduler(FlowMatchEulerDiscreteScheduler())+ sched.set_timesteps(sigmas = [0.85, 0.725, 0.421875], device = "cpu")+ gen = torch.Generator().manual_seed(1)+ sched.noise_generator = gen+ sched.keep_tokens = (2, 6)+ sample = torch.randn(1, 6, 3)+ out = torch.randn(1, 6, 3)+ nxt = sched.step(out, sched.timesteps[0], sample, return_dict = False)[0]+ expected = sample[:, :2] + (0.725 - 0.85) * out[:, :2]+ torch.testing.assert_close(nxt[:, :2], expected)+ assert not torch.allclose(nxt[:, 2:], sample[:, 2:] + (0.725 - 0.85) * out[:, 2:])+ clone = copy.deepcopy(sched)+ assert clone.noise_generator is gen and clone.keep_tokens == (2, 6)+++def test_prepare_scheduler_per_variant(monkeypatch):+ from diffusers import FlowMatchEulerDiscreteScheduler++ pipe = SimpleNamespace(scheduler = FlowMatchEulerDiscreteScheduler(use_dynamic_shifting = False))+ assert v25.prepare_scheduler(pipe, dev = False) == "euler_ancestral"+ assert hasattr(pipe.scheduler, "keep_tokens")+ pipe = SimpleNamespace(scheduler = FlowMatchEulerDiscreteScheduler(use_dynamic_shifting = False))+ assert v25.prepare_scheduler(pipe, dev = True) == "euler"+ assert (+ pipe.scheduler.config.use_dynamic_shifting and pipe.scheduler.config.shift_terminal == 0.1+ )+ monkeypatch.setenv(v25.SAMPLER_ENV, "euler")+ pipe = SimpleNamespace(scheduler = FlowMatchEulerDiscreteScheduler(use_dynamic_shifting = False))+ assert v25.prepare_scheduler(pipe, dev = False) == "euler"+++# ── render orchestration ─────────────────────────────────────────────────────+++class _FakePipe:+ """Records each call; returns latents shaped like the real stage-1 output."""++ vae_spatial_compression_ratio = 32+ vae_temporal_compression_ratio = 8++ def __init__(self, scheduler):+ self.scheduler = scheduler+ self.calls = []+ self.freed = 0++ def __call__(+ self,+ prompt = None,+ width = None,+ height = None,+ num_frames = None,+ sigmas = None,+ num_inference_steps = None,+ output_type = None,+ return_dict = True,+ latents = None,+ audio_latents = None,+ noise_scale = None,+ conditions = None,+ callback_on_step_end = None,+ guidance_scale = None,+ stg_scale = None,+ modality_scale = None,+ audio_guidance_scale = None,+ generator = None,+ frame_rate = None,+ ):+ import torch++ self.calls.append(+ dict(+ width = width,+ height = height,+ sigmas = sigmas,+ steps = num_inference_steps,+ output_type = output_type,+ noise_scale = noise_scale,+ latents = None if latents is None else tuple(latents.shape),+ conditions = conditions,+ keep = getattr(self.scheduler, "keep_tokens", None),+ stg = stg_scale,+ audio_cfg = audio_guidance_scale,+ )+ )+ if callback_on_step_end is not None:+ for i in range(len(sigmas) if sigmas else num_inference_steps):+ callback_on_step_end(self, i, None, {})+ if output_type == "latent":+ lat = torch.zeros(1, 8, 2, height // 32, width // 32)+ return lat, torch.zeros(1, 2, 3, 4)+ return SimpleNamespace(frames = ["final"], audio = None)++ def maybe_free_model_hooks(self):+ self.freed += 1+++class _Upsampler:+ def __init__(self):+ import torch+ self.weight = torch.nn.Parameter(torch.zeros(1))++ def parameters(self):+ yield self.weight++ def to(self, *_a, **_k):+ return self++ def __call__(self, latents):+ import torch+ return torch.nn.functional.interpolate(latents, scale_factor = (1, 2, 2))+++def _kwargs():+ return dict(+ prompt = "p",+ num_inference_steps = 8,+ width = 1280,+ height = 704,+ num_frames = 121,+ generator = None,+ guidance_scale = 1.0,+ frame_rate = 24.0,+ )+++def test_two_stage_t2v_follows_the_reference_recipe():+ pipe = _FakePipe(SimpleNamespace(keep_tokens = None))+ seen = []+ out = v25.render(+ pipe,+ _kwargs(),+ dev = False,+ upsampler = _Upsampler(),+ on_step = lambda p, i, t, kw: seen.append(i) or kw,+ )+ assert out.frames == ["final"]+ s1, s2 = pipe.calls+ assert (s1["width"], s1["height"]) == (640, 352) and s1["output_type"] == "latent"+ assert (+ s1["sigmas"] == list(v25.LTX25_STAGE1_SIGMAS)+ and s1["stg"] == 0.0+ and s1["audio_cfg"] == 1.0+ )+ assert (s2["width"], s2["height"]) == (1280, 704)+ assert s2["sigmas"] == [0.85, 0.725, 0.421875] and s2["noise_scale"] == 0.85+ assert s2["latents"] == (1, 8, 2, 22, 40)+ assert s1["conditions"] is None and s1["keep"] is None+ assert seen == list(range(11))+ assert v25.stage_steps(8, dev = False) == (8, 3)+++def test_two_stage_i2v_conditions_both_stages(monkeypatch):+ pipe = _FakePipe(SimpleNamespace(keep_tokens = None))+ cond = _FakePipe(pipe.scheduler)+ pipe._unsloth_ltx25_condition_pipe = cond+ image = object()+ v25.render(pipe, _kwargs(), dev = False, image = image, upsampler = _Upsampler())+ assert pipe.calls == [] and len(cond.calls) == 2+ c1, c2 = (call["conditions"][0] for call in cond.calls)+ assert (c1.strength, c1.crf, c1.index) == (0.7, 18, 0) and c1.frames is image+ assert (c2.strength, c2.crf) == (1.0, 18)+ # keep tokens = the first latent frame at each stage's latent size+ assert cond.calls[0]["keep"] == (11 * 20, 11 * 20 * 16)+ assert cond.calls[1]["keep"] == (22 * 40, 22 * 40 * 16)+ assert pipe.freed == 1+++def test_every_image_path_resets_the_offload_hooks(monkeypatch):+ import threading++ image = object()+ # dev, single stage+ pipe = _FakePipe(SimpleNamespace(keep_tokens = None))+ pipe._unsloth_ltx25_condition_pipe = _FakePipe(pipe.scheduler)+ v25.render(pipe, dict(_kwargs(), num_inference_steps = 30), dev = True, image = image)+ assert pipe.freed == 1+ # a cancel during the upsample+ cancel = threading.Event()++ class _CancellingUpsampler(_Upsampler):+ def __call__(self, latents):+ cancel.set()+ return super().__call__(latents)++ pipe = _FakePipe(SimpleNamespace(keep_tokens = None))+ pipe._unsloth_ltx25_condition_pipe = _FakePipe(pipe.scheduler)+ with pytest.raises(RuntimeError, match = "cancelled"):+ v25.render(+ pipe, _kwargs(), dev = False, image = image, upsampler = _CancellingUpsampler(), cancel = cancel+ )+ assert pipe.freed == 1+ # distilled with the two-stage recipe off+ monkeypatch.setenv(v25.TWO_STAGE_ENV, "0")+ pipe = _FakePipe(SimpleNamespace(keep_tokens = None))+ pipe._unsloth_ltx25_condition_pipe = _FakePipe(pipe.scheduler)+ v25.render(pipe, _kwargs(), dev = False, image = image)+ assert pipe.freed == 1+ # text-to-video runs pipe itself, whose own call resets its hooks+ pipe = _FakePipe(SimpleNamespace(keep_tokens = None))+ v25.render(pipe, _kwargs(), dev = False)+ assert pipe.freed == 0+++def test_dev_and_single_stage_paths(monkeypatch):+ pipe = _FakePipe(SimpleNamespace())+ v25.render(pipe, dict(_kwargs(), num_inference_steps = 30, guidance_scale = 3.0), dev = True)+ (call,) = pipe.calls+ assert call["steps"] == 30 and call["sigmas"] is None and call["stg"] is None+ assert v25.stage_steps(30, dev = True) == (30, 0)+ monkeypatch.setenv(v25.TWO_STAGE_ENV, "0")+ pipe = _FakePipe(SimpleNamespace())+ v25.render(pipe, _kwargs(), dev = False)+ (call,) = pipe.calls+ assert (call["width"], call["height"]) == (1280, 704) and call["sigmas"] == list(+ v25.LTX25_STAGE1_SIGMAS+ )+ assert v25.stage_steps(8, dev = False) == (8, 0)+++def test_two_stage_without_an_upsampler_is_a_clear_error():+ with pytest.raises(RuntimeError, match = "latent upsampler"):+ v25.render(_FakePipe(SimpleNamespace()), _kwargs(), dev = False, upsampler = None)+++class _OffloadedUpsampler(_Upsampler):+ """Starts off the latents' device; ``to`` swaps the parameter's device in place, as Module.to() does."""++ def __init__(self):+ import torch++ super().__init__()+ self.param = SimpleNamespace(device = torch.device("meta"), dtype = torch.float32)+ self.moves = []++ def parameters(self):+ yield self.param++ def to(self, device, *_a, **_k):+ import torch++ self.moves.append(torch.device(device))+ self.param.device = torch.device(device)+ return self+++def test_a_cancel_during_the_upsample_skips_stage_two():+ import threading++ cancel = threading.Event()++ class _CancellingUpsampler(_Upsampler):+ def __call__(self, latents):+ cancel.set()+ return super().__call__(latents)++ pipe = _FakePipe(SimpleNamespace(keep_tokens = None))+ with pytest.raises(RuntimeError, match = "cancelled"):+ v25.render(pipe, _kwargs(), dev = False, upsampler = _CancellingUpsampler(), cancel = cancel)+ assert len(pipe.calls) == 1+++def test_an_offloaded_upsampler_goes_back_where_it_was():+ import torch++ upsampler = _OffloadedUpsampler()+ v25.render(+ _FakePipe(SimpleNamespace(keep_tokens = None)), _kwargs(), dev = False, upsampler = upsampler+ )+ assert upsampler.moves == [torch.device("cpu"), torch.device("meta")]+ assert upsampler.param.device == torch.device("meta")+++# ── the real 2.5 DiT layout lands on the 2.5 diffusers transformer ───────────++# diffusers' scripts/convert_ltx2_to_diffusers.py, version "2.5" (what Lightricks/LTX-2.5-Diffusers transformer/ holds).+_LTX25_TRANSFORMER_CONFIG = {+ "in_channels": 128,+ "out_channels": 128,+ "patch_size": 1,+ "patch_size_t": 1,+ "num_attention_heads": 32,+ "attention_head_dim": 128,+ "cross_attention_dim": 4096,+ "vae_scale_factors": (8, 32, 32),+ "pos_embed_max_pos": 20,+ "base_height": 2048,+ "base_width": 2048,+ "gated_attn": True,+ "cross_attn_mod": True,+ "audio_in_channels": 128,+ "audio_out_channels": 128,+ "audio_patch_size": 1,+ "audio_patch_size_t": 1,+ "audio_num_attention_heads": 32,+ "audio_attention_head_dim": 64,+ "audio_cross_attention_dim": 2048,+ "audio_scale_factor": 4,+ "audio_pos_embed_max_pos": 20,+ "audio_sampling_rate": 16000,+ "audio_hop_length": 160,+ "audio_gated_attn": True,+ "audio_cross_attn_mod": True,+ "num_layers": 48,+ "activation_fn": "gelu-approximate",+ "qk_norm": "rms_norm_across_heads",+ "norm_elementwise_affine": False,+ "norm_eps": 1e-6,+ "caption_channels": 3840,+ "attention_bias": True,+ "attention_out_bias": True,+ "rope_theta": 10000.0,+ "rope_double_precision": True,+ "causal_offset": 1,+ "timestep_scale_multiplier": 1000,+ "cross_attn_timestep_scale_multiplier": 1000,+ "rope_type": "split",+ "use_prompt_embeddings": False,+ "perturbed_attn": True,+ "ff_bias": False,+ "use_keyframes_abs_pos_embedding": True,+}+++ "key",+ [+ _LTX25_REAL_KEY,+ "vantagewithai/LTX-2.5-GGUF/distilled/ltx-2.5-22b-distilled-transformer-Q4_K_M.gguf",+ ],+)+def test_real_ltx25_header_converts_onto_the_ltx25_transformer(key):+ """Every DiT tensor of the official file and of a community GGUF (non-block tensors + block 0, by name and logical+ shape; range-read headers) lands on a parameter of+ the same shape after load_ltx25_transformer's key handling (2.3 pre-rename + diffusers' converter), with nothing+ missing; the connector stacks in the file are dropped (they come from the pack)."""+ import torch+ from accelerate import init_empty_weights+ from diffusers import LTX2VideoTransformer3DModel+ from diffusers.loaders.single_file_utils import convert_ltx2_transformer_to_diffusers++ from core.inference.video_ltx2 import _ltx23_pre_convert, ltx23_is_dit_key++ with init_empty_weights():+ model = LTX2VideoTransformer3DModel.from_config(_LTX25_TRANSFORMER_CONFIG)+ expected = {+ k: tuple(v.shape)+ for k, v in model.state_dict().items()+ if not k.startswith("transformer_blocks.") or k.startswith("transformer_blocks.0.")+ }+ shapes = _LTX25_REAL[key]["shapes"]+ state = {k: torch.empty(v, device = "meta") for k, v in shapes.items() if ltx23_is_dit_key(k)}+ converted = convert_ltx2_transformer_to_diffusers(_ltx23_pre_convert(state))+ got = {k: tuple(v.shape) for k, v in converted.items()}+ assert got == expected+++# ── the split single-file release as its own base ───────────────────────────++# Lightricks/LTX-2.5's listing (sizes rounded).+_SINGLE_REPO = [+ (".gitattributes", 1600),+ ("README.md", 9000),+ ("diffusion_models/ltx-2.5-22b-dev-transformer-bf16.safetensors", 42_020_000_000),+ ("diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors", 42_020_000_000),+ (+ "diffusion_models/ltx-2.5-22b-distilled-transformer-comfy-int8-convrot.safetensors",+ 21_500_000_000,+ ),+ ("diffusion_models/ltx-2.5-22b-distilled-transformer-nvfp4.safetensors", 18_720_000_000),+ ("hf-hero-web.webp", 90_000),+ (+ "latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors",+ 1_000_000_000,+ ),+ ("latent_upscale_models/ltx-2.5-latent-temporal-upscaler-x2-bf16-1.0.safetensors", 260_000_000),+ ("loras/ltx-2.5-22b-distilled-lora-450-bf16.safetensors", 8_900_000_000),+ ("model_patches/ltx-2.5-duration-head-bf16.safetensors", 4_000_000),+ ("text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors", 26_260_000_000),+ ("text_encoders/gemma4-12b-with-proj-ltx-2.5-comfy-int8-convrot.safetensors", 15_370_000_000),+ ("vae/ltx-2.5-audio-vae-bf16.safetensors", 360_000_000),+ ("vae/ltx-2.5-video-vae-bf16.safetensors", 1_470_000_000),+ ("vae/ltx-2.5-video-vae-conv-bf16.safetensors", 1_450_000_000),+]+++def test_single_file_release_is_its_own_base(tmp_path):+ from core.inference.video_families import resolve_video_base_repo++ fam = detect_video_family("Lightricks/LTX-2.5-Diffusers")+ assert fam.name == LTX25_FAMILY+ assert v25.is_ltx25_single_file_base("Lightricks/LTX-2.5")+ assert v25.is_ltx25_single_file_base("lightricks/ltx-2.5")+ assert not v25.is_ltx25_single_file_base("Lightricks/LTX-2.5-Diffusers")+ assert not v25.is_ltx25_single_file_base("")+ # A DiT picked from the release defaults to it; an explicit base wins; any other pick keeps the pack.+ assert resolve_video_base_repo(fam, None, "Lightricks/LTX-2.5") == "Lightricks/LTX-2.5"+ assert resolve_video_base_repo(fam, "Lightricks/LTX-2.5-Diffusers", "Lightricks/LTX-2.5") == (+ "Lightricks/LTX-2.5-Diffusers"+ )+ assert (+ resolve_video_base_repo(fam, None, "someone/ltx-2.5-gguf") == "Lightricks/LTX-2.5-Diffusers"+ )+ ltx2 = detect_video_family("Lightricks/LTX-2")+ assert resolve_video_base_repo(ltx2, None, "Lightricks/LTX-2.5") == ltx2.base_repo+ # A local folder counts once the encoder file and the conv VAE sit in it.+ assert not v25.is_ltx25_single_file_base(str(tmp_path))+ for name in (v25.LTX25_SINGLE_TEXT_ENCODER, v25.LTX25_SINGLE_VIDEO_VAE):+ (tmp_path / name).parent.mkdir(parents = True, exist_ok = True)+ (tmp_path / name).write_bytes(b"x")+ assert v25.is_ltx25_single_file_base(str(tmp_path))+ assert resolve_video_base_repo(fam, None, str(tmp_path)) == str(tmp_path)+ assert v25.ltx25_companion_path(str(tmp_path), v25.LTX25_SINGLE_VIDEO_VAE, None) == str(+ tmp_path / v25.LTX25_SINGLE_VIDEO_VAE+ )+ with pytest.raises(FileNotFoundError, match = "audio-vae"):+ v25.ltx25_companion_path(str(tmp_path), v25.LTX25_SINGLE_AUDIO_VAE, None)+++def test_single_file_release_downloads_only_the_companions():+ from core.inference.video import VideoBackend++ assert v25.is_ltx25_single_file_listing(n for n, _ in _SINGLE_REPO)+ assert not v25.is_ltx25_pack(n for n, _ in _SINGLE_REPO)+ names = [n for n, _ in VideoBackend._base_download_files(_info(_SINGLE_REPO), "single_file")]+ assert sorted(names) == sorted(v25.LTX25_SINGLE_COMPANIONS)+ assert not v25.is_ltx25_single_file_listing(n for n, _ in _PACK)+++def test_text_encoder_key_mapping_reaches_the_gemma4_names():+ import re++ def mapped(key):+ for pattern, repl in v25.LTX25_TEXT_ENCODER_KEY_MAPPING.items():+ key = re.sub(pattern, repl, key)+ return key++ # Real names from the encoder file -> the pack's text_encoder/ names (checked on the full headers).+ assert (+ mapped("model.layers.0.mlp.down_proj.weight")+ == "model.language_model.layers.0.mlp.down_proj.weight"+ )+ assert mapped("model.embed_tokens.weight") == "model.language_model.embed_tokens.weight"+ assert mapped("model.norm.weight") == "model.language_model.norm.weight"+ assert (+ mapped("audio_projector.embedding_projection.weight")+ == "model.embed_audio.embedding_projection.weight"+ )+ assert mapped("multi_modal_projector.embedding_projection.weight") == (+ "model.embed_vision.embedding_projection.weight"+ )+ assert mapped("vision_model.pos_embedding") == "model.vision_embedder.pos_embedding"+ assert mapped("model.language_model.norm.weight") == "model.language_model.norm.weight"+ assert mapped("text_embedding_projection.video_aggregate_embed.weight").startswith(+ "text_embedding_projection."+ )+++def test_config_dir_survives_a_concurrent_writer(monkeypatch, tmp_path):+ import os+ import tempfile++ monkeypatch.setattr(tempfile, "gettempdir", lambda: str(tmp_path))+ real_replace = os.replace+ nested = []++ def replace(src, dst):+ # Another load in this process writes the same config between this one's scratch write and its replace.+ if not nested:+ nested.append(True)+ v25.ltx25_transformer_config_dir()+ real_replace(src, dst)++ monkeypatch.setattr(os, "replace", replace)+ folder = Path(v25.ltx25_transformer_config_dir())+ config = folder / "transformer" / "config.json"+ assert nested and json.loads(config.read_text(encoding = "utf-8"))["ff_bias"] is False+ assert [p.name for p in config.parent.iterdir()] == ["config.json"]+++def test_embedded_transformer_config_matches_the_tested_layout():+ # The config the real-header conversion test builds on, plus the two keys the pack's config spells out.+ expected = {+ k: (list(v) if isinstance(v, tuple) else v) for k, v in _LTX25_TRANSFORMER_CONFIG.items()+ }+ extra = {k: v for k, v in v25.LTX25_TRANSFORMER_CONFIG.items() if k not in expected}+ assert extra == {"audio_ff_bias": True, "use_prompt_adaln_single": True}+ assert {k: v for k, v in v25.LTX25_TRANSFORMER_CONFIG.items() if k in expected} == expected+ folder = Path(v25.ltx25_transformer_config_dir())+ written = json.loads((folder / "transformer" / "config.json").read_text(encoding = "utf-8"))+ assert written["_class_name"] == "LTX2VideoTransformer3DModel" and written["ff_bias"] is False+ assert v25._transformer_config_source("Lightricks/LTX-2.5") == str(folder)+ assert (+ v25._transformer_config_source("Lightricks/LTX-2.5-Diffusers")+ == "Lightricks/LTX-2.5-Diffusers"+ )+++def test_single_file_assembly_refuses_quantized_connectors(tmp_path):+ import torch+ from safetensors.torch import save_file++ path = tmp_path / "ltx-2.5-22b-distilled-transformer-comfy-int8-convrot.safetensors"+ save_file(+ {+ "model.diffusion_model.video_embeddings_connector.transformer_1d_blocks.0.attn1.to_q.weight": torch.zeros(+ 2, 2, dtype = torch.int8+ ),+ "model.diffusion_model.video_embeddings_connector.transformer_1d_blocks.0.attn1.to_q.weight_scale": (+ torch.ones(1)+ ),+ "model.diffusion_model.proj_out.bias": torch.zeros(2),+ },+ str(path),+ )+ with pytest.raises(ValueError, match = "connectors quantized"):+ v25.assemble_ltx25_single_file_pipeline(+ object(), path, base = "Lightricks/LTX-2.5", torch_dtype = torch.bfloat16, hf_token = None+ )+++def test_encoder_worker_reads_the_single_file_release(tmp_path):+ import os++ import numpy as np+ import torch+ from safetensors.torch import save_file++ from core.inference import video_ltx25_te_worker as worker++ name = v25.LTX25_SINGLE_TEXT_ENCODER+ path = tmp_path / name+ path.parent.mkdir(parents = True)+ tokenizer_json = b'{"version": "1.0"}'+ tokenizer_config = b'{"tokenizer_class": "GemmaTokenizer"}'+ save_file(+ {+ "model.norm.weight": torch.ones(4),+ "tokenizer_json": torch.from_numpy(+ np.frombuffer(tokenizer_json, dtype = np.uint8).copy()+ ),+ "hf_asset__tokenizer_config.json": torch.from_numpy(+ np.frombuffer(tokenizer_config, dtype = np.uint8).copy()+ ),+ },+ str(path),+ metadata = {"gemma_config": json.dumps({"model_type": "gemma4_unified"}), "format": "pt"},+ )+ client = v25.Ltx25TextEncoderClient(+ repo = str(tmp_path),+ hf_token = None,+ cache_dir = None,+ local_files_only = True,+ device = "cpu",+ dtype = "bfloat16",+ resident = False,+ venv_dir = "/nonexistent",+ single_file = name,+ )+ assert client.config["single_file"] == name+ assert client.config["key_mapping"] == v25.LTX25_TEXT_ENCODER_KEY_MAPPING+ folder = Path(worker._single_file_folder(client.config))+ try:+ assert json.loads((folder / "config.json").read_text()) == {"model_type": "gemma4_unified"}+ assert (folder / "tokenizer.json").read_bytes() == tokenizer_json+ assert (folder / "tokenizer_config.json").read_bytes() == tokenizer_config+ assert os.path.realpath(folder / "model.safetensors") == os.path.realpath(path)+ finally:+ import shutil+ shutil.rmtree(folder)+ # A pack base keeps the subfolder layout.+ pack_client = v25.Ltx25TextEncoderClient(+ repo = "Lightricks/LTX-2.5-Diffusers",+ hf_token = None,+ cache_dir = None,+ local_files_only = True,+ device = "cpu",+ dtype = "bfloat16",+ resident = False,+ venv_dir = "/nonexistent",+ )+ assert pack_client.config["single_file"] is None and pack_client.config["key_mapping"] is None+++def _write_single_file_encoder(folder: Path) -> Path:+ import numpy as np+ import torch+ from safetensors.torch import save_file++ path = folder / v25.LTX25_SINGLE_TEXT_ENCODER+ path.parent.mkdir(parents = True, exist_ok = True)+ save_file(+ {+ "model.norm.weight": torch.ones(4),+ "tokenizer_json": torch.from_numpy(np.frombuffer(b"{}", dtype = np.uint8).copy()),+ "hf_asset__tokenizer_config.json": torch.from_numpy(+ np.frombuffer(b"{}", dtype = np.uint8).copy()+ ),+ },+ str(path),+ metadata = {"gemma_config": json.dumps({"model_type": "gemma4_unified"}), "format": "pt"},+ )+ return path+++def test_encoder_worker_links_without_symlink_rights(monkeypatch, tmp_path):+ import os+ import shutil++ from core.inference import video_ltx25_te_worker as worker++ path = _write_single_file_encoder(tmp_path / "weights")+ config = {"repo": str(tmp_path / "weights"), "single_file": v25.LTX25_SINGLE_TEXT_ENCODER}++ def no_symlink(*_a, **_k):+ raise OSError(1314, "A required privilege is not held by the client")++ monkeypatch.setattr(worker.os, "symlink", no_symlink)+ folder = Path(worker._single_file_folder(config))+ try:+ linked = folder / "model.safetensors"+ assert not linked.is_symlink() and os.path.samefile(linked, path)+ finally:+ shutil.rmtree(folder)+ assert path.is_file()++ # The temp dir on another volume: the scratch folder goes beside the weights, and is the caller's to remove.+ real_link = os.link++ def link_beside_only(src, dst):+ if Path(dst).parent.parent != path.parent:+ raise OSError(18, "Invalid cross-device link")+ real_link(src, dst)++ monkeypatch.setattr(worker.os, "link", link_beside_only)+ folder = Path(worker._single_file_folder(config))+ try:+ assert folder.parent == path.parent and os.path.samefile(folder / "model.safetensors", path)+ assert json.loads((folder / "config.json").read_text()) == {"model_type": "gemma4_unified"}+ finally:+ shutil.rmtree(folder)+ assert path.is_file() and sorted(p.name for p in path.parent.iterdir()) == [path.name]+++def test_a_failed_load_stops_only_its_own_encoder_worker():+ from core.inference import video as vid++ class _Client:+ closed = False++ def close(self):+ self.closed = True++ backend = vid.VideoBackend()+ newer = _Client()+ backend._ltx25_pending_encoder = (2, newer)+ # A superseded load (token 1) unwinding after the newer load started its worker leaves that worker alone.+ backend._close_pending_ltx25_encoder(1)+ assert not newer.closed and backend._ltx25_pending_encoder == (2, newer)+ backend._close_pending_ltx25_encoder(2)+ assert newer.closed and backend._ltx25_pending_encoder is None+ # Untokened, whichever load started it.+ other = _Client()+ backend._ltx25_pending_encoder = (3, other)+ backend._close_pending_ltx25_encoder()+ assert other.closed and backend._ltx25_pending_encoder is None+++def test_unload_stops_a_pending_encoder_worker():+ from core.inference import video as vid++ class _Client:+ closed = False++ def close(self):+ self.closed = True++ backend = vid.VideoBackend()+ pending = _Client()+ backend._ltx25_pending_encoder = (backend._load_token, pending)+ backend.unload()+ # Stopped by unload itself, not when the cancelled load thread finally unwinds.+ assert pending.closed and backend._ltx25_pending_encoder is None+++def test_encoder_worker_is_spawned_on_the_lifetime_thread(monkeypatch):+ """The child arms PR_SET_PDEATHSIG, which follows the spawning thread; a worker started from the (short-lived)+ load thread died as soon as the load returned, so the first generate restarted it."""+ import multiprocessing+ import threading++ import utils.process_lifetime as lifetime++ spawned_via = []++ class _Proc:+ pid = 4242++ def __init__(self, **kwargs):+ self.started_on = None++ def start(self):+ self.started_on = threading.current_thread().name++ class _Ctx:+ Queue = queue.Queue++ def Process(self, **kwargs): # noqa: N802 -- mirrors the multiprocessing API+ return _Proc(**kwargs)++ def _spawn(fn):+ spawned_via.append(fn)+ return fn()++ monkeypatch.setattr(multiprocessing, "get_context", lambda method: _Ctx())+ monkeypatch.setattr(lifetime, "spawn_on_lifetime_thread", _spawn)+ monkeypatch.setattr(lifetime, "adopt_pid", lambda pid: None)+ client = v25.Ltx25TextEncoderClient(+ repo = "Lightricks/LTX-2.5-Diffusers",+ hf_token = None,+ cache_dir = None,+ local_files_only = True,+ device = "cpu",+ dtype = "bfloat16",+ resident = False,+ venv_dir = "/nonexistent",+ )+ worker = threading.Thread(target = client.start, name = "short-lived-load")+ worker.start()+ worker.join()+ assert len(spawned_via) == 1 and spawned_via[0] == client._proc.start+++# ── the encoder worker inside the memory plan ────────────────────────────────+++ "policy, stream_te, resident",+ [+ ("none", False, True),+ ("group", False, True), # companions resident: the plan budgeted the encoder on the card+ ("group", True, False), # streamed text encoders: the plan did not+ ("model", False, False), # one module on the card at a time+ ("streaming", True, False),+ ("sequential", False, False),+ ],+)+def test_encoder_placement_follows_the_plan_tier(policy, stream_te, resident):+ plan = SimpleNamespace(offload_policy = policy, stream_text_encoders = stream_te)+ assert v25.encoder_resident_for_plan(plan) is resident+++def test_family_table_prices_the_worker_encoder():+ """The plan counts the worker's Gemma 4 as the family's text encoder term: the pack's text_encoder/ weights are+ 22.28 GiB (23.9 GB), the table's second entry."""+ fam = detect_video_family("Lightricks/LTX-2.5-Diffusers")+ assert fam.bf16_components_gb[1] == pytest.approx(22.28 * 2**30 / 1e9, rel = 0.01)+++class _FakeEncoderModel:+ def __init__(self):+ import torch++ self.weight = torch.zeros(1024, 1024, dtype = torch.bfloat16) # 2 MiB+ self.dtype = torch.bfloat16+ self.moves = []++ def parameters(self):+ return [self.weight]++ def buffers(self):+ return []++ def to(self, device):+ self.moves.append(str(device))+ return self++ def __call__(self, input_ids, attention_mask, output_hidden_states):+ import torch+ b, n = input_ids.shape+ return SimpleNamespace(+ hidden_states = tuple(torch.full((b, n, 4), float(i)) for i in range(3))+ )+++class _FakeTokenizer:+ padding_side = "right"+ pad_token = "<pad>"++ def __call__(self, prompts, **kwargs):+ import torch+ n = kwargs["max_length"]+ return SimpleNamespace(+ input_ids = torch.ones(len(prompts), n, dtype = torch.long),+ attention_mask = torch.ones(len(prompts), n, dtype = torch.long),+ )+++def _patch_free(monkeypatch, free_mib):+ import torch+ def _mem_get_info(device = None):+ if free_mib is None:+ raise RuntimeError("no device")+ return free_mib << 20, 80 << 30++ monkeypatch.setattr(torch.cuda, "mem_get_info", _mem_get_info)+++def test_offloaded_encoder_onloads_only_when_the_card_has_room(monkeypatch):+ from core.inference import video_ltx25_te_worker as worker++ model = _FakeEncoderModel()+ monkeypatch.setattr(worker, "ENCODE_MARGIN_MIB", 10)+ offloaded = {"device": "cuda:0", "resident": False}+ _patch_free(monkeypatch, 12) # weights 2 MiB + margin 10 MiB+ assert worker._encode_device(offloaded, model) == "cuda:0"+ _patch_free(monkeypatch, 11)+ assert worker._encode_device(offloaded, model) == "cpu"+ _patch_free(monkeypatch, None) # unreadable: keep the planned onload+ assert worker._encode_device(offloaded, model) == "cuda:0"+ _patch_free(monkeypatch, 0)+ # A resident encoder is already on the card; other devices are not probed.+ assert worker._encode_device({"device": "cuda:0", "resident": True}, model) == "cuda:0"+ assert worker._encode_device({"device": "mps", "resident": False}, model) == "mps"+++def test_offloaded_encoder_on_xpu_is_budgeted_too(monkeypatch):+ import torch++ from core.inference import video_ltx25_te_worker as worker++ model = _FakeEncoderModel()+ monkeypatch.setattr(worker, "ENCODE_MARGIN_MIB", 10)+ offloaded = {"device": "xpu:0", "resident": False}+ free = {"mib": 12}++ def mem_get_info(_device):+ if free["mib"] is None:+ raise RuntimeError("no reading")+ return free["mib"] << 20, 80 << 30++ monkeypatch.setattr(torch, "xpu", SimpleNamespace(mem_get_info = mem_get_info), raising = False)+ assert worker._encode_device(offloaded, model) == "xpu:0"+ free["mib"] = 11+ assert worker._encode_device(offloaded, model) == "cpu"+ # Neither a free reading nor a budget: an XPU cannot be judged, so the encode stays on the CPU.+ free["mib"] = None+ assert worker._encode_device(offloaded, model) == "cpu"+ budgeted = dict(offloaded, budget_mib = 1000)+ monkeypatch.setattr(worker, "WORKER_CONTEXT_MIB", 100)+ assert worker._encode_device(budgeted, model, server_reserved_mib = 888) == "xpu:0"+ assert worker._encode_device(budgeted, model, server_reserved_mib = 889) == "cpu"+++def test_short_card_encodes_on_the_cpu_without_moving_the_encoder(monkeypatch):+ import torch++ from core.inference import video_ltx25_te_worker as worker++ model = _FakeEncoderModel()+ _patch_free(monkeypatch, 1)+ embeds, mask, device = worker._encode_on(+ _FakeTokenizer(), model, {"device": "cuda:0", "resident": False}, ["a fox"], 6+ )+ assert device == "cpu" and model.moves == []+ # Same packing as the GPU path: every hidden state stacked on a last axis, flattened.+ assert embeds.shape == (1, 6, 4 * 3) and embeds.dtype == torch.bfloat16+ assert mask.shape == (1, 6)+ assert worker._encode(_FakeTokenizer(), model, {"device": "cpu", "resident": False}, ["a"], 2)[+ 0+ ].shape == (+ 1,+ 2,+ 12,+ )+++def test_worker_reports_its_own_memory():+ from core.inference import video_ltx25_te_worker as worker+ stats = worker._memory_stats("cpu")+ assert stats.get("host_rss_mib", 0) > 0 and "gpu_peak_allocated_mib" not in stats+++class _Planned(Exception):+ pass+++def _ltx25_pack_plan(monkeypatch, total_gib):+ """Drive ``load_pipeline`` for the LTX-2.5 pack on a card of ``total_gib`` up to the encoder worker's start; return+ the plan it is placed by, the plan inputs and the placement."""+ import core.inference.diffusion_auto_policy as auto_policy+ import core.inference.diffusion_te_prequant as te_prequant+ import core.inference.video as vid+ from core.inference.diffusion_memory import DeviceMemory++ total = int(total_gib * 1024)+ target = SimpleNamespace(+ device = "cuda",+ dtype = None,+ torch_device = "cuda",+ ordinal = None,+ supports_model_cpu_offload = True,+ )+ backend = vid.VideoBackend()+ monkeypatch.setattr(backend, "_device_target", lambda *a, **k: target)+ monkeypatch.setattr(+ vid,+ "settled_snapshot_device_memory",+ lambda _t: DeviceMemory("cuda", "cuda", "discrete_vram", total - 600, total),+ )+ monkeypatch.setattr(te_prequant, "te_prequant_budget_scale", lambda *a, **k: 1.0)+ # The family table, not whatever pack sizes this machine's cache holds.+ monkeypatch.setattr(auto_policy, "base_repo_bf16_components_gb", lambda *_a, **_k: None)+ inputs = []+ real = vid.plan_diffusion_memory++ def capture(**kw):+ inputs.append(kw)+ return real(**kw)++ monkeypatch.setattr(vid, "plan_diffusion_memory", capture)+ seen = {}++ def placement(plan):+ seen["plan"], seen["resident"] = plan, v25.encoder_resident_for_plan.__wrapped__(plan)+ raise _Planned()++ placement.__wrapped__ = v25.encoder_resident_for_plan+ monkeypatch.setattr(v25, "encoder_resident_for_plan", placement)+ with pytest.raises(_Planned):+ backend.load_pipeline(+ "Lightricks/LTX-2.5-Diffusers", local_files_only = True, model_kind = "pipeline"+ )+ return seen["plan"], inputs[-1], seen["resident"]+++ "total_gib, policy, stream_te, stream_dit, resident",+ [+ # Companions alone exceed the card: the DiT and the encoder both stream; the worker never holds Gemma 4.+ (24, "group", True, True, False),+ # The DiT streams, the companions (Gemma 4 included) stay: the worker keeps it on the card.+ (48, "group", False, True, True),+ # The DiT fits once the encoder is not resident: the worker onloads only for an encode, when there is room.+ (80, "group", True, False, False),+ (180, "none", False, True, True),+ ],+)+def test_plan_counts_the_encoder_worker_per_card(+ monkeypatch, total_gib, policy, stream_te, stream_dit, resident+):+ from core.inference.video_ltx25 import LTX25_WORKER_RESIDENT_GB++ plan, inputs, placed_resident = _ltx25_pack_plan(monkeypatch, total_gib)+ mib = 1000.0**3 / 2**20+ te_mib = int(23.9 * mib)+ # The worker's weights are the encoder term, its context the always-resident companion share.+ assert inputs["text_encoder_dense_mib"] == te_mib+ assert inputs["companion_dense_mib"] == int((23.9 + 9.2 + LTX25_WORKER_RESIDENT_GB) * mib)+ assert inputs["model_dense_mib"] == int((42.0 + 23.9 + 9.2 + LTX25_WORKER_RESIDENT_GB) * mib)+ assert (plan.offload_policy, plan.stream_text_encoders, plan.stream_transformer) == (+ policy,+ stream_te,+ stream_dit,+ )+ assert placed_resident is resident+ if resident:+ # Whatever keeps the encoder resident budgeted its bytes on the card.+ budget = plan.estimates["safe_device_budget_mib"]+ floor = (+ plan.estimates["resident_required_mib"]+ if policy == "none"+ else plan.estimates["group_floor_mib"]+ )+ assert floor <= budget and inputs["text_encoder_dense_mib"] <= floor+++class _DeviceTensor:+ """Input ids / mask that accept a move to any device (no accelerator in CPU CI)."""++ def __init__(self, real):+ self.real = real+ self.shape = real.shape++ def to(self, device):+ return self if not str(device).startswith("cpu") else self.real+++class _AnyDeviceTokenizer(_FakeTokenizer):+ def __call__(self, prompts, **kwargs):+ out = super().__call__(prompts, **kwargs)+ return SimpleNamespace(+ input_ids = _DeviceTensor(out.input_ids), attention_mask = _DeviceTensor(out.attention_mask)+ )+++def test_offloaded_encoder_is_released_after_each_encode_and_reloaded_for_the_next(monkeypatch):+ from core.inference import video_ltx25_te_worker as worker++ monkeypatch.setattr(worker, "ENCODE_MARGIN_MIB", 0)+ _patch_free(monkeypatch, 1 << 20)+ model = _FakeEncoderModel()+ config = {"device": "cuda:0", "resident": False}+ for _ in range(2):+ _embeds, _mask, device = worker._encode_on(+ _AnyDeviceTokenizer(), model, config, ["a fox"], 4+ )+ assert device == "cuda:0"+ # Onto the card for each encode, back to the host after it.+ assert model.moves == ["cuda:0", "cpu", "cuda:0", "cpu"]+ resident = _FakeEncoderModel()+ worker._encode_on(+ _AnyDeviceTokenizer(), resident, {"device": "cuda:0", "resident": True}, ["a fox"], 4+ )+ assert resident.moves == [] # loaded onto the card once, at worker start+++def test_offloaded_encoder_borrows_only_budget_the_server_leaves(monkeypatch):+ """A free card is not enough: the plan did not budget the encoder, so it may only use the load's budget minus what+ the server holds at encode time."""+ from core.inference import video_ltx25_te_worker as worker++ model = _FakeEncoderModel() # 2 MiB+ monkeypatch.setattr(worker, "ENCODE_MARGIN_MIB", 10)+ monkeypatch.setattr(worker, "WORKER_CONTEXT_MIB", 100)+ _patch_free(monkeypatch, 1 << 20) # the card itself is wide open (a shared or larger card)+ config = {"device": "cuda:0", "resident": False, "budget_mib": 1000}+ assert (+ worker._encode_device(config, model, server_reserved_mib = 888) == "cuda:0"+ ) # 1000 - 888 - 100 = 12+ assert worker._encode_device(config, model, server_reserved_mib = 889) == "cpu"+ # No server figure: the card's free memory decides, as before.+ assert worker._encode_device(config, model, server_reserved_mib = None) == "cuda:0"+ # No free figure: the budget alone decides.+ _patch_free(monkeypatch, None)+ assert worker._encode_device(config, model, server_reserved_mib = 889) == "cpu"+ assert worker._encode_device(config, model, server_reserved_mib = 0) == "cuda:0"+++def test_client_sends_the_budget_and_the_servers_share():+ client = v25.Ltx25TextEncoderClient(+ repo = "Lightricks/LTX-2.5-Diffusers",+ hf_token = None,+ cache_dir = None,+ local_files_only = True,+ device = "cpu",+ dtype = "bfloat16",+ resident = False,+ venv_dir = "/nonexistent",+ budget_mib = 43622,+ )+ assert client.config["budget_mib"] == 43622+ assert v25._server_reserved_mib("cpu") is Nonediff --git a/studio/backend/tests/test_video_ltx25_refusal.py b/studio/backend/tests/test_video_ltx25_refusal.pydeleted file mode 100644index 6b6dfee241f..00000000000--- a/studio/backend/tests/test_video_ltx25_refusal.py+++ /dev/null@@ -1,411 +0,0 @@-# SPDX-License-Identifier: AGPL-3.0-only-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0--"""LTX-2.5 is refused instead of being loaded as LTX-2; LTX-2.0 / 2.3 still resolve to ltx-2."""--from __future__ import annotations--import json-import struct-from pathlib import Path--import pytest--from core.inference import diffusion_content as dc-from core.inference.video_families import (- assert_supported_ltx_version,- detect_video_family,- unsupported_ltx_version,-)--_FIXTURE = json.loads(- (Path(__file__).parent / "fixtures" / "comfy_checkpoint_headers.json").read_text(- encoding = "utf-8"- )-)--LTX25_NAMES = [- "Lightricks/LTX-2.5-Diffusers",- "Lightricks/LTX-2.5",- "lightricks/ltx-2.5",- "ltx-2.5-22b-distilled-transformer-bf16.safetensors",- "diffusion_models/ltx-2.5-22b-dev-transformer-bf16.safetensors",- "ltx-2.5-22b-distilled-transformer-comfy-int8-convrot.safetensors",- "ltx-2.5-22b-distilled-transformer-nvfp4.safetensors",- "someone/LTX-2.5-GGUF",- "ltx2.5",- "ltx2_5",- "LTX25",- "LTX-Video-2.5",-]--LTX2X_NAMES = [- "Lightricks/LTX-2",- "Lightricks/LTX-2.3",- "Lightricks/LTX-2.3-fp8",- "unsloth/LTX-2-FP8",- "unsloth/LTX-2.3-FP8",- "unsloth/LTX-2.3-GGUF",- "ltx-2-19b-dev.safetensors",- "ltx-2-19b-distilled-fp8.safetensors",- "ltx-2.3-22b-distilled.safetensors",- "ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf",- "LTX-2.3-22B-distilled-1.1-Q4_K_M.gguf",- "ltx-2.3-22b-distilled-1.1_transformer_only_int8_convrot.safetensors",- "ltx-2.3-spatial-upscaler-x1.5-1.0.safetensors",- "ltxv",- "ltx2",-]--[email protected]("name", LTX25_NAMES)-def test_ltx25_names_are_recognised(name):- assert unsupported_ltx_version(name) == "2.5"--[email protected]("name", LTX2X_NAMES)-def test_ltx2_and_ltx23_names_are_untouched(name):- assert unsupported_ltx_version(name) is None- assert detect_video_family(name).name == "ltx-2"--[email protected]("name", ["ltx-24fps-clip", "voltx-2.5", "ltx-23", "Lightricks/LTX-Video"])-def test_lookalikes_are_not_ltx25(name):- assert unsupported_ltx_version(name) is None---def test_prerelease_name_is_named_as_such():- assert unsupported_ltx_version("ltx-2.4-test") == "2.4"---def test_refusal_names_the_pick_and_the_alternative():- with pytest.raises(ValueError) as exc:- assert_supported_ltx_version("Lightricks/LTX-2.5-Diffusers")- text = str(exc.value)- assert "'Lightricks/LTX-2.5-Diffusers' is LTX-2.5" in text- assert "Gemma 4" in text- assert "LTX-2.3" in text---def test_picked_file_name_outranks_the_folder():- # An ltx-2.3 file in a folder someone named after 2.5 still loads...- assert_supported_ltx_version("/models/ltx-2.5-tests", "ltx-2.3-22b-distilled.safetensors")- # ... while a 2.5 file is refused whatever the folder is called...- with pytest.raises(ValueError, match = "ltx-2.5-22b-distilled-transformer-bf16"):- assert_supported_ltx_version(- "Lightricks/LTX-2.5",- "diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors",- )- # ... and a generically named file defers to the repo / display id.- with pytest.raises(ValueError, match = "LTX-2.5"):- assert_supported_ltx_version("Lightricks/LTX-2.5", "model.safetensors")- with pytest.raises(ValueError, match = "LTX-2.5"):- assert_supported_ltx_version("/tmp/x", "model.safetensors", "Lightricks/LTX-2.5")---def test_detect_load_family_refuses_ltx25_even_with_an_override():- from core.inference.video import _detect_load_family-- for override in (None, "ltx-2", "ltx-2.3"):- with pytest.raises(ValueError, match = "LTX-2.5"):- _detect_load_family("Lightricks/LTX-2.5-Diffusers", None, override)- with pytest.raises(ValueError, match = "LTX-2.5"):- _detect_load_family(- "Lightricks/LTX-2.5",- "diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors",- None,- )- assert (- _detect_load_family("Lightricks/LTX-2.3", "ltx-2.3-22b-distilled.safetensors", None).name- == "ltx-2"- )- assert _detect_load_family("Lightricks/LTX-2", None, None).name == "ltx-2"- assert (- _detect_load_family(- "unsloth/LTX-2.3-GGUF", "distilled/ltx-2.3-22b-distilled-Q4_K_M.gguf", None- ).name- == "ltx-2"- )---def test_validate_load_request_refuses_before_any_download():- from core.inference.video import get_video_backend-- backend = get_video_backend()- with pytest.raises(ValueError, match = "LTX-2.5"):- backend.validate_load_request("Lightricks/LTX-2.5-Diffusers", model_kind = "pipeline")- with pytest.raises(ValueError, match = "LTX-2.5"):- backend.validate_load_request(- "Lightricks/LTX-2.5",- gguf_filename = "diffusion_models/ltx-2.5-22b-dev-transformer-bf16.safetensors",- model_kind = "single_file",- family_override = "ltx-2",- )---def test_training_refuses_ltx25_base():- from core.training.diffusion_train_common import resolve_trainable_family- for family in (None, "ltx-2"):- with pytest.raises(ValueError, match = "LTX-2.5"):- resolve_trainable_family("Lightricks/LTX-2.5-Diffusers", family)---_LTX23_KEYS = [- "Lightricks/LTX-2.3/ltx-2.3-22b-distilled.safetensors",- "Lightricks/LTX-2.3/ltx-2.3-22b-dev.safetensors",- "Lightricks/LTX-2.3-fp8/ltx-2.3-22b-distilled-fp8.safetensors",- "Kijai/LTX2.3_comfy/diffusion_models/ltx-2.3-22b-distilled-1.1_transformer_only_int8_convrot.safetensors",- "Kijai/LTX2.3_comfy/diffusion_models/ltx-2.3-22b-distilled-1.1_transformer_only_mxfp8_block32.safetensors",- "Lightricks/LTX-2/ltx-2-19b-dev-fp4.safetensors",- "QuantStack/LTX-2.3-GGUF/LTX-2.3-distilled-1.1/LTX-2.3-22B-distilled-1.1-Q4_K_M.gguf",- "diffusers/ltx-2/LTX2VideoTransformer3DModel",-]---def _shapes(key):- entry = _FIXTURE[key]- return (entry["shapes"], entry.get("meta")) if "shapes" in entry else (entry, None)---def _as_ltx25(shapes):- """The 2.3 header with diffusers' 2.5 deltas applied: no video FFN bias, a keyframe position embedding."""- prefix = (- "model.diffusion_model."- if any(k.startswith("model.diffusion_model.") for k in shapes)- else ""- )- out = {- k: v- for k, v in shapes.items()- if not (".ff.net." in k and k.endswith(".bias") and ".audio_ff." not in k)- }- out[f"{prefix}keyframes_abs_pos_embedding"] = [1, 4096]- return out--[email protected]("key", _LTX23_KEYS)-def test_every_ltx2x_header_still_classifies_as_ltx2(key):- shapes, meta = _shapes(key)- assert dc.classify_tensors(shapes, meta).family == "ltx-2"--[email protected]("key", _LTX23_KEYS)-def test_ltx25_header_is_recognised_but_unsupported(key):- shapes, meta = _shapes(key)- info = dc.classify_tensors(_as_ltx25(shapes), meta)- assert info.role == dc.ROLE_DIT and info.family is None- assert "LTX-2.5" in info.what---def test_ltx25_header_without_the_embedding_is_still_caught():- # Fixture is trimmed past the FFN: re-add block 0's video FFN.- shapes, meta = _shapes("Lightricks/LTX-2.3/ltx-2.3-22b-distilled.safetensors")- ff = "model.diffusion_model.transformer_blocks.0.ff.net.0.proj"- no_bias = {**shapes, f"{ff}.weight": [16384, 4096]}- assert dc.classify_tensors(no_bias, meta).family is None- assert dc.classify_tensors({**no_bias, f"{ff}.bias": [16384]}, meta).family == "ltx-2"---def _write_header_only_safetensors(path: Path, shapes: dict) -> None:- header = {k: {"dtype": "BF16", "shape": v, "data_offsets": [0, 0]} for k, v in shapes.items()}- raw = json.dumps(header).encode()- path.write_bytes(struct.pack("<Q", len(raw)) + raw)---def test_renamed_local_ltx25_file_is_refused_by_its_header(tmp_path):- from core.inference.video import get_video_backend- from core.inference.video_ltx2 import assert_not_ltx25_checkpoint-- shapes, _ = _shapes("Lightricks/LTX-2.3/ltx-2.3-22b-distilled.safetensors")- good = tmp_path / "ltx-2.3-renamed.safetensors"- bad = tmp_path / "ltx-2.3-but-really-2.5.safetensors"- _write_header_only_safetensors(good, shapes)- _write_header_only_safetensors(bad, _as_ltx25(shapes))- assert_not_ltx25_checkpoint(good)- with pytest.raises(ValueError, match = "LTX-2.5"):- assert_not_ltx25_checkpoint(bad)- message = dc.refusal_for(str(bad), "video")- assert message and "LTX-2.5" in message- assert dc.resolve_family_with_content("ltx-2", str(bad), "video") == (None, True)- with pytest.raises(ValueError, match = "LTX-2.5"):- get_video_backend().validate_load_request(- str(tmp_path), gguf_filename = bad.name, model_kind = "single_file"- )---def test_local_ltx25_diffusers_folder_is_refused_by_model_index(tmp_path):- from core.inference.video import _detect_load_family-- folder = tmp_path / "my-ltx-video"- folder.mkdir()- index = {- "_class_name": "LTX2Pipeline",- "text_encoder": ["transformers", "Gemma4UnifiedForConditionalGeneration"],- "transformer": ["diffusers", "LTX2VideoTransformer3DModel"],- }- (folder / "model_index.json").write_text(json.dumps(index), encoding = "utf-8")- with pytest.raises(ValueError, match = "model_index.json"):- _detect_load_family(str(folder), None, None)- index["text_encoder"] = ["transformers", "Gemma3ForConditionalGeneration"]- (folder / "model_index.json").write_text(json.dumps(index), encoding = "utf-8")- assert _detect_load_family(str(folder), None, None).name == "ltx-2"- index["duration_head"] = ["diffusers", "LTX2DurationHead"]- (folder / "model_index.json").write_text(json.dumps(index), encoding = "utf-8")- with pytest.raises(ValueError, match = "LTX-2.5"):- _detect_load_family(str(folder), None, None)- index["duration_head"] = [None, None]- (folder / "model_index.json").write_text(json.dumps(index), encoding = "utf-8")- assert _detect_load_family(str(folder), None, None).name == "ltx-2"--- "filename", ["ltx-transformer.safetensors", "ltxv_dit.safetensors", "LTX.safetensors"]-)-def test_unversioned_ltx_file_name_defers_to_the_repo(filename):- from core.inference.video import get_video_backend-- with pytest.raises(ValueError, match = "LTX-2.5"):- assert_supported_ltx_version("Lightricks/LTX-2.5", filename)- with pytest.raises(ValueError, match = "LTX-2.5"):- get_video_backend().validate_load_request(- "Lightricks/LTX-2.5",- gguf_filename = filename,- model_kind = "single_file",- family_override = "ltx-2",- )- # A version-free name is no evidence either way in a 2.0 / 2.3 repo.- assert_supported_ltx_version("Lightricks/LTX-2.3", filename)--- "filename", ["ltx-2-19b-dev.safetensors", "ltx2_dit.safetensors", "ltx-video-2.3-x.safetensors"]-)-def test_versioned_supported_file_name_still_outranks_the_folder(filename):- assert_supported_ltx_version("/models/ltx-2.5-tests", filename)---def test_training_refuses_renamed_local_ltx25_pipeline(tmp_path):- from core.training.diffusion_train_common import resolve_trainable_family-- folder = tmp_path / "my-video-base"- folder.mkdir()- index = {- "_class_name": "LTX2Pipeline",- "text_encoder": ["transformers", "Gemma4UnifiedForConditionalGeneration"],- "transformer": ["diffusers", "LTX2VideoTransformer3DModel"],- }- (folder / "model_index.json").write_text(json.dumps(index), encoding = "utf-8")- for family in (None, "ltx-2"):- with pytest.raises(ValueError, match = "model_index.json"):- resolve_trainable_family(str(folder), family)- index["text_encoder"] = ["transformers", "Gemma3ForConditionalGeneration"]- (folder / "model_index.json").write_text(json.dumps(index), encoding = "utf-8")- assert resolve_trainable_family(str(folder), "ltx-2") == "ltx-2"---def test_explicit_pipeline_load_ignores_the_unused_filename(tmp_path):- from core.inference.video import _detect_load_family, get_video_backend-- with pytest.raises(ValueError, match = "LTX-2.5"):- get_video_backend().validate_load_request(- "Lightricks/LTX-2.5",- gguf_filename = "ltx-2.3-22b-dev.safetensors",- model_kind = "pipeline",- family_override = "ltx-2",- )- folder = tmp_path / "opaque"- folder.mkdir()- index = {- "_class_name": "LTX2Pipeline",- "text_encoder": ["transformers", "Gemma4UnifiedForConditionalGeneration"],- }- (folder / "model_index.json").write_text(json.dumps(index), encoding = "utf-8")- with pytest.raises(ValueError, match = "model_index.json"):- _detect_load_family(str(folder), "ltx-2.3.safetensors", "ltx-2", None, "pipeline")- # A real single-file pick still lets its own ltx-2.3 file decide.- assert (- _detect_load_family(str(folder), "ltx-2.3.safetensors", "ltx-2", None, "single_file").name- == "ltx-2"- )---def test_training_name_guard_is_scoped_to_ltx(tmp_path):- from core.training.diffusion_train_common import resolve_trainable_family-- folder = tmp_path / "sdxl-ltx-2.5-style"- folder.mkdir()- (folder / "model_index.json").write_text(- json.dumps({"_class_name": "StableDiffusionXLPipeline"}), encoding = "utf-8"- )- assert resolve_trainable_family(str(folder), "sdxl") == "sdxl"- with pytest.raises(ValueError, match = "LTX-2.5"):- resolve_trainable_family(str(folder), "ltx-2")--- "name", ["ltxv-2.5.safetensors", "ltxv25", "LTXV_2_5-dev.safetensors", "ltxv2.4"]-)-def test_versioned_ltxv_alias_is_refused(name):- assert unsupported_ltx_version(name) is not None- with pytest.raises(ValueError, match = "LTX-2"):- assert_supported_ltx_version("/models/x", name)--- "filename",- [- "ltx-24fps-clip.safetensors",- "ltx-23.safetensors",- "ltx-2.10-x.safetensors",- "ltx2fast.safetensors",- ],-)-def test_numeric_lookalike_file_name_defers_to_the_repo(filename):- with pytest.raises(ValueError, match = "LTX-2.5"):- assert_supported_ltx_version("Lightricks/LTX-2.5", filename)- assert_supported_ltx_version("Lightricks/LTX-2.3", filename)---def test_inference_name_guard_is_scoped_to_ltx():- from core.inference.video import _detect_load_family-- fam = _detect_load_family(- "someone/wan-ltx-2.5-style",- "wan-ltx-2.5-style.safetensors",- "wan2.2-ti2v-5b",- None,- "single_file",- )- assert fam is not None and fam.name == "wan2.2-ti2v-5b"- with pytest.raises(ValueError, match = "LTX-2.5"):- _detect_load_family(- "someone/wan-ltx-2.5-style",- "wan-ltx-2.5-style.safetensors",- "ltx-2",- None,- "single_file",- )---def test_ltx25_companion_base_is_refused(tmp_path, monkeypatch):- import core.inference.diffusion as diffusion- from core.inference.video import get_video_backend-- # Isolate the LTX-2.5 check from the pipeline-completeness check on the stub folder.- monkeypatch.setattr(diffusion, "_assert_local_base_is_pipeline", lambda *a, **k: None)-- backend = get_video_backend()- pick = dict(gguf_filename = "distilled/ltx-2.3-22b-distilled-Q4_K_M.gguf", model_kind = "gguf")- with pytest.raises(ValueError, match = "LTX-2.5"):- backend.validate_load_request(- "unsloth/LTX-2.3-GGUF", base_repo = "unsloth/LTX-2.5-Diffusers", **pick- )- folder = tmp_path / "my-base"- folder.mkdir()- index = {- "_class_name": "LTX2Pipeline",- "text_encoder": ["transformers", "Gemma4UnifiedForConditionalGeneration"],- }- (folder / "model_index.json").write_text(json.dumps(index), encoding = "utf-8")- with pytest.raises(ValueError, match = r"by its model_index\.json\) is LTX-2\.5"):- backend.validate_load_request("unsloth/LTX-2.3-GGUF", base_repo = str(folder), **pick)diff --git a/studio/frontend/src/features/model-picker/components/model-selector/family-override.ts b/studio/frontend/src/features/model-picker/components/model-selector/family-override.tsindex 19b53adc610..965966ff5ae 100644--- a/studio/frontend/src/features/model-picker/components/model-selector/family-override.ts+++ b/studio/frontend/src/features/model-picker/components/model-selector/family-override.ts@@ -23,6 +23,7 @@ const LABELS: Readonly<Record<string, string>> = {sdxl: "SDXL","minimax-h3": "MiniMax-H3","ltx-2": "LTX-2",+ "ltx-2.5": "LTX-2.5","wan2.2-ti2v-5b": "Wan2.2 TI2V 5B","wan2.2-t2v-a14b": "Wan2.2 T2V A14B","wan2.1-t2v-1.3b": "Wan2.1 T2V 1.3B",diff --git a/studio/frontend/src/features/video/keyframe-canvas.ts b/studio/frontend/src/features/video/keyframe-canvas.tsindex 53ace3e3f9b..820e63c8938 100644--- a/studio/frontend/src/features/video/keyframe-canvas.ts+++ b/studio/frontend/src/features/video/keyframe-canvas.ts@@ -54,8 +54,41 @@ export function matchedCanvas(width *= scale;height *= scale;}- const snap = (value: number) => Math.max(multiple, Math.round(value / multiple) * multiple);- return [snap(width), snap(height)];+ return snapCanvasWithinCap(width, height, multiple, maxPixels);+}++/** Each side to the nearest multiple; when that pushes the area past the cap, a side rounds down+ * instead (largest area under the cap, then the aspect nearest the unsnapped one). Mirrors the+ * backend's snap_canvas_within_cap. */+export function snapCanvasWithinCap(+ width: number,+ height: number,+ multiple: number,+ maxPixels: number,+): [number, number] {+ const down = (value: number) => Math.max(multiple, Math.floor(value / multiple) * multiple);+ const near = (value: number) => Math.max(multiple, Math.floor(value / multiple + 0.5) * multiple);+ const w = near(width);+ const h = near(height);+ if (w * h <= maxPixels) return [w, h];+ const target = Math.log(width / height);+ const fits = (+ [+ [down(width), h],+ [w, down(height)],+ [down(width), down(height)],+ ] as [number, number][]+ ).filter(([cw, ch]) => cw * ch <= maxPixels);+ if (fits.length === 0) return [down(width), down(height)];+ let best = fits[0];+ for (const candidate of fits.slice(1)) {+ const area = candidate[0] * candidate[1];+ const bestArea = best[0] * best[1];+ const distance = Math.abs(Math.log(candidate[0] / candidate[1]) - target);+ const bestDistance = Math.abs(Math.log(best[0] / best[1]) - target);+ if (area > bestArea || (area === bestArea && distance < bestDistance)) best = candidate;+ }+ return best;}/** Which keyframes the loaded checkpoint takes. Newer backends report each one; an older backenddiff --git a/studio/frontend/tests/video-keyframe-canvas.test.ts b/studio/frontend/tests/video-keyframe-canvas.test.tsindex d1db19bec02..1fe0c6ca4d4 100644--- a/studio/frontend/tests/video-keyframe-canvas.test.ts+++ b/studio/frontend/tests/video-keyframe-canvas.test.ts@@ -112,3 +112,31 @@ test("keyframe support: per-frame fields win, the legacy flag covers old backend);assert.deepEqual(keyframeSupport(null), { first: false, last: false });});++// LTX-2.5's rule: 704 px short edge, 1280x704 cap, 64 px units.+const ltx25: VideoGenerationDefaults = {+ ...h3,+ resolution_multiple: 64,+ resolution_presets: [[1280, 704]],+ canvas_short_edge: 704,+ canvas_max_pixels: 1280 * 704,+};++test("snapping never leaves the pixel cap, and matches the backend at its edges", () => {+ // Rounding both sides up used to give 576x1664 here, 6% past LTX-2.5's cap.+ assert.deepEqual(matchedCanvas(0.32841, 1, ltx25), [512, 1664]);+ assert.deepEqual(matchedCanvas(0.32841, 1, h3), [576, 1760]);+ assert.deepEqual(matchedCanvas(0.25, 1, ltx25), [448, 1920]);+ assert.deepEqual(matchedCanvas(3.045, 1, ltx25), [1664, 512]);+ for (const defaults of [ltx25, h3]) {+ const multiple = defaults.resolution_multiple ?? 1;+ for (let i = 2500; i <= 40000; i += 7) {+ const canvas = matchedCanvas(i / 10000, 1, defaults);+ assert.ok(canvas);+ const [width, height] = canvas;+ assert.ok(width * height <= (defaults.canvas_max_pixels ?? 0), `${i}: ${width}x${height}`);+ assert.equal(width % multiple, 0);+ assert.equal(height % multiple, 0);+ }+ }+});