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
// Phosphene Pinokio menu.
//
// Uses required_files.json as the single source of truth for what counts
// as "installed". The same file is consumed by mlx_ltx_panel.py (run-time
// completeness checks) and is what install.js / update.js are wired to
// produce — so the menu state never drifts from what the panel will accept.
//
// Start needs a working runtime. Models are requested inside the app;
// an empty model folder is a valid first run. Q8 remains an optional offer.
const fs = require("fs")
const os = require("os")
const path = require("path")
// Hailuo H3 (optional second video engine): the compact Q8 DiT lane's measured
// peak is 25.63 GiB (text_encode, a 7-second phase), so the floor is 36 GB —
// the same number H3_MIN_RAM_GB_Q8 in mlx_ltx_panel.py and
// scripts/pinokio/h3_preflight.sh use. Keep all three in sync.
//
// 46e9 UNTIL v4.8.0, AND THAT IS THE INCIDENT. 46 was never a measurement — it
// was a guard band picked to sit ~4 GB under a 48 GB Mac's marketing number
// back when the only number anyone had was "27.3 GiB peak". v4.8.0 lowered the
// PANEL's floor to 36 on the phase profile above and left this restatement and
// the preflight's behind, so a 36-48 GB Mac was told by the panel that H3 runs
// and by this menu that H3 does not exist. One number, three files.
const H3_MIN_BYTES = 36 * 1000 * 1000 * 1000
// The full bf16 engine's floor (H3_MIN_RAM_GB = 60 in the panel). Below it the
// compact Q8 engine is the only lane that renders, so its build is REQUIRED.
const H3_BF16_BYTES = 60 * 1000 * 1000 * 1000
function h3Capable() {
try {
return os.totalmem() >= H3_MIN_BYTES
} catch (e) {
// Fail CLOSED here (unlike the installer's fail-open preflight): if we
// can't read the hardware, don't advertise a 75 GB download that might
// never run. The user can still install it from the panel's instructions.
return false
}
}
function musicCapable() {
// Same floor as MUSIC_MIN_RAM_GB (16 GB since 4.19.12). A "16 GB" Mac reports
// 17179869184 bytes, so the decimal 16e9 admits it and nothing smaller.
try { return os.totalmem() >= 16 * 1000 * 1000 * 1000 } catch (e) { return false }
}
// SYS-18: the Q8 download entry below was offered on EVERY Mac regardless
// of RAM — 30 GB of disk and bandwidth for a feature the panel's own tier
// table (SYSTEM_CAPS["allows_q8"], mlx_ltx_panel.py) refuses under 48 GB
// (the base/"Compact" tier). Same threshold, same fail-closed shape as
// h3Capable()/musicCapable() above.
function q8Capable() {
try { return os.totalmem() >= 48 * 1000 * 1000 * 1000 } catch (e) { return false }
}
function getInstallRoot(info) {
// Pinokio's `info.path` API has shifted across versions:
// - older Pinokio: info.path is a STRING property (the install dir itself)
// - newer Pinokio: info.path is a FUNCTION that joins args with install dir
// cocktailpeanut's working diff uses the function form; some user installs
// (Mr Bizarro's reproduced this) error with TypeError on the function call, then
// Pinokio's outer error handler stat's a bogus path constructed from the
// error's .errno property — surfacing as "ENOENT ... stat '.../Errno'".
// Try both shapes; fall back to __dirname which Pinokio sets to the install
// dir for the running menu module on every version we've tested.
if (info && typeof info.path === "function") {
try { return path.dirname(info.path("required_files.json")) } catch (e) {}
}
if (info && typeof info.path === "string") return info.path
return __dirname
}
function loadRequired(installRoot) {
// Read required_files.json synchronously — Pinokio menus are sync today
// (info.exists is sync) and this is small (< 1 KB) so blocking is fine.
try {
return JSON.parse(fs.readFileSync(path.join(installRoot, "required_files.json"), "utf8"))
} catch (e) {
// Treat as completely uninstalled if the manifest is gone.
return { repos: [], env: { marker_paths: [] }, min_size_bytes: 1024 }
}
}
// Persistent user overrides live in the ENVIRONMENT file the Pinokio launcher
// sources — that is exactly where docs/H3_ENGINE.md tells users to put them.
// The PANEL reads these names from its own process env; this menu runs in a
// different process entirely, so the only way for the two to agree is to parse
// the same file. Read once, used for the model generation AND for the two H3
// roots (see the h3Path note below for what disagreeing costs).
//
// Deliberately narrow: `KEY=value`, no continuations, no expansion. Anything
// this parser cannot read leaves the caller on its default, which is always the
// shipped behaviour.
const ENV_KEYS = ["LTX_MODEL_VERSION", "LTX_H3_ROOT", "LTX_H3_MODELS", "LTX_MUSIC_ROOT", "LTX_MUSIC_MODELS"]
//
// THE SAME GRAMMAR PINOKIO USES. The launcher reads this file with
// dotenv.parse (Pinokio 8.2.0 kernel/util.js parse_env), so the shell, the
// panel and the installers see `LTX_MUSIC_ROOT=/Volumes/Media Drive/YuE` as
// the whole path. This parser took `(\S+)` and silently dropped any value
// with a space — quoted or not — so the sidebar probed the default location
// and offered a fresh install of an engine that was installed, or the wrong
// repair (Codex INST-13, 2026-09-24). DOTENV_LINE is dotenv's own line rule,
// copied rather than required: pinokio.js runs in Pinokio's node, where the
// app's node_modules are not on the resolution path. Last assignment wins,
// as in dotenv.
const DOTENV_LINE = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg
function readEnvironment(installRoot) {
const out = {}
try {
const envPath = path.join(installRoot, "ENVIRONMENT")
if (!fs.existsSync(envPath)) return out
const text = fs.readFileSync(envPath, "utf8").replace(/\r\n?/g, "\n")
let m
DOTENV_LINE.lastIndex = 0
while ((m = DOTENV_LINE.exec(text)) !== null) {
if (!ENV_KEYS.includes(m[1])) continue
const value = (m[2] || "").trim().replace(/^(['"`])([\s\S]*)\1$/, "$2")
// Pinokio drops an empty value rather than setting it (skill §1), so
// an empty one leaves the caller on its default here too.
if (value) out[m[1]] = value
else delete out[m[1]]
}
} catch (e) { /* unreadable ENVIRONMENT: every caller keeps its default */ }
return out
}
function repoComplete(installRoot, repo, minBytes) {
// A repo is "complete" iff every listed file exists under its local_dir at
// its declared exact size (file_sizes) or else >= minBytes, and every loader
// sidecar (small upscaler configs) exists and is not empty. Mirrors the
// Python-side pack_file_ok in mlx_ltx_panel.py (fleet #206).
const sizes = repo.file_sizes || {}
const sidecars = repo.sidecars || []
for (const fname of (repo.files || []).concat(sidecars)) {
try {
const abs = path.join(installRoot, repo.local_dir, fname)
const st = fs.statSync(abs)
if (!st.isFile()) return false
const want = sizes[fname]
if (typeof want === "number" && want > 0) {
if (st.size !== want) return false
} else if (sidecars.includes(fname)) {
if (st.size <= 0) return false
} else if (st.size < minBytes) {
return false
}
} catch (e) {
return false
}
}
return true
}
module.exports = {
version: "7.0",
// PUBLIC IDENTITY. From v4.8.2 to v4.15.2 this said "Phosphene BETA" and
// "[BETA — unreleased builds, runs alongside the stable install on port
// 8199]": the private beta checkout's local edit got committed and rode
// every promote since. Pinokio 8.2.0 overlays pinokio.json's title and
// description on top of these (kernel/api meta(), Object.assign order), so
// the sidebar read "Phosphene" — but the text shipped to every user, indexed
// by Pinokio's app search and shown by any build without that overlay. The
// beta install names itself in its own local pinokio.json (skip-worktree);
// nothing beta-only belongs in this file.
title: "Phosphene",
// The Pinokio store listing. It still said "via LTX 2.3 (MLX)" three weeks after 2.5
// became the generation a fresh install renders with — the first sentence a prospective
// user reads, naming the wrong engine, while a confused existing user hunting a "why
// does it keep asking for LTX 2.3" answer finds it confirming their suspicion.
description: "[MAC ONLY] Local generative video panel for Apple Silicon. Joint audio+video via LTX-2.5 (MLX), with Hailuo H3 as a second engine. T2V, I2V, FFLF, Extend, trained characters. Lossless h264. Hardware-tier feature gating. Free, open source.",
icon: "icon.png",
menu: async (kernel, info) => {
// Resolve the install root. cocktailpeanut diagnosed that `info.path` is
// a function on his Pinokio (call as info.path("file") → absolute path
// inside install dir). On older Pinokio versions it's a string property.
// getInstallRoot() handles both shapes and falls back to __dirname when
// info is unusable. See the helper above for the full history.
const installRoot = getInstallRoot(info)
const required = loadRequired(installRoot)
const minBytes = required.min_size_bytes || 1024
// Every ENVIRONMENT override this menu honours, read once. See readEnvironment().
const envFile = readEnvironment(installRoot)
// --- env detection: either Pinokio's `env/` or manual `.venv/` ---
const env_ready = (required.env.marker_paths || []).some(p => info.exists(p))
// --- per-repo completeness from the unified manifest ---
const repos = required.repos || []
// Use the active generation for the optional high-quality model offer.
const caps = required.capabilities || {}
const capRender = caps.render || {}
// THE ACTIVE GENERATION, where it is knowable. A user pinned back with
// LTX_MODEL_VERSION=ltx23 renders on 2.3's packs, and evaluating the
// manifest's default here told them their install was incomplete for a
// generation they are not using. The panel resolves this from its own
// process env; Pinokio's menu runs elsewhere, so it reads the same override
// from the ENVIRONMENT file the launcher sources — which is exactly where
// docs/H3_ENGINE.md tells users to put persistent overrides. Falls back to
// the manifest default when nothing has been pinned, which is the norm.
let activeVersion = capRender.default_version
const pinnedVersion = envFile.LTX_MODEL_VERSION
if (pinnedVersion && (capRender.repos_by_version || {})[pinnedVersion]) {
activeVersion = pinnedVersion
}
// THE PACK THE BUTTON ACTUALLY INSTALLS. This read `key === "q8"` —
// LTX-2.3's pack — while the menu entry it gates dispatches
// download_q8.js -> q8_weights.sh -> `--repo-key q8_25`, i.e. LTX-2.5's.
// The gate and the action were about different packs, so after a
// successful 30 GB install the menu kept offering the download forever.
// Resolved by mirror-block presence rather than a hardcoded key so a third
// generation does not reopen it: the 2.5-era packs are the mirrored ones.
// THE Q8 PACK OF THE ACTIVE GENERATION. This preferred q8_25 unconditionally,
// so a user pinned back with LTX_MODEL_VERSION=ltx23 whose 2.3 Q8 pack was
// already complete still saw "Download Q8 weights (~30 GB)" forever — an
// offer to fetch 30 GB their generation does not load. `characters` is the
// capability that names it, and it is declared per version.
const capChars = caps.characters || {}
const q8Keys = ((capChars.repos_by_version || {})[activeVersion]
|| (capChars.repos_by_version || {})[capChars.default_version] || [])
const q8Repo = q8Keys.map(k => repos.find(r => r.key === k)).filter(Boolean)[0]
|| repos.find(r => r.key === "q8_25") || repos.find(r => r.key === "q8")
const q8Size = q8Repo && q8Repo.size_gb
? `~${Math.round(q8Repo.size_gb)} GB` : "unknown size"
const q8Name = q8Repo && q8Repo.name ? q8Repo.name : "Q8 weights"
const q8_ready = q8Repo ? repoComplete(installRoot, q8Repo, minBytes) : false
const sharp_ready =
info.exists("ltx-2-mlx/env/lib/python3.11/site-packages/pipersr") ||
info.exists("ltx-2-mlx/env/lib/python3.11/site-packages/pipersr-1.0.0.dist-info")
// Qwen-Image-Edit-2509 readiness — the mflux package on PATH is the
// canonical signal that the user opted into multi-reference image
// generation. Weights live lazily in ~/.cache/huggingface (outside
// install dir, so they survive Reset). Probing for the per-family CLI
// covers the case where mflux was upgraded but the new
// `mflux-generate-qwen-edit` binary didn't land (mflux <0.17.5).
const qwen_ready =
info.exists("ltx-2-mlx/env/bin/mflux-generate-qwen-edit")
// Hailuo H3 readiness — the engine's own venv, its runner, and EVERY weight
// component the panel requires.
//
// The old note here said "the one 41 GB file; if that landed, the small
// siblings did too". That assumption is what Medium 6 was: a partial install
// where the DiT arrived and a compact Q8 component did not looked ready from
// this side and refused to run from the panel's, and because the menu thought
// it was fine it hid the Install/Repair entry that would have fixed it. The
// components are declared once in required_files.json and checked here, so
// the assumption is gone rather than reworded.
//
// Weights live under mlx_models/ so they survive Reset like every other
// model, and both download layouts are accepted (capabilities.h3.model_roots
// mirrors _h3_model_roots() in the panel).
//
// Probed with Node's own fs, NOT info.exists() — deliberately, and this is
// the whole fix. `uv venv` builds the venv interpreter as a symlink chain
// into Pinokio's SHARED managed Python:
// .venv/bin/python3.11 -> python
// .venv/bin/python -> <pinokio>/cache/XDG_DATA_HOME/uv/python/
// cpython-3.11-macos-aarch64-none/bin/python3.11
// That target belongs to Pinokio, not to us: any other pack install (or
// any other Pinokio app) that makes uv re-resolve, bump or prune the
// managed interpreter leaves the chain DANGLING. Nothing is deleted — the
// venv, the clone and all ~75 GB of weights stay put — but H3 stops
// resolving. That is the v3.4.0 "installed other packs and Hailuo H3
// vanished" report.
//
// required_files.json already documents info.exists() as unreliable on
// exactly this chain, so it cannot answer the question we need answered
// here — "does this interpreter still resolve?" — in either direction.
// fs.existsSync FOLLOWS symlinks, so a dangling chain is definitively
// false, which makes the menu agree with the panel's _h3_python() by
// construction. (repoComplete() above already probes with fs.statSync +
// absolute paths for the same reason.) Keep the two in sync.
const onDisk = (rel) => {
try { return fs.existsSync(path.join(installRoot, rel)) } catch (e) { return false }
}
// ...AND AT THE ROOT THE PANEL ACTUALLY USES. required_files.json states the
// H3 paths relative to the install dir, but the panel's H3_ROOT / H3_MODELS
// are env-overridable (mlx_ltx_panel.py — `LTX_H3_ROOT`, `LTX_H3_MODELS`,
// documented in docs/H3_ENGINE.md as THE way to point a second install at an
// existing 75 GB checkout instead of duplicating it). This menu joined every
// manifest path onto installRoot unconditionally, so on exactly that setup
// the panel reported H3 installed and the menu reported it missing — and
// offered a 75 GB download for weights already on disk, next to a "Repair"
// for an engine that was never broken. Two consumers, one manifest, and now
// one set of roots. The two prefixes below are the panel's own defaults;
// they are what the override REPLACES, so they have to be named somewhere.
const H3_ROOT_REL = "minimax-h3-mlx"
const H3_MODELS_REL = "mlx_models/hailuo-h3"
// A relative override is relative to the install dir (same as the default it
// replaces); an absolute one passes straight through. path.join collapses a
// trailing "" cleanly, so an exact prefix match resolves to the root itself.
const underRoot = (base, rel) =>
path.isAbsolute(base) ? path.join(base, rel) : path.join(installRoot, base, rel)
const h3Path = (rel) => {
const norm = String(rel).replace(/\\/g, "/")
for (const [prefix, override] of [[H3_ROOT_REL, envFile.LTX_H3_ROOT],
[H3_MODELS_REL, envFile.LTX_H3_MODELS]]) {
if (!override) continue
if (norm === prefix) return underRoot(override, "")
if (norm.startsWith(prefix + "/")) return underRoot(override, norm.slice(prefix.length + 1))
}
return path.join(installRoot, norm)
}
const h3Resolves = (rel) => {
try { return fs.existsSync(h3Path(rel)) } catch (e) { return false }
}
// DECLARED, NOT RE-DERIVED. This used to call H3 ready on venv + runner +
// the one big DiT, while the panel additionally required every compact Q8
// component and the upstream text config — so a partial install hid the
// Install/Repair entry here while the panel refused to run H3, and the user
// had no route to the fix. Both sides now read the same component list from
// required_files.json → capabilities.h3.
const capH3 = ((required.capabilities || {}).h3) || {}
const h3_venv = (capH3.venv_any || []).some(h3Resolves)
const h3_runner = (capH3.paths || []).every(h3Resolves)
// The weights are the expensive thing (~75 GB) and they live under
// mlx_models/, a completely different tree from the clone — so they
// routinely survive whatever broke the engine. `model_roots` are
// ALTERNATIVES (either download layout is valid); every entry in `models`
// is required beneath whichever root carried the DiT.
// PER FILE, not per root. This required every component beneath ONE root,
// while the panel resolves each file against any of them — and the panel is
// right: LTX_H3_MODELS and LTX_H3_COMPACT_DIR legitimately split a layout
// across roots, which is the documented dev setup. On a split layout the
// panel said installed and this said not, so Pinokio offered a 75 GB
// install for weights already on disk. Two consumers, one manifest, and now
// one resolution rule.
const h3_weights = (capH3.models || []).every(rel =>
(capH3.model_roots || []).some(root => h3Resolves(root + "/" + rel)))
const h3_ready = h3_venv && h3_runner && h3_weights
// Weights on disk but the code/venv gone → a REPAIR, not a 75 GB install.
// install_h3.js is idempotent and skips every intact weight, so the same
// script serves both; only the label changes, because telling a user to
// "install ~75 GB" when they already have the 75 GB is the thing that
// made this look like data loss.
const h3_repair = h3_weights && !h3_ready
// The compact Q8 engine, built locally at the end of install_h3.js. A 36-59
// GB Mac cannot render H3 without it (the panel's h3_capable()), and once
// the weights are complete `h3_ready` is true — so the only entry left was
// "Update Hailuo H3 runner", while the panel told the user to click an
// "Install Hailuo H3" that was no longer there. Same markers as the panel's
// _h3_q8_dit_dir(): config + quant recipe + EVERY shard the index names
// (non-empty). "At least one shard" let a pack missing four of five read as
// built, hiding the Build entry that repairs it (Codex H3-04). A pack with
// no index predates it and keeps the one-shard rule.
const h3_q8 = (capH3.model_roots || []).some(root => {
try {
const dir = h3Path(root + "/h3-dit-q8")
if (!fs.existsSync(path.join(dir, "config.json"))
|| !fs.existsSync(path.join(dir, "quant_config.json"))) return false
const idx = path.join(dir, "model.safetensors.index.json")
if (!fs.existsSync(idx)) {
return fs.readdirSync(dir).some(n => /^model-.*\.safetensors$/.test(n))
}
const names = [...new Set(Object.values(JSON.parse(fs.readFileSync(idx, "utf8")).weight_map || {}))]
return names.length > 0 && names.every(n => {
try { const st = fs.statSync(path.join(dir, n)); return st.isFile() && st.size > 0 } catch (e) { return false }
})
} catch (e) { return false }
})
let h3_small = false
try { h3_small = os.totalmem() < H3_BF16_BYTES } catch (e) {}
const h3_needs_build = h3_ready && !h3_q8 && h3_small && h3Capable()
// The ONE H3 offer for a machine that cannot render H3 yet, in every menu
// state that has a Start or an Open Panel. It used to exist only in the
// stopped-panel menu, while the panel's install card (the thing a user reads
// WHILE the panel runs) sends them to it: a 48 GB owner on X, 2026-09-24,
// "couldn't even install it from the UI". install_h3.js touches only
// minimax-h3-mlx/ and mlx_models/hailuo-h3/, its Q8 build streams one tensor
// at a time on the CPU, and the panel picks the engine up on its next
// /status tick — safe beside a running panel, like the music install.
const h3Offer = () => {
if (!h3Capable()) return []
if (!h3_ready) {
return [h3_repair
// Quoted verbatim by the panel (H3_REPAIR_MENU_TEXT) -- change both.
? { icon: "fa-solid fa-screwdriver-wrench", text: "Repair Hailuo H3 (weights kept — no re-download)", href: "install_h3.js" }
// ENGINES ARE PEERS: "optional" told a user that half the panel's
// video capability was a side dish. The entry names what it IS.
// The panel's install card quotes this string verbatim -- change both
// (H3_INSTALL_MENU_TEXT in mlx_ltx_panel.py).
: { icon: "fa-solid fa-comments", text: "Install Hailuo H3 (second video engine, ~75 GB)", href: "install_h3.js" }]
}
if (h3_needs_build) {
// Quoted verbatim by the panel (H3_BUILD_MENU_TEXT) -- change both.
return [{ icon: "fa-solid fa-screwdriver-wrench", text: "Build Hailuo H3 compact engine (weights kept — no re-download)", href: "install_h3.js" }]
}
return []
}
const musicRoot = underRoot(envFile.LTX_MUSIC_ROOT || "yue2-mlx", "")
const musicModels = underRoot(envFile.LTX_MUSIC_MODELS || "mlx_models/yue2", "")
const musicFile = p => { try { return fs.statSync(p).isFile() } catch (e) { return false } }
let musicWeights = false
try {
const generator = path.join(musicModels, "generator")
const files = JSON.parse(fs.readFileSync(path.join(generator, "conversion.json"), "utf8")).files
const generatorNames = ["LICENSE", "THIRD_PARTY_NOTICES.md", "ar-8bit.safetensors", "ar-bf16.safetensors",
"config.json", "licenses/SnakeBeta-NVIDIA-MIT.txt", "licenses/stable-audio-tools-MIT.txt",
"nar-bf16.safetensors", "qwen.tiktoken"]
const allowed = new Set([...Object.keys(files), "conversion.json", "README.md"])
const clean = (dir, prefix = "") => fs.readdirSync(dir, { withFileTypes: true }).every(e => {
const rel = prefix + e.name
if (e.isSymbolicLink()) return false
if (e.isDirectory()) return [...allowed].some(n => n.startsWith(rel + "/")) && clean(path.join(dir, e.name), rel + "/")
return allowed.has(rel)
})
const vae = path.join(musicModels, "vae")
const vfiles = JSON.parse(fs.readFileSync(path.join(vae, "weights_manifest.json"), "utf8")).files
const intact = (base, entries) => Object.entries(entries).every(([n, r]) => {
if (n.includes("..") || path.isAbsolute(n)) return false
const st = fs.lstatSync(path.join(base, n))
return st.isFile() && st.size > 0 && st.size === r.bytes && /^[0-9a-f]{64}$/.test(r.sha256)
})
musicWeights = Object.keys(files).length === generatorNames.length && generatorNames.every(n => files[n])
&& clean(generator) && intact(generator, files)
&& vfiles["model.safetensors"].bytes === 530512720
&& vfiles["model.safetensors"].sha256 === "807ce9d5149fa27c5ad3e6582058469852e908f6c5acc8c8aa338e7ab7751346"
&& intact(vae, vfiles)
&& ["config.json", "LICENSE", "THIRD_PARTY_NOTICES.md"].every(n => musicFile(path.join(vae, n)))
&& fs.readdirSync(path.join(vae, "licenses")).length > 0
} catch (e) { /* partial pack: keep the install route available */ }
const musicReady = musicWeights && ["python", "python3.12"].some(n => {
const p = path.join(musicRoot, ".venv/bin", n)
try { fs.accessSync(p, fs.constants.X_OK); return musicFile(p) } catch (e) { return false }
})
&& musicFile(path.join(musicRoot, "pyproject.toml"))
&& musicFile(path.join(installRoot, "scripts/music/yue2_run.py"))
const musicRepair = musicWeights && !musicReady
const musicMenu = () => !musicCapable() ? [] : [musicReady || musicRepair
? { icon: "fa-solid fa-screwdriver-wrench", text: "Repair the music engine (weights kept — no re-download)", href: "install_music.js" }
: { icon: "fa-solid fa-music", text: "Install the music engine (YuE2, ~11 GB)", href: "install_music.js" }]
// Keep the H3 recovery affordance reachable from EVERY menu state, not
// only the healthy one. Reset wipes ltx-2-mlx, so env_ready goes false and
// the menu early-returns (below) long before it reaches the H3 row — which
// is exactly why the v3.4.0 reporter ran Reset and still found "no H3
// anywhere". The pack is independent of the LTX install (own clone, own
// venv, weights in a different tree), so offering the repair mid-reinstall
// is safe and never competes with the default action.
const pushH3Recovery = (m) => {
if (musicRepair && musicCapable()) {
m.push({ icon: "fa-solid fa-screwdriver-wrench", text: "Repair the music engine (weights kept — no re-download)", href: "install_music.js" })
}
if (h3_repair && h3Capable()) {
m.push({ icon: "fa-solid fa-screwdriver-wrench",
text: "Repair Hailuo H3 (weights kept — no re-download)",
href: "install_h3.js" })
}
return m
}
// --- LTX engine health: the SAME dangling-interpreter class, one tree over -
// `env_ready` above trusts a marker path — ltx-2-mlx/env/pyvenv.cfg, a plain
// FILE that survives everything. The interpreter beside it does not: install
// .js builds it with `uv venv`, which makes bin/python a symlink chain into
// Pinokio's SHARED managed Python, and any other pack (or any other Pinokio
// app) that makes uv re-resolve, bump or prune that interpreter leaves the
// chain DANGLING. That is precisely the v3.4.0 report the H3 probes above
// exist for — LTX is simply the tree nobody re-checked afterwards.
//
// In that state the menu showed a confident `default: true` Start, Python
// never came up, and the only entries offered were Update (which pip-installs
// into the venv that isn't there) and Reset (which deletes the install). No
// route to the fix, for a machine whose venv is the ONLY broken thing.
// fs.existsSync FOLLOWS symlinks, so a dangling chain is definitively false.
//
// install.js IS the repair: its ltx_venv.sh step probes the interpreter,
// rebuilds only when it does not run, and every download step after it skips
// what is already on disk. Nothing is re-fetched — hence "models kept".
const ltx_python = onDisk("ltx-2-mlx/env/bin/python3.11") ||
onDisk("ltx-2-mlx/env/bin/python")
// ...and the OTHER half-built shape, which used to look perfectly healthy
// here (fleet, 2026-09-20): the interpreter is present but the engine
// package never landed in it, so every render dies at helper start with
// "ModuleNotFoundError: No module named 'ltx_pipelines_mlx'". Three
// installs on 4.13.0 / 4.14.3 / 4.15.0 hit it, one of them 28 times in a
// row — with no repair offered, because the file this menu looked at was
// exactly the file that existed. The package directory is the honest
// marker: pip writes it last.
const ltx_pkg = onDisk("ltx-2-mlx/env/lib/python3.11/site-packages/ltx_pipelines_mlx")
const ltx_repair = env_ready && (!ltx_python || !ltx_pkg)
// WHILE THE PANEL RUNS, the repair cannot be offered directly: install.js
// reinstalls into the venv the running panel (and its image engine) holds
// open. But the panel's render error names this sidebar entry, and both
// running menus used to hide it — the user was sent to a button that did
// not exist exactly when they needed it (Codex INST-05, 2026-09-24). So the
// running menu says what to do instead, and opens the terminal whose Stop
// button is the first half of it.
const ltxRepairWhileRunning = () => ltx_repair ? [{
icon: "fa-solid fa-screwdriver-wrench",
text: "Engine needs repair — Stop the panel, then click Repair Phosphene engine (models kept)",
href: "start.js" }] : []
const pushLtxRepair = (m) => {
if (ltx_repair) {
m.push({ icon: "fa-solid fa-screwdriver-wrench",
text: "Repair Phosphene engine (models kept)",
href: "install.js" })
}
return m
}
// User-content folders persist across Reset (which only removes the venv).
// Keep their shortcuts visible whenever they exist on disk so users can
// still recover their renders / models / uploads.
const has_outputs = info.exists("mlx_outputs")
const has_models = info.exists("mlx_models")
const has_uploads = info.exists("panel_uploads")
// --- has an install already been ATTEMPTED here? ------------------------
// THE INFINITE-RESTART FIX (@natxou field report, v3.5.0).
//
// Two Pinokio rules combine badly. From PINOKIO.md:
// "Dynamic menu rendering" — the sidebar menu is re-rendered every time
// a step in the currently running script finishes.
// "Auto-executing menu items" — when a menu item marked `default: true`
// has a script as its href, selecting it also STARTS that script.
//
// So a `default: true` -> install.js entry is only safe while install.js
// is still capable of succeeding. The moment install.js aborts — a dropped
// connection during the ltx-2-mlx clone, a HuggingFace 5xx mid-download, a
// full disk — the menu re-renders, still sees an incomplete install, hands
// Pinokio the very same auto-run entry, and Pinokio starts install.js
// again. Which aborts again. Forever.
//
// The user-visible symptom is NOT a crash loop in the panel: it is the
// Pinokio console scrolling
// Starting Shell <uuid> ... Terminated Shell <uuid>
// with a DIFFERENT uuid every time (Pinokio gives each command in a
// `message` array its own shell, so one install pass alone emits a dozen),
// the app parked at ~90 MB on disk, and Python never starting — because
// nothing in this state ever reaches start.js. Present in every public
// release from v2.0.0 through v3.5.0; it just needed a failing install to
// become visible.
//
// fs.link is install.js's FIRST side-effecting step — it runs before the
// clone, before the venv, before every download — so these folders exist
// after even an attempt that died immediately. Their presence is a
// reliable "install.js has already run at least once" marker. Probed with
// fs.existsSync as well as info.exists because fs.link creates them as
// symlinks into Pinokio's drive, and a dangling link must still count as
// an attempt (see the H3 note above for the same lesson).
//
// Net effect: a clean machine still auto-installs on first open (nothing
// exists yet, so nothing to detect). Every state AFTER a failed attempt
// waits for a deliberate click instead of respawning itself.
// (`onDisk` is defined next to the H3 probes above — same fs.existsSync
// reasoning, one definition.)
const install_attempted =
has_models || has_outputs || has_uploads ||
onDisk("mlx_models") || onDisk("mlx_outputs") ||
onDisk("panel_uploads") || onDisk("state") || onDisk("ltx-2-mlx")
const running = {
install: info.running("install.js"),
start: info.running("start.js"),
update: info.running("update.js"),
reset: info.running("reset.js"),
q8download: info.running("download_q8.js"),
sharp: info.running("install_sharp.js"),
qwen: info.running("install_qwen.js"),
h3: info.running("install_h3.js"),
music: info.running("install_music.js"),
}
// Running states first — show what's in progress, hide everything else.
if (running.install) return [{ default: true, icon: "fa-solid fa-plug", text: "Installing", href: "install.js" }]
if (running.update) return [{ default: true, icon: "fa-solid fa-rotate", text: "Updating", href: "update.js" }]
if (running.reset) return [{ default: true, icon: "fa-solid fa-eraser", text: "Resetting", href: "reset.js" }]
if (running.q8download) return [{ default: true, icon: "fa-solid fa-download", text: `Downloading ${q8Name} (${q8Size})`, href: "download_q8.js" }]
if (running.sharp) return [{ default: true, icon: "fa-solid fa-wand-magic-sparkles", text: "Installing Sharp upscaler", href: "install_sharp.js" }]
if (running.qwen) return [{ default: true, icon: "fa-solid fa-images", text: "Installing Qwen-Image-Edit (multi-ref)", href: "install_qwen.js" }]
if (running.music) return [{ default: true, icon: "fa-solid fa-music", text: "Installing the music engine (~11 GB)", href: "install_music.js" }]
if (running.h3) return [{ default: true, icon: "fa-solid fa-comments", text: "Installing Hailuo H3 (~75 GB)", href: "install_h3.js" }]
// No env at all → fresh install path. Recovery shortcuts to user content
// folders if a previous install left files behind.
if (!env_ready) {
// `default: true` — and therefore Pinokio's auto-run — ONLY on a machine
// that has never attempted an install. Anywhere else this is the entry
// that restarts a failing install.js forever (see install_attempted).
const m = [install_attempted
? { icon: "fa-solid fa-rotate-right",
text: "Resume Install (last attempt didn't finish — click to retry)",
href: "install.js" }
: { default: true, icon: "fa-solid fa-plug", text: "Install", href: "install.js" }]
if (has_outputs) m.push({ icon: "fa-solid fa-film", text: "Outputs", href: "mlx_outputs?fs=true" })
if (has_models) m.push({ icon: "fa-solid fa-cube", text: "Models", href: "mlx_models?fs=true" })
if (has_uploads) m.push({ icon: "fa-solid fa-image", text: "Uploads", href: "panel_uploads?fs=true" })
pushH3Recovery(m)
// Escape hatch. This branch used to offer no Reset at all, so a user
// whose install died before the venv existed had nothing to click except
// the thing that kept failing.
if (install_attempted) m.push({ icon: "fa-regular fa-circle-xmark", text: "Reset engine (keeps models & outputs)", href: "reset.js" })
return m
}
// Models are optional until a feature is used. A runtime can always open.
if (running.start) {
const local = info.local("start.js")
if (local && local.url) {
return [
{ default: true, icon: "fa-solid fa-rocket", text: "Open Panel", href: local.url },
...ltxRepairWhileRunning(),
{ icon: "fa-solid fa-terminal", text: "Terminal", href: "start.js" },
{ icon: "fa-solid fa-film", text: "Outputs", href: "mlx_outputs?fs=true" },
{ icon: "fa-solid fa-cube", text: "Models", href: "mlx_models?fs=true" },
{ icon: "fa-solid fa-image", text: "Uploads", href: "panel_uploads?fs=true" },
// Settings → Models tells a running panel's user to click this, so it
// has to exist while the panel runs. The install touches only
// yue2-mlx/ and mlx_models/yue2/; the panel picks it up on /status.
...musicMenu(),
// Same reasoning for H3: the panel's install card points here.
...h3Offer(),
]
}
return [{ default: true, icon: "fa-solid fa-terminal", text: "Terminal", href: "start.js" }, ...ltxRepairWhileRunning(), ...musicMenu(), ...h3Offer()]
}
// Healthy install — Start path.
//
// UNLESS THE ENGINE IS BROKEN. `default: true` auto-runs Start, which boots
// a panel that cannot render and — see ltxRepairWhileRunning — used to hide
// the repair the moment it came up (INST-05). So a broken engine gets no
// auto-run at all: Repair goes FIRST, without `default` (auto-running
// install.js after a failed attempt is the respawn loop documented at
// install_attempted), and Start stays available below it for anyone who
// wants the panel anyway.
const baseMenu = []
if (ltx_repair) pushLtxRepair(baseMenu)
baseMenu.push(
{ default: !ltx_repair, icon: "fa-solid fa-power-off", text: "Start", href: "start.js" },
{ icon: "fa-solid fa-film", text: "Outputs", href: "mlx_outputs?fs=true" },
{ icon: "fa-solid fa-cube", text: "Models", href: "mlx_models?fs=true" },
{ icon: "fa-solid fa-image", text: "Uploads", href: "panel_uploads?fs=true" },
)
if (!q8_ready && q8Capable()) {
// ~30 GB and what it actually buys on 2.5: trained characters and voices.
// High additionally needs the separate 29.5 GB add-on, which is offered
// in Settings -> Models rather than here — one menu entry, one download.
// Size and wording follow the pack that will actually be fetched.
baseMenu.push({ icon: "fa-solid fa-download",
text: `Download ${q8Name} (${q8Size}) — trained characters + voices`,
href: "download_q8.js" })
}
if (!sharp_ready) {
baseMenu.push({ icon: "fa-solid fa-wand-magic-sparkles", text: "Install Sharp upscaler (PiperSR, optional)", href: "install_sharp.js" })
}
if (!qwen_ready) {
// mflux image-engine pack now ships in install.js/update.js; this entry
// is a recovery action shown only when the pack isn't present (e.g. a
// failed pip step, or a pre-3.2.1 install that hasn't updated). Renamed
// off "Qwen-Image-Edit" — it enables Ideogram 4 too (cocktailpeanut's
// confusion: installing "Qwen" to use Ideogram).
// SYS-30: "Reinstall" implies it was here before and broke — on a
// fresh install that never fetched this pack, that's simply untrue.
// qwen_ready collapses both cases (never installed vs. broken) to
// the same boolean, so the honest word covers both without
// guessing which one this install is.
baseMenu.push({ icon: "fa-solid fa-images", text: "Install/repair image engines (Ideogram 4 + Qwen-Edit)", href: "install_qwen.js" })
}
baseMenu.push(...musicMenu())
// Second VIDEO engine — joint picture + dialogue + sound. Opt-in only:
// ~75 GB, 36 GB+ Macs (H3_MIN_BYTES above), MiniMax Community License
// with territory restrictions. Hidden entirely on machines that can't
// run it, so it never reads as a missing piece of the base install.
const h3Entry = h3Offer()
if (h3Entry.length) {
baseMenu.push(...h3Entry)
} else if (h3_ready) {
// THE DOOR MUST NOT CLOSE BEHIND THE INSTALL. The panel's live-preview
// note tells users with an older H3 runner to update it "from the
// Phosphene sidebar" — but this entry used to exist only while H3 was
// NOT installed, so the exact people the note addressed had no button
// to press (reported by a user on X, 2026-08-18, whose sidebar showed
// only the sharp/Q8 offers). install_h3.js is idempotent: runner
// refresh, weights untouched.
baseMenu.push({ icon: "fa-solid fa-rotate", text: "Update Hailuo H3 runner (weights kept — no re-download)", href: "install_h3.js" })
}
baseMenu.push(
{ icon: "fa-solid fa-rotate", text: "Update", href: "update.js" },
{ icon: "fa-regular fa-circle-xmark", text: "Reset engine (keeps models & outputs)", href: "reset.js" },
)
return baseMenu
}
}