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.
Python ai-filmmakingai-videoai-video-generatorapple-siliconhailuoimage-to-videolip-synclocal-ailora-trainingltx-2ltx-2-5ltx-videomacosminimax-h3mlxmusic-generationoffline-aipinokiotext-to-videovideo-generation
release(v4.19.12): H3 character and style LoRAs look right again
mrbizarrof333f1ca042b
diff --git a/README.md b/README.mdindex 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/VERSIONindex 0ca0cba..aca0bf9 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-4.19.11+4.19.12diff --git a/docs/H3_ENGINE.md b/docs/H3_ENGINE.mdindex 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.pyindex 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) -> Notry:# 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: BLE001push_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 = 56H3_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: BLE001push_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.pyindex 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_availableq("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())continueeq(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: Truetry: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())continueno_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"] = savedp.pack_available_anywhere = _saved_anywhere@@ -524,8 +562,11 @@ finally:p.ACTIVE_MODEL_VERSION = _saved_activeeq("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.mdindex 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}