mlx-community/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.