Skip to content

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

release(v4.9.4): four fleet-driven fixes — self-pausing queue, H3 failures name their cause, capped step counts, HiDream fallback

mrbizarro10f822d7d12e
diff --git a/README.md b/README.md
index ae39e77..e2eda1c 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
</p>
-> **Current release: v4.9.3.** Fixes from a full review of the fast 4.9.x releases. Storyboard works again on Macs that cap at 768 (24 GB): new films are planned at a size the Mac can deliver, the fix button offers the real size, and the Quality section is visible at Pinokio window widths (#71). Renaming a character works again. A freshly trained character clicked "Use in video" now actually rides on the render. Image Studio tells 8/24 GB Macs up front which engines fit instead of refusing at the last second. High/Keyframes/Extend without the Q8 pack point to Settings → Models. Image mode with no image is stopped at the button. Update moves the H3 engine to its pinned branch before building the half-memory engine (#74, thanks @blackest). Full notes on the [releases page](https://github.com/mrbizarro/phosphene/releases).
+> **Current release: v4.9.4.** Four small fixes from the first day of fleet data on 4.9.3. A queue that fails three times in a row on the same problem now pauses itself and says what to fix, instead of burning through every waiting job. H3 failures name the actual reason ("last line: …") instead of "see the log above". Step counts that exceed what the model's schedule holds are capped instead of crashing the render after the models load. A stale HiDream setting in Image Studio falls back to an installed engine. Full notes on the [releases page](https://github.com/mrbizarro/phosphene/releases).
## Overview
diff --git a/VERSION b/VERSION
index c01c413..fa42341 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-4.9.3
+4.9.4
diff --git a/docs/STATE.md b/docs/STATE.md
index 42dc7c9..416c600 100644
--- a/docs/STATE.md
+++ b/docs/STATE.md
@@ -1,5 +1,28 @@
# Phosphene — project state, history, open work
+> **🩹 2026-09-04 — v4.9.4: the four follow-ups from 4.9.3's first day, shipped.**
+> Queue circuit breaker (3 identical failures → pause + why), H3 failures
+> carry their last engine line, stage step counts capped at the checkpoint's
+> tables, dead HiDream image setting falls back. Fleet-driven, all verified
+> on scratch panels / tests; full gates green. Promoted by the snapshot ritual.
+
+> **📈 2026-09-04 — first 12 h of v4.9.3 (UNRELEASED follow-ups on dev/beta: b1ffb4b).**
+> 40 installs on 4.9.3 within 12 h, 15 new installs. Its raw failure count
+> (394) is ONE 16 GB install with an incomplete Q4 pack failing 371 times
+> (227 in ten minutes; it had failed 479× on 4.6.0) — not a regression. Fix
+> on dev: the queue pauses itself after three identical failures in a row
+> (`_CONSEC_FAIL` in worker_loop, verified on a scratch panel). H3: 20
+> failures / 3 installs all read "exited with code 1 — see the log above";
+> per-install history shows those installs failed on older versions too
+> and an old-branch install (cf14779a) renders fine after the #74 branch
+> move — no sign the move broke anything. Fix on dev: the H3 failure now
+> carries the last engine line. Also fixed on dev (same day): explicit stage step counts are capped at
+> what the checkpoint's own tables hold (`_clamp_stage_steps_to_tables`,
+> the "cannot thin … up to 12 steps" class); a saved HiDream image engine
+> with no venv promotes to an installed mflux family instead of failing
+> every Studio render. Pinokio: no replies to the 4.9.3 post or from @vxlab
+> yet; no new threads. GitHub: no new activity on any open issue.
+
> **🩹 2026-09-03 — v4.9.3: the full-review fixes, shipped as a plain bugfix.**
> Everything in the 09-02 review entry below, plus #74 (Update now moves the
> H3 engine checkout to `codex/h3-engine-v2` via the new shared
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index d1cc886..1b60cbe 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -19,6 +19,7 @@ import importlib.util
import io
import json
import math
+import collections
import os
import random
import re
@@ -18430,6 +18431,48 @@ def _safe_float(raw, default: float = 0.0, *,
return val
+def _clamp_stage_steps_to_tables(job: dict) -> None:
+ """Cap an explicit stage1/stage2 step count at what the active
+ checkpoint's schedule tables can be thinned to. Stage 2 is always a
+ fixed table (4 points on 2.5); stage 1 is only a table on the distilled
+ lane — the HQ lane's stage 1 is a real sampler, left alone. Logs each
+ clamp so the render card explains the number the user did not get."""
+ p = job.get("params") or {}
+ try:
+ from ltx_pipelines_mlx.scheduler import ( # noqa: PLC0415
+ resolve_distilled_schedule, resolve_stage2_sigmas)
+ except Exception: # noqa: BLE001
+ return
+ mv = (2, 5) if (model_version().get("id") or "").startswith("ltx25") else (2, 3)
+ caps: dict[str, int] = {}
+ try:
+ caps["stage2_steps"] = len(resolve_stage2_sigmas(mv, None)) - 1
+ except Exception: # noqa: BLE001
+ pass
+ hq = False
+ try:
+ hq = bool(ltx_quality_uses_hq(p.get("quality") or ""))
+ except Exception: # noqa: BLE001
+ pass
+ if not hq and p.get("mode") not in ("extend", "keyframe", "restore",
+ "ingredients", "control"):
+ try:
+ _s1, _ = resolve_distilled_schedule(
+ mv, preset=(p.get("schedule_preset") or None))
+ caps["stage1_steps"] = len(_s1) - 1
+ except Exception: # noqa: BLE001
+ pass
+ for key, cap in caps.items():
+ try:
+ want = int(p.get(key))
+ except (TypeError, ValueError):
+ continue
+ if cap > 0 and want > cap:
+ p[key] = cap
+ push(f"{key.replace('_steps', '')} steps {want} → {cap}: the model's "
+ f"own schedule has {cap}; more would be padding, not quality.")
+
+
def make_job(form: dict[str, list[str]] | dict[str, str], *,
override_prompt: str | None = None) -> dict:
def f(name: str, default: str = "") -> str:
@@ -19329,6 +19372,11 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,
job["params"][_sk] = max(_lo, int(_raw))
except (TypeError, ValueError):
pass
+ # And never MORE than the loaded checkpoint's own table holds: a step
+ # count thins that table, and asking for more is a pad request the
+ # sampler refuses after the models are already loaded (fleet 2026-09-03:
+ # "stage 2: cannot thin a 4-point schedule (3 steps) up to 12 steps").
+ _clamp_stage_steps_to_tables(job)
# Attach Characters-origin metadata only when the form actually carried
# it. Keeps the params shape unchanged for every other entry point.
if _source == "characters" and _character_id:
@@ -21447,11 +21495,17 @@ def run_h3_job_inner(job: dict) -> None:
line, buf = buf.split(b"\n", 1)
yield line.decode("utf-8", "replace") + "\n"
+ # The last few lines the engine printed ride on the failure message
+ # (fleet 2026-09-03: 20 H3 failures on one release all read
+ # "exited with code 1 — see the log above", which analytics cannot
+ # see and users rarely paste). Traceback tails are what we want.
+ _h3_tail: collections.deque = collections.deque(maxlen=4)
for raw in _h3_lines():
line = raw.rstrip("\n")
if not line.strip():
continue
push(f"[h3] {line}")
+ _h3_tail.append(line.strip())
m_window = window_rx.match(line.strip())
if m_window:
try:
@@ -21565,9 +21619,12 @@ def run_h3_job_inner(job: dict) -> None:
raise RuntimeError(
f"H3 helper exited from {_sig} ({_hint}) — see the log "
f"above (metrics at {metrics_path}).")
+ _last = next((t for t in reversed(_h3_tail)
+ if t and not t.startswith(('step', 'Window', '['))), '')
raise RuntimeError(
- f"H3 render exited with code {rc} — see the log above for the "
- f"traceback (metrics at {metrics_path}).")
+ f"H3 render exited with code {rc}"
+ + (f" — last line: {_last[:220]}" if _last else "")
+ + f" (see the log above; metrics at {metrics_path}).")
finally:
if proc is not None:
try:
@@ -23446,6 +23503,9 @@ def run_job_inner(job: dict) -> None:
# ---- worker thread -----------------------------------------------------------
+_CONSEC_FAIL: dict = {"sig": "", "n": 0} # worker_loop's same-failure streak
+
+
def worker_loop() -> None:
while True:
with QUEUE_COND:
@@ -23471,6 +23531,7 @@ def worker_loop() -> None:
with _GPU_LOCK:
run_job_inner(job)
job["status"] = "done"
+ _CONSEC_FAIL.update(sig="", n=0)
except JobStopped as stop:
# EXIT 75 IS A CANCEL, NOT A FAILURE. The user looked at the live
# preview, saw the wrong shot and stopped it. Nothing was saved —
@@ -23498,6 +23559,22 @@ def worker_loop() -> None:
if isinstance(exc, RenderRefused) and exc.reason:
job["refused_reason"] = exc.reason
push(f"ERROR: {exc}")
+ # CIRCUIT BREAKER (fleet 2026-09-03: one 16 GB install failed
+ # 227 renders in ten minutes on the same incomplete-model
+ # message — a whole queue burning down on a problem no
+ # retry can fix). Three identical failures in a row with
+ # more work queued: pause, say why, leave the queue intact.
+ _sig = str(exc)[:80]
+ if _sig and _sig == _CONSEC_FAIL["sig"]:
+ _CONSEC_FAIL["n"] += 1
+ else:
+ _CONSEC_FAIL.update(sig=_sig, n=1)
+ if _CONSEC_FAIL["n"] >= 3 and STATE["queue"] and not STATE["paused"]:
+ STATE["paused"] = True
+ push(f"Paused the queue: {_CONSEC_FAIL['n']} renders in a row failed "
+ f"with the same problem, and {len(STATE['queue'])} more are "
+ f"waiting. Fix the cause above (Settings → Models for a "
+ f"missing or incomplete model), then press Resume.")
finally:
job["finished_at"] = iso_now()
if job.get("started_ts"):
@@ -23651,6 +23728,14 @@ def _load_agent_image_config() -> agent_image_engine.ImageEngineConfig:
if cfg.kind == "mock":
needs_promote = True
reason = "mock"
+ elif (cfg.kind == "hidream"
+ and not agent_image_engine._resolve_hidream_python(cfg)):
+ # The HiDream lab lives in a venv most installs never built; a
+ # config that still names it (an old Settings pick, or a copied
+ # state dir) failed every Studio render with "HiDream venv python
+ # not found" (fleet 2026-09-03). Same promotion as mock.
+ needs_promote = True
+ reason = "hidream_not_installed"
elif (cfg.kind == "mflux"
and (cfg.mflux_family == "qwen_edit"
or agent_image_engine._infer_mflux_family(cfg.mflux_model) == "qwen_edit")
diff --git a/test_refusal_gates.py b/test_refusal_gates.py
index 1a426a1..9f8d683 100644
--- a/test_refusal_gates.py
+++ b/test_refusal_gates.py
@@ -477,3 +477,32 @@ class ImageStudioMemoryGuardIsARefusal(unittest.TestCase):
msg = ("High quality needs the LTX-2.5 High add-on (the Q8 model), which "
"isn't downloaded on this Mac yet. Missing 12 file(s): x.")
self.assertEqual(P._analytics_refusal_reason(msg), "pack_missing")
+
+
+class StepCountsNeverPadTheTable(unittest.TestCase):
+ """Fleet 2026-09-03: an explicit stage-2 count of 12 on 2.5's 4-point
+ table loaded the models and then died on "cannot thin … up to 12 steps".
+ The panel now caps explicit counts at what the table holds."""
+
+ def test_stage2_is_capped_and_stage1_on_the_distilled_lane(self):
+ job = {"params": {"quality": "balanced", "mode": "t2v",
+ "stage1_steps": 40, "stage2_steps": 12}}
+ with unittest.mock.patch.object(P, "model_version", lambda *a, **k: {"id": "ltx25"}):
+ P._clamp_stage_steps_to_tables(job)
+ self.assertEqual(job["params"]["stage2_steps"], 3)
+ self.assertLessEqual(job["params"]["stage1_steps"], 8)
+
+ def test_hq_lane_stage1_is_left_alone(self):
+ job = {"params": {"quality": "high", "mode": "t2v",
+ "stage1_steps": 15, "stage2_steps": 12}}
+ with unittest.mock.patch.object(P, "model_version", lambda *a, **k: {"id": "ltx25"}):
+ P._clamp_stage_steps_to_tables(job)
+ self.assertEqual(job["params"]["stage1_steps"], 15)
+ self.assertEqual(job["params"]["stage2_steps"], 3)
+
+ def test_counts_within_the_table_are_untouched(self):
+ job = {"params": {"quality": "balanced", "mode": "t2v",
+ "stage1_steps": 6, "stage2_steps": 2}}
+ with unittest.mock.patch.object(P, "model_version", lambda *a, **k: {"id": "ltx25"}):
+ P._clamp_stage_steps_to_tables(job)
+ self.assertEqual((job["params"]["stage1_steps"], job["params"]["stage2_steps"]), (6, 2))