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.

feat(image): Qwen-Edit Lightning as universal default (E2)

mrbizarroeca173a4b411
diff --git a/image_engine.py b/image_engine.py
index c63e372..7cfb102 100644
--- a/image_engine.py
+++ b/image_engine.py
@@ -197,7 +197,7 @@ class ImageEngineConfig:
mflux_model: str = "Runpod/FLUX.2-klein-4B-mflux-4bit"
mflux_family: str = "auto" # "auto" or one of the family ids above
mflux_base_model: str = "" # only needed when mflux_model is a path/HF id and family inference can't tell the architecture
- mflux_steps: int = 0 # 0 = use family default (4/9/25 per family)
+ mflux_steps: int = 4 # Lightning 4-step default (was 0 = family default). The default Lightning LoRA below is distilled for 4 steps; the auto-promote in mlx_ltx_panel.py picks this up when promoting mock/legacy configs onto qwen_edit. Non-Lightning families ignore this and use the family default in MFLUX_FAMILY_DEFAULTS via the `eff_steps = config.mflux_steps if config.mflux_steps > 0 else ...` path in _generate_mflux — set this back to 0 to force the family default.
mflux_quantize: int = 6 # 3 | 4 | 5 | 6 | 8 — Q6 is the Apple-Silicon community sweet spot (~4-6% quality loss vs full precision; Q4 is 8-12%). Draw Things uses Q6/Q5 by default. Q4 only matters on ≤16 GB Macs; on 64 GB M4 Max the speed gap is negligible and the quality jump is visible.
mflux_guidance: float | None = None # None = use family default (1.0 / 0.0 / 4.5 / 5.0 per family)
mflux_python_path: str = "" # optional override for the mflux CLI location
@@ -208,8 +208,22 @@ class ImageEngineConfig:
# rejects the mismatch). Each path is a HuggingFace repo id, a
# collection-format string (`repo:filename.safetensors`), or a
# local file path.
- mflux_lora_paths: list[str] = field(default_factory=list)
- mflux_lora_scales: list[float] = field(default_factory=list)
+ #
+ # DEFAULT shipped 2026-05-26 (E2): bake the Lightning 4-step LoRA in
+ # so a fresh ImageEngineConfig() — and any v2.x upgrade promoted by
+ # _auto_promote_image_engine_kind — lands on the ~1:20-per-image tier
+ # out of the box instead of the legacy ~2:35 8-step path. Lightning
+ # was distilled for scale 1.0 — don't change it. Only applies when
+ # the resolved family is qwen_edit; other families silently skip the
+ # LoRA flags because mflux's non-qwen CLIs reject Lightning entries
+ # on unrelated architectures. (No-op for the FLUX.2 / Z-Image / FIBO
+ # paths because _resolve_mflux_family returns flux2/etc. and the
+ # auto-promote rewrites the whole config — model + family + steps +
+ # loras — when a real engine binary is detected on PATH.)
+ mflux_lora_paths: list[str] = field(default_factory=lambda: [
+ "lightx2v/Qwen-Image-Edit-2511-Lightning:Qwen-Image-Edit-2511-Lightning-4steps-V1.0-bf16.safetensors"
+ ])
+ mflux_lora_scales: list[float] = field(default_factory=lambda: [1.0])
# HiDream-O1-Image-Dev (BF16 MLX) — runs out of a separate lab venv outside
# Phosphene's tree. Subprocess pattern; we never import mlx-vlm into
@@ -642,6 +656,7 @@ def _generate_mflux(prompt: str, n: int, width: int, height: int,
import os
import random
import subprocess
+ import sys # sys.executable used by the TeaCache wrap fallback below
bin_path = _resolve_mflux_bin(config)
fam = _resolve_mflux_family(config)
@@ -796,10 +811,51 @@ def _generate_mflux(prompt: str, n: int, width: int, height: int,
env["MFLUX_FB_CACHE"] = "1"
env.setdefault("MFLUX_FB_THRESHOLD", "0.15")
env.setdefault("MFLUX_FB_KEEP_LAST", "8")
+ # TeaCache wrap for FLUX.2 (mlx-teacache 0.4.1, github.com/IonDen/
+ # mlx-teacache, MIT). Skip-decodes ~3/25 timesteps on the base
+ # 25-step Klein at SSIM>0.99 and ~1.25x on the distilled 4-step path
+ # (mostly mx.compile avoid). Default on — set MFLUX_TC_FLUX=0 to
+ # bypass. We export the env var unconditionally so the wrapper
+ # subprocess sees the threshold; the wrapper itself decides whether
+ # to wrap based on MFLUX_TC_FLUX. The bin_path swap below is what
+ # actually launches the wrapper instead of bare mflux-generate-flux2.
+ if fam == "flux2" and os.environ.get("MFLUX_TC_FLUX", "1").strip().lower() not in ("0", "false", "no"):
+ env["MFLUX_TC_FLUX"] = "1"
+ env.setdefault("MFLUX_TC_FLUX_THRESH", "0.20")
per_image_budget = 60 if fam in ("flux2", "z_image_turbo") else 360
cold_start_budget = 240 if fam in ("flux2", "z_image_turbo") else 1800
timeout_s = cold_start_budget + per_image_budget * n
+ # TeaCache bin-path swap: when wrapping is on, the subprocess command
+ # becomes `<venv-python> run_mflux_with_teacache.py <args...>` instead
+ # of the bare CLI. The wrapper imports mlx_teacache + monkey-patches
+ # Flux2Klein.generate_image to enter apply_teacache, then defers to
+ # mflux's own flux2_generate.main() with sys.argv intact — so the
+ # argv contract (--model / --prompt / --output / --steps / --lora-
+ # paths / ...) is exactly what bare mflux expects. If the import or
+ # patch fails the wrapper itself shells back out to the bare CLI, so
+ # there's no scenario where this swap loses a render — only the
+ # speedup.
+ if fam == "flux2" and env.get("MFLUX_TC_FLUX") == "1":
+ # bin_path is .../ltx-2-mlx/env/bin/mflux-generate-flux2; the
+ # corresponding python is the sibling python3 in the same bin/.
+ # Use sys.executable as a sanity fallback if the inferred path
+ # doesn't exist (e.g. the user has a non-standard mflux install
+ # via mflux_python_path that lives outside our venv layout).
+ bin_dir = Path(bin_path).parent
+ venv_py = bin_dir / "python3"
+ if not venv_py.is_file():
+ venv_py = bin_dir / "python"
+ if not venv_py.is_file():
+ venv_py = Path(sys.executable)
+ wrapper = Path(__file__).resolve().parent / "run_mflux_with_teacache.py"
+ if wrapper.is_file():
+ cmd[:1] = [str(venv_py), str(wrapper)]
+ if on_log is not None:
+ try: on_log(f"[mflux-teacache] wrap on (thresh={env.get('MFLUX_TC_FLUX_THRESH')})")
+ except Exception: # noqa: BLE001
+ pass
+
# Switched to Popen + line-streaming so the panel can surface mflux's
# tqdm progress bars (`[12/30]`-style step lines) and weight-download
# status to the user while the subprocess runs. Capturing both
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index 0fab9d8..4ef020f 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -7273,7 +7273,30 @@ def _load_agent_image_config() -> agent_image_engine.ImageEngineConfig:
cfg = agent_image_engine.ImageEngineConfig()
# Auto-promote away from mock if a real engine is installed.
+ # Also migrate v2.x users still on raw qwen_edit (8-step Q6, no
+ # LoRA) onto the Lightning 4-step path so the Image Studio default
+ # and the agent's Settings default land on the same ~1:20-per-image
+ # tier instead of the legacy ~2:35 path. Escape hatch:
+ # PHOSPHENE_SKIP_QWEN_PROMOTE=1 keeps the user's existing config.
+ needs_promote = False
+ reason = ""
if cfg.kind == "mock":
+ needs_promote = True
+ reason = "mock"
+ elif (cfg.kind == "mflux"
+ and (cfg.mflux_family == "qwen_edit"
+ or agent_image_engine._infer_mflux_family(cfg.mflux_model) == "qwen_edit")
+ and cfg.mflux_steps in (0, 8)
+ and not cfg.mflux_lora_paths):
+ needs_promote = True
+ reason = "qwen_edit_no_lightning"
+
+ # Env escape hatch — lets a power user pin the old behaviour
+ # (e.g. for A/B benchmarking or to keep a slow but exact path).
+ if os.environ.get("PHOSPHENE_SKIP_QWEN_PROMOTE", "").strip() in ("1", "true", "yes"):
+ needs_promote = False
+
+ if needs_promote:
promoted = _auto_promote_image_engine_kind(cfg)
if promoted is not None:
cfg = promoted
@@ -7291,7 +7314,7 @@ def _load_agent_image_config() -> agent_image_engine.ImageEngineConfig:
os.chmod(AGENT_IMAGE_CONFIG_PATH, 0o600)
except OSError:
pass
- push(f"agent: auto-promoted image engine mock -> {cfg.kind}/{cfg.mflux_family} (model={cfg.mflux_model})")
+ push(f"agent: auto-promoted image engine ({reason}) -> {cfg.kind}/{cfg.mflux_family} (model={cfg.mflux_model}, steps={cfg.mflux_steps}, loras={len(cfg.mflux_lora_paths)})")
except OSError as e:
push(f"agent: image-engine auto-promote in-memory only (write failed: {e})")
@@ -7333,12 +7356,19 @@ def _auto_promote_image_engine_kind(
"mflux_model": model,
"mflux_family": fam,
}
- # Fresh install fast-path: bake Lightning into the qwen_edit
- # auto-promotion so first-time "Auto" runs hit the 90-second
- # tier instead of the 2:35 8-step path. Only applies when the
- # user hasn't customized steps/LoRAs yet (cur.mflux_steps == 0
- # means "use family default" and no LoRAs picked).
- if fam == "qwen_edit" and cur.mflux_steps == 0 and not cur.mflux_lora_paths:
+ # Fresh install + v2.x upgrade fast-path: bake Lightning into
+ # the qwen_edit auto-promotion so first-time "Auto" runs hit
+ # the 90-second tier instead of the 2:35 8-step path. Applies
+ # to BOTH a brand-new fresh install (cur.mflux_steps == 0,
+ # the dataclass default) AND to existing v2.x users who saved
+ # the previous 8-step default to disk and never picked their
+ # own LoRA (steps in {0, 8} + no LoRAs picked). The matching
+ # gate in _load_agent_image_config catches the v2.x case;
+ # this branch then writes the Lightning recipe in. Users
+ # who picked a custom step count or LoRA are left alone.
+ if (fam == "qwen_edit"
+ and cur.mflux_steps in (0, 8)
+ and not cur.mflux_lora_paths):
overrides["mflux_steps"] = 4
overrides["mflux_lora_paths"] = [
"lightx2v/Qwen-Image-Edit-2511-Lightning:Qwen-Image-Edit-2511-Lightning-4steps-V1.0-bf16.safetensors"
@@ -18463,9 +18493,9 @@ HTML = r"""<!doctype html>
<div class="studio-engine-row">
<select id="imgStudioEngine" onchange="imgStudioUpdateValidity();imgStudioRefreshEngineStatus();imgStudioUpdateEstimate();imgStudioUpdateRefWarning();if(typeof renderLorasList==='function')renderLorasList()">
<option value="auto">Auto (use Settings)</option>
- <option value="qwen_edit_lightning_inline" selected>Qwen Fast (Lightning &middot; 4-step Q6 + FBCache, ~1:20 / image, multi-ref)</option>
- <option value="qwen_edit_inline">Qwen Medium (8-step Q6 + FBCache, ~2:05 / image, multi-ref)</option>
- <option value="qwen_edit_high_inline">Qwen Quality (40-step Q8 + CFG 4.0 + FBCache, ~3:50 / image, multi-ref)</option>
+ <option value="qwen_edit_lightning_inline" selected>Fast &mdash; Lightning 4-step (~1:20, default, multi-ref)</option>
+ <option value="qwen_edit_inline">Standard &mdash; 8-step Q6 (~2:05, no LoRA)</option>
+ <option value="qwen_edit_high_inline">Quality &mdash; 40-step Q8 + CFG (~3:50, final renders)</option>
<option value="hidream_fast_inline">HiDream Fast (3-step, ~3:45 / 4-img batch, slight bg softness)</option>
<option value="hidream_inline">HiDream Medium (6-step + FBCache, ~6 min / 4-img batch, character-preserving)</option>
<option value="hidream_quality_inline">HiDream Quality (12-step + light FBCache, ~9 min / 4-img batch, best detail)</option>