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.

v4.14.1 — Compose is always in Audio; H3 black renders fixed

mrbizarrod8a7ca4b4bff
diff --git a/README.md b/README.md
index 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 as
48 kHz stereo WAVs in the gallery; **Drive video** loads a song into the video
diff --git a/VERSION b/VERSION
index c412a4e..d2b9909 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-4.14.0
+4.14.1
diff --git a/docs/MUSIC_ENGINE.md b/docs/MUSIC_ENGINE.md
index 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 together
from 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 estimates
diff --git a/docs/STATE.md b/docs/STATE.md
index 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** (renamed
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index 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 = 0
if 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 into
diff --git a/panel/routes_models.py b/panel/routes_models.py
index 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}); return
diff --git a/panel/routes_queue.py b/panel/routes_queue.py
index 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_PROFILE
payload["train_presets"] = P.TRAIN_PRESETS
payload["train_style_presets"] = P.TRAIN_STYLE_PRESETS
diff --git a/test_h3_render_integrity.py b/test_h3_render_integrity.py
new file mode 100644
index 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.py
index 31da52f..fe95ef0 100644
--- a/test_music_engine.py
+++ b/test_music_engine.py
@@ -7,6 +7,7 @@ import io
import json
import os
from pathlib import Path
+import shutil
import signal
import subprocess
import sys
@@ -407,23 +408,63 @@ console.log(JSON.stringify({payload,lyrics:els.musicLyrics.value,AUDIO_STUDIO,su
def 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 src
assert "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] == 409
diff --git a/webapp/index.html b/webapp/index.html
index 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, and
by 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, so
this card explains the one sidebar click — the same shape the Sharp and
image-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.js
index 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.js
index 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.css
index 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 checkbox
under 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. */