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.10.2): Macs with 24 GB or less stream the video model from disk during a render
mrbizarro3f63e773eb5b
diff --git a/README.md b/README.mdindex 59b0693..57e557b 100644--- a/README.md+++ b/README.md@@ -19,7 +19,7 @@</p>-> **Current release: v4.10.1.** Continuity for one-takes: the light is locked in every beat, each part is measured, and a part whose light drifts is retaken once on its own. One take (a clip up to two minutes on either engine, written as beats), Turbo on the community's v4 adapter, a timeline that trims and moves like an NLE, anchor stills and long shots on the Storyboard, LoRA guides and update checks, closed-tab alerts, a light theme — and *The Commuter*, a 75 s one take rendered overnight at native, as the release film. Includes the v4.9.6–v4.9.8 fixes. Full notes on the [releases page](https://github.com/mrbizarro/phosphene/releases).+> **Current release: v4.10.2.** Macs with 24 GB of memory or less now stream the video model's blocks from disk during a render instead of holding the whole model resident. Measured on a 1024×576, 121-frame Image render: peak Metal memory 16.1 → 13.8 GB, only 1 GB held between phases instead of 10.6, about 7% slower, frames bit-identical — the margin that separates a 16 GB Mac finishing a clip from being killed mid-render. Renders that carry a LoRA or a trained character keep the exact previous path. `LTX_LOW_RAM_STREAM=1|0` in the environment forces it either way. Includes v4.10.1 (continuity for one-takes) and v4.10.0 (One take, Turbo v4, the NLE timeline, anchor stills). Full notes on the [releases page](https://github.com/mrbizarro/phosphene/releases).## Overviewdiff --git a/VERSION b/VERSIONindex ad96464..0216ba3 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-4.10.1+4.10.2diff --git a/docs/STATE.md b/docs/STATE.mdindex 29787b1..69c4f80 100644--- a/docs/STATE.md+++ b/docs/STATE.md@@ -1,5 +1,31 @@# Phosphene — project state, history, open work+> **🪶 2026-09-06 — low-RAM block streaming for ≤24 GB Macs (on dev, rides the next release).**+> The vendored engine already had `low_ram_streaming` (BlockStreamer); the+> helper never used it. Now `LTX_LOW_RAM_STREAM` (panel sets it when+> SYSTEM_RAM_GB ≤ 24; env forces either way) → t2v/i2v/extend pipelines get+> `low_ram_streaming=_stream_for(loras)`; LoRA jobs keep the exact unfused+> branch (the streamer cannot carry per-block adapters; the library refuses+> rather than fusing lossily on a quantized pack); the pipeline cache key+> carries the decision; apply_mlx_cache_policy keeps the Metal cache at 0+> while streaming; /status reports `low_ram_stream`. **Measured (64 GB Mac,+> forced on, Q4 Balanced i2v 1024×576×121, seed 4242):** denoise peak+> 16.13 → 13.77 GiB, active between phases 10.58 → 1.04 GiB, wall 141 →+> 151 s, frames bit-identical (framemd5) at 768×432×49 and 1024×576×121.+> `test_low_ram_stream.py`. RELEASE NOTE for whoever cuts 4.10.x next: "Macs+> with 24 GB or less stream the video model from disk during a render —+> peak memory 16.1 → 13.8 GB on a heavy Image render, ~7% slower, frames+> identical; renders with a LoRA/character keep the previous path."+> **AdaLN dedupe (upstream ltx-2-mlx #86/#119/#121) PARKED:** cherry-picked+> cleanly onto our fork (local branch `adaln-dedupe-0152` in ltx-2-mlx; 17+> upstream tests + 971 fork tests pass) and proven bitwise-identical on both+> canvases, but ZERO measured gain on our lane (142 vs 144 s, same peak) —+> our 2.5 i2v pins the reference by sample re-composition, not per-token+> timesteps, so there is nothing to dedupe. Revisit with the full rebase+> onto upstream 0.15.x (push to fork refused: a cherry-pick touches+> .github/workflows; token lacks `workflow` scope). Landscape research:+> ~/AI/projects/phosphene/notes/ltx25_landscape_2026-09-06.md.+> **🚀 2026-09-06 — v4.10.0 ships.** Everything on this branch since v4.9.5> goes public as one release: Editor v2 (transitions, speed, titles, the> Director + song map, retake, completion alerts, deliver-as, duplicate,diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex e59c8a5..9cf4e0c 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -247,6 +247,12 @@ STATS_HTML_FILE = ROOT / "panel_assets" / "stats.html"STATS_FETCHER = ROOT / "scripts" / "fetch_repo_stats.py"HELPER_IDLE_TIMEOUT = int(os.environ.get("LTX_HELPER_IDLE_TIMEOUT", "1800"))HELPER_LOW_MEMORY = os.environ.get("LTX_HELPER_LOW_MEMORY", "true")+# Low-RAM block streaming (v4.9.9): on Macs with 24 GB or less the helper+# streams transformer blocks from disk instead of holding the whole DiT+# resident — the 16 GB installs were the ones dying of jetsam mid-render.+# `LTX_LOW_RAM_STREAM=1|0` in the environment forces it either way (testing+# on a big Mac, or opting out); otherwise it is decided by physical RAM.+LOW_RAM_STREAM_RAM_GB = 24# Enhance is an interactive HTTP request, unlike renders that may legitimately# run for tens of minutes. Bound its helper wait below the UI/curl client's# 120-second ceiling so a silent helper still produces a JSON error response.@@ -11618,6 +11624,19 @@ def _settings_set_internal(**kv) -> None:pass+def low_ram_streaming_enabled() -> bool:+ """Whether renders on this Mac stream transformer blocks from disk."""+ forced = (os.environ.get("LTX_LOW_RAM_STREAM") or "").strip().lower()+ if forced in ("1", "true", "yes"):+ return True+ if forced in ("0", "false", "no"):+ return False+ try:+ return float(SYSTEM_RAM_GB or 0) <= LOW_RAM_STREAM_RAM_GB+ except (TypeError, ValueError):+ return False++def _analytics_enabled() -> bool:"""Master switch. Settings toggle (default ON), with an env kill-switchfor users who want it off before the panel ever writes a settings file@@ -13969,6 +13988,7 @@ class WarmHelper:env["LTX_ENHANCE_GEMMA"] = str(GEMMA)env["LTX_IDLE_TIMEOUT"] = str(HELPER_IDLE_TIMEOUT)env["LTX_LOW_MEMORY"] = HELPER_LOW_MEMORY+ env["LTX_LOW_RAM_STREAM"] = "1" if low_ram_streaming_enabled() else "0"env["LTX_ENABLE_MODEL_UPSCALE"] = "1" if MODEL_UPSCALE_ENABLED else "0"# Output codec env vars sourced from panel settings. The patched# ffmpeg call inside ltx_core_mlx reads these at job time, so@@ -14039,7 +14059,7 @@ class WarmHelper:self.ready_info = {k: ready.get(k) for k in ("ltx_version", "ltx_version_expected", "ltx_version_match",- "model", "gemma", "low_memory",+ "model", "gemma", "low_memory", "low_ram_stream","mlx_version", "mlx_metal_version", "chip", "macos",# THIS ALLOWLIST IS THE SEAM. A key the helper emits and# this tuple does not name is dropped here, silently, anddiff --git a/mlx_warm_helper.py b/mlx_warm_helper.pyindex 6b7a563..ce2fc67 100644--- a/mlx_warm_helper.py+++ b/mlx_warm_helper.py@@ -89,6 +89,19 @@ ENHANCE_GEMMA_PATH = os.environ.get()IDLE_TIMEOUT = int(os.environ.get("LTX_IDLE_TIMEOUT", "1800"))LOW_MEMORY = os.environ.get("LTX_LOW_MEMORY", "true").lower() in ("true", "1", "yes")+# Low-RAM block streaming (v4.9.9): stream transformer blocks from disk instead+# of holding the whole DiT resident. The panel sets this for small-memory Macs+# (see HELPER_LOW_RAM_STREAM in mlx_ltx_panel.py). Slower per step, far+# smaller peak — the difference between a 16 GB Mac finishing a clip and+# being jetsam-killed. Renders that carry LoRAs keep the exact unfused+# runtime branch and skip streaming (the streamer cannot carry per-block+# adapters; the library refuses rather than silently fusing on a quantized+# pack), so the flag is applied per pipeline, not blindly.+LOW_RAM_STREAM = os.environ.get("LTX_LOW_RAM_STREAM", "0").lower() in ("true", "1", "yes")+++def _stream_for(loras) -> bool:+ return bool(LOW_RAM_STREAM) and not lorasMODEL_UPSCALE_ENABLED = os.environ.get("LTX_ENABLE_MODEL_UPSCALE", "").lower() in ("1", "true", "yes", "on")# Y1.037 — VAE temporal-streaming decision.@@ -569,7 +582,7 @@ _extend_lora_key: tuple | None = None_extend_dev_name: str | None = None-def _lora_fingerprint(loras: list[dict] | None) -> tuple:+def _lora_fingerprint_base(loras: list[dict] | None) -> tuple:"""Stable hashable representation of a LoRA list. Order-insensitiveso [{a,1},{b,2}] and [{b,2},{a,1}] hash to the same set — fusingis commutative."""@@ -580,6 +593,13 @@ def _lora_fingerprint(loras: list[dict] | None) -> tuple:for l in loras))+def _lora_fingerprint(loras: list[dict] | None) -> tuple:+ """The pipeline cache key: the LoRA set AND whether this job streams+ blocks (v4.9.9). A LoRA-free job after a LoRA job must not reuse a+ pipeline built the other way round."""+ return _lora_fingerprint_base(loras) + (("stream",) if _stream_for(loras) else ())++def _resolve_lora_path(path: str) -> str:"""Resolve a LoRA path to a local .safetensors file.@@ -1286,6 +1306,7 @@ def get_pipe(kind: str, loras: list[dict] | None = None,"line": "Loading I2V pipeline (first job is the slow one)..."})pipe = ImageToVideoPipeline(model_dir=i2v_dir, gemma_model_id=GEMMA_PATH, low_memory=LOW_MEMORY,+ low_ram_streaming=_stream_for(loras),)_attach_loras(pipe, loras)_i2v_pipe = pipe@@ -1312,6 +1333,7 @@ def get_pipe(kind: str, loras: list[dict] | None = None,"line": f"Loading Extend pipeline (heavier — uses dev transformer at {ext_dir})..."})pipe = ExtendPipeline(model_dir=ext_dir, gemma_model_id=GEMMA_PATH, low_memory=LOW_MEMORY,+ low_ram_streaming=_stream_for(loras),dev_transformer=ext_dev,)_attach_loras(pipe, loras)@@ -1335,6 +1357,7 @@ def get_pipe(kind: str, loras: list[dict] | None = None,"line": "Loading T2V pipeline (first job is the slow one)..."})pipe = TextToVideoPipeline(model_dir=t2v_dir, gemma_model_id=GEMMA_PATH, low_memory=LOW_MEMORY,+ low_ram_streaming=_stream_for(loras),)_attach_loras(pipe, loras)_t2v_pipe = pipe@@ -2648,6 +2671,16 @@ def apply_mlx_cache_policy() -> None:returntry:import mlx.core as mx+ if LOW_RAM_STREAM:+ # Streaming only pays if freed block buffers actually leave the+ # heap; a retained cache re-pins them. Keep the pipeline's own+ # set_cache_limit(0) instead of re-asserting the fractional cap.+ mx.set_cache_limit(0)+ if not _MLX_CACHE_ANNOUNCED:+ _MLX_CACHE_ANNOUNCED = True+ emit({"event": "log",+ "line": "[mlx] low-RAM streaming: transformer blocks are read from disk as needed and the Metal cache is off — slower per step, far smaller peak."})+ returnmx.set_cache_limit(int(_MLX_CACHE_LIMIT))except Exception as exc: # noqa: BLE001if not _MLX_CACHE_ANNOUNCED:@@ -2718,6 +2751,7 @@ emit({"gemma4_tower_supported": (importlib.util.find_spec("ltx_core_mlx.text_encoders.gemma.gemma4")is not None),+ "low_ram_stream": bool(LOW_RAM_STREAM),"mlx_version": _RUNTIME_ENV.get("mlx"),"mlx_metal_version": _RUNTIME_ENV.get("mlx_metal"),# None when the policy is off (LTX_MLX_CACHE_GIB=off) — i.e. MLX's owndiff --git a/test_low_ram_stream.py b/test_low_ram_stream.pynew file mode 100644index 0000000..dd86067--- /dev/null+++ b/test_low_ram_stream.py@@ -0,0 +1,62 @@+"""v4.9.9: low-RAM block streaming — the helper streams transformer blocks+from disk on small-memory Macs. Pinned here: the per-job decision (LoRA jobs+keep the exact unfused branch and never stream), the pipeline cache key+carrying that decision, every t2v/i2v/extend constructor receiving it, and+the cache policy keeping the Metal cache off while streaming.++The helper is a script whose module body ends in a blocking stdin read, so+the functions under test are extracted with `ast` and exec'd, never+imported (same discipline as test_mlx_cache_policy.py)."""+import ast+import unittest+from pathlib import Path++HELPER = Path(__file__).with_name("mlx_warm_helper.py")+SRC = HELPER.read_text(encoding="utf-8")+++def _funcs(names: set[str], low_ram_stream: bool) -> dict:+ tree = ast.parse(SRC)+ picked = [n for n in tree.body if isinstance(n, ast.FunctionDef) and n.name in names]+ assert {n.name for n in picked} == names, f"missing {names - {n.name for n in picked}}"+ ns: dict = {"LOW_RAM_STREAM": low_ram_stream, "os": __import__("os")}+ exec(compile(ast.Module(body=picked, type_ignores=[]), str(HELPER), "exec"), ns)+ return ns+++class StreamingIsPerJob(unittest.TestCase):+ def test_lora_free_jobs_stream_only_when_enabled(self):+ on = _funcs({"_stream_for"}, True)+ off = _funcs({"_stream_for"}, False)+ self.assertTrue(on["_stream_for"]([]))+ self.assertTrue(on["_stream_for"](None))+ self.assertFalse(off["_stream_for"]([]))++ def test_lora_jobs_never_stream(self):+ on = _funcs({"_stream_for"}, True)+ self.assertFalse(on["_stream_for"]([{"path": "/x/a.safetensors", "strength": 1.0}]))++ def test_cache_key_carries_the_decision(self):+ ns = _funcs({"_stream_for", "_lora_fingerprint", "_lora_fingerprint_base"}, True)+ self.assertIn("stream", ns["_lora_fingerprint"]([]))+ self.assertNotIn("stream", ns["_lora_fingerprint"]([{"path": "/x/a.safetensors", "strength": 1.0}]))+ ns_off = _funcs({"_stream_for", "_lora_fingerprint", "_lora_fingerprint_base"}, False)+ self.assertNotIn("stream", ns_off["_lora_fingerprint"]([]))+++class EveryPipelineGetsTheFlag(unittest.TestCase):+ def test_t2v_i2v_extend_constructors_pass_low_ram_streaming(self):+ self.assertGreaterEqual(SRC.count("low_ram_streaming=_stream_for(loras)"), 3)+ for ctor in ("ImageToVideoPipeline(", "ExtendPipeline(", "TextToVideoPipeline("):+ i = SRC.index("pipe = " + ctor)+ self.assertIn("low_ram_streaming=_stream_for(loras)", SRC[i:i + 400], ctor)++ def test_cache_policy_keeps_the_cache_off_while_streaming(self):+ i = SRC.index("def apply_mlx_cache_policy")+ body = SRC[i:i + 2500]+ self.assertIn("if LOW_RAM_STREAM:", body)+ self.assertIn("mx.set_cache_limit(0)", body)+++if __name__ == "__main__":+ unittest.main()diff --git a/test_refusal_gates.py b/test_refusal_gates.pyindex 9f8d683..6714797 100644--- a/test_refusal_gates.py+++ b/test_refusal_gates.py@@ -506,3 +506,27 @@ class StepCountsNeverPadTheTable(unittest.TestCase):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))+++class LowRamStreamingDecision(unittest.TestCase):+ """v4.9.9: Macs with 24 GB or less stream transformer blocks from disk;+ the environment can force either way for testing or opting out."""++ def test_small_macs_stream_big_ones_do_not(self):+ with unittest.mock.patch.dict(os.environ, {"LTX_LOW_RAM_STREAM": ""}):+ with unittest.mock.patch.object(P, "SYSTEM_RAM_GB", 16.0):+ self.assertTrue(P.low_ram_streaming_enabled())+ with unittest.mock.patch.object(P, "SYSTEM_RAM_GB", 24.0):+ self.assertTrue(P.low_ram_streaming_enabled())+ with unittest.mock.patch.object(P, "SYSTEM_RAM_GB", 32.0):+ self.assertFalse(P.low_ram_streaming_enabled())+ with unittest.mock.patch.object(P, "SYSTEM_RAM_GB", 64.0):+ self.assertFalse(P.low_ram_streaming_enabled())++ def test_environment_forces_either_way(self):+ with unittest.mock.patch.object(P, "SYSTEM_RAM_GB", 64.0):+ with unittest.mock.patch.dict(os.environ, {"LTX_LOW_RAM_STREAM": "1"}):+ self.assertTrue(P.low_ram_streaming_enabled())+ with unittest.mock.patch.object(P, "SYSTEM_RAM_GB", 16.0):+ with unittest.mock.patch.dict(os.environ, {"LTX_LOW_RAM_STREAM": "0"}):+ self.assertFalse(P.low_ram_streaming_enabled())