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.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.md
index 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).
## Overview
diff --git a/VERSION b/VERSION
index ad96464..0216ba3 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-4.10.1
+4.10.2
diff --git a/docs/STATE.md b/docs/STATE.md
index 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.py
index 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-switch
for 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, and
diff --git a/mlx_warm_helper.py b/mlx_warm_helper.py
index 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 loras
MODEL_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-insensitive
so [{a,1},{b,2}] and [{b,2},{a,1}] hash to the same set — fusing
is 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:
return
try:
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."})
+ return
mx.set_cache_limit(int(_MLX_CACHE_LIMIT))
except Exception as exc: # noqa: BLE001
if 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 own
diff --git a/test_low_ram_stream.py b/test_low_ram_stream.py
new file mode 100644
index 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.py
index 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())