Update README.md

README.md

@@ -15,51 +15,107 @@ tags:
 
 # LightVAE: Towards Compact and Efficient Video Autoencoders
 
-LightVAE accelerates pretrained video autoencoders through temporal low-rank compression and block pruning while preserving their latent interfaces. This repository provides checkpoints for Wan2.1, Wan2.2, and MiniMax-H3, including versions converted for ComfyUI.
+LightVAE accelerates pretrained video autoencoders through temporal low-rank compression and block pruning while preserving their latent interfaces.
+
+This repository provides checkpoints for **Wan2.1, Wan2.2, and MiniMax-H3**, including exports for our ComfyUI custom node.
 
 **Paper:** *LightVAE: Towards Compact and Efficient Video Autoencoders*  
 **Code and examples:** [ModelTC/LightVAE](https://github.com/ModelTC/LightVAE)
 
-## Checkpoints
+## 📦 Checkpoints
+
+| Backbone | Variant | Python checkpoint | ComfyUI checkpoint |
+| :-- | :-- | :-- | :-- |
+| Wan2.1 | Pro decoder | [Download](./lightvae-pro-wan21-decoder.safetensors) | [Download](./lightvae-pro-wan21-decoder-comfy.safetensors) |
+| Wan2.1 | Lite decoder | [Download](./lightvae-lite-wan21-decoder.safetensors) | [Download](./lightvae-lite-wan21-decoder-comfy.safetensors) |
+| Wan2.2 | Pro decoder | [Download](./lightvae-pro-wan22-decoder.safetensors) | [Download](./lightvae-pro-wan22-decoder-comfy.safetensors) |
+| Wan2.2 | Lite decoder | [Download](./lightvae-lite-wan22-decoder.safetensors) | [Download](./lightvae-lite-wan22-decoder-comfy.safetensors) |
+| MiniMax-H3 | Lite decoder | [Download](./lightvae-lite-h3-decoder.safetensors) | [Download](./lightvae-lite-h3-decoder-comfy.safetensors) |
+| MiniMax-H3 | Lite encoder | [Download](./lightvae-lite-h3-encoder.safetensors) | [Download](./lightvae-lite-h3-encoder-comfy.safetensors) |
+
+**Pro** retains the original decoder depth for higher reconstruction fidelity. **Lite** applies additional pruning for faster inference.
+
+Wan models retain their original encoders. MiniMax-H3 can use either its original encoder or the provided Lite encoder.
+
+> **Wan2.2 model selection:** Wan2.2 **14B** uses the **Wan2.1 VAE**; Wan2.2 **5B TI2V** uses the **Wan2.2 VAE**. Choose the decoder accordingly.
+
+## ⚡ Use with ComfyUI
+
+> **Important:** The `-comfy.safetensors` checkpoints require our **Load LightVAE (TLR)** custom node. Do **not** load them with ComfyUI's standard **Load VAE / VAELoader** node.
+
+### 1. Install the node and download weights
+
+Taking **MiniMax-H3** as an example, run these commands in the **same Python environment used by ComfyUI**:
+
+```bash
+cd /path/to/ComfyUI
+
+git clone https://github.com/ModelTC/LightVAE.git LightVAE
+python -m pip install ./LightVAE huggingface_hub
+python LightVAE/comfyui/install.py --comfy-root .
+
+hf download lightx2v/LightVAE \
+  lightvae-lite-h3-decoder-comfy.safetensors \
+  --local-dir models/vae/LightVAE
+```
+
+Restart ComfyUI, then add a **Load LightVAE (TLR)** node.
+
+### 2. H3 FL2V: replace the decoder
+
+In **Load LightVAE (TLR)**, select:
 
-| Backbone | Variant | Standard checkpoint | ComfyUI checkpoint |
-| --- | --- | --- | --- |
-| Wan2.1 | Pro decoder | [`lightvae-pro-wan21-decoder.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-pro-wan21-decoder.safetensors) | [`lightvae-pro-wan21-decoder-comfy.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-pro-wan21-decoder-comfy.safetensors) |
-| Wan2.1 | Lite decoder | [`lightvae-lite-wan21-decoder.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-lite-wan21-decoder.safetensors) | [`lightvae-lite-wan21-decoder-comfy.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-lite-wan21-decoder-comfy.safetensors) |
-| Wan2.2 | Pro decoder | [`lightvae-pro-wan22-decoder.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-pro-wan22-decoder.safetensors) | [`lightvae-pro-wan22-decoder-comfy.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-pro-wan22-decoder-comfy.safetensors) |
-| Wan2.2 | Lite decoder | [`lightvae-lite-wan22-decoder.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-lite-wan22-decoder.safetensors) | [`lightvae-lite-wan22-decoder-comfy.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-lite-wan22-decoder-comfy.safetensors) |
-| MiniMax-H3 | Lite decoder | [`lightvae-lite-h3-decoder.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-lite-h3-decoder.safetensors) | [`lightvae-lite-h3-decoder-comfy.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-lite-h3-decoder-comfy.safetensors) |
-| MiniMax-H3 | Lite encoder | [`lightvae-lite-h3-encoder.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-lite-h3-encoder.safetensors) | [`lightvae-lite-h3-encoder-comfy.safetensors`](https://huggingface.co/lightx2v/LightVAE/blob/main/lightvae-lite-h3-encoder-comfy.safetensors) |
+- `decoder`: `lightvae-lite-h3-decoder-comfy.safetensors`
+- `encoder`: `none`
+- Leave `precision`, `backend`, and `device` set to `auto`.
 
-**Pro** retains the original decoder depth for higher reconstruction fidelity. **Lite** applies additional pruning for faster decoding. For Wan2.1 and Wan2.2, pair a LightVAE decoder with the corresponding original VAE encoder. MiniMax-H3 can use its original encoder or the provided Lite encoder. Keep checkpoints matched to their backbone.
+Connect its **VAE output** to your existing **VAE Decode** node.
 
-## Use with ComfyUI
+Keep the original VAE connections for first/last-frame encoding unchanged. For this decoder-only connection, `base_vae` can remain disconnected.
 
-Choose a checkpoint with the `-comfy.safetensors` suffix for a compatible ComfyUI workflow. Download only the variant you need into your ComfyUI VAE model directory. For example, to download the Wan2.1 Lite decoder:
+The same decoder-only replacement also works for **REF2V**.
+
+### 3. H3 REF2V: optionally replace the encoder too
+
+To also accelerate reference-image/video encoding, download the Lite encoder:
 
 ```bash
 hf download lightx2v/LightVAE \
-  lightvae-lite-wan21-decoder-comfy.safetensors \
-  --local-dir ComfyUI/models/vae
+  lightvae-lite-h3-encoder-comfy.safetensors \
+  --local-dir models/vae/LightVAE
 ```
 
-For MiniMax-H3, download the Lite decoder and, if your workflow replaces the encoder too, the Lite encoder. Select the corresponding VAE components in a workflow that supports MiniMax-H3. The ComfyUI checkpoints are separate from the standard checkpoints used by the Python examples below.
+Restart ComfyUI and select both H3 Lite files in **Load LightVAE (TLR)**:
+
+- `decoder`: `lightvae-lite-h3-decoder-comfy.safetensors`
+- `encoder`: `lightvae-lite-h3-encoder-comfy.safetensors`
 
-## Quick start with the Python code
+Connect its **VAE output** to both the **reference-encoding node** and **VAE Decode**. No original video VAE is needed for these connections.
+
+**Keep the H3 audio VAE and its connections unchanged in all cases.**
+
+See the [ComfyUI guide and example workflows](https://github.com/ModelTC/LightVAE/tree/main/comfyui) for more details and Wan examples.
+
+## 🐍 Quick start with Python
+
+Use the standard checkpoints **without** the `-comfy` suffix:
 
 ```bash
 git clone https://github.com/ModelTC/LightVAE.git
 cd LightVAE
-pip install -r requirements.txt
+python -m pip install -r requirements.txt
+
 hf download lightx2v/LightVAE \
   lightvae-lite-wan21-decoder.safetensors \
   --local-dir weights/LightVAE
 ```
 
-For example, reconstruct a video with the Wan2.1 Lite decoder:
+For example, reconstruct a video with the Wan2.1 Lite decoder and original encoder:
 
 ```bash
-hf download Wan-AI/Wan2.1-T2V-1.3B Wan2.1_VAE.pth --local-dir weights/Wan2.1
+hf download Wan-AI/Wan2.1-T2V-1.3B \
+  Wan2.1_VAE.pth \
+  --local-dir weights/Wan2.1
 
 python infer.py \
   --model wan21 --variant lite \
@@ -70,3 +126,7 @@ python infer.py \
 ```
 
 See the [GitHub repository](https://github.com/ModelTC/LightVAE) for Wan2.2 and MiniMax-H3 examples, benchmarks, and visual comparisons.
+
+## ⭐ Support Us
+
+If you find LightVAE useful, please consider starring [LightVAE](https://github.com/ModelTC/LightVAE) and [LightX2V](https://github.com/ModelTC/LightX2V). Your support helps us keep improving efficient video generation!