Skip to content

Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.

release(v4.19.12): H3 character and style LoRAs look right again

mrbizarrof333f1ca042b
diff --git a/README.md b/README.md
index f8f0b97..175f461 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ AI video with sound, songs and images, made locally on your Mac.
[Website](https://phosphene.video) · [Docs](https://phosphene.video/docs/) · [Benchmarks](https://phosphene.video/benchmarks/) · [Changelog](https://phosphene.video/changelog/) · [@PhospheneAI](https://x.com/PhospheneAI)
-**Current release: v4.19.11.** See what's new in the [changelog](https://phosphene.video/changelog/).
+**Current release: v4.19.12.** See what's new in the [changelog](https://phosphene.video/changelog/).
Phosphene is a free, open-source app for Apple Silicon Macs, built on Apple's MLX by Mr Bizarro.
Renders run offline, and your prompts, pictures and videos stay on your Mac.
diff --git a/VERSION b/VERSION
index 0ca0cba..aca0bf9 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-4.19.11
+4.19.12
diff --git a/docs/H3_ENGINE.md b/docs/H3_ENGINE.md
index 5bc3be5..92370a0 100644
--- a/docs/H3_ENGINE.md
+++ b/docs/H3_ENGINE.md
@@ -357,33 +357,85 @@ says so under itself when one of them is picked.
sigma subset, decode; plus `h3.schedule` (the sigmas the runner ran) and
`h3.lora_accounting`. The ⓘ modal prints a Speed row.
-### Speed adapters run a per-head copy (2026-10-22)
+### Every H3 LoRA runs in the base's qkv row order (2026-10-22)
H3's DiT stores the fused `attn.qkv_proj` rows **per head**, `(heads, 3,
-head_dim)`. Every speed adapter Phosphene resolves — Kijai's TaoMate r19, the
-official TaoMate r128, larryvrh's v4-600 EMA, the LightX2V v1.x repack — has
-its `lora_B` rows **contiguous**, `(3, heads, head_dim)`: the layout of the
-ComfyUI/diffusers definition it was trained or converted through. (One-way
-ANOVA on row norms, q/k/v as groups: base blocks.49 per-head F 5006 vs
-contiguous 43; the adapters' B·A deltas at blocks.49 read the other way,
-TaoMate 11 vs 1897, v4 0 vs 1038.) The runner only re-orders rows under
-`--lora-qkv-permute`, which has been OFF by default since 2026-08-15 and is
-global to a run, so it would also re-order a stacked user LoRA that lora-lab
-trained in the native layout.
-
-So the panel re-orders the speed adapter itself: `h3_bake_runner_layout()`
-writes `turbo-lora/runner-layout/<same name>` with each qkv `lora_B`'s 168
-blocks of 128 rows moved into per-head order. It is a byte move of whole rows
-(dtype-agnostic, no arithmetic), byte-identical to the runner's
-`_permute_qkv_rows` on all 52 modules of the real TaoMate file, stamped in the
-file's metadata with the source's size and mtime and re-made when either
-changes, and written through a `.partial` + rename. It runs right after a Fast
-or Turbo download and, for installs that already have the file, on the first
-render (0.25 s for the 182 MB TaoMate file on an M4 Max). The downloaded, digest-pinned file is never touched.
-A runner without `--lora-qkv-permute` predates 2026-08-15 and re-orders every
-`--lora` itself, so it is handed the source file. User LoRAs never go through
-this. Provenance: `h3.tristep` / `h3.turbo` carry `lora` (the file the runner
-read), `source` and `qkv_rows` (`per-head` or `runner`).
+head_dim)`. The ComfyUI/diffusers definition the community trains against
+splits them **contiguously**, `(3, heads, head_dim)`, and every H3 LoRA
+measured is in that order: the speed adapters (Kijai's TaoMate r19, the
+official TaoMate r128, larryvrh's v4-600 EMA, the LightX2V v1.x repack) and
+every user LoRA in the library (ostris ai-toolkit, the fal
+`minimax-h3-trainer`, a kohya-style trainer). The runner only re-orders rows
+under `--lora-qkv-permute`, which has been OFF by default since 2026-08-15
+and is global to a run. So since then every H3 LoRA has added its q update
+to the wrong heads' rows.
+
+**The test.** One-way ANOVA on per-row norms with q/k/v as the groups, read
+both ways. The base (bf16 pruned DiT and the Q8 pack alike) reads per head:
+blocks.0 F 1362 vs 83, blocks.49 5006 vs 43, token_refiner.0 1549 vs 10.
+`h3_lora_qkv_layout()` runs the same test on each of a LoRA's qkv modules —
+row norms of B·A via the rank×rank Gram matrix, so the full delta is never
+built — and each trained module votes for the larger F. 70 % agreement
+calls the file (measured files sit at 87-98 %); below that it is
+"unclear". A file whose metadata declares per-head rows (our own
+runner-layout copies, `fetch_h3_v13.py` builds, Viggle's "interleaved"
+exports) skips the vote. 0.03-0.9 s per file, cached per size + mtime.
+
+**Contiguous is the default (2026-10-23, 4.19.12 blocker).** MiniMax's own
+release is diffusers-shaped (separate `to_q` / `to_k` / `to_v`), and every
+tool that fuses them into one `attn.qkv_proj` stacks them `[q; k; v]`. So
+only a declared or measured per-head file runs as it is; "unclear" (or a
+dtype the vote cannot read) is re-ordered like every other fused file, with
+a log line. Before this, "unclear" ran as trained — wrong for every trainer
+we know of.
+
+**fc1 is not in this class.** The runner reads `mlp.fc1` as `[gate; value]`
+and so does every fused-name lineage: Kijai's comfy repack of LightX2V v1.0
+swaps diffusers' `[value; gate]` into it (his metadata says so, and our own
+diffusers repack agrees with his file as-is at +0.962), and his TaoMate r19
+keeps the official TaoMate r128's half order (per-block half-norm ratios
+identical: 0.014 / 0.014 / 0.206 at blocks 5 / 25 / 45). Diffusers-format
+files are refused at import, so `--lora-fc1-swap` stays off.
+
+**The fix.** `h3_lora_for_runner()` hands the runner, for a contiguous file,
+`<dir>/runner-layout/<same name>`: each qkv `lora_B`'s 168 blocks of 128 rows
+moved into per-head order by `h3_bake_runner_layout()` (whole-row byte moves,
+dtype-agnostic, no arithmetic; byte-identical to the runner's
+`_permute_qkv_rows` on the real TaoMate and bizarrotrn_h3 files). A per-head
+file runs as it is; an MLP-only LoRA has nothing to re-order. The copy is
+stamped with the source's size + mtime and re-made when either changes,
+written through `.partial` + rename, and pruned once its source leaves the
+library; the picker lists only the library's top level, so it never shows.
+The source file is never touched, so a recipe keeps naming it. Fast and
+Turbo get their copy right after download; everything else on first use. A
+runner without `--lora-qkv-permute` predates 2026-08-15 and re-orders every
+`--lora` itself, so it is handed the source.
+
+**Evidence.** Fast @ High 1024×576 5 s, seed 52031: the re-ordered TaoMate
+copy renders byte-identical to `--lora-qkv-permute`, and against the shipped
+order the mouth is 56 % sharper (Laplacian variance 26.4 → 41.1) with no
+added flicker. A character LoRA moves further: bizarrotrn_h3 at 1.0 on Fast
+@ High, seed 52032, ArcFace identity against its 42 training stills 0.399 →
+0.640, mouth region 24 % sharper, face 30 % steadier frame to frame — as
+shipped, the trigger's description (a waxed handlebar) won over the face the
+LoRA learned.
+
+**The 4.19.12 blocker (2026-10-23).** 4.19.11 shipped only the speed-adapter
+half (e1568d7): user LoRAs still went to the runner as trained, on every
+speed including Best at High with lightx2v v1.3 (its own file is per-head;
+a user LoRA stacked after it was not). Regression gates in
+`test_h3_tristep_draft.py`: the delta the runner applies, B'·A, equals the
+trained B·A with its rows moved (3, heads, head_dim) → (heads, 3,
+head_dim), derived from row indices, not from either implementation; and on
+the maintainer's Mac the bizarrotrn_h3 copy's tensor bytes match the copy
+that rendered the corrected clips (sha256 758e0096…). The fused block weight
+W + B'·A matches the pinned runner's own `--lora-qkv-permute` bit for bit
+(blocks 0 / 25 / 49); as 4.19.11 passed it, |Δ − Δref| / |Δref| ≈ 1.41,
+i.e. an orthogonal, unrelated update.
+
+**Provenance.** `h3.tristep` / `h3.turbo` carry `lora` (the file the runner
+read), `source` and `qkv_rows`; `params.h3_lora_qkv` lists each user LoRA
+with its `qkv_rows` (`re-ordered`, `as-trained`, `none`, `runner`).
### Best on High: lightx2v v1.3 (2026-10-22)
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index 7d22228..a59f198 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -3821,7 +3821,7 @@ def _h3_turbo_download_bg(target_dir, push_log, asset: dict | None = None) -> No
try:
# Same as Fast's: the runner's per-head copy, retried by the
# first Turbo render if this fails.
- h3_bake_runner_layout(target, push_log)
+ h3_lora_for_runner(target, push_log)
except Exception as e: # noqa: BLE001
push_log(f"[h3:turbo] qkv re-order deferred to the first render: {e}")
_h3_turbo_fetch_embedder(target_dir, push_log, force=True)
@@ -14205,29 +14205,64 @@ def h3_turbo_argv(paths: dict | None = None) -> list[str]:
return argv
-# ---- Speed adapters: fused qkv rows in THIS checkpoint's order -------------
-# H3's DiT stores `attn.qkv_proj` rows PER HEAD, (heads, 3, head_dim): a
-# one-way ANOVA on the Q8 DiT's row norms separates the q/k/v groups at
-# F 1362 (blocks.0) / 5006 (blocks.49) read that way, against 83 / 43 read
-# contiguously. Every speed adapter we resolve was trained or converted
-# through the ComfyUI/diffusers definition, whose rows are CONTIGUOUS,
-# (3, heads, head_dim): the same test on their B·A deltas reads contiguous at
-# blocks.49 for Kijai's TaoMate r19 (1897 vs 11), the official TaoMate r128
-# (1931 vs 10), larryvrh's v4-600 EMA (1038 vs 0) and LightX2V's v1.x
-# conversions (fetch_h3_turbo.py says so in its own docstring). The runner
-# re-orders those rows only under `--lora-qkv-permute`, OFF by default since
-# 2026-08-15 — so Fast and Turbo were writing the q update onto the first
-# 18.7 heads' q/k/v triplets, k onto the next, v onto the rest. That flag is
-# global to the run and would also hit a user LoRA stacked on top (one
-# lora-lab trains natively is already per-head), so the panel re-orders the
-# speed adapter's rows ITSELF, once, into a sibling file the runner reads
-# verbatim: `<adapter dir>/runner-layout/<same name>`. Pure byte moves of
-# whole rows — dtype-agnostic, no float maths, no new dependency — and the
-# source file (digest-pinned) is never touched.
+# ---- Every H3 LoRA: fused qkv rows in THIS checkpoint's order ---------------
+# H3's DiT stores `attn.qkv_proj` rows PER HEAD, (heads, 3, head_dim). A
+# one-way ANOVA on the base's per-row norms, q/k/v as the groups, separates
+# them at F 1362 (blocks.0) / 5006 (blocks.49) / 1549 (token_refiner.0) read
+# that way, against 83 / 43 / 10 read contiguously — identical on the bf16
+# pruned DiT and the Q8 pack built from it (H3_BASE_QKV_LAYOUT).
+#
+# The ComfyUI/diffusers definition everyone trains against splits them
+# CONTIGUOUSLY, (3, heads, head_dim), and every H3 LoRA measured on
+# 2026-10-22 is in that order: the speed adapters (Kijai's TaoMate r19, the
+# official TaoMate r128, larryvrh's v4-600 EMA, LightX2V's v1.x repacks) and
+# all ten user LoRAs in the library — ostris ai-toolkit 0.12.x, the fal
+# minimax-h3-trainer (bizarrotrn_h3, vh5tape), a kohya-style trainer, and
+# one with no metadata; 45-51 of 52 qkv modules each read contiguous. The
+# runner re-orders rows only under `--lora-qkv-permute`, OFF by default since
+# 2026-08-15 and global to a run, so since then every H3 LoRA has written its
+# q update onto the first 18.7 heads' q/k/v triplets, k onto the next, v onto
+# the rest. Nothing errors: the delta is ~1 % of the weight.
+#
+# So the order is decided PER FILE (h3_lora_qkv_layout: the same ANOVA on
+# each qkv module's B·A row norms, a module voting for the grouping with the
+# larger F) and a file whose order differs from the base's is handed to the
+# runner as a re-ordered sibling, `<dir>/runner-layout/<same name>` — byte
+# moves of whole rows, dtype-agnostic, no arithmetic. The source is never
+# touched, so a recipe still names it, and a per-head file (none exists yet)
+# runs as it is.
+#
+# Contiguous is the DEFAULT, not just the majority (2026-10-23): MiniMax's
+# own release is diffusers-shaped (separate to_q / to_k / to_v), and every
+# tool that fuses those into one `attn.qkv_proj` stacks them [q; k; v]. Only
+# a file that says it is per-head (our own runner-layout copies and fetch
+# builds stamp it; Viggle-lineage files say "interleaved") or that measures
+# per-head runs as it is. A file the vote cannot call ("unclear", or a dtype
+# it cannot read) is re-ordered like every other fused file, and the log
+# says so — applied as-is it would be wrong for every trainer we know of.
+#
+# fc1 is NOT in this class. The runner reads `mlp.fc1` as [gate; value], and
+# so does every fused-name lineage: Kijai's comfy repack of LightX2V v1.0
+# swaps diffusers' [value; gate] into it (his metadata says so; our own
+# repack agrees with his file as-is, +0.962), and his TaoMate r19 keeps the
+# official TaoMate r128's half order (per-block half-norm ratios identical).
+# Diffusers-format files are refused at import, so no fused file reaches the
+# runner in [value; gate]; `--lora-fc1-swap` stays off.
H3_RUNNER_LAYOUT_DIRNAME = "runner-layout"
H3_QKV_HEADS = 56
H3_QKV_HEAD_DIM = 128
+H3_QKV_LORA_A_SUFFIX = ".attn.qkv_proj.lora_A.weight"
H3_QKV_LORA_B_SUFFIX = ".attn.qkv_proj.lora_B.weight"
+H3_BASE_QKV_LAYOUT = "per-head"
+# Share of a file's trained qkv modules that must agree before its order is
+# called. Measured files sit at 0.87-0.98 for their order; below this the
+# file is "unclear" and re-ordered like any fused file (the default above).
+H3_QKV_LAYOUT_VOTE = 0.7
+# Metadata a per-head file declares itself with (checked before the vote):
+# our runner-layout copies, scripts/fetch_h3_v13.py builds, Viggle exports.
+_H3_QKV_DECLARED_PER_HEAD = (("phosphene_qkv_rows", "per-head"),
+ ("qkv_layout", "per-head"),
+ ("qkv_layout", "interleaved"))
H3_RUNNER_LAYOUT_KEY = "phosphene_qkv_rows"
H3_RUNNER_LAYOUT_VALUE = "per-head (heads, 3, head_dim), re-ordered from (3, heads, head_dim)"
@@ -14249,6 +14284,100 @@ def h3_runner_layout_file(src: Path | str) -> Path:
return src.parent / H3_RUNNER_LAYOUT_DIRNAME / src.name
+def _st_tensor_f32(fh, hlen: int, info: dict):
+ """One safetensors tensor as a float32 numpy array (BF16 widened exactly)."""
+ import numpy as np
+ start, end = info["data_offsets"]
+ fh.seek(8 + hlen + start)
+ raw = fh.read(end - start)
+ dtype = info["dtype"]
+ if dtype == "BF16":
+ arr = (np.frombuffer(raw, "<u2").astype(np.uint32) << 16).view(np.float32)
+ elif dtype in ("F16", "F32", "F64"):
+ arr = np.frombuffer(raw, {"F16": "<f2", "F32": "<f4", "F64": "<f8"}[dtype]).astype(np.float32)
+ else:
+ raise ValueError(f"unsupported dtype {dtype}")
+ return arr.reshape(info["shape"])
+
+
+def _anova3_f(values, labels) -> float:
+ """One-way ANOVA F of `values` over three groups (labels 0/1/2)."""
+ import numpy as np
+ groups = [values[labels == g] for g in range(3)]
+ grand = values.mean()
+ between = sum(len(g) * (g.mean() - grand) ** 2 for g in groups) / 2
+ within = sum(((g - g.mean()) ** 2).sum() for g in groups) / (len(values) - 3)
+ return float(between / within) if within > 0 else float("inf")
+
+
+_H3_QKV_LAYOUT_CACHE: dict[tuple, dict] = {}
+
+
+def h3_lora_qkv_layout(path: Path | str) -> dict:
+ """Which order a LoRA's fused qkv rows are in: declared per-head, else measured.
+
+ For every `attn.qkv_proj` pair: the row norms of B·A (from B and the
+ rank×rank Gram matrix A·Aᵀ, so the 21504×5376 delta is never built), then
+ the ANOVA F with q/k/v grouped per head and grouped contiguously; the
+ module votes for the larger. Untrained (all-zero) modules abstain.
+ Returns {"layout": "contiguous" | "per-head" | "unclear" | "none",
+ "modules", "contiguous", "per_head", "declared"}. A file whose metadata
+ declares per-head rows (`_H3_QKV_DECLARED_PER_HEAD`) is per-head without
+ a vote. Cached per (path, size, mtime)."""
+ import numpy as np
+ path = Path(path)
+ st = path.stat()
+ key = (str(path), st.st_size, st.st_mtime_ns)
+ if key in _H3_QKV_LAYOUT_CACHE:
+ return _H3_QKV_LAYOUT_CACHE[key]
+ hlen, header = _st_header(path)
+ meta = header.get("__metadata__") or {}
+ declared = next((f"{k}={meta[k]}" for k, v in _H3_QKV_DECLARED_PER_HEAD
+ if str(meta.get(k) or "").strip().lower().startswith(v)), "")
+ if declared:
+ out = {"layout": "per-head", "modules": 0, "contiguous": 0, "per_head": 0,
+ "declared": declared}
+ _H3_QKV_LAYOUT_CACHE[key] = out
+ return out
+ rows = 3 * H3_QKV_HEADS * H3_QKV_HEAD_DIM
+ idx = np.arange(rows)
+ per_head_labels = (idx // H3_QKV_HEAD_DIM) % 3
+ contiguous_labels = idx // (H3_QKV_HEADS * H3_QKV_HEAD_DIM)
+ votes = {"contiguous": 0, "per_head": 0}
+ with open(path, "rb") as fh:
+ for name in sorted(k for k in header if k.endswith(H3_QKV_LORA_B_SUFFIX)):
+ a_info = header.get(name[: -len(H3_QKV_LORA_B_SUFFIX)] + H3_QKV_LORA_A_SUFFIX)
+ b_info = header[name]
+ if a_info is None or int(b_info["shape"][0]) != rows:
+ continue
+ b = _st_tensor_f32(fh, hlen, b_info).astype(np.float64)
+ a = _st_tensor_f32(fh, hlen, a_info).astype(np.float64)
+ norms = np.sqrt(np.clip(((b @ (a @ a.T)) * b).sum(axis=1), 0, None))
+ if not norms.any():
+ continue
+ # A tie (both F infinite or equal: a module whose rows cannot tell
+ # the two orders apart) votes for the contiguous default, never
+ # for "leave the rows alone" (4.19.12 review).
+ if _anova3_f(norms, per_head_labels) > _anova3_f(norms, contiguous_labels):
+ votes["per_head"] += 1
+ else:
+ votes["contiguous"] += 1
+ modules = votes["contiguous"] + votes["per_head"]
+ if not modules:
+ layout = "none"
+ elif votes["contiguous"] >= H3_QKV_LAYOUT_VOTE * modules:
+ layout = "contiguous"
+ elif votes["per_head"] >= H3_QKV_LAYOUT_VOTE * modules:
+ layout = "per-head"
+ else:
+ layout = "unclear"
+ out = {"layout": layout, "modules": modules, **votes, "declared": ""}
+ if len(_H3_QKV_LAYOUT_CACHE) > 64:
+ _H3_QKV_LAYOUT_CACHE.clear()
+ _H3_QKV_LAYOUT_CACHE[key] = out
+ return out
+
+
def _h3_runner_layout_current(src: Path, dst: Path) -> bool:
"""The re-ordered copy exists and was made from THIS source file."""
try:
@@ -14277,8 +14406,19 @@ _h3_bake_locks: dict[str, threading.Lock] = {}
_h3_bake_locks_guard = threading.Lock()
+def _h3_prune_runner_layout(directory: Path) -> None:
+ """Drop re-ordered copies whose source left the library (H3 LoRAs are
+ removed by hand; nothing else would ever reclaim the copy)."""
+ try:
+ for copy in directory.glob("*.safetensors"):
+ if not (directory.parent / copy.name).exists():
+ copy.unlink(missing_ok=True)
+ except OSError:
+ pass
+
+
def h3_bake_runner_layout(src: Path | str, push=None) -> Path:
- """Write (once) and return the per-head copy of a speed adapter.
+ """Write (once) and return the per-head copy of a contiguous-order LoRA.
Re-made whenever the source's size or mtime changes; written to a
`.partial` and renamed, so a killed bake never leaves a file the runner
@@ -14348,24 +14488,59 @@ def _h3_bake_runner_layout_locked(src: Path, dst: Path, push=None) -> Path:
except BaseException:
tmp.unlink(missing_ok=True)
raise
+ _h3_prune_runner_layout(dst.parent)
if push:
push(f"[h3] {src.name}: {moved} qkv row-blocks re-ordered to the "
f"checkpoint's per-head layout → {dst}")
return dst
+def h3_lora_for_runner(src: Path | str, push=None) -> tuple[Path, str]:
+ """(the file the runner should read, what was done to its qkv rows).
+
+ "re-ordered" a fused file in the contiguous order every trainer writes
+ (measured, or unclear — see the note above) → its
+ per-head copy
+ "as-trained" already in the base's per-head order (declared or measured)
+ "none" no trained qkv module (an MLP-only LoRA)
+ "runner" a runner without `--lora-qkv-permute` predates 2026-08-15
+ and re-orders every `--lora` itself — handing it a
+ re-ordered copy would put the rows back in the wrong order
+ """
+ src = Path(src)
+ if not _h3_runner_has_flag("--lora-qkv-permute"):
+ return src, "runner"
+ try:
+ info = h3_lora_qkv_layout(src)
+ except (ValueError, KeyError) as e:
+ # Values the vote cannot read (an unusual dtype): the rows can still
+ # be moved, and contiguous is what every fused file is.
+ info = {"layout": "unclear", "modules": 0, "contiguous": 0,
+ "per_head": 0, "declared": "", "error": str(e)}
+ if info["layout"] == "none":
+ return src, "none"
+ if info["layout"] == H3_BASE_QKV_LAYOUT:
+ return src, "as-trained"
+ votes = (f"{info['contiguous']} of {info['modules']} qkv modules read contiguous"
+ if info["modules"] else f"order not measured: {info.get('error')}")
+ dst = h3_bake_runner_layout(src, push)
+ if push:
+ if info["layout"] == "unclear":
+ push(f"[h3] {src.name}: qkv row order unclear ({votes}) — re-ordered "
+ f"to the base's per-head order, the order every H3 trainer writes")
+ else:
+ push(f"[h3] {src.name}: qkv rows re-ordered to the base's per-head order ({votes})")
+ return dst, "re-ordered"
+
+
def h3_speed_adapter_for_runner(resolved: dict, push=None) -> dict:
"""The resolved Fast/Turbo paths with `lora` pointing at the file the
- runner should read; the downloaded file moves to `lora_source`.
-
- A runner without `--lora-qkv-permute` predates 2026-08-15 and re-orders
- the rows of every `--lora` itself, so it gets the source file as-is —
- re-ordering twice would put the rows back in the wrong order."""
+ runner should read; the downloaded file moves to `lora_source`."""
src = resolved.get("lora")
- if src is None or not _h3_runner_has_flag("--lora-qkv-permute"):
- return {**resolved, "lora_source": src, "qkv_rows": "runner"}
- return {**resolved, "lora": h3_bake_runner_layout(src, push),
- "lora_source": src, "qkv_rows": "per-head"}
+ if src is None:
+ return {**resolved, "lora_source": None, "qkv_rows": None}
+ runner_file, qkv_rows = h3_lora_for_runner(src, push)
+ return {**resolved, "lora": runner_file, "lora_source": src, "qkv_rows": qkv_rows}
def h3_turbo_status() -> dict:
@@ -14603,7 +14778,7 @@ def _h3_tristep_download_bg(target_dir, push_log, asset: dict | None = None,
try:
# The runner's per-head copy now, so the first Fast render does
# not pay for it; a failure here is retried by that render.
- h3_bake_runner_layout(target, push_log)
+ h3_lora_for_runner(target, push_log)
except Exception as e: # noqa: BLE001
push_log(f"[h3:tristep] qkv re-order deferred to the first render: {e}")
_set_h3_tristep_dl(status="done", mb=total_mb, total_mb=total_mb,
@@ -36494,8 +36669,8 @@ def run_h3_job_inner(job: dict) -> None:
f"Speed, or click Fast to install it (180 MB).")
steps = H3_TRISTEP_STEPS
# Both speed adapters store their qkv rows in the ComfyUI order; the runner
- # gets the per-head copy (h3_speed_adapter_for_runner). User LoRAs never
- # pass through here.
+ # gets the per-head copy (h3_speed_adapter_for_runner). User LoRAs take
+ # the same per-file decision where their --lora is built, below.
if turbo:
turbo_paths = h3_speed_adapter_for_runner(turbo_paths, push)
if tristep:
@@ -36850,8 +37025,10 @@ def run_h3_job_inner(job: dict) -> None:
cmd += h3_tristep_argv(tristep_paths)
if v13:
# Shift 6 + the adapter at 1.0 (alpha folded, qkv rows already in the
- # DiT's order: no --lora-qkv-permute, so a user LoRA after it is
- # applied exactly as trained).
+ # DiT's order: no --lora-qkv-permute). A user LoRA after it still
+ # needs its own re-order (h3_lora_for_runner, below): before
+ # 4.19.12 it was passed as trained and its q/k/v update landed on
+ # the wrong heads.
cmd += h3_v13_argv(v13_paths, shift=v13_shift)
if user_lora is not None and (not turbo or h3_supports_lora_stack()):
# The SAME flag Turbo rides. On a stacking runner every `--lora` is one
@@ -36862,8 +37039,13 @@ def run_h3_job_inner(job: dict) -> None:
# checkpoint that ships alpha == rank, which is the only namespace this
# lane accepts (the diffusers/PEFT one, whose alpha is NOT in the file,
# is refused upstream in _h3_lora_prepare).
+ # The runner reads each file in the base's qkv row order
+ # (h3_lora_for_runner); the recipe keeps naming the library file.
+ p["h3_lora_qkv"] = []
for _pp, _ps in (user_lora_stack if h3_supports_lora_stack() else [(user_lora, user_lora_strength)]):
- cmd += ["--lora", f"{_pp}:{_ps:g}"]
+ _run_pp, _qkv = h3_lora_for_runner(_pp, push)
+ p["h3_lora_qkv"].append({"path": str(_pp), "qkv_rows": _qkv})
+ cmd += ["--lora", f"{_run_pp}:{_ps:g}"]
env = os.environ.copy()
# The runner pipes raw RGB into `ffmpeg` from PATH (minimax_h3_mlx.media);
diff --git a/scripts/assert_registry.py b/scripts/assert_registry.py
index 067a95f..6bad749 100644
--- a/scripts/assert_registry.py
+++ b/scripts/assert_registry.py
@@ -162,6 +162,34 @@ def not_installed(quant, version_id):
return ""
+def code_only():
+ """A reason string when this tree holds NO model file at all, else "".
+
+ A git worktree or a fresh clone is code only: start.js points the panel at
+ `{{cwd}}/mlx_models`, and nothing has ever downloaded into it (it may not
+ exist, or hold only empty folders other gates create, such as `loras/`).
+ The "this install" checks below (the default pack is complete, the text
+ encoder is there, the default pack carries its manifest) cannot be
+ answered on such a tree, and failing them made the gate red on every
+ release worktree that did not link a model folder in (4.19.10-4.19.12).
+ They SKIP here, named. Any file at all under the folder means a download
+ happened, so a missing or partial default pack is still a FAIL; so is a
+ dangling symlink (a moved install, an unplugged model drive)."""
+ d = p.MODELS_DIR
+ if d.is_symlink() and not d.exists():
+ return ""
+ if not d.exists():
+ return f"code-only tree: no model folder at {d}"
+ if d.is_symlink():
+ return ""
+ try:
+ if any(f.is_file() and f.name != ".DS_Store" for f in d.rglob("*")):
+ return ""
+ except OSError:
+ return ""
+ return f"code-only tree: no model file under {d}"
+
+
def known_defect(tag, label, got, current, should_be):
"""Pin a WRONG behaviour so the gate stays green and the bug stays visible.
@@ -329,11 +357,14 @@ eq("q8_available_anywhere delegates", p.q8_available_anywhere(), p.pack_availabl
eq("an unregistered quant invents no missing files", p.pack_missing_files("q9"), [])
for vid in ("ltx23", "ltx25"):
for q in ("q4", "q8"):
- if not_installed(q, vid):
- skip(f"this install is complete ({vid}/{q})", not_installed(q, vid))
+ if not_installed(q, vid) or code_only():
+ skip(f"this install is complete ({vid}/{q})", not_installed(q, vid) or code_only())
continue
eq(f"this install is complete ({vid}/{q})", p.pack_missing_files(q, vid), [])
- eq(f"this install has {vid}'s text encoder", p.text_encoder_missing_files(vid), [])
+ if code_only():
+ skip(f"this install has {vid}'s text encoder", code_only())
+ else:
+ eq(f"this install has {vid}'s text encoder", p.text_encoder_missing_files(vid), [])
if not_installed("q8", "ltx25"):
skip("the HQ surface is complete on this box", not_installed("q8", "ltx25"))
else:
@@ -405,8 +436,8 @@ p._canonical_layout = lambda: True
try:
for vid in ("ltx23", "ltx25"):
for q in ("q4", "q8"):
- if not_installed(q, vid):
- skip(f"a complete pack passes ({vid}/{q})", not_installed(q, vid))
+ if not_installed(q, vid) or code_only():
+ skip(f"a complete pack passes ({vid}/{q})", not_installed(q, vid) or code_only())
continue
no_raise(f"a complete pack passes ({vid}/{q})",
lambda vid=vid, q=q: p.ltx_pack_preflight(q, "X", vid))
@@ -442,9 +473,16 @@ try:
):
raises(f"the refusal {what}",
lambda: p.ltx_pack_preflight("q8", "Extend", "ltx23"), needle)
- # ...and the OTHER generation is untouched by it.
- no_raise("2.5 is unaffected by a broken 2.3 pack",
- lambda: p.ltx_pack_preflight("q8", "Extend", "ltx25"))
+ # ...and the OTHER generation is untouched by it. Only answerable
+ # where the 2.5 q8 pack is installed: it is opt-in (Settings ->
+ # Models), and with pack_available_anywhere forced off above, an
+ # install without it would fail here for a reason unrelated to 2.3.
+ if not_installed("q8", "ltx25") or code_only():
+ skip("2.5 is unaffected by a broken 2.3 pack",
+ not_installed("q8", "ltx25") or code_only())
+ else:
+ no_raise("2.5 is unaffected by a broken 2.3 pack",
+ lambda: p.ltx_pack_preflight("q8", "Extend", "ltx25"))
finally:
pack["path"] = saved
p.pack_available_anywhere = _saved_anywhere
@@ -524,8 +562,11 @@ finally:
p.ACTIVE_MODEL_VERSION = _saved_active
eq("an unknown repo defaults to hf-api", p._pack_verify_source("ic_colorize"), "hf-api")
eq("None defaults to hf-api", p._pack_verify_source(None), "hf-api")
-eq("the 2.5 q4 pack really does carry a manifest",
- (p.pack_path("q4", "ltx25") / p.PACK_MANIFEST_NAME).exists(), True)
+if code_only():
+ skip("the 2.5 q4 pack really does carry a manifest", code_only())
+else:
+ eq("the 2.5 q4 pack really does carry a manifest",
+ (p.pack_path("q4", "ltx25") / p.PACK_MANIFEST_NAME).exists(), True)
eq("the 2.3 q4 pack really does not",
(p.pack_path("q4", "ltx23") / p.PACK_MANIFEST_NAME).exists(), False)
diff --git a/webapp/docs/loras.md b/webapp/docs/loras.md
index b927f80..6730cfa 100644
--- a/webapp/docs/loras.md
+++ b/webapp/docs/loras.md
@@ -30,6 +30,7 @@ CivitAI needs an API key to download: paste it in the browser's banner or in Set
- **LTX** — copy `.safetensors` files into `mlx_models/loras/` and press the rescan button.
- **Hailuo H3** — **Import H3 LoRA** takes a `.safetensors` file (up to 4 GB) and reports how it was read and its recommended strength.
H3 LoRAs live in their own library, `mlx_models/hailuo-h3/loras/`; you can also drop files there by hand and press rescan, with the same checks. H3 accepts the runner layout with paired `lora_A` / `lora_B` tensors. ComfyUI repacks and Kohya files (`lora_down`, `lora_up` and `.alpha`) are converted on import, and a Kohya file keeps its alpha scaling, so strength 1.0 means "as trained".
+ H3 LoRAs from CivitAI, Hugging Face, fal, or your own imports store one internal set of weights in a different order than H3 expects; Phosphene checks each file and, when needed, runs a reordered copy kept in a `runner-layout` folder next to the library file, leaving your file untouched. This brings character LoRAs and Fast speed mode closer to how they were trained, most visibly with sharper mouths.
## Stacking LoRAs on Hailuo H3 {#h3-stacking}