Document self-contained loading and the guided modes

README.md

@@ -83,17 +83,23 @@ V100 — the encoder fits one consumer card for the first time.
 ### Standalone
 
 ```python
+from huggingface_hub import hf_hub_download, snapshot_download
 from ltx_packed_codec import load_packed_model
 from transformers import AutoTokenizer
 
-model = load_packed_model("path/to/encoder-hf", "A3.packed.safetensors",
-                          resident=True)
-tokenizer = AutoTokenizer.from_pretrained("path/to/encoder-hf")
+repo = "topabaem/LTX-2.5-TextEncoder-nvfp4-portable"
+packed = hf_hub_download(repo, "A3.packed.safetensors")
+encoder_dir = snapshot_download(repo, allow_patterns=["encoder-hf/*"]) + "/encoder-hf"
+
+model = load_packed_model(encoder_dir, packed, resident=True)
+tokenizer = AutoTokenizer.from_pretrained(encoder_dir)
 ```
 
-`encoder-hf` is a normal HF model directory for this encoder — config,
-tokenizer and the assets that ship inside the original safetensors. Extract it
-with `ltx_extract_encoder_assets.py` from the Lightricks file.
+`encoder-hf/` here is config and tokenizer only, 31 MB. **The 26 GB original is
+not needed**: `load_packed_model` builds the skeleton with
+`AutoModel.from_config` and feeds every parameter from the packed file, so
+nothing reads the Lightricks weights. The asset blobs that ship inside the
+original safetensors are already in the packed file as raw BF16.
 
 ### ComfyUI
 
@@ -113,6 +119,26 @@ CONDITIONING.
 > nodes themselves have not been loaded in a live ComfyUI, and that is a
 > different claim.
 
+## Image- and video-to-video
+
+Both work, and both needed a fix ComfyUI does not ship. `LTXVAddGuide` is the
+only producer of guided LTX latents and it cannot take an LTX-2.5 one: it calls
+`torch.cat` on what is a `NestedTensor` for this model. The `ValueError` in that
+function saying AV guides are unsupported never fires — `NestedTensor.shape`
+proxies to the video half, whose channel count is exactly the 128 it checks for
+— so the real failure is a `TypeError`, and the message is stale.
+
+Everything below the node already supports AV guides: the model routes
+`keyframe_idxs` to the video branch, the sampler pads a video-only denoise mask
+with ones for audio, and `model_base` splits the packed mask apart again. So
+`ltx_av_guide.py` unwraps the pair, runs the stock node on the video half and
+re-wraps; the guide arithmetic stays the vendor's.
+
+Measured on a 16 GB V100 at 512x320, 25 frames: t2v 98.8 s / 5.84 GiB, i2v
+62.7 s / 6.80 GiB, v2v 86.5 s / 5.84 GiB. An i2v first frame lands **relL2
+0.0766** from its guide image against **0.7061** for the same seed and prompt
+without the guide, so the guide is honoured rather than merely accepted.
+
 ## How it was built
 
 nvfp4 4.5 bpw (E2M1, group 16 with an fp8-e4m3 scale) on 320 projections;