zero0303/ltx-2.5-mlx-dynamic-8bit

LTX-2.5 for MLX (dynamic 8-bit)

An Apple Silicon (MLX) port of LTX-2.5 by Lightricks: text to video and image to video (a start image), the distilled two-stage pipeline, with dynamic 8-bit weights. No PyTorch, no CUDA.

• Ported line by line from the official code (v1.5.0, commit e98f6d9): tokenizer, Gemma 4 text encoder, feature extractor and connectors, the 48-block audio-video transformer, the ancestral sampler and its noise order, the x2 latent upsampler, the tiled conv VAE decoder and the H.264 file; for image to video the still's loading and H.264 re-compression, the VAE encoder, the per-token timesteps and the pinning of the first frame in both stages.
• Proven against the official model at its own precision (bf16) before quantizing: in fp32 every part matches the official fp32 output (strict gates); in bf16 every part is as accurate as the official bf16 against the exact answer (ratio 0.98-1.00); the whole sampling chain reproduces the official run bit for bit.
• Dynamic 8-bit (in the spirit of Unsloth's dynamic quants): every one of the 1,771 large weight matrices was quantized on its own and its effect measured (fp32, real denoising states); whole recipes were then compared on held-out data against the official 16-bit model's own rounding error. The most sensitive tensors stay 16-bit (48 in the transformer, mostly in its last blocks; 48 in Gemma, the token embeddings and the early layers' feed-forwards), the rest is 8-bit, group size 32. Result: 45.8 GB instead of 66 GB, as fast as 16-bit, and within about 5% of the official 16-bit model's own error (below).

Independent port; not an official Lightricks release. See NOTICE.md.

Quickstart

Requirements: an Apple Silicon Mac (tested on an M5 with 24 GB; a clip peaks at 9.3 GB), Python 3.14, ffmpeg on the PATH, 46 GB of disk.

hf download zero0303/ltx-2.5-mlx-dynamic-8bit --local-dir ltx-2.5-mlx
cd ltx-2.5-mlx
uv venv --python 3.14 .venv
VIRTUAL_ENV=$PWD/.venv uv pip install "mlx==0.32.2" "numpy==2.4.6" "tokenizers==0.23.3" "av==19.0.2" "pillow==13.0.0"
.venv/bin/python generate.py "Night, heavy rain on an empty city street ..." -o clip.mp4 --seed 7

Options: --width 1024 --height 576 (multiples of 64), --frames 121 (8k + 1; 121 = 5.04 s), --fps 24, --seed, --image start.png (the clip starts from this image; --image-strength, default 1.0), --models (this pack by default, or a folder with Lightricks' 16-bit release). The output is an H.264 MP4 (BT.709, crf 19), no sound.

From Python:

import sys; sys.path.insert(0, "ltx-2.5-mlx")
from ltx25.pipeline import generate

generate("A lighthouse on a cliff at dusk, waves below, the camera slowly circles.", "out.mp4", seed=42,
         width=1024, height=576, num_frames=121, models="ltx-2.5-mlx/models/ltx-2.5-mlx-8bit")

Speed and memory (M5, 24 GB)

One 5-second clip at 1024 x 576 (121 frames): 440 s (7.3 min). Prompt encoding 17 s, stage 1 (8 steps at 512 x 288) 16 s a step, stage 2 (3 steps at 1024 x 576) 72 s a step, the 16-bit model's speed; decoding 70 s. Peak memory 9.3 GB for the whole process (MLX's own peak 7.6 GB, in the prompt encoding): the weights are streamed one transformer block or Gemma layer at a time, and the decoder works through each tile a few frames at a time.

Accuracy

Error of one denoising call against the exact fp32 model (Lightricks' weights), on real full-size inputs, as a multiple of the official-precision 16-bit runtime's own error:

	stage 1 (2,304 tokens)	stage 2 (9,216 tokens)
16-bit (official precision)	1.00	1.00
dynamic 8-bit	1.05 video, 1.04 audio	1.06 video, 1.07 audio

Measured on its own (fp32), the quantization adds about 0.4 of the 16-bit rounding error in the transformer and 0.48-0.61 in the text encoder. Plain 8-bit (every weight 8-bit) adds 0.72-1.48 in the text encoder, up to more than 16-bit itself: errors in Gemma's early layers grow through its 48 layers. Keeping the sensitive tensors 16-bit is what fixes that.

Files

File	Size	Contents
models/ltx-2.5-mlx-8bit/diffusion_models/ltx-2.5-22b-distilled-transformer-8bit.safetensors	26.0 GB	the transformer (1,296 block matrices and the 96 connector linears 8-bit; 48 block matrices, norms, gates, AdaLN, patchify and output layers as shipped)
models/ltx-2.5-mlx-8bit/text_encoders/gemma4-12b-with-proj-ltx-2.5-8bit.safetensors	17.4 GB	Gemma 4 12B and the two aggregate projections (283 matrices 8-bit; the embeddings and 47 sensitive matrices as shipped) and the tokenizer
models/ltx-2.5-mlx-8bit/vae/ltx-2.5-video-vae-conv-bf16.safetensors	1.5 GB	the video VAE, unchanged
models/ltx-2.5-mlx-8bit/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors	1.0 GB	the x2 latent upscaler, unchanged
models/ltx-2.5-mlx-8bit/quant.json		the recipe: files, group size, the tensors kept 16-bit, the scans

Code: ltx25/ (the port) and generate.py (the command line). The parity tests against the official model and the quantization scripts are not part of this repository; their results are summarised below.

How it was checked

	Result
Tokenizer	16/16 prompts identical to the official
Every part, fp32	strict gates against the official fp32 (Gemma's 49 states ≤ 4.4e-6, transformer ≤ 2.2e-5, VAE 1.6e-5)
Every part, bf16	as accurate as the official bf16 against the exact answer (ratios 0.98-1.00)
Sampling chain	all 11 denoising steps, both terminal steps and the stage-2 noise blend bit for bit
8-bit export	every stored code, scale and bias equals a fresh quantization of the official weight; everything else byte-identical
8-bit runtime	within 1.04-1.07x of the 16-bit's own error at full size; text contexts within 0.5-1.0% of exact
Image to video	the still's pixels, re-compression and encoder input bit for bit; the encoder as accurate as the official (0.99-1.00); the masked sampling chain bit for bit; a full call with the mask: strict fp32 7.4e-5 / 3.9e-6, bf16 ratio 0.98 / 1.04
Reviews	two independent code reviews against the official source, then a per-file read

Not included

Other conditioning (keyframe guides after frame 0, EXR / HDR stills, video-to-video), audio decoding (the audio stream is generated jointly, as the model requires, but not decoded), LoRAs, prompt enhancement, long multi-chunk videos. One clip at a time.

Licence and credit

LTX-2.5 weights and code © Lightricks Ltd., under the LTX-2.x Community License Agreement (LICENSE, unchanged). This repository is a Derivative of LTX-2.x and is distributed under that Agreement: its use restrictions (Section 4, Attachment A) apply to you, and entities with US$10M or more in annual revenue need a paid licence from Lightricks for commercial use. The two 8-bit files are modified (see NOTICE.md).