Skip to content

feat: add LTX-2.5 support - #1893

Open
pwilkin wants to merge 1 commit into
leejet:masterfrom
pwilkin:ltx-2-5-support
Open

feat: add LTX-2.5 support#1893
pwilkin wants to merge 1 commit into
leejet:masterfrom
pwilkin:ltx-2-5-support

Conversation

@pwilkin

@pwilkin pwilkin commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

I'll let Claude describe the details, it's surprisingly not that different from LTX-2.3:

LTX-2.5 shares its video VAE, audio VAE, vocoder and spatial upscaler architecture with LTX-2.3, so those need no changes. The transformer differs in two places and the text encoder moves from Gemma 3 to Gemma 4.

Transformer:

  • Detect ff_bias and audio_ff_bias separately from the weights. LTX-2.5 sets ff_bias=false but leaves audio_ff_bias at its default, so a single flag would drop the audio FFN biases.
  • Add the keyframes_abs_pos_embedding marker, applied after patchify_proj to the tokens of the first latent frame.
  • Cast learnable_registers to F32 when the checkpoint stores them at another type, as the published LTX-2.5 GGUFs do.

Text encoder (LLMArch::GEMMA4_12B):

  • Full-attention layers use a 512-wide head with a single KV head and no v_proj, taking V from the raw K projection; sliding layers keep 256/8.
  • V is normalized with a weightless RMS norm and never rotated.
  • Attention runs unscaled, and RoPE is proportional on full-attention layers, implemented with freq_factors so the unrotated pairs collapse to identity without reordering the head.
  • Each layer ends with its learned layer_scalar.
  • Both the transformers and the llama.cpp GGUF layer-norm namings are accepted, so the bundled single-file checkpoint loads directly.

The Gemma 4 vocabulary differs from Gemma 3 only in reserved slots and shares its merge table, so the embedded Gemma vocab still produces the right token ids.

LTX-2.5 bundles the text projection into its text encoder, so --embeddings-connectors is no longer required; the projection is looked up under the --llm prefix as well.

Verified on the Q8_0 dev transformer for T2V, I2V, spatial latent upscaling and a Q8_0-converted text encoder, and against Z-Image for the shared attention and feed-forward changes.

Summary

It works. That's good, right? :) The guys from the LTX team said they'd gladly help if there are any issues (they contacted me by mail after I filled in the gating form on HF).

Checklist

LTX-2.5 shares its video VAE, audio VAE, vocoder and spatial upscaler
architecture with LTX-2.3, so those need no changes. The transformer
differs in two places and the text encoder moves from Gemma 3 to Gemma 4.

Transformer:

- Detect ff_bias and audio_ff_bias separately from the weights. LTX-2.5
  sets ff_bias=false but leaves audio_ff_bias at its default, so a single
  flag would drop the audio FFN biases.
- Add the keyframes_abs_pos_embedding marker, applied after patchify_proj
  to the tokens of the first latent frame.
- Cast learnable_registers to F32 when the checkpoint stores them at
  another type, as the published LTX-2.5 GGUFs do.

Text encoder (LLMArch::GEMMA4_12B):

- Full-attention layers use a 512-wide head with a single KV head and no
  v_proj, taking V from the raw K projection; sliding layers keep 256/8.
- V is normalized with a weightless RMS norm and never rotated.
- Attention runs unscaled, and RoPE is proportional on full-attention
  layers, implemented with freq_factors so the unrotated pairs collapse
  to identity without reordering the head.
- Each layer ends with its learned layer_scalar.
- Both the transformers and the llama.cpp GGUF layer-norm namings are
  accepted, so the bundled single-file checkpoint loads directly.

The Gemma 4 vocabulary differs from Gemma 3 only in reserved <unusedN>
slots and shares its merge table, so the embedded Gemma vocab still
produces the right token ids.

LTX-2.5 bundles the text projection into its text encoder, so
--embeddings-connectors is no longer required; the projection is looked
up under the --llm prefix as well.

Verified on the Q8_0 dev transformer for T2V, I2V, spatial latent
upscaling and a Q8_0-converted text encoder, and against Z-Image for the
shared attention and feed-forward changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant