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
v4.14.1 — Compose is always in Audio; H3 black renders fixed
mrbizarrod8a7ca4b4bff
diff --git a/README.md b/README.mdindex e8da020..2293e1e 100644--- a/README.md+++ b/README.md@@ -19,7 +19,7 @@</p>-> **Current release: v4.14.0.** **Songs, faces and sound**: **Audio → Compose** writes whole songs with vocals from your lyrics and a style (YuE2 by Multimodal Art Projection, MLX port by vanch007; about real time on an M4 Max, 11 GB). **Upscale & Face Fix** sharpens faces and doubles the size of any clip in one click, from the player, Outputs, the queue or the Editor. The Editor gets **sound tracks**: A3, A4 and more, a Sound pool, and clip sound on two lanes so neighbouring shots can crossfade. Full notes on the [releases page](https://github.com/mrbizarro/Phosphene/releases).+> **Current release: v4.14.1.** **Compose is always in Audio**: install YuE2 from right there with one click (no more hunting in the Pinokio sidebar), and H3 renders that some community LoRAs turned black now work or fail with a clear message. **v4.14.0 — Songs, faces and sound**: **Audio → Compose** writes whole songs with vocals from your lyrics and a style (YuE2 by Multimodal Art Projection, MLX port by vanch007; about real time on an M4 Max, 11 GB). **Upscale & Face Fix** sharpens faces and doubles the size of any clip in one click, from the player, Outputs, the queue or the Editor. The Editor gets **sound tracks**: A3, A4 and more, a Sound pool, and clip sound on two lanes so neighbouring shots can crossfade. Full notes on the [releases page](https://github.com/mrbizarro/Phosphene/releases).## Overview@@ -41,7 +41,7 @@ LTX, Hailuo H3 and YuE2 are peers with their own jobs and install sizes:| **Hailuo H3** | Video with dialogue and sound | ~75 GB; Q8 DiT adds ~22 GB | 36 GB+ with the Q8 DiT; 60 GB+ for full bf16 || **YuE2** | Audio → Compose: vocals and arrangement from lyrics and a style | ~11 GB | 24 GB or more |-YuE2 arrives through **Install the music engine** in the Pinokio sidebar.+YuE2 installs from inside the panel: open **Audio → Compose** and click **Install music engine (YuE2, ~11 GB)** (the Pinokio sidebar entry **Install the music engine** does the same).Compose offers section-tagged lyrics, a prose style, an Instrumental pill,three score modes, Draft/Final quality and a maximum length. Songs appear as48 kHz stereo WAVs in the gallery; **Drive video** loads a song into the videodiff --git a/VERSION b/VERSIONindex c412a4e..d2b9909 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-4.14.0+4.14.1diff --git a/docs/MUSIC_ENGINE.md b/docs/MUSIC_ENGINE.mdindex a4a13de..210e78e 100644--- a/docs/MUSIC_ENGINE.md+++ b/docs/MUSIC_ENGINE.md@@ -2,9 +2,39 @@YuE2 by Multimodal Art Projection writes vocals and an arrangement togetherfrom lyrics and a style description. It sits beside LTX and Hailuo H3 as a-peer engine. Install **the music engine (YuE2, ~11 GB)** from the Phosphene-sidebar in Pinokio, then open **Audio → Compose**. Without its pack, Audio-keeps its existing Drive video surface; Settings → Models offers the install.+peer engine. Open **Audio → Compose**: Compose is always there. Until the+engine is installed the form is greyed and one button, **Install music engine+(YuE2, ~11 GB)**, installs it from the panel; pressing **Compose** does the+same. The sidebar entry **Install the music engine** in Pinokio still works and+runs the same steps. Settings → Models and the header engine picker (YuE2 ·+11 GB) open the same install card.++## Installing from the panel++`POST /music/install` (`kind=install|repair`) starts a background task that+runs `MUSIC_INSTALL_STEPS` in `mlx_ltx_panel.py`: the six `shell.run` commands+of `install_music.js`, character for character, from the app folder+(`test_music_engine.py` compares the two lists). Progress rides+`/status.music_install` (`state` idle/running/stopping/done/failed/stopped,+`step_index`, `step_label`, `percent`, `bytes_done`/`bytes_total` while the+weights download, `last_line`, a short `log`). The byte counter reads the pack+folder, so with hf_xet it moves as each large file lands.++- **Environment:** the panel's own (HF_HOME, SSL certs, `LTX_MUSIC_*`) minus+ the LTX venv activation, with Pinokio's `bin/miniforge/bin`,+ `bin/miniconda/bin` and `bin/homebrew/bin` in front of PATH — a panel started+ outside Pinokio's shell has no `uv` otherwise.+- **Stop** (`POST /music/install/stop`) SIGTERMs the step's process group and+ SIGKILLs it after 8 s. **Install again resumes**: the clone and venv are kept+ and `music_fetch.py` keeps every file whose sha256 matches.+- **Guards:** one install at a time (409); refused while a song is being+ written; a song is refused while the install runs; each step is registered+ with the orphan reaper (`state/music_install_running.json`), and the panel+ stops the install when it exits.+- **Disk:** `music_preflight.sh` (14 GB free) and `music_fetch.py` (space for+ the missing bytes) refuse with a sentence the card shows verbatim.+- Nothing restarts: `/status.music` flips to available and Compose unlocks on+ the next poll.## Memory, length and estimatesdiff --git a/docs/STATE.md b/docs/STATE.mdindex 47b9214..9a574a4 100644--- a/docs/STATE.md+++ b/docs/STATE.md@@ -1,5 +1,25 @@# Phosphene — project state, history, open work+> **🎶 2026-09-17 — v4.14.1 released (public, tag `v4.14.1`): "Compose is always in Audio; H3 black renders fixed".**+> Pinokio's author looked for YuE2 for an hour: Compose only appeared after a sidebar install. Owner: "do as the peanut says and ship".+> **Music:** Audio always offers Compose. Not installed → greyed form + one button "Install music engine (YuE2, ~11 GB)"; Compose,+> the header picker (YuE2 · 11 GB) and Settings → Models open the same card. `POST /music/install` runs `MUSIC_INSTALL_STEPS`+> (= install_music.js's six commands, test-enforced) in the background; `/status.music_install` (step, percent, bytes, last line);+> `POST /music/install/stop` (killpg, SIGKILL after 8 s); Install again resumes; orphan guard `music_install_running.json`;+> no install during a song and vice versa; Pinokio's `bin/miniforge|miniconda|homebrew/bin` prepended (a manually started panel has+> no uv). hf_xet writes whole files, so the byte counter moves per file. Dev commit `ee5827b`. Also: stray `=======` in panel.css.+> **H3 black renders:** dev `39b828d` cherry-picked (panel fails a flat-colour clip, shows the runner's `error_message`); runner+> `codex/h3-engine-v2` pushed 11b90a0 → `d39879b` (F16 adapters → bf16, NaN/flat guard; also carries 6bbed80/ccf532b, optional+> `--sigma-subset`/`--vae-dtype`, defaults unchanged, unused by this panel — the Fast switch stays unreleased). Runner tests on CPU:+> unittest 25 OK, test_sigma_subset 4 passed, mux frame count PASS; test_video_vae_smoke has 4 tiled FAILs that 11b90a0 shows+> identically on CPU (pre-existing, not this change).+> **Release:** cherry-pick of the two dev commits + VERSION/README on `fbc777c` (no Fast switch, room tone, Editor round 2 or+> Face Fix placement). Gates `release_gates.sh --fast` 99 PASS / 0 FAIL / 2 SKIP (--fast), MLX on CPU. **Clean room:** fresh clone+> in `<home>/api/phosphene.git` + install's LTX steps, no music engine, empty HF_HOME, PATH without uv, booted :8441 → 4.14.1+> not dirty, music `not_installed`; Compose → card → Install ran clone, pin `9253ed1`, venv (3.12.13, mlx 0.32.2), frozen sync+> and started the weight download; Stop left no process or guard. Not run: a full 10.5 GB download, any render, Codex (owner).+> **Local dev checkout (8199's) is behind beta** by `ee5827b` + the merge — ff it at the next panel restart (new JS needs the new routes).+> **🎵 2026-09-17 — v4.14.0 released (public, tag `v4.14.0`): "Songs, faces and sound".**> Owner's order: "Let's make a release because I think there are too many things to release at the moment." No further> Codex round for this release (owner). Ships everything on dev: **Audio → Compose (YuE2)**, **Upscale & Face Fix** (renameddiff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex 72f1b07..6b61e6b 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -12511,6 +12511,237 @@ def music_status() -> dict:for q in MUSIC_QUALITY_STEPS}}+# ---- In-panel music engine install -----------------------------------------+# "It kicks in when you try to use it": Audio → Compose installs YuE2 from the+# panel itself. The panel runs the SAME six steps as the Pinokio sidebar's+# install_music.js — the same command strings, from the app folder, so the+# sidebar entry and this button can never drift apart (test_music_install.py+# compares the two lists). Every step is idempotent, so Install again after a+# Stop, a failure or a panel restart resumes: the clone and venv are kept and+# music_fetch.py keeps every weight whose sha256 already matches.+#+# Each step runs in its own process group (Stop = killpg, SIGKILL after 8 s)+# and is registered with the orphan reaper, so a panel that dies mid-install+# does not leave a second downloader racing the next one.+MUSIC_INSTALL_STEPS = (+ ("preflight", "Checking memory and disk space", 1,+ 'bash scripts/pinokio/music_preflight.sh'),+ ("clone", "Downloading the engine code", 3,+ 'bash scripts/pinokio/music_clone.sh'),+ ("checkout", "Pinning the engine version", 2,+ 'bash scripts/pinokio/music_checkout.sh "${LTX_MUSIC_ROOT:-$PWD/yue2-mlx}"'),+ ("venv", "Setting up Python 3.12", 4,+ 'bash scripts/pinokio/music_venv.sh "${LTX_MUSIC_ROOT:-$PWD/yue2-mlx}"'),+ ("sync", "Installing the engine's packages", 10,+ 'bash scripts/pinokio/music_sync.sh "${LTX_MUSIC_ROOT:-$PWD/yue2-mlx}"'),+ ("fetch", "Downloading the model (~10.5 GB)", 80,+ '"${LTX_MUSIC_ROOT:-$PWD/yue2-mlx}/.venv/bin/python" scripts/pinokio/music_fetch.py --min-free-gb 14'),+)+MUSIC_INSTALL_LOCK = threading.Lock()+MUSIC_INSTALL: dict = {"state": "idle", "active": False}+_MUSIC_INSTALL_STOP = threading.Event()+_MUSIC_INSTALL_BYTES = {"ts": 0.0, "bytes": 0}+++def _music_install_env() -> dict:+ """The child env: the panel's own (HF_HOME, SSL certs, LTX_MUSIC_* all+ carry over, exactly as Pinokio's shell merges them) minus the LTX venv's+ activation, plus Pinokio's own tool folders in front of PATH. A panel+ started outside Pinokio's shell has no `uv` on PATH at all."""+ env = {k: v for k, v in os.environ.items()+ if k not in ("VIRTUAL_ENV", "PYTHONPATH", "PYTHONHOME", "PYTHONSTARTUP", "__PYVENV_LAUNCHER__")}+ home = (Path(os.environ["PINOKIO_HOME"]).expanduser() if os.environ.get("PINOKIO_HOME")+ else ROOT.parent.parent if ROOT.parent.name == "api" else None)+ pinokio_bins = [home / d for d in ("bin/miniforge/bin", "bin/miniconda/bin", "bin/homebrew/bin")] if home else []+ fallbacks = [Path.home() / ".local/bin", Path.home() / ".cargo/bin",+ Path("/opt/homebrew/bin"), Path("/usr/local/bin")]+ venv_bin = str(Path(sys.prefix) / "bin")+ parts = [p for p in env.get("PATH", "").split(os.pathsep) if p and p != venv_bin]+ front = [str(d) for d in pinokio_bins if d.is_dir()]+ back = [str(d) for d in fallbacks if d.is_dir()]+ env["PATH"] = os.pathsep.join(dict.fromkeys(front + parts + back))+ env.update({"PYTHONUNBUFFERED": "1", "GIT_TERMINAL_PROMPT": "0", "HF_HUB_DISABLE_PROGRESS_BARS": "1"})+ return env+++def _music_install_bytes() -> int:+ """Bytes of the pack on disk, staged downloads included — the download's+ progress without parsing anything. Throttled: /status polls every 1.5 s."""+ now = time.time()+ if now - _MUSIC_INSTALL_BYTES["ts"] < 1.0:+ return _MUSIC_INSTALL_BYTES["bytes"]+ total = 0+ try:+ for f in MUSIC_MODELS.rglob("*"):+ try:+ if f.is_file() and not f.is_symlink():+ total += f.stat().st_size+ except OSError:+ pass+ except OSError:+ pass+ _MUSIC_INSTALL_BYTES.update(ts=now, bytes=total)+ return total+++def music_install_status() -> dict:+ from scripts.pinokio.music_fetch import PACK_BYTES+ with MUSIC_INSTALL_LOCK:+ s = {k: v for k, v in MUSIC_INSTALL.items() if k not in ("pgid", "log")}+ s["log"] = list(MUSIC_INSTALL.get("log") or [])[-6:]+ s["steps"] = len(MUSIC_INSTALL_STEPS)+ if s.get("active") and s.get("step_key") == "fetch":+ done = min(_music_install_bytes(), PACK_BYTES)+ s["bytes_done"], s["bytes_total"] = done, PACK_BYTES+ frac = done / PACK_BYTES+ else:+ frac = 0.0+ if s.get("active"):+ weights = [w for _, _, w, _ in MUSIC_INSTALL_STEPS]+ idx = int(s.get("step_index") or 0)+ pct = (sum(weights[:idx]) + weights[idx] * frac) * 100 / sum(weights)+ s["percent"] = max(1, min(99, round(pct)))+ return s+++def music_install_start(kind: str = "install") -> tuple[int, dict]:+ """Start the background install. Returns (http_status, body)."""+ if not music_capable():+ return 400, {"error": f"YuE2 needs about {MUSIC_MIN_RAM_GB:.0f} GB of unified memory; "+ f"this Mac reports {SYSTEM_RAM_GB:.0f} GB. The rest of Phosphene is unaffected."}+ cur = STATE.get("current") or {}+ if STATE.get("music_pgid") or (cur.get("params") or {}).get("engine") == "music":+ return 409, {"error": "A song is being written right now. Install or repair the music engine after it finishes."}+ with MUSIC_INSTALL_LOCK:+ if MUSIC_INSTALL.get("active"):+ return 409, {"error": "The music engine is already installing.", "install": True}+ if not music_paths()["missing"]:+ return 200, {"ok": True, "nothing_to_do": True}+ _MUSIC_INSTALL_STOP.clear()+ MUSIC_INSTALL.clear()+ MUSIC_INSTALL.update({"state": "running", "active": True, "kind": kind,+ "step_index": 0, "step_key": MUSIC_INSTALL_STEPS[0][0],+ "step_label": MUSIC_INSTALL_STEPS[0][1],+ "started_ts": time.time(), "finished_ts": None,+ "error": None, "pgid": None,+ "log": collections.deque(maxlen=60)})+ threading.Thread(target=_music_install_thread, daemon=True, name="music-install").start()+ push("[music-install] started from the panel (same steps as the Pinokio sidebar entry)")+ return 202, {"ok": True, "started": True}+++def music_install_stop() -> bool:+ with MUSIC_INSTALL_LOCK:+ if not MUSIC_INSTALL.get("active"):+ return False+ _MUSIC_INSTALL_STOP.set()+ MUSIC_INSTALL["state"] = "stopping"+ pgid = MUSIC_INSTALL.get("pgid")+ if pgid:+ _music_install_kill(pgid)+ return True+++def _music_install_kill(pgid: int, grace: float = 8.0) -> None:+ try:+ os.killpg(pgid, signal.SIGTERM)+ except (OSError, ProcessLookupError):+ return++ def force():+ deadline = time.time() + grace+ while time.time() < deadline:+ try:+ os.killpg(pgid, 0)+ except (OSError, ProcessLookupError):+ return+ time.sleep(0.2)+ try:+ os.killpg(pgid, signal.SIGKILL)+ except (OSError, ProcessLookupError):+ pass+ threading.Thread(target=force, daemon=True, name="stop-music-install").start()+++def _music_install_thread() -> None:+ env = _music_install_env()+ error = None+ for idx, (key, label, _w, command) in enumerate(MUSIC_INSTALL_STEPS):+ if _MUSIC_INSTALL_STOP.is_set():+ break+ with MUSIC_INSTALL_LOCK:+ MUSIC_INSTALL.update(step_index=idx, step_key=key, step_label=label)+ MUSIC_INSTALL["log"].append(f"— {label}")+ push(f"[music-install] step {idx + 1}/{len(MUSIC_INSTALL_STEPS)}: {label}")+ tail: list[str] = []+ try:+ proc = subprocess.Popen(["bash", "-c", command], cwd=str(ROOT), env=env,+ stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,+ stderr=subprocess.STDOUT, text=True, bufsize=1,+ errors="replace", start_new_session=True)+ except OSError as e:+ error = f"Could not start step '{label}': {e}"+ break+ with MUSIC_INSTALL_LOCK:+ MUSIC_INSTALL["pgid"] = proc.pid+ stop_now = _MUSIC_INSTALL_STOP.is_set()+ _proc_guard_write("music_install", proc.pid, proc.pid, note=key)+ if stop_now:+ _music_install_kill(proc.pid)+ try:+ for raw in proc.stdout:+ for line in raw.replace("\r", "\n").splitlines():+ line = line.rstrip()+ if not line:+ continue+ tail = (tail + [line])[-8:]+ with MUSIC_INSTALL_LOCK:+ MUSIC_INSTALL["log"].append(line[:300])+ MUSIC_INSTALL["last_line"] = line[:300]+ rc = proc.wait()+ finally:+ with MUSIC_INSTALL_LOCK:+ MUSIC_INSTALL["pgid"] = None+ _proc_guard_clear("music_install")+ if _MUSIC_INSTALL_STOP.is_set():+ break+ if rc != 0:+ if key == "clone" or key == "sync" or key == "venv":+ missing_tool = next((t for t in ("uv", "git") if shutil.which(t, path=env["PATH"]) is None), None)+ if missing_tool:+ error = (f"'{missing_tool}' was not found, so the panel cannot run this step. "+ "Use “Install the music engine” in the Phosphene sidebar in Pinokio instead.")+ break+ reason = next((l for l in reversed(tail) if not l.startswith(("+", "Traceback"))), "")+ error = f"{label} failed (exit {rc})" + (f": {reason}" if reason else "") + \+ ". Click Install again to resume — nothing already downloaded is lost."+ break+ stopped = _MUSIC_INSTALL_STOP.is_set()+ ok = not stopped and error is None and not music_paths()["missing"]+ if not stopped and error is None and not ok:+ error = "The install finished but the engine still reports: " + "; ".join(music_paths()["missing"][:3])+ with MUSIC_INSTALL_LOCK:+ MUSIC_INSTALL.update(active=False, finished_ts=time.time(), pgid=None,+ state="stopped" if stopped else "done" if ok else "failed",+ error=None if (stopped or ok) else error)+ push("[music-install] " + ("stopped — Install again resumes where it left off" if stopped+ else "done — Audio → Compose is ready" if ok else f"failed: {error}"))+++def _stop_music_install_at_exit() -> None:+ with MUSIC_INSTALL_LOCK:+ pgid = MUSIC_INSTALL.get("pgid") if MUSIC_INSTALL.get("active") else None+ if pgid:+ _MUSIC_INSTALL_STOP.set()+ try:+ os.killpg(pgid, signal.SIGTERM)+ except (OSError, ProcessLookupError):+ pass+++atexit.register(_stop_music_install_at_exit)++def music_params(form: dict) -> dict:"""Explicit allowlist shared by queue construction and dispatch/replays."""def value(key, default=""):@@ -12636,11 +12867,13 @@ def run_music_job_inner(job: dict) -> None:paths = music_paths()if not music_capable():raise RenderRefused("music_ram", f"YuE2 needs about {MUSIC_MIN_RAM_GB:.0f} GB of unified memory; this Mac reports {SYSTEM_RAM_GB:.0f} GB. The rest of Phosphene is unaffected.")+ if MUSIC_INSTALL.get("active"):+ raise RenderRefused("music_installing", "The music engine is still installing. Compose again when the install finishes.")if paths["missing"]:missing = "; ".join(paths["missing"])if paths["repairable"]:- raise RuntimeError(f"The YuE2 weights are on disk but the engine needs repair — missing: {missing}. Click 'Repair the music engine' in the Phosphene sidebar in Pinokio — it is idempotent and skips every weight already on disk, so this is a couple of minutes, NOT an 11 GB download.")- raise RuntimeError(f"The music engine isn't installed — missing: {missing}. Click 'Install the music engine' in the Phosphene sidebar in Pinokio (~11 GB, resumable).")+ raise RuntimeError(f"The YuE2 weights are on disk but the engine needs repair — missing: {missing}. Open Audio → Compose and click 'Repair music engine' (or use the Phosphene sidebar in Pinokio) — it is idempotent and skips every weight already on disk, so this is a couple of minutes, NOT an 11 GB download.")+ raise RuntimeError(f"The music engine isn't installed — missing: {missing}. Open Audio → Compose and click 'Install music engine' (or use the Phosphene sidebar in Pinokio) — ~11 GB, resumable.")if not p["music_style"] and not p["music_lyrics"] and not p["music_instrumental"]:raise RenderRefused("music_input", "Give it something to work with — lyrics, a style description, or both.")held = _music_external_gpu_lock()@@ -16399,6 +16632,7 @@ def _kill_h3_proc() -> None:_PROC_GUARDS: dict[str, tuple[Path, str]] = {"h3": (STATE_DIR / "h3_running.json", "generate_staged"),"music": (STATE_DIR / "music_running.json", "yue2_run.py"),+ "music_install": (STATE_DIR / "music_install_running.json", "scripts/pinokio/music_"),"helper": (STATE_DIR / "helper_running.json", "mlx_warm_helper"),}@@ -25035,6 +25269,50 @@ def _h3_clip_is_complete(path: Path, started_at: float,return False+def _h3_runner_error_message(metrics_path: Path) -> str | None:+ """The runner's own readable failure, when it wrote one.++ Runners with the integrity guard (2026-09-17) record `error_message` for+ a render they refused to save — NaN/inf latents or a flat decode — so the+ job shows that sentence instead of a traceback's last line."""+ try:+ data = json.loads(Path(metrics_path).read_text(encoding="utf-8")) or {}+ except (OSError, ValueError, TypeError):+ return None+ if data.get("status") != "error":+ return None+ msg = str(data.get("error_message") or "").strip()+ return msg or None+++#: A clip whose luma never moves more than this many code values, first frame+#: to last, is not a render — it is what NaN latents decode to.+H3_BLANK_LUMA_SPREAD = 2+++def _h3_clip_is_blank(path: Path) -> bool:+ """True when every frame of `path` is one flat colour.++ The safety net for runners without the integrity guard: j-1a0b02ef0b0-002+ (an F16 user LoRA overflowing inside the runtime adapter) delivered 124+ frames of luma 16.0 and was reported done. Decodes a 64x36 grey thumbnail+ stream — a fraction of a second for a 5 s clip. Unknown = not blank: an+ unreadable file is `_h3_clip_is_complete`'s question, not this one."""+ if not Path(str(FFMPEG)).is_file() and not shutil.which(str(FFMPEG)):+ return False+ try:+ out = subprocess.run(+ [str(FFMPEG), "-v", "error", "-i", str(path), "-an",+ "-vf", "scale=64:36,format=gray", "-f", "rawvideo", "-"],+ capture_output=True, timeout=60)+ except Exception: # noqa: BLE001+ return False+ if out.returncode != 0 or not out.stdout:+ return False+ data = out.stdout+ return (max(data) - min(data)) <= H3_BLANK_LUMA_SPREAD++# UPSCALE & FACE FIX — the user-facing name of the Upscale ×2 lane (owner,# 2026-09-17: "this thing we ship that fixes the faces has the wrong name").# Only the words changed: the mode is still `upscale`, the form keys are still@@ -26086,6 +26364,11 @@ def run_h3_job_inner(job: dict) -> None:f"keeping the file.")rc = 0if rc != 0:+ _runner_msg = _h3_runner_error_message(metrics_path)+ if _runner_msg:+ # The runner refused a broken render and said why (NaN/inf+ # latents, blank decode) — that sentence IS the diagnosis.+ raise RuntimeError(_runner_msg)# Negative rc means the child died on a signal, and NAMING it is# the whole diagnosis: a jetsam kill during joint denoise (issue# #67 — the log just stops at "== w1_joint_denoise ==") used to@@ -26141,6 +26424,22 @@ def run_h3_job_inner(job: dict) -> None:if not out_path.is_file():raise RuntimeError(f"H3 finished but no file landed at {out_path} — check the log.")+ if _h3_clip_is_blank(out_path):+ # Never report a flat black clip as done (older runners have no+ # integrity guard). The file is kept, only hidden from the gallery.+ try:+ set_hidden(str(out_path), True)+ except Exception: # noqa: BLE001+ pass+ _loras = ", ".join(f"{Path(str(_pp)).name} @ {_ps:g}"+ for _pp, _ps in (user_lora_stack or []))+ raise RuntimeError(+ "H3 render failed: every frame came out one flat colour (black), "+ "which is what broken latents decode to — usually a LoRA adapter "+ "overflowing"+ + (f" ({_loras}). Try again without it, or update the H3 runner."+ if _loras else ". Please report it with the log.")+ + f" (clip hidden: {out_path.name})")# ---- export pass: the SAME post-process an LTX render gets ------------# Most tiers write 768×448 (12:7), which is neither 720p nor 1080p and looks@@ -32735,6 +33034,7 @@ def page(theme: str = "") -> str:# switcher knowing anything about H3 in particular."h3": h3_status(),"music": music_status(),+ "music_install": music_install_status(),# LTX's own (quality × length) table, in the SAME shape as `h3` above so# the two strips are rendered by one generalised function rather than# two that drift. Every LTX estimate the page prints is a lookup intodiff --git a/panel/routes_models.py b/panel/routes_models.pyindex 3a04b1e..66e4030 100644--- a/panel/routes_models.py+++ b/panel/routes_models.py@@ -255,3 +255,25 @@ def post_models_repair(h, path, qs, ctype) -> None:f"({', '.join(deleted)}) — re-downloading.")P.threading.Thread(target=P._download_thread, args=(repo,), daemon=True).start()h._json({"ok": True, "deleted": deleted, "repo_id": repo["repo_id"]}, 202); return+++@post("/music/install")+def post_music_install(h, path, qs, ctype) -> None:+ # Audio → Compose's "Install music engine" / "Repair music engine". Runs+ # install_music.js's own steps as a background task; progress rides+ # /status.music_install. Resumable: every step skips finished work.+ _rb = h._read_form_body()+ if _rb is None:+ return+ _body, form = _rb+ kind = "repair" if (form.get("kind", [""])[0] or "") == "repair" else "install"+ code, payload = P.music_install_start(kind)+ h._json(payload, code); return+++@post("/music/install/stop")+def post_music_install_stop(h, path, qs, ctype) -> None:+ if not P.music_install_stop():+ h._json({"error": "no music engine install is running"}, 404); return+ P.push("[music-install] stop requested")+ h._json({"ok": True}); returndiff --git a/panel/routes_queue.py b/panel/routes_queue.pyindex b43b4b2..579b762 100644--- a/panel/routes_queue.py+++ b/panel/routes_queue.py@@ -211,6 +211,7 @@ def get_status(h, parsed) -> None:# exactly like the Q8 download already does.payload["h3"] = P.h3_status()payload["music"] = P.music_status()+ payload["music_install"] = P.music_install_status()payload["train_profile"] = P.TRAIN_PROFILEpayload["train_presets"] = P.TRAIN_PRESETSpayload["train_style_presets"] = P.TRAIN_STYLE_PRESETSdiff --git a/test_h3_render_integrity.py b/test_h3_render_integrity.pynew file mode 100644index 0000000..91b31d0--- /dev/null+++ b/test_h3_render_integrity.py@@ -0,0 +1,79 @@+"""An H3 render that decoded to a flat black clip must never be reported done.++j-1a0b02ef0b0-002 (2026-09-17): an F16 user LoRA overflowed inside the+runner's runtime adapter, every latent went NaN, 124 frames of luma 16 were+written, and the job said "done". Two nets: the runner's own refusal message+(read from metrics) and a panel-side blank-clip check for older runners.+"""+import json+import subprocess+import tempfile+import unittest+from pathlib import Path++import mlx_ltx_panel as p+++def _clip(path: Path, source: str) -> Path:+ subprocess.run(+ [str(p.FFMPEG), "-v", "error", "-y", "-f", "lavfi", "-i", source,+ "-frames:v", "24", "-pix_fmt", "yuv420p", str(path)],+ check=True, capture_output=True)+ return path+++class RunnerErrorMessage(unittest.TestCase):+ def test_reads_the_runner_refusal(self):+ with tempfile.TemporaryDirectory() as tmp:+ m = Path(tmp) / "m.json"+ m.write_text(json.dumps({+ "status": "error", "error_kind": "nonfinite_latents",+ "error_message": "H3 render failed: the latents became NaN/inf after denoise step 1/3"}))+ self.assertIn("NaN/inf", p._h3_runner_error_message(m))++ def test_silent_on_plain_errors_and_success(self):+ with tempfile.TemporaryDirectory() as tmp:+ m = Path(tmp) / "m.json"+ m.write_text(json.dumps({"status": "error", "error": "ValueError: x"}))+ self.assertIsNone(p._h3_runner_error_message(m))+ m.write_text(json.dumps({"status": "done", "error_message": "stale"}))+ self.assertIsNone(p._h3_runner_error_message(m))+ self.assertIsNone(p._h3_runner_error_message(Path(tmp) / "missing.json"))++[email protected](Path(str(p.FFMPEG)).is_file(), "ffmpeg not available")+class BlankClip(unittest.TestCase):+ def test_black_clip_is_blank(self):+ with tempfile.TemporaryDirectory() as tmp:+ clip = _clip(Path(tmp) / "black.mp4", "color=c=black:s=320x180:r=24")+ self.assertTrue(p._h3_clip_is_blank(clip))++ def test_real_and_dark_clips_are_not(self):+ with tempfile.TemporaryDirectory() as tmp:+ clip = _clip(Path(tmp) / "src.mp4", "testsrc2=s=320x180:r=24")+ self.assertFalse(p._h3_clip_is_blank(clip))+ # A dim scene with a little movement is a real clip.+ dim = _clip(Path(tmp) / "dim.mp4",+ "color=c=0x101010:s=320x180:r=24,drawbox=x=100:y=60:w=60:h=60:c=0x404040:t=fill")+ self.assertFalse(p._h3_clip_is_blank(dim))++ def test_unreadable_file_is_not_called_blank(self):+ with tempfile.TemporaryDirectory() as tmp:+ bad = Path(tmp) / "bad.mp4"+ bad.write_bytes(b"not a video")+ self.assertFalse(p._h3_clip_is_blank(bad))+++class Wiring(unittest.TestCase):+ def test_h3_job_uses_both_nets(self):+ import inspect+ src = inspect.getsource(p.run_h3_job_inner)+ self.assertIn("_h3_runner_error_message(metrics_path)", src)+ self.assertIn("_h3_clip_is_blank(out_path)", src)+ # The blank check must sit before the export pass and the sidecar,+ # or the black clip is already published as done.+ self.assertLess(src.index("_h3_clip_is_blank(out_path)"), src.index("---- export pass: the SAME"))+++if __name__ == "__main__":+ unittest.main()diff --git a/test_music_engine.py b/test_music_engine.pyindex 31da52f..fe95ef0 100644--- a/test_music_engine.py+++ b/test_music_engine.py@@ -7,6 +7,7 @@ import ioimport jsonimport osfrom pathlib import Path+import shutilimport signalimport subprocessimport sys@@ -407,23 +408,63 @@ console.log(JSON.stringify({payload,lyrics:els.musicLyrics.value,AUDIO_STUDIO,sudef test_compose_visibility_tracks_install_state():+ """v4.14.1: Compose is always offered. Not installed, the form is greyed,+ the install panel carries one primary button, and Compose opens the card."""src = (ROOT / "webapp/js/characters.js").read_text()- result = node_eval('''let audioModeChoice=null,musicBusy=false;-const window={_ENGINE_PROBES:{music:{available:false,capable:true}}};-const els=Object.fromEntries(['audioModeGroup','musicComposePane','audioDrivePane','musicInstrumental','musicLyrics','musicInstrumentalPill','musicMaxSeconds','musicMaxSecondsVal','musicQuality','musicEstimate','musicGenBtn'].map(id=>[id,{hidden:false,classList:{toggle:()=>{}}}]));+ ids = ['audioModeGroup', 'musicComposePane', 'audioDrivePane', 'musicInstrumental', 'musicLyrics',+ 'musicInstrumentalPill', 'musicMaxSeconds', 'musicMaxSecondsVal', 'musicQuality', 'musicEstimate',+ 'musicGenBtn', 'musicInstallPanel', 'musicInstallModal', 'musicInstallBody', 'musicStyle', 'musicStatus']+ funcs = "\n".join(extract_function(n, src) for n in (+ "updateMusicAvailability", "musicFormChanged", "musicInstallRender", "openMusicInstallCard", "musicGenerate"))+ result = node_eval("""let audioModeChoice=null,musicBusy=false,musicInstall={state:'idle',active:false},musicInstallSeenActive=false;+const window={_ENGINE_PROBES:{music:{available:false,capable:true,min_ram_gb:24}}};+const mk=()=>{const cl=new Set();return {hidden:false,innerHTML:'',value:'',classList:{toggle:(c,on)=>on?cl.add(c):cl.delete(c),has:c=>cl.has(c)}}};+const els=Object.fromEntries(""" + json.dumps(ids) + """.map(id=>[id,mk()]));+els.musicInstallModal.hidden=true;els.musicInstrumental.checked=false;els.musicMaxSeconds.value='240';els.musicQuality.value='final';const document={body:{dataset:{workflow:'audio'}},getElementById:id=>els[id],querySelectorAll:()=>[]};-const renderEngineSwitch=()=>{};-''' + extract_function("updateMusicAvailability", src) + extract_function("musicFormChanged", src) + '''+const renderEngineSwitch=()=>{};const escapeHtml=s=>String(s);let fetched=0;const fetch=()=>{fetched++;};+let toasts=0;const phosToast=()=>{toasts++;};+""" + funcs + """+const snap=()=>({strip:els.audioModeGroup.hidden,compose:els.musicComposePane.hidden,drive:els.audioDrivePane.hidden,+ locked:els.musicComposePane.classList.has('music-locked'),panel:els.musicInstallPanel.hidden,+ panelHtml:els.musicInstallPanel.innerHTML,btnDisabled:els.musicGenBtn.disabled});+(async()=>{const states=[];-for(const available of [false,true,false]) {- updateMusicAvailability({music:{available,capable:true,estimates:{}}});- states.push({strip:els.audioModeGroup.hidden,compose:els.musicComposePane.hidden,drive:els.audioDrivePane.hidden});-}-console.log(JSON.stringify(states));''')- assert result == [{"strip": True, "compose": True, "drive": False},- {"strip": False, "compose": False, "drive": True},- {"strip": True, "compose": True, "drive": False}]+updateMusicAvailability({music:{available:false,capable:true,min_ram_gb:24,estimates:{}}});+states.push(snap());+audioModeChoice='compose';updateMusicAvailability();states.push(snap());+await musicGenerate();+const card={opened:!els.musicInstallModal.hidden,html:els.musicInstallBody.innerHTML,fetched};+updateMusicAvailability({music:{available:false,capable:true,min_ram_gb:24,estimates:{}},+ music_install:{active:true,state:'running',percent:42,step_index:5,steps:6,step_label:'Downloading the model (~10.5 GB)',bytes_done:4e9,bytes_total:10.4e9}});+states.push(snap());+updateMusicAvailability({music:{available:true,capable:true,min_ram_gb:24,estimates:{}},music_install:{active:false,state:'done'}});+states.push(snap());+updateMusicAvailability({music:{available:false,capable:false,min_ram_gb:24,estimates:{}},music_install:{active:false,state:'idle'}});+states.push(snap());+console.log(JSON.stringify({states,card,toasts}));+})();""")+ s = result["states"]+ # Not installed, never chosen: the Compose chip is there; Drive stays the default pane.+ assert s[0]["strip"] is False and s[0]["compose"] is True and s[0]["drive"] is False+ # Compose chosen: greyed form, install panel with ONE primary button, Compose button live.+ assert s[1]["compose"] is False and s[1]["locked"] and s[1]["panel"] is False+ assert "Install music engine (YuE2, ~11 GB)" in s[1]["panelHtml"]+ assert s[1]["panelHtml"].count('class="primary"') == 1+ assert s[1]["btnDisabled"] is False+ # Pressing Compose before install opens the same install card and queues nothing.+ assert result["card"]["opened"] and "Install music engine (YuE2, ~11 GB)" in result["card"]["html"]+ assert result["card"]["fetched"] == 0+ # Installing: progress with the step and the bytes, and a Stop.+ assert "42%" in s[2]["panelHtml"] and "Step 6 of 6" in s[2]["panelHtml"]+ assert "4.0 of 10.4 GB" in s[2]["panelHtml"] and "musicInstallStop()" in s[2]["panelHtml"]+ # Done: the form unlocks by itself (no reload), the panel goes away, one toast.+ assert s[3]["locked"] is False and s[3]["panel"] is True and s[3]["compose"] is False+ assert result["toasts"] == 1+ # Not capable: no install button, Compose disabled.+ assert "can't run on this Mac" in s[4]["panelHtml"] and "primary" not in s[4]["panelHtml"]+ assert s[4]["btnDisabled"] is True# ---- review fixes (2026-09-17) ------------------------------------------------@@ -618,3 +659,201 @@ def test_fetch_clears_abandoned_temporaries_and_does_not_credit_them():src = (ROOT / "scripts/pinokio/music_fetch.py").read_text()assert 'stage.rglob("*.incomplete")' in src and "leftover.unlink()" in srcassert "partial_bytes" not in src+++# ---- in-panel install (v4.14.1: "Compose is always in Audio") ------------------++def _install_js_messages():+ src = (ROOT / "install_music.js").read_text()+ import re as _re+ return [json.loads('"' + m + '"') for m in _re.findall(r'shell\.run", params: \{\s*message: "((?:[^"\\]|\\.)*)"', src)]+++def test_panel_install_runs_exactly_the_sidebar_steps():+ assert [cmd for *_, cmd in P.MUSIC_INSTALL_STEPS] == _install_js_messages()+ assert len(P.MUSIC_INSTALL_STEPS) == 6+++FAKE_GIT = '''#!/bin/sh+case "$1" in+ clone) dest=""; for a in "$@"; do dest="$a"; done; mkdir -p "$dest/.git"; printf "[project]\\nname='fake'\\n" > "$dest/pyproject.toml";;+ rev-parse) cat "$FAKE_PIN_FILE";;+ *) :;;+esac+'''+FAKE_UV = '''#!/bin/sh+if [ "$1" = venv ]; then+ for a in "$@"; do d="$a"; done+ mkdir -p "$d/bin"; printf '#!/bin/sh\\nexec "%s" "$@"\\n' "$FAKE_PY" > "$d/bin/python"; chmod +x "$d/bin/python"+ echo "pyvenv fake" > "$d/pyvenv.cfg"+fi+echo "uv $1 ok"+'''+FAKE_DF = '''#!/bin/sh+echo "Filesystem 1024-blocks Used Available Capacity Mounted on"+echo "fake 999999999 1 ${FAKE_FREE_KB:-99999999} 1% /"+'''+# The mocked download: grows a staged file (progress), waits while a hold file+# exists (so a test can Stop it mid-download), then "downloads" the fixture pack.+FAKE_FETCH = '''import os, shutil, sys, time+from pathlib import Path+models = Path(os.environ["LTX_MUSIC_MODELS"])+stage = models / ".staging"+stage.mkdir(parents=True, exist_ok=True)+if os.environ.get("FAKE_FETCH_FAIL"):+ print("YuE2 pack: network unreachable", file=sys.stderr, flush=True)+ sys.exit(1)+part = stage / "ar-bf16.safetensors.incomplete"+with part.open("ab") as f:+ f.write(b"x" * 1_000_000)+print("Fetch generator/ar-bf16.safetensors from vanch007/mlx-Yue2-3B", flush=True)+hold = Path(os.environ["FAKE_FETCH_HOLD"])+while hold.exists():+ time.sleep(0.05)+part.unlink()+for sub in ("generator", "vae", "pack_source.json"):+ src = Path(os.environ["FAKE_PACK_SRC"]) / sub+ (shutil.copytree if src.is_dir() else shutil.copyfile)(src, models / sub)+print("YuE2 pack verified.", flush=True)+'''+++def install_env(pack, tmp_path, monkeypatch):+ models, engine = pack+ src = tmp_path / "pack-src"+ models.rename(src)+ app = tmp_path / "app"+ (app / "scripts/pinokio").mkdir(parents=True)+ (app / "scripts/music").mkdir(parents=True)+ for name in ("music_preflight.sh", "music_clone.sh", "music_checkout.sh", "music_venv.sh", "music_sync.sh"):+ shutil.copy(ROOT / "scripts/pinokio" / name, app / "scripts/pinokio" / name)+ shutil.copy(ROOT / "scripts/music/engine_pin.txt", app / "scripts/music/engine_pin.txt")+ (app / "scripts/pinokio/music_fetch.py").write_text(FAKE_FETCH)+ fakebin = tmp_path / "bin"+ fakebin.mkdir()+ for name, body in (("git", FAKE_GIT), ("uv", FAKE_UV), ("df", FAKE_DF),+ ("sysctl", "#!/bin/sh\necho 68719476736\n")):+ (fakebin / name).write_text(body)+ (fakebin / name).chmod(0o755)+ new_models, new_engine = tmp_path / "new-models", tmp_path / "new-engine"+ hold = tmp_path / "hold"+ monkeypatch.setattr(P, "ROOT", app)+ monkeypatch.setattr(P, "MUSIC_ROOT", new_engine)+ monkeypatch.setattr(P, "MUSIC_MODELS", new_models)+ monkeypatch.setattr(P, "_PROC_GUARDS", {"music_install": (tmp_path / "mi.json", "scripts/pinokio/music_")})+ monkeypatch.delenv("PINOKIO_HOME", raising=False)+ for k, v in {"PATH": f"{fakebin}:/usr/bin:/bin:/usr/sbin:/sbin", "LTX_MUSIC_ROOT": str(new_engine),+ "LTX_MUSIC_MODELS": str(new_models), "FAKE_PY": sys.executable,+ "FAKE_PIN_FILE": str(app / "scripts/music/engine_pin.txt"),+ "FAKE_PACK_SRC": str(src), "FAKE_FETCH_HOLD": str(hold)}.items():+ monkeypatch.setenv(k, v)+ monkeypatch.setattr(P, "MUSIC_INSTALL", {"state": "idle", "active": False})+ monkeypatch.setattr(P, "push", lambda line: None)+ P._MUSIC_INSTALL_BYTES.update(ts=0.0, bytes=0)+ return SimpleNamespace(hold=hold, models=new_models, engine=new_engine, fakebin=fakebin)+++def _wait(pred, timeout=30.0):+ deadline = time.time() + timeout+ while time.time() < deadline:+ if pred():+ return True+ time.sleep(0.05)+ return False+++def test_install_from_the_panel_end_to_end_with_stop_and_resume(install_env):+ env = install_env+ assert P.music_status()["available"] is False+ env.hold.touch()+ code, body = P.music_install_start()+ assert code == 202 and body["started"]+ # Second click while it runs is refused, not a second downloader.+ assert P.music_install_start()[0] == 409+ # The mocked download is running: progress, byte counter, orphan guard.+ assert _wait(lambda: P.music_install_status().get("step_key") == "fetch"+ and "Fetch generator" in (P.music_install_status().get("last_line") or ""))+ P._MUSIC_INSTALL_BYTES["ts"] = 0.0+ s = P.music_install_status()+ assert s["active"] and s["step_index"] == 5 and s["steps"] == 6+ assert s["bytes_done"] >= 1_000_000 and s["bytes_total"] > 10e9+ assert 20 <= s["percent"] <= 99+ guard = json.loads((env.hold.parent / "mi.json").read_text())+ assert "scripts/pinokio/music_" in P._pid_cmdline(guard["pid"])+ # A song can't start mid-install.+ job = P.make_job({"mode": "music", "music_style": "piano"})+ with pytest.raises(P.RenderRefused) as refused:+ P.run_music_job_inner(job)+ assert "still installing" in str(refused.value)+ # Stop: the group dies, the state says stopped, the staged bytes stay.+ pgid = P.MUSIC_INSTALL["pgid"]+ assert P.music_install_stop()+ assert _wait(lambda: not P.MUSIC_INSTALL["active"])+ assert P.MUSIC_INSTALL["state"] == "stopped" and P.MUSIC_INSTALL["error"] is None+ assert _wait(lambda: not P._pid_alive(pgid), 10)+ assert not (env.hold.parent / "mi.json").exists()+ assert P.music_status()["available"] is False+ assert (env.engine / ".venv/bin/python").is_file()+ # Resume: same button, finishes, and Compose is available with no restart.+ env.hold.unlink()+ code, _ = P.music_install_start()+ assert code == 202+ assert _wait(lambda: not P.MUSIC_INSTALL["active"])+ assert P.MUSIC_INSTALL["state"] == "done", P.MUSIC_INSTALL+ st = P.music_status()+ assert st["available"] and st["reason"] == "ok"+ assert P.music_install_start() == (200, {"ok": True, "nothing_to_do": True})+ assert not (env.models / ".staging/ar-bf16.safetensors.incomplete").exists()+++def test_install_failure_names_the_reason_and_can_retry(install_env, monkeypatch):+ monkeypatch.setenv("FAKE_FREE_KB", "1000")+ assert P.music_install_start()[0] == 202+ assert _wait(lambda: not P.MUSIC_INSTALL["active"])+ assert P.MUSIC_INSTALL["state"] == "failed"+ assert "14 GB free" in P.MUSIC_INSTALL["error"] and "Install again" in P.MUSIC_INSTALL["error"]+ monkeypatch.delenv("FAKE_FREE_KB")+ monkeypatch.setenv("FAKE_FETCH_FAIL", "1")+ assert P.music_install_start()[0] == 202+ assert _wait(lambda: not P.MUSIC_INSTALL["active"])+ assert P.MUSIC_INSTALL["state"] == "failed"+ assert "network unreachable" in P.MUSIC_INSTALL["error"]+ assert "Downloading the model" in P.MUSIC_INSTALL["error"]+++def test_install_env_finds_pinokio_tools_and_drops_the_ltx_venv(monkeypatch, tmp_path):+ home = tmp_path / "pinokio"+ (home / "bin/miniforge/bin").mkdir(parents=True)+ app = home / "api/phosphene.git"+ app.mkdir(parents=True)+ monkeypatch.setattr(P, "ROOT", app)+ monkeypatch.delenv("PINOKIO_HOME", raising=False)+ monkeypatch.setenv("VIRTUAL_ENV", "/x/ltx-2-mlx/env")+ monkeypatch.setenv("PYTHONPATH", "/somewhere")+ monkeypatch.setenv("PATH", f"{Path(sys.prefix) / 'bin'}:/usr/bin:/bin")+ monkeypatch.setenv("HF_HOME", "/hf/home")+ env = P._music_install_env()+ parts = env["PATH"].split(":")+ assert parts[0] == str(home / "bin/miniforge/bin")+ assert str(Path(sys.prefix) / "bin") not in parts and "/usr/bin" in parts+ assert "VIRTUAL_ENV" not in env and "PYTHONPATH" not in env+ assert env["HF_HOME"] == "/hf/home" and env["GIT_TERMINAL_PROMPT"] == "0"+++def test_install_refusals(pack, monkeypatch, http_server):+ monkeypatch.setattr(P, "MUSIC_INSTALL", {"state": "idle", "active": False})+ # Installed: nothing to do, through the real route.+ code, _, body = http_server("POST", "/music/install", "kind=install",+ {"Content-Type": "application/x-www-form-urlencoded"})+ assert code == 200 and json.loads(body)["nothing_to_do"]+ code, _, body = http_server("POST", "/music/install/stop", "", {"Content-Type": "application/x-www-form-urlencoded"})+ assert code == 404+ code, _, body = http_server("GET", "/status")+ assert json.loads(body)["music_install"]["state"] == "idle"+ monkeypatch.setattr(P, "SYSTEM_RAM_GB", 16.0)+ code, body = P.music_install_start()+ assert code == 400 and "24 GB" in body["error"]+ monkeypatch.setattr(P, "SYSTEM_RAM_GB", 64.0)+ monkeypatch.setitem(P.STATE, "current", {"params": {"engine": "music"}})+ assert P.music_install_start()[0] == 409diff --git a/webapp/index.html b/webapp/index.htmlindex d6deb5f..c6bf782 100644--- a/webapp/index.html+++ b/webapp/index.html@@ -3063,6 +3063,7 @@<button type="button" class="mode-chip pill-btn" data-audio-mode="drive" onclick="audioModeSet('drive')">Drive video<span class="mc-sub sub">use a track you have</span></button></div><div id="musicComposePane" hidden>+ <div class="composer-card music-install-panel" id="musicInstallPanel" role="status" hidden></div><div class="composer-card"><label for="musicLyrics">Lyrics</label><textarea id="musicLyrics" class="composer-prompt" rows="8" placeholder="[Verse]@@ -5053,19 +5054,23 @@ The last line"></textarea></div></div>+<!-- ============== MUSIC ENGINE (YuE2) INSTALL CARD ============== -->+<!-- Opened by Compose before the engine exists, by the YuE2 row of the header+ engine picker and by Settings → Models. The install runs from the panel+ (the same steps as the Pinokio sidebar entry); see musicInstallRender. -->+<div id="musicInstallModal" class="models-modal" role="dialog" aria-modal="true" aria-labelledby="musicInstallTitle" hidden onclick="if(event.target===this)closeMusicInstallCard()">+ <div class="models-card">+ <div class="models-head"><h2 id="musicInstallTitle">YuE2 · music engine</h2><button type="button" class="ghost-btn" onclick="closeMusicInstallCard()">Close</button></div>+ <div id="musicInstallBody" class="music-install-body"></div>+ <p class="hint">YuE2 license (CC BY-NC 4.0 + creator permission): individual creators may monetize their songs; companies need a license for the weights.</p>+ </div>+</div><!-- ============== HAILUO H3 INSTALL CARD ============== --><!-- Opened by clicking the H3 engine pill when the pack isn't installed, andby the H3 row in the Models modal. H3 installs through Pinokio (clone +venv + ~75 GB of weights), not through the panel's `hf download` path, sothis card explains the one sidebar click — the same shape the Sharp andimage-engine optional packs already use. -->-<div id="musicInstallModal" class="models-modal" role="dialog" aria-modal="true" aria-labelledby="musicInstallTitle" hidden onclick="if(event.target===this)closeMusicInstallCard()">- <div class="models-card">- <div class="models-head"><h2 id="musicInstallTitle">YuE2 · music engine</h2><button type="button" onclick="closeMusicInstallCard()" aria-label="Close">×</button></div>- <p id="musicInstallBody"></p>- <p class="hint">YuE2 license (CC BY-NC 4.0 + creator permission): individual creators may monetize their songs; companies need a license for the weights.</p>- </div>-</div><div id="h3InstallModal" class="models-modal" style="display:none"role="dialog" aria-modal="true" aria-labelledby="h3InstallTitle"onclick="if(event.target===this) closeH3InstallCard()">diff --git a/webapp/js/characters.js b/webapp/js/characters.jsindex ca6eed3..69ac6d0 100644--- a/webapp/js/characters.js+++ b/webapp/js/characters.js@@ -22,20 +22,37 @@ let audioModeChoice = null;let musicBusy = false;function musicComposeActive() {- return document.body.dataset.workflow === 'audio' && audioModeChoice === 'compose'- && !!window._ENGINE_PROBES.music.available;+ // Compose is ALWAYS a real surface now — installed or not. Not installed, it+ // is the place the install lives ("it kicks in when you try to use it").+ return document.body.dataset.workflow === 'audio' && audioModeChoice === 'compose';}function musicInit() {try { audioModeChoice = localStorage.getItem('phos_audio_mode'); } catch (_) {}if (!['compose', 'drive'].includes(audioModeChoice)) audioModeChoice = null;- updateMusicAvailability({ music: BOOT.music });+ updateMusicAvailability({ music: BOOT.music, music_install: BOOT.music_install });}+// The install task's last snapshot (/status.music_install), and whether this+// tab watched it run — "done" only earns a toast when we saw it happen.+let musicInstall = { state: 'idle', active: false };+let musicInstallSeenActive = false;function updateMusicAvailability(s) {if (s && s.music) window._ENGINE_PROBES.music = s.music;- const ready = !!window._ENGINE_PROBES.music.available;- if (audioModeChoice == null && ready) audioModeChoice = 'compose';- const compose = ready && audioModeChoice === 'compose';- document.getElementById('audioModeGroup').hidden = !ready;+ if (s && s.music_install) {+ const was = musicInstallSeenActive;+ musicInstall = s.music_install;+ if (musicInstall.active) musicInstallSeenActive = true;+ else if (was) {+ musicInstallSeenActive = false;+ if (musicInstall.state === 'done' && typeof phosToast === 'function') {+ phosToast('Music engine installed — Compose is ready.', { kind: 'success' });+ }+ }+ }+ const music = window._ENGINE_PROBES.music;+ const ready = !!music.available;+ if (audioModeChoice == null) audioModeChoice = ready ? 'compose' : 'drive';+ const compose = audioModeChoice === 'compose';+ document.getElementById('audioModeGroup').hidden = false;document.getElementById('musicComposePane').hidden = !compose;document.getElementById('audioDrivePane').hidden = compose;document.querySelectorAll('#audioModeGroup [data-audio-mode]').forEach(b => {@@ -43,6 +60,17 @@ function updateMusicAvailability(s) {b.classList.toggle('active', active);b.setAttribute('aria-pressed', String(active));});+ // Not installed: the form stays visible (so you can see what you are+ // installing) but greyed, and the install panel sits on top of it.+ const pane = document.getElementById('musicComposePane');+ if (pane) pane.classList.toggle('music-locked', !ready);+ const panel = document.getElementById('musicInstallPanel');+ if (panel) {+ panel.hidden = ready && !musicInstall.active;+ if (!panel.hidden) musicInstallRender(panel, 'inline');+ }+ const modal = document.getElementById('musicInstallModal');+ if (modal && !modal.hidden) musicInstallRender(document.getElementById('musicInstallBody'), 'modal');musicFormChanged();if (document.body.dataset.workflow === 'audio') renderEngineSwitch();}@@ -72,7 +100,11 @@ function musicFormChanged() {const estimate = ((music.estimates || {})[quality] || {})[String(seconds)];document.getElementById('musicEstimate').textContent = estimate? `≈ ${estimate.eta} at full length · estimate` : '';- document.getElementById('musicGenBtn').disabled = musicBusy || !music.available || !music.capable;+ const btn = document.getElementById('musicGenBtn');+ btn.disabled = musicBusy || !music.capable;+ btn.title = music.available ? '' : (music.capable+ ? 'The music engine is not installed yet — click to install it'+ : `YuE2 needs ${music.min_ram_gb} GB of unified memory`);}function musicFormParams() {const instrumental = document.getElementById('musicInstrumental').checked;@@ -89,6 +121,8 @@ function musicFormParams() {}async function musicGenerate() {if (musicBusy) return;+ // Pressing Compose before the engine exists IS the request to install it.+ if (!window._ENGINE_PROBES.music.available) { openMusicInstallCard(); return; }const fd = musicFormParams();const status = document.getElementById('musicStatus');if (!fd.get('music_style').trim() && !fd.get('music_lyrics').trim() && fd.get('music_instrumental') !== 'on') {@@ -122,12 +156,65 @@ function useTrackInA2V(path) {audioStudioRenderSlots();phosToast('Track loaded — add a prompt and generate.');}+// One renderer, two places: the panel on top of Compose and the modal card+// (opened by Compose, the header engine picker and Settings → Models).+function musicInstallRender(el, where) {+ if (!el) return;+ const music = window._ENGINE_PROBES.music || {};+ const inst = musicInstall || {};+ const size = 'YuE2, ~11 GB';+ let html;+ if (!music.capable) {+ html = `<p class="mi-lead">YuE2 needs about ${escapeHtml(String(music.min_ram_gb || 24))} GB of unified memory, so it can't run on this Mac. The rest of Phosphene is unaffected.</p>`;+ } else if (inst.active) {+ const pct = inst.percent || 1;+ const step = `Step ${(inst.step_index || 0) + 1} of ${inst.steps || 6} · ${escapeHtml(inst.step_label || '')}`;+ const bytes = inst.bytes_total+ ? ` · ${(inst.bytes_done / 1e9).toFixed(1)} of ${(inst.bytes_total / 1e9).toFixed(1)} GB` : '';+ html = `<p class="mi-lead"><b>${inst.state === 'stopping' ? 'Stopping…' : 'Installing the music engine…'}</b> ${pct}%</p>+ <div class="progress-bar"><div class="fill" style="width:${pct}%"></div></div>+ <p class="mi-sub">${step}${bytes}</p>+ <p class="mi-line">${escapeHtml(inst.last_line || '')}</p>+ <div class="mi-actions"><button type="button" class="danger" onclick="musicInstallStop()" ${inst.state === 'stopping' ? 'disabled' : ''}>Stop</button>+ <span class="mi-note">You can keep using Phosphene. Compose unlocks by itself when it finishes.</span></div>`;+ } else if (music.available) {+ html = `<p class="mi-lead"><b>The music engine is installed.</b> Write lyrics and a style, then press Compose.</p>+ ${where === 'modal' ? '<div class="mi-actions"><button type="button" class="primary" onclick="closeMusicInstallCard();audioModeSet(\'compose\');workflowSwitch(\'audio\')">Start composing</button></div>' : ''}`;+ } else {+ const repair = !!music.repairable;+ const failed = inst.state === 'failed' && inst.error;+ const stopped = inst.state === 'stopped';+ const label = repair ? 'Repair music engine (weights kept)' : `Install music engine (${size})`;+ const lead = repair+ ? 'The YuE2 weights are on disk but the engine needs repair. This takes a couple of minutes and re-downloads nothing.'+ : 'Compose writes a whole song — vocals and arrangement — from your lyrics and a style. It needs the YuE2 music engine: a one-time ~11 GB download that resumes if interrupted.';+ html = `<p class="mi-lead">${lead}</p>+ ${failed ? `<p class="mi-error">${escapeHtml(inst.error)}</p>` : ''}+ ${stopped ? '<p class="mi-sub">Install stopped. Click again to resume where it left off.</p>' : ''}+ <div class="mi-actions"><button type="button" class="primary" onclick="musicInstallStart(${repair ? "'repair'" : ''})">${escapeHtml(failed || stopped ? (repair ? 'Try the repair again' : 'Resume install (YuE2, ~11 GB)') : label)}</button></div>+ <p class="mi-note">Needs ${escapeHtml(String(music.min_ram_gb || 24))} GB unified memory and 14 GB free disk. Also available from the Phosphene sidebar in Pinokio.</p>`;+ }+ el.innerHTML = html;+}+async function musicInstallStart(kind) {+ const fd = new URLSearchParams({ kind: kind === 'repair' ? 'repair' : 'install' });+ try {+ const r = await fetch('/music/install', { method: 'POST', body: fd });+ const result = await r.json().catch(() => ({}));+ if (!r.ok && !result.install) throw new Error(result.error || 'Could not start the install');+ if (result.started || result.install) musicInstall = { ...musicInstall, active: true, state: 'running', percent: 1, step_index: 0 };+ } catch (e) {+ musicInstall = { state: 'failed', active: false, error: e.message || String(e) };+ }+ updateMusicAvailability();+ if (typeof poll === 'function') poll();+}+async function musicInstallStop() {+ try { await fetch('/music/install/stop', { method: 'POST' }); } catch (_) {}+ if (typeof poll === 'function') poll();+}function openMusicInstallCard() {- const music = window._ENGINE_PROBES.music;- const body = document.getElementById('musicInstallBody');- body.textContent = music.repairable- ? 'The YuE2 weights are on disk but the engine needs repair. Click “Repair the music engine (weights kept — no re-download)” in the Phosphene sidebar in Pinokio. It skips every intact weight.'- : `Click “Install the music engine (YuE2, ~11 GB)” in the Phosphene sidebar in Pinokio. Needs ${music.min_ram_gb} GB unified memory. The download resumes if interrupted. Compose appears in Audio when it is ready.`;+ musicInstallRender(document.getElementById('musicInstallBody'), 'modal');document.getElementById('musicInstallModal').hidden = false;}function closeMusicInstallCard() {@@ -2979,6 +3066,7 @@ document.querySelectorAll('#extendModeGroup .pill-btn').forEach(b => b.onclick =Object.assign(globalThis, {musicComposeActive, musicInit, updateMusicAvailability, audioModeSet, musicPick, musicFormChanged,musicFormParams, musicGenerate, useTrackInA2V, openMusicInstallCard, closeMusicInstallCard,+ musicInstallRender, musicInstallStart, musicInstallStop,windowPromptsInput,audioStudioInit, audioStudioDurationChanged, audioStudioEnhancePrompt, audioStudioGenerate,trainRecommendedPreset, trainUpdatePresetButtons, trainUpdatePresetNote, downloadSampleCharacter,diff --git a/webapp/js/preview.js b/webapp/js/preview.jsindex 38dee18..61550f6 100644--- a/webapp/js/preview.js+++ b/webapp/js/preview.js@@ -1865,16 +1865,19 @@ async function refreshModelsModal({ silent = false } = {}) {let musicRow = '';const music = (LAST_STATUS && LAST_STATUS.music) || BOOT.music;if (music && music.capable) {+ const inst = (LAST_STATUS && LAST_STATUS.music_install) || {};const statusText = music.available? `Ready · Compose unlocked in the Audio tab · ${escapeHtml(music.root || '')}`+ : inst.active ? `Installing… ${inst.percent || 1}% · ${escapeHtml(inst.step_label || '')}`: music.repairable ? 'Weights on disk · engine needs repair'- : `Available to install · one click in the Pinokio sidebar · ~11 GB · needs ${music.min_ram_gb} GB unified memory`;+ : `Available to install · one click here or in Audio → Compose · ~11 GB · needs ${music.min_ram_gb} GB unified memory`;musicRow = `<li class="${music.available ? 'ready' : 'missing'}"><span class="icon">♪</span><div class="meta"><span class="ttl">YuE2 · music engine</span><span class="sub">Lyrics and a style description in, a finished song out — vocals and arrangement together</span><span class="sub">${statusText}</span></div>- ${music.available ? '<button class="ghost" disabled>Installed</button>' : '<button onclick="openMusicInstallCard()">How to install</button>'}+ ${music.available ? '<button class="ghost" disabled>Installed</button>'+ : `<button onclick="openMusicInstallCard()">${inst.active ? 'Progress' : music.repairable ? 'Repair' : 'Install'}</button>`}</li>`;}list.innerHTML = (rows + h3Row + musicRow) || `<li class="empty-state">No model manifest found — required_files.json is missing or unreadable.</li>`;diff --git a/webapp/style/panel.css b/webapp/style/panel.cssindex 89f0300..4cd0eff 100644--- a/webapp/style/panel.css+++ b/webapp/style/panel.css@@ -10643,7 +10643,24 @@ body[data-workflow="oneshot"] #audioSectionTab { display: none !important; }.music-card-note { position: absolute; inset: auto 0 22%; text-align: center; font-size: 40px; color: var(--muted); }.car-thumb-wrap:has(.music-card-player) { display: flex; align-items: flex-start; padding-top: 8px; }.music-info-text { white-space: pre-wrap; overflow-wrap: anywhere; }-=======+/* Compose before the engine exists: the form stays readable but inert, and the+ install panel on top carries the one action. The Compose button stays live —+ pressing it opens the install card. */+#musicInstallPanel[hidden] { display: none !important; }+.music-install-panel { padding: 14px 16px; border-color: rgba(177,74,255,0.42); }+#musicComposePane.music-locked > .composer-card:not(.music-install-panel),+#musicComposePane.music-locked > .quick-settings,+#musicComposePane.music-locked .queue-strip { opacity: .45; pointer-events: none; user-select: none; }+.music-install-body, .music-install-panel { line-height: 1.5; }+.music-install-body .mi-lead, .music-install-panel .mi-lead { margin: 0 0 10px; }+.mi-sub, .mi-note { margin: 6px 0 0; color: var(--muted); font-size: var(--fs-sm, 12px); }+.mi-line { margin: 4px 0 0; color: var(--muted); font-size: 11px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace;+ white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }+.mi-error { margin: 0 0 10px; color: var(--danger, #ff6b6b); overflow-wrap: anywhere; }+.mi-actions { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; margin-top: 10px; }+.mi-actions .mi-note { margin: 0; }+.mi-actions .danger { width: auto; flex: 0 0 auto; padding-left: 18px; padding-right: 18px; }+.mi-actions .mi-note { flex: 1 1 200px; }/* After-the-draft Upscale & Face Fix (H3 Customize → Upscale). A checkboxunder the size pills: it is an extra job, not a size. While it is on,the draft ships as rendered, so the size pills step back. */