MrMofer/ltx-2.5-mlx-q8

LTX-2.5 MLX q8

An MLX/Apple Silicon conversion of the LTX-2.5 model layout. This repository contains the q8 transformer checkpoints and the supporting LTX-2.5 components needed by the ltx-2-mlx runtime. It runs natively through MLX and Metal; CUDA is not required.

Runtime pin: LTX-2.5 support is on the ltx25 branch. The public main branch remains oriented toward LTX-2.3. Use the branch and commit below rather than an arbitrary main checkout.

• Runtime: https://github.com/MrMoferFRAN/ltx-2-mlx/tree/ltx25
• Branch: ltx25
• Pinned source commit: 57952288076766abe27dda3a774b2c24f7346977

Quick start

Requirements: macOS on Apple Silicon, Python 3.11 or newer, and ffmpeg.

git clone https://github.com/MrMoferFRAN/ltx-2-mlx.git
cd ltx-2-mlx
git checkout ltx25
git checkout 57952288076766abe27dda3a774b2c24f7346977
uv sync --all-extras

LTX-2.5 uses the Gemma 4 checkpoint bundled under text_encoder/. The runtime detects it from text_encoder/config.json when model_type is gemma4; no separate Gemma download and no --gemma option are required for this model. Use mlx-lm >= 0.31.3 (the lockfile pins 0.31.3).

A video uses 8n + 1 frames, dimensions divisible by 32, and normally a 24 fps frame rate. Start with modest dimensions and increase them as memory allows.

Distilled two-stage generation

The distilled example uses the q8 transformer-distilled.safetensors for both denoising stages: half-resolution generation, spatial upscale, then full-resolution refinement. --low-ram streams transformer blocks and is recommended on a 24 GB Apple Silicon Mac.

uv run --project ltx-2-mlx ltx-2-mlx generate --model MrMofer/ltx-2.5-mlx-q8 \
  --prompt "A small sailboat crossing a calm sea at golden hour" \
  --distilled --low-ram --height 480 --width 704 --frames 97 --frame-rate 24 \
  --output distilled.mp4

Dev two-stage generation

The standard two-stage example requires transformer-dev.safetensors for stage 1: the dev model runs with CFG at half resolution, then the model is refined at full resolution with the LTX-2.5 distilled LoRA (ltx-2.5-22b-distilled-lora-450.safetensors).

uv run --project ltx-2-mlx ltx-2-mlx generate --model MrMofer/ltx-2.5-mlx-q8 \
  --prompt "A small sailboat crossing a calm sea at golden hour" \
  --two-stage --low-ram --height 480 --width 704 --frames 97 --frame-rate 24 \
  --output two-stage.mp4

Model layout and quantization

The repository follows the split MLX layout expected by ltx-2-mlx:

Path	Role	Representation
transformer-distilled.safetensors	Distilled 22B audio/video transformer	q8 affine MLX weights, group size 64
transformer-dev.safetensors	Dev 22B audio/video transformer for CFG modes	q8 affine MLX weights, group size 64
ltx-2.5-22b-distilled-lora-450.safetensors	LTX-2.5 distilled LoRA for stage 2	LoRA safetensors; applied at runtime
text_encoder/	Bundled Gemma 4 LTX text encoder and tokenizer	4-bit affine MLX weights, group size 64
connector.safetensors	Text-to-video/audio feature connector	bf16
vae_encoder.safetensors, vae_decoder.safetensors	Video VAE	bf16
audio_vae.safetensors, vocoder.safetensors	Audio VAE and vocoder	bf16
spatial_upscaler_x2.safetensors, temporal_upscaler_x2.safetensors	Latent upscalers	bf16
duration_head.safetensors	Audio/video duration prediction head	bf16
config.json, embedded_config.json, *_config.json	Runtime and component configuration	JSON

The q8 transformer files are quantized for MLX rather than stored as ordinary full-precision PyTorch tensors. The text encoder's quantization is recorded in text_encoder/config.json as 4-bit affine, group size 64. Supporting components remain bf16 unless their individual configuration says otherwise.

Pipeline modes

The CLI mode determines which transformer files are needed:

• --distilled: distilled two-stage path, no CFG. It uses transformer-distilled.safetensors in stage 1 and stage 2.
• --two-stage: dev transformer + CFG at half resolution, upscale, then distilled-LoRA refinement. The LTX-2.5 stage-2 LoRA is ltx-2.5-22b-distilled-lora-450.safetensors.
• --two-stages-hq: the same dev/LoRA two-stage arrangement, but stage 1 uses the higher-quality second-order res_2s sampler.
• --one-stage: dev transformer + CFG directly at the target resolution; it does not use the distilled LoRA as a second stage.
• a2v: audio-to-video. The normal two-stage path requires the dev transformer and uses the distilled LoRA for stage 2; a2v --one-stage also requires the dev transformer and skips stage 2.

With --two-stage, --two-stages-hq, or the normal a2v path, stage 2 is selected as follows:

• without --low-ram, the runtime loads the dev transformer and applies the 450-step distilled LoRA;
• with --low-ram and the default LoRA strength of 1.0, it streams the pre-fused transformer-distilled.safetensors instead;
• with --low-ram and a non-default --distilled-lora-strength, it keeps the dev stream and attaches the 450-step LoRA at that strength during block binding.

The transformer-dev.safetensors file is therefore required for all dev/CFG modes (--two-stage, --two-stages-hq, --one-stage, and standard a2v), while --distilled can run from the distilled checkpoint alone.

Sampler details

For an LTX-2.5 checkpoint, the distilled pipeline's stage 1 uses the port of the upstream EulerAncestralDiffusionStep with eta=1.0 and s_noise=1.0. It performs the default 8 ancestral steps and draws fresh per-step noise from the pipeline seed stream (the implementation uses seed + 10000 for that stream). Stage 2 uses the deterministic three-step refinement schedule.

This is sampler implementation detail, not a separate CLI mode: there is no independent CLI mode named Euler. The dev --two-stage path uses guided deterministic Euler in stage 1, --two-stages-hq uses res_2s, and their stage 2 is deterministic.

Apple Silicon memory guidance

--low-ram is recommended for q8 generation on a Mac with 24 GB unified memory because it streams transformer blocks from the safetensors file. This is a recommendation, not a claim of direct testing on every 24 GB configuration; runtime validation has been performed on an M4 Max. Actual limits depend on resolution, frame count, pipeline mode, and other applications using unified memory.

License and use

The runtime software is an open-source MLX port, but the model files are derived from the official Lightricks LTX-2.5 weights. The official weights and their derivatives have their own license and use conditions; they are not relicensed by this conversion or by the runtime repository. Read LICENSE.md in this repository and the upstream LTX-2 license, including the acceptable-use and redistribution terms, before downloading, modifying, or using the weights commercially. This is an unofficial community conversion and does not imply endorsement by Lightricks.

Credits

• Lightricks for LTX-2 / LTX-2.5 and the reference model.
• dgrauet/ltx-2-mlx for the MLX runtime and conversion layout.