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.

12.8 KB
Raw Blame
"""FLUX 3's isolated worker contract. No MLX or mflux imports in the studio."""
from __future__ import annotations

import json
import hashlib
import os
from pathlib import Path
import platform
import queue
import re
import secrets
import shutil
import subprocess
import sys
import threading
import time

ROOT = Path(__file__).resolve().parent
CREDIT = "FLUX 3 Klein by Black Forest Labs"
LICENCE_URL = "https://huggingface.co/black-forest-labs/flux-3-image-klein/blob/main/LICENSE.md"
# Free space FLUX 3 leaves untouched while it GROWS the disk (worker install,
# weight downloads). Rendering with everything installed writes one small PNG,
# so it only needs output headroom: a full reserve there refused every image
# on a Mac that had installed FLUX 3 and then had under the reserve free.
RESERVE = 5 * 1024**3
OUTPUT_HEADROOM = 64 * 1024**2
INSTALL_BUDGET = 3 * 1024**3
PACKS = json.loads((ROOT / "data/flux3_models.json").read_text())
PRESETS = {
    f"flux3_{variant}_q{q}": {"variant": variant, "quantize": q,
        "steps": 50 if variant == "base" else 16,
        "guidance": 3.5 if variant == "base" else None,
        "label": f"{CREDIT} / {'Base Quality' if variant == 'base' else 'Standard'} / Q{q}"}
    for variant in ("distilled", "base") for q in (8, 6, 4)
}


def worker_root():
    return Path(os.environ.get("PHOSPHENE_FLUX3_ROOT") or ROOT / "flux3-worker").expanduser().resolve()


def worker_python():
    return worker_root() / "env/bin/python"


def requirements_digest():
    return hashlib.sha256((ROOT / "scripts/pinokio/flux3_requirements.txt").read_bytes()).hexdigest()


def worker_ready():
    try:
        return worker_python().is_file() and (worker_root() / ".ready").read_text().strip() == requirements_digest()
    except OSError:
        return False


def clean_env(base=None):
    source = os.environ if base is None else base
    stripped = {"VIRTUAL_ENV", "PYTHONPATH", "PYTHONHOME", "PYTHONSTARTUP",
                "__PYVENV_LAUNCHER__", "PYTORCH_ENABLE_MPS_FALLBACK",
                "PYTORCH_MPS_FAST_MATH", "TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD"}
    env = {k: v for k, v in source.items() if k not in stripped
           and not k.startswith(("Malloc", "MFLUX_"))}
    env.update(PYTHONUNBUFFERED="1", HF_HUB_DISABLE_TELEMETRY="1",
               HF_HUB_DISABLE_PROGRESS_BARS="0", MLX_ENABLE_TF32="0")
    return env


def cache_root(env=None):
    env = os.environ if env is None else env
    return Path(env.get("HF_HUB_CACHE") or
                Path(env.get("HF_HOME") or Path.home() / ".cache/huggingface") / "hub").expanduser()


def pack_for(config):
    key = f"{config.flux3_variant}-q{config.mflux_quantize}"
    if key not in PACKS:
        raise ValueError("FLUX 3 needs Standard or Base Quality and Q8, Q6 or Q4.")
    return PACKS[key]


def snapshot_path(pack, env=None):
    return cache_root(env) / ("models--" + pack["repo"].replace("/", "--")) / "snapshots" / pack["revision"]


def cached_bytes(pack, env=None):
    snap = snapshot_path(pack, env)
    total = 0
    for item in pack["files"]:
        try:
            if (snap / item["path"]).stat().st_size == item["size"]:
                total += item["size"]
        except OSError:
            pass
    return total


def downloaded_bytes(pack, env=None):
    """Completed files plus resumable Hub blobs; never count a partial as ready."""
    snap = snapshot_path(pack, env)
    blobs = snap.parent.parent / "blobs"
    total = cached_bytes(pack, env)
    for item in pack["files"]:
        try:
            if (snap / item["path"]).stat().st_size == item["size"]:
                continue
        except OSError:
            pass
        digest = item.get("sha256")
        if digest:
            total += min(item["size"], partial_blob_bytes(blobs, digest))
    return total


def partial_blob_bytes(blobs, digest):
    """Largest in-flight blob for this file. huggingface_hub 1.x writes
    `<etag>.<uuid8>.incomplete` (older hubs `<etag>.incomplete`); counting
    only the old name showed 0.00 GB for the whole download."""
    best = 0
    try:
        for part in Path(blobs).glob(digest + "*.incomplete"):
            try:
                best = max(best, part.stat().st_size)
            except OSError:
                pass
    except OSError:
        pass
    return best


def require_space(path, extra=0, reserve=RESERVE):
    path = Path(path)
    while not path.exists():
        path = path.parent
    free = shutil.disk_usage(path).free
    if free < reserve + extra:
        why = (f", keeping {reserve / 1024**3:.0f} GB free for your Mac" if reserve >= 1024**3 else "")
        raise RuntimeError(f"FLUX 3 needs {(reserve + extra) / 1024**3:.1f} GB free here "
                           f"({free / 1024**3:.1f} GB available){why}. "
                           "Free space or choose another model location, then retry.")


def ram_need(config):
    pack_for(config)
    return {4: 18.5, 6: 20.6, 8: 22.8}[config.mflux_quantize]


def validate(config, width, height, refs, total_gb=None):
    pack_for(config)
    if total_gb is None:
        if platform.system() != "Darwin" or platform.machine() != "arm64":
            raise RuntimeError("FLUX 3 requires an Apple Silicon Mac.")
        total_gb = int(subprocess.check_output(["/usr/sbin/sysctl", "-n", "hw.memsize"])) / 1024**3
    floor = 24 if config.mflux_quantize == 4 else 32
    if total_gb < floor:
        raise ValueError(f"FLUX 3 Q{config.mflux_quantize} needs a {floor} GB Mac. "
                         "Q4 is available on 24 GB Macs; 32 GB or more is recommended.")
    if width % 16 or height % 16 or width * height > 1024**2:
        raise ValueError("FLUX 3 supports up to 1024 x 1024 pixels, in multiples of 16.")
    if len(refs) > 10:
        raise ValueError("FLUX 3 supports up to ten reference images.")
    if total_gb < 32 and (width * height > 768**2 or len(refs) > 1):
        raise ValueError("On a 24 GB Mac, use Q4, a small image size and at most one reference.")


def status(engine, total_gb):
    recipe = PRESETS[engine]
    pack = PACKS[f"{recipe['variant']}-q{recipe['quantize']}"]
    complete = cached_bytes(pack)
    done = downloaded_bytes(pack)
    floor = 24 if recipe["quantize"] == 4 else 32
    return dict(engine=engine, repo_id=pack["repo"], cached=complete == pack["bytes"],
                partial=done > 0 and complete < pack["bytes"], partial_gb=done / 1e9,
                family_installed=True, worker_installed=worker_ready(),
                lazy_install=True, download_gb=pack["bytes"] / 1e9,
                ram_need_gb={4: 18.5, 6: 20.6, 8: 22.8}[recipe["quantize"]],
                mac_gb_needed=floor, fits_mac=total_gb >= floor,
                sec_per_image=0, cold_start_sec=0, samples_source="unmeasured",
                gated=False, license_url=LICENCE_URL)


def _redact(line):
    return re.sub(r"hf_[A-Za-z0-9]+", "[redacted]", line)


def _run(cmd, env, on_log, request=None, timeout=7200, guard=(), tail_out=None):
    """Stream progress and share the studio's cancellation registry, including install."""
    import image_engine
    events = queue.Queue()
    proc = subprocess.Popen(cmd, cwd=ROOT, env=env, stdin=subprocess.PIPE,
                            stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
                            text=True, errors="replace", start_new_session=True)
    try:
        image_engine._register_active_proc(proc)
    except BaseException:
        proc.stdin.close()
        proc.stdout.close()
        raise
    tail, receipts = [], []
    def read():
        try:
            for line in proc.stdout:
                events.put(line.rstrip())
        finally:
            events.put(None)
    threading.Thread(target=read, daemon=True).start()
    started = time.monotonic()
    try:
        if request is not None:
            proc.stdin.write(json.dumps(request) + "\n")
        proc.stdin.close()
        while True:
            check = image_engine._CANCEL_CHECK
            if check and check():
                raise image_engine.ImageJobCancelled("FLUX 3 stopped.")
            if time.monotonic() - started > timeout:
                raise RuntimeError("FLUX 3 timed out. Retry with a smaller image or fewer references.")
            for path, reserve in guard:
                require_space(path, reserve=reserve)
            try:
                line = events.get(timeout=0.25)
            except queue.Empty:
                continue
            if line is None:
                break
            # Anywhere in the line, not only at its start: a progress bar
            # left on the same line (stderr shares this pipe) must not hide a
            # finished image's receipt (fleet #206).
            mark = line.find("FLUX3_RESULT ")
            if mark >= 0:
                try:
                    receipts.append(json.loads(line[mark + len("FLUX3_RESULT "):]))
                except ValueError:
                    tail = (tail + [_redact(line[:200])])[-15:]
            else:
                line = _redact(line)
                tail = (tail + [line])[-15:]
                if on_log:
                    on_log(line)
        rc = proc.wait(timeout=10)
        if tail_out is not None:
            tail_out[:] = tail
        if rc < 0:
            raise image_engine.ImageJobCancelled("FLUX 3 stopped.")
        if rc:
            raise RuntimeError("FLUX 3 did not finish: " + "\n".join(tail))
        return receipts
    finally:
        if proc.poll() is None:
            import signal
            try:
                os.killpg(proc.pid, signal.SIGKILL)
            except ProcessLookupError:
                pass
            proc.wait(timeout=10)
        image_engine._unregister_active_proc(proc)
        proc.stdout.close()


def generate(prompt, n, width, height, output_dir, base_seed, config, refs, on_log, install_env=None):
    validate(config, width, height, refs)
    env = clean_env(install_env)
    pack = pack_for(config)
    # The reserve guards GROWTH only: nothing to fetch or install, no reserve.
    missing = pack["bytes"] - downloaded_bytes(pack, env)
    if missing > 0:
        require_space(cache_root(env), missing)
    require_space(output_dir, OUTPUT_HEADROOM, reserve=0)
    installing = not worker_ready()
    if installing and not worker_python().is_file():
        require_space(worker_root(), INSTALL_BUDGET)
    # The bootstrap checks exact package versions without importing MLX.
    _run([sys.executable, "-S", str(ROOT / "scripts/pinokio/flux3_env.py"), str(worker_root())], env, on_log,
         guard=[(worker_root(), RESERVE)] if installing else [])
    first_seed = base_seed if base_seed is not None else secrets.randbelow(2**31)
    request = dict(prompt=prompt, seeds=[first_seed + i for i in range(n)],
                   width=width, height=height, output_dir=str(output_dir), refs=refs,
                   variant=config.flux3_variant, quantize=config.mflux_quantize)
    tail = []
    result = _run([str(worker_python()), str(ROOT / "scripts/flux3_worker.py")], env, on_log, request,
                  timeout=1800 + 3600 * n,
                  # The worker guards its own downloads with RESERVE; here only
                  # the output volume matters, so a full disk still stops it.
                  guard=[(output_dir, OUTPUT_HEADROOM)], tail_out=tail)
    return _complete_receipts(result, request, output_dir, tail)


def _complete_receipts(result, request, output_dir, tail=()):
    """The finished images, one per requested seed, or a precise error.

    Fleet #206 (4.19.15, one M5 Max, 3 of 9): "FLUX 3 returned no complete
    image" after full-length renders with the worker exiting cleanly. The
    worker writes `<png>.flux3.json` (the same receipt) BEFORE it prints the
    FLUX3_RESULT line, so a receipt the pipe lost is recovered from disk for
    every requested seed whose verified image is there. Anything still missing
    names how many images came back and the worker's last lines, so the next
    report says why instead of "check the log"."""
    seeds = list(request.get("seeds") or [])
    got = {int(r.get("seed", -1)): r for r in result
           if isinstance(r, dict) and Path(str(r.get("png_path") or "")).is_file()}
    for seed in seeds:
        if seed in got:
            continue
        for meta in sorted(Path(output_dir).glob(f"flux3_*_{seed}.flux3.json")):
            try:
                rec = json.loads(meta.read_text())
            except (OSError, ValueError):
                continue
            if int(rec.get("seed", -1)) == seed and Path(str(rec.get("png_path") or "")).is_file():
                got[seed] = rec
                break
    if seeds and all(s in got for s in seeds):
        return [got[s] for s in seeds]
    done = sum(1 for s in seeds if s in got)
    last = "\n".join(str(x) for x in list(tail)[-6:])
    raise RuntimeError(
        f"FLUX 3 returned no complete image ({done} of {len(seeds)} finished; "
        f"the worker exited without an error). Check the log and retry."
        + (f" Last lines:\n{last}" if last else ""))