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
release(v3.8.1): the Update that could not be retried
mrbizarrobe108ad0abff
diff --git a/README.md b/README.mdindex b77a04b..6a40d06 100644--- a/README.md+++ b/README.md@@ -32,7 +32,7 @@ Key differences from the standard A2V path:</p>-> **Current release: v3.8.0.** Storyboard — describe a film in a sentence, get a shot list you can edit before anything renders. Also fixes the install failure that had been breaking every fresh install and every Update since hatchling 1.32.0 shipped. Full notes on the [releases page](https://github.com/mrbizarro/phosphene/releases).+> **Current release: v3.8.1.** Hotfix: Update and Install could abort at the video-engine pin with `error: Your local changes to the following files would be overwritten by checkout: … video_vae.py`, and retrying never cleared it. Both paths now discard local edits in the app-managed vendored checkout before moving the pin, then re-apply the codec patch. v3.8.0 brought Storyboard — describe a film in a sentence, get a shot list you can edit before anything renders — plus the fix for the install failure that had been breaking every fresh install and every Update since hatchling 1.32.0 shipped. Full notes on the [releases page](https://github.com/mrbizarro/phosphene/releases).## Overviewdiff --git a/VERSION b/VERSIONindex 1981190..f280719 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-3.8.0+3.8.1diff --git a/docs/STATE.md b/docs/STATE.mdindex eaa22a3..06e571b 100644--- a/docs/STATE.md+++ b/docs/STATE.md@@ -1,6 +1,6 @@# Phosphene — project state, history, open work-**Public release: `v3.8.0`** (see the v3.8.0 CHANGELOG entry below; the narrative in this paragraph stops at v3.1.1 and is kept as history). The entire v3.0 line shipped — v3.0.0 (Characters / Voice / Image Studio / A2V, May 23) → v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a 2-month silent regression) → v3.0.3 (HiDream hidden, #15) → v3.0.4 (CivitAI SSL) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6 (deep-review hardening) → v3.0.7 (GPU-race fix + /status version surfacing) → **v3.0.8 (ltx-2-mlx v0.14.8 catch-up — codec-only patches, I2V "mosaic"/Metal-watchdog fix #17, ASCII version-skew handshake fix)** → **v3.0.9 (custom I2V Width×height inputs restored for power users; Train-tab dev-transformer Download "unknown install key" fix — form-encoding, reported by @cocktailpeanut)** → **v3.0.10 (model-integrity self-heal — boot scan + `/status.model_integrity` + a one-click Repair banner for corrupt/partial weights, the leading *non-Metal* "mosaic" garbage-decode cause; safetensors header+size check)** → **v3.0.11 (latent helper-handshake hang fixed: `_read_until` mixed `select()` on the raw fd with a buffered `readline()`, so any event the helper emitted *right before* `ready` — a version-skew line, the new runtime fingerprint — got stranded in the TextIOWrapper buffer and the panel hung 120 s → "helper failed to start: None". This is the true root cause behind the mislabeled "⚠️-emoji" handshake break. Now reads the raw fd via `os.read()` into a carry buffer and drains every complete line before re-`select()`-ing. PLUS: every render log self-documents its runtime — mlx/mlx-metal version + Apple chip + macOS — surfaced in `/status`, the `helper ready ·` line, and a standalone `runtime |` line, the exact data needed to triangulate the remaining MLX-numerical "mosaic")** → **v3.0.12 (the REAL mosaic fix + 3 more. The mosaic is NOT a code bug or the missing-upscaler theory (both disproved by local repro — the bare 6-file Q4 set renders byte-identical-clean on M4 Max); it's stale/corrupt weight *content* — right size, wrong bytes — that v3.0.10's header+size check can't see (confirmed: ronyeoh/#18 + claude3d/#5 fixed it only by a fresh full re-download). Added **deep checksum verify vs upstream**: Settings → Model files → "Verify model files (checksum)" / `/models/verify-deep` hashes every weight + compares to HuggingFace's published SHA-256 (proven to match local), mismatches feed the existing one-click Repair re-download. Validated: flipped 16 bytes mid-file → header+size passed, deep-verify caught it. ALSO in v3.0.12: character-LoRA-shows-as-"style-only" fix (#5 — `list_user_loras` recovers trigger+kind from the `_v2` filename when the sidecar is missing); `cgi`→`email` multipart migration (Python-3.13-ready, removes the boot DeprecationWarning, adopted from @ssfeather's PR #22); dynamic 3–8 multi-keyframe UI (adopted from @youngbee12's PR #20, ported clean with the integrity feature preserved + a JS ReferenceError fixed). Folds in v3.0.11's handshake fix + runtime fingerprint.)** → **v3.0.13 (character LoRA fixes, #5 @claude3d: a multi-word/spaced character filename no longer mislabels as style-only — the id regex gated out spaces before the sidecar was read; and the Character tab no longer silently falls back to plain T2V — a UI desync left the avatar's selection ring lit after `character_id` was cleared. Plus an `enhancePrompt` element-id fix. Cherry-picked to prod `ce03139`, release `814dc2d`.)** → **v3.1.0 (Ideogram 4 — open-weight 9.3B text-rendering image model + a visual text-placement canvas that places exact text via normalized-bbox captions. mflux 0.18 `mflux-generate-ideogram4`; gated `ideogram-ai/ideogram-4-fp8` ~26 GB, needs a HF Read token + license. Fixed the gated-download 401 that would have hit EVERY user — the panel now exports its configured token to subprocess env via `_sync_hf_token_to_env` so a stale `hf auth login` cache can't shadow it; proven clean-room. Validated end-to-end: 8-text-element field-guide poster rendered clean, every label placed per its bbox.)** → **v3.1.1 (Ideogram output-card buttons hotfix, reported by Mr Bizarro: an Ideogram image's prompt is a caption JSON, which broke every output surface that fed it into a plain box / inline onclick — the Recent-list Animate button was worked-but-dead because apostrophes/&/< in the caption terminated the single-quoted onclick. Display-layer fix: `_displayPromptFor` derives `high_level_description`, `escapeHtml` the onclick args, friendly `_imgEngineLabel`, and `loadParams` restores an Ideogram image into the visual canvas instead of dumping JSON. `params.prompt` stays the caption JSON; renders unaffected. Validated live.)** All validated end-to-end on the dev panel (deep-verify corrupt-detect + repair, /loras, byte-identical upload, multi-keyframe render, FFLF regression). See §4 for the full version history. The May-17 Codex C+ UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) and the Train-tab / LoRA-chrome work that followed are all baseline now, folded into v3.0.x. There is no `v2.0.6` tag.+**Public release: `v3.8.1`** (see the v3.8.1 + v3.8.0 CHANGELOG entries below; the narrative in this paragraph stops at v3.1.1 and is kept as history). The entire v3.0 line shipped — v3.0.0 (Characters / Voice / Image Studio / A2V, May 23) → v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a 2-month silent regression) → v3.0.3 (HiDream hidden, #15) → v3.0.4 (CivitAI SSL) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6 (deep-review hardening) → v3.0.7 (GPU-race fix + /status version surfacing) → **v3.0.8 (ltx-2-mlx v0.14.8 catch-up — codec-only patches, I2V "mosaic"/Metal-watchdog fix #17, ASCII version-skew handshake fix)** → **v3.0.9 (custom I2V Width×height inputs restored for power users; Train-tab dev-transformer Download "unknown install key" fix — form-encoding, reported by @cocktailpeanut)** → **v3.0.10 (model-integrity self-heal — boot scan + `/status.model_integrity` + a one-click Repair banner for corrupt/partial weights, the leading *non-Metal* "mosaic" garbage-decode cause; safetensors header+size check)** → **v3.0.11 (latent helper-handshake hang fixed: `_read_until` mixed `select()` on the raw fd with a buffered `readline()`, so any event the helper emitted *right before* `ready` — a version-skew line, the new runtime fingerprint — got stranded in the TextIOWrapper buffer and the panel hung 120 s → "helper failed to start: None". This is the true root cause behind the mislabeled "⚠️-emoji" handshake break. Now reads the raw fd via `os.read()` into a carry buffer and drains every complete line before re-`select()`-ing. PLUS: every render log self-documents its runtime — mlx/mlx-metal version + Apple chip + macOS — surfaced in `/status`, the `helper ready ·` line, and a standalone `runtime |` line, the exact data needed to triangulate the remaining MLX-numerical "mosaic")** → **v3.0.12 (the REAL mosaic fix + 3 more. The mosaic is NOT a code bug or the missing-upscaler theory (both disproved by local repro — the bare 6-file Q4 set renders byte-identical-clean on M4 Max); it's stale/corrupt weight *content* — right size, wrong bytes — that v3.0.10's header+size check can't see (confirmed: ronyeoh/#18 + claude3d/#5 fixed it only by a fresh full re-download). Added **deep checksum verify vs upstream**: Settings → Model files → "Verify model files (checksum)" / `/models/verify-deep` hashes every weight + compares to HuggingFace's published SHA-256 (proven to match local), mismatches feed the existing one-click Repair re-download. Validated: flipped 16 bytes mid-file → header+size passed, deep-verify caught it. ALSO in v3.0.12: character-LoRA-shows-as-"style-only" fix (#5 — `list_user_loras` recovers trigger+kind from the `_v2` filename when the sidecar is missing); `cgi`→`email` multipart migration (Python-3.13-ready, removes the boot DeprecationWarning, adopted from @ssfeather's PR #22); dynamic 3–8 multi-keyframe UI (adopted from @youngbee12's PR #20, ported clean with the integrity feature preserved + a JS ReferenceError fixed). Folds in v3.0.11's handshake fix + runtime fingerprint.)** → **v3.0.13 (character LoRA fixes, #5 @claude3d: a multi-word/spaced character filename no longer mislabels as style-only — the id regex gated out spaces before the sidecar was read; and the Character tab no longer silently falls back to plain T2V — a UI desync left the avatar's selection ring lit after `character_id` was cleared. Plus an `enhancePrompt` element-id fix. Cherry-picked to prod `ce03139`, release `814dc2d`.)** → **v3.1.0 (Ideogram 4 — open-weight 9.3B text-rendering image model + a visual text-placement canvas that places exact text via normalized-bbox captions. mflux 0.18 `mflux-generate-ideogram4`; gated `ideogram-ai/ideogram-4-fp8` ~26 GB, needs a HF Read token + license. Fixed the gated-download 401 that would have hit EVERY user — the panel now exports its configured token to subprocess env via `_sync_hf_token_to_env` so a stale `hf auth login` cache can't shadow it; proven clean-room. Validated end-to-end: 8-text-element field-guide poster rendered clean, every label placed per its bbox.)** → **v3.1.1 (Ideogram output-card buttons hotfix, reported by Mr Bizarro: an Ideogram image's prompt is a caption JSON, which broke every output surface that fed it into a plain box / inline onclick — the Recent-list Animate button was worked-but-dead because apostrophes/&/< in the caption terminated the single-quoted onclick. Display-layer fix: `_displayPromptFor` derives `high_level_description`, `escapeHtml` the onclick args, friendly `_imgEngineLabel`, and `loadParams` restores an Ideogram image into the visual canvas instead of dumping JSON. `params.prompt` stays the caption JSON; renders unaffected. Validated live.)** All validated end-to-end on the dev panel (deep-verify corrupt-detect + repair, /loras, byte-identical upload, multi-keyframe render, FFLF regression). See §4 for the full version history. The May-17 Codex C+ UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) and the Train-tab / LoRA-chrome work that followed are all baseline now, folded into v3.0.x. There is no `v2.0.6` tag.> **🌍 2026-08-12 — THE GEOIP KILL (analytics schema-v2 Phase 1): every event now tells PostHog not to locate it.** The panel has never sent a location field. It didn't have to: PostHog derives country, city, subdivision, timezone and the city's coordinates from the connecting IP by **default**, and the previous posture — in `_analytics_post`'s own docstring — was *"we neither add to nor suppress that."* Now suppressed, on every event, via `_ANALYTICS_RECEIVER_DIRECTIVES` spread **last** into the properties block so no call site can override it.>@@ -742,6 +742,35 @@ Reconciled against the deep review (2026-05-31). Everything that was a recent fi> handoff, not a user changelog. v3.8.0 is written up here as well because a release that> changes the install path deserves a line somebody can find with grep.+#### v3.8.1 — the Update that could not be retried+- **Update / Install aborted at the video-engine pin, permanently.** Both paths move the+ vendored `ltx-2-mlx` checkout with `git checkout <sha>`, and for an affected install that+ line failed with `error: Your local changes to the following files would be overwritten by+ checkout: packages/ltx-core-mlx/src/ltx_core_mlx/model/video_vae/video_vae.py`. Nothing in+ the flow ever un-dirtied the file, so every retry died on the same line — including "click+ Install again", the recovery we tell people to use.+- **Where the dirty file came from — every install, not a rare cohort.** `ltx-2-mlx` is a uv+ *workspace*, and `install.js` installs its members with deps and without `--reinstall`, so uv+ links them **editable**: site-packages gets `_editable_impl_ltx_core_mlx.pth`, not a copy.+ `patch_ltx_codec.py` resolves its target through `VENV_ROOTS` — site-packages first,+ `packages/ltx-core-mlx/src` as a fallback — finds no `ltx_core_mlx` directory in+ site-packages, and patches the **git-tracked source**. A perfectly successful install+ therefore ends with a modified tracked file, every time. (An install that *died* at the+ package step lands in the same place for a different reason: nothing in site-packages at+ all.) The `v0.14.8 → 871694d` pin move rewrites the very ffmpeg lines that patch edits, so+ git refused to move the pin.+- **The fix.** Both `install.js` and `update.js` discard local edits in the vendored checkout+ (`git reset --hard HEAD`, behind a guard that the shell really landed in that tree) before+ moving the pin. The checkout is app-managed: models live in `../mlx_models`, the build+ constraints in `../pip-build-constraints.txt`, and the only non-tracked thing inside it on a+ real install is the ignored `env/` venv — which `reset --hard` does not touch. Update's own+ `uv pip install --reinstall --no-deps` step then replaces the editable `.pth` links with real+ copies in site-packages, and the codec patch re-applies **there** — so the runtime imports a+ patched `video_vae.py` and the vendored tree is left clean for the next pin move. General,+ not SHA-specific: any modified tracked file that differs across a pin move is now cleared.+- **No model re-download, no weight change, no pin change.** The vendored pin is still+ `871694d` / `0.14.19+ltx25.1`.+#### v3.8.0 — Storyboard, and the install that had been failing for everyone new- **Storyboard tab** — a concept sentence is planned into a shot list by`storyboard_planner.py` (running on the `gemma-3-12b-it-4bit` weights the panel alreadydiff --git a/install.js b/install.jsindex b8e5429..3747ced 100644--- a/install.js+++ b/install.js@@ -173,6 +173,18 @@ module.exports = {"git fetch --tags origin","git remote get-url fork > /dev/null 2>&1 || git remote add fork https://github.com/mrbizarro/ltx-2-mlx.git","git fetch fork feat/ltx-2.5",+ // 3.8.1 HOTFIX — the same guard as update.js, and it matters here+ // too. ltx-2-mlx is a uv workspace, so the package step below links+ // its members EDITABLE; patch_ltx_codec.py (further down this file)+ // therefore lands on the git-tracked source instead of+ // site-packages, and every successful install leaves this tree with+ // a modified video_vae.py. "Click Install again" — the recovery we+ // tell people to take — then aborts right here with "Your local+ // changes ... would be overwritten by checkout", and no retry can+ // clear it. The tree is app-managed: nothing user-owned lives in it,+ // and reset --hard leaves the ignored env/ venv alone. See update.js+ // for the full rationale.+ "if [ -f packages/ltx-core-mlx/pyproject.toml ]; then echo 'vendored tree is app-managed; discarding local edits before the pin move:'; git status --porcelain | head -20; git reset --hard HEAD; else echo 'WARN: not the vendored ltx-2-mlx tree - skipping reset'; fi","git checkout 871694ddaa09c1598d663a49005a2f91ae6b4ed2","git rev-parse --short HEAD"]diff --git a/update.js b/update.jsindex 643454c..5d1caf8 100644--- a/update.js+++ b/update.js@@ -86,6 +86,46 @@ module.exports = {"git fetch --tags origin","git remote get-url fork > /dev/null 2>&1 || git remote add fork https://github.com/mrbizarro/ltx-2-mlx.git","git fetch fork feat/ltx-2.5",+ // 3.8.1 HOTFIX — DISCARD LOCAL EDITS BEFORE THE PIN MOVE.+ //+ // This checkout is the most fragile line in the updater, and on+ // 3.8.0 it failed for real users with+ // error: Your local changes to the following files would be+ // overwritten by checkout:+ // packages/ltx-core-mlx/src/ltx_core_mlx/model/video_vae/video_vae.py+ // No retry could clear it — nothing in the flow ever un-dirties the+ // file, so the Update button was dead for good.+ //+ // WHY EVERY INSTALL IS DIRTY. ltx-2-mlx is a uv WORKSPACE, and+ // install.js installs its members WITH deps and WITHOUT --reinstall,+ // so uv links them EDITABLE: site-packages gets+ // `_editable_impl_ltx_core_mlx.pth`, not a copy. patch_ltx_codec.py+ // then resolves through VENV_ROOTS, finds no ltx_core_mlx directory+ // in site-packages, and falls through to `packages/ltx-core-mlx/src`+ // — the GIT-TRACKED source. So a perfectly successful install ends+ // with a modified tracked file, every single time. (An install that+ // DIED at the package step lands in the same place for a different+ // reason: nothing in site-packages at all.) The v0.14.8 -> 871694d+ // diff rewrites the very ffmpeg lines that patch edits, so git+ // refuses to move the pin. Same class, not the same SHA: ANY+ // modified tracked file that differs across a pin move blocks it.+ //+ // WHY reset --hard AND NOT `git checkout -- <file>`. This tree is+ // APP-MANAGED end to end: models live in ../mlx_models, the build+ // constraints in ../pip-build-constraints.txt, and on a real install+ // the only non-tracked thing inside it is the ignored env/ venv —+ // which reset --hard does not touch, so the multi-GB venv survives.+ // A surgical per-file revert would only fix today's filename.+ //+ // SAFE BECAUSE OF WHAT FOLLOWS. The uv step below reinstalls the+ // three packages with --reinstall --no-deps, which REPLACES the+ // editable .pth links with real copies in site-packages; the codec+ // patch further down then re-applies there, so the runtime imports a+ // patched video_vae.py and this tree stays clean for the NEXT pin+ // move. Proven end to end, from a real v0.14.8 editable install.+ // The guard stops reset --hard ever firing in a shell that did not+ // land in the vendored tree.+ "if [ -f packages/ltx-core-mlx/pyproject.toml ]; then echo 'vendored tree is app-managed; discarding local edits before the pin move:'; git status --porcelain | head -20; git reset --hard HEAD; else echo 'WARN: not the vendored ltx-2-mlx tree - skipping reset'; fi","git checkout 871694ddaa09c1598d663a49005a2f91ae6b4ed2","git rev-parse --short HEAD"]