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.11.1): estimates follow the chip; Control, HiDream, training and image pre-flight guards from the fleet read
mrbizarro94bd30d0c38f
diff --git a/README.md b/README.mdindex de4a878..23f2d3f 100644--- a/README.md+++ b/README.md@@ -19,7 +19,7 @@</p>-> **Current release: v4.11.0.** **One Shot** is its own way of making video: a continuous shot of 30 s to 2 min that never cuts, next to Text, Character and Image — pick a length, write one line per 5 seconds, add a start frame if you like, keep the light locked, and see the real time for your Mac. LTX one shots hold together now (parts that continue from the last frame, like Hailuo H3's), and the Storyboard planner can place a One Shot inside a film. Also in this line: LTX Upscale, Extend fixed, LoRAs stack on Hailuo H3. Full notes on the [releases page](https://github.com/mrbizarro/Phosphene/releases).+> **Current release: v4.11.1.** Time estimates now follow your chip (an M4 Pro or M1 Max renders two to four times slower than the M4 Max the numbers were measured on; an M5 Max or M3 Ultra much faster). Control asks for a clip before it queues, a saved HiDream pick falls back to Auto instead of failing, training says no on Macs under 24 GB, and the image pre-flight frees the idle video helper before refusing a 32 GB Mac. Includes 4.11.0: **One Shot** as its own mode, LTX one shots that hold together, the planner placing a One Shot inside a film. Full notes on the [releases page](https://github.com/mrbizarro/Phosphene/releases).## Overviewdiff --git a/VERSION b/VERSIONindex a162ea7..d782fca 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-4.11.0+4.11.1diff --git a/docs/STATE.md b/docs/STATE.mdindex 90e8d91..73402de 100644--- a/docs/STATE.md+++ b/docs/STATE.md@@ -1,5 +1,38 @@# Phosphene — project state, history, open work+> **🚀 2026-09-07 — v4.11.1 ships: the fleet fixes** (chip-scaled estimates,+> Control gate, HiDream fallback, training floor, image pre-flight frees the+> helper). Carries 4.11.0.++> **🔬 2026-09-07 — fleet study after v4.11.0 (on dev).** Queried PostHog by+> version, mode, engine, chip and RAM. Findings and what was done:+> **(1) Estimates ignored the chip** — fleet medians for the same tier: LTX+> Balanced 121f M5 Max 60 s … M4 Max 180 … M4 Pro 300 … M1 Pro 600 … M2/M3+> 900; H3 draft_5s M5 Max 120 … M4 Max 300 … M4 Pro/M3 Max 600 … M1 Max 900,+> H3 standard_10s on an M4 Pro 2400 vs 600. Every chip promised the M4 Max+> number ("~30 s left" for forty minutes, the report that started this).+> `HW_SPEED_FACTOR_LTX/H3` + `_hw_speed_factor()` scale `ltx_estimate_minutes`+> and `h3_estimate_minutes` (so every chip, Speed pill, take estimate and+> Storyboard price follow); `PHOSPHENE_SPEED_FACTOR` overrides;+> `test_fleet_calibration.py`. **(2) Control queued with no clip** (seven+> installs, "control video not found: ''") — client gate beside the Image one.+> **(3) HiDream still reachable** from a saved pick / Load Params on installs+> without its venv (5 installs, 4.8.1 → 4.11.0) — the queue path now falls+> back to Auto with a log line (`_hidream_available`). **(4) Training on+> 16 GB Macs**: 10 failures to 1 success — `/train/start` refuses below+> `TRAIN_MIN_RAM_GB = 24` with the reason. **(5) `image_ram` refusals**: 46 of+> 70 on 32 GB Macs — the idle video helper was holding the memory; the image+> pre-flight now releases it and measures again before refusing.+> **Not bugs (noise to know about):** the 7-day error-rate tile (23 %) and the+> 16 GB "67 % failure" are ONE 4.9.3 install with a broken model dir (380+> failures: "model incomplete / Missing 262 parameters / no safetensors"); one+> install's FLUX.2-klein download stuck at 4.6 GB for days (disk); watchdog+> kills scattered 1–5 per install on old versions; "H3 render exited with code+> 1" clusters on 4.9.3/4.9.4 (stale engine packs). 4.11.0 after one day: 30+> installs, 56 renders, 7 failures, none new. H3 dense 10 s tiers run 50–60 min+> at p50 on M4 Pro (memory-bound chain) — the chip factor covers the chip,+> not the RAM tier; a RAM-aware H3 factor is the next step if it recurs.+> **🚀 2026-09-07 — v4.11.0 ships: One Shot.** The mode chip + panel, LTX> one shots by last-frame handoff (proven on a 40 s bar conversation:> four 10 s parts, same people, same room, camera moving), the planner'sdiff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex c7867fd..0abd7f7 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -1920,6 +1920,11 @@ TRAIN_TYPES = ("character", "style")# Dataset rules.TRAIN_MIN_IMAGES = 15+# Fleet, 7 days to 2026-09-07: on 16 GB Macs training exited with code 1 ten+# times for one success (four installs). The trainer holds the Q4 base plus+# the adapter and its optimizer state; below this much memory it does not+# finish, so /train/start says so before the first step instead of after it.+TRAIN_MIN_RAM_GB = 24# Soft cap on the per-character dataset size. The old 50-image limit# was a friendly-default-misread-as-hard-rule — many users wanted to# train against 80-200 photos for richer identity capture, and the@@ -8118,6 +8123,63 @@ def _h3_fixed_seconds(w: int, h: int, window_frames: int) -> float:return H3_LOAD_SEC + H3_DECODE_SEC_PER_PX_FRAME * int(w) * int(h) * int(window_frames)+# Render speed by chip CLASS relative to the M4 Max every estimate in this file+# was measured on. Fleet medians of wall_sec_bucket for the same tier and frame+# count (PostHog, 30 days to 2026-09-07, n >= 10 per cell): LTX Balanced 121f —+# M5 Max 60 s, M3 Ultra 90, M5 Pro/M2 Ultra 120, M1 Ultra 150, M2 Max/M4 Max+# 180, M3 Max 210, M5 240, M1 Max/M4 Pro 300, M4 420, M3 Pro 510, M1 Pro 600,+# M1 750, M2/M3 900. H3 draft_5s — M5 Max/M5 Pro/M3 Ultra 120, M4 Max/M2 Ultra+# 300, M1 Ultra 420, M4 Pro/M3 Max 600, M1 Max 900. Before this table an M4 Pro+# was promised the M4 Max number and saw "~30 s left" for forty minutes.+# Unknown chips price as an M4 Max (factor 1.0), as before.+HW_SPEED_FACTOR_LTX = {+ "M5 Max": 0.35, "M3 Ultra": 0.5, "M5 Pro": 0.65, "M2 Ultra": 0.7, "M1 Ultra": 0.85,+ "M2 Max": 1.0, "M4 Max": 1.0, "M3 Max": 1.2, "M5": 1.35, "M1 Max": 1.7, "M4 Pro": 1.7,+ "M4": 2.3, "M3 Pro": 2.8, "M2 Pro": 2.8, "M1 Pro": 3.3, "M1": 4.2, "M2": 5.0, "M3": 5.0,+}+HW_SPEED_FACTOR_H3 = {**HW_SPEED_FACTOR_LTX,+ "M5 Max": 0.4, "M5 Pro": 0.6, "M3 Ultra": 0.7, "M2 Ultra": 1.0, "M1 Ultra": 1.4,+ "M4 Pro": 2.0, "M3 Max": 2.0, "M1 Max": 3.0}+++def _hw_speed_factor(engine: str = "ltx") -> float:+ """How many times slower than an M4 Max this Mac renders on `engine`.+ Env `PHOSPHENE_SPEED_FACTOR` overrides (a number), for tests and for a+ user whose machine the table misjudges."""+ raw = (os.environ.get("PHOSPHENE_SPEED_FACTOR") or "").strip()+ if raw:+ try:+ return max(0.05, float(raw))+ except ValueError:+ pass+ table = HW_SPEED_FACTOR_H3 if engine == "h3" else HW_SPEED_FACTOR_LTX+ return float(table.get(_hw_chip_family(), 1.0))+++_HW_CHIP_FAMILY: str | None = None+++def _hw_chip_family() -> str:+ """'Apple M4 Max' -> 'M4 Max'; read once. Lives ahead of the tier tables+ because they are priced at import, before the analytics module's own+ reader is defined."""+ global _HW_CHIP_FAMILY+ if _HW_CHIP_FAMILY is None:+ fam = "unknown"+ try:+ brand = subprocess.run(["sysctl", "-n", "machdep.cpu.brand_string"],+ capture_output=True, text=True, timeout=3).stdout.strip()+ m = re.search(r"Apple (M\d+)(?: (Pro|Max|Ultra))?", brand)+ if m:+ fam = m.group(1) + (f" {m.group(2)}" if m.group(2) else "")+ except Exception: # noqa: BLE001+ pass+ _HW_CHIP_FAMILY = fam+ return _HW_CHIP_FAMILY++++def h3_estimate_minutes(w: int, h: int, window_frames: int, windows: int,forwards: int) -> float:"""Wall clock, in minutes, for a render of this exact shape. The one function@@ -8129,7 +8191,7 @@ def h3_estimate_minutes(w: int, h: int, window_frames: int, windows: int,rows = _h3_packed_rows(w, h, window_frames)per_fwd = _h3_forward_seconds(rows)fixed = _h3_fixed_seconds(w, h, window_frames)- return (windows * max(0, int(forwards)) * per_fwd + windows * fixed) / 60.0+ return (windows * max(0, int(forwards)) * per_fwd + windows * fixed) / 60.0 * _hw_speed_factor("h3")def _fmt_eta(minutes: float) -> str:@@ -8676,7 +8738,7 @@ def ltx_estimate_minutes(w: int, h: int, frames: int,+ max(0, int(stage2_steps)) * max(1, int(stage2_evals))* _ltx_forward_seconds(s2))fixed = LTX_LOAD_SEC + LTX_DECODE_SEC_PER_PX_FRAME * int(w) * int(h) * int(frames)- return (denoise + fixed) / 60.0+ return (denoise + fixed) / 60.0 * _hw_speed_factor("ltx")# END-TO-END WALL CLOCKS actually observed, keyed@@ -12308,6 +12370,16 @@ def _analytics_chip_family() -> str:return family+def _hidream_available() -> bool:+ """Whether the HiDream lab venv exists on this install. It never ships by+ default; a saved engine pick that names it must fall back, not fail."""+ try:+ probe = agent_image_engine.ImageEngineConfig(kind="hidream")+ return bool(agent_image_engine._resolve_hidream_python(probe))+ except Exception: # noqa: BLE001+ return False++def _qwen_pack_available() -> bool:"""Whether the optional Qwen image pack's mflux binary is installed.Same probe the /agent/image/config endpoint uses for its family pills."""@@ -20477,6 +20549,13 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,except (TypeError, ValueError):seed = -1engine_override = (f("engine_override", "auto") or "auto").lower()+ # HiDream is hidden from the dropdown (v3.0.3) but a saved pick or a+ # Load Params of an old sidecar still names it; on the ~all installs+ # without its venv every such job died with "HiDream venv python not+ # found" (fleet: 4.8.1 → 4.11.0, five installs). Fall back, say so.+ if engine_override.startswith("hidream") and not _hidream_available():+ push(f"[image] {engine_override} is not installed on this Mac — rendering with Auto instead.")+ engine_override = "auto"aspect = f("aspect", "16:9") or "16:9"# refs comes as a JSON-encoded list (e.g. '["panel_uploads/foo.png"]').# Plain form fields can't carry a list cleanly; the panel JS already@@ -21648,6 +21727,23 @@ def _preflight_image_job(cfg, *, engine_override: str = "auto") -> None:f"{total_gb:.0f} GB. Pick Auto (the 4B FLUX engine, fits here) "f"or a lighter preset.")+ if free_gb < need_gb and HELPER.is_alive():+ # The video helper keeps its pipelines warm between jobs; on a 32 GB+ # Mac that is most of the memory an image engine needs, and the fleet+ # showed 46 of 70 image_ram refusals landing on exactly that class of+ # machine. The queue runs one job at a time, so while an image job is+ # here the helper is idle by construction: let it go, measure again.+ push(f"[preflight] {free_gb:.1f} GB free of {need_gb:.0f} needed — releasing the idle video helper first")+ try:+ HELPER.kill()+ time.sleep(2.0)+ except Exception: # noqa: BLE001+ pass+ mem = get_memory()+ total_gb = float(mem.get("total_gb") or total_gb)+ used_gb = float(mem.get("used_gb") or used_gb)+ free_gb = max(0.0, total_gb - used_gb)+ push(f"[preflight] {free_gb:.1f} GB free after releasing the helper")if free_gb < need_gb:raise RenderRefused("image_ram",diff --git a/panel/routes_train.py b/panel/routes_train.pyindex d998de8..87d3e92 100644--- a/panel/routes_train.py+++ b/panel/routes_train.py@@ -177,6 +177,10 @@ def post_train_start(h, path, qs, ctype) -> None:train_job_id = (form.get("train_job_id", [""])[0] or "").strip()if not train_job_id:h._json({"error": "train_job_id required"}, 400); return+ if float(P.SYSTEM_RAM_GB or 0) and float(P.SYSTEM_RAM_GB) < P.TRAIN_MIN_RAM_GB:+ h._json({"error": f"Training needs at least {P.TRAIN_MIN_RAM_GB} GB of memory; this Mac has "+ f"{float(P.SYSTEM_RAM_GB):.0f} GB. On this machine the trainer runs out of memory "+ f"before it finishes."}, 409); returntry:train_job_id = P._safe_job_id(train_job_id)except ValueError as e:diff --git a/test_fleet_calibration.py b/test_fleet_calibration.pynew file mode 100644index 0000000..ee14cf0--- /dev/null+++ b/test_fleet_calibration.py@@ -0,0 +1,54 @@+"""Estimates follow the chip; the queue path never routes to an engine that is not there.++Fleet, 30 days to 2026-09-07: the same tier renders 2-4x slower on an M4 Pro+than on the M4 Max every estimate was measured on, and faster on the M5 and+Ultra parts. The chips promised the M4 Max number to everyone.+"""+import os, unittest+from unittest import mock++import mlx_ltx_panel as p+++class SpeedFactor(unittest.TestCase):+ def test_unknown_chip_prices_as_m4_max(self):+ with mock.patch.object(p, "_hw_chip_family", lambda: "unknown"), \+ mock.patch.dict(os.environ, {"PHOSPHENE_SPEED_FACTOR": ""}):+ self.assertEqual(p._hw_speed_factor("ltx"), 1.0)+ self.assertEqual(p._hw_speed_factor("h3"), 1.0)++ def test_m4_pro_is_slower_and_m5_max_faster(self):+ with mock.patch.dict(os.environ, {"PHOSPHENE_SPEED_FACTOR": ""}):+ with mock.patch.object(p, "_hw_chip_family", lambda: "M4 Pro"):+ self.assertGreater(p._hw_speed_factor("ltx"), 1.4)+ self.assertGreater(p._hw_speed_factor("h3"), 1.8)+ with mock.patch.object(p, "_hw_chip_family", lambda: "M5 Max"):+ self.assertLess(p._hw_speed_factor("ltx"), 0.5)++ def test_estimates_scale_with_the_factor(self):+ import inspect+ n_ltx = len(inspect.signature(p.ltx_estimate_minutes).parameters)+ with mock.patch.dict(os.environ, {"PHOSPHENE_SPEED_FACTOR": "1"}):+ h3_one = p.h3_estimate_minutes(768, 448, 124, 1, 3)+ ltx_one = p.ltx_estimate_minutes(1024, 576, 121, *([8] * (n_ltx - 3)))+ with mock.patch.dict(os.environ, {"PHOSPHENE_SPEED_FACTOR": "2"}):+ self.assertAlmostEqual(p.h3_estimate_minutes(768, 448, 124, 1, 3), h3_one * 2, places=4)+ self.assertAlmostEqual(p.ltx_estimate_minutes(1024, 576, 121, *([8] * (n_ltx - 3))), ltx_one * 2, places=4)++ def test_env_override_wins(self):+ with mock.patch.dict(os.environ, {"PHOSPHENE_SPEED_FACTOR": "3.5"}):+ self.assertEqual(p._hw_speed_factor("h3"), 3.5)+++class QueuePathRouting(unittest.TestCase):+ def test_hidream_pick_falls_back_to_auto_when_not_installed(self):+ with mock.patch.object(p, "_hidream_available", lambda: False):+ job = p.make_job({"mode": "image", "prompt": "a lamp", "engine_override": "hidream_inline", "n": "1"})+ self.assertEqual(job["params"].get("engine_override"), "auto")++ def test_train_floor_is_declared(self):+ self.assertGreaterEqual(p.TRAIN_MIN_RAM_GB, 24)+++if __name__ == "__main__":+ unittest.main()diff --git a/webapp/js/queue.js b/webapp/js/queue.jsindex 9afe017..86dd441 100644--- a/webapp/js/queue.js+++ b/webapp/js/queue.js@@ -4423,6 +4423,14 @@ document.getElementById('genForm').addEventListener('submit', async e => {reenable();return;}+ // Same class of silent failure for Control: seven installs queued it with+ // no clip and got "control video not found" as a red card (fleet, 2026-09-07).+ if (_modeNow === 'control' && !String(fd.get('control_video_path') || '').trim()) {+ alert('Control needs a clip to follow — pick one in the Control video picker, '+ + 'or switch to Text mode.');+ reenable();+ return;+ }// Safety net: if the prompt mentions a trigger word from a LoRA the user// has installed but NOT toggled active for this render, ask before