Skip to content

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.

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.py
index 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.py
index 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.py
index 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.py
index 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 generically
named 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, False
fam = (
(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 fam
from .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_content
if fam is None or fam.name != name:
fam = detect_video_family("", override = name)
- return fam
+ return fam, by_content
+ return fam, False
def _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_scale
companions_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_GB
model_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 = 0
self._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_event
self._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_native
if 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:
return
logger.error("video.load_failed: %s", exc)
@@ -4078,6 +4209,17 @@ class VideoBackend:
from .gpu_arbiter import VIDEO, release_if
release_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 compiled
GGUF 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_weight
from .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_REFERENCES
h3_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):
continue
files.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 None
from 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] = None
roots: 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 load
pass
- 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_keys
def _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_GB
vae_scale = 1.0 if getattr(fam, "vae_force_fp32", False) else dtype_scale
scaled_te_gb = text_encoder_gb * dtype_scale
scaled_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 pipe
clear_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_adapter
install_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_policy
and 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_cache
diffusion_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 = None
logger.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_pil
for 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_pil
if 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 = None
if 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)
+
@staticmethod
def _resolve_flow_shifts(
fam: VideoFamily,
@@ -10586,6 +11039,9 @@ class VideoBackend:
from . import diffusion_prompt_cache
diffusion_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.py
index 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 version
return None
def 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 json
from pathlib import Path
try:
index = Path(str(path or "")).expanduser() / "model_index.json"
if not path or not index.is_file():
- return
+ return None
spec = json.loads(index.read_text(encoding = "utf-8"))
except (OSError, ValueError, TypeError):
- return
+ return None
if not isinstance(spec, dict) or not str(spec.get("_class_name", "")).startswith("LTX2"):
- return
+ return None
encoder = 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] = None
i2v_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]) -> dict
return {}
+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 identifier
naming 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 local
path 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_DEFAULTS
variant = 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.py
index 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_message
if 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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[int
if 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.py
index 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**30
diff --git a/studio/backend/tests/fixtures/ltx25_checkpoint_headers.json b/studio/backend/tests/fixtures/ltx25_checkpoint_headers.json
new file mode 100644
index 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 file
diff --git a/studio/backend/tests/test_diffusion_memory.py b/studio/backend/tests/test_diffusion_memory.py
index 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 GiB
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index 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.fixture
def 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,
continue
calls.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.0
assert 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",
} <= off
assert 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 _FAMILIES
if not fam.cudnn_benchmark
)
diff --git a/studio/backend/tests/test_video_families.py b/studio/backend/tests/test_video_families.py
index 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.py
new file mode 100644
index 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 None
diff --git a/studio/backend/tests/test_video_ltx25_refusal.py b/studio/backend/tests/test_video_ltx25_refusal.py
deleted file mode 100644
index 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.ts
index 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.ts
index 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 backend
diff --git a/studio/frontend/tests/video-keyframe-canvas.test.ts b/studio/frontend/tests/video-keyframe-canvas.test.ts
index 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);
+ }
+ }
+});