Port complete on both consumers; add measured memory guidance and DFR/multishot notes

README.md

@@ -19,10 +19,15 @@ MLX-format conversion of [Lightricks LTX-2.5](https://huggingface.co/Lightricks/
 (joint audio+video DiT, 22B) for Apple Silicon, in the per-component split layout consumed by
 [`ltx-2-mlx`](https://github.com/xocialize/ltx-2-mlx) (branch `ltx-2.5`).
 
-> **Status: research port in progress.** The conversion layer is verified (see *Conversion
-> receipts*); the MLX pipeline generates end-to-end and its text-encoder path is parity-gated
-> against the PyTorch reference. Remaining parity gates (DiT forward, e2e latents) are being
-> landed on the consuming repo's `ltx-2.5` branch.
+> **Status (2026-08-13): the port is COMPLETE on both consumers.** Python-MLX
+> ([`ltx-2-mlx`](https://github.com/xocialize/ltx-2-mlx), branch `ltx-2.5`) and Swift-MLX
+> ([`ltx-2-mlx-swift`](https://github.com/xocialize/ltx-2-mlx-swift)) both generate end to end,
+> including the DFR pipeline with temporal rounds. Parity-gated per component against the
+> PyTorch reference: text encoder 49 states (mean cosine 0.999985), DiT forward, sampler,
+> keyframe slots, and the DFR canvas geometry bit-exactly.
+>
+> Still a **research port** — it is not a supported product, and see *Memory* below before you
+> plan a run.
 
 ## ⚠️ License — read before use
 
@@ -83,6 +88,39 @@ numerically altered beyond layout/serialization transforms. Conversion tooling:
   identical; all 49 tapped hidden states ≥ 0.9997 cosine; pre-connector projections ≥ 0.99996.
 - The embedded LTX-2.x license text present in upstream file metadata is preserved.
 
+## Memory — read this before planning a run
+
+Measured on Apple Silicon (128 GB unified), 448×320×9 frames, bf16, via the Swift consumer.
+Your numbers will differ with resolution and frame count; the *structure* is what transfers.
+
+| | peak |
+|---|---|
+| default (text encoder co-resident with the DiT) | **62.40 GB** |
+| with the DiT evicted around the encode phase | **40.66 GB** |
+
+**The text encoder is the surprise.** `gemma4-12b-ltx-v1/` is an unquantized **bf16 12B —
+23.8 GB on disk, ~24.4 GB resident**. LTX-2.3 used a 4-bit Gemma-3 (~7 GB), so anything you
+carry over from a 2.3 setup will badly under-estimate 2.5. The DiT itself is a 37.98 GB
+resident floor at bf16.
+
+Two levers, and they stack:
+
+1. **Evict the DiT around the phases that don't need it.** −21.74 GB (−34.8%) with output
+   **bit-identical** and wall-clock within run-to-run noise. This is a scheduling change, not
+   a quality trade — it is on by default in the Swift consumer.
+2. **Quantize the text encoder to int8** (group 64, keeping `embed_tokens` in bf16): encoder
+   24.42 → 14.20 GB, end-to-end 62.40 → 52.18 GB. We measured this as **numerically faithful**
+   (valid-token cosine 0.999820 against a 0.999879 bf16 floor) and **perceptually neutral** in a
+   blinded 6-pair operator A/B (3 ties, 2–1, all "very close").
+   ⚠️ **int4 was REJECTED** — 0.996728 on the same metric, consistent with an independent
+   in-fleet measurement of a different frozen encoder. Note that several third-party MLX packs
+   ship this encoder at 4-bit with no published quality data.
+   **No quantized sibling is published here**; the recipe is in the consuming repo.
+
+⚠️ **If you quantize it yourself:** the default `mlx_lm.convert -q` also quantizes
+`embed_tokens`, which is hidden state 00 *and* the input to all 48 layers — exclude it. The
+`mixed_*` recipes are worse: with tied embeddings they put the embedding table at 3 bits.
+
 ## Usage
 
 ```bash
@@ -95,6 +133,30 @@ uv run ltx-2-mlx generate \
   -H 512 -W 768 -f 121 --frame-rate 24 -o fox.mp4
 ```
 
+**Multishot (LTX-2.5 generated keyframe slots)** — `--num-generated-keyframes N` places N
+invented keyframes at evenly spaced interior positions. Note what this does and does not do:
+it relaxes the effective temporal compression at those positions (each slot costs a full
+latent frame of tokens to buy one pixel frame). In our measurement it did **not**, on its own,
+turn a shot-listed prompt into multiple cut shots — that is the DFR pipeline's job.
+
+**DFR (diffusion fidelity rendering)** is implemented in both consumers. Its *spatial*
+detailing pass was preferred by an operator on 4 of 4 matched pairs for roughly ×1.2 time.
+Its *temporal rounds* are a parity/quality feature, **not** a speed one: they cost ×2.767
+(1 round) / ×3.542 (2 rounds), and generating the same deliverable natively at the target
+frame rate was both ~2.8× cheaper and preferred. Use rounds when you want the temporal
+density, not to save time.
+
+### Swift
+
+```swift
+// https://github.com/xocialize/ltx-2-mlx-swift — MLX-Swift consumer.
+// 2.5 is detected from the CHECKPOINT (the in-dir gemma4-12b-ltx-v1/), never a path name,
+// so a renamed or relocated copy still resolves correctly.
+let pipeline = try await LTX2Pipeline.load(ltxDir: modelDir, gemmaDir: gemma4Dir)
+let out = try await pipeline.t2vTwoStage(prompt: prompt, height: 320, width: 448,
+                                         numFrames: 25, fps: 24, seed: 4242)
+```
+
 ## Provenance
 
 Converted from [`Lightricks/LTX-2.5`](https://huggingface.co/Lightricks/LTX-2.5) (comfy split