---

license: other

license_name: ltx-2-community-license

license_link: https://huggingface.co/Lightricks/LTX-2/blob/main/LICENSE.txt

tags:

• comfyui
• ltx-video
• ltx-2.3
• vae
• diffusion-single-file

base_model: Lightricks/LTX-2.3

---

LTX-2.3 VAE + vocoder companion — for GGUF runs

**A 9 GB stand-in for the 43 GB checkpoint, for when your DiT comes from a

GGUF. Same VAEs, byte for byte. Cuts peak system RAM from ~60 GB to ~11 GB.**

If you run a GGUF DiT on a 64 GB machine and ComfyUI dies while loading with

Windows fatal exception: access violation, this is the fix.

The problem

When you put a GGUF in model_file, the JoyAI-Echo loader takes the transformer

from the GGUF — but checkpoint_path is still required, because it supplies the

VAEs, the vocoder and the text-embedding projection.

The catch: the loader **materialises that whole checkpoint in system RAM as owned

copies**, not memory-mapped. Against a 43 GB bf16 build that is roughly 60 GB at

peak. It has to be owned copies — a tensor left aliasing the safetensors mmap

dangles once the file closes, and the next load faults natively on Windows.

So on a 64 GB box you are ~4 GB from the wall before Windows, ComfyUI and the

Gemma encoder take their share. It usually falls over, and it looks like a VRAM

problem even though the GPU is sitting idle — the crash lands in

create_vae_wrappers, right after the DiT loaded perfectly.

What is actually needed

Of a 43 GB checkpoint, a GGUF run touches 9.02 GB - a GGUF carries only

the transformer BLOCKS, so everything else must come from checkpoint_path:

| kept | size | tensors |

|---|---|---|

| model.* (embedding connectors, adaLN singles, patchify/proj) | 4.89 GB | 316 |

| text_embedding_projection.* | 2.31 GB | 4 |

| vae.* | 1.45 GB | 170 |

| vocoder.* | 0.26 GB | 1227 |

| audio_vae.* | 0.11 GB | 102 |

| total | 9.02 GB | 1819 |

The other ~34 GB is the DiT's transformer blocks - which the GGUF is already

providing. You are paying 34 GB of RAM for tensors that get overwritten.

Using it

1. Put this file wherever your checkpoints live.
2. In JoyEcho_ModelLoader: your GGUF in model_file, this file in

checkpoint_path.

1. Nothing else changes.

model_file       LTX23-echoVid-ltxAud-Surgical-e50-DiT-Q5_0.gguf
checkpoint_path  ltx23_e50_GGUF-COMPANION.safetensors

Peak system RAM drops to about 11 GB, and load time drops with it.

What it is not

• Not a model. There is no DiT in here. On its own it generates nothing —

it is the other half of a GGUF.

• Not quantised. The VAE, vocoder and projection tensors are copied verbatim

from the bf16 source, bit for bit. Output is identical.

• Not a substitute for the full checkpoint if you are running a

.safetensors DiT. In that case you need the whole file.

Which one do I need?

The VAEs are shared across the LTX-2.3 family, so in practice this companion

loads with any LTX-2.3 GGUF. But matching the family it was cut from matters

more than it used to: the embedding connectors and adaLN gate tensors ride in

this file, and those DIFFER between merge variants (they were merge axes in

the echoVid family). This file is cut from the e50 merge - it is the exact

match for the e50 GGUFs; with other variants it works but supplies e50's

gates. For an exact pairing with a different checkpoint, cut your own with the

included script (one command). text_embedding_projection remains the piece

that keeps voice and identity conditioning wired up. A GGUF missing those

four tensors is the classic cause of robotic voice, the model reading your

prompt aloud, and a different face every shot.

Build your own

build_vae_companion.py cuts one from any full LTX-2.3 checkpoint:

python build_vae_companion.py path/to/full_checkpoint.safetensors

It keeps __metadata__ deliberately — the GGUF path calls

_full_config(checkpoint_path) to configure the transformer, so a companion

stripped of metadata would silently fall back to a stock config. The script

refuses to write a file that would.

Verification

Built from ltx23_echoVid-ltxAud_surgical_e50_bf16.safetensors:

• 1819 tensors, all five groups present
• _full_config() returns identically to the 43 GB original —

num_layers=48, in_channels=128, positional_embedding_max_pos=[20, 2048, 2048]

• VAE tensor payloads byte-identical to the source (SHA-256 spot checks)

Related

• JoyAI-Echo multishot patch — the node pack this targets
• LTX-2.3 Multishot Lite — core-node workflow
• All models

License

LTX-2 Community License, inherited from the source checkpoint. Non-commercial

where the source is non-commercial.

Support

Everything here is free and stays free. If it saved you time, you can

sponsor me on GitHub,

buy me a coffee, or

support me on Liberapay.