Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.
Python ai-filmmakingai-videoai-video-generatorapple-siliconhailuoimage-to-videolip-synclocal-ailora-trainingltx-2ltx-2-5ltx-videomacosminimax-h3mlxmusic-generationoffline-aipinokiotext-to-videovideo-generation
release(v4.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.mdindex 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).## Overviewdiff --git a/VERSION b/VERSIONindex c01c413..fa42341 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-4.9.3+4.9.4diff --git a/docs/STATE.md b/docs/STATE.mdindex 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 shareddiff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex d1cc886..1b60cbe 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -19,6 +19,7 @@ import importlib.utilimport ioimport jsonimport math+import collectionsimport osimport randomimport 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():continuepush(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.reasonpush(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 = Truereason = "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.pyindex 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))