# LTX-2.5 Studio — Design Plan **Status (2026-11-16):** implemented. After the 2026-11-16 fixes, all eleven modes are verified on real weights on a Mac (Apple silicon); none has been re-run on the Space, which still runs the 2026-08-26 build. What has been verified, and how, is in [`SPACE_MODE_MATRIX.md`](SPACE_MODE_MATRIX.md) §10. *(Originally: "implemented; not yet run on a GPU. The matrix in `docs/TEST_PLAN.md` is what proves it works.")* **Branch:** `soma/ltx25-studio` · **Remote:** `git@github.com:techfreakworm/ltx2.5-studio.git` **Target:** private Hugging Face Space `techfreakworm/LTX2.5-Studio` (gradio SDK, ZeroGPU). > ✅ **Status superseded by events (annotated 2026-08-25).** "Not yet run on a > GPU" was true when written. Since then: **all eleven modes ran on hinode** > (704×480×121 baseline, stage 2 at 1408×960, duration head f=97, LoRA both > directions, mel round-trip — [`OPERATOR_HANDOFF.md`](OPERATOR_HANDOFF.md) §2) > and **all eleven execute on the live ZeroGPU Space** at sha `287ba9c`, > 256×256×9 ([`SPACE_MODE_MATRIX.md`](SPACE_MODE_MATRIX.md)). *(Corrected > 2026-11-16: this said "generate". Every Space output up to `ff142d9` was colour > static, because the int8 build quantised the conditioning path; fixed at > `eb1aa9f`.)* The line above is > kept because this document records how the build was *decided*; where the > project *stands* is the handoff's job. Where a decision below was overtaken — > the bf16 default (§2.6), the ~68 GB ceiling (§2), the explicit `size=` > (§8.6), the disk routes (§7.4, §10 risk 1) — a dated annotation sits on it. > ### ⚠️ Read this before you trust the test suite > > **This suite was green at 1102 passing tests while five blockers were live in the tree.** > At that moment the app could not reach a GPU, could not apply a LoRA, and reported every > successful run in its three flagship modes as an internal error. Nothing was failing. > > The ~700 tests added since are almost entirely **seam and reachability** tests, not more unit > coverage — because more tests of the original shape would have found none of it. §9.1.1 > explains the pattern and the one check that catches it. > > If you are about to trust a green gate here the way we did: that is the mistake this document > exists to warn you out of. This document is the contract for the build. Every section is either a **decision** (settled, build to it) or a **risk** (§10, needs measurement not argument). Where a claim was verified against real source or real repo metadata, the evidence is cited inline so a future reader can re-check it instead of trusting it. **Prime directive:** this app must not repeat the failure modes of its predecessor (`ltx2.3-AIO-generator`). Those were not model failures. They were *packaging, pinning, and silent-failure* failures. §5 and §8 are the sections the build will be judged on. **A note on how to read this document.** Several statements here contradict things that are true of *other* diffusion apps, or true of LTX-2.5 on a normal GPU box but false on ZeroGPU. The biggest is §8: **`enable_model_cpu_offload()` must not be used.** If a future reader's instinct says otherwise, §8.4 explains why the instinct is wrong here. --- ## 1. Decision 1 — Integration path: **Diffusers**, pinned to an exact SHA We build on `diffusers`, loading `Lightricks/LTX-2.5-Diffusers`. ### 1.1 Options considered | | Path | What it is | Verdict | |---|---|---|---| | **A** | `ltx-pipelines` | Lightricks' own repo, installed via `uv sync` of a git workspace | **Rejected** | | **B** | ComfyUI runtime | Vendor ComfyUI + custom nodes, drive it via API graphs | **Rejected** | | **C** | `diffusers` | `diffusers.pipelines.ltx2`, weights from `Lightricks/LTX-2.5-Diffusers` | **CHOSEN** | ### 1.2 Why C **Path A is a heavy, fragile install for a Space.** It needs `uv sync` of a git workspace, CUDA >= 12.7, torch ~= 2.7. A Space build that resolves a git workspace at image-build time is a build we cannot reproduce or pin. **Path B is the documented cause of the fragility we are told to avoid.** The 2.3 project's `requirements.txt` vendors an entire ComfyUI runtime — ~50 dependencies, nearly all unpinned: `spandrel`, `torchsde`, `kornia`, `PyOpenGL`, `glfw`, `SQLAlchemy`, `alembic`, `Mako`, `blake3`, `comfyui-frontend-package`, `comfyui-workflow-templates`, `comfyui-embedded-docs`, plus a hand-maintained block of *custom-node deps we discovered are required but aren't auto-installed by their respective nodes* (`gguf`, `imageio_ffmpeg`, `opencv-python`, `matplotlib`, `scikit-image`, `onnxruntime`, `yt-dlp`). That comment block is the evidence: the dependency surface was discovered by breakage, not by design. Diffusers replaces all of it with 19 direct deps, each pinned to one version (§5.1), and zero custom-node surface. **Decisive coupling to §2.** The `*-comfy-int8-convrot` quantised weights are **ComfyUI-only** — the model card says so. Choosing A or C means those 36.9 GB of int8 weights are unusable to us. Path choice and disk budget are one decision, not two. ### 1.3 The pinned revision — and why a release tag will not do ``` diffusers @ git+https://github.com/huggingface/diffusers@ac56fa2f25c1c15b4cbaa1e0b3255e9bc38c06dc ``` HEAD at 2026-08-19T12:11:04Z. Contains the LTX-2.5 merge (PR #14447, 2026-08-11) plus #14453 and #14462. PEP 508 direct reference — **not** the legacy `#egg=` form. **A SHA is more pinned than a version range, not less.** It is byte-for-byte reproducible and cannot drift. It costs a git clone at build time and manual upgrades; both are acceptable. **The latest release (0.39.0) does not have 2.5, and it fails LATE.** `LTX2Pipeline` imports fine on 0.39.0 — so the app starts, the UI renders, weights begin downloading — and only then does it fail on a missing `temporal_latent_upsampler`. A failure that happens after 70 GB of download is the worst kind. **Confirmed by the repo itself.** `model_index.json` on `Lightricks/LTX-2.5-Diffusers` declares `_diffusers_version: 0.40.0.dev0`. The weights and the code agree on the dev version; our SHA pin is not a guess. **Therefore: a startup fail-fast assertion.** ```python assert diffusers.__version__ == "0.40.0.dev0", ( f"LTX-2.5 needs the pinned diffusers SHA (reports 0.40.0.dev0); got {diffusers.__version__}. " "See docs/PLAN.md §1.3." ) ``` This converts a late, confusing, expensive failure into an immediate, obvious one. It lives in `preflight.py` (§7.1) and it is a test case (§9.3). ### 1.4 The single-file escape hatch: investigated and REJECTED `diffusers/loaders/single_file_utils.py` does contain an LTX-2 route: `CHECKPOINT_KEY_NAMES["ltx2"]` → `model_type = "ltx2-dev"` → config repo `{"pretrained_model_name_or_path": "Lightricks/LTX-2"}`. Note the repo: **`LTX-2`, i.e. 2.0, not 2.5**. The converters it ships are only `convert_ltx2_transformer_to_diffusers`, `convert_ltx2_vae_to_diffusers` and `convert_ltx2_audio_vae_to_diffusers` — all keyed on `LTX_2_0_*` rename dicts. There is **no** single-file converter for 2.5's `connectors`, `diffusion_decoder`, `vocoder`, `duration_head` or `latent_upsampler`. Even a successful load would give us a pipeline missing the components that make 2.5 what it is. Settled; do not revisit without new upstream converters. > ### ⛔ CORRECTED 2026-08-25 — the observation is right, the conclusion is wrong > > **`from_single_file` IS implemented for LTX2 at the pinned SHA.** 📄 Verified by > reading `ac56fa2f`: > > * `LTX2VideoTransformer3DModel` inherits **`FromOriginalModelMixin`** — > `models/transformers/transformer_ltx2.py:1081`. > * It is registered in `SINGLE_FILE_LOADABLE_CLASSES` at > **`loaders/single_file_model.py:207`**, with `AutoencoderKLLTX2Video` (211) > and `AutoencoderKLLTX2Audio` (215). > > The `LTX_2_0_*` naming above is accurate and is **not** a blocker: those are > local rename dicts *inside* `convert_ltx2_transformer_to_diffusers` > (`single_file_utils.py:4060`), not a version gate. What survives from this > section is the narrower half — there is no single-file route for 2.5's > `connectors`, `diffusion_decoder`, `vocoder`, `duration_head` or > `latent_upsampler`, so a whole-**pipeline** single-file load is unavailable. We > would never want one: the Diffusers pack supplies those, and the only thing > worth swapping is the transformer, which **is** loadable this way. > > **The real reason the vendor quantised weights are rejected is FORMAT, and it > is a worse reason than the one written here** — 📄 verified by range-reading the > real safetensors headers over the Hub: > > * `ltx-2.5-22b-distilled-transformer-comfy-int8-convrot.safetensors` carries > **`.comfy_quant` `U8[72]` per-Linear ComfyUI metadata**. `convert_ltx2_transformer_to_diffusers` > knows nothing about it, so the file would **load silently as garbage rather > than raise** — the single worst failure mode available, and precisely the one > this project has just spent three weeks failing to detect (see the > invalidation blocks in `SPACE_MODE_MATRIX.md` / `SPACE_SESSION_2026-08-25.md`). > * `ltx-2.5-22b-distilled-transformer-nvfp4.safetensors` is **FP4-packed with > halved inner dims** and needs NVIDIA **ModelOpt** to unpack. It is not a > safetensors file diffusers can interpret. > > Still rejected — for these reasons, not the stated one. Do not re-derive the > rejection from the `LTX_2_0_*` naming; that argument is void. --- ## 2. Decision 2 — Disk, RAM and dtype budget Three separate resource ceilings, and the tightest one is not the obvious one. | resource | ceiling | our load | margin | |---|---|---|---| | **VRAM** (`xlarge`) | ~95 GiB | 67.2 GiB weights | ~28 GiB for activations — **comfortable** | | **CPU RAM** | **~68 GB** (community cgroup observation, *not* an official figure — HF publishes ZeroGPU RAM as `"-"` / "Dynamic resources") | ~72 GB | **marginal — risk #1** | | **Ephemeral disk** | 150 GB, **wiped on every restart/rebuild** | **152–156 GB peak** (§2.5) | **EXCEEDS THE CAP — settled, not a risk** | **VRAM was never the problem.** The problems are CPU RAM and the startup disk peak — and the second is now settled rather than uncertain: it does not fit (§2.5). > ⛔ **The CPU RAM row is FALSIFIED (annotated 2026-08-25).** The ~68 GB figure > was inherited — a community cgroup observation, never ours — and the platform > measured past it: a load peaked at **87.13 GiB = 93.56 GB** RSS on ZeroGPU and > was not killed, so the ceiling is **above 93.56 GB** and "marginal — risk #1" > died with the number (`SPACE_GENERATION_FINDING.md` §6). The disk row's > verdict stood for bf16 — and was then routed around: the deployed Space ships > **int8** (`ZEROGPU_DISK.md` Option B) and fits at **82.2 GB of 150 [OK]**. > > ⛔ **Corrected 2026-11-16, two rows.** (1) "82.2 GB of 150 [OK]" is a reading > taken *before* ZeroGPU packs (packed term 0.0). On the 2026-11-13 boot the > platform's progress bar read `40.6G` packed; the disk peak has never been measured. > (2) The VRAM row assumed `xlarge`. Until 2026-08-26 the Space ran on the > 47.375 GiB `large` partition (`auto` never promotes, §2.6), where stage 2 at > 704×480×49 — 55.906 GiB reserved — could not fit: on `large`, VRAM *was* the > problem. On `xlarge` (94.971 GiB, now the code's default) that is the largest > peak measured, with ~39 GiB to spare. ### 2.1 Trap A — duplicate shard sets Two folders ship the *same weights twice*, in two different shardings: | folder | set 1 | set 2 | note | |---|---|---|---| | `transformer/` | 4 shards: 9.932 + 9.919 + 9.986 + 8.138 = **37.975 GB** | 8 shards: 4.991 + 4.944 + 4.994 + 4.928 + 4.977 + 4.995 + 4.994 + 3.163 = **37.986 GB** | only **one** `diffusion_pytorch_model.safetensors.index.json` | | `connectors/` | single file: **6.344 GB** | 2 shards: 5.000 + 1.344 = **6.344 GB** | same | **Resolved against the actual index files — which set is live is now measured, not inferred:** | folder | LIVE set | DEAD weight | |---|---|---:| | `transformer/` | the **4-shard** set — 37.976 GB | 37.986 GB | | `connectors/` | the **2-shard** set — 6.345 GB | 6.344 GB | | `text_encoder/` | all 5 shards — 23.920 GB | none | | `transformer_full/` | 4 shards (excluded entirely, §2.2) | none | | | | **total avoidable waste: 44.33 GB** | Note the direction on `connectors/`: the **2-shard** set is live and the single 6.344 GB file is the dead one — the opposite of the naive guess that a single file must be canonical. A naive `snapshot_download` of those folders pays the full 44.33 GB. `from_pretrained` reads the index JSON and fetches only the referenced shards. **Binding consequences:** (1) we rely on the index, never hand-rolling a `snapshot_download` of `transformer/`; (2) any `preload_from_hub:` entry must name **only the live shards**. A wrong list here does not fail fast — it fails after tens of GB, and on a 150 GB cap it evicts us. ### 2.2 Trap B — `transformer_full/` is the DEV transformer A further **37.975 GB**, the *dev* (non-distilled) transformer. We ship the distilled 8-step path, so we do not ship it. Documented as opt-in (§2.5), not deleted from our mental model. ### 2.3 The bf16 subset we ship — **37 files, 72.185 GB (67.23 GiB)** Measured from the Hub's own byte counts, not estimated. The `GB` column is decimal (bytes / 1e9), matching how the Hub reports sizes. | component | GB | loaded via | why | |---|---:|---|---| | `transformer/` | 37.9762 | index | the model (4 live shards + config + index) | | `text_encoder/` | 23.9195 | index | `Gemma4UnifiedForConditionalGeneration` (§10 OQ-4) | | `connectors/` | 6.3445 | index | text → transformer conditioning; also a LoRA target | | `vae/` | 1.4522 | index | video VAE: encodes conditions, and decodes wherever the diffusion decoder cannot run (§7.4) | | `latent_upsampler/` | 0.9957 | **subfolder** | stage-2 spatial upscale | | `diffusion_decoder/` | 0.8343 | index | **the native 2.5 decoder** — §7.4 | | `temporal_latent_upsampler/` | 0.2619 | **subfolder** | stage-2 temporal upscale | | `vocoder/` | 0.2583 | index | `LTX2VocoderWithBWE` — **not** plain `LTX2Vocoder` | | `audio_vae/` | 0.1065 | index | audio VAE (mel ↔ latent) | | `tokenizer/` | 0.0322 | index | `GemmaTokenizer` | | `duration_head/` | 0.0038 | index | duration prediction | | `scheduler/` | ~0 | index | `FlowMatchEulerDiscreteScheduler` -- config-only, but every pipeline constructor needs it, and it uses `scheduler_config.json`, not `config.json` | | `model_index.json` (repo root) | ~0 | — | the component manifest | | **TOTAL** | **72.185** | | **= 67.23 GiB, 44% of the repo — we skip 92.005 GB** | > ⛔ **Corrected 2026-11-17: the Space loads 35 of these files, 71.92 GB.** > `temporal_latent_upsampler/` (0.2619 GB) is no longer fetched: nothing loads it, since the > stage graph wires only the spatial `latent_upsampler`. Every file's size is recorded in > `model_files.py`, and the image brings the set (`preload_from_hub`, §6.2). **`model_index.json`, verbatim** — this is the authority for what the pipeline expects: ``` _class_name: LTX2Pipeline _diffusers_version: 0.40.0.dev0 audio_vae: ['diffusers', 'AutoencoderKLLTX2Audio'] connectors: ['ltx2', 'LTX2TextConnectors'] diffusion_decoder: ['diffusers', 'LTX2VideoDiffusionDecoderModel'] duration_head: ['ltx2', 'LTX2DurationHead'] processor: [None, None] prompt_enhancer: [None, None] scheduler: ['diffusers', 'FlowMatchEulerDiscreteScheduler'] text_encoder: ['transformers', 'Gemma4UnifiedForConditionalGeneration'] tokenizer: ['transformers', 'GemmaTokenizer'] transformer: ['diffusers', 'LTX2VideoTransformer3DModel'] vae: ['diffusers', 'AutoencoderKLLTX2Video'] vocoder: ['ltx2', 'LTX2VocoderWithBWE'] ``` **Two loading mechanisms, and `model_files.py` must model the difference.** `latent_upsampler` and `temporal_latent_upsampler` are **not in `model_index.json`**. They are loaded separately by subfolder, exactly as the model card does: ```python LTX2LatentUpsamplerModel.from_pretrained(MODEL_ID, subfolder="latent_upsampler") ``` Index-components and subfolder-components are fetched by *different calls*. A resolver that assumes one mechanism silently misses two components — and they are precisely the two the stage-2 quality path needs. ### 2.4 What we exclude, and why | excluded | GB | reason | |---|---:|---| | `transformer_full/` | 37.977 | the DEV transformer; not needed for the distilled 8-step path | | duplicate shard sets (transformer 8-shard + connectors single-file) | 44.330 | Trap A — same weights, different sharding | | `ltx-2.5-22b-distilled-lora-450-bf16.safetensors` (repo root) | 9.699 | the distilled LoRA for **DEV** workflows; useless when we ship the distilled transformer | **Arithmetic check:** 72.185 + 37.977 + 44.330 + 9.699 = **164.191 GB**, closing against the repo's stated 164.19 GB across 56 files (37 shipped, 19 skipped). **Precision note, because it has already bitten once.** Summing figures that were each truncated to three decimals gives 37.975 for the transformer; the exact byte count (37,976,221,088 B) gives **37.9762**. The difference is 220 KB and irrelevant to the disk budget, but it is larger than a ±0.001 assertion tolerance. `model_files.py` carries the byte-exact values, so any test asserting on sizes should use a tolerance of ±0.01, not ±0.001. The accounting is complete; there is no unexplained remainder. ### 2.5 The startup disk peak — negative margin, not tight margin > **Authoritative section for this arithmetic.** The mechanism is §8.3; the > consequence for the deploy is §7.4. If those and this ever disagree, this one > is wrong — do not reconcile by editing the other two. > > *Provenance: verified against `spaces` 0.51.1 source (`zero/torch/patching.py`, > `zero/configs.json`), not inferred.* Startup holds **two** copies: the HF cache (~72.19 GB) *and* the packed copy ZeroGPU writes to `~/.zerogpu/tensors` (~72.19 GB). The 2.3 project was evicted with exactly this: `"Workload evicted, storage limit exceeded (150G)"`. **The packer does auto-prune the HF blobs** — `ZEROGPU_MMAP_AUTOPRUNE_PATTERN` = `~/.cache/huggingface/hub/models--*/blobs/*`, logging `"Cleaned NGB of tensor files ... after packing"`. **That is verified, and it does not save us**, because the unlink runs *strictly after* `_pack()` returns: | | GB | |---|---:| | HF cache snapshot | 72.19 | | ZeroGPU packed copy (**one** pipeline, post-`from_pipe`) | 72.19 | | **peak, before the prune can run** | **144.37** | | the image itself — torch + CUDA | **+8–12** | | **total against a 150 GB cap** | **152–156** | **The margin is negative, not tight.** An earlier draft of this section read it as *"6 GB of margin is not much"* — that figure never counted the image, which is not optional and is present for the whole window. The prune is real; it simply happens **after** the peak it would have to prevent. Steady state afterwards is fine at ~72 GB. **It is the peak that evicts us, not the residency**, and the two have different fixes — which is why they are stated separately here. §5.6's preflight measures free disk and reports a number, so an eviction arrives as a diagnosable message rather than anonymously. Remaining headroom after packing: `150 − 72.19 ≈ 77.8 GB` for the pip environment, user LoRA uploads and outputs. `transformer_full/` (37.98 GB) fits in that — which is why it is opt-in rather than impossible — but enabling it leaves ~40 GB and makes output eviction urgent. ### 2.6 dtype and quantization — **default bf16**, quantization is a documented fallback Packed weight size decides which ZeroGPU tier we land on, and the tier decides quota cost. The threshold is `xlarge_threshold = 42.00 GiB`: **exceed it and ZeroGPU silently auto-promotes to `xlarge` and doubles quota cost, with no code change.** > ⛔ **The premise in bold is FALSE, and finding that out cost this project half > its GPU (2026-08-27).** Crossing the threshold sets `_default_gpu_size`, which > is read by exactly one function — `get_duration_seconds` — and feeds exactly > one branch: the `duration_factor` multiplier. It never reaches the `gpuSize` > the scheduler allocates on, which is sent **only** when a size is passed > explicitly. ✅ Measured from inside the worker: `LTX25_ZEROGPU_SIZE=auto` ran > the Space on `large` at **47.375 GiB**; setting `xlarge` gives **94.971 GiB**. > The tier argument below is still the right argument — it is just an argument > for *setting the variable*, never for trusting the packer to set it. > [`MIG_ALLOCATOR_SIGHTINGS.md`](MIG_ALLOCATOR_SIGHTINGS.md) §1. | config | approx total | packed vs 42.00 GiB | tier | quota | verdict | |---|---:|---|---|---|---| | **bf16 everything** | 72.19 GB (67.2 GiB) | over | `xlarge` | **2×** | **DEFAULT** — documented by the model card, matches the official Lightricks Space pattern; RAM/disk marginal | | fp8 transformer (~19) + bf16 TE (~24) + rest (~10) | ~53 GB (~49.3 GiB) | over | `xlarge` | 2× | comfortable RAM/disk, no quota win | | fp8 transformer + int8 TE | ~41 GB (~38.2 GiB) | **under** | `large` | **1×** | best quota economics, highest accuracy risk | **⚠️ The quantized checkpoints are not available to us at all — the blocker is FORMAT, not size.** The int8 / nvfp4 files exist only in `Lightricks/LTX-2.5`, the **native** repo; there are none in the Diffusers pack. And our single-file path cannot load them: `CHECKPOINT_KEY_NAMES["ltx2"]` → `ltx2-dev` → config repo `Lightricks/LTX-2` (that is **2.0**), with every converter named `LTX_2_0_*` and **nothing for 2.5's connectors, diffusion_decoder, vocoder, duration_head or latent_upsampler** (§1.4). So no plan should be written around the quantized files being reachable — they are a different repo in a format we have no converter for. > ⛔ **CORRECTED 2026-08-25:** the verdict holds; the reason given here does not. > `from_single_file` **is** wired for `LTX2VideoTransformer3DModel` at the pinned > SHA (`loaders/single_file_model.py:207`, `FromOriginalModelMixin` at > `transformer_ltx2.py:1081`) 📄, so "our single-file path cannot load them" is > false. The real blockers, verified by range-reading the Hub headers: the > `comfy-int8-convrot` file carries `.comfy_quant` `U8[72]` per-Linear ComfyUI > metadata and would **load silently as garbage rather than raise**, and `nvfp4` > is FP4-packed with halved inner dims and needs ModelOpt. §1.4's correction > carries the detail. **Why bf16 is the default and not the quantised config.** Shipping quantised by default would trade a *known* uncertainty for an *unverified* one: - The RAM ceiling (~68 GB) is a community cgroup observation, not an official number. It is uncertain, but it is uncertainty about a configuration that upstream documents and that a production Space already runs. - ~~Quantization carries its own unquantified risk: bitsandbytes and torchao use custom tensor subclasses and the packer's handling of them is unverified.~~ **This was wrong.** `spaces/zero/torch/bitsandbytes.py` is a 43-line version check that **no-ops for bnb ≥ 0.46.0**, wired into the packing path at `patching.py:328/355/445` — so modern bitsandbytes needs **no special handling at all**. There is **no equivalent module for torchao**, and that asymmetry is what actually selects the library. *Verified against `spaces` 0.51.1.* See `docs/ZEROGPU_DISK.md`. So bf16 ships and `size="xlarge"` is **declared explicitly** rather than being silently promoted (§8.5). > ⛔ **Both halves of that sentence were overtaken (annotated 2026-08-25), and > the section's default inverted with them.** The deployed Space ships **int8**, > not bf16 — `components_to_quantize=["transformer", "text_encoder"]` via > `PipelineQuantizationConfig` + bitsandbytes (text encoder widened at > `02fe943`) — landed as the fix for the eviction this section's bf16 default > ran into, and it is what makes the Space fit disk (82.2/150 [OK]). And > `size=` was **never declared**: every deploy has run `LTX25_ZEROGPU_SIZE=auto` > → `size=None`, so ZeroGPU promoted to `xlarge` by inference (packed ~51.1 GB > int8 > 42.00 GiB) — see §8.6's annotation and `OPERATOR_HANDOFF.md` §4 > gap 0. Quantization is therefore no longer "a documented fallback" — it is > **the configured, deployed route**; the reasoning above stands as the record > of why bf16 was chosen first, and its load-bearing premise (the ~68 GB > ceiling, "uncertain but documented") is falsified besides > (`SPACE_GENERATION_FINDING.md` §6). The §6.2.1-class route list at the end of > this section omitted the route actually taken. > > ⛔ **Corrected 2026-11-16.** "ZeroGPU promoted to `xlarge` by inference" is wrong: > `auto` never promotes (the block above this section's table), so the Space ran > on `large` until `LTX25_ZEROGPU_SIZE=xlarge` was set as a Space variable on > 2026-08-26. The code now defaults to `xlarge` (`config.DEFAULT_ZEROGPU_SIZE`), > so `size="xlarge"` is declared explicitly after all — by default, not by a > variable. "Packed ~51.1 GB": the platform's progress bar read `40.6G` on the > 2026-11-13 boot. "82.2/150 [OK]" is a reading taken before packing. **⚠️ There is no precision switch, and the reason is a correction rather than a decision.** `LTX25_TRANSFORMER_PRECISION` and `LTX25_TEXT_ENCODER_PRECISION` existed, resolved cleanly, and were **wired to nothing** — `pipelines.get_pipeline` never read the config, so the load was always bf16. Worse, `expected_weights_gb` applied the precision factor anyway, so the startup report stated **53.20 GB for a load that was still 72.19 GB**. It did not fail silently: it *spoke*, and the number was wrong in the direction that misdirects the next decision. It was one approval away from being reached for to fix a disk eviction, twice. **An advertised lever attached to nothing is worse than no lever at all**, so it was removed rather than half-wired. Wiring it properly needs `bitsandbytes` or `torchao` — neither pinned, neither verifiable without a GPU. **The reason originally given here — that the packer's handling of quantised tensors was unknown — was false; see above.** The lever is gone because it was **wired to nothing**, which is reason enough on its own. Quantization remains a *documented option*; it is not a *configured* one, and the difference is now visible in the code rather than implied. > ⛔ **Corrected 2026-11-16: there is a precision switch now, and it is wired.** > `LTX25_QUANTIZATION` = `auto` (the default: int8 on ZeroGPU, bf16 everywhere else) | > `bf16` | `int8`, resolved in `config.py` and `device.py`; int8 is bitsandbytes > (pinned, §5.1) and is refused at startup off CUDA. The two removed variables stay > removed. The routes actually available under disk pressure are persistent storage, a public Space, or smaller checkpoints — see §6.2.1. **⚠️ Flipping precision is a REBUILD, not a runtime switch.** Preloading is all-or-nothing (§6.2): preloaded files are owned by the build user and read-only to the runtime, so a quantised variant needing *different files* cannot be fetched on demand into that cache. If a future precision setting changes the file list, the Space must be rebuilt with a new `preload_from_hub` block. Setting the variable alone changes how the existing weights are loaded -- nothing more. This is **technical risk #1** (§10), and it is to be settled by measurement on the Space, not by argument. *(2026-11-16: moot as built. int8 is applied at load time to the same files, so changing `LTX25_QUANTIZATION` needs no new download and no rebuild.)* ### 2.7 Output retention — 20 GB, evicted oldest-first `outputs/` is capped at **20 GB**, bounded-bytes, oldest-first eviction, as a single constant in `config.py` overridable by env. Swept **on startup** (`app.py`) **and after every successful generation** (`generate.py`), logging each eviction and surfacing it on the result's warnings. Both call sites are deliberately **non-fatal**: the user's video exists and is fine, so a retention failure must not turn a good run into an error, and a bad cap must not stop the app from starting. A policy that exists but is never called prevents nothing -- which is precisely what was true here until the call sites were added. Rationale: ~78 GB headroom minus the pip environment and a user LoRA or two. 20 GB is many generations and leaves the margin the 2.3 Space did not have when it filled its disk and went unhealthy. *(As built, 2026-11-16: the folder is `LTX25_OUTPUT_DIR`, `outputs` by default, and the writer and the startup sweep read the same setting. Gradio serves a file a step returns only from the working directory, the system temp dir, its own cache or `launch(allowed_paths=…)`, so a folder that resolves outside the first two is passed by `app.main` as the only allowed path (`e7cde1a`); in Gradio 6.24 a non-empty `allowed_paths` replaces `GRADIO_ALLOWED_PATHS` for that launch. A launcher that calls `app.demo.launch()` itself must pass the same. A run whose result Gradio still cannot show ends with Generate back and a card saying so, never on "Generating…" (`55692f5`).)* --- ## 3. Decision 3 — Mode coverage: 11 UI modes over 4 real workflows All 11 requested modes are reachable. **They are not 11 code paths**, and the plan says so plainly — describing them as independent implementations would be dishonest and would produce a much worse registry. ### 3.1 The four real workflows From `_workflow_map` in `diffusers/modular_pipelines/ltx2/modular_blocks_ltx25.py`: ``` text2video {prompt} image2video {image, prompt} condition {conditions, prompt} in_context {reference_conditions, num_frames, prompt} ``` Our **11 UI modes are a presentation layer over those four**, plus the audio-latent input route and the audio-only export. That is the honest description, and it is also the design that keeps the registry small: `modes.py` is data over four builders, not eleven. ### 3.2 Three facts that shape everything **(a) One conditioning mechanism covers both image and video.** `LTX2VideoCondition.frames` is typed `PIL.Image.Image | list[PIL.Image.Image] | np.ndarray | torch.Tensor` — "the image (**or video**) to condition the video on" — and carries `index` and `strength`. Image- and video-conditioning are *the same code path* with a different payload. See §5.7 for the `index` trap, which is severe. **(b) The model is jointly audio-visual. There is no video-off switch.** The return type is `LTX2PipelineOutput(frames=..., audio=...)`, both non-optional tensors. Every call spends video compute and returns a video. This is the most important cost fact in the app. **(c) Audio input is not a first-class kwarg.** There is no `audio=` argument. Audio enters as `audio_latents` — upstream documents it as *"Optional pre-encoded audio latents; random noise is used when not provided"* — combined with `noise_scale`. `prepare_audio_latents` routes through `_create_noised_state`, whose body is `noise_scale * noise + (1 - noise_scale) * latents`: img2img-style strength, where `1.0` discards the input entirely. ### 3.3 The mode registry | # | Mode | Workflow | How it is reached | Cost note | |---|---|---|---|---| | 1 | text → video | text2video | `prompt` | first-class | | 2 | image → video | condition | one `LTX2VideoCondition(frames=PIL, index=0)`, empty prompt | first-class | | 3 | image + text → video | condition | as #2 with a prompt | first-class | | 4 | video → video | condition | `LTX2VideoCondition(frames=