ltx-2.5-mlx-q8

LTX-2.5 — int8 text encoder (MLX)

A complete LTX-2.5 component tree whose only difference from mlx-community/ltx-2.5-mlx is the Gemma-4 text encoder, quantized to int8 (13.6 GB vs 23.8 GB). Everything else is byte-identical to the base repo and is duplicated here only so this tree resolves standalone.

⚠️ This repo does NOT contain a quantized DiT. The transformer is a separate axis: see mlx-community/ltx-2.5-mlx-ditq8. The two are independent — you can mix an int8 encoder with a bf16 or int8 DiT.

Why it exists — it is load-bearing on small machines, not a nicety

With the DiT streamed, LTX-2.5's peak memory is set by a geometry-independent ~24.8 GB floor that turns out to be the bf16 encoder (measured: a 256×256×9 clip and a 512×288×121 clip peak within 0.01 GB of each other — a decode-bound peak would scale with geometry; this does not). That floor is over the budget of both 24 GB and 32 GB machines.

Swapping in this int8 encoder takes the whole-run peak to 14.6 GB / 15.4 GB respectively. Neither lever works alone: resident is DiT-bound, so the encoder swap is invisible without streaming, and streaming alone leaves the encoder floor.

Recipe

int8, group 64, with embed_tokens deliberately EXCLUDED (kept bf16). Hidden state 00 is embedTokens(ids) · embedScale — one of the 49 states the connector consumes directly, and the input to all 48 layers. Quantizing it moves that state on its own; state 00 == 1.000000 exactly is the fingerprint that it stayed bf16.

Fidelity

Connector output at valid token positions — the number that decides a text-encoder quant — reads 0.999820 against a 0.999879 bf16 floor.

⚠️ Read that metric, not a whole-array cosine. With a short prompt most of the 1024 positions are learned registers, identical across every encoder arm, which dilutes a whole-array figure 3–30×: a deliberately-poisoned arm scored 0.994316 whole-array but 0.829329 on its real tokens.

⚠️ The sample MOVES. Output is not bit-identical to bf16 (mean −0.1421/σ 0.4253 vs −0.1274/0.4222) — a different but equally valid video, because changing the encoder changes the conditioning and therefore the trajectory. Judged acceptable in a blind 4-pair perceptual A/B across prompts including a close-up face, at both 704×512 and a clamped 512×288 one-stage geometry. Comparing the arms with SSIM/PSNR would be a category error.

Licence

LTX-2 Community License — see LICENSE.md and the acceptable-use policy snapshot. Derivative of Lightricks LTX-2.5, carrying its terms including the Attachment A revenue gate and non-compete. Redistribution permitted under §3 with those terms propagated.

vae_decoder_pruna.safetensors — PrunaAI's lean video decoder (optional)

What it is. PrunaAI/PrunaVAED (revision 4baacd7ef66a6131439542c1f05872afe042e128, last modified 2026-07-29), a pruned, distillation-finetuned drop-in replacement for the LTX-2 video VAE decoder, converted on 2026-07-31 from its diffusers layout to this repo's ltx-core flat decoder dialect with scripts/convert_pruna_vae_decoder.py. The conversion is a key mapping plus the PyTorch→MLX conv transposition; no tensor values are changed. Only the decoder is produced: the encoder, the latent format and the per-channel statistics are the stock ones, and the video VAE is byte-identical across LTX-2.3 and LTX-2.5, so one file serves both. It is not a pure width prune — two blocks carry a channel-adapter ResBlock (conv_in 512→384 and 384→256, with an affine norm3) that the stock decoder lacks; the MLX decoder derives every width from the weights and enables those adapters on sight.

Why it is here. Decode is roughly 2× faster and the decode activation peak materially smaller, at a decode that is near-identical but not bit-exact. Measured on a 24 GB M5 Pro at the compact24 tier (receipt AB-R-0561, ltx-2-mlx-swift): −15.9 % wall-clock per clip at the tier's own envelope with the peak unchanged, and where decode binds (704×512×121) a 21.1 → 14.5 GB peak that turns an over-budget, swapping run into one within budget. The Swift port selects it with LTX2Configuration.vaeDecoderPath or LTX_VAE_DECODER=pruna, and makes it the default decoder on the low tiers (compact24, balanced32) once promoted. The port reads its components from this int8-encoder sibling tree whenever the int8 text encoder is selected (the shipping low-tier configuration), which is why the file is hosted here as well as in the base repo.

Licence. PrunaAI publishes PrunaVAED under the LTX-2 licence (license_name: ltx-2, base model diffusers/LTX-2.3-Diffusers). This converted copy is redistributed under the same LTX-2 Community License Agreement that governs every other file in this repo, with this section as the modification notice (Agreement §3.3). Mirroring and layout conversion do not alter, relax or re-license anything.

Integrity. vae_decoder_pruna.safetensors — 690,025,680 bytes — SHA-256 891ec5f0680acea9acbdd651c9756a26c5d3298480224356cf5ea86071846f79.