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.

peanut review: patch I2V memory overlap + identify signals by name

mrbizarro93889f641a09
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index d169be4..2059b3b 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -1019,18 +1019,37 @@ class WarmHelper:
raise RuntimeError(f"helper stdin closed: {exc}")
ev = self._read_until(["done", "error", "exit"])
if ev is None:
- # Silent death — no exit event, no Python error, just stdout pipe
- # closing. This is the OOM / SIGKILL / Metal-segfault fingerprint
- # because nothing else can kill the helper without giving Python
- # a chance to emit "exit" or "error". The atexit handler emits
- # "python_normal_exit" on normal shutdown; the SIGTERM handler
- # emits "sigterm(...)" before exit. If we get nothing at all,
- # SIGKILL or hard fault is the only explanation.
+ # Pipe closed without an event. peanut review correction: don't
+ # claim "SIGKILL" with certainty — could be SIGKILL (OOM jetsam),
+ # SIGSEGV (Metal/MLX fault), SIGABRT (assertion), or any other
+ # native-level abort. Inspect proc.returncode to actually name
+ # the signal so users have a real datapoint to share.
+ proc = self.proc
+ rc = proc.poll() if proc else None
+ if rc is not None and rc < 0:
+ sig_num = -rc
+ try:
+ sig_name = signal.Signals(sig_num).name
+ except (ValueError, AttributeError):
+ sig_name = f"signal{sig_num}"
+ # Translate the common ones into intent — what the OS was
+ # likely telling us when it sent that signal.
+ hint = {
+ "SIGKILL": "out of memory (jetsam) or external kill — close memory-heavy apps and retry",
+ "SIGSEGV": "native segfault inside MLX/Metal — share the crashlog at ~/Library/Logs/DiagnosticReports/python3.11_*.crash",
+ "SIGABRT": "C-level assertion failed — share the crashlog as above",
+ "SIGBUS": "memory access fault — could indicate a Metal driver issue or a bad weight file",
+ }.get(sig_name, "external kill")
+ raise RuntimeError(
+ f"helper exited from {sig_name} ({hint}); returncode={rc}"
+ )
+ # rc is None (still running but pipe closed?) or rc >= 0
+ # (graceful exit but missed the event). Both are unusual.
raise RuntimeError(
- "helper killed by the OS (likely out of memory or a Metal fault). "
- "No Python exception was emitted before the helper died — that's "
- "the SIGKILL signature. Close memory-heavy apps and retry, "
- "or switch to Draft quality."
+ f"helper pipe closed without an event; returncode={rc}. "
+ "Check the panel log for the last step:* breadcrumb to see "
+ "which phase died, and the crashlog at "
+ "~/Library/Logs/DiagnosticReports/python3.11_*.crash if any."
)
if ev.get("event") == "error":
raise RuntimeError(ev.get("error", "helper error"))
@@ -3772,13 +3791,23 @@ async function poll() {
const raw = (last.error || 'unknown error');
const rawLower = raw.toLowerCase();
let friendly, hint;
- if (rawLower.includes('killed by the os') || rawLower.includes('sigkill') ||
- rawLower.includes('helper died') || rawLower.includes('helper exited')) {
- friendly = 'Helper killed by the OS — likely out of memory.';
- hint = 'Close memory-heavy apps (Chrome, Slack, iOS Simulator) and try again. ' +
- 'Or switch Quality to Draft, which uses about half the RAM. ' +
- 'If it keeps happening, check ~/Library/Logs/DiagnosticReports/ for ' +
- 'a crash report named python3.11_*.crash and share it on the GitHub repo.';
+ if (rawLower.includes('sigkill')) {
+ friendly = 'Helper killed by the OS — out of memory (jetsam).';
+ hint = 'Close memory-heavy apps (Chrome, Slack, iOS Simulator) and try again, ' +
+ 'or switch Quality to Draft (about half the RAM).';
+ } else if (rawLower.includes('sigsegv') || rawLower.includes('sigbus')) {
+ friendly = 'Helper crashed at the native level (MLX/Metal fault).';
+ hint = 'Share the crashlog at ~/Library/Logs/DiagnosticReports/python3.11_*.crash ' +
+ 'on github.com/mrbizarro/phosphene/issues so we can fix it.';
+ } else if (rawLower.includes('sigabrt')) {
+ friendly = 'Helper hit a C-level assertion and aborted.';
+ hint = 'Share the crashlog at ~/Library/Logs/DiagnosticReports/python3.11_*.crash ' +
+ 'on github.com/mrbizarro/phosphene/issues.';
+ } else if (rawLower.includes('helper exited from') || rawLower.includes('helper pipe closed') ||
+ rawLower.includes('helper died') || rawLower.includes('helper exited')) {
+ friendly = 'Helper exited unexpectedly.';
+ hint = 'Check the log for the last "step:*" breadcrumb (tells us which ' +
+ 'phase died). If memory-pressured, close other apps and retry.';
} else if (rawLower.includes('q8') || rawLower.includes('keyframe')) {
friendly = 'This mode needs the Q8 model.';
hint = raw;
diff --git a/patch_ltx_codec.py b/patch_ltx_codec.py
index a8a0f73..6d981eb 100644
--- a/patch_ltx_codec.py
+++ b/patch_ltx_codec.py
@@ -101,6 +101,68 @@ PATCH_I2V_OOM_NEW = ''' video_latent, audio_latent = self.generate_from_i
return self._decode_and_save_video(video_latent, audio_latent, output_path)'''
+# ---- Patch 3: I2V free vae_encoder + feature_extractor BEFORE denoise --------
+# Credit: cocktailpeanut review. The existing Patch 2 only frees memory
+# right before the VAE *decode* step. By that point we've already paid the
+# peak: during the denoise loop we have DiT (~10.54 GiB Q4 / ~19 GiB Q8 dev)
+# + feature_extractor with connector (~5.91 GiB) + vae_encoder (still
+# resident because ImageToVideoPipeline.load() reloads it after super().
+# load() finishes) + denoise activations. That overlap is what kills the
+# helper "10 seconds in" silently.
+#
+# Fix: right after _encode_text_and_load() returns inside generate_from_image,
+# explicitly null out vae_encoder + feature_extractor. They aren't needed
+# during denoise — vae_encoder was used in step 1 and reload happens via
+# the I2V load(); feature_extractor only mattered for the text-encoding
+# step that just completed.
+PATCH_I2V_PREDENOISE_OLD = ''' # Step 2: Encode text, then load remaining components
+ video_embeds, audio_embeds = self._encode_text_and_load(prompt)
+ assert self.dit is not None'''
+PATCH_I2V_PREDENOISE_NEW = ''' # Step 2: Encode text, then load remaining components
+ video_embeds, audio_embeds = self._encode_text_and_load(prompt)
+
+ # PATCHED (LTX23MLX, peanut review): free vae_encoder +
+ # feature_extractor BEFORE the denoise loop, not just before VAE
+ # decode. The old patch (Patch 2) freed too late — denoise itself
+ # was the peak. With DiT (10.5 GB Q4) + connector (5.9 GB) + vae_enc
+ # + activations all overlapping during the loop, the helper was
+ # being SIGKILL'd by jetsam on memory-pressured Macs (cocktailpeanut
+ # repro: "I2V started, ~10s in stopped with no error").
+ if self.low_memory:
+ self.vae_encoder = None
+ self.feature_extractor = None
+ try:
+ from ltx_core_mlx.utils.memory import aggressive_cleanup as _cleanup
+ _cleanup()
+ except Exception:
+ pass
+
+ assert self.dit is not None'''
+
+# ---- Patch 4: Base load() also clears feature_extractor before DiT -----------
+# Same diagnosis. Base TextToVideoPipeline.load() only clears self.text_encoder
+# before loading the transformer; feature_extractor (which holds the connector,
+# ~5.9 GiB on Q4) stays resident through the DiT load. Two big weight blobs
+# coexisting in MLX memory at peak load is exactly the avoidable overlap.
+PATCH_BASE_LOAD_OLD = ''' # Stage 2: DiT (largest component — load after text encoding frees Gemma)
+ if self.dit is None:
+ if self.low_memory:
+ # Free text encoder before loading transformer to fit in RAM
+ self.text_encoder = None
+ aggressive_cleanup()'''
+PATCH_BASE_LOAD_NEW = ''' # Stage 2: DiT (largest component — load after text encoding frees Gemma)
+ if self.dit is None:
+ if self.low_memory:
+ # PATCHED (LTX23MLX, peanut review): also clear feature_extractor
+ # alongside text_encoder before loading the transformer. The
+ # connector lives inside feature_extractor (~5.9 GiB Q4) and
+ # without this it stays resident through the 10.5 GiB DiT load,
+ # peaking around 16+ GiB just for weights before activations.
+ self.text_encoder = None
+ self.feature_extractor = None
+ aggressive_cleanup()'''
+
+
# NOTE: Keyframe interpolation OOMs at the stage-1 → stage-2 transition on
# 64 GB Macs. We tried free-DiT-before-upscale + reload-after-upscale; that
# *didn't* help (the reload hit the same memory peak from a different angle
@@ -257,6 +319,46 @@ def main() -> int:
i2v_outcome = OUTCOME_ALREADY
outcomes.append(("I2V OOM (free DiT before decode)", i2v_outcome))
+ # Patch 3: free vae_encoder + feature_extractor BEFORE the I2V denoise loop.
+ # Same target file as Patch 2; different anchor. Optional like Patch 2 —
+ # if dgrauet refactors generate_from_image upstream this becomes a no-op
+ # warning instead of a hard install failure.
+ pre_outcome = apply_patch(
+ i2v_target, PATCH_I2V_PREDENOISE_OLD, PATCH_I2V_PREDENOISE_NEW,
+ marker="PATCHED (LTX23MLX, peanut review): free vae_encoder",
+ label="I2V free pre-denoise (peanut)",
+ )
+ if pre_outcome in (OUTCOME_DRIFT, OUTCOME_MISSING):
+ print(
+ " [I2V free pre-denoise] note: anchor not found — pipeline may have "
+ "been refactored upstream. Generation still works, just without the "
+ "memory-overlap cleanup. T2V users unaffected.",
+ file=sys.stderr,
+ )
+ pre_outcome = OUTCOME_ALREADY
+ outcomes.append(("I2V free pre-denoise (peanut)", pre_outcome))
+
+ # Patch 4: base TextToVideoPipeline.load() also clears feature_extractor
+ # alongside text_encoder before loading the transformer. Affects T2V/I2V/
+ # Extend — they all go through the same base load(). Strict subset of the
+ # peanut-review fix: even when generate_from_image has its own cleanup,
+ # the base load() reload-then-free-then-load-DiT path benefits from the
+ # extra clear (no point holding feature_extractor through a 10 GiB DiT load).
+ base_outcome = apply_patch(
+ i2v_target, PATCH_BASE_LOAD_OLD, PATCH_BASE_LOAD_NEW,
+ marker="PATCHED (LTX23MLX, peanut review): also clear feature_extractor",
+ label="base load() free feature_extractor (peanut)",
+ )
+ if base_outcome in (OUTCOME_DRIFT, OUTCOME_MISSING):
+ print(
+ " [base load() free feature_extractor] note: anchor not found — "
+ "base load() may have been refactored upstream. Memory peak slightly "
+ "higher than with this patch but generation is unaffected.",
+ file=sys.stderr,
+ )
+ base_outcome = OUTCOME_ALREADY
+ outcomes.append(("base load() free feature_extractor (peanut)", base_outcome))
+
# (Keyframe OOM patch was removed — see NOTE in the patches block above.
# The fix is currently a panel-side resolution clamp, not a pipeline edit.)