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(v3.2.4): Ideogram runs on slower Apple GPUs (M1/M2)

mrbizarroedd84dc14c73
diff --git a/VERSION b/VERSION
index e4604e3..351227f 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-3.2.1
+3.2.4
diff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md
new file mode 100644
index 0000000..e22e526
--- /dev/null
+++ b/docs/RELEASE_CHECKLIST.md
@@ -0,0 +1,56 @@
+# Release checklist — DON'T ship broken
+
+Hard rule: **a release is not validated until it has been run FROM ZERO** — the
+state a brand-new user is in when they click Install in Pinokio. "It works on my
+machine" is not validation; my machine has every model cached, a token saved, and
+every dep already installed. New users have none of that. Most of the things that
+have shipped broken (gated model needing a token, mflux not bundled, the missing
+upscaler "mosaic", the scary pip dependency block) were invisible on a warm dev
+box and only showed up from zero.
+
+Run these BEFORE promoting `dev`/`beta` → public `main`. All must pass.
+
+## 1. Ideogram — from-zero render gate (the one that keeps biting us)
+
+```
+bash scripts/validate_ideogram_fresh.sh
+```
+
+It **deletes the Ideogram model** and re-renders with the un-gated mirror and
+**no Hugging Face token** — exactly a new user's first render. It fails loudly if:
+- `mflux-generate-ideogram4` is missing (install.js didn't bundle mflux),
+- the model can't download without a token (gating regressed),
+- the render crashes or produces no/empty PNG.
+
+Exit 0 = pass. Then **eyeball `/tmp/validate_ideo_fresh.png`** — the text must be
+legible (an auto-check can't tell crisp typography from a mosaic).
+
+## 2. Install scripts produce no scary errors
+
+The mflux pack must install via **uv, not plain pip** (mlx-vlm is `--no-deps`, so
+plain pip dumps an "ERROR: dependency resolver…" block that makes the update look
+broken). Grep to confirm no plain-pip mflux install slipped back in:
+
+```
+grep -n "pip install 'mflux" install.js update.js # expect NOTHING (all uv)
+node -c install.js && node -c update.js # syntax
+```
+
+## 3. Video modality smoke (when LTX/ltx-2-mlx is touched)
+
+Render T2V + I2V at Q4 and confirm no mosaic (frames, not just exit code). The
+mosaic was a missing `spatial_upscaler_x2_v1_1.safetensors` in the Q4 download —
+if you touch `required_files.json` / `install.js` / `update.js` model lists,
+re-confirm a fresh Q4 install pulls it.
+
+## 4. Version + compile
+
+```
+ltx-2-mlx/env/bin/python -m py_compile mlx_ltx_panel.py image_engine.py
+cat VERSION # bumped for this release
+```
+
+---
+
+When all pass, promote (`git push origin dev:main` + `gh release create`). If
+any fails, **do not ship** — that's the whole point of this file.
diff --git a/image_engine.py b/image_engine.py
index 0b26ff8..1d68647 100644
--- a/image_engine.py
+++ b/image_engine.py
@@ -280,6 +280,13 @@ ASPECT_DIMS = {
"9:16": (720, 1280),
"3:4": (768, 1024),
"21:9": (1280, 544),
+ # Small variants (value suffixed "s") — ~1/3–1/4 the pixels so weaker
+ # Apple GPUs render fast and stay under the Metal watchdog. The client
+ # CSS ratio uses parseFloat, which reads "9s" as 9, so the stage still
+ # shows the right shape. Requested by cocktailpeanut.
+ "16:9s": (768, 432),
+ "1:1s": (512, 512),
+ "9:16s": (432, 768),
}
@@ -738,7 +745,14 @@ def _generate_mflux(prompt: str, n: int, width: int, height: int,
# the prompt string VERBATIM to a temp .json and pass that path.
# - --steps / --guidance are warned-and-ignored (the preset defines
# them) so we omit them; the preset goes on --preset.
- # - no -q / quantization flag and no --image-paths (text-to-image).
+ # - --image-paths is unsupported (text-to-image).
+ # - -q defaults to 6 (the config builder passes mflux_quantize=6 for
+ # normal Ideogram, 4 for fast mode). Quantizing the fp8 weights on
+ # load gives smaller/faster GPU kernels — the only thing that helps
+ # slower Apple GPUs (M1/M2) clear the macOS Metal command-buffer
+ # watchdog (ml-explore/mlx#3267, wontfix). Raw fp8 (no -q) renders
+ # but is far slower and trips the watchdog on M1; q6 is the M1-safe
+ # default cocktailpeanut validated, q4 halves RAM again for ≤16 GB.
# The temp file is deleted in the `finally` after the subprocess ends
# (it must outlive the child, which reads it during model setup).
ideogram_prompt_file: str | None = None
@@ -757,8 +771,10 @@ def _generate_mflux(prompt: str, n: int, width: int, height: int,
"--width", str(width),
"--height", str(height),
"--preset", (config.mflux_preset or "V4_DEFAULT_20"),
- "--seed", *[str(s) for s in seeds],
]
+ if config.mflux_quantize: # None/0 → raw fp8; 4 → fast mode
+ cmd += ["-q", str(config.mflux_quantize)]
+ cmd += ["--seed", *[str(s) for s in seeds]]
else:
cmd = [
bin_path,
@@ -880,6 +896,17 @@ def _generate_mflux(prompt: str, n: int, width: int, height: int,
# qwen_edit: ~30 s @ 8 steps Q4 / ~5 min @ 30 steps Q8
# Plus the one-time load, plus first-run download.
env = _clean_subprocess_env()
+ # Ideogram (raw fp8 DiT) overruns the macOS Metal command-buffer
+ # watchdog on slower Apple GPUs — the subprocess aborts with
+ # kIOGPUCommandBufferCallbackErrorImpactingInteractivity / SIGABRT
+ # (exit -6). Disabling MLX's kernel compile and forcing fast Metal
+ # sync make MLX submit shorter command buffers that stay under the
+ # watchdog. Found by cocktailpeanut getting Ideogram to run on an
+ # M1 Max 64 GB (ml-explore/mlx#3267, upstream wontfix). Ideogram-only
+ # so the other mflux families keep mx.compile.
+ if fam == "ideogram":
+ env.setdefault("MLX_DISABLE_COMPILE", "1")
+ env.setdefault("MLX_METAL_FAST_SYNCH", "1")
# FBCache toggle for the Qwen-Edit transformer (skips middle blocks
# when the layer-0 residual is stable step-to-step). The patch is
# injected by patch_mflux_fbcache.py at install/update time and is
diff --git a/install.js b/install.js
index 0d12760..6234bb2 100644
--- a/install.js
+++ b/install.js
@@ -312,7 +312,7 @@ module.exports = {
// isn't yet on disk (warning + plain Python downloader).
env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },
message: [
- "hf download dgrauet/ltx-2.3-mlx-q4 --local-dir ../mlx_models/ltx-2.3-mlx-q4 --include '*.json' --include 'transformer-distilled.safetensors' --include 'connector.safetensors' --include 'vae_decoder.safetensors' --include 'vae_encoder.safetensors' --include 'audio_vae.safetensors' --include 'vocoder.safetensors'"
+ "hf download dgrauet/ltx-2.3-mlx-q4 --local-dir ../mlx_models/ltx-2.3-mlx-q4 --include '*.json' --include 'transformer-distilled.safetensors' --include 'connector.safetensors' --include 'vae_decoder.safetensors' --include 'vae_encoder.safetensors' --include 'audio_vae.safetensors' --include 'vocoder.safetensors' --include 'spatial_upscaler_x2_v1_1.safetensors'"
]
}
},
@@ -351,9 +351,15 @@ module.exports = {
params: {
message: [
"echo 'Installing the mflux image-engine pack (Ideogram 4 + Qwen-Edit)…' && \\",
- "( ./ltx-2-mlx/env/bin/pip install 'mflux==0.18.0' && \\",
- " ./ltx-2-mlx/env/bin/pip install --force-reinstall --no-deps 'mflux==0.18.0' && \\",
- " ./ltx-2-mlx/env/bin/pip install 'mlx-teacache==0.4.1' && \\",
+ // uv, NOT plain pip: mlx-vlm is installed --no-deps (to dodge its
+ // PIL>=10/av pins), which leaves its declared extras unsatisfied. Plain
+ // `pip install` then dumps a scary "ERROR: pip's dependency resolver…"
+ // block about mlx-vlm on EVERY later install — verified, and it made
+ // cocktailpeanut's update look broken. uv installs the same packages
+ // with zero such noise (same reason the base deps above use uv).
+ "( uv pip install --python ./ltx-2-mlx/env/bin/python 'mflux==0.18.0' && \\",
+ " uv pip install --python ./ltx-2-mlx/env/bin/python --reinstall --no-deps 'mflux==0.18.0' && \\",
+ " uv pip install --python ./ltx-2-mlx/env/bin/python 'mlx-teacache==0.4.1' && \\",
" ./ltx-2-mlx/env/bin/python3.11 patch_mflux_fbcache.py ) \\",
"|| echo 'WARN: mflux image-engine install hit an error — video still works; use the Reinstall image engines action to retry image generation.'"
].join("\n")
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index b0cf9dc..37c81c2 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -5364,7 +5364,7 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,
if not prompt:
prompt = "A cinematic atmospheric scene"
try:
- n = max(1, min(8, int(f("n", "4") or 4)))
+ n = max(1, min(8, int(f("n", "1") or 1)))
except (TypeError, ValueError):
n = 4
try:
@@ -5707,14 +5707,14 @@ _PREFLIGHT_BASE_GB: dict[tuple[str, int], float] = {
("qwen_edit", 4): 18.0,
("qwen_edit", 6): 24.0,
("qwen_edit", 8): 32.0,
- # Ideogram 4 fp8 — 9.3B fp8 DiT + 8B Qwen3-VL text encoder, ~28 GB on
- # disk. The fp8 weights aren't re-quantized by us (no -q flag on the
- # ideogram4 CLI), so the quantize key is nominal — every row maps to the
- # same ~24-28 GB peak Metal residency. We list 4/6/8 so the (family,
- # quantize) lookup hits exactly regardless of the dataclass default (6).
- ("ideogram", 4): 26.0,
- ("ideogram", 6): 26.0,
- ("ideogram", 8): 28.0,
+ # Ideogram 4 — 9.3B fp8 DiT + 8B text encoder, quantized on load. The
+ # default is now -q 6 (M1-safe); -q 4 is fast mode for ≤16 GB Macs.
+ # Numbers cocktailpeanut validated getting it to run on an M1 Max 64 GB:
+ # q6 (default) ~24 GB, q4 ~18 GB, q8 ~32 GB. The lookup keys on
+ # mflux_quantize (or 6), so the default render path resolves to the q6 row.
+ ("ideogram", 4): 18.0,
+ ("ideogram", 6): 24.0,
+ ("ideogram", 8): 32.0,
# FLUX.2 — distilled 4B and base 4B/9B variants
("flux2", 4): 6.0,
("flux2", 6): 8.0,
@@ -5885,7 +5885,7 @@ def run_image_job_inner(job: dict) -> None:
engine_override = (p.get("engine_override") or "auto").lower()
aspect = (p.get("aspect") or "16:9").strip() or "16:9"
try:
- n = max(1, min(8, int(p.get("n") or 4)))
+ n = max(1, min(8, int(p.get("n") or 1)))
except (TypeError, ValueError):
n = 4
try:
@@ -7976,11 +7976,18 @@ def _build_image_engine_config(
# (V4_DEFAULT_20 / V4_TURBO_12 / V4_QUALITY_48) into `mflux_preset`.
if engine_override == "ideogram4_inline":
_ideo_preset = str(form.get("ideo_preset") or "V4_DEFAULT_20").strip() or "V4_DEFAULT_20"
+ # Quantize level for the fp8 weights. Default 6 — the M1-safe level
+ # cocktailpeanut validated (raw fp8 trips the macOS Metal watchdog
+ # and is far slower on M1/M2). Fast mode sends ideo_quantize=4 →
+ # smaller/faster kernels + ~half the RAM for ≤16 GB Macs.
+ _ideo_q = str(form.get("ideo_quantize") or "").strip()
+ _ideo_quantize = int(_ideo_q) if _ideo_q in ("3", "4", "5", "6", "8") else 6
return agent_image_engine.ImageEngineConfig(
kind="mflux",
mflux_model=_resolve_ideogram_repo(), # un-gated mirror unless official already cached
mflux_family="ideogram",
mflux_preset=_ideo_preset,
+ mflux_quantize=_ideo_quantize, # 6 → M1-safe default; 4 → fast mode
mflux_lora_paths=[],
mflux_lora_scales=[],
)
@@ -11718,9 +11725,40 @@ class Handler(BaseHTTPRequestHandler):
# only so no cross-platform branch needed.
if path == "/output/open_folder":
try:
- target_dir = OUTPUT.resolve()
- subprocess.run(["open", str(target_dir)], check=False)
- self._json({"ok": True, "opened": str(target_dir)})
+ # Reveal the folder that actually holds the user's LATEST
+ # output. Videos land under OUTPUT (mlx_outputs); images land
+ # under UPLOADS/library/manual/<date>/. Always opening OUTPUT
+ # showed an empty Finder window to anyone whose last render
+ # was an image (reported by cocktailpeanut). Find the newest
+ # file across both roots and `open -R` it so Finder opens the
+ # right folder with that file selected.
+ roots = [OUTPUT, UPLOADS / "library" / "manual"]
+ newest_file = None
+ newest_mtime = -1.0
+ for _root in roots:
+ if not _root.is_dir():
+ continue
+ for _p in _root.rglob("*"):
+ # Skip dotfiles and .json sidecars so `open -R` selects
+ # the actual render (png/mp4), not its metadata twin.
+ if (not _p.is_file() or _p.name.startswith(".")
+ or _p.suffix.lower() == ".json"):
+ continue
+ try:
+ _mt = _p.stat().st_mtime
+ except OSError:
+ continue
+ if _mt > newest_mtime:
+ newest_mtime, newest_file = _mt, _p
+ if newest_file is not None:
+ subprocess.run(["open", "-R", str(newest_file)], check=False)
+ self._json({"ok": True, "opened": str(newest_file.parent)})
+ else:
+ # Nothing rendered yet — open OUTPUT (create if missing).
+ target_dir = OUTPUT.resolve()
+ target_dir.mkdir(parents=True, exist_ok=True)
+ subprocess.run(["open", str(target_dir)], check=False)
+ self._json({"ok": True, "opened": str(target_dir)})
except Exception as e:
self._json({"error": f"open failed: {e}"}, 500)
return
@@ -12579,6 +12617,18 @@ _DENOISE_RE = re.compile(
r"Denoising(\s*\([^)]*\))?:[^|]*\|[^|]*\|\s*(\d+)\s*/\s*(\d+)"
)
_PER_IT_RE = re.compile(r"(\d+(?:\.\d+)?)\s*s/it")
+# Image engines (mflux / Ideogram) stream a plain tqdm bar with no
+# "Denoising" desc, prefixed `[image] ` by the panel:
+# `[image] 65%|████▌ | 13/20 [12:23<07:37, 65.39s/it]`
+# Capture step/total so the Now card shows real image progress instead of
+# sitting on "Loading pipeline" — the image job never emits the LTX helper's
+# step:get_pipe markers, so without this its phase never leaves setup.
+# (Reported by cocktailpeanut.) The leading `\d+%` (bar starts with a bare
+# percentage) is deliberate: it matches the denoise bar but NOT the model
+# download bars, which carry a desc — `[image] Fetching 16 files: 0%|...`
+# or `[image] model.safetensors: 45%|...` — so download progress is never
+# mistaken for denoise steps.
+_IMAGE_STEP_RE = re.compile(r"\[image\]\s+\d+%\|[^|]*\|\s*(\d+)\s*/\s*(\d+)")
def _parse_progress_signals(log_lines: list[str]) -> dict:
@@ -12597,6 +12647,7 @@ def _parse_progress_signals(log_lines: list[str]) -> dict:
"""
stage1_step = stage1_total = None # latest seen for stage 1
stage2_step = stage2_total = None # latest seen for stage 2
+ image_step = image_total = None # latest seen for an mflux image job
last_per_it = None
decode_started = decode_done = generate_done = upscale_done = pipe_loaded = False
for ln in reversed(log_lines or []):
@@ -12625,6 +12676,16 @@ def _parse_progress_signals(log_lines: list[str]) -> dict:
pit = _PER_IT_RE.search(ln)
if pit:
last_per_it = float(pit.group(1))
+ # mflux image job — a single plain tqdm bar (no two-stage). Seeing
+ # it stepping means the model is resident, so flip pipe_loaded too.
+ mi = _IMAGE_STEP_RE.search(ln)
+ if mi and image_step is None:
+ image_step, image_total = int(mi.group(1)), int(mi.group(2))
+ pipe_loaded = True
+ if last_per_it is None:
+ pit = _PER_IT_RE.search(ln)
+ if pit:
+ last_per_it = float(pit.group(1))
if not decode_started and "step:decode_and_save start" in ln:
decode_started = True
if not decode_done and "step:decode_and_save done" in ln:
@@ -12654,6 +12715,11 @@ def _parse_progress_signals(log_lines: list[str]) -> dict:
else:
denoise_step = denoise_total = None
+ # An mflux image job has one tqdm bar (no stages); if we saw image
+ # steps, they ARE the denoise counter — overrides the stage logic.
+ if image_step is not None:
+ denoise_step, denoise_total = image_step, image_total
+
return {
"denoise_step": denoise_step,
"denoise_total": denoise_total,
@@ -20316,6 +20382,14 @@ HTML = r"""<!doctype html>
</div>
</div>
+ <!-- Fast mode: opt-in 4-bit quantize. The fix for slower Apple GPUs
+ (M1/M2) where the full fp8 model trips the macOS Metal watchdog
+ (ml-explore/mlx#3267), and ~half the RAM. Sends ideo_quantize=4. -->
+ <label class="ideo-fastmode" title="Quantize the model to 4-bit on load — much faster on M1/M2 GPUs (clears the macOS Metal command-buffer watchdog) and roughly half the RAM. Slightly lower quality; leave off on M3/M4." style="display:flex;align-items:center;gap:8px;margin-top:10px;padding:8px 11px;border:1px solid var(--border);border-radius:var(--r-sm);background:var(--panel-2);font-size:12.5px;color:var(--muted,#9aa6bd);cursor:pointer">
+ <input type="checkbox" id="ideoFastMode" onchange="ideoState.fast=this.checked" style="accent-color:var(--accent);cursor:pointer;flex:0 0 auto;width:16px;height:16px;margin:0">
+ <span><strong style="color:var(--text)">⚡ Fast mode</strong> &mdash; 4-bit, for M1/M2 or low-RAM Macs <em>(slightly lower quality)</em></span>
+ </label>
+
<!-- Image-level palette (collapsible). ≤16 colors. -->
<details class="ideo-details" id="ideoPaletteDetails">
<summary>Image palette <span class="ideo-summary-meta" id="ideoPaletteCount"></span></summary>
@@ -20397,11 +20471,16 @@ HTML = r"""<!doctype html>
<option value="9:16">9:16 — 720×1280</option>
<option value="3:4">3:4 — 768×1024</option>
<option value="21:9">21:9 — 1280×544</option>
+ <optgroup label="Smaller — faster, lower RAM">
+ <option value="16:9s">16:9 — 768×432</option>
+ <option value="1:1s">1:1 — 512×512</option>
+ <option value="9:16s">9:16 — 432×768</option>
+ </optgroup>
</select>
</div>
<div class="mf-cell">
<span class="mf-label">Candidates (n)</span>
- <input type="number" id="imgStudioN" min="1" max="8" value="4" oninput="imgStudioUpdateEstimate()">
+ <input type="number" id="imgStudioN" min="1" max="8" value="1" oninput="imgStudioUpdateEstimate()">
</div>
<div class="mf-cell">
<span class="mf-label">Seed</span>
@@ -22794,8 +22873,8 @@ function imgStudioUpdateEstimate() {
const btnLabel = document.getElementById('imgStudioGenBtnLabel');
if (!out || !btnLabel) return;
const eng = (document.getElementById('imgStudioEngine') || {}).value || 'auto';
- const n = parseInt((document.getElementById('imgStudioN') || {}).value || '4', 10);
- const safeN = Math.max(1, Math.min(8, isFinite(n) ? n : 4));
+ const n = parseInt((document.getElementById('imgStudioN') || {}).value || '1', 10);
+ const safeN = Math.max(1, Math.min(8, isFinite(n) ? n : 1));
// Wall-time = cold_start (paid once per batch) + n × per-image (denoise).
// /image/engine_status returns both fields. The HiDream lab subprocess
// pays ~45s cold load per batch (BF16 weights -> MLX); mflux engines
@@ -22938,6 +23017,7 @@ const ideoState = {
history: [],
_editing: false, // a text input is focused (don't steal keys)
_editId: null, // box currently being edited inline on the canvas
+ fast: false, // Fast mode → 4-bit quantize (slower-GPU / low-RAM)
_seq: 1,
};
@@ -24086,11 +24166,14 @@ async function imgStudioGenerate() {
const refs = IMG_STUDIO.refs.filter(r => r && r.path).map(r => r.path);
const body = {
prompt,
- n: parseInt(document.getElementById('imgStudioN').value || '4', 10),
+ n: parseInt(document.getElementById('imgStudioN').value || '1', 10),
aspect: document.getElementById('imgStudioAspect').value || '16:9',
seed: parseInt(document.getElementById('imgStudioSeed').value || '-1', 10),
engine_override: engineVal,
ideo_preset: ideoPreset,
+ // Fast mode → 4-bit quantize (Ideogram only). Null otherwise so the
+ // server applies its M1-safe q6 default.
+ ideo_quantize: (engineVal === 'ideogram4_inline' && typeof ideoState === 'object' && ideoState.fast) ? 4 : null,
refs,
};
// Submit through the same /queue/add endpoint video jobs use, with
@@ -24114,8 +24197,9 @@ async function imgStudioGenerate() {
// Ideogram 4 sampler preset — only meaningful for ideogram4_inline;
// _build_image_engine_config reads it into ImageEngineConfig.mflux_preset.
if (body.ideo_preset) fd.set('ideo_preset', body.ideo_preset);
+ if (body.ideo_quantize) fd.set('ideo_quantize', String(body.ideo_quantize));
fd.set('aspect', body.aspect || '16:9');
- fd.set('n', String(body.n || 4));
+ fd.set('n', String(body.n || 1));
fd.set('seed', String(body.seed != null ? body.seed : -1));
// refs is a list of paths — the existing /image/generate code
// accepts a JSON-encoded list as a form field, and make_job()
diff --git a/scripts/validate_ideogram_fresh.sh b/scripts/validate_ideogram_fresh.sh
new file mode 100755
index 0000000..d9d0a96
--- /dev/null
+++ b/scripts/validate_ideogram_fresh.sh
@@ -0,0 +1,61 @@
+#!/bin/bash
+# ---------------------------------------------------------------------------
+# validate_ideogram_fresh.sh — FROM-ZERO Ideogram release gate.
+#
+# Reproduces a brand-new user's very first Ideogram render: DELETE the model,
+# then download + render with NO Hugging Face token (the un-gated mirror) on the
+# real cache the panel uses. Catches the things that have shipped broken before:
+# - model gated / needs a token → download must work token-less
+# - mflux / ideogram CLI missing → mflux-generate-ideogram4 must exist
+# - render crash / garbled output → must produce a real PNG
+#
+# RUN THIS BEFORE PROMOTING ANY IDEOGRAM-AFFECTING RELEASE TO PUBLIC.
+# Exit 0 = PASS. Non-zero = do NOT ship.
+# ---------------------------------------------------------------------------
+set -uo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+HFH="$ROOT/cache/HF_HOME"
+VENV="$ROOT/ltx-2-mlx/env"
+MIRROR="cocktailpeanut/ideogram-4-fp8"
+OUT="/tmp/validate_ideo_fresh.png"
+CAP="/tmp/validate_ideo_caption.json"
+
+echo "== 1. mflux + ideogram CLI present? =="
+[ -x "$VENV/bin/mflux-generate-ideogram4" ] || { echo "FAIL: mflux-generate-ideogram4 missing — install.js didn't bundle mflux"; exit 2; }
+"$VENV/bin/mflux-generate-ideogram4" --help >/dev/null 2>&1 || { echo "FAIL: ideogram CLI not runnable"; exit 2; }
+echo " ok"
+
+echo "== 2. DELETE the model (force a fresh download) =="
+rm -rf "$HFH/hub/models--ideogram-ai--ideogram-4-fp8" \
+ "$HFH/hub/models--cocktailpeanut--ideogram-4-fp8"
+echo " deleted"
+
+echo "== 3. fresh render: un-gated mirror, NO HF token =="
+cat > "$CAP" <<'J'
+{"high_level_description":"A bold typographic poster reading FRESH INSTALL on a deep purple background.","compositional_deconstruction":{"background":"A deep purple to black gradient background.","elements":[{"type":"text","bbox":[360,80,560,920],"text":"FRESH INSTALL","desc":"a huge bold white headline, centered","color_palette":["#FFFFFF"]},{"type":"text","bbox":[600,250,680,750],"text":"no token needed","desc":"a small cyan subtitle, centered","color_palette":["#43E0FF"]}]}}
+J
+rm -f "$OUT"
+export HF_HOME="$HFH"
+unset HF_TOKEN HUGGING_FACE_HUB_TOKEN # a brand-new user has no token
+unset HF_HUB_OFFLINE # must be allowed to download
+export HF_HUB_ENABLE_HF_TRANSFER=1
+export SSL_CERT_FILE="$VENV/lib/python3.11/site-packages/certifi/cacert.pem"
+export REQUESTS_CA_BUNDLE="$SSL_CERT_FILE"
+T0=$(python3 -c 'import time;print(int(time.time()))')
+"$VENV/bin/mflux-generate-ideogram4" \
+ --model "$MIRROR" --base-model ideogram4 \
+ --prompt-file "$CAP" --output "$OUT" \
+ --width 1280 --height 720 --preset V4_TURBO_12 --seed 7 2>&1 | tail -25
+RC=${PIPESTATUS[0]}
+T1=$(python3 -c 'import time;print(int(time.time()))')
+
+echo "== 4. verify output =="
+if [ "$RC" -ne 0 ]; then echo "FAIL: render exited $RC"; exit 3; fi
+if [ ! -f "$OUT" ]; then echo "FAIL: no PNG produced"; exit 3; fi
+DIMS=$("$VENV/bin/python" -c "from PIL import Image;im=Image.open('$OUT');print(f'{im.width}x{im.height}')" 2>/dev/null)
+SZ=$(stat -f%z "$OUT" 2>/dev/null)
+echo " PNG: $DIMS, ${SZ} bytes, $(( T1 - T0 ))s total (incl. fresh download)"
+[ "${SZ:-0}" -gt 50000 ] || { echo "FAIL: PNG suspiciously small"; exit 3; }
+echo ""
+echo "PASS — fresh, token-less Ideogram install renders. Eyeball $OUT for legible text."
diff --git a/update.js b/update.js
index 05dd041..3caf1a1 100644
--- a/update.js
+++ b/update.js
@@ -209,10 +209,15 @@ module.exports = {
// Two-step (WITH deps then --force-reinstall --no-deps) mirrors
// install_qwen.js so the full transitive set (transformers, accelerate,
// sentencepiece, …) resolves, then the version is locked.
+ // uv, NOT plain pip: mlx-vlm is installed --no-deps, so plain pip dumps
+ // a scary "ERROR: pip's dependency resolver…" block about mlx-vlm's
+ // unsatisfied extras on every install (verified — this is what made
+ // cocktailpeanut's update look broken even though mflux installed fine).
+ // uv does the same install with zero such noise.
"echo 'Installing/refreshing the mflux image-engine pack (Ideogram 4 + Qwen-Edit) — now standard…' && \\",
- "( ./ltx-2-mlx/env/bin/pip install 'mflux==0.18.0' && \\",
- " ./ltx-2-mlx/env/bin/pip install --force-reinstall --no-deps 'mflux==0.18.0' && \\",
- " ./ltx-2-mlx/env/bin/pip install 'mlx-teacache==0.4.1' ) \\",
+ "( uv pip install --python ./ltx-2-mlx/env/bin/python 'mflux==0.18.0' && \\",
+ " uv pip install --python ./ltx-2-mlx/env/bin/python --reinstall --no-deps 'mflux==0.18.0' && \\",
+ " uv pip install --python ./ltx-2-mlx/env/bin/python 'mlx-teacache==0.4.1' ) \\",
"|| echo 'WARN: mflux image-engine install hit an error — video is unaffected; re-run Update, or use the Reinstall image engines action, to retry.'"
].join("\n")
}
@@ -254,6 +259,29 @@ module.exports = {
// training install on every panel update — users who clicked
// Download Q8 dev for training and then Update would lose 11 GB of
// bandwidth and have to re-download.
+ // ---- Mosaic fix (2026-06-13) -----------------------------------------
+ // The Q4 render path is two-stage: it upscales the half-res latent with
+ // spatial_upscaler_x2_v1_1.safetensors. The Y1.024 download allowlist
+ // dropped that file, so affected Q4 installs silently ran a
+ // RANDOMLY-INITIALISED upsampler -> the "mosaic"/rainbow-grid (#23; root
+ // cause found by @dgrauet, who also made ltx-pipelines-mlx fail loud about
+ // it upstream). It's back in required_files.json (verify/repair flags it),
+ // and fetched here so existing users self-heal on Update without clicking
+ // Repair. ~1 GB, resumable; hf skips it when already present. BEST-EFFORT —
+ // a network hiccup must not fail the update.
+ {
+ method: "shell.run",
+ params: {
+ venv: "env",
+ path: "ltx-2-mlx",
+ env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },
+ message: [
+ "echo 'Ensuring the Q4 spatial upscaler is present (mosaic fix)…' && \\",
+ "hf download dgrauet/ltx-2.3-mlx-q4 --local-dir ../mlx_models/ltx-2.3-mlx-q4 --include 'spatial_upscaler_x2_v1_1.safetensors' \\",
+ "|| echo 'WARN: spatial upscaler fetch failed — open the panel and click Repair to retry (fixes the mosaic).'"
+ ].join("\n")
+ }
+ },
{
method: "shell.run",
params: {