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(v3.7.0): drafts in a minute, a real 10 seconds, H3 LoRAs, and a low-RAM engine

mrbizarrod4c6ac55a2de
diff --git a/VERSION b/VERSION
index b727628..7c69a55 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-3.6.2
+3.7.0
diff --git a/docs/ANALYTICS.md b/docs/ANALYTICS.md
index 0ae5d73..87f30f4 100644
--- a/docs/ANALYTICS.md
+++ b/docs/ANALYTICS.md
@@ -66,7 +66,7 @@ that matters to you, turn analytics off — or self-host the endpoint (below).
## Events
-Five event types. That's the whole list.
+Six event types. That's the whole list.
### `app_boot`
diff --git a/docs/H3_ENGINE.md b/docs/H3_ENGINE.md
index 65865d6..bb0c9a6 100644
--- a/docs/H3_ENGINE.md
+++ b/docs/H3_ENGINE.md
@@ -215,15 +215,69 @@ can never disagree with the ffmpeg command because it is generated from it.
---
+## LoRAs
+
+H3 takes community adapters through the same `--lora PATH[:SCALE]` flag Turbo
+rides on. Four things about that are not obvious, and each is enforced in code:
+
+**Its own library.** H3 LoRAs live in `<models root>/loras/`, beside
+`turbo-lora/` and the weight components — **not** in `mlx_models/loras/`, which
+is the LTX (and mflux image) tree. The split is a directory, not a naming
+convention, because the picker filters on *which tree a file was found in*
+before it looks at any metadata: a hand-dropped `.safetensors` with no sidecar
+classifies as `unknown`, and `unknown` is deliberately permissive. The two
+engines share no module tree, so an LTX adapter handed to H3's loader matches
+zero modules — a **silent** no-op — and an H3 one handed to LTX fails inside the
+fuser. `make_job` scrubs the wrong lane off every job, in both directions.
+
+**One slot.** `generate_staged.py` declares `--lora` with `default=None`, not
+`action="append"`, and calls `parse_spec` once. So there is exactly one adapter
+per render and **Turbo and a user LoRA cannot both run**. The panel refuses to
+pick a winner silently: `h3_lora_slot` (make_job allowlist) is `turbo` by
+default, in which case picking a LoRA while Turbo is on is a hard error naming
+the conflict; setting it to `user` is the explicit opt-out — Turbo is released,
+the step count goes back to the tier's, and both facts are logged. Stacking two
+LoRAs is refused the same way.
+
+**Key layouts.** Three exist in the wild and only two work:
+
+| Layout | Keys | What happens |
+|---|---|---|
+| bare | `blocks.N.attn.qkv_proj.lora_A/B.weight` | loads as-is |
+| ComfyUI repack | the same, namespaced under `diffusion_model.` | **converted in place** at install time — a safetensors *header* rewrite (the offsets are relative to the tensor buffer, so every tensor byte is untouched), recorded in the sidecar as `lora_layout` / `lora_converted_prefix` |
+| diffusers / PEFT | split `to_q`/`to_k`/`to_v`, `ff.net.*` | **refused, by design** |
+| kohya | `lora_down`/`lora_up` + `.alpha` | **refused, by design** |
+
+The refusals are not laziness. A diffusers-namespace adapter needs a runtime
+`alpha / rank` multiplier that **is not in the file** — LightX2V's is
+`8 / 128 = 0.0625`, supplied externally by its own inference script — and
+applying it at 1.0 renders coloured noise, not a slightly-off clip. See
+`LIGHTX2V_LORA_FIX.md` and `scripts/convert_lightx2v_lora.py` in the engine
+repo for the manual path. The panel says exactly this in the error.
+
+**CivitAI.** The browser's video context has family pills (`ltx` / `h3`),
+preselected from the active engine, so an LTX user's default view is unchanged.
+CivitAI's base-model string is **`MiniMax H3`** — verified against the live API;
+`MiniMax`, `Hailuo` and `Hailuo H3` all return zero. Downloads route by the
+item's *own* base model, not by which pill was showing, so a MiniMax H3 LoRA
+lands in the H3 library even if it was found under "All".
+
+`/status.h3.loras` reports `{supported, dir, count, usable, max_stack}`;
+`supported` is a probe of the **installed** runner for `--lora`, and the picker
+is hidden entirely on a pack that predates it.
+
+---
+
## What H3 does *not* do
- **Modes**: Text and Image only. Every other mode (FFLF, Extend, Remix,
Character, A2V) is LTX-pipeline-specific; the picker snaps back to LTX with a
- note. Character does too — it submits `mode=t2v` but stacks LTX LoRAs, and H3
- has no LoRA path.
-- **LoRAs, orientation, accel, temporal interpolation, the LTX upscale
- control**: none apply. Those carry `data-ltx-only` and fold away under
- `body[data-h3-engine="h3"]`. H3 has its own export control (`h3_upscale`,
+ note. Character does too — it submits `mode=t2v` but stacks **LTX** LoRAs, and
+ those cannot load on H3 (see LoRAs below, which is about H3's own library).
+- **LoRA STACKING**: H3 takes exactly one adapter — see LoRAs below.
+- **Orientation, accel, temporal interpolation, the LTX upscale control**: none
+ apply. Those carry `data-ltx-only` and fold away under
+ `body[data-engine="h3"]`. H3 has its own export control (`h3_upscale`,
`data-h3-only`) — see the export-pass section above.
- **External audio**: H3 generates its own. `i2v_clean_audio` stays LTX.
diff --git a/install_h3.js b/install_h3.js
index 92102ab..5e39538 100644
--- a/install_h3.js
+++ b/install_h3.js
@@ -32,7 +32,12 @@
// runner for the flag and keeps Image mode on LTX when it's absent, so an
// older checkout degrades to Text-only instead of failing mid-render. Bump
// this pin when the first-frame work is published.
-const H3_BRANCH = "codex/h3-engine"
+// v2 (2026-08-10): --lora (single adapter slot), TAE draft decode, native
+// single-window 10s/15s drafts, Stage-A latent caching, the streaming Q8
+// quantizer for 48 GB Macs, and the LoRA-on-quantized logical-dims fix.
+// Published as a NEW branch: the histories diverged, and force-moving a
+// branch users' installs already track is how updates break mid-clone.
+const H3_BRANCH = "codex/h3-engine-v2"
module.exports = {
requires: { bundle: "ai" },
@@ -59,15 +64,18 @@ module.exports = {
// single lines (#50). One shell invocation — the if/else spans lines.
[
"MEM_BYTES=$(sysctl -n hw.memsize 2>/dev/null)",
- "if echo \"$MEM_BYTES\" | grep -qE '^[0-9]+$' && [ \"$MEM_BYTES\" -lt 60000000000 ]; then",
+ "if echo \"$MEM_BYTES\" | grep -qE '^[0-9]+$' && [ \"$MEM_BYTES\" -lt 46000000000 ]; then",
" MEM_GB=$((MEM_BYTES / 1000000000))",
" echo '=================================================================='",
- " echo \"HAILUO H3 NEEDS ABOUT 64 GB OF UNIFIED MEMORY (this Mac has ${MEM_GB} GB)\"",
- " echo 'The staged runner peaks around 40 GiB with one component resident at'",
- " echo 'a time. Below 64 GB it swaps and a 3-second clip takes hours.'",
+ " echo \"HAILUO H3 NEEDS AT LEAST A 48 GB MAC (this Mac has ${MEM_GB} GB)\"",
+ " echo 'Even the reduced-RAM Q8 engine peaks around 27 GiB while rendering;'",
+ " echo 'below 48 GB it swaps and a 3-second clip takes hours.'",
" echo 'Nothing was downloaded. Keep using the built-in LTX-2.3 engine.'",
" echo '=================================================================='",
" exit 1",
+ "elif [ \"$MEM_BYTES\" -lt 60000000000 ]; then",
+ " echo 'H3 memory preflight OK - 48 GB class: the reduced-RAM Q8 engine'",
+ " echo 'will be built locally after the weights download (adds ~5 min).'",
"else",
" echo 'H3 memory preflight OK'",
"fi",
@@ -197,6 +205,60 @@ module.exports = {
}
},
+ // ---- TAE: the fast draft decoder (~23 MB) ------------------------------
+ // H3's video decoder is a 36-layer ViT and it is the biggest FIXED cost in
+ // a render — 88 s of a 501 s clip, 77% of everything that isn't denoising.
+ // madebyollin's TAE replaces it on DRAFT tiers only and takes a 640x384 5 s
+ // draft from ~5 min to ~66 s. 23 MB against a 75 GB pack, so it is not
+ // worth making optional; the panel offers the fast path only when this file
+ // AND the runner flag are both present, and every delivery tier keeps the
+ // untouched full VAE regardless.
+ {
+ method: "shell.run",
+ params: {
+ path: "minimax-h3-mlx",
+ env: {
+ HF_HOME: "{{cwd}}/cache/HF_HOME",
+ HF_XET_HIGH_PERFORMANCE: "1"
+ },
+ message: [
+ "mkdir -p '{{cwd}}/mlx_models/hailuo-h3/models/tae'",
+ ".venv/bin/python -c \"from huggingface_hub import hf_hub_download; import shutil; p=hf_hub_download('madebyollin/taeh3','taeh3.safetensors'); shutil.copy(p, '{{cwd}}/mlx_models/hailuo-h3/models/tae/taeh3.safetensors'); print('TAE draft decoder ready')\""
+ ]
+ }
+ },
+
+ // ---- Reduced-RAM engine (48 GB Macs): build the Q8 DiT locally ---------
+ // The Q8 pack halves the render peak (27.3 vs 42.8 GiB measured), which is
+ // what makes H3 possible on this class of machine at all. Built locally by
+ // quantize_stream.py — bounded memory (never holds more than one tensor,
+ // CPU stream, deterministic), so the build itself runs fine on the same
+ // 48 GB machine that could never load the model whole. ~22 GB on disk,
+ // ~5 min. 64 GB+ Macs skip this: bf16 is the quality default there, and
+ // the panel can build the pack later via Settings if the user wants the
+ // low-RAM mode. Idempotent: the pack's own config files gate the re-run.
+ {
+ method: "shell.run",
+ params: {
+ path: "minimax-h3-mlx",
+ message: [
+ [
+ "MEM_BYTES=$(sysctl -n hw.memsize 2>/dev/null)",
+ "PACK='{{cwd}}/mlx_models/hailuo-h3/models/h3-dit-q8'",
+ "SRC='{{cwd}}/mlx_models/hailuo-h3/models/deepbeep-pruned-bf16/MiniMax-H3-FL2VA-pruned_bf16.safetensors'",
+ "if [ -f \"$PACK/quant_config.json\" ]; then",
+ " echo 'Q8 engine already built - skipping'",
+ "elif echo \"$MEM_BYTES\" | grep -qE '^[0-9]+$' && [ \"$MEM_BYTES\" -lt 60000000000 ]; then",
+ " echo '=== Building the reduced-RAM Q8 engine (~5 min, one time) ==='",
+ " .venv/bin/python scripts/quantize_stream.py --src \"$SRC\" --out \"$PACK\"",
+ "else",
+ " echo '64 GB-class Mac - bf16 engine is the default, Q8 not built'",
+ "fi",
+ ].join("\n")
+ ]
+ }
+ },
+
{
method: "notify",
params: {
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index 67d7b55..c39541f 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -597,6 +597,15 @@ def _validate_settings_patch(patch: dict) -> tuple[dict, str | None]:
return {}, f"unknown memory_policy: {policy}"
out["memory_policy"] = policy
+ # ---- H3 DiT precision --------------------------------------------------
+ # auto (RAM decides — the default), q8 (force the low-RAM pack: ~15 GiB
+ # back for the OS on any machine), bf16 (force max quality where it fits).
+ if "h3_dit" in patch:
+ v = str(patch["h3_dit"]).strip().lower()
+ if v not in ("auto", "bf16", "q8"):
+ return {}, f"unknown h3_dit: {v} (auto | bf16 | q8)"
+ out["h3_dit"] = v
+
# ---- Anonymous usage analytics -------------------------------------
# Additive only: three user-settable fields. `analytics_install_id`,
# `analytics_last_packs` and `analytics_disclosed` are deliberately NOT
@@ -1999,6 +2008,12 @@ def _h3_install_turbo(push_log) -> dict:
#
# Compat tag vocabulary used throughout the panel + JS picker:
# "video" — LTX-Video LoRAs (any t2v / i2v / keyframe / extend)
+# "video:h3" — MiniMax / Hailuo H3 LoRAs. Its OWN tag, deliberately
+# NOT a flavour of "video": the two video engines share
+# no weight layout and no runner, so an LTX LoRA offered
+# on the H3 picker is a guaranteed failure rather than a
+# maybe. The two libraries also live in two directories
+# (see _h3_loras_dir) so the separation is structural.
# "image:flux1" — FLUX.1 [dev] / [schnell] (mflux flux1 family)
# "image:flux2" — FLUX.2 (klein-4b) base + Klein-Edit (flux2 + flux2_edit)
# "image:qwen" — Qwen-Image / Qwen-Image-Edit (qwen + qwen_edit)
@@ -2031,9 +2046,18 @@ def _classify_lora_modes(base_model) -> list[str]:
norm = "".join(ch for ch in s if ch.isalnum())
tags: list[str] = []
+ # ---- Video lane: Hailuo H3 (MiniMax) ----
+ # CivitAI's taxonomy string is "MiniMax H3" — VERIFIED 2026-08-09 against
+ # the live /models endpoint: `baseModels=MiniMax H3` returns hits while
+ # "MiniMax", "Hailuo" and "Hailuo H3" all return zero. Checked BEFORE the
+ # LTX branch and returned INSTEAD of "video" (not alongside it), because
+ # the whole point of the tag is that these two libraries must never bleed
+ # into each other's picker.
+ if ("minimax" in norm and "h3" in norm) or "hailuoh3" in norm:
+ tags.append("video:h3")
# ---- Video lane (LTX-Video) ----
# CivitAI strings include "LTXV 2.3", "LTX-Video", "LTX-2", "LTXV2.3".
- if "ltx" in norm:
+ elif "ltx" in norm:
tags.append("video")
# ---- Image lane: Qwen ----
# "Qwen Image", "Qwen-Image-Edit", "Qwen Image Edit 2511" → image:qwen.
@@ -2104,6 +2128,16 @@ def _read_lora_sidecar(safetensors_path: Path) -> dict:
# CivitAI / manual installs. The picker uses this to badge trained
# LoRAs distinctly so users can find their own characters fast.
"kind": None,
+ # ---- H3 lane bookkeeping (2026-08-09) ----------------------------
+ # `lora_layout` is the key layout the file was found in — "bare" (what
+ # the MLX loader wants) or "comfyui" (the same tensors under a
+ # `diffusion_model.` namespace). `lora_converted_prefix` records the
+ # namespace we STRIPPED at install time, so the sidecar answers "was
+ # this file modified, and how" without re-reading 700 MB of weights.
+ # Both are None on every LTX-lane sidecar ever written; absent keys
+ # fall back to these defaults, so no existing sidecar needs a rewrite.
+ "lora_layout": None,
+ "lora_converted_prefix": None,
}
if sidecar.exists():
try:
@@ -2170,6 +2204,15 @@ def list_user_loras() -> list[dict]:
"path": str(path),
"filename": path.name,
"size_bytes": size_bytes,
+ # Which ENGINE DIRECTORY this file was discovered in — "ltx" for
+ # the panel's own mlx_models/loras/ tree (LTX video + every mflux
+ # image family), "h3" for the Hailuo pack's loras/ dir. The picker
+ # filters on THIS before it looks at compatible_modes, because a
+ # sidecar-less drop classifies as "unknown" and "unknown" is
+ # deliberately permissive — without the directory being
+ # authoritative, an untagged LTX LoRA would surface in the H3
+ # picker and vice versa. See list_h3_user_loras().
+ "lane": "ltx",
"trigger_words": trigger_words,
"recommended_strength": float(meta.get("recommended_strength") or 1.0),
"preview_url": preview_url,
@@ -4116,12 +4159,34 @@ _CIVITAI_IMAGE_FAMILIES: dict[str, list[str]] = {
"qwen": ["Qwen 2", "Qwen"], # Qwen-Image-Edit-2511 + Qwen-Image (2509)
"hidream": ["HiDream-O1"], # HiDream-O1-Image-Dev
}
+# Sub-families for the VIDEO context — one per video ENGINE. Same mechanism
+# the image context uses, and for a stronger reason: LTX and H3 don't merely
+# prefer different LoRAs, they cannot load each other's at all (different
+# module tree, different runner, different loader). The family pill is
+# therefore not a convenience filter here, it is the lane selector, and
+# openCivitaiModal() preselects it from the ACTIVE engine so an LTX user's
+# default view is byte-for-byte what it was before H3 LoRAs existed.
+#
+# Both strings probed against the live CivitAI API rather than guessed:
+# "LTXV 2.3" verified 2026-05-20 — "LTX 2.3", "LTX-Video 2.3" and
+# "LTXV2.3" all return zero.
+# "MiniMax H3" verified 2026-08-09 — "MiniMax", "Hailuo" and "Hailuo H3"
+# all return zero; "MiniMax H3" is the only spelling with hits.
+_CIVITAI_VIDEO_FAMILIES: dict[str, list[str]] = {
+ "ltx": ["LTXV 2.3"],
+ "h3": ["MiniMax H3"],
+}
+# family-map per context, so the `family` query param means the same thing on
+# both surfaces and adding a family stays a one-line edit in ONE of the two
+# dicts above.
+_CIVITAI_FAMILIES_BY_CONTEXT: dict[str, dict[str, list[str]]] = {
+ "video": _CIVITAI_VIDEO_FAMILIES,
+ "image": _CIVITAI_IMAGE_FAMILIES,
+}
_CIVITAI_BASE_MODELS_BY_CONTEXT = {
- # Video LoRAs — the default. LTX-2.3 is the only video base we support.
- # Verified 2026-05-20 by probing the CivitAI API: "LTXV 2.3" is the
- # only spelling that returns hits; "LTX 2.3", "LTX-Video 2.3", and
- # "LTXV2.3" all return zero.
- "video": ["LTXV 2.3"],
+ # Video LoRAs — the default. Union of every video family; the `family`
+ # query param on /civitai/search narrows it to one engine's lane.
+ "video": [bm for bms in _CIVITAI_VIDEO_FAMILIES.values() for bm in bms],
# Image LoRAs — union of every family in _CIVITAI_IMAGE_FAMILIES.
# Sub-filtering happens via the `family` query param on /civitai/search.
"image": [bm for bms in _CIVITAI_IMAGE_FAMILIES.values() for bm in bms],
@@ -4160,13 +4225,14 @@ def _civitai_search(query: str = "", nsfw: bool = False,
base_models_filter = _CIVITAI_BASE_MODELS_BY_CONTEXT.get(
context, _CIVITAI_BASE_MODELS_BY_CONTEXT["video"]
)
- # Sub-family narrowing for the image context. The browser exposes pills
- # for "Qwen-Image" and "HiDream" so users can scope the result set to
- # the engine they're about to use. family="" (or missing, or "all")
- # leaves the full image-context list active.
+ # Sub-family narrowing. The browser exposes pills per context — "LTX-2.3"
+ # / "Hailuo H3" on video, "Qwen-Image" / "HiDream" on image — so users can
+ # scope the result set to the engine they're about to use. family=""
+ # (or missing, or "all") leaves the full context list active.
fam = (family or "").strip().lower()
- if context == "image" and fam and fam in _CIVITAI_IMAGE_FAMILIES:
- base_models_filter = _CIVITAI_IMAGE_FAMILIES[fam]
+ _fam_map = _CIVITAI_FAMILIES_BY_CONTEXT.get(context) or {}
+ if fam and fam in _fam_map:
+ base_models_filter = _fam_map[fam]
# The CivitAI API accepts multi-value baseModels as repeated query
# params (`baseModels=X&baseModels=Y`), not comma-separated. Passing
# a list here triggers `urlencode(..., doseq=True)` in _civitai_request
@@ -4255,11 +4321,18 @@ def _civitai_search(query: str = "", nsfw: bool = False,
def _civitai_download(download_url: str, meta: dict) -> dict:
- """Download a CivitAI .safetensors into mlx_models/loras/ and write
- a sidecar JSON. Returns { name, path, sidecar_path, size_bytes }.
+ """Download a CivitAI .safetensors into the right LoRA dir for its base
+ model and write a sidecar JSON. Returns
+ { name, path, sidecar_path, size_bytes, lane }.
Streams to a .partial file then renames atomically — a Pinokio kill
mid-download leaves nothing the next scan would mistake for a
- complete LoRA."""
+ complete LoRA.
+
+ Lane routing (2026-08-09) is decided from the ITEM's own `base_model`,
+ not from which browser context the click came from. A MiniMax H3 LoRA
+ lands in the H3 weights tree even if the user found it while the browser
+ was showing "All", because the file's family is a property of the file,
+ and mis-filing it would put an unloadable adapter in the LTX picker."""
import urllib.parse, urllib.request
if not download_url:
raise RuntimeError("download_url required")
@@ -4279,7 +4352,12 @@ def _civitai_download(download_url: str, meta: dict) -> dict:
if api_key_env and "token=" not in (parsed.query or ""):
sep = "&" if parsed.query else "?"
download_url = download_url + sep + "token=" + urllib.parse.quote(api_key_env)
- loras_dir = _safe_loras_dir()
+ # Which engine's library does this belong to? _classify_lora_modes is the
+ # single source for that mapping — the picker filter, the sidecar and this
+ # router all read the same function, so a new family is one edit there.
+ lane = ("h3" if "video:h3" in _classify_lora_modes(meta.get("base_model"))
+ else "ltx")
+ loras_dir = _safe_h3_loras_dir() if lane == "h3" else _safe_loras_dir()
# Filename from meta (preferred — preserves CivitAI's name) or fall
# back to the URL's last path segment.
fname = (meta.get("filename") or
@@ -4300,6 +4378,7 @@ def _civitai_download(download_url: str, meta: dict) -> dict:
"name": meta.get("name") or target.stem,
"path": str(target),
"size_bytes": target.stat().st_size,
+ "lane": lane,
"skipped": True,
"reason": "already exists",
}
@@ -4357,6 +4436,24 @@ def _civitai_download(download_url: str, meta: dict) -> dict:
except OSError: pass
raise
push(f"[civitai] saved {target.name} ({bytes_written // (1024*1024)} MB)")
+ # ---- H3 lane: classify the key layout NOW, at install time --------------
+ # Doing it here rather than at render time means the ComfyUI rename happens
+ # once, in front of the user, with the log open — and a diffusers-namespace
+ # LoRA is refused at the moment they clicked Install instead of 30 s into a
+ # 20-minute render. The file is REMOVED on refusal: leaving an unloadable
+ # adapter in the library would put a permanently-failing entry in the
+ # picker, which is worse than the wasted download it cost to find out.
+ layout_info = {"layout": None, "converted": False, "prefix": ""}
+ if lane == "h3":
+ try:
+ layout_info = _h3_lora_prepare(target)
+ except Exception as exc:
+ try:
+ target.unlink()
+ except OSError:
+ pass
+ push(f"[civitai] refused {target.name}: {exc}")
+ raise RuntimeError(str(exc)) from exc
# Write the sidecar — kept tolerant of meta gaps so a partial
# payload still produces a usable picker entry.
sidecar = target.with_suffix(".json")
@@ -4366,12 +4463,19 @@ def _civitai_download(download_url: str, meta: dict) -> dict:
"trigger_words": list(meta.get("trigger_words") or []),
"recommended_strength": float(meta.get("recommended_strength") or 1.0),
"preview_url": meta.get("preview_url"),
- "base_model": meta.get("base_model") or "LTXV 2.3",
+ "base_model": (meta.get("base_model")
+ or ("MiniMax H3" if lane == "h3" else "LTXV 2.3")),
"civitai_id": meta.get("id"),
"civitai_version_id": meta.get("version_id"),
"civitai_url": meta.get("civitai_url"),
"downloaded_at": iso_now(),
"downloaded_size_bytes": bytes_written,
+ # What we found, and what we did about it. Written for both lanes so
+ # the field means the same thing everywhere; None on LTX, where the
+ # panel does no layout surgery.
+ "lora_layout": layout_info.get("layout"),
+ "lora_converted_prefix": (layout_info.get("prefix") or None
+ if layout_info.get("converted") else None),
}
try:
atomic_write_text(sidecar, json.dumps(sidecar_data, indent=2))
@@ -4382,6 +4486,11 @@ def _civitai_download(download_url: str, meta: dict) -> dict:
"path": str(target),
"sidecar_path": str(sidecar),
"size_bytes": bytes_written,
+ # "ltx" | "h3" — the client uses this to decide whether it may
+ # auto-enable the new LoRA on the currently-selected engine.
+ "lane": lane,
+ "layout": layout_info.get("layout"),
+ "converted": bool(layout_info.get("converted")),
"skipped": False,
}
@@ -4868,6 +4977,12 @@ H3_MODELS = Path(os.environ.get("LTX_H3_MODELS", str(ROOT / "mlx_models" / "hail
# 64 GB machines report ~63.x GiB after firmware reservations, so the floor is
# 60, not 64. Below this the staged runner swaps and a 3 s clip takes hours.
H3_MIN_RAM_GB = 60.0
+# With the Q8 DiT (8-bit core + 8-bit AdaLN, the recipe quantize.py's own table
+# calls measured-safe) the render peak drops from 42.8 to 27.3 GiB measured at
+# 1024x576/124f — which puts H3 in reach of 48 GB Macs. 46 leaves the same
+# ~4 GB guard band under the marketing number that 60-under-64 does.
+H3_MIN_RAM_GB_Q8 = 46.0
+H3_DIT_Q8_DIRNAME = "h3-dit-q8"
H3_DIT_FILENAME = "MiniMax-H3-FL2VA-pruned_bf16.safetensors"
H3_COMPACT_FILES = ("text_encoder.safetensors", "video_vae.safetensors",
"audio_vae.safetensors")
@@ -5370,23 +5485,35 @@ def _h3_lengths() -> dict[str, dict]:
"note": H3_TIER_CHAIN_NOTE,
"offered": True,
},
- # The pre-chaining path, kept reachable for A/B work and NOT offered by
- # default: it costs ~2.1× the chained length for the same delivered clip.
- # Restricted to the two smaller canvases because it is the one shape
- # where memory is NOT flat — a single 243f pass is 25k packed rows at
- # 768×448 (42.6 GiB peak, measured) and would be 42.5k at 1024×576,
- # which does not fit in 64 GB. Encoded as data so the UI can grey the
- # cell with the reason rather than letting it queue and OOM.
+ # A REAL 10 s clip: one pass, one window, no seam, no chain drift, and no
+ # repeated prompt. Requested as the #1 wish by @Wizard_1981 ("echte 10
+ # und 15 Sekunden Videos") after the chained 10 s was reported as
+ # "repeats after 5 seconds".
+ #
+ # This was gated off on a PROJECTION that it "would be 42.5k rows at
+ # 1024×576, which does not fit in 64 GB". That projection is wrong, and
+ # measurement retired it: seven single-window 243f renders on a 64 GB
+ # M4 Max, peaks 47.0 GiB at 1024×576 and 53.5 GiB at 1344×768 — it fits
+ # at BOTH, with headroom. (AURELIUS round 2, metrics JSON per clip:
+ # 28_BOX_JOY 1024×576 47.0; 01_AVRELIVS/23_THE_BOX/31_THE_GATE/
+ # 32_STREET_WIDE/34_GATE_THE_WAIT 1344×768 53.5.)
+ #
+ # The old "~2.1× slower" line was measured against the 15-forward dense
+ # default; with Turbo the same single pass is what the AURELIUS batch
+ # rendered all night. 15 s single-window (362f) is NOT enabled — it is
+ # ~1.5× these rows and has never been measured here. Chain 15 s until it is.
"10s_dense": {
- "key": "10s_dense", "label": "10s dense", "order": 4, "seconds": 10,
+ "key": "10s_dense", "label": "10s single pass", "order": 4, "seconds": 10,
"frames": 243, "window_frames": 243, "windows": 1,
"steps": 16,
- "blurb": "One dense pass at 15 forwards — the pre-chaining path. "
- "Kept for A/B only; the chained 10s is ~2.1× faster.",
- "qualities": ("preview", "draft", "standard"),
+ "blurb": "A real 10 seconds in ONE pass — no seam, no chained "
+ "repeat, no drift between halves. Slower than the chained "
+ "10s; this is the one to pick when the clip has to hold "
+ "together as a single shot.",
+ # Measured to fit on every canvas up to Native (53.5 GiB peak at
+ # 1344×768); no longer restricted to the small ones.
"dense": True,
- "offered": os.environ.get("LTX_H3_DENSE_10S", "").strip()
- in ("1", "true", "yes"),
+ "offered": True,
},
}
for l in out.values():
@@ -5690,9 +5817,20 @@ def h3_paths() -> dict:
continue
models_root = root
dit = cand_dit
- cand_compact = root / "ddalcu-q8"
+ # LTX_H3_COMPACT_DIR picks an alternate conditioning-encoder dir under the same
+ # models root (e.g. "heretic-q8", an abliterated encoder re-quantized to the
+ # ddalcu layout). Dev/testing override; default stays the shipped ddalcu-q8.
+ compact_dirname = os.environ.get("LTX_H3_COMPACT_DIR", "ddalcu-q8")
+ cand_compact = root / compact_dirname
if all((cand_compact / f).is_file() for f in H3_COMPACT_FILES):
compact_root = cand_compact
+ elif compact_dirname != "ddalcu-q8":
+ # explicit override that isn't usable: fall back loudly, not silently
+ print(f"[h3] LTX_H3_COMPACT_DIR={compact_dirname} incomplete under {root}; "
+ f"falling back to ddalcu-q8", flush=True)
+ cand_compact = root / "ddalcu-q8"
+ if all((cand_compact / f).is_file() for f in H3_COMPACT_FILES):
+ compact_root = cand_compact
cand_cfg = root.joinpath("upstream-meta", *H3_TEXT_CONFIG_REL)
if cand_cfg.is_file():
text_config = cand_cfg
@@ -5745,6 +5883,9 @@ def h3_paths() -> dict:
"runner": runner,
"python": python,
"dit": dit,
+ # bf16 master path stays canonical in `dit`; the render-time swap to
+ # the Q8 pack happens in the dispatch via h3_dit_choice(), so /status
+ # can always show BOTH what exists and what will be used.
"compact_root": compact_root,
"text_config": text_config,
"missing": missing,
@@ -5764,6 +5905,39 @@ def h3_available() -> bool:
return not h3_paths()["missing"]
+def _h3_q8_dit_dir() -> Path | None:
+ """The quantized DiT pack, if present: config + quant recipe + all shards."""
+ for root in _h3_model_roots():
+ d = root / H3_DIT_Q8_DIRNAME
+ if (d / "config.json").is_file() and (d / "quant_config.json").is_file() and any(d.glob("model-*.safetensors")):
+ return d
+ return None
+
+
+def h3_dit_choice() -> tuple[str, Path | None]:
+ """Which DiT this Mac should render with: ("bf16"|"q8", path).
+
+ The system decides from RAM, the same signal every other capability tier
+ uses — a 64 GB Mac keeps the bf16 master (max quality, its peak fits), a
+ sub-60 GB Mac gets the Q8 pack (27.3 vs 42.8 GiB measured peak, +3% wall,
+ faces held in the 2026-08-10 A/B). `h3_dit` in Settings overrides both
+ ways: "q8" lets a 64 GB machine reclaim ~15 GiB for the rest of the OS
+ (the mic-dies / video-stalls complaint), "bf16" forces max quality where
+ it fits. An override that names a pack that is not on disk falls back
+ loudly in /status rather than silently."""
+ pref = str(get_settings().get("h3_dit") or "auto").strip().lower()
+ q8 = _h3_q8_dit_dir()
+ if pref == "q8" and q8 is not None:
+ return "q8", q8
+ if pref == "bf16":
+ return "bf16", None
+ if pref == "q8" and q8 is None:
+ pref = "auto" # fall through, surfaced via /status
+ if SYSTEM_RAM_GB < H3_MIN_RAM_GB and q8 is not None:
+ return "q8", q8
+ return "bf16", None
+
+
def h3_capable() -> bool:
"""True when this Mac has the unified memory H3 needs (~40 GiB peak).
@@ -5773,7 +5947,12 @@ def h3_capable() -> bool:
"""
if os.environ.get("LTX_H3_FORCE_CAPABLE", "").strip() in ("1", "true", "yes"):
return True
- return SYSTEM_RAM_GB >= H3_MIN_RAM_GB
+ if SYSTEM_RAM_GB >= H3_MIN_RAM_GB:
+ return True
+ # Reduced-RAM lane: the Q8 DiT pack halves the render peak (27.3 GiB
+ # measured), so a 48 GB-class Mac is genuinely capable once that pack
+ # exists on disk. Without the pack the old gate stands.
+ return SYSTEM_RAM_GB >= H3_MIN_RAM_GB_Q8 and _h3_q8_dit_dir() is not None
_H3_FLAG_CACHE: dict[str, bool] = {}
@@ -5904,6 +6083,427 @@ def h3_turbo_status() -> dict:
}
+# ============================================================================
+# H3 USER LoRAs — CivitAI adapters for the MiniMax H3 lane
+# ============================================================================
+# Turbo proved the mechanism: the staged runner takes `--lora PATH[:SCALE]`
+# and fuses a low-rank adapter into the DiT at load. Nothing about that flag
+# is Turbo-specific, so a community LoRA trained for MiniMax H3 is renderable
+# today. Three things had to be decided before it could be offered, and each
+# one is a trap someone else already fell into:
+#
+# 1. WHERE THEY LIVE. Their OWN directory, next to the weights they apply to,
+# exactly as `_h3_turbo_dir()` already does — NOT mlx_models/loras/. The
+# two engines share no module tree: an LTX LoRA handed to H3's loader
+# matches zero modules (a silent no-op, the worst failure mode there is)
+# and an H3 LoRA handed to LTX's fuser fails inside the pipeline. Making
+# the split a DIRECTORY makes it structural — the picker filters on which
+# tree a file was found in, before it ever looks at a sidecar string, so a
+# LoRA someone dropped in by hand with no metadata still can't cross lanes.
+#
+# 2. THE COMFYUI PREFIX. Most H3 LoRAs on CivitAI are ComfyUI repacks, whose
+# keys carry a `diffusion_model.` namespace the MLX loader doesn't expect.
+# Verified fact (Kijai's repack, diffed against larryvrh's original): the
+# repack IS the bare layout plus that prefix, tensors bit-identical. So the
+# fix is a pure key rename — see _h3_lora_strip_prefix, which rewrites the
+# safetensors HEADER and copies the tensor buffer through untouched.
+#
+# 3. THE PEFT/DIFFUSERS ALPHA TRAP. A diffusers-namespace LoRA (split
+# to_q/to_k/to_v, ff.net.*) needs BOTH a structural conversion and an
+# alpha/rank multiplier that IS NOT IN THE FILE — LightX2V's adapter needs
+# alpha 8 / rank 128 = 0.0625 supplied externally, and running it without
+# that renders coloured noise (LIGHTX2V_LORA_FIX.md, in the H3 pack). There
+# is no way to recover that number from the checkpoint, so this pass
+# DETECTS the layout and REFUSES it with a sentence naming the problem.
+# Guessing 1.0 would ship a 16x-hot adapter that looks like a broken render.
+H3_LORAS_DIRNAME = "loras"
+
+# The runner's `--lora` takes ONE path. `default=None`, not `action="append"` —
+# checked in scripts/generate_staged.py, which then does a single
+# `lora_mod.parse_spec(args.lora)`. So there is exactly one adapter slot per
+# render and a user LoRA and Turbo cannot both occupy it. That is a fact about
+# the runner, not a policy we chose, and it is why h3_lora_slot exists rather
+# than the panel quietly picking a winner.
+H3_LORA_MAX_STACK = 1
+H3_LORA_SLOTS = ("turbo", "user")
+H3_LORA_SLOT_DEFAULT = "turbo"
+H3_LORA_STACK_NOTE = (
+ "H3's runner has ONE adapter slot (`--lora` takes a single path), so a "
+ "LoRA and Turbo can't both run. Pick which one this render uses.")
+
+# Namespaces other runtimes wrap the DiT in. Longest-first so
+# "model.diffusion_model." wins over "diffusion_model." on a file that has
+# both spellings' worth of depth. Mirrors KNOWN_PREFIXES in the H3 pack's
+# minimax_h3_mlx/lora.py — kept here as well because the panel must classify a
+# file BEFORE any pack code runs, and because older installed packs have no
+# lora.py at all.
+H3_LORA_KNOWN_PREFIXES = ("model.diffusion_model.", "diffusion_model.", "transformer.")
+# Key fragments that identify a diffusers / PEFT-namespace adapter — the one
+# layout this pass refuses. Split attention projections and the diffusers
+# feed-forward path are both present in that namespace and in no other.
+_H3_LORA_DIFFUSERS_MARKERS = (".to_q.", ".to_k.", ".to_v.", ".to_out.", ".ff.net.")
+# kohya / sd-scripts naming. A rename away from ours on paper, but those files
+# also carry `.alpha` scalars whose meaning we would have to honour — same
+# class of trap as the PEFT one, so it gets the same answer: name it, refuse.
+_H3_LORA_KOHYA_SUFFIX = ".lora_down.weight"
+_H3_LORA_A_SUFFIX = ".lora_A.weight"
+_H3_LORA_B_SUFFIX = ".lora_B.weight"
+# A safetensors header is JSON and small (a few hundred KB for a 200-module
+# adapter). Anything claiming more than this is not a header we should read
+# into memory on a /status tick.
+_H3_LORA_MAX_HEADER_BYTES = 64 * 1024 * 1024
+
+
+def _h3_loras_dir() -> Path:
+ """Where H3 user LoRAs live: alongside the other weight components.
+
+ Follows whichever of the two supported model layouts actually holds the
+ DiT — the identical rule `_h3_turbo_dir()` uses, so Turbo's adapter and a
+ CivitAI adapter end up as siblings instead of in two different places."""
+ for root in _h3_model_roots():
+ if (root / "deepbeep-pruned-bf16" / H3_DIT_FILENAME).is_file():
+ return root / H3_LORAS_DIRNAME
+ return H3_MODELS / H3_LORAS_DIRNAME
+
+
+def _safe_h3_loras_dir() -> Path:
+ """Ensure the H3 LoRA dir exists. Idempotent. Called on the DOWNLOAD path
+ only — listing never creates it, so a machine with no H3 install doesn't
+ grow an empty tree that the pack's own probes would then have to ignore."""
+ d = _h3_loras_dir()
+ d.mkdir(parents=True, exist_ok=True)
+ return d
+
+
+def _lora_is_h3_lane(path_str) -> bool:
+ """Does this LoRA path live in the H3 library?
+
+ The ONE lane test, used by make_job's scrub, make_job's Turbo-vs-LoRA
+ decision and the render dispatch alike — three places that must never
+ disagree about which engine a file belongs to. Directory containment, not
+ a sidecar string: a file someone hand-copied with no metadata still has
+ exactly one answer here. Never raises; anything unresolvable is "not H3",
+ which keeps LTX (the built-in, forgiving lane) as the default."""
+ raw = str(path_str or "").strip()
+ if not raw:
+ return False
+ try:
+ rp = Path(raw).resolve()
+ base = _h3_loras_dir().resolve()
+ except (OSError, ValueError):
+ return False
+ try:
+ return rp.is_relative_to(base)
+ except ValueError:
+ return False
+
+
+def _safetensors_header(path: Path) -> tuple[dict, int]:
+ """The JSON header of a .safetensors file, and where the tensor buffer
+ starts. Reads the header ONLY — no tensor, no mlx, no torch.
+
+ Format: 8 bytes little-endian u64 header length, that many bytes of UTF-8
+ JSON, then one contiguous tensor buffer. Every entry's `data_offsets` are
+ relative to the START of that buffer, which is what makes a key rename a
+ header-only edit (see _h3_lora_strip_prefix). Classifying a 700 MB adapter
+ this way costs one small read instead of a full load."""
+ with path.open("rb") as fh:
+ raw_len = fh.read(8)
+ if len(raw_len) != 8:
+ raise RuntimeError(f"{path.name} is too short to be a safetensors file.")
+ n = int.from_bytes(raw_len, "little")
+ if n <= 0 or n > _H3_LORA_MAX_HEADER_BYTES:
+ raise RuntimeError(
+ f"{path.name} declares a {n}-byte safetensors header, which is "
+ f"not a plausible LoRA — refusing to read it.")
+ blob = fh.read(n)
+ if len(blob) != n:
+ raise RuntimeError(f"{path.name} is truncated (header cut short).")
+ try:
+ header = json.loads(blob.decode("utf-8"))
+ except Exception as exc:
+ raise RuntimeError(f"{path.name} has an unreadable safetensors header ({exc}).")
+ if not isinstance(header, dict):
+ raise RuntimeError(f"{path.name} has a safetensors header that isn't an object.")
+ return header, 8 + n
+
+
+def _h3_lora_layout(path: Path) -> dict:
+ """Classify a .safetensors as an H3 adapter, from its header alone.
+
+ Returns:
+ layout "bare" | "comfyui" | "diffusers" | "kohya" | "not_a_lora"
+ prefix the namespace to strip ("" unless layout == "comfyui")
+ pairs number of lora_A/lora_B module pairs found
+ ok loadable by the runner exactly as it sits on disk
+ convertible ok after an in-place key rename (comfyui)
+ reason a sentence for the user when ok is False
+ """
+ header, _ = _safetensors_header(path)
+ keys = [k for k in header if k != "__metadata__"]
+ a_names = sorted({k[: -len(_H3_LORA_A_SUFFIX)] for k in keys
+ if k.endswith(_H3_LORA_A_SUFFIX)})
+ b_names = {k[: -len(_H3_LORA_B_SUFFIX)] for k in keys
+ if k.endswith(_H3_LORA_B_SUFFIX)}
+ pairs = len([n for n in a_names if n in b_names])
+ diffusers_hit = any(m in k for k in keys for m in _H3_LORA_DIFFUSERS_MARKERS)
+ if diffusers_hit:
+ return {
+ "layout": "diffusers", "prefix": "", "pairs": pairs,
+ "ok": False, "convertible": False,
+ "reason": (
+ "this LoRA is in diffusers layout and needs manual conversion. "
+ "Its attention weights are split into to_q / to_k / to_v and it "
+ "carries no alpha value, so the scale the adapter was trained "
+ "with (PEFT's alpha/rank) is simply not in the file — applying "
+ "it at 1.0 renders coloured noise, not a slightly-off clip. "
+ "Converting it needs the rank and alpha from the model card "
+ "plus scripts/convert_lightx2v_lora.py in the H3 pack; see "
+ "LIGHTX2V_LORA_FIX.md."),
+ }
+ if not a_names and any(k.endswith(_H3_LORA_KOHYA_SUFFIX) for k in keys):
+ return {
+ "layout": "kohya", "prefix": "", "pairs": 0,
+ "ok": False, "convertible": False,
+ "reason": (
+ "this LoRA uses kohya `lora_down` / `lora_up` naming and ships "
+ "its own `.alpha` scalars. The H3 loader reads lora_A / lora_B "
+ "and applies no alpha, so a plain rename would run it at the "
+ "wrong strength — it needs manual conversion."),
+ }
+ if not pairs:
+ return {
+ "layout": "not_a_lora", "prefix": "", "pairs": 0,
+ "ok": False, "convertible": False,
+ "reason": ("no lora_A / lora_B tensor pairs in this file — it "
+ "doesn't look like a LoRA the H3 runner can apply."),
+ }
+ prefix = ""
+ for cand in sorted(H3_LORA_KNOWN_PREFIXES, key=len, reverse=True):
+ if all(n.startswith(cand) for n in a_names):
+ prefix = cand
+ break
+ if prefix:
+ return {"layout": "comfyui", "prefix": prefix, "pairs": pairs,
+ "ok": False, "convertible": True,
+ "reason": (f"ComfyUI repack — every key is namespaced under "
+ f"`{prefix}`. Stripping it is a pure rename; the "
+ f"tensors are untouched.")}
+ return {"layout": "bare", "prefix": "", "pairs": pairs,
+ "ok": True, "convertible": False, "reason": ""}
+
+
+def _h3_lora_strip_prefix(path: Path, prefix: str) -> int:
+ """Rewrite a ComfyUI-repacked H3 LoRA to the bare key layout, IN PLACE.
+
+ This is a HEADER rewrite, not a conversion. safetensors stores
+ `{name: {dtype, shape, data_offsets}}` as JSON followed by one contiguous
+ tensor buffer, and every offset is relative to that buffer — so renaming
+ keys leaves every offset, and therefore every byte of every tensor,
+ bit-identical. No tensor is ever loaded; no mlx, no torch, no numpy. The
+ claim "Kijai's comfy repack == bare layout + prefix, tensors bit-identical"
+ is exactly what makes this legitimate, and this function is careful to do
+ only the part that claim covers.
+
+ Atomic: writes a sibling temp file and os.replace()s it, so a kill
+ mid-write can never leave a half-renamed adapter where the picker would
+ find it. Returns the number of keys renamed."""
+ header, data_start = _safetensors_header(path)
+ meta = header.get("__metadata__")
+ entries = {k: v for k, v in header.items() if k != "__metadata__"}
+ renamed: dict = {}
+ n_renamed = 0
+ for k, v in entries.items():
+ nk = k[len(prefix):] if k.startswith(prefix) else k
+ if nk != k:
+ n_renamed += 1
+ if nk in renamed:
+ raise RuntimeError(
+ f"stripping `{prefix}` from {path.name} would collide on key "
+ f"{nk!r} — refusing to rewrite it.")
+ renamed[nk] = v
+ if not n_renamed:
+ return 0
+ new_meta = dict(meta or {}) if isinstance(meta, (dict, type(None))) else {}
+ # safetensors metadata values must be strings.
+ new_meta["phosphene_stripped_prefix"] = str(prefix)
+ new_meta["phosphene_converted_at"] = iso_now()
+ new_header: dict = {"__metadata__": new_meta}
+ new_header.update(renamed)
+ blob = json.dumps(new_header, separators=(",", ":")).encode("utf-8")
+ # The tensor buffer must start 8-byte aligned; the spec pads the JSON with
+ # spaces to get there, which is why trailing whitespace inside the header
+ # is legal and ignored by every reader.
+ blob += b" " * ((-len(blob)) % 8)
+ tmp = path.with_name(path.name + ".converting")
+ try:
+ with path.open("rb") as src, tmp.open("wb") as dst:
+ dst.write(len(blob).to_bytes(8, "little"))
+ dst.write(blob)
+ src.seek(data_start)
+ shutil.copyfileobj(src, dst, 1024 * 1024)
+ # Prove the rewrite before it replaces the original: re-read the temp
+ # file's header and require the same pair count under bare names.
+ check = _h3_lora_layout(tmp)
+ if check["layout"] != "bare" or check["pairs"] < 1:
+ raise RuntimeError(
+ f"post-rewrite check failed (layout={check['layout']}, "
+ f"pairs={check['pairs']}) — leaving the original untouched.")
+ os.replace(tmp, path)
+ except Exception:
+ try:
+ tmp.unlink()
+ except OSError:
+ pass
+ raise
+ return n_renamed
+
+
+def _h3_lora_prepare(path: Path) -> dict:
+ """Make `path` loadable by the H3 runner, or raise saying why it can't be.
+
+ Called on the CivitAI download path (so the conversion happens once, at
+ install time, where the user is watching the log) AND again immediately
+ before a render (so a file dropped in by hand, or a pre-existing download,
+ gets the same treatment instead of failing inside the runner). Idempotent:
+ a bare-layout file is inspected and returned untouched."""
+ info = _h3_lora_layout(path)
+ if info["ok"]:
+ return {"layout": "bare", "converted": False, "prefix": "",
+ "pairs": info["pairs"]}
+ if not info["convertible"]:
+ raise RuntimeError(f"{path.name}: {info['reason']}")
+ n = _h3_lora_strip_prefix(path, info["prefix"])
+ push(f"[h3:lora] {path.name}: stripped `{info['prefix']}` from {n} keys "
+ f"(ComfyUI repack → bare layout; tensors untouched)")
+ return {"layout": "comfyui", "converted": True, "prefix": info["prefix"],
+ "pairs": info["pairs"]}
+
+
+# Layout probes are cheap but not free, and h3_status() runs on every /status
+# tick. Cache on (path, mtime_ns, size) so an unchanged file is classified
+# once per edit rather than once per poll.
+_H3_LORA_LAYOUT_CACHE: dict[str, dict] = {}
+
+
+def _h3_lora_layout_cached(path: Path) -> dict:
+ try:
+ st = path.stat()
+ key = f"{path}|{st.st_mtime_ns}|{st.st_size}"
+ except OSError as exc:
+ return {"layout": "not_a_lora", "prefix": "", "pairs": 0, "ok": False,
+ "convertible": False, "reason": f"unreadable ({exc})"}
+ hit = _H3_LORA_LAYOUT_CACHE.get(key)
+ if hit is not None:
+ return hit
+ try:
+ info = _h3_lora_layout(path)
+ except Exception as exc:
+ info = {"layout": "not_a_lora", "prefix": "", "pairs": 0, "ok": False,
+ "convertible": False, "reason": str(exc)}
+ # Drop stale entries for the same path (an edited file leaves one behind).
+ for stale in [k for k in _H3_LORA_LAYOUT_CACHE if k.split("|")[0] == str(path)]:
+ _H3_LORA_LAYOUT_CACHE.pop(stale, None)
+ _H3_LORA_LAYOUT_CACHE[key] = info
+ return info
+
+
+def list_h3_user_loras() -> list[dict]:
+ """Scan the H3 LoRA dir and return one entry per .safetensors found.
+
+ Same record shape list_user_loras() returns — the picker renders both from
+ one code path — with three additions the H3 lane needs: `lane` ("h3", the
+ field the picker filters on), and the `layout` / `layout_ok` /
+ `layout_reason` triple so a diffusers-namespace file the user copied in by
+ hand shows up in the list marked unusable, with the reason, instead of
+ silently missing or silently failing 30 s into a render.
+
+ Turbo's own adapter is NOT here — it lives in turbo-lora/ and is driven by
+ the Speed control, not the picker (the same reason the HDR IC-LoRA is
+ hidden from the LTX picker)."""
+ out: list[dict] = []
+ base = _h3_loras_dir()
+ if not base.exists():
+ return out
+ for path in sorted(base.iterdir()):
+ if not path.is_file() or path.suffix.lower() != ".safetensors":
+ continue
+ try:
+ size_bytes = path.stat().st_size
+ except OSError:
+ continue
+ meta = _read_lora_sidecar(path)
+ info = _h3_lora_layout_cached(path)
+ preview_url = meta.get("preview_url")
+ preview_type = meta.get("preview_type")
+ if preview_url and not preview_type:
+ preview_type = ("video" if preview_url.lower().split("?")[0].endswith(".mp4")
+ else "image")
+ civitai_url = meta.get("civitai_url")
+ if not civitai_url and meta.get("civitai_id"):
+ civitai_url = f"https://civitai.com/models/{meta.get('civitai_id')}"
+ out.append({
+ "id": f"h3:{path.name}",
+ "name": meta["name"],
+ "description": meta["description"],
+ "path": str(path),
+ "filename": path.name,
+ "size_bytes": size_bytes,
+ "lane": "h3",
+ "trigger_words": list(meta.get("trigger_words") or []),
+ "recommended_strength": float(meta.get("recommended_strength") or 1.0),
+ "preview_url": preview_url,
+ "preview_type": preview_type,
+ "base_model": meta.get("base_model") or "MiniMax H3",
+ "kind": meta.get("kind"),
+ # Hard-coded rather than classified: this file was found in the H3
+ # weights tree, which is a stronger statement than any sidecar
+ # string. A hand-dropped file with no metadata still belongs to
+ # exactly one lane.
+ "compatible_modes": ["video:h3"],
+ # ok as it sits on disk, OR convertible with a key rename we do at
+ # render time. Only diffusers / kohya / not-a-LoRA come back False.
+ "layout": info.get("layout"),
+ "layout_ok": bool(info.get("ok") or info.get("convertible")),
+ "layout_reason": ("" if (info.get("ok") or info.get("convertible"))
+ else info.get("reason") or ""),
+ "civitai_id": meta.get("civitai_id"),
+ "civitai_version_id": meta.get("civitai_version_id"),
+ "civitai_url": civitai_url,
+ "downloaded_at": meta.get("downloaded_at"),
+ "is_curated": False,
+ })
+ return out
+
+
+def h3_loras_status() -> dict:
+ """The H3 LoRA lane's own availability block for /status + the bootstrap.
+
+ Separate from `turbo` because the two answers differ: Turbo is a specific
+ 0.8 GB download with a button, this is a directory the user fills from the
+ CivitAI browser. They share one gate — `supported`, whether the installed
+ runner has `--lora` at all — and one hard constraint, the single adapter
+ slot, which is why `max_stack` is reported rather than assumed by the UI."""
+ supported = h3_supports_lora()
+ entries: list[dict] = []
+ try:
+ entries = list_h3_user_loras()
+ except Exception:
+ entries = []
+ usable = [e for e in entries if e.get("layout_ok")]
+ return {
+ "supported": supported,
+ "dir": str(_h3_loras_dir()),
+ "count": len(entries),
+ "usable": len(usable),
+ "max_stack": H3_LORA_MAX_STACK,
+ "slots": list(H3_LORA_SLOTS),
+ "default_slot": H3_LORA_SLOT_DEFAULT,
+ "note": H3_LORA_STACK_NOTE,
+ "base_model": _CIVITAI_VIDEO_FAMILIES["h3"][0],
+ }
+
+
def h3_supports_chain() -> bool:
"""Whether the INSTALLED runner accepts `--chain-windows` (window chaining).
@@ -5927,6 +6527,42 @@ def h3_supports_chain_prompts() -> bool:
return _h3_runner_has_flag("--chain-prompts")
+def h3_supports_tae_draft() -> bool:
+ """Whether the INSTALLED runner accepts `--draft-decode` (TAE fast decode).
+
+ Same discipline as --chain-windows / --chain-prompts: probe, never assume.
+ A pack cloned before the draft work renders every tier correctly and simply
+ has no fast path, so the control is withheld rather than dying on an
+ argparse error 30 s into a render."""
+ return _h3_runner_has_flag("--draft-decode")
+
+
+def h3_tae_checkpoint() -> Path | None:
+ """The TAE weight, if it is on disk. ~23 MB, sits beside the other H3 models.
+
+ Returned as a path rather than a bool because the runner needs it passed
+ explicitly (`--tae-checkpoint`); `--draft-decode tae` without it is an
+ argparse error, so both halves are checked together in h3_tae_ready().
+ """
+ for root in _h3_model_roots():
+ cand = root / "tae" / "taeh3.safetensors"
+ if cand.is_file() and cand.stat().st_size > 1_000_000:
+ return cand
+ return None
+
+
+def h3_supports_stage_a() -> bool:
+ """Whether the INSTALLED runner can cache Stage-A latents (`--save-stage-a`)
+ — the input a later hires-refine pass needs to improve THIS take instead of
+ rolling a new one. Probed like every other capability."""
+ return _h3_runner_has_flag("--save-stage-a")
+
+
+def h3_tae_ready() -> bool:
+ """Runner flag AND weight both present — the only state where TAE is offered."""
+ return h3_supports_tae_draft() and h3_tae_checkpoint() is not None
+
+
def h3_normalize_chain_prompts(raw, windows: int) -> list[str]:
"""Whatever the form (or a curl) posted → exactly one entry per window.
@@ -6099,7 +6735,25 @@ def h3_status() -> dict:
"download_gb": H3_TURBO_DOWNLOAD_GB, "repo": H3_TURBO_REPO,
"dir": str(_h3_turbo_dir()), "missing": [],
"note": H3_TURBO_NOTE, "label": "Turbo"}),
+ # User LoRAs — the CivitAI lane. A separate block from `turbo` for the
+ # same reason turbo is separate from `first_frame`: "you can't pick a
+ # LoRA" has three unrelated causes (H3 absent / runner predates --lora
+ # / nothing installed yet) and the UI owes a different sentence for
+ # each. `supported` is the gate that decides whether the picker is
+ # even offered on this engine.
+ "loras": (h3_loras_status() if available else
+ {"supported": False, "dir": str(_h3_loras_dir()), "count": 0,
+ "usable": 0, "max_stack": H3_LORA_MAX_STACK,
+ "slots": list(H3_LORA_SLOTS),
+ "default_slot": H3_LORA_SLOT_DEFAULT,
+ "note": H3_LORA_STACK_NOTE,
+ "base_model": _CIVITAI_VIDEO_FAMILIES["h3"][0]}),
"min_ram_gb": H3_MIN_RAM_GB,
+ "min_ram_gb_q8": H3_MIN_RAM_GB_Q8,
+ "dit_choice": (lambda _c: {"kind": _c[0],
+ "q8_pack": str(_c[1]) if _c[1] else None,
+ "q8_available": _h3_q8_dit_dir() is not None,
+ "pref": str(get_settings().get("h3_dit") or "auto")})(h3_dit_choice()),
"ram_gb": round(SYSTEM_RAM_GB, 1),
"root": paths["root"],
"models": paths["models"],
@@ -6181,6 +6835,12 @@ def h3_status() -> dict:
# excluded_modes modes it must NOT serve even though they resolve to a
# `modes` entry (`character` submits t2v but stacks LTX LoRAs;
# `i2v_clean_audio` muxes an external track onto LTX video).
+# lora_tag the compat tag this engine's LoRA picker filters the library
+# by ("video" = LTX, "video:h3" = Hailuo H3). None means the
+# engine takes no LoRAs at all and the picker is hidden for it
+# — which is what an announced-but-unreleased engine wants, and
+# is why the picker's visibility reads this table instead of
+# hard-coding `data-ltx-only` on the markup the way it used to.
# accent/_dim/_soft the three stops of the Phosphene wordmark gradient, one
# engine each, so engines are coloured out of the product's own
# identity instead of a new palette. Used as an active-state
@@ -6205,6 +6865,8 @@ ENGINES: tuple[dict, ...] = (
"excluded_modes": (),
"serves_label": "every mode",
"surfaces": ("video",),
+ # LTX fuses as many LoRAs as you stack, from mlx_models/loras/.
+ "lora_tag": "video",
# LTX's primary strip is #qualityGroup, but its visibility is owned by
# _applyCharacterQualityStripVisibility (it swaps to the character-only
# strip when a character is selected). Leaving `strip` empty tells the
@@ -6229,6 +6891,11 @@ ENGINES: tuple[dict, ...] = (
"excluded_modes": ("character", "i2v_clean_audio"),
"serves_label": "Text and Image",
"surfaces": ("video",),
+ # H3 takes ONE adapter through the same `--lora` flag Turbo rides, out
+ # of its own library (see _h3_loras_dir). The picker is additionally
+ # gated on BOOT.h3.loras.supported, because a pack cloned before
+ # `--lora` landed renders every tier fine and can't take one at all.
+ "lora_tag": "video:h3",
"strip": "h3TierGroup",
"hint": "h3Hint",
# H3's first strip IS a quality picker now (canvas presets in the same
@@ -6262,6 +6929,8 @@ ENGINES: tuple[dict, ...] = (
"excluded_modes": ("character", "i2v_clean_audio"),
"serves_label": "Text and Image",
"surfaces": ("video",),
+ # No weights, so no LoRA ecosystem yet — the picker stays hidden.
+ "lora_tag": None,
"strip": "",
"hint": "",
"strip_label": "Flux tier",
@@ -6367,10 +7036,18 @@ def _engine_css() -> str:
# more pack_state_change at the same moment, and one event per finished job.
# There are NO heartbeats and NO background timers in this module.
-# Empty string = analytics disabled at the source. This constant stays ""
-# in the public tree; the maintainer supplies the real key at runtime via
-# Settings or PHOSPHENE_ANALYTICS_KEY so it is never committed.
-ANALYTICS_KEY_DEFAULT = ""
+# The PostHog PROJECT (ingestion) key. Committed on purpose, and it is safe to:
+# a phc_ project key is WRITE-ONLY — it can send events, it cannot read a single
+# one back, list users, or mutate the project. PostHog documents these as
+# client-side keys meant to ship in public web/app bundles. Phosphene is
+# distributed AS ITS SOURCE (users git-clone via Pinokio), so a key that "stays
+# empty in the public tree" could never reach the fleet — committing it is the
+# only way anonymous fleet counts work at all. The earlier stance here treated a
+# client key like a secret; it isn't. Reading the fleet still requires the
+# separate PERSONAL key (analytics_query_key), which is NOT committed.
+# Empty string would disable analytics at the source (no socket opened);
+# PHOSPHENE_ANALYTICS_KEY still overrides at runtime.
+ANALYTICS_KEY_DEFAULT = "phc_shvL6mr1NB8fmcCqGUtAbpr8d4TgA2ebEIxwoLxeezn"
# PostHog ingestion host (capture). Override for a self-hosted receiver.
ANALYTICS_HOST_DEFAULT = "https://us.i.posthog.com"
# PostHog app host (HogQL query API — different host from ingestion).
@@ -6787,6 +7464,18 @@ def _analytics_boot() -> None:
return
_analytics_disclose_once()
packs = _analytics_pack_state()
+ # app_installed: fired exactly once, the first boot this install ever
+ # reports. Gives a clean "new installs over time" counter and an
+ # install→version funnel, instead of reverse-engineering it from unique
+ # install-ids. The flag is persisted, so a re-boot never re-counts; a
+ # fresh install (new UUID) reports its own app_installed once.
+ if not bool(get_settings().get("analytics_install_reported")):
+ _analytics_capture("app_installed", {
+ "version": _read_local_version() or "unknown",
+ "chip_family": _analytics_chip_family(),
+ "ram_gb": int(round(SYSTEM_RAM_GB)),
+ })
+ _settings_set_internal(analytics_install_reported=True)
_analytics_capture("app_boot", {
"version": _read_local_version() or "unknown",
"os_version": _analytics_os_version(),
@@ -7915,6 +8604,7 @@ def list_outputs(
# read is cheap, but tolerate a missing/corrupt sidecar by leaving
# elapsed_sec null and letting the UI fall back to the file mtime.
elapsed_sec = None
+ clip_sec = None
# Which engine rendered this, and (H3 only) at which tier. Both come
# out of the sidecar read we are ALREADY doing for elapsed_sec, so
# they cost nothing — and they let the stage pane decide synchronously
@@ -7946,6 +8636,17 @@ def list_outputs(
_tier = h3_resolve_tier(_sc_params.get("h3_tier"))
if _tier:
h3_tier = _tier
+ # Clip LENGTH, derived — frames/frame_rate are already in the
+ # sidecar params for both engines, so the card can lead with
+ # what the file IS (a 10 s clip) instead of only how long it
+ # took to make. No ffprobe: 719 files, one stat pass.
+ try:
+ _fr = float(_sc_params.get("frames") or 0)
+ _fps = float(_sc_params.get("frame_rate") or 24.0)
+ if _fr > 0 and _fps > 0:
+ clip_sec = round(_fr / _fps, 2)
+ except Exception:
+ pass
except Exception:
pass
# Y1.039 cache-bust — append the file's mtime as a version param so
@@ -7968,6 +8669,7 @@ def list_outputs(
"mtime": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(mt)),
"size_mb": p.stat().st_size / 1024 / 1024,
"elapsed_sec": elapsed_sec,
+ "clip_sec": clip_sec,
"url": url,
"has_sidecar": has_sidecar,
# Sidecar-derived, cheap (see the read above). `engine` is "h3" on
@@ -9586,6 +10288,19 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,
# or a curl must never reach the worker asking for an adapter this install
# doesn't have).
_h3_turbo = (f("h3_turbo", "") or "").strip().lower() in ("1", "true", "on", "yes")
+ # Which of the runner's ONE adapter slots this render spends. H3's
+ # `--lora` is a single path (`default=None`, not `action="append"` — see
+ # scripts/generate_staged.py), so a user LoRA and Turbo are mutually
+ # exclusive and SOMETHING has to choose. The panel refuses to choose
+ # silently: "turbo" (the default) keeps Turbo and makes a picked LoRA a
+ # hard error naming the conflict; "user" is the explicit opt-out that
+ # spends the slot on the LoRA and turns Turbo off with a line in the log.
+ # Dropping Turbo without being told to is exactly the silent behaviour
+ # this field exists to prevent.
+ _h3_lora_slot = (f("h3_lora_slot", H3_LORA_SLOT_DEFAULT)
+ or H3_LORA_SLOT_DEFAULT).strip().lower()
+ if _h3_lora_slot not in H3_LORA_SLOTS:
+ _h3_lora_slot = H3_LORA_SLOT_DEFAULT
# Per-window prompts for a CHAINED length: a JSON array of strings, one per
# 5 s window, "" meaning "this window uses the main prompt". Read raw here
# and normalised below, AFTER the tier fallback has settled — the window
@@ -9655,6 +10370,10 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,
# Turbo is an H3 sampler mode and means nothing on the LTX lane; a
# fallback to LTX above must not leave the flag set on the job.
_h3_turbo = False
+ # Same for the adapter-slot choice: LTX fuses as many LoRAs as you
+ # stack, so there is no slot to allocate and a leftover "user" here
+ # would only be a confusing field in the sidecar.
+ _h3_lora_slot = H3_LORA_SLOT_DEFAULT
if _h3_turbo and _h3_steps:
# The adapter is distilled FOR 4 sigma points. Honouring a Steps pill on
# top of it would quietly render a configuration nobody validated, so
@@ -9702,6 +10421,12 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,
# this dict — leaving `h3_turbo` out of here is how the control
# would look wired, pass validation, and silently render at 9.
"h3_turbo": _h3_turbo,
+ # Which of H3's ONE adapter slots this render spends: "turbo"
+ # (default) or "user". SAME allowlist trap as every key in this
+ # dict — leave `h3_lora_slot` out and the Turbo-vs-LoRA control
+ # would look wired, post cleanly, and every render would silently
+ # come back on the Turbo branch.
+ "h3_lora_slot": _h3_lora_slot,
# Per-window prompts for a chained length: one entry per 5 s
# window, in render order, "" = "use the main prompt for this
# window". Already clamped to the resolved cell's window count
@@ -9842,6 +10567,19 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,
# and keeps a stale tab from posting an LTX 8k+1 frame count (121) into a
# runner that snaps frames to the 17n+5 grid.
if _engine == "h3":
+ # One adapter slot, and the user asked for it to hold their LoRA:
+ # settle that HERE, before `steps` is stamped, or the queue card (and
+ # the render) would carry Turbo's pinned 4 sigma points on a render
+ # that is not using the 4-step distillation adapter. Announced, never
+ # silent — the whole reason h3_lora_slot is an explicit field.
+ if (_h3_turbo and _h3_lora_slot == "user"
+ and any(_lora_is_h3_lane((e or {}).get("path"))
+ for e in (job["params"].get("loras") or []))):
+ _h3_turbo = False
+ job["params"]["h3_turbo"] = False
+ push("Turbo off: H3's runner has one `--lora` slot and you chose "
+ "to spend it on your LoRA. Rendering at this shape's own "
+ f"{_h3_steps or H3_TIERS[_h3_tier]['steps']} sigma points.")
_tier_cfg = H3_TIERS[_h3_tier]
job["params"]["width"] = _tier_cfg["width"]
job["params"]["height"] = _tier_cfg["height"]
@@ -9963,6 +10701,41 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,
# exact slider value (defaults to 1.0 on the picker).
job["params"].setdefault("character_strength", char_strength)
+ # ---- lane scrub: a LoRA never crosses engines --------------------------
+ # The picker is ONE control shared by both video engines, and its hidden
+ # field survives an engine switch. Client-side it re-serialises on every
+ # switch, but a stale tab, a Load-Params replay of an H3 job onto LTX, or a
+ # hand-rolled POST can still carry the other lane's paths. LTX would then
+ # try to fuse an H3 adapter (fails inside the pipeline) and H3 would be
+ # handed an LTX one (matches zero modules — a SILENT no-op, the worse of
+ # the two). Decide it here, once, on the server, by the directory the file
+ # lives in — the same authority list_h3_user_loras() uses.
+ try:
+ _h3_lora_root = _h3_loras_dir().resolve()
+ except OSError:
+ _h3_lora_root = None
+ if _h3_lora_root is not None:
+ def _lora_lane(entry: dict) -> str:
+ try:
+ rp = Path(str((entry or {}).get("path") or "")).resolve()
+ except (OSError, ValueError):
+ return "ltx"
+ try:
+ return "h3" if rp.is_relative_to(_h3_lora_root) else "ltx"
+ except ValueError:
+ return "ltx"
+ _want_lane = "h3" if job["params"].get("engine") == "h3" else "ltx"
+ _all_loras = list(job["params"].get("loras") or [])
+ _kept = [e for e in _all_loras if _lora_lane(e) == _want_lane]
+ if len(_kept) != len(_all_loras):
+ _dropped = [Path(str(e.get("path") or "")).name or "?"
+ for e in _all_loras if _lora_lane(e) != _want_lane]
+ push(f"Dropped {len(_dropped)} LoRA(s) that belong to the other "
+ f"video engine ({', '.join(_dropped[:4])}"
+ f"{'…' if len(_dropped) > 4 else ''}) — LTX and Hailuo H3 "
+ f"adapters are not interchangeable.")
+ job["params"]["loras"] = _kept
+
_apply_generation_profile_to_job(job)
lora_artifact_neg = _lora_artifact_negative_prompt(job["params"].get("loras") or [])
@@ -11134,11 +11907,107 @@ def run_h3_job_inner(job: dict) -> None:
"Phosphene sidebar to update the clone; your weights "
"stay.")
+ # ---- user LoRA -------------------------------------------------------
+ # Resolved BEFORE Turbo, deliberately: the two compete for the runner's one
+ # `--lora` slot, and Turbo's branch below pins `steps` to 4. Settling the
+ # LoRA first means the Turbo branch can decline to run at all instead of
+ # running and then being unwound, which is how `steps` would end up at 4 on
+ # a render that isn't using the 4-step adapter.
+ #
+ # `loras` is the SAME form field the LTX picker posts — one control, one
+ # wire format. make_job has already scrubbed the other engine's lane out of
+ # it; this re-checks against the directory anyway, because a queued job can
+ # be resumed across a panel restart into a differently-configured H3 root.
+ lora_slot = (str(p.get("h3_lora_slot") or H3_LORA_SLOT_DEFAULT).strip().lower()
+ or H3_LORA_SLOT_DEFAULT)
+ if lora_slot not in H3_LORA_SLOTS:
+ lora_slot = H3_LORA_SLOT_DEFAULT
+ user_lora: Path | None = None
+ user_lora_strength = 1.0
+ _h3_lora_root = _h3_loras_dir()
+ _picked: list[tuple[Path, float]] = []
+ _foreign: list[str] = []
+ for _entry in (p.get("loras") or []):
+ _raw = str((_entry or {}).get("path") or "").strip()
+ if not _raw:
+ continue
+ _lp = Path(_raw)
+ if not _lora_is_h3_lane(_raw):
+ _foreign.append(_lp.name or _raw)
+ continue
+ try:
+ _rp = _lp.resolve()
+ except OSError:
+ _rp = _lp
+ if not _rp.is_file():
+ raise RuntimeError(
+ f"The LoRA {_lp.name} is no longer on disk (expected under "
+ f"{_h3_lora_root}). Re-install it from the CivitAI browser, or "
+ f"un-pick it and render again.")
+ try:
+ _st = float((_entry or {}).get("strength", 1.0))
+ except (TypeError, ValueError):
+ _st = 1.0
+ _picked.append((_rp, max(-2.0, min(2.0, _st))))
+ if _foreign:
+ # Never silent: an LTX LoRA handed to H3's loader matches zero modules
+ # and renders as though no adapter were attached at all.
+ push(f"[h3] ignoring {len(_foreign)} LoRA(s) from the LTX library "
+ f"({', '.join(_foreign[:4])}{'…' if len(_foreign) > 4 else ''}) — "
+ f"H3 can only load adapters trained for MiniMax H3. Install those "
+ f"from the CivitAI browser with the Hailuo H3 filter on.")
+ if _picked:
+ if not h3_supports_lora():
+ raise RuntimeError(
+ "This Hailuo H3 checkout's runner has no `--lora` support "
+ f"({paths['runner']}), so it can't take a LoRA. Re-run 'Install "
+ "Hailuo H3' from the Phosphene sidebar to update the clone — it "
+ "keeps every weight already on disk.")
+ if len(_picked) > H3_LORA_MAX_STACK:
+ raise RuntimeError(
+ f"H3's runner has {H3_LORA_MAX_STACK} adapter slot — `--lora` "
+ f"takes a single path — and {len(_picked)} LoRAs are picked "
+ f"({', '.join(pp.name for pp, _ in _picked)}). Stacking is an "
+ f"LTX capability; on H3, pick one.")
+ user_lora, user_lora_strength = _picked[0]
+ # Layout gate. Idempotent — a file already in bare layout is inspected
+ # and returned untouched; a ComfyUI repack is renamed in place here if
+ # it wasn't already renamed at install time (hand-copied files never
+ # went through the download path); a diffusers-namespace file raises
+ # with the sentence naming the alpha problem.
+ _layout = _h3_lora_prepare(user_lora)
+ p["h3_lora_path"] = str(user_lora)
+ p["h3_lora_strength"] = user_lora_strength
+ p["h3_lora_layout"] = _layout.get("layout")
+
# ---- Turbo: the 4-step distillation LoRA -----------------------------
# make_job already gated this and pinned `steps`, but re-resolve the files
# HERE: the queue can sit for an hour and a job must not reach the runner
# with a --lora path that stopped resolving in the meantime.
turbo = bool(p.get("h3_turbo"))
+ if turbo and user_lora is not None:
+ # ONE slot, two claimants. Both outcomes are stated out loud; neither
+ # is chosen for the user behind their back.
+ if lora_slot == "user":
+ turbo = False
+ p["h3_turbo"] = False
+ # make_job normally settles this before it stamps `steps`, so this
+ # branch only fires for a job queued by an older build or replayed
+ # from a sidecar. Give the step count back: `steps` is 4 right now
+ # because Turbo pinned it, and 4 sigma points without the 4-step
+ # adapter is a visibly under-denoised clip.
+ steps = int(p.get("h3_steps") or tier["steps"])
+ push(f"[h3] Turbo OFF for this render — you chose to spend the "
+ f"adapter slot on {user_lora.name}. {H3_LORA_STACK_NOTE} "
+ f"Rendering at this shape's own {steps} sigma points "
+ f"({steps - 1} forwards).")
+ else:
+ raise RuntimeError(
+ f"Turbo and the LoRA {user_lora.name} both want H3's single "
+ f"adapter slot — its runner's `--lora` takes one path, so they "
+ f"cannot both run. Turn Turbo off, or switch the LoRA control "
+ f"to 'Use my LoRA' to spend the slot on it instead (that drops "
+ f"Turbo and renders at this shape's own step count).")
turbo_paths: dict = {}
if turbo:
if not h3_supports_lora():
@@ -11230,8 +12099,10 @@ def run_h3_job_inner(job: dict) -> None:
# else about the argv is identical.
if chain_prompts_path is None:
cmd.append(prompt)
+ _dit_kind, _dit_q8 = h3_dit_choice()
+ _dit_path = _dit_q8 if (_dit_kind == "q8" and _dit_q8 is not None) else paths["dit"]
cmd += [
- "--dit", str(paths["dit"]),
+ "--dit", str(_dit_path),
"--compact-root", str(paths["compact_root"]),
"--text-config", str(paths["text_config"]),
"-o", str(out_path),
@@ -11255,12 +12126,54 @@ def run_h3_job_inner(job: dict) -> None:
cmd += ["--chain-prompts", str(chain_prompts_path)]
if first_frame is not None:
cmd += ["--first-frame", str(first_frame)]
+ # ---- Fast draft decode (TAE) --------------------------------------------
+ # H3's video decoder is a 36-layer ViT and it is the single largest FIXED
+ # cost in a render: 88 s of a 501 s clip, 77% of everything that is not
+ # denoising. madebyollin's TAE replaces it for DRAFTS only and takes a
+ # 640x384 5 s draft from ~5 min to ~66 s end to end.
+ #
+ # Gated three ways, deliberately: the tier must be a Draft (the quality
+ # whose own blurb already says faces and fine detail resolve at Standard
+ # and High), the installed runner must carry the flag, and the weight must
+ # be on disk. Any one missing and the render takes the untouched full-VAE
+ # path — which is also the ONLY path a non-Draft tier can take, so no
+ # delivery render can silently pick up a draft decoder.
+ tae_used = False
+ if tier.get("draft") and h3_supports_tae_draft():
+ _tae = h3_tae_checkpoint()
+ if _tae is not None:
+ cmd += ["--draft-decode", "tae", "--tae-checkpoint", str(_tae)]
+ tae_used = True
+ # Cache the draft's clean Stage-A latents beside the clip. This is what a
+ # LATER hires-refine pass consumes to sharpen THIS take at a higher canvas
+ # — the owner's actual expectation of "Finish", which today re-renders a
+ # different take (same seed on a different canvas is a different noise
+ # tensor). Runner refuses the flag on chained renders, so gate to one
+ # window; the cache is a few hundred MB and rides the output's lifecycle.
+ stage_a_path = None
+ if tier.get("draft") and chain_windows == 1 and h3_supports_stage_a():
+ stage_a_path = out_path.with_suffix(".stage_a")
+ cmd += ["--save-stage-a", str(stage_a_path)]
if turbo:
# `--lora-adaln` carries the recovered time embedder, which lets the
# runner apply the adapter's 51 adaLN modules too. They fold into the
# precomputed modulation cache, so they cost nothing per forward.
cmd += ["--lora", str(turbo_paths["lora"]),
"--lora-adaln", str(turbo_paths["embedder"])]
+ elif user_lora is not None:
+ # The SAME flag Turbo rides — one slot, and this render spent it here.
+ # `PATH:SCALE` is the runner's own spelling (lora.parse_spec), and the
+ # scale is the picker's strength: 1.0 means "as trained" for a
+ # 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).
+ #
+ # No `--lora-adaln` here on purpose: that flag applies TURBO's adaLN
+ # modules using the recovered upstream time embedder, and it is
+ # meaningful only for an adapter that HAS adaLN pairs trained against
+ # the 2688-d timestep MLP this pruned checkpoint dropped. A community
+ # LoRA's attention/MLP pairs apply without it.
+ cmd += ["--lora", f"{user_lora}:{user_lora_strength:g}"]
env = os.environ.copy()
# The runner pipes raw RGB into `ffmpeg` from PATH (minimax_h3_mlx.media);
@@ -11270,7 +12183,11 @@ def run_h3_job_inner(job: dict) -> None:
push(f"[h3] {tier['label']} · {width}×{height} · {frames}f · "
f"{steps} sigma points ({steps - 1} forwards) · seed {seed}"
+ + (" · Q8 DiT (low-RAM)" if _dit_kind == "q8" else "")
+ (" · Turbo (4-step distill LoRA)" if turbo else "")
+ + (f" · LoRA {user_lora.name} @ {user_lora_strength:g}"
+ if (user_lora is not None and not turbo) else "")
+ + (" · fast draft decode (TAE)" if tae_used else "")
+ (f" · {chain_windows} chained windows of {window_frames}f"
if chain_windows > 1 else "")
+ (" · per-window prompts" if chain_prompts else "")
@@ -11538,6 +12455,13 @@ def run_h3_job_inner(job: dict) -> None:
},
"command": "hailuo_h3",
"engine": "h3",
+ # Where this draft's clean Stage-A latents live, if the render cached
+ # them — the input a hires-refine pass needs to sharpen THIS take at a
+ # higher canvas instead of re-rolling a new one. null on non-drafts,
+ # chained renders, and runners without --save-stage-a.
+ "stage_a_cache": (str(stage_a_path)
+ if (stage_a_path is not None and stage_a_path.exists())
+ else None),
"started": job.get("started_at"),
"elapsed_sec": elapsed,
"video_duration_sec": round(max(0.0, frames / H3_FPS), 3),
@@ -14608,17 +15532,38 @@ class Handler(BaseHTTPRequestHandler):
# sidecar). The Manual-tab style picker passes this so the
# Characters picker is the only surface where face+audio LoRAs
# live — no confusing duplicates in two pickers at once.
+ #
+ # Two LIBRARIES are returned as one list (2026-08-09): the panel's
+ # own mlx_models/loras/ tree and the Hailuo pack's loras/ dir, each
+ # entry tagged `lane`. The browser fetches this endpoint ONCE with
+ # no filter and re-filters client-side on every mode/engine flip,
+ # so both lanes have to be present in that one payload or an engine
+ # switch would need a round-trip to show anything.
qs = parse_qs(parsed.query)
mode_filter = (qs.get("mode", [""])[0] or "").strip().lower()
exclude_characters_raw = (qs.get("exclude_characters", [""])[0] or "").strip().lower()
exclude_characters = exclude_characters_raw in ("1", "true", "yes", "on")
- user_loras = list_user_loras()
+ try:
+ h3_user_loras = list_h3_user_loras()
+ except Exception:
+ h3_user_loras = []
+ user_loras = list_user_loras() + h3_user_loras
if mode_filter:
- user_loras = [
- l for l in user_loras
- if mode_filter in (l.get("compatible_modes") or [])
- or "unknown" in (l.get("compatible_modes") or [])
- ]
+ # The lane is checked BEFORE compatible_modes, and the
+ # "unknown" wildcard is deliberately NOT honoured across lanes.
+ # An untagged .safetensors in mlx_models/loras/ classifies as
+ # ["unknown"], which is permissive by design — but permissive
+ # must not mean "offer it to an engine that cannot load it".
+ # The directory a file was found in is the authority here.
+ if mode_filter == "video:h3":
+ user_loras = [l for l in user_loras if l.get("lane") == "h3"]
+ else:
+ user_loras = [
+ l for l in user_loras
+ if l.get("lane") != "h3"
+ and (mode_filter in (l.get("compatible_modes") or [])
+ or "unknown" in (l.get("compatible_modes") or []))
+ ]
if exclude_characters:
blocked_names = _character_lora_basenames()
user_loras = [
@@ -14634,6 +15579,15 @@ class Handler(BaseHTTPRequestHandler):
"user": user_loras,
"curated": curated,
"loras_dir": str(_safe_loras_dir()),
+ # The H3 lane's directory + its gate. `h3_lora_supported` is
+ # whether the INSTALLED runner takes `--lora` at all — an older
+ # H3 pack renders every tier fine and can't take an adapter, so
+ # the picker must not be offered on that install. Reported here
+ # (not just in /status) so the CivitAI modal can name the right
+ # install path without a second round-trip.
+ "h3_loras_dir": str(_h3_loras_dir()),
+ "h3_lora_supported": h3_supports_lora(),
+ "h3_lora_max_stack": H3_LORA_MAX_STACK,
# Echo back so the JS picker can verify the server filtered
# by the mode it asked for (vs back-compat unfiltered).
"mode_filter": mode_filter or None,
@@ -14965,9 +15919,11 @@ class Handler(BaseHTTPRequestHandler):
context = (qs.get("context", ["video"])[0] or "video").lower()
if context not in _CIVITAI_BASE_MODELS_BY_CONTEXT:
context = "video"
- # Optional `family` narrows the image context to one engine
- # family (e.g. "qwen" or "hidream"). Empty / "all" leaves the
- # full image list active. Ignored when context != "image".
+ # Optional `family` narrows a context to one engine family —
+ # "ltx" / "h3" on video, "qwen" / "hidream" on image. Empty /
+ # "all" leaves the whole context list active. An unknown value
+ # is ignored by _civitai_search rather than erroring, so a stale
+ # tab degrades to "All" instead of to a 400.
family = (qs.get("family", [""])[0] or "").lower()
try:
results = _civitai_search(query=query, nsfw=nsfw,
@@ -14976,10 +15932,13 @@ class Handler(BaseHTTPRequestHandler):
results["context"] = context
results["family"] = family or "all"
# Echo the family list so the client can render pills
- # without hardcoding the catalog. Only meaningful for
- # context=image.
- if context == "image":
- results["available_families"] = list(_CIVITAI_IMAGE_FAMILIES.keys())
+ # without hardcoding the catalog. Every context that HAS
+ # families gets them — video grew a pair (ltx / h3) when the
+ # H3 engine learned to take LoRAs, and the client renders
+ # both surfaces from this one echo.
+ _fams = _CIVITAI_FAMILIES_BY_CONTEXT.get(context) or {}
+ if _fams:
+ results["available_families"] = list(_fams.keys())
self._json(results)
except Exception as exc:
self._json({"error": f"civitai search failed: {exc}",
@@ -26019,6 +26978,15 @@ HTML = r"""<!doctype html>
<input type="hidden" name="h3_upscale" id="h3_upscale" value="fit_720p">
<input type="hidden" name="h3_steps" id="h3_steps" value="auto">
<input type="hidden" name="h3_turbo" id="h3_turbo" value="0">
+ <!-- Which of H3's ONE adapter slots this render spends. Its runner's
+ `--lora` takes a single path (default=None, not append), so Turbo
+ and a picked LoRA cannot both run and something has to choose.
+ "turbo" (default) keeps Turbo and makes a picked LoRA a hard,
+ named error; "user" is the explicit opt-out. In the make_job
+ allowlist — a field that isn't listed there silently no-ops on
+ /queue/add, which here would mean every render quietly coming back
+ on the Turbo branch with the control looking wired. -->
+ <input type="hidden" name="h3_lora_slot" id="h3_lora_slot" value="turbo">
<!-- Per-window prompts for a chained length, posted as ONE field: a
JSON array of strings, one entry per 5 s window, in render order.
One field rather than h3_chain_prompt_1..N because the window count
@@ -26250,6 +27218,31 @@ HTML = r"""<!doctype html>
<div class="h3-turbo-note" id="h3TurboNote" hidden></div>
</div>
+ <!-- Adapter slot. Appears ONLY when the conflict is real — Turbo
+ selected AND a LoRA picked — because H3's runner has exactly
+ one `--lora` and there is nothing to decide until both want
+ it. Rendered by renderH3LoraSlot() from BOOT.h3.loras so the
+ sentence explaining the constraint comes from Python, next to
+ the constant that encodes it. The alternative (silently
+ preferring one) is the failure this control exists to
+ prevent: a render that quietly ignored the LoRA you picked,
+ or quietly dropped the Turbo you asked for. -->
+ <div class="cz-control" id="h3LoraSlotRow" data-h3-only hidden>
+ <div class="cz-label">Adapter
+ <span class="cz-label-hint">one slot · Turbo or your LoRA</span>
+ </div>
+ <div class="pill-group cols-2" id="h3LoraSlotGroup">
+ <button type="button" class="pill-btn active" data-h3-lora-slot="turbo"
+ title="Spend the slot on Turbo. Your picked LoRA won't render — the job stops and says so rather than silently dropping it.">
+ <span>Turbo</span>
+ </button>
+ <button type="button" class="pill-btn" data-h3-lora-slot="user" id="h3LoraSlotUserPill">
+ <span>My LoRA</span><span class="sub" id="h3LoraSlotUserSub"></span>
+ </button>
+ </div>
+ <div class="h3-turbo-note" id="h3LoraSlotNote"></div>
+ </div>
+
<!-- H3 sampler depth. Every cell bakes 9 steps (8 forwards per
window) — the validated speed/quality point; the official
reference recipe runs 20. Four honest pills beat an unbounded
@@ -26318,7 +27311,7 @@ HTML = r"""<!doctype html>
<div class="mini-fields">
<div class="mf-cell" data-ltx-only>
<span class="mf-label">Duration (s)</span>
- <input id="duration" value="5" type="number" min="1" max="20" step="1">
+ <input id="duration" value="5" type="number" min="1" max="20" step="any">
</div>
<div class="mf-cell" data-ltx-only>
<span class="mf-label">Frames <span class="mf-hint">8k+1</span></span>
@@ -26357,7 +27350,13 @@ HTML = r"""<!doctype html>
it easy to forget. Default open so first-time users see what's
inside without hunting for the disclosure triangle. -->
<div class="form-divider"></div>
- <div id="loraPickerVideoSlot" data-ltx-only>
+ <!-- NOT `data-ltx-only` any more (2026-08-09): H3 takes LoRAs too, out
+ of its own library, so the picker is shared and its visibility is
+ decided by _syncLoraPickerForEngine() from the ENGINES table's
+ `lora_tag` plus the H3 runner probe. A CSS fold rule can express
+ "one engine" but not "any engine whose installed pack has --lora",
+ which is the actual condition. -->
+ <div id="loraPickerVideoSlot">
<details id="lorasDetails" open class="loras-section">
<summary class="loras-summary">
<span class="loras-chevron" aria-hidden="true"><svg class="ph"><use href="#ph-caret-down-bold"/></svg></span>
@@ -33963,6 +34962,9 @@ function setH3Turbo(on) {
if (s) s.value = t.steps || 4;
}
_h3SyncStepsEnabled();
+ // Turbo is one half of the single-adapter-slot conflict, so the Adapter row
+ // appears / disappears with it.
+ if (typeof renderH3LoraSlot === 'function') { try { renderH3LoraSlot(); } catch (e) {} }
try { localStorage.setItem('phos_h3_turbo', v); } catch (e) {}
// Turbo roughly halves every cell, so the chips have to re-price — a strip
// still advertising the 9-step wall clock while Turbo is lit is the same lie
@@ -34011,6 +35013,12 @@ document.querySelectorAll('#h3TurboGroup [data-h3-turbo]').forEach(b => {
b.onclick = () => (b.dataset.h3Turbo === '1') ? h3TurboClick() : setH3Turbo(false);
});
+// Adapter-slot pills. Bound at parse time like the Turbo / Steps groups —
+// the row itself is hidden until Turbo and a LoRA actually collide.
+document.querySelectorAll('#h3LoraSlotGroup [data-h3-lora-slot]').forEach(b => {
+ b.onclick = () => setH3LoraSlot(b.dataset.h3LoraSlot);
+});
+
// The switcher earns its place only when there is a real choice to make: at
// least two ACTIONABLE engines on the current workflow. One engine means the
// control and its divider both disappear — which is exactly what the ~80% of
@@ -34926,6 +35934,12 @@ function setEngine(engine, opts) {
try { updatePromptPlaceholder(); } catch (e) {}
}
try { _syncEnginePromptTools(); } catch (e) {}
+ // The LoRA picker is SHARED by the video engines and each has its own
+ // library, so an engine switch re-points it, re-filters it and re-serializes
+ // the hidden field (the lane guard). Last, after the surface swap, so it
+ // reads the engine this call actually settled on rather than the one that
+ // was requested — a gate may have bounced it back to the built-in.
+ try { _syncLoraPickerForEngine(); } catch (e) {}
return target;
}
@@ -36754,7 +37768,17 @@ function animateFromPhoto(payload) {
// pre-date the elapsed_sec field, or outputs whose sidecar got
// deleted) so the slot is never empty.
function _outputDurationLabel(o) {
+ // Lead with what the file IS (its length), then how long it took, labeled.
+ // "1 h 20 m" alone on a 10-second clip read as a broken duration
+ // (Mr Bizarro 2026-08-10: "preview is not accurate") — same confusion as
+ // the 2026-05-21 mtime incident, opposite direction. Numbers get names.
+ const clip = (o && typeof o.clip_sec === 'number' && o.clip_sec > 0)
+ ? (o.clip_sec >= 60 ? `${Math.floor(o.clip_sec / 60)}m ${Math.round(o.clip_sec % 60)}s clip`
+ : `${Math.round(o.clip_sec)}s clip`)
+ : null;
const s = (o && typeof o.elapsed_sec === 'number') ? o.elapsed_sec : null;
+ if (clip && s != null) return `${clip} · ${_fmtRenderTime(s)}`;
+ if (clip) return clip;
if (s == null) {
// No render-elapsed in sidecar — show a relative timestamp instead
// of HH:MM, which looked like a render duration and was confusing
@@ -36764,9 +37788,13 @@ function _outputDurationLabel(o) {
return (o && o.mtime && typeof _relTimeFromMtime === 'function')
? _relTimeFromMtime(o.mtime) : '—';
}
- if (s < 60) return `${Math.round(s)} s`;
- if (s < 3600) return `${Math.floor(s / 60)} m ${Math.round(s % 60)} s`;
- return `${Math.floor(s / 3600)} h ${Math.round((s % 3600) / 60)} m`;
+ return _fmtRenderTime(s);
+}
+
+function _fmtRenderTime(s) {
+ if (s < 60) return `rendered ${Math.round(s)} s`;
+ if (s < 3600) return `rendered ${Math.floor(s / 60)} m ${Math.round(s % 60)} s`;
+ return `rendered ${Math.floor(s / 3600)} h ${Math.round((s % 3600) / 60)} m`;
}
function renderCarousel() {
@@ -39277,7 +40305,14 @@ function _currentLoraModeFilter() {
// works.
const mode = (currentMode || document.getElementById('mode')?.value || 't2v');
if (mode !== 'image') {
- // All video modes share the LTX lane.
+ // Video modes are no longer one lane: LTX and Hailuo H3 have separate
+ // libraries in separate directories, and neither can load the other's
+ // adapters. The tag comes off the ENGINES table (`lora_tag`) so a third
+ // video engine is one registry entry, not another branch here.
+ try {
+ const e = (typeof engineById === 'function') ? engineById(currentEngine()) : null;
+ if (e && e.lora_tag) return e.lora_tag;
+ } catch (_) { /* fall through to the built-in lane */ }
return 'video';
}
// Image Studio: read the engine override + map to compat tag.
@@ -39314,6 +40349,7 @@ function _currentLoraModeFilter() {
function _loraFilterLabel(tag) {
switch (tag) {
case 'video': return 'LTX-Video LoRAs (active video mode)';
+ case 'video:h3': return 'Hailuo H3 LoRAs (MiniMax H3 base — separate library)';
case 'image': return 'image LoRAs (any mflux family — auto engine)';
case 'image:qwen': return 'Qwen-Image / Qwen-Image-Edit LoRAs';
case 'image:ideogram': return 'Ideogram 4 LoRAs (community formats — none validated yet)';
@@ -39327,12 +40363,132 @@ function _loraFilterLabel(tag) {
}
}
+// Which LoRA library directory the picker is currently pointed at. Filled by
+// refreshLoras() from /loras — one fetch carries both, so flipping engine
+// re-labels the empty state without a round-trip.
+let _lorasDirs = { ltx: 'mlx_models/loras/', h3: '' };
+// Whether the INSTALLED H3 pack's runner takes `--lora` at all. An older
+// checkout renders every tier and cannot take an adapter, and offering the
+// picker there would be a lie the user only discovers 30 s into a render.
+let _h3LoraSupported = false;
+
+// Show / hide the shared LoRA picker for the ACTIVE engine, and re-point its
+// "drop files here" line at that engine's directory.
+//
+// This used to be a CSS fold (`data-ltx-only` on #loraPickerVideoSlot). A fold
+// rule can say "one engine"; it cannot say "any engine whose lora_tag is set
+// AND, if that engine is H3, whose installed pack has --lora" — which is the
+// real condition. So the markup lost its attribute and the decision moved
+// here, reading the same ENGINES table the rest of the engine surface does.
+function _syncLoraPickerForEngine() {
+ const slot = document.getElementById('loraPickerVideoSlot');
+ if (!slot) return;
+ let e = null;
+ try { e = (typeof engineById === 'function') ? engineById(currentEngine()) : null; }
+ catch (_) { e = null; }
+ const tag = e ? e.lora_tag : 'video';
+ let show = !!tag;
+ if (show && e && e.id === 'h3') {
+ // BOOT.h3.loras.supported is refreshed on every /status tick, so updating
+ // an old pack unlocks the picker without a panel restart — the same
+ // contract Turbo's download already has.
+ show = !!((H3 && H3.loras && H3.loras.supported) || _h3LoraSupported);
+ }
+ slot.hidden = !show;
+ slot.style.display = show ? '' : 'none';
+ const dirEl = document.getElementById('lorasDir');
+ if (dirEl) {
+ dirEl.textContent = (tag === 'video:h3')
+ ? (_lorasDirs.h3 || 'the Hailuo H3 pack’s loras/ folder')
+ : (_lorasDirs.ltx || 'mlx_models/loras/');
+ }
+ if (typeof renderLorasList === 'function') { try { renderLorasList(); } catch (_) {} }
+ // Re-serialize: the lane guard in _serializeLoras is what keeps the other
+ // engine's chips off the wire, and it has to re-run when the lane changes.
+ if (typeof _serializeLoras === 'function') { try { _serializeLoras(); } catch (_) {} }
+ if (typeof renderH3LoraSlot === 'function') { try { renderH3LoraSlot(); } catch (_) {} }
+}
+
+// The H3-lane LoRA (at most one) currently picked, as a picker row — or null.
+function _h3ActiveUserLora() {
+ if (!Array.isArray(_activeLoras)) return null;
+ for (const a of _activeLoras) {
+ const u = Array.isArray(_knownUserLoras)
+ ? _knownUserLoras.find(x => x.path === a.path) : null;
+ if (u && u.lane === 'h3') return Object.assign({}, u, { strength: a.strength });
+ }
+ return null;
+}
+
+// Adapter-slot control. Only rendered when the conflict is REAL — Turbo
+// selected AND an H3 LoRA picked — because H3's runner has one `--lora` and
+// there is nothing to choose until both want it. The copy comes from
+// BOOT.h3.loras.note so the sentence lives next to the constant that encodes
+// the constraint.
+function renderH3LoraSlot() {
+ const row = document.getElementById('h3LoraSlotRow');
+ if (!row) return;
+ const lora = _h3ActiveUserLora();
+ const turboOn = (document.getElementById('h3_turbo') || {}).value === '1';
+ const onH3 = (typeof currentEngine === 'function') && currentEngine() === 'h3';
+ const conflict = !!(onH3 && lora && turboOn);
+ row.hidden = !conflict;
+ if (!conflict) {
+ // No conflict = no choice to remember. Reset so a later render can't
+ // inherit a stale "user" from a LoRA the user has since un-picked.
+ const inp = document.getElementById('h3_lora_slot');
+ if (inp) inp.value = 'turbo';
+ document.querySelectorAll('#h3LoraSlotGroup .pill-btn').forEach(b =>
+ b.classList.toggle('active', b.dataset.h3LoraSlot === 'turbo'));
+ return;
+ }
+ const sub = document.getElementById('h3LoraSlotUserSub');
+ if (sub) sub.textContent = lora.name || lora.filename || '';
+ const note = document.getElementById('h3LoraSlotNote');
+ if (note) {
+ note.textContent = ((H3 && H3.loras && H3.loras.note) ||
+ "H3's runner has one adapter slot, so a LoRA and Turbo can't both run.")
+ + ' Choosing your LoRA turns Turbo off and renders at this shape’s own step count.';
+ }
+ const cur = (document.getElementById('h3_lora_slot') || {}).value || 'turbo';
+ document.querySelectorAll('#h3LoraSlotGroup .pill-btn').forEach(b =>
+ b.classList.toggle('active', b.dataset.h3LoraSlot === cur));
+}
+
+function setH3LoraSlot(slot) {
+ const v = (slot === 'user') ? 'user' : 'turbo';
+ const inp = document.getElementById('h3_lora_slot');
+ if (inp) inp.value = v;
+ document.querySelectorAll('#h3LoraSlotGroup .pill-btn').forEach(b =>
+ b.classList.toggle('active', b.dataset.h3LoraSlot === v));
+ renderH3LoraSlot();
+}
+
function _serializeLoras() {
// What the helper actually needs is path + strength. Keep the rest in
// the in-memory list for UI rendering, drop it on the wire. Summary
// count is updated by renderLorasList() which has fuller state — we
// don't touch it here to avoid two functions stomping each other.
- const slim = _activeLoras.map(l => ({ path: l.path, strength: l.strength }));
+ //
+ // Lane guard (2026-08-09): _activeLoras SURVIVES an engine switch on
+ // purpose — flipping LTX → H3 → LTX must not silently unpick the user's
+ // chips. But the hidden field is what gets POSTed, so anything from the
+ // other video engine's library has to be withheld from THIS submit or an
+ // LTX render would be handed an H3 adapter (and vice versa). The server
+ // scrubs the same way in make_job; this copy keeps the UI's own summary and
+ // the wire in agreement instead of relying on a correction it can't see.
+ const _tag = (typeof _currentLoraModeFilter === 'function')
+ ? _currentLoraModeFilter() : '';
+ const _laneOf = (p) => {
+ const u = Array.isArray(_knownUserLoras)
+ ? _knownUserLoras.find(x => x.path === p) : null;
+ return (u && u.lane) || 'ltx';
+ };
+ const _inLane = (l) => (_tag === 'video:h3')
+ ? _laneOf(l.path) === 'h3'
+ : _laneOf(l.path) !== 'h3';
+ const slim = _activeLoras.filter(_inLane)
+ .map(l => ({ path: l.path, strength: l.strength }));
document.getElementById('lorasJson').value = JSON.stringify(slim);
// Train-Character LoRAs are trained against the dev transformer (HQ
// path) — Quick/Standard run the distilled model at 8 steps, which is
@@ -39341,6 +40497,9 @@ function _serializeLoras() {
// output. Disable those chips when any trained LoRA is attached so
// the wrong-path landing becomes visible.
try { updateQualityChipsForLora(); } catch (_) {}
+ // Picking (or un-picking) an H3 LoRA is the other half of the
+ // single-adapter-slot conflict, so the Adapter row follows the selection.
+ if (typeof renderH3LoraSlot === 'function') { try { renderH3LoraSlot(); } catch (_) {} }
}
function updateQualityChipsForLora() {
@@ -39478,11 +40637,23 @@ async function refreshLoras() {
} catch (e) {
return;
}
+ // One list, BOTH video libraries, each row carrying `lane`. The client
+ // filters per engine (renderLorasList) so an engine switch costs no
+ // round-trip — the same reason this fetch has never sent a mode filter.
_knownUserLoras = data.user || [];
- // Update displayed loras dir
- if (data.loras_dir) {
+ if (data.loras_dir) _lorasDirs.ltx = data.loras_dir;
+ if (data.h3_loras_dir) _lorasDirs.h3 = data.h3_loras_dir;
+ _h3LoraSupported = !!data.h3_lora_supported;
+ // Update displayed loras dir — whichever library the ACTIVE engine reads.
+ {
const dirEl = document.getElementById('lorasDir');
- if (dirEl) dirEl.textContent = data.loras_dir;
+ const tag = (typeof _currentLoraModeFilter === 'function')
+ ? _currentLoraModeFilter() : 'video';
+ if (dirEl) {
+ dirEl.textContent = (tag === 'video:h3')
+ ? (_lorasDirs.h3 || 'the Hailuo H3 pack’s loras/ folder')
+ : (_lorasDirs.ltx || 'mlx_models/loras/');
+ }
}
// Backfill compatible_modes on any active LoRA whose entry we now
// have full metadata for — addLoraToActive() may have stored a sparse
@@ -39501,6 +40672,10 @@ async function refreshLoras() {
knownPaths.has(l.path) || l.path.includes('/')); // keep HF ids (no dir slash)
renderLorasList();
_serializeLoras();
+ // The picker's own visibility depends on the H3 gate we just refreshed.
+ if (typeof _syncLoraPickerForEngine === 'function') {
+ try { _syncLoraPickerForEngine(); } catch (_) {}
+ }
// Refill the Ingredients-mode character dropdown from the same library
// (kind=train_character). Runs here so a newly-trained character appears
// the moment /loras is re-fetched after training.
@@ -39534,6 +40709,14 @@ function renderLorasList() {
filename: ul.filename,
civitai_url: ul.civitai_url,
compatible_modes: ul.compatible_modes || ['unknown'],
+ // Which engine DIRECTORY this file came from. Checked before
+ // compatible_modes in the filter below, because 'unknown' is
+ // deliberately permissive and must not be permissive ACROSS engines.
+ lane: ul.lane || 'ltx',
+ // H3 lane only: 'bare' / 'comfyui' load, 'diffusers' / 'kohya' don't.
+ layout: ul.layout || null,
+ layout_ok: (ul.layout_ok === undefined) ? true : !!ul.layout_ok,
+ layout_reason: ul.layout_reason || '',
active: !!active,
strength: active ? active.strength : (ul.recommended_strength || 1.0),
// 'user' = downloaded/installed (CivitAI or manual);
@@ -39553,6 +40736,10 @@ function renderLorasList() {
filename: null,
civitai_url: null,
compatible_modes: a.compatible_modes || ['unknown'],
+ lane: a.lane || 'ltx',
+ layout: null,
+ layout_ok: true,
+ layout_reason: '',
active: true,
strength: a.strength,
kind: 'remote',
@@ -39615,9 +40802,18 @@ function renderLorasList() {
if (tags.includes('unknown') && !_looksVideoOnly(r)) return true;
return false;
}
- // Video lane stays permissive (video + unknown both match)
- // since LTX is the only video family — there's no risk of
- // family leakage on the video side.
+ // ---- Video lanes: LTX and Hailuo H3, by DIRECTORY -----------------
+ // 2026-08-09: the video side stopped being one family the moment H3
+ // learned to take LoRAs, and the two are not interchangeable in
+ // either direction — an LTX adapter handed to H3's loader matches
+ // zero modules (silent no-op), an H3 one handed to LTX fails inside
+ // the fuser. The 'unknown' escape hatch above is what makes this a
+ // lane check rather than a tag check: a sidecar-less .safetensors
+ // dropped into mlx_models/loras/ classifies as 'unknown' and would
+ // otherwise surface in the H3 picker, which is the exact
+ // cross-gallery leakage the image split was built to stop.
+ if (modeTag === 'video:h3') return r.lane === 'h3';
+ if (r.lane === 'h3') return false;
return tags.includes(modeTag) || tags.includes('unknown');
};
rows = allRows.filter(r => {
@@ -39700,6 +40896,15 @@ function renderLorasList() {
<div style="margin-bottom:4px;color:var(--fg);"><strong>No video LoRAs in your library.</strong></div>
<div>Install an LTX-Video LoRA via the <strong>Browse CivitAI</strong> button above (filter base model to LTX 2.3), or train one in the <strong>Train Character</strong> tab.</div>
</div>`;
+ } else if (modeTag === 'video:h3') {
+ // Its own empty state, not the LTX one: the two libraries are separate
+ // directories and the CivitAI filter to reach for is a different pill.
+ wrap.innerHTML = `
+ <div class="hint" style="padding:14px 8px;text-align:center;line-height:1.6;">
+ <div style="margin-bottom:4px;color:var(--fg);"><strong>No Hailuo H3 LoRAs in your library.</strong></div>
+ <div>H3 has its own library — your LTX LoRAs can't load here, and H3's can't load on LTX.</div>
+ <div style="margin-top:6px;">Install one via <strong>Browse CivitAI</strong> above (the <strong>Hailuo H3</strong> pill), and it lands in <code>${escapeHtml(_lorasDirs.h3 || 'the H3 pack’s loras/ folder')}</code>.</div>
+ </div>`;
} else {
wrap.innerHTML = `<div class="hint" style="padding:8px 0;">No LoRAs available.</div>`;
}
@@ -39736,6 +40941,13 @@ function loraRowHtml(r, modeTag) {
if (familyMismatch) {
familyBadges.push(`<span class="badge" style="background:rgba(232,179,65,0.15);color:var(--warn,#e8b341)" title="This LoRA was trained for a different family (${tags.join(', ')}) — it will be passed to mflux but probably won't influence the output. Switch the Engine dropdown to a matching family, or remove this LoRA."><svg class="ph" aria-hidden="true"><use href="#ph-warning-fill"/></svg></span>`);
}
+ // H3 lane: a file whose KEY LAYOUT the runner can't read (diffusers /
+ // kohya). Shown rather than hidden, with the reason on the badge, because
+ // "my LoRA vanished" is a worse bug report than "my LoRA says why it can't
+ // run" — and the reason is the actionable half (it names the conversion).
+ if (r.layout_ok === false) {
+ familyBadges.push(`<span class="badge" style="background:rgba(248,81,73,0.15);color:var(--danger,#f85149)" title="${escapeHtml(r.layout_reason || 'This LoRA is in a key layout the H3 runner cannot read.')}"><svg class="ph" aria-hidden="true"><use href="#ph-warning-fill"/></svg></span>`);
+ }
// Trigger summary line under the name (when not expanded). Truncated.
const trigs = r.trigger_words || [];
const trigSummary = trigs.length
@@ -40526,7 +41738,18 @@ function _civitaiContextForCurrentWorkflow() {
return 'video';
}
-function _civitaiContextMeta(ctx) {
+// The video context's family pill IS the lane selector — the two video
+// engines cannot load each other's adapters — so it is preselected from the
+// engine the user is actually on rather than defaulting to "All". Net effect
+// for an LTX user: the modal opens showing exactly what it always showed.
+function _civitaiFamilyForCurrentEngine() {
+ if (_civitaiContext !== 'video') return '';
+ try {
+ return (currentEngine() === 'h3') ? 'h3' : 'ltx';
+ } catch (_) { return 'ltx'; }
+}
+
+function _civitaiContextMeta(ctx, fam) {
if (ctx === 'image') {
return {
title: 'Browse CivitAI for image LoRAs',
@@ -40534,31 +41757,51 @@ function _civitaiContextMeta(ctx) {
empty: 'No image LoRAs match',
};
}
+ if (fam === 'h3') {
+ return {
+ title: 'Browse CivitAI for Hailuo H3 LoRAs',
+ hint: 'MiniMax H3.',
+ empty: 'No MiniMax H3 LoRAs match',
+ };
+ }
+ if (fam === 'ltx') {
+ return {
+ title: 'Browse CivitAI for LTX 2.3 LoRAs',
+ hint: 'LTX-Video 2.3.',
+ empty: 'No LTX 2.3 LoRAs match',
+ };
+ }
return {
- title: 'Browse CivitAI for LTX 2.3 LoRAs',
- hint: 'LTX-Video 2.3.',
- empty: 'No LTX 2.3 LoRAs match',
+ title: 'Browse CivitAI for video LoRAs',
+ hint: 'LTX-Video 2.3 and MiniMax H3.',
+ empty: 'No video LoRAs match',
};
}
function openCivitaiModal(context) {
// Pick context from the active workflow if not explicitly passed.
_civitaiContext = context || _civitaiContextForCurrentWorkflow();
- const meta = _civitaiContextMeta(_civitaiContext);
+ // Family BEFORE the title: on video the title names the engine's family.
+ _civitaiFamily = _civitaiFamilyForCurrentEngine();
+ const meta = _civitaiContextMeta(_civitaiContext, _civitaiFamily);
const titleEl = document.getElementById('civitaiModalTitle');
if (titleEl) titleEl.textContent = meta.title;
document.getElementById('civitaiModal').style.display = 'flex';
- // Pull /loras to populate the dir text and the auth-banner state.
+ // Pull /loras to populate the dir text and the auth-banner state. The dir
+ // shown is the one this family's downloads will actually land in — the
+ // server routes by the item's base model, so browsing H3 while on H3 has to
+ // name the H3 library or the line would be a lie.
fetch('/loras').then(r => r.json()).then(d => {
- const dirEl = document.getElementById('civitaiTargetDir');
- if (dirEl && d.loras_dir) dirEl.textContent = d.loras_dir;
+ if (d.loras_dir) _lorasDirs.ltx = d.loras_dir;
+ if (d.h3_loras_dir) _lorasDirs.h3 = d.h3_loras_dir;
+ _h3LoraSupported = !!d.h3_lora_supported;
+ _civitaiSyncTargetDir();
renderCivitaiAuthBanner(!!d.civitai_auth);
}).catch(() => { renderCivitaiAuthBanner(false); });
document.getElementById('civitaiQuery').value = '';
_civitaiCursor = '';
- // Reset family on every modal open so users always land on "All".
- _civitaiFamily = '';
- // Hide family row by default; render fills it + shows it for image context.
+ // Hide the family row by default; the first search response fills it and
+ // shows it for every context that HAS families (image, and video since H3).
const famRow = document.getElementById('civitaiFamilyRow');
if (famRow) famRow.style.display = 'none';
// Pull current Spicy mode state so the "Show NSFW" toggle hides when off.
@@ -40582,6 +41825,8 @@ function civitaiRenderFamilyPills(available, active) {
const labels = {
qwen: 'Qwen-Image',
hidream: 'HiDream',
+ ltx: 'LTX-2.3',
+ h3: 'Hailuo H3',
};
const all = ['all', ...available];
row.style.display = 'flex';
@@ -40595,9 +41840,30 @@ function civitaiRenderFamilyPills(available, active) {
}).join('');
}
+// Point the "LoRAs land in …" line at the directory the CURRENT family's
+// downloads will actually be written to. The server routes by the item's own
+// base model, so on the video surface this tracks the family pill.
+function _civitaiSyncTargetDir() {
+ const dirEl = document.getElementById('civitaiTargetDir');
+ if (!dirEl) return;
+ const ltx = _lorasDirs.ltx || 'mlx_models/loras/';
+ const h3 = _lorasDirs.h3 || 'the Hailuo H3 pack’s loras/ folder';
+ if (_civitaiContext !== 'video') { dirEl.textContent = ltx; return; }
+ if (_civitaiFamily === 'h3') { dirEl.textContent = h3; return; }
+ if (_civitaiFamily === 'ltx') { dirEl.textContent = ltx; return; }
+ // "All" spans both video engines and the server routes each download by its
+ // OWN base model, so naming one directory here would be a coin flip. Name
+ // both, and say what decides.
+ dirEl.textContent = `${ltx} · MiniMax H3 → ${h3}`;
+}
+
// Click handler for a family pill — set state + re-search.
function civitaiSetFamily(family) {
_civitaiFamily = (family === 'all') ? '' : family;
+ const _m = _civitaiContextMeta(_civitaiContext, _civitaiFamily);
+ const _t = document.getElementById('civitaiModalTitle');
+ if (_t) _t.textContent = _m.title;
+ _civitaiSyncTargetDir();
// Optimistically toggle the active class so the click feels instant
// (the re-render after the fetch will reaffirm it).
const row = document.getElementById('civitaiFamilyRow');
@@ -40740,7 +42006,7 @@ async function civitaiSearch() {
_civitaiCursor = data.next_cursor || '';
if (data.has_more) loadMore.style.display = '';
if ((data.items || []).length === 0) {
- const meta = _civitaiContextMeta(_civitaiContext);
+ const meta = _civitaiContextMeta(_civitaiContext, _civitaiFamily);
grid.innerHTML = `<div class="hint">${meta.empty} "${escapeHtml(q || '')}"${document.getElementById('civitaiNsfw').checked ? '' : ' (try Show NSFW for more)'}.</div>`;
}
} catch (e) {
@@ -40860,10 +42126,32 @@ async function civitaiInstall(btn, item) {
return;
}
btn.textContent = data.skipped ? 'Already installed ✓' : 'Installed ✓';
+ // The server routes by the item's OWN base model, so a MiniMax H3 LoRA
+ // lands in the H3 library even if it was found while the browser showed
+ // "All". Auto-enable only when that library is the one the active engine
+ // reads — attaching an H3 adapter to an LTX render would fail inside the
+ // fuser, and attaching an LTX one to H3 would match zero modules and
+ // render as though nothing were attached at all.
+ const lane = data.lane || 'ltx';
+ let activeTag = 'video';
+ try {
+ activeTag = (typeof _currentLoraModeFilter === 'function')
+ ? _currentLoraModeFilter() : 'video';
+ } catch (_) {}
+ const laneMatches = (lane === 'h3') ? (activeTag === 'video:h3')
+ : (activeTag !== 'video:h3');
const status = document.getElementById('civitaiStatus');
- status.textContent = data.skipped
- ? `Already in ${data.path} — auto-enabled below.`
- : `Saved to ${data.path}. Auto-enabled below.`;
+ const where = data.skipped ? `Already in ${data.path}` : `Saved to ${data.path}`;
+ status.textContent = where + (
+ laneMatches
+ ? ' — auto-enabled below.'
+ : (lane === 'h3'
+ ? ' — it is a Hailuo H3 LoRA, so switch the engine to Hailuo H3 to use it.'
+ : ' — it is an LTX LoRA, so switch the engine to LTX-2.3 to use it.'))
+ + (data.converted
+ ? ' Converted from the ComfyUI key layout on install (a key rename;'
+ + ' the tensors are untouched).'
+ : '');
status.className = 'civitai-status-line ok';
// Refresh the local picker so the new LoRA appears, then auto-enable.
// Auto-enable applies on BOTH the fresh-download AND the
@@ -40874,12 +42162,15 @@ async function civitaiInstall(btn, item) {
// looking like a no-op even though the file was sitting right
// there in the picker.
await refreshLoras();
- addLoraToActive({
- path: data.path,
- name: data.name || item.name,
- strength: item.recommended_strength || 1.0,
- trigger_words: item.trigger_words || [],
- });
+ if (laneMatches) {
+ addLoraToActive({
+ path: data.path,
+ name: data.name || item.name,
+ strength: item.recommended_strength || 1.0,
+ trigger_words: item.trigger_words || [],
+ lane: lane,
+ });
+ }
// Open the LoRAs disclosure so the user sees the entry without
// hunting for it after the modal closes.
const det = document.getElementById('lorasDetails');