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
feat(image): mlx-teacache wrap for FLUX.2 family (E3)
mrbizarroe8c6c679c8d7
diff --git a/install_qwen.js b/install_qwen.jsindex 00c6086..837303c 100644--- a/install_qwen.js+++ b/install_qwen.js@@ -80,6 +80,23 @@ module.exports = {message: "./ltx-2-mlx/env/bin/pip install --force-reinstall --no-deps 'mflux==0.17.5'"}},+ {+ method: "shell.run",+ params: {+ // mlx-teacache 0.4.1 (MIT, github.com/IonDen/mlx-teacache). Powers+ // the optional TeaCache wrap for the FLUX.2 family — skips 3/25+ // timesteps on flux2-klein-base-4b at SSIM>0.99 (~1.41x speedup)+ // and gives a smaller ~1.25x on the 4-step distilled klein-4b+ // (mostly mx.compile avoid). Wired by run_mflux_with_teacache.py+ // which image_engine.py launches in place of mflux-generate-flux2+ // when MFLUX_TC_FLUX=1 (default). The wrapper itself falls back+ // to the bare CLI if this import isn't present, so the install+ // step failing isn't fatal — but we pin it next to mflux so a+ // user who opted into Qwen also gets the FLUX.2 speedup.+ // Library is compatible with mflux>=0.17,<0.18 (matches our pin).+ message: "./ltx-2-mlx/env/bin/pip install 'mlx-teacache==0.4.1'"+ }+ },{method: "shell.run",params: {diff --git a/run_mflux_with_teacache.py b/run_mflux_with_teacache.pynew file mode 100644index 0000000..a6d2fed--- /dev/null+++ b/run_mflux_with_teacache.py@@ -0,0 +1,233 @@+#!/usr/bin/env python3+"""Phosphene wrapper that invokes mflux flux2 inside a TeaCache context.++When MFLUX_TC_FLUX=1 (set by image_engine.py for fam='flux2'), Phosphene+launches this script instead of the bare `mflux-generate-flux2` CLI.+The wrapper imports mlx_teacache and inlines a near-copy of mflux's+``flux2_generate.main`` that calls ``apply_teacache(model, ...)`` between+``Flux2Klein(...)`` construction and the ``model.generate_image(...)``+loop. ``apply_teacache`` itself wraps ``model.generate_image`` (see+mlx_teacache.api.apply_teacache step B: wrap_generate_image) so the+TeaCache step-decode logic runs for the entire per-seed loop without any+further plumbing on our side.++Expected speedup at SSIM > 0.99 per the library's published numbers+(github.com/IonDen/mlx-teacache v0.4.1):+ - flux2-klein-4b 4-step distilled: ~1.25x (mostly mx.compile avoid;+ the polynomial gate does not engage at default threshold on a 4-step+ schedule, but the wrap still avoids one mx.compile path per run)+ - flux2-klein-base-4b 25-step: ~1.41x (3/25 cached, polynomial gate+ active because the base model is non-distilled at guidance=1.0)+ - flux2-klein-base-4b w/ CFG > 1.0: NO-op (TeaCache 0.4.1 falls back+ to vanilla mflux pending v0.5; wrapper still safe, just no speedup)++Env vars:+ MFLUX_TC_FLUX_THRESH (default 0.20) — library-recommended sweet spot.+ MFLUX_TC_FLUX=0/false/no — disable wrap, fall through to+ bare mflux-generate-flux2.++Fallback behaviour: if ANY import, wrap, or runtime step fails, we shell+out to the original ``mflux-generate-flux2`` CLI with the same argv. The+user gets a working render every time; the only loss is the TeaCache+speedup and a one-line stderr diagnostic explaining why.++Compatibility: mflux==0.17.5 (pinned by install_qwen.js / update.js),+mlx-teacache==0.4.1 (pinned alongside). The inline main() mirrors mflux's+``mflux/models/flux2/cli/flux2_generate.py`` — re-validate after any+mflux bump that touches Flux2Klein construction or generate_image kwargs.+"""+import os+import sys+++THRESH = float(os.environ.get("MFLUX_TC_FLUX_THRESH", "0.20"))+++def _fallback(reason: str) -> int:+ """Shell out to the unwrapped CLI. Returns the child's exit code so+ sys.exit(_fallback(...)) propagates it to the caller (image_engine).++ Prefer the venv-local binary (sibling of sys.executable) — the+ wrapper is launched from image_engine.py via the venv python so the+ sibling mflux-generate-flux2 is guaranteed installed alongside it.+ Falls through to PATH lookup if that file isn't there (covers the+ rare case where the wrapper is invoked manually outside the venv).+ """+ import shutil+ import subprocess+ venv_bin = os.path.dirname(sys.executable)+ candidate = os.path.join(venv_bin, "mflux-generate-flux2")+ if not (os.path.isfile(candidate) and os.access(candidate, os.X_OK)):+ candidate = shutil.which("mflux-generate-flux2") or "mflux-generate-flux2"+ print(f"[mflux-teacache] falling back to {candidate} ({reason})",+ file=sys.stderr, flush=True)+ return subprocess.call([candidate, *sys.argv[1:]])+++def _wrapped_main() -> int:+ """Inline near-copy of ``mflux.models.flux2.cli.flux2_generate.main``+ with a single ``apply_teacache(model, rel_l1_thresh=THRESH)`` call+ inserted between model construction and the per-seed generate loop.++ Mirroring upstream rather than calling it lets us avoid monkey-patch+ races on ``Flux2Klein.generate_image`` — ``apply_teacache`` itself+ wraps ``generate_image`` via ``wrap_generate_image`` (see+ mlx_teacache.api line ~210), and a class-level monkey-patch from us+ would either no-op or fight that wrap. The inline copy is ~50 LoC+ and stable across mflux 0.17.x (only Klein bumps would touch it).+ """+ # All upstream imports are lazy so a fast `--help` fallback doesn't+ # pay the model-loading cost.+ from mflux.callbacks.callback_manager import CallbackManager+ from mflux.cli.parser.parsers import CommandLineParser+ from mflux.models.common.config import ModelConfig+ from mflux.models.flux2.latent_creator.flux2_latent_creator import Flux2LatentCreator+ from mflux.models.flux2.variants import Flux2Klein+ from mflux.utils.dimension_resolver import DimensionResolver+ from mflux.utils.exceptions import PromptFileReadError, StopImageGenerationException+ from mflux.utils.image_util import ImageUtil+ from mflux.utils.prompt_util import PromptUtil+ from mlx_teacache import apply_teacache+ from mlx_teacache.errors import (+ AlreadyPatchedError,+ IncompatibleModelError,+ TeaCacheError,+ )++ # 0. Parse command line arguments — identical shape to upstream main().+ parser = CommandLineParser(description="Generate an image using Flux2 Klein.")+ parser.add_general_arguments()+ parser.add_model_arguments(require_model_arg=False)+ parser.add_lora_arguments()+ parser.add_image_generator_arguments(supports_metadata_config=True, supports_dimension_scale_factor=True)+ parser.add_image_to_image_arguments(required=False)+ parser.add_output_arguments()+ args = parser.parse_args()++ if getattr(args, "negative_prompt", ""):+ parser.error("--negative-prompt is not supported for FLUX.2. Focus on describing what you want.")++ model_name = args.model or "flux2-klein-4b"+ model_config = ModelConfig.from_name(model_name=model_name)++ if args.guidance is None:+ args.guidance = 1.0+ is_distilled = "base" not in model_config.model_name.lower()+ if args.guidance != 1.0 and is_distilled:+ parser.error("--guidance is only supported for FLUX.2 base models. Use --guidance 1.0.")++ model = Flux2Klein(+ model_config=model_config,+ quantize=args.quantize,+ model_path=args.model_path,+ lora_paths=args.lora_paths,+ lora_scales=args.lora_scales,+ )++ # === TeaCache wrap ============================================+ # apply_teacache mutates `model` in place (wraps generate_image,+ # patches _predict, registers a generation callback). The returned+ # TeaCacheHandle is also a context manager — entering is a no-op+ # but __exit__ calls handle.restore(), which is harmless in a+ # one-shot subprocess. Wrapping in `with` keeps the lifecycle+ # tidy and would matter if we ever re-used `model` after the+ # generation loop.+ #+ # Three failure modes the library raises that we tolerate+ # gracefully:+ # - IncompatibleModelError: model variant outside the supported+ # set (e.g. an upstream Klein bump we haven't validated). The+ # wrap is purely a speedup so skipping it just costs us the+ # speedup, not the render.+ # - AlreadyPatchedError: shouldn't happen in our subprocess+ # because Flux2Klein is fresh, but defensive in case mflux+ # ever pre-patches.+ # - Other TeaCacheError: same — skip the wrap, still render.+ handle = None+ try:+ handle = apply_teacache(model, rel_l1_thresh=THRESH)+ print(f"[mflux-teacache] wrap on (variant={handle.variant_id}, thresh={THRESH})",+ file=sys.stderr, flush=True)+ except (IncompatibleModelError, AlreadyPatchedError, TeaCacheError) as exc:+ print(f"[mflux-teacache] wrap skipped ({type(exc).__name__}: {exc}); rendering vanilla",+ file=sys.stderr, flush=True)+ handle = None+ # ============================================================++ memory_saver = CallbackManager.register_callbacks(+ args=args,+ model=model,+ latent_creator=Flux2LatentCreator,+ )++ try:+ width, height = DimensionResolver.resolve(+ width=args.width,+ height=args.height,+ reference_image_path=args.image_path,+ )++ for seed in args.seed:+ image = model.generate_image(+ seed=seed,+ prompt=PromptUtil.read_prompt(args),+ width=width,+ height=height,+ guidance=args.guidance,+ image_path=args.image_path,+ num_inference_steps=args.steps,+ image_strength=args.image_strength,+ scheduler="flow_match_euler_discrete",+ )+ ImageUtil.save_image(+ image=image,+ path=args.output.format(seed=seed),+ export_json_metadata=args.metadata,+ )+ except (StopImageGenerationException, PromptFileReadError) as exc:+ print(exc)+ finally:+ if memory_saver:+ print(memory_saver.memory_stats())+ # Restore on the way out so any future re-use of `model` in the+ # same interpreter (we don't currently re-use, but harmless to+ # be tidy) starts from a clean state. handle.restore() is+ # idempotent — safe to call even if we never wrapped.+ if handle is not None:+ try:+ handle.restore()+ except Exception: # noqa: BLE001+ pass+ return 0+++def main() -> int:+ # Quick disable knob — if image_engine sets MFLUX_TC_FLUX=0 we+ # transparently fall through. (image_engine wouldn't normally launch+ # the wrapper in that case but this defensive check keeps the script+ # callable by hand for A/B testing.)+ if os.environ.get("MFLUX_TC_FLUX", "1").strip().lower() in ("0", "false", "no"):+ return _fallback("MFLUX_TC_FLUX disabled")++ try:+ import mlx_teacache # noqa: F401 — import probe+ except Exception as exc: # noqa: BLE001+ return _fallback(f"mlx_teacache import: {exc!r}")++ try:+ from mflux.models.flux2.variants import Flux2Klein # noqa: F401+ from mflux.models.flux2.cli import flux2_generate # noqa: F401+ except Exception as exc: # noqa: BLE001+ return _fallback(f"mflux flux2 import: {exc!r}")++ try:+ return _wrapped_main()+ except SystemExit as exc:+ # argparse / mflux clean exit — propagate the code as-is.+ return int(exc.code) if isinstance(exc.code, int) else (0 if exc.code is None else 1)+ except Exception as exc: # noqa: BLE001+ return _fallback(f"wrap failed at runtime: {exc!r}")+++if __name__ == "__main__":+ sys.exit(main())diff --git a/update.js b/update.jsindex de8c7e6..abc37d9 100644--- a/update.js+++ b/update.js@@ -190,7 +190,13 @@ module.exports = {" ./ltx-2-mlx/env/bin/pip install 'mflux==0.17.5' && \\",// Step 3: force-reinstall WITHOUT deps to lock the version// without churning the deps we just installed.- " ./ltx-2-mlx/env/bin/pip install --force-reinstall --no-deps 'mflux==0.17.5'; \\",+ " ./ltx-2-mlx/env/bin/pip install --force-reinstall --no-deps 'mflux==0.17.5' && \\",+ // Step 4: install (or refresh) mlx-teacache 0.4.1 (MIT) for the+ // optional FLUX.2 TeaCache wrap (run_mflux_with_teacache.py).+ // Gated by the same `import mflux` probe above — only land this+ // for users who actually opted into mflux. Pinned exact for+ // reproducibility; compatible with mflux>=0.17,<0.18.+ " ./ltx-2-mlx/env/bin/pip install 'mlx-teacache==0.4.1'; \\","else \\"," echo 'mflux not installed (user never opted into Qwen image gen) — skipping mflux repair.'; \\","fi"