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
fix(helper): drain stranded ready event from _read_until + runtime fingerprint (v3.0.11)
mrbizarro093a9f0563e7
diff --git a/VERSION b/VERSIONindex a909317..778bf95 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-3.0.10+3.0.11diff --git a/docs/STATE.md b/docs/STATE.mdindex dd3f289..373a7ce 100644--- a/docs/STATE.md+++ b/docs/STATE.md@@ -1,6 +1,6 @@# Phosphene — project state, history, open work-**Public release: `v3.0.10`.** The entire v3.0 line shipped — v3.0.0 (Characters / Voice / Image Studio / A2V, May 23) → v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a 2-month silent regression) → v3.0.3 (HiDream hidden, #15) → v3.0.4 (CivitAI SSL) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6 (deep-review hardening) → v3.0.7 (GPU-race fix + /status version surfacing) → **v3.0.8 (ltx-2-mlx v0.14.8 catch-up — codec-only patches, I2V "mosaic"/Metal-watchdog fix #17, ASCII version-skew handshake fix)** → **v3.0.9 (custom I2V Width×height inputs restored for power users; Train-tab dev-transformer Download "unknown install key" fix — form-encoding, reported by @cocktailpeanut)** → **v3.0.10 (model-integrity self-heal — boot scan + `/status.model_integrity` + a one-click Repair banner for corrupt/partial weights, the leading *non-Metal* "mosaic" garbage-decode cause; safetensors header+size check)**. See §4 for the full version history. The May-17 Codex C+ UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) and the Train-tab / LoRA-chrome work that followed are all baseline now, folded into v3.0.x. There is no `v2.0.6` tag.+**Public release: `v3.0.10`.** The entire v3.0 line shipped — v3.0.0 (Characters / Voice / Image Studio / A2V, May 23) → v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a 2-month silent regression) → v3.0.3 (HiDream hidden, #15) → v3.0.4 (CivitAI SSL) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6 (deep-review hardening) → v3.0.7 (GPU-race fix + /status version surfacing) → **v3.0.8 (ltx-2-mlx v0.14.8 catch-up — codec-only patches, I2V "mosaic"/Metal-watchdog fix #17, ASCII version-skew handshake fix)** → **v3.0.9 (custom I2V Width×height inputs restored for power users; Train-tab dev-transformer Download "unknown install key" fix — form-encoding, reported by @cocktailpeanut)** → **v3.0.10 (model-integrity self-heal — boot scan + `/status.model_integrity` + a one-click Repair banner for corrupt/partial weights, the leading *non-Metal* "mosaic" garbage-decode cause; safetensors header+size check)** → **v3.0.11 (latent helper-handshake hang fixed: `_read_until` mixed `select()` on the raw fd with a buffered `readline()`, so any event the helper emitted *right before* `ready` — a version-skew line, the new runtime fingerprint — got stranded in the TextIOWrapper buffer and the panel hung 120 s → "helper failed to start: None". This is the true root cause behind the mislabeled "⚠️-emoji" handshake break. Now reads the raw fd via `os.read()` into a carry buffer and drains every complete line before re-`select()`-ing. PLUS: every render log self-documents its runtime — mlx/mlx-metal version + Apple chip + macOS — surfaced in `/status`, the `helper ready ·` line, and a standalone `runtime |` line, the exact data needed to triangulate the remaining MLX-numerical "mosaic")**. **v3.0.11 is on `beta`, validated on the dev panel (handshake fix confirmed + clean 58 s T2V render end-to-end), pending promote to public.** See §4 for the full version history. The May-17 Codex C+ UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) and the Train-tab / LoRA-chrome work that followed are all baseline now, folded into v3.0.x. There is no `v2.0.6` tag.Current `dev` head: see `git log -1` for the live SHA. `dev` tracks `beta/main` (private repo — see §1).diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex afbf4bc..e8d1de4 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -4285,6 +4285,9 @@ class WarmHelper:stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,text=True, bufsize=1, start_new_session=True,)+ # Fresh fd → drop any bytes carried over from a prior helper's pipe+ # so _read_until's line buffer starts clean for this process.+ self._read_carry = b""ready = self._read_until(["ready", "error", "exit"], timeout=120)if not ready or ready.get("event") != "ready":raise RuntimeError(f"helper failed to start: {ready}")@@ -4293,14 +4296,21 @@ class WarmHelper:k: ready.get(k) for k in ("ltx_version", "ltx_version_expected", "ltx_version_match","model", "gemma", "low_memory",+ "mlx_version", "mlx_metal_version", "chip", "macos",)}_vtag = ""if ready.get("ltx_version") is not None:_vtag = (f" · ltx-2-mlx={ready.get('ltx_version')}"- + ("" if ready.get("ltx_version_match") else " ⚠️SKEW"))+ + ("" if ready.get("ltx_version_match") else " SKEW"))+ # Self-documenting env on the ready line — mlx + chip are the data we+ # need on mosaic / garbled-output reports (an MLX numerical bug per+ # chip/mlx, not a crash). ASCII only (emoji here can break stdout).+ _env = (f" · mlx={ready.get('mlx_version')}" if ready.get("mlx_version") else "")+ if ready.get("chip"):+ _env += f" · {ready.get('chip')}"push(f"helper ready · model={ready.get('model')} · "- f"low_memory={ready.get('low_memory')}{_vtag}")+ f"low_memory={ready.get('low_memory')}{_vtag}{_env}")def _read_until(self, target_events: list[str], timeout: float | None = None,log_hook: callable | None = None,@@ -4320,10 +4330,30 @@ class WarmHelper:deadline = time.time() + timeout if timeout else None# Poll-and-check loop: blocking readline() used to mean a hung helper# froze the worker thread until /stop. select() with a small interval- # gives us deterministic deadline enforcement; readline() is only- # called once we know there's data waiting.+ # gives us deterministic deadline enforcement.+ #+ # CRITICAL (2026-06-05): we read the RAW fd with os.read() and split+ # lines ourselves instead of select()+stdout.readline(). The old code+ # mixed select() on the OS fd with a buffered TextIOWrapper.readline().+ # When the helper emits a burst — e.g. a "log" line immediately+ # followed by "ready" — a single readline() pulls BOTH lines off the+ # pipe into Python's userspace buffer and returns only the first. The+ # second ("ready") then sits in the TextIOWrapper buffer, NOT on the+ # OS fd, so select() never reports it readable; if the helper then+ # goes silent (exactly what it does after "ready"), _read_until hung+ # for the full timeout → "helper failed to start: None". This was+ # dormant for as long as "ready" was the helper's first emitted event;+ # any pre-ready line (the version-skew log, the runtime fingerprint)+ # exposed it. os.read() only ever returns bytes select() already saw,+ # and we drain EVERY complete line from the carry buffer before+ # waiting on select() again — so no line is ever stranded.poll_interval = 0.5- stdout = self.proc.stdout+ try:+ fd = self.proc.stdout.fileno()+ except (OSError, ValueError):+ return None+ if not hasattr(self, "_read_carry"):+ self._read_carry = b""while True:if deadline and time.time() > deadline:return None@@ -4334,18 +4364,25 @@ class WarmHelper:synth = panic_check()if synth is not None:return synth- rlist, _, _ = select.select([stdout], [], [], poll_interval)- if not rlist:- continue # idle slice — re-check deadline- try:- line = stdout.readline()- except (OSError, ValueError):- # Pipe closed underneath us (kill from another thread).- return None- if not line:- # EOF — helper closed stdout (likely crashed or was killed).- return None- line = line.strip()+ nl = self._read_carry.find(b"\n")+ if nl < 0:+ # No complete line buffered — wait for more bytes on the fd.+ rlist, _, _ = select.select([fd], [], [], poll_interval)+ if not rlist:+ continue # idle slice — re-check deadline+ try:+ chunk = os.read(fd, 65536)+ except (OSError, ValueError):+ # Pipe closed underneath us (kill from another thread).+ return None+ if not chunk:+ # EOF — helper closed stdout (likely crashed or was killed).+ return None+ self._read_carry += chunk+ continue # loop back to drain complete lines from the buffer+ raw = self._read_carry[:nl]+ self._read_carry = self._read_carry[nl + 1:]+ line = raw.decode("utf-8", "replace").strip()if not line:continuetry:@@ -8079,6 +8116,12 @@ class Handler(BaseHTTPRequestHandler):payload["ltx_version"] = HELPER.ready_info.get("ltx_version")payload["ltx_version_expected"] = HELPER.ready_info.get("ltx_version_expected")payload["ltx_version_match"] = HELPER.ready_info.get("ltx_version_match")+ # Runtime fingerprint (mlx/chip/macOS) for triaging the "mosaic"+ # MLX-numerical bug — surfaces in every bug report's /status.+ payload["mlx_version"] = HELPER.ready_info.get("mlx_version")+ payload["mlx_metal_version"] = HELPER.ready_info.get("mlx_metal_version")+ payload["chip"] = HELPER.ready_info.get("chip")+ payload["macos"] = HELPER.ready_info.get("macos")# Per-kind avg ETA: image jobs are 30s–2min, video jobs are# 5–30min. Computing queue ETA from one mixed avg makes an# image queued after a few videos show "~30 min" — thediff --git a/mlx_warm_helper.py b/mlx_warm_helper.pyindex bfef4a8..7427074 100644--- a/mlx_warm_helper.py+++ b/mlx_warm_helper.py@@ -1774,6 +1774,51 @@ if not _LTX_VERSION_INFO["match"]:f"against {_LTX_EXPECTED_VERSION}; behavior on this version is "f"unvalidated. {_LTX_VERSION_INFO['note']}".strip())})+# ---- runtime fingerprint (mlx / chip / OS) ----------------------------------+# Every render log then self-documents the exact environment — the data we keep+# having to ask for on "mosaic" / garbled-output reports. Those are an MLX+# numerical-correctness issue on specific chip+mlx combos (the render completes+# and writes a normal-size file full of garbage pixels — not a crash, OOM, or+# corrupt weights), so the mlx/mlx-metal version and the Apple chip are exactly+# what's needed to triangulate. Never raises.+def _detect_runtime_env() -> dict:+ env = {"mlx": None, "mlx_metal": None, "mlx_lm": None,+ "chip": None, "macos": None, "arch": None}+ try:+ import importlib.metadata as _md+ for _k, _dist in (("mlx", "mlx"), ("mlx_metal", "mlx-metal"), ("mlx_lm", "mlx-lm")):+ try:+ env[_k] = _md.version(_dist)+ except Exception:+ pass+ except Exception:+ pass+ try:+ import platform as _pf+ env["arch"] = _pf.machine()+ env["macos"] = _pf.mac_ver()[0] or None+ except Exception:+ pass+ try:+ import subprocess as _sp+ _chip = _sp.run(["sysctl", "-n", "machdep.cpu.brand_string"],+ capture_output=True, text=True, timeout=3).stdout.strip()+ env["chip"] = _chip or None+ except Exception:+ pass+ return env+++_RUNTIME_ENV = _detect_runtime_env()+# ASCII only — this is emitted to the helper's stdout, which the panel reads to+# parse events; a non-ASCII byte there can break the read on a non-UTF-8 locale+# (the same failure mode the version-skew emoji had). No "·" / emoji here.+emit({"event": "log",+ "line": (f"runtime | mlx={_RUNTIME_ENV.get('mlx')} "+ f"mlx-metal={_RUNTIME_ENV.get('mlx_metal')} | "+ f"chip={_RUNTIME_ENV.get('chip')} | "+ f"macOS={_RUNTIME_ENV.get('macos')} ({_RUNTIME_ENV.get('arch')})")})+# ---- ready -------------------------------------------------------------------emit({"event": "ready",@@ -1784,6 +1829,10 @@ emit({"ltx_version": _LTX_VERSION_INFO["version"],"ltx_version_expected": _LTX_EXPECTED_VERSION,"ltx_version_match": _LTX_VERSION_INFO["match"],+ "mlx_version": _RUNTIME_ENV.get("mlx"),+ "mlx_metal_version": _RUNTIME_ENV.get("mlx_metal"),+ "chip": _RUNTIME_ENV.get("chip"),+ "macos": _RUNTIME_ENV.get("macos"),})