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(v4.0.7): your reference image is honoured on every tier — and "Inspire" becomes a mode
mrbizarro7884ca47bcd4
diff --git a/CLAUDE.md b/CLAUDE.mdindex fcdda05..9f79757 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -197,7 +197,7 @@ These are not arbitrary — every pin is a paid lesson:| `mlx==0.31.1` | mlx 0.31.2 introduced a numerical regression that attenuates LTX 2.3 vocoder output by ~22 dB. Verified: same model + same prompt + same seed → -42 dB peak on 0.31.2 vs -9 dB peak on 0.31.1. || `mlx-lm==0.31.1` `mlx-metal==0.31.1` | Same release line, kept consistent with mlx. || `huggingface-hub>=1.0` | `hf` CLI replaced `huggingface-cli`; older Pinokio bundles ship < 1.0. |-| `ltx-2-mlx` PINNED to the FORK TAG **`v0.14.19+ltx25.4`** (`mrbizarro/ltx-2-mlx`, commit `ee256f5` on `release/ltx25.4` = v0.14.19 `1192051` + the LTX-2.5 port + the schedule/sampler/live-preview work + the i2v anchor re-pin) | **The pin is a TAG and it lives in `scripts/pinokio/ltx_checkout.sh`**, which is the ONE checkout implementation both lanes call (install.js dispatches it; scripts/post_update.sh calls it). It was a bare SHA through v3.8.3 and was reachable only by luck — a force-push would have stranded every install with an un-fetchable pin and a dead Update button. `check_ltx_pin.js` is the gate. The packages report **`0.14.19+ltx25.4`**; `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py must equal that string or every render logs VERSION SKEW — move the two together. This pin is what lets **LTX-2.5 render through the panel**, and on **dev/beta** 2.5 is the registry DEFAULT (2.3 stays installed, selectable via `LTX_MODEL_VERSION=ltx23`). **v3.8.x did NOT register `ltx25` at all** and shipped 2.3 as the only generation, because the 2.5 weight packs were not publicly downloadable when it was cut — a fresh install would have booted into a generation it could not fetch. They are published now, and **v4.0.0 closes that divergence**: 2.5 is the registered default everywhere. If you ever need to curate a release back to a single generation, it is one `MODEL_VERSIONS` dict plus its three `required_files.json` rows (watch the `kind: "base"` trap: any base row is mandatory for an install to read complete, in the panel *and* in `pinokio.js`). The **pin diverged for the same reason**: v3.8.x shipped `871694d` / `0.14.19+ltx25.1`, one commit behind, because `e6be9d6` (the 2.5 sampler + stage-2 schedule, below) had no 2.3 regression evidence behind it at cut time. It does now — a 2.3 sha256-identity pair across the change — so the next release should choose the pin deliberately rather than inherit either. The base tag v0.14.19 landed 2026-08-11 (a catch-up from v0.14.8, itself a 2026-06-01 catch-up from v0.14.0). **STAY PINNED** — this is NOT "main HEAD", and not upstream's tip either. The v0.14.8 bump had pulled dgrauet's native `_pre_denoise_flush` (the Metal-watchdog fix for the I2V "mosaic" on memory-pressured Macs, #17), budget-aware VAE decode tiling and first-class `frame_rate`, which cut us from 7 runtime patches to 1 (codec-only). The v0.14.19 bump keeps that shape and adds: checkpoint-read `av_ca_timestep_scale_multiplier` (0.14.11 — **audio/dialogue weighting changes on every render**, toward upstream parity, plus `LTXModelConfig.from_checkpoint_dir()`), `frame_rate` forwarded at the A2V/lipdub call sites and no more shortest-stream mux truncation (0.14.15), quantized transformers at any `group_size` (0.14.16), and GPU-watchdog explanation + DiT-freed-before-VAE-decode + a Gemma cache-limit fix (0.14.19). **The `+ltx25.2` bump (2026-08-12) is the first one that changes what a 2.5 render computes**, and only a 2.5 render: (a) the **euler-ancestral sampler is finally REACHED** — it had been implemented with 48 tests and zero callers, so every prior 2.5 render silently used the 2.3 Euler step, against upstream's own `ANCESTRAL_SAMPLER_SINCE_VERSION = (2, 5)` and all three official ComfyUI 2.5 templates; keyframe/flf2v deliberately stays on Euler because the flf2v template pins eta to 0. (b) **stage 2's first sigma is now the vendor's 0.85**, read from `video_ltx2_5_t2v.json` node 395, where we had been using 2.3's 0.909375 — a refine pass starting at the wrong noise level. Both are version-keyed off the checkpoint's own `model_version`, and 2.3 output is proven **sha256-identical** before and after. **No model re-download**: 0.14.13+ prefers a versioned `transformer-distilled-*.safetensors` and falls back to the unversioned name, and update.js trims the `-1.1` variants, so file resolution is identical to v0.14.8. Bumping the pin further is a deliberate, tested operation — read the release notes, bump `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py, smoke-test the matrix on dev, then bump BOTH install.js and update.js in one commit. **The `+ltx25.4` bump (2026-08-14, v4.0.2) is the i2v anchor.** The conditioning item was always built correctly — `frame_idx=0`, `strength=1.0`, `mask_value=0`, a hard latent replace — and both loops forced those tokens back into the model's **x0 estimate** every step. Under Euler that was sufficient by arithmetic accident: velocity `(x - x0)/sigma` is exactly 0 at a pinned token, so the step returns it unchanged. The **euler-ancestral** step 2.5 selects has no such property: it rescales every token by `alpha_next/alpha_down` and adds fresh Gaussian noise, unmasked. Measured on the real 2.5 schedule the anchor is **halved and buried under noise 0.86x its own scale after step 1**, so every forward from step 2 on saw garbage where the image should be and the composition was decided without it; the terminal step stamped the image back in, which is why the delivered frame 0 always matched while the clip was a different shot. The fix re-composites the **sample** against `clean_latent`/`denoise_mask` after the ancestral step at all three sites, guarded by the existing uniform-mask flags — the other half of what ComfyUI's 2.5 i2v graph does. Proven, not argued: **t2v at a fixed seed is sha256-identical** before and after (`fbf09533583c423ab9ad3c0a437aee3484f15c0c5cceb2b1fc4ecc6d59071abb`), and frame-vs-input normalised cross-correlation at seed 424242 moves **0.0934 -> 0.7878** (frame 36) and **0.0902 -> 0.7187** (frame 72) while frame 0 holds at ~0.975. Every Euler lane — 2.3 i2v, keyframe/flf2v with its deliberate `eta=0`, a2v, extend, restore, ic_lora, lipdub — never reaches the branch. `res2s_denoise_loop`'s `_sde_step` has the **same defect class** and is deliberately NOT fixed: it is on the 2.3 path too, so a fix there would not be byte-identical on 2.3. The historic `dcd639e (0.1.0)` detour broke the Extend `cfg_scale` API; do not revisit. |+| `ltx-2-mlx` PINNED to the FORK TAG **`v0.14.19+ltx25.5`** (`mrbizarro/ltx-2-mlx`, commit `b2a9d9e` on `release/ltx25.5` = v0.14.19 `1192051` + the LTX-2.5 port + the schedule/sampler/live-preview work + the i2v anchor re-pin on BOTH loops) | **The pin is a TAG and it lives in `scripts/pinokio/ltx_checkout.sh`**, which is the ONE checkout implementation both lanes call (install.js dispatches it; scripts/post_update.sh calls it). It was a bare SHA through v3.8.3 and was reachable only by luck — a force-push would have stranded every install with an un-fetchable pin and a dead Update button. `check_ltx_pin.js` is the gate. The packages report **`0.14.19+ltx25.4`**; `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py must equal that string or every render logs VERSION SKEW — move the two together. This pin is what lets **LTX-2.5 render through the panel**, and on **dev/beta** 2.5 is the registry DEFAULT (2.3 stays installed, selectable via `LTX_MODEL_VERSION=ltx23`). **v3.8.x did NOT register `ltx25` at all** and shipped 2.3 as the only generation, because the 2.5 weight packs were not publicly downloadable when it was cut — a fresh install would have booted into a generation it could not fetch. They are published now, and **v4.0.0 closes that divergence**: 2.5 is the registered default everywhere. If you ever need to curate a release back to a single generation, it is one `MODEL_VERSIONS` dict plus its three `required_files.json` rows (watch the `kind: "base"` trap: any base row is mandatory for an install to read complete, in the panel *and* in `pinokio.js`). The **pin diverged for the same reason**: v3.8.x shipped `871694d` / `0.14.19+ltx25.1`, one commit behind, because `e6be9d6` (the 2.5 sampler + stage-2 schedule, below) had no 2.3 regression evidence behind it at cut time. It does now — a 2.3 sha256-identity pair across the change — so the next release should choose the pin deliberately rather than inherit either. The base tag v0.14.19 landed 2026-08-11 (a catch-up from v0.14.8, itself a 2026-06-01 catch-up from v0.14.0). **STAY PINNED** — this is NOT "main HEAD", and not upstream's tip either. The v0.14.8 bump had pulled dgrauet's native `_pre_denoise_flush` (the Metal-watchdog fix for the I2V "mosaic" on memory-pressured Macs, #17), budget-aware VAE decode tiling and first-class `frame_rate`, which cut us from 7 runtime patches to 1 (codec-only). The v0.14.19 bump keeps that shape and adds: checkpoint-read `av_ca_timestep_scale_multiplier` (0.14.11 — **audio/dialogue weighting changes on every render**, toward upstream parity, plus `LTXModelConfig.from_checkpoint_dir()`), `frame_rate` forwarded at the A2V/lipdub call sites and no more shortest-stream mux truncation (0.14.15), quantized transformers at any `group_size` (0.14.16), and GPU-watchdog explanation + DiT-freed-before-VAE-decode + a Gemma cache-limit fix (0.14.19). **The `+ltx25.2` bump (2026-08-12) is the first one that changes what a 2.5 render computes**, and only a 2.5 render: (a) the **euler-ancestral sampler is finally REACHED** — it had been implemented with 48 tests and zero callers, so every prior 2.5 render silently used the 2.3 Euler step, against upstream's own `ANCESTRAL_SAMPLER_SINCE_VERSION = (2, 5)` and all three official ComfyUI 2.5 templates; keyframe/flf2v deliberately stays on Euler because the flf2v template pins eta to 0. (b) **stage 2's first sigma is now the vendor's 0.85**, read from `video_ltx2_5_t2v.json` node 395, where we had been using 2.3's 0.909375 — a refine pass starting at the wrong noise level. Both are version-keyed off the checkpoint's own `model_version`, and 2.3 output is proven **sha256-identical** before and after. **No model re-download**: 0.14.13+ prefers a versioned `transformer-distilled-*.safetensors` and falls back to the unversioned name, and update.js trims the `-1.1` variants, so file resolution is identical to v0.14.8. Bumping the pin further is a deliberate, tested operation — read the release notes, bump `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py, smoke-test the matrix on dev, then bump BOTH install.js and update.js in one commit. **The `+ltx25.4` bump (2026-08-14, v4.0.2) is the i2v anchor.** The conditioning item was always built correctly — `frame_idx=0`, `strength=1.0`, `mask_value=0`, a hard latent replace — and both loops forced those tokens back into the model's **x0 estimate** every step. Under Euler that was sufficient by arithmetic accident: velocity `(x - x0)/sigma` is exactly 0 at a pinned token, so the step returns it unchanged. The **euler-ancestral** step 2.5 selects has no such property: it rescales every token by `alpha_next/alpha_down` and adds fresh Gaussian noise, unmasked. Measured on the real 2.5 schedule the anchor is **halved and buried under noise 0.86x its own scale after step 1**, so every forward from step 2 on saw garbage where the image should be and the composition was decided without it; the terminal step stamped the image back in, which is why the delivered frame 0 always matched while the clip was a different shot. The fix re-composites the **sample** against `clean_latent`/`denoise_mask` after the ancestral step at all three sites, guarded by the existing uniform-mask flags — the other half of what ComfyUI's 2.5 i2v graph does. Proven, not argued: **t2v at a fixed seed is sha256-identical** before and after (`fbf09533583c423ab9ad3c0a437aee3484f15c0c5cceb2b1fc4ecc6d59071abb`), and frame-vs-input normalised cross-correlation at seed 424242 moves **0.0934 -> 0.7878** (frame 36) and **0.0902 -> 0.7187** (frame 72) while frame 0 holds at ~0.975. Every Euler lane — 2.3 i2v, keyframe/flf2v with its deliberate `eta=0`, a2v, extend, restore, ic_lora, lipdub — never reaches the branch. **The `+ltx25.5` bump (2026-08-15, v4.0.7) closes that on res_2s too**, which is the lane 2.5's HQ tiers run: the owner reported a reference image producing a high-quality clip of something else on High / High-720p. `res2s_denoise_loop` takes `repin_masked_sample` (default False = the old bytes) and `ti2vid_two_stages_hq` resolves it **per generation**, so 2.5 anchors i2v for real while 2.3 is byte-identical BY CONSTRUCTION — the reason this was deferred in +ltx25.4 is answered by construction rather than by measurement. `denoise_loop` takes the same flag defaulting True, so passing False deliberately restores the drift: that is **Inspire**, shipped as an explicit i2v mode (`loose_reference` through `generate_two_stage`/`generate_and_save` on both pipelines, forwarded only when true). `tests/test_repin_masked_sample.py` pins all four directions. The historic `dcd639e (0.1.0)` detour broke the Extend `cfg_scale` API; do not revisit. || `hatchling<1.32` (build-time only, `pip-build-constraints.txt`) | Not a runtime dep — the **wheel build backend** for the three vendored `ltx-*` packages. All three declare `readme = "../../README.md"`, which hatchling 1.32.0 turned into a hard error, so both installer paths died at `metadata-generation-failed` on *every* pinned tag from the day 1.32 shipped. **Both are now `uv pip install --build-constraints ../pip-build-constraints.txt`** — install.js always was, update.js as of the v3.8.0 port-back. **NOT `PIP_CONSTRAINT=`**: modern pip spawns its build-dependency sub-install with `_PIP_IN_BUILD_IGNORE_CONSTRAINTS=1` and drops the env constraint on purpose, so that spelling silently resolved hatchling 1.32.0 and failed anyway (proven on pip 26.1/26.2.1, relative and absolute paths). pip's `--build-constraint` flag would work but does not exist on older pips, and Update runs on venvs seeded years apart. Remove only when a pinned upstream tag stops pointing `readme` outside the package dir. |When changing a version, document the test that proved the new pin is OK.diff --git a/README.md b/README.mdindex 51970c9..2ce055b 100644--- a/README.md+++ b/README.md@@ -135,8 +135,8 @@ cd phosphenegit clone https://github.com/dgrauet/ltx-2-mlx.git ltx-2-mlxcd ltx-2-mlxgit remote add fork https://github.com/mrbizarro/ltx-2-mlx.git-git fetch fork +refs/tags/v0.14.19+ltx25.4:refs/tags/v0.14.19+ltx25.4-git checkout v0.14.19+ltx25.4+git fetch fork +refs/tags/v0.14.19+ltx25.5:refs/tags/v0.14.19+ltx25.5+git checkout v0.14.19+ltx25.5cd ..# 2. Create the Python 3.11 venv inside ltx-2-mlx (uv-managed).@@ -190,7 +190,7 @@ cd .../ltx-2-mlx/env/bin/python3.11 mlx_ltx_panel.py```-About the version pins: `mlx 0.31.2` attenuates the LTX vocoder by 22 dB. Stay on 0.31.1. `ltx-2-mlx` is pinned to the fork **tag** `v0.14.19+ltx25.4` (`mrbizarro/ltx-2-mlx`, commit `ee256f5`) — v0.14.19 plus the LTX-2.5 port, because upstream has no 2.5 branch. A tag, not a bare SHA: a force-push upstream would strand every install with an un-fetchable pin and a dead Update button. The installed packages report `0.14.19+ltx25.4` and `_LTX_EXPECTED_VERSION` must match that string exactly, or every render logs a VERSION SKEW warning. `scripts/pinokio/ltx_checkout.sh` holds the pin and `node scripts/check_ltx_pin.js` enforces the agreement. `mflux 0.17.5` is the version `patch_mflux_fbcache.py` is line-targeted against. `hatchling<1.32` (in `pip-build-constraints.txt`) is a *build-time* pin: 1.32 rejects the `readme = "../../README.md"` that all three upstream packages declare, which fails the wheel build on every tag.+About the version pins: `mlx 0.31.2` attenuates the LTX vocoder by 22 dB. Stay on 0.31.1. `ltx-2-mlx` is pinned to the fork **tag** `v0.14.19+ltx25.5` (`mrbizarro/ltx-2-mlx`, commit `ee256f5`) — v0.14.19 plus the LTX-2.5 port, because upstream has no 2.5 branch. A tag, not a bare SHA: a force-push upstream would strand every install with an un-fetchable pin and a dead Update button. The installed packages report `0.14.19+ltx25.5` and `_LTX_EXPECTED_VERSION` must match that string exactly, or every render logs a VERSION SKEW warning. `scripts/pinokio/ltx_checkout.sh` holds the pin and `node scripts/check_ltx_pin.js` enforces the agreement. `mflux 0.17.5` is the version `patch_mflux_fbcache.py` is line-targeted against. `hatchling<1.32` (in `pip-build-constraints.txt`) is a *build-time* pin: 1.32 rejects the `readme = "../../README.md"` that all three upstream packages declare, which fails the wheel build on every tag.## Interfacediff --git a/VERSION b/VERSIONindex d13e837..43beb40 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-4.0.6+4.0.7diff --git a/docs/ANALYTICS.md b/docs/ANALYTICS.mdindex 0506342..44e4961 100644--- a/docs/ANALYTICS.md+++ b/docs/ANALYTICS.md@@ -173,18 +173,39 @@ including image and training jobs.|---|---|---|---|| `engine` | string | `"ltx"` | `ltx` or `h3` || `mode` | string | `"i2v"` | `t2v`, `i2v`, `extend`, `keyframe`, `a2v`, `restore`, `ingredients`, `control`, `image`, `train` |-| `tier` | string | `"standard"` | LTX quality (`quick`/`balanced`/`standard`/`high`) or H3 tier (`3s`/`5s`/`10s`/`15s`) |-| `duration_bucket` | string | `"5-15m"` | One of `<2m`, `2-5m`, `5-15m`, `15-40m`, `>40m`, `unknown`. Bucketed, not raw — a precise duration plus a resolution plus a timestamp starts to look like a fingerprint |+| `tier` | string | `"standard"` | LTX quality (`quick`/`balanced`/`standard`/`high`) or the H3 composite cell (`standard_5s`, `high_10s`, …) |+| `duration_bucket` | string | `"5-15m"` | Legacy 5-value bucket, kept one more release for dashboard continuity, then removed in favour of `wall_sec_bucket` |+| `wall_sec_bucket` | int | `480` | The lower edge of a log-spaced ladder (`15, 30, 45, 60, 90, 120, 180, 240, 300, 420, 600, 900, 1200, 1800, 2400, 3600, 5400`). Sharp enough to see a performance regression, far too coarse to be a timing fingerprint. Absent when the wall clock is unknown || `resolution` | string | `"1216x704"` | Output dimensions, or `"unknown"` |+| `canvas_class` | string | `"720p"` | Coarse megapixel class: `<=480p`, `576p`, `720p`, `1080p`, `native+` || `frames` | int | `121` | Frame count |+| `version` | string | `"4.0.6"` | Same value `app_boot` sends. Repeated here so "failure rate by version" is a one-click breakdown instead of a join |+| `chip_family` | string | `"M4 Max"` | Hardware **class**, identical across every machine of that model — same value `app_boot` sends |+| `ram_gb` | int | `64` | Hardware class — same value `app_boot` sends |+| `os_version` | string | `"macOS 15"` | Coarse — same value `app_boot` sends |+| `steps` | int | `8` | Sampler depth the job ran — separates a real regression from a user on 30 steps |+| `accel` | string | `"off"` | `off` / `boost` / `turbo` |+| `temporal_mode` | string | `"native"` | `native` or `fps12_interp24` (Long Clip Boost) |+| `upscale` | string | `"fit_720p"` | `off` / `fit_720p` / `fit_1080p` / `x2` |+| `upscale_method` | string | `"lanczos"` | `lanczos` or `pipersr` |+| `schedule_preset` | string | `"default"` | `default` or `fast` — the LTX-2.5 draft schedule's adoption |+| `chain_windows` | int | `2` | H3 chained-window count (1 = single pass) |+| `chain_prompts_used` | bool | `false` | Did the per-window shot list carry any text |+| `lora_count` | int | `1` | **Count only. Which adapters is deliberately never sent** |+| `lora_kinds` | string | `"style"` | Closed vocabulary: `none` / `style` / `character` / `mixed` |+| `character_used` | bool | `true` | A cast character drove this render |+| `audio_mode` | string | `"joint"` | `joint` / `none` (external audio replaces the generated track) / `a2v_dub` / `h3_native` |+| `first_render` | bool | `true` | Present once per install, on its first successful render ever — the activation funnel without a join |### `render_failed`-Same as `render_completed`, plus one field:+Same as `render_completed` (minus `first_render`), plus:| Field | Type | Example | Notes ||---|---|---|---|-| `error_signature` | string | `"RuntimeError: helper exited before first frame"` | **The only free-text field the panel sends.** See the scrubbing rules below |+| `error_class` | string | `"metal_watchdog"` | **A closed 16-value taxonomy** (`oom_jetsam`, `metal_watchdog`, `native_crash`, `helper_start_timeout`, `helper_exit`, `model_missing`, `model_corrupt`, `download_failed`, `venv_broken`, `bad_params`, `input_missing`, `disk_full`, `export_failed`, `timeout`, `cancelled_race`, `other`). Classification runs on the original error text locally; **only the class leaves the machine** |+| `error_fingerprint` | string | `"a3f09c21e7b4"` | Only when `error_class` is `other`: 12 hex chars of the SHA-256 of the already-scrubbed first line. Lets "the same unknown error, 17 times, all on M1 Max" be counted without transmitting the text — the readable line stays in your own `state/usage-log.jsonl` |+| `error_signature` | string | `"RuntimeError: helper exited before first frame"` | **The only free-text field the panel sends**, see the scrubbing rules below. Kept for ONE transition release alongside `error_class`, then removed |Cancelled jobs are **not** reported — a user cancelling is not a signal aboutthe software.@@ -259,7 +280,7 @@ network is touched, and independently of whether the send then succeeds. OneJSON object per line:```json-{"event":"render_completed","props":{"engine":"ltx","mode":"t2v","tier":"standard","duration_bucket":"2-5m","resolution":"1216x704","frames":121},"install_id":"…","ts":1754400000.0,"at":"2026-08-05 17:40:00","utc":"2026-08-05T14:40:00Z"}+{"event":"render_completed","props":{"engine":"ltx","mode":"t2v","tier":"standard","duration_bucket":"2-5m","wall_sec_bucket":180,"resolution":"1216x704","canvas_class":"720p","frames":121,"version":"4.0.6","chip_family":"M4 Max","ram_gb":64,"os_version":"macOS 15","steps":8,"accel":"off","temporal_mode":"native","upscale":"fit_720p","upscale_method":"lanczos","schedule_preset":"default","chain_windows":1,"chain_prompts_used":false,"lora_count":0,"lora_kinds":"none","character_used":false,"audio_mode":"joint"},"install_id":"…","ts":1754400000.0,"at":"2026-08-05 17:40:00","utc":"2026-08-05T14:40:00Z"}```Two reasons it exists: it's the "this machine" data source for the Usagediff --git a/docs/STATE.md b/docs/STATE.mdindex 1b77582..4d0f766 100644--- a/docs/STATE.md+++ b/docs/STATE.md@@ -1,5 +1,16 @@# Phosphene — project state, history, open work+> **🎯 2026-08-15 — v4.0.7: the reference image is honoured on every tier, "Inspire" becomes a mode, Ingredients stops pretending, and the analytics finally answer per-machine questions.** Four owner reports in one release, plus the schema-v2 render events.+>+> - **THE PIN MOVES: `v0.14.19+ltx25.4` → `v0.14.19+ltx25.5`.** +ltx25.4 fixed the i2v anchor on the euler-ancestral loop and left `res2s_denoise_loop` open as an owner-visible decision — the lane 2.5's HQ tiers actually run. The owner's report is that decision arriving: a reference image on High / High·720p produced a high-quality clip of **something else**. Same mechanism, second loop: res_2s injects SDE noise **unmasked** at both substep and step level, so every forward after step 1 saw noise where the anchor should be and the terminal denoise stamped the image back only into the delivered frame. `res2s_denoise_loop` now takes `repin_masked_sample` (default False = the old bytes) and `ti2vid_two_stages_hq` **resolves it per generation** — so 2.5 anchors i2v for real and **2.3 is byte-identical by construction**, which is precisely the objection that deferred the fix, answered structurally rather than by measurement.+> - **Inspire ships as a MODE, because the accident was worth keeping.** `denoise_loop` takes the same flag defaulting True, so passing False deliberately restores the pre-fix drift: the reference guides subject, style and palette while the shot composes itself. Image mode on 2.5 gets **Anchor / Inspire** pills that say out loud that Inspire will not show your picture as frame one. Lane-gated in `make_job` exactly like `schedule_preset` (2.5 + LTX + i2v only; a stale pill resets quietly), threaded to the engine as `loose_reference` on both the HQ and distilled lanes, and it round-trips through Load Params, the Customize summary and the ⓘ modal from day one. `tests/test_repin_masked_sample.py` (4) pins all four directions, on schedules that deliberately stop before the terminal 0.0 — that final denoise masks x0 on every path and is exactly what made the original defect invisible.+> - **Ingredients refuses the generation it cannot serve.** Its IC-LoRA is 2.3-trained and Lightricks has published **no 2.5 one** (their entire 2.5 IC-LoRA catalogue is a pixel upscaler). On 2.5 the in-context transfer does not graft onto the layers, and because the reference sheet rides at **strength 0.0 by design** (at 1.0 the model copies the sheet verbatim — measured), a dead adapter means the references are simply **absent**: the owner got an unrelated subject at full two-stage cost, ~11 GPU-minutes. One predicate (`ltx_generation_serves_ingredients`) now feeds the worker's refusal, the bootstrap flag and the tests; the chip paints unavailable with the reason and points at Inspire. 2.3 installs are untouched, and the day a 2.5 adapter ships this is one registry row.+> - **H3 can render vertical.** Every H3 canvas shipped landscape, which left social formats unreachable on that engine. Portrait is the **same canvas rotated** — 576×1024 is the same 0.59 MP, the same packed-row count, therefore the same wall clock and peak as the shipped 1024×576 cell — so every tier estimate stays true by construction. Deliberately a per-render flip applied where `make_job` stamps the cell's geometry, **not** a third tier axis: `h3_tier` is the wire format every sidecar carries and a key change would strand replay for every clip ever rendered.+> - **H3's missing live preview now says why.** The panel side is complete (schema `h3-live-preview/1`, adapter, per-job live directory, tests) but **no published H3 runner branch implements `--live-preview`**, so the capability probe is correctly false and the stage stays out — silently, which read as "the theater preview is broken on MiniMax". It is not broken; that half is not built yet. The H3 bootstrap block now carries `reason` + `note` and the Now card speaks it, with no CTA because there is nothing for the user to click.+> - **ANALYTICS SCHEMA V2 — the render events answer the questions the fleet exists for.** `version` / `chip_family` / `ram_gb` / `os_version` lived on `app_boot` only, so "failure rate by chip" or "render time by machine class" needed a per-install join nobody had written and PostHog's UI cannot do in a click. Every render event now carries them, plus **`wall_sec_bucket`** (numeric lower edge of a 17-rung log ladder, so percentiles work natively and an 8:19 → 12:00 regression moves buckets where the old 5-value `duration_bucket` could not see it), `canvas_class`, and a **closed 16-value `error_class`** classified LOCALLY — only the class leaves the machine, with a 12-hex fingerprint of the already-scrubbed line when the class is `other`, so "the same unknown thing, 17 times, all on M1 Max" is countable without transmitting the text. Adoption fields (steps, accel, temporal_mode, upscale(+method), schedule_preset, chain_windows, chain_prompts_used, lora_count — **count only, never which** — lora_kinds, character_used, audio_mode) and a once-ever `first_render` activation flag complete it. `docs/ANALYTICS.md` documents every field in the same commit; suite 43 → 48.+>+> **Gates at the promote tree:** `check_ltx_pin` PASS at `v0.14.19+ltx25.5` · vendored engine suite green · `check_pinokio_scripts` PASS · `check_post_update` PASS · `assert_registry` 169 · `assert_schedules` 45 · `check_output_codec` PASS · `test_repin_masked_sample` 4 · `test_schedule_preset` 8 → 19 (Anchor/Inspire lane gate, Ingredients predicate + bootstrap, H3 orientation) · `test_geometry_grid` 6 · `test_character_roundtrip` 35 · `test_stage_live_preview` 18 · `test_h3_turbo_adapter` 11 · `test_lora_compat` · `test_spicy_contract` · `test_prompt_enhance_endpoint` · analytics 48 · storyboard suites · py_compile · page parse.+> **🔧 2026-08-14 night — v4.0.5 ASSEMBLED on dev/beta (`65880b3` + version `66f0dbd`), HELD for the owner's word.** The two recovered audits' punch-list, closed in one campaign. (1) **H3 Turbo install is LIVE again**: the v1.0 runner-layout repack is a published release asset on `weights-ltx25-v1` (sha256 `d51d626f…`, verified byte-identical against the local repack the selection was graded on); `/h3/turbo/install` streams it partial→verify→atomic-rename, `install_h3.js` fetches the same asset best-effort via `scripts/fetch_h3_turbo.py` (resumable, digest-checked, short Pinokio-safe lines), and the retired **ckpt500-EMA is accepted again as the LAST fallback** — dropping it in 4.0.4 un-Turboed installs that rendered fine on it. Raw v0.1 stays refused by name. Turbo gate 5→11 tests incl. script↔panel pin parity. (2) **The dead HQ Speed control is gone** (skip-step fields were dropped at the engine boundary; both pills ran identical settings under a "~12% faster" claim), and the collapsed summary stops printing "exact speed" from the retired accel input. (3) **The real speed control**: the engine's 2.5-only `fast` schedule preset (F6S2, 5+2 forwards, owner-graded, **a different take**) wired end to end — Speed pills → `schedule_preset` → make_job (lane-gated: dropped with a sentence on 2.3/HQ/H3) → helper → `generate_two_stage`; tier cells carry `fast_eta` (cost-model 5+2/8+2 ratio, so fixed costs aren't discounted), chips re-price while Fast is armed, and Load Params round-trips it from day one (`test_schedule_preset.py`, 8). (4) **Geometry truth**: make_job floors LTX canvases to the two-stage engine's /64 grid and frames to 8k+1 (floored, never raised) and pushes a sentence when it does; dims inputs step by 64; warnings state what WILL render; H3 tier-cell geometry untouched (`test_geometry_grid.py`, 6). (5) **Load Params restores the cast** (owner-reported): the fire-and-forget IIFE is replaced by an awaited restore through `applyCharacterSelection()` — the new non-toggling hydrator — with visible failure when the character left the library; quality chip by the sidecar's own token, explicit `no_voice` with touched provenance, Extend's four fields, STG (absence = Off), and the Length chip repaints after programmatic frame assignment. A hidden checked No-voice can no longer rewrite a plain render (submit gated on a cast; every hide path clears the box). (6) **One health cluster**: the six machine-state pills live in a single bordered container that is the header's only shrinkable region — narrow windows degrade it to colored state dots, then collapse it; the creator avatar is never clipped again. (7) **Stale-process pill**: `/version` compares HEAD-on-disk to HEAD-at-boot each poll; a promote landing under a running panel renders "Restart to finish update" — **validated live**: the dev panel booted at `90b8a6e` reported `stale_process: true` the moment `65880b3` landed. (8) Keyframe sidecars stamp the resolved q8 pack, not the 2.3-defaulting `MODEL_ID_HQ`. **Gates all green at the tree** (pinokio scripts 377/500 worst · ltx pin unmoved at `v0.14.19+ltx25.4` · post_update · registry 169 · schedules 45 · character round-trip 35 · lora_compat · stage_live_preview · spicy · turbo 11 · schedule_preset 8 · geometry 6 · storyboard suites · py_compile · page parse). **Known-remaining / descoped**: the owner's "stray −1 bar" did not reproduce in either live panel's idle state (needs a screenshot the moment it appears); HDR Load-Params restore is moot while the HDR pill ships commented out (roadmap-parked); render validation of the fast preset + Turbo v1.0 timing run deferred until the GPU frees (the eltrumpo retrain holds both locks overnight). **Audit sources**: `~/AI/projects/phosphene/notes/customize_audit_2026-08-14.md` + `journey_audit_2026-08-14.md` (recovered from the sandboxed sessions' stdout; the FIELD REGISTRY campaign spec in the journey audit is the post-4.0.5 systemic fix).**Public release: `v4.0.4`** (2026-08-14 — the live preview leaves the postage stamp and plays full-size on the main stage; the Spicy option follows the Settings switch on both engines; H3's Turbo adapter selection moves to LightX2V v1.0 768p and its automatic install is paused until the repack is published. Carries v4.0.3's picker-LoRA crash fix and the v4.0.2 content: the 720p High tier, i2v that animates the image you gave it, characters on the engine's native runtime-LoRA route, and the vendored pin at `v0.14.19+ltx25.4`; see the entries below. The narrative in this paragraph stops at v3.1.1 and is kept as history). **The 2.3/2.5 divergence that ran through the v3.8.x line was closed by v4.0.0** — LTX-2.5 is the registered default and the vendored port is pinned at the tag `v0.14.19+ltx25.4`. v3.8.x registered 2.3 only and pinned `871694d`, because the 2.5 packs were not publicly downloadable at cut time; they are now. See `CLAUDE.md`'s pin table. 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.diff --git a/install.js b/install.jsindex e89799f..430f46c 100644--- a/install.js+++ b/install.js@@ -180,7 +180,7 @@ module.exports = {// LAUNCHER SCRIPT. Both lanes now call the one implementation in// `scripts/pinokio/ltx_checkout.sh`, which holds the literal://- // v0.14.19+ltx25.4 on mrbizarro/ltx-2-mlx+ // v0.14.19+ltx25.5 on mrbizarro/ltx-2-mlx//// Two reasons, both structural. (1) A SHA on a branch is not a pin:// v3.8.x fetched `feat/ltx-2.5` and checked out a SHA that the branch@@ -193,7 +193,7 @@ module.exports = {// lanes carried byte-identical copies of this block, and a duplicated// fix is a fix that half-lands.//- // 2026-08-14 (v4.0.2) — the pin moves to `v0.14.19+ltx25.4` for one+ // 2026-08-14 (v4.0.2) — the pin moves to `v0.14.19+ltx25.5` for one// change, and it is the reason image-to-video on 2.5 now animates the// image you gave it: the euler-ancestral step rescaled and re-noised// the pinned conditioning tokens on every intermediate step, so the@@ -203,7 +203,7 @@ module.exports = {// not implemented. t2v is sha256-identical across the change and every// Euler lane never reaches the branch.//- // The packages report `0.14.19+ltx25.4`, and `_LTX_EXPECTED_VERSION`+ // The packages report `0.14.19+ltx25.5`, and `_LTX_EXPECTED_VERSION`// in mlx_warm_helper.py must equal that string. The local segment is// the ONLY thing distinguishing this tree from upstream v0.14.19 at// runtime — the release segment is deliberately unchanged. Move thediff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex b5dc3d4..dfd0098 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -8179,6 +8179,18 @@ def ltx_tiers_payload() -> dict:LTX_LENGTHS.values(), key=lambda x: x["order"]) if l["offered"]],"default_quality": LTX_QUALITY_DEFAULT,"default_length": LTX_LENGTH_DEFAULT,+ # The active generation, SERVER-OWNED, so surfaces that differ by+ # generation (the i2v Anchor/Inspire pills, the Ingredients gate)+ # read one authoritative flag instead of parsing a label string.+ "generation": ACTIVE_MODEL_VERSION,+ # Inspire (loose-reference i2v) exists only where the engine's+ # masked-sample re-pin is version-resolved on — 2.5.+ "inspire_available": ACTIVE_MODEL_VERSION == "ltx25",+ # Ingredients runs the 2.3-trained IC-LoRA whose in-context transfer+ # does not graft onto 2.5 layers: refs get ignored at two-stage cost+ # (owner-reproduced 2026-08-15). Offered only where it works; the+ # 2.5 adapter swap is one registry row the day Lightricks ships it.+ "ingredients_available": ltx_generation_serves_ingredients(),# The `?` copy the LTX help-dots fill from, on the same four-hop# Python-owned path H3's chain-prompt help takes. It rides the LTX# bootstrap block rather than a top-level one so everything the LTX@@ -8219,6 +8231,16 @@ def ltx_tiers_payload() -> dict:# to 1080p, no pad filter at all.H3_UPSCALE_MODES = ("off", "fit_720p", "fit_1080p")H3_UPSCALE_DEFAULT = "fit_720p"+# ORIENTATION — H3's canvases are all landscape, which left vertical social+# formats unreachable on this engine (owner-reported 2026-08-15). Portrait is+# the SAME canvas rotated: 576x1024 is the same 0.59 MP, the same packed-row+# count and therefore the same wall clock and peak as the shipped 1024x576+# cell, so every estimate in the tier table stays true by construction. It is+# a per-render FLIP applied where the cell's geometry is stamped, deliberately+# NOT a third tier axis: `h3_tier` is the wire format every sidecar carries+# and a key change would strand replay for every clip ever rendered.+H3_ORIENTATIONS = ("landscape", "portrait")+H3_ORIENTATION_DEFAULT = "landscape"# Modes H3 can serve. Text = prompt only; Image = FL2VA first-frame# conditioning. Everything else (FFLF, Extend, Remix, Character, A2V) is# LTX-pipeline-specific and has no H3 equivalent.@@ -9358,6 +9380,25 @@ def h3_status() -> dict:"schema": "h3-live-preview/1","meaningful_at": 1,"help": LTX_PREVIEW_HELP,+ # WHY it is off, so the stage can say it instead of showing+ # nothing and letting the user conclude the feature is broken —+ # the same rule the LTX lane's `preview_state` follows. The+ # panel side is complete (schema, adapter, per-job live dir,+ # tests); no published H3 runner branch implements+ # `--live-preview`, so the probe is correctly false and the+ # honest sentence is "the runner cannot publish frames yet".+ "reason": (+ None if (available and h3_live_preview_ready())+ else "engine_off" if not available+ else "runner_lacks_flag" if not h3_supports_live_preview()+ else "setting_off" if not live_preview_setting_on()+ else "missing_decoder"),+ "note": (+ "" if (available and h3_live_preview_ready())+ else ("This Hailuo H3 runner cannot publish preview frames "+ "yet — the panel is ready for them, the runner half "+ "is still to come. Renders are unaffected.")+ if (available and not h3_supports_live_preview()) else ""),},# Turbo — the 4-step distill LoRA. A separate block rather than a bare# flag because "off" has three causes the UI must not conflate: H3@@ -10247,6 +10288,149 @@ def _analytics_job_secrets(job: dict) -> list:return out+# ---- Schema v2 render-event vocabulary (spec: analytics_spec_2026-08-11) ---+#+# Every addition below obeys the schema's three rules: coarse classes never+# measurements, closed vocabularies never free text, and no new information+# about the PERSON — only about the render and the hardware class it ran on.+# The point (spec F6): version/chip/ram lived on app_boot only, so "failure+# rate by chip" or "wall time by machine class" needed a per-install join+# nobody had written and PostHog's UI can't do in a click. Stamping the same+# four coarse fields on the render events collapses all of it to one-click+# breakdowns.++# Lower edges of the wall-clock ladder (seconds). Log-spaced at ~1.3-1.5x:+# sharp enough that a 8:19 -> 12:00 regression moves buckets (the old+# 5-value duration_bucket could not see it — spec F7), far too coarse to be+# a timing fingerprint. Numeric so PostHog's percentile aggregation works.+_ANALYTICS_WALL_LADDER = (15, 30, 45, 60, 90, 120, 180, 240, 300, 420,+ 600, 900, 1200, 1800, 2400, 3600, 5400)+++def _analytics_wall_sec_bucket(seconds):+ """The ladder's lower edge for this wall clock, or None when unknown."""+ try:+ s = float(seconds)+ except (TypeError, ValueError):+ return None+ if s <= 0:+ return None+ edge = 0+ for rung in _ANALYTICS_WALL_LADDER:+ if s >= rung:+ edge = rung+ else:+ break+ return int(edge)+++def _analytics_canvas_class(width: int, height: int) -> str:+ """Coarse canvas grouping by megapixels — the percentile dimension."""+ try:+ mp = (int(width) * int(height)) / 1e6+ except (TypeError, ValueError):+ return "unknown"+ if mp <= 0:+ return "unknown"+ if mp <= 0.45:+ return "<=480p"+ if mp <= 0.66:+ return "576p"+ if mp <= 1.1:+ return "720p"+ if mp <= 2.3:+ return "1080p"+ return "native+"+++# Closed error taxonomy (spec 2.7). Classification runs on the ORIGINAL+# error string, locally; only the class leaves the machine. Order is+# load-bearing: the watchdog marker must win over the generic signal names+# (issue #44 must never be merged into native_crash), cancel races must win+# over broad matches, and download failures must win over corrupt-weights+# so a failed fetch's checksum line doesn't count against installed packs.+_ANALYTICS_ERROR_CLASSES = (+ ("metal_watchdog", ("kiogpucommandbuffercallbackerrortimeout",+ "caused gpu timeout error")),+ ("cancelled_race", ("cancel",)),+ ("oom_jetsam", ("sigkill", "helper died mid-job")),+ ("native_crash", ("sigsegv", "sigbus", "sigabrt")),+ ("helper_start_timeout", ("helper failed to start", "handshake")),+ ("helper_exit", ("pipe closed", "broken pipe", "helper exited",+ "exited mid-job")),+ ("download_failed", ("download", "urlopen", "http error", "gated",+ "401", "403", "fetch")),+ ("model_corrupt", ("corrupt", "checksum", "integrity",+ "safetensors header", "hash mismatch")),+ ("model_missing", ("isn't fully installed", "not downloaded",+ "weights are missing", "pack is missing",+ "resume install", "hq add-on", "missing (")),+ ("venv_broken", ("venv", "dangling", "runner missing",+ "no module named")),+ ("disk_full", ("enospc", "no space left")),+ ("input_missing", ("does not exist", "no longer exists")),+ ("export_failed", ("ffmpeg", "pipersr")),+ ("bad_params", ("required", "invalid", "unknown mode",+ "unsupported mode", "must be", "out of range")),+ ("timeout", ("timed out", "timeout")),+)+++def _analytics_error_class(raw) -> str:+ """Map an original error string onto the closed taxonomy."""+ s = str(raw or "").strip().lower()+ if not s:+ return "other"+ for name, needles in _ANALYTICS_ERROR_CLASSES:+ if any(n in s for n in needles):+ return name+ return "other"+++def _analytics_error_fingerprint(scrubbed: str) -> str:+ """12 hex chars of the ALREADY-SCRUBBED first line, sent only when the+ class is `other`. The server learns "the same unknown error, N times,+ on these chips" without the text; the readable line stays in the user's+ own state/usage-log.jsonl for them to paste if they choose."""+ import hashlib as _hashlib+ return _hashlib.sha256(str(scrubbed or "").encode("utf-8",+ "replace")).hexdigest()[:12]+++def _analytics_lora_kinds(params: dict) -> str:+ """Closed-vocabulary adapter summary: none|style|character|mixed.+ COUNT and KIND only — which files is deliberately never sent."""+ loras = params.get("loras") or []+ character = bool(params.get("character_id"))+ if not loras and not character:+ return "none"+ if character and loras:+ return "mixed"+ return "character" if character else "style"+++def _analytics_audio_mode(params: dict, engine: str, mode: str) -> str:+ """Where this render's soundtrack came from, as a closed vocabulary."""+ if engine == "h3":+ return "h3_native"+ if mode == "a2v":+ return "a2v_dub"+ if mode == "i2v_clean_audio":+ return "none"+ return "joint"+++def ltx_generation_serves_ingredients(version_id: str | None = None) -> bool:+ """Can this generation actually run the Ingredients IC-LoRA?++ One predicate, read by the worker's gate, the bootstrap flag the UI+ keys off, and the tests — so "which generations serve Ingredients"+ cannot drift between the three the way `q8_available` once did. The+ day Lightricks publishes a 2.5 adapter this returns True for ltx25 and+ the registry row is the only other change."""+ return (version_id or ACTIVE_MODEL_VERSION) != "ltx25"++def _analytics_render_tier(params: dict, engine: str) -> str:"""The user-facing quality/tier selector for this job, per engine.LTX calls it `quality` (quick/balanced/standard/high); H3 calls it@@ -10281,17 +10465,64 @@ def _analytics_render_event(job: dict) -> None:frames = int(p.get("frames") or 0)except (TypeError, ValueError):frames = 0+ mode = str(p.get("mode") or "unknown")props = {"engine": engine,- "mode": str(p.get("mode") or "unknown"),+ "mode": mode,"tier": _analytics_render_tier(p, engine),"duration_bucket": _analytics_duration_bucket(job.get("elapsed_sec")),"resolution": f"{width}x{height}" if width and height else "unknown","frames": frames,+ # ---- Schema v2 context (spec 2.4). The same coarse machine+ # class app_boot already sends, repeated here so "failure rate+ # by chip" and "wall time by machine class" are one-click+ # PostHog breakdowns instead of an unwritten join. No new+ # information about the person — only the render.+ "version": _read_local_version() or "unknown",+ "chip_family": _analytics_chip_family(),+ "ram_gb": int(round(SYSTEM_RAM_GB)),+ "os_version": _analytics_os_version(),+ "canvas_class": _analytics_canvas_class(width, height),+ # ---- Feature adoption, all closed vocabularies derived from+ # what actually rendered.+ "steps": max(0, int(p.get("steps") or 0)),+ "accel": str(p.get("accel") or "off"),+ "temporal_mode": str(p.get("temporal_mode") or "native"),+ "upscale": str(p.get("upscale") or "off"),+ "upscale_method": str(p.get("upscale_method") or "lanczos"),+ "schedule_preset": str(p.get("schedule_preset") or "") or "default",+ "chain_windows": max(1, int(p.get("h3_chain_windows") or 1)),+ "chain_prompts_used": any(+ str(x).strip() for x in (p.get("h3_chain_prompts") or [])),+ "lora_count": len(p.get("loras") or []),+ "lora_kinds": _analytics_lora_kinds(p),+ "character_used": bool(p.get("character_id")),+ "audio_mode": _analytics_audio_mode(p, engine, mode),}+ # wall_sec_bucket only when the wall clock is known — a None would+ # just pollute the percentile aggregation it exists to feed.+ wall = _analytics_wall_sec_bucket(job.get("elapsed_sec"))+ if wall is not None:+ props["wall_sec_bucket"] = wall+ if status == "done" and not bool(+ get_settings().get("analytics_first_render_reported")):+ # Activation as a one-event funnel (spec D1): the first+ # successful render this install ever produced, once, same+ # persisted-flag shape as analytics_install_reported.+ props["first_render"] = True+ _settings_set_internal(analytics_first_render_reported=True)if status == "failed":- props["error_signature"] = _analytics_scrub_text(+ # The closed class is the leaderboard dimension; the scrubbed+ # free-text signature ships ONE more transition release (spec+ # 2.4) and then goes. `other` carries a 12-hex fingerprint of+ # the scrubbed line so unknown-unknowns can be counted without+ # transmitting their text.+ scrubbed = _analytics_scrub_text(job.get("error"), _analytics_job_secrets(job))+ props["error_class"] = _analytics_error_class(job.get("error"))+ props["error_signature"] = scrubbed+ if props["error_class"] == "other":+ props["error_fingerprint"] = _analytics_error_fingerprint(scrubbed)_analytics_capture("render_completed" if status == "done" else "render_failed", props)except Exception:@@ -14207,9 +14438,15 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,"H3' from the Phosphene sidebar to update the clone; your ""weights stay.")_h3_chain_prompts = []+ # Orientation: flip the resolved cell's canvas for vertical work.+ _h3_orientation = (f("h3_orientation", H3_ORIENTATION_DEFAULT)+ or H3_ORIENTATION_DEFAULT).strip().lower()+ if _h3_orientation not in H3_ORIENTATIONS:+ _h3_orientation = H3_ORIENTATION_DEFAULT# An LTX schedule preset means nothing on the H3 lane; a leftover# value from an engine switch must not ride onto the job._schedule_preset = ""+ _i2v_ref_mode = "anchor"else:# A chained shot list means nothing on the LTX lane, and a fallback to# LTX above must not leave one on the job.@@ -14221,6 +14458,8 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,# stack, so there is no slot to allocate and a leftover "user" here# would only be a confusing field in the sidecar._h3_lora_slot = H3_LORA_SLOT_DEFAULT+ # LTX has its own aspect control; H3's orientation must not ride along.+ _h3_orientation = H3_ORIENTATION_DEFAULT# LTX-2.5 distilled schedule preset ("fast" = the graded F6S2 draft# schedule, 5+2 forwards, renders a DIFFERENT take). Gated server-side# like every H3 rule above: the value rides only when the job will@@ -14245,6 +14484,27 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,"only — High tiers run their own two-stage schedule. The ""default runs.")_schedule_preset = ""+ # i2v reference mode: "anchor" (default — the image is animated) or+ # "inspire" (2.5 only — the image guides subject/style while the+ # composition re-imagines itself; the engine skips the masked-sample+ # re-pin ON PURPOSE). Same lane-gating discipline as the preset+ # above: a value the active lane cannot honor is normalized with a+ # sentence, never queued into a surprise.+ _i2v_ref_mode = (f("i2v_reference_mode", "") or "").strip().lower()+ if _i2v_ref_mode in ("", "anchor"):+ _i2v_ref_mode = "anchor"+ elif _i2v_ref_mode != "inspire":+ push(f"Unknown i2v reference mode {_i2v_ref_mode!r} — anchoring "+ "to the image.")+ _i2v_ref_mode = "anchor"+ elif ACTIVE_MODEL_VERSION != "ltx25":+ push("Inspire is an LTX-2.5 mode — this install renders "+ f"{model_version()['label']}, so the image is anchored.")+ _i2v_ref_mode = "anchor"+ elif f("mode", "t2v") not in ("i2v", "i2v_clean_audio"):+ # Inert without a reference image; a leftover pill from a mode+ # switch resets quietly rather than logging noise on every t2v.+ _i2v_ref_mode = "anchor"if _h3_turbo and _h3_steps:# The adapter is distilled FOR 4 sigma points. Honouring a Steps pill on# top of it would quietly render a configuration nobody validated, so@@ -14298,6 +14558,9 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,# would look wired, post cleanly, and every render would silently# come back on the Turbo branch."h3_lora_slot": _h3_lora_slot,+ # Portrait flips the resolved cell's canvas (same pixel budget,+ # same cost). SAME allowlist trap as every key in this dict.+ "h3_orientation": _h3_orientation,# Per-window prompts for a chained length: one entry per 5 s# window, in render order, "" = "use the main prompt for this# window". Already clamped to the resolved cell's window count@@ -14313,6 +14576,10 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,# it. SAME allowlist trap as every key in this dict: leave it out# and the Speed control looks wired and silently no-ops."schedule_preset": _schedule_preset,+ # i2v reference mode: "anchor" (animate the image) or "inspire"+ # (2.5: guide subject/style, re-imagine the composition). Already+ # lane-gated above. SAME allowlist trap as every key here.+ "i2v_reference_mode": _i2v_ref_mode,"prompt": prompt,"negative_prompt": f("negative_prompt", ""),"width": max(32, int(f("width", str(default_w)) or default_w)),@@ -14474,8 +14741,14 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,"to spend it on your LoRA. Rendering at this shape's own "f"{_h3_steps or H3_TIERS[_h3_tier]['steps']} sigma points.")_tier_cfg = H3_TIERS[_h3_tier]- job["params"]["width"] = _tier_cfg["width"]- job["params"]["height"] = _tier_cfg["height"]+ # Portrait = the cell's own canvas, rotated. Identical pixel count and+ # packed-row count, so the tier's measured estimate stays honest.+ if _h3_orientation == "portrait":+ job["params"]["width"] = _tier_cfg["height"]+ job["params"]["height"] = _tier_cfg["width"]+ else:+ job["params"]["width"] = _tier_cfg["width"]+ job["params"]["height"] = _tier_cfg["height"]# DELIVERED frames — for a chained tier that is the stitched total, not# the per-window count, so the queue card and the duration line read the# clip the user actually gets. run_h3_job_inner splits it back out.@@ -17079,6 +17352,27 @@ def run_job_inner(job: dict) -> None:# (skip_stage_2=True), and the two-field prompt. Default off; no other# mode changes. Recipe matches the public Space# ltx-community/ltx-2.3-ingredients-distilled.+ #+ # GENERATION GATE (2026-08-15, owner-reproduced). The adapter is+ # 2.3-trained and Lightricks has published no 2.5 Ingredients+ # IC-LoRA — their whole 2.5 IC-LoRA catalogue is a pixel upscaler.+ # On 2.5 its in-context transfer does not graft onto the layers: the+ # reference sheet rides at strength 0.0 BY DESIGN (at 1.0 the model+ # copies the sheet verbatim — measured), so when the adapter+ # contributes nothing the refs are simply absent and the render+ # collapses to prompt-only. The owner's report is exactly that: an+ # unrelated subject, produced at two-stage cost. Refuse at the door+ # with the reason instead of burning ~11 GPU-minutes on noise.+ if not ltx_generation_serves_ingredients():+ raise RuntimeError(+ "Ingredients needs the LTX-2.3 generation. Its IC-LoRA is "+ "2.3-trained and Lightricks has not published a 2.5 one, so "+ "on "+ f"{model_version()['label']} the reference sheet is ignored "+ "and you get an unrelated clip at full two-stage cost. For "+ "reference-guided work on 2.5, use Image mode with Inspire "+ "— or install the 2.3 pack from the Train tab for "+ "Ingredients.")try:image_paths = json.loads(p.get("ingredient_images_json") or "[]")if not isinstance(image_paths, list):@@ -17906,6 +18200,11 @@ def run_job_inner(job: dict) -> None:"seed": p["seed"],"image": p["image"] if mode != "t2v" else None,"loras": hq_loras,+ # Inspire on the HQ lane — this is the lane where the owner+ # first hit the loose-reference behavior (High / High·720p),+ # because res_2s re-noises the anchor unmasked. Anchored+ # renders (the default) now hold the image here for real.+ "loose_reference": (p.get("i2v_reference_mode") == "inspire"),# Q8 tuning knobs honor per-job overrides from the form.# Defaults updated 2026-05-12 to match the 5-min sweet# spot recovered from the May-10 clip 11–17 cluster@@ -18039,6 +18338,11 @@ def run_job_inner(job: dict) -> None:# make_job; the helper forwards it to generate_two_stage,# whose resolver validates it before any GPU is spent."schedule_preset": p.get("schedule_preset") or "",+ # Inspire: the engine skips its masked-sample re-pin so the+ # reference guides subject/style while the composition is+ # re-imagined. Lane-gated in make_job; the helper only+ # forwards it when true.+ "loose_reference": (p.get("i2v_reference_mode") == "inspire"),"memory_policy": memory_plan["effective"],"vae_full_decode_max_frames": memory_plan["full_decode_max_frames"],# Sharp/PiperSR is a panel-side post-render pass. Do not pass it@@ -32942,6 +33246,33 @@ HTML = r"""<!doctype html><div class="picker-recent-strip" id="picker_recent_image"></div></div></div>+ <!-- HOW the reference is used. Anchor = the image IS frame one+ and gets animated (what i2v has always promised). Inspire =+ the image guides subject, style and palette while the shot+ re-composes — the behavior High/High·720p produced BY+ ACCIDENT until v4.0.7 anchored them for real, kept as an+ explicit choice because the owner graded the accident as+ worth having. 2.5 only (server-owned flag); the row hides+ itself on 2.3 and on H3. -->+ <div class="cz-control" id="i2vRefModeRow" data-ltx-only hidden+ style="margin-top:10px">+ <div class="cz-label">Reference use+ <span class="cz-label-hint">anchor the image, or take it as inspiration</span>+ </div>+ <input type="hidden" name="i2v_reference_mode" id="i2v_reference_mode" value="anchor">+ <div class="pill-group cols-2" id="i2vRefModeGroup">+ <button type="button" class="pill-btn active" data-i2v-ref="anchor"+ title="Your image is frame one and the clip animates it. This is what Image mode has always promised — and on High tiers it is a v4.0.7 fix.">+ <span>Anchor</span>+ <span class="sub">animate this image</span>+ </button>+ <button type="button" class="pill-btn" data-i2v-ref="inspire"+ title="The image guides subject, style and palette, but the shot composes itself — you will NOT see your picture as frame one. Good for 'this character, new scene'.">+ <span>Inspire</span>+ <span class="sub">new shot from it</span>+ </button>+ </div>+ </div></div><!-- Keyframe interpolation — FFLF or a dynamic 3–8-anchor shot. -->@@ -33749,6 +34080,30 @@ HTML = r"""<!doctype html>control below it, folded away on any other engine bydata-h3-only (rule emitted from the ENGINES table). -->+ <!-- H3 orientation. Every H3 canvas ships landscape, which made+ vertical social formats unreachable on this engine. Portrait+ is the SAME canvas rotated — identical pixel count, identical+ packed rows, so the tier chip's measured estimate stays true+ and no new cell is invented. Applied where make_job stamps the+ cell's geometry; `h3_tier` (the wire format every sidecar+ carries) is untouched. -->+ <div class="cz-control" id="h3OrientationRow" data-h3-only>+ <div class="cz-label">Orientation+ <span class="cz-label-hint">portrait rotates the tier's canvas — same cost</span>+ </div>+ <input type="hidden" name="h3_orientation" id="h3_orientation" value="landscape">+ <div class="pill-group cols-2" id="h3OrientationGroup">+ <button type="button" class="pill-btn active" data-h3-orientation="landscape"+ title="The tier's canvas as trained and measured — e.g. 1024×576.">+ <span>Landscape</span><span class="sub" id="h3OrientLandSub">16:9-ish</span>+ </button>+ <button type="button" class="pill-btn" data-h3-orientation="portrait"+ title="The same canvas rotated for vertical/social — e.g. 576×1024. Same pixel budget, same wall clock.">+ <span>Portrait</span><span class="sub" id="h3OrientPortSub">vertical / social</span>+ </button>+ </div>+ </div>+<!-- H3 export canvas. Most tiers render 12:7 (768×448), which isneither 720p nor 1080p; this runs the SAME lanczos-fit + pad +libx264 pass an LTX render gets, keeping the native file on@@ -41426,6 +41781,12 @@ function updateCustomizeSummary() {if (typeof schedPresetActive === 'function' && schedPresetActive()) {parts.push('fast draft · different take');}+ // Inspire changes what the reference DOES; the folded-away summary owes+ // that sentence as much as it owes the schedule.+ if (typeof i2vInspireActive === 'function' && i2vInspireActive()+ && currentMode === 'i2v') {+ parts.push('inspire · new shot from the image');+ }if ((document.getElementById('temporal_mode')?.value || 'native') === 'fps12_interp24') {parts.push('12→24fps long clip');}@@ -41481,8 +41842,41 @@ document.querySelectorAll('#modeGroup .pill-btn').forEach(b => b.onclick = () =>// setMode keeps the parent Remix pill lit + this sub-pill active + the section// shown. Wired here alongside the #modeGroup handler so both rows behave alike.document.querySelectorAll('#remixSubGroup .pill-btn').forEach(b => b.onclick = () => {+ // Ingredients needs the 2.3 generation: its IC-LoRA is 2.3-trained and no+ // 2.5 one exists, so on 2.5 the references are silently ignored and the+ // clip costs full two-stage time (owner-reproduced 2026-08-15). Say that+ // instead of letting someone spend 11 GPU-minutes finding out. The server+ // refuses too — this is the polite half.+ if (b.dataset.remix === 'ingredients'+ && (BOOT.ltx || {}).ingredients_available === false) {+ if (typeof phosToast === 'function') {+ phosToast('Ingredients needs the LTX-2.3 generation — its reference '+ + 'adapter has no 2.5 release yet, so on 2.5 your references would '+ + 'be ignored. For reference-guided work here, use Image mode with '+ + 'Inspire.', { kind: 'danger' });+ }+ return;+ }setMode(b.dataset.remix);});+// Paint the Ingredients chip as unavailable on a generation that cannot+// serve it, so the state is visible before the click.+(function _markIngredientsAvailability() {+ const apply = () => {+ if ((BOOT.ltx || {}).ingredients_available !== false) return;+ const chip = document.querySelector('#remixSubGroup [data-remix="ingredients"]');+ if (!chip) return;+ chip.classList.add('disabled');+ chip.title = 'Needs LTX-2.3 — the 2.5 reference adapter is not published '+ + 'yet. Use Image mode with Inspire for reference-guided work '+ + 'on 2.5.';+ const sub = chip.querySelector('.mc-sub');+ if (sub) sub.textContent = 'needs LTX-2.3';+ };+ if (document.readyState === 'loading') {+ document.addEventListener('DOMContentLoaded', apply);+ } else { apply(); }+})();document.querySelectorAll('#qualityGroup .pill-btn').forEach(b => b.onclick = () => {// Disabled-but-actionable: the High pill becomes a "click to install Q8"// CTA when Q8 is missing. Routes to the Models modal so the user lands@@ -41740,6 +42134,40 @@ document.querySelectorAll('#h3UpscaleGroup [data-h3-upscale]').forEach(b => {b.onclick = () => setH3Upscale(b.dataset.h3Upscale);});+// H3 orientation — a per-render flip of the resolved cell's canvas, not a new+// tier. The chips' estimates stay valid because a rotation changes no pixel+// count. Persisted like the other H3 sub-preferences.+function setH3Orientation(v) {+ const val = (v === 'portrait') ? 'portrait' : 'landscape';+ const inp = document.getElementById('h3_orientation');+ if (inp) inp.value = val;+ document.querySelectorAll('#h3OrientationGroup [data-h3-orientation]').forEach(b =>+ b.classList.toggle('active', b.dataset.h3Orientation === val));+ try { localStorage.setItem('phos_h3_orientation', val); } catch (e) {}+ _h3SyncOrientationSubs();+ if (typeof updateDerived === 'function') { try { updateDerived(); } catch (e) {} }+}+// Say the ACTUAL canvases the current cell would produce, both ways round.+function _h3SyncOrientationSubs() {+ const cell = (typeof h3CurrentCell === 'function') ? h3CurrentCell() : null;+ const land = document.getElementById('h3OrientLandSub');+ const port = document.getElementById('h3OrientPortSub');+ if (!cell) return;+ if (land) land.textContent = `${cell.width}×${cell.height}`;+ if (port) port.textContent = `${cell.height}×${cell.width} · vertical`;+}+document.querySelectorAll('#h3OrientationGroup [data-h3-orientation]').forEach(b => {+ b.onclick = () => setH3Orientation(b.dataset.h3Orientation);+});+(function _restoreH3Orientation() {+ let v = 'landscape';+ try { v = localStorage.getItem('phos_h3_orientation') || 'landscape'; } catch (e) {}+ const apply = () => setH3Orientation(v);+ if (document.readyState === 'loading') {+ document.addEventListener('DOMContentLoaded', apply);+ } else { apply(); }+})();+// Sampler depth for an H3 render. 'auto' = the tier's tuned count (stamped in// H3_TIERS); a number overrides it for every window of the job. Server-side// make_job clamps to 4-30 and re-validates — a stale tab must never win.@@ -43636,6 +44064,11 @@ function updateDerived() {const inI2V = mode === 'i2v' || mode === 'i2v_clean_audio';const inImageFlow = inI2V || currentMode === 'keyframe';document.getElementById('imageSection').classList.toggle('show', inI2V && currentMode !== 'keyframe');+ // The reference-use row lives inside that section and follows the same+ // mode question, plus the server's 2.5-only availability flag.+ if (typeof _applyI2vRefModeVisibility === 'function') {+ try { _applyI2vRefModeVisibility(); } catch (_) {}+ }document.getElementById('extendSection').classList.toggle('show', currentMode === 'extend');// Colorize (restore) shows its own source-video picker. Unlike Extend it// KEEPS the sizing + quick-metrics rows below (the source's own dims/length@@ -46007,6 +46440,11 @@ async function loadParams() {if (typeof setSchedPreset === 'function') {try { setSchedPreset(p.schedule_preset || ''); } catch (e) {}}+ // Reference use round-trips from day one; always applied, so a clip+ // rendered on Anchor clears a leftover Inspire.+ if (typeof setI2vRefMode === 'function') {+ try { setI2vRefMode(p.i2v_reference_mode || 'anchor'); } catch (e) {}+ }if (p.temporal_mode) setTemporalMode(p.temporal_mode);if (p.upscale) setUpscale(p.upscale);if (p.upscale_method) setUpscaleMethod(p.upscale_method);@@ -46252,6 +46690,9 @@ async function loadParams() {if (typeof setH3Upscale === 'function' && p.h3_upscale) {try { setH3Upscale(p.h3_upscale); } catch (e) {}}+ if (typeof setH3Orientation === 'function') {+ try { setH3Orientation(p.h3_orientation || 'landscape'); } catch (e) {}+ }if (typeof setH3Turbo === 'function') {try { setH3Turbo(!!Number(p.h3_turbo || 0)); } catch (e) {}}@@ -46521,6 +46962,9 @@ function renderOutputInfoBody(path, data) {if (p.schedule_preset && p.schedule_preset !== 'default') {genRows.push(`<dt>Schedule</dt><dd>${escapeHtml(String(p.schedule_preset))} · draft schedule — a different take than Tuned</dd>`);}+ if (p.i2v_reference_mode === 'inspire') {+ genRows.push(`<dt>Reference use</dt><dd>Inspire — the image guided subject and style; the shot was composed fresh (not animated from it)</dd>`);+ }if (accelMetrics && p.accel && p.accel !== 'off') {const cachedCount = accelMetrics.cached_steps_count || 0;const totalSteps = accelMetrics.total_steps || p.steps || 0;@@ -46736,6 +47180,7 @@ document.getElementById('genForm').addEventListener('submit', async e => {fd.set('character_id', ''); // character LoRAs are an LTX constructfd.set('no_voice', ''); // only ever meant "skip the character's voice LoRA"fd.set('schedule_preset', ''); // an LTX-2.5 distilled schedule; H3 has its own axes+ fd.set('i2v_reference_mode', 'anchor'); // an LTX-2.5 sampler behaviour// `loras` IS NOT SCRUBBED, and the line that used to scrub it said "the H3// runner stacks nothing" — true when it was written, false since the H3// LoRA import shipped in 3.7.0. H3 takes ONE adapter from its own family@@ -49792,9 +50237,22 @@ function renderNowPreview(s, prog, previewData) {missing_decoder: { label: 'Install it', run: 'openModelsModal()' },stale_engine: null,};- const speaks = s.running && !prev && previewServesThisJob+ // H3 gets the SAME courtesy, from its own bootstrap block. Its absence has+ // a different cause and therefore a different sentence: the panel side is+ // complete (schema, adapter, per-job live dir) but no published H3 runner+ // implements `--live-preview`, so nothing can publish frames yet. Silence+ // here read as "the theater preview is broken on MiniMax" — it is not+ // broken, it is not built on that half yet, and saying so is the fix+ // available today. No CTA: there is nothing for the user to click.+ const h3state = ((BOOT.h3 || {}).live_preview) || {};+ const h3Modes = ((BOOT.h3 || {}).modes) || [];+ const h3Speaks = s.running && !prev && jobEngine === 'h3'+ && Array.isArray(h3Modes) && h3Modes.indexOf(jobMode) !== -1+ && h3state.on !== true && !!h3state.note;+ const speaks = (s.running && !prev && previewServesThisJob&& Object.prototype.hasOwnProperty.call(PREVIEW_ABSENCE_CTA,- pstate.reason);+ pstate.reason))+ || h3Speaks;let miss = document.getElementById('nowPreviewMissing');if (speaks) {if (!miss) {@@ -49803,8 +50261,8 @@ function renderNowPreview(s, prog, previewData) {miss.className = 'now-preview-missing';box.parentNode.insertBefore(miss, box.nextSibling);}- const cta = PREVIEW_ABSENCE_CTA[pstate.reason];- miss.innerHTML = escapeHtml(pstate.note || '') + (cta+ const cta = h3Speaks ? null : PREVIEW_ABSENCE_CTA[pstate.reason];+ miss.innerHTML = escapeHtml((h3Speaks ? h3state.note : pstate.note) || '') + (cta? ` <a href="#" onclick="event.preventDefault();${cta.run}">`+ escapeHtml(cta.label) + '</a>': '');@@ -50343,6 +50801,52 @@ function _applySchedPresetRowVisibility() {if (tunedSub) tunedSub.textContent = cell.eta || 'default schedule';}}+// ---- i2v reference use (Anchor / Inspire) ----------------------------------+// Server-owned availability: BOOT.ltx.inspire_available is true only where the+// engine's masked-sample re-pin is version-resolved on (2.5). The UI never+// parses a generation label.+function setI2vRefMode(v) {+ const val = (v === 'inspire') ? 'inspire' : 'anchor';+ const inp = document.getElementById('i2v_reference_mode');+ if (inp) inp.value = val;+ document.querySelectorAll('#i2vRefModeGroup [data-i2v-ref]').forEach(b =>+ b.classList.toggle('active', (b.dataset.i2vRef || '') === val));+ if (typeof updateCustomizeSummary === 'function') {+ try { updateCustomizeSummary(); } catch (e) {}+ }+}+function i2vInspireActive() {+ return (document.getElementById('i2v_reference_mode') || {}).value === 'inspire';+}+function _applyI2vRefModeVisibility() {+ const row = document.getElementById('i2vRefModeRow');+ if (!row) return;+ const isI2v = (currentMode === 'i2v');+ const offered = !!((BOOT.ltx || {}).inspire_available)+ && isI2v && document.body.dataset.engine !== 'h3';+ row.hidden = !offered;+ // A mode the current lane cannot honor must not ride on the form — the+ // server drops it anyway (make_job gates it); this keeps UI and wire+ // agreeing. Direct clear, no setter (avoids a summary repaint loop).+ if (!offered && i2vInspireActive()) {+ const inp = document.getElementById('i2v_reference_mode');+ if (inp) inp.value = 'anchor';+ document.querySelectorAll('#i2vRefModeGroup [data-i2v-ref]').forEach(b =>+ b.classList.toggle('active', (b.dataset.i2vRef || '') === 'anchor'));+ }+}+function _wireI2vRefModePills() {+ const group = document.getElementById('i2vRefModeGroup');+ if (!group || group.dataset.wired === '1') return;+ group.dataset.wired = '1';+ group.querySelectorAll('[data-i2v-ref]').forEach(b => {+ b.addEventListener('click', (e) => {+ e.preventDefault();+ setI2vRefMode(b.dataset.i2vRef || 'anchor');+ });+ });+}+function _wireSchedPresetPills() {const group = document.getElementById('schedPresetGroup');if (!group || group.dataset.wired === '1') return;@@ -50906,6 +51410,10 @@ document.addEventListener('DOMContentLoaded', () => {if (typeof _wireSchedPresetPills === 'function') {try { _wireSchedPresetPills(); } catch (e) {}}+ // Bind the reference-use pills; visibility follows mode in updateDerived.+ if (typeof _wireI2vRefModePills === 'function') {+ try { _wireI2vRefModePills(); } catch (e) {}+ }// Apply correct quality-strip visibility based on whether a character// is already selected (e.g. restored from sidecar / Load Params).if (typeof _applyCharacterQualityStripVisibility === 'function') {diff --git a/mlx_warm_helper.py b/mlx_warm_helper.pyindex 1466d67..735027b 100644--- a/mlx_warm_helper.py+++ b/mlx_warm_helper.py@@ -2237,7 +2237,7 @@ def configure_acceleration(mode: str) -> str:# of letting it surface as an un-triageable TypeError mid-render.## 2026-08-12: this is a FORK BUILD, not an upstream tag. The vendored checkout-# is mrbizarro/ltx-2-mlx at the immutable tag `v0.14.19+ltx25.4` — v0.14.19 plus+# is mrbizarro/ltx-2-mlx at the immutable tag `v0.14.19+ltx25.5` — v0.14.19 plus# the LTX-2.5 port (keyframe pos-emb, Gemma 4 tower, ancestral sampler). The# release segment stays 0.14.19 because that is genuinely what it branches from;# the `+ltx25.N` local segment is what makes the two distinguishable.@@ -2262,7 +2262,7 @@ def configure_acceleration(mode: str) -> str:# — a skew gate blind to the one skew that mattered. Bumping the pin here# without bumping the packages (or the reverse) puts it back into permanent# SKEW warnings, so the two move together or not at all.-_LTX_EXPECTED_VERSION = "0.14.19+ltx25.4"+_LTX_EXPECTED_VERSION = "0.14.19+ltx25.5"def _detect_ltx_version() -> dict:@@ -2496,6 +2496,11 @@ for line in sys.__stdin__:# log line, so carrying the key is forward-safe by design.if p.get("schedule_preset"):kwargs["schedule_preset"] = str(p["schedule_preset"])+ # Inspire (loose reference): forwarded only when TRUE, so an+ # older installed library never sees a key it cannot take — and+ # _filter_unsupported_kwargs drops it with a log line even then.+ if p.get("loose_reference"):+ kwargs["loose_reference"] = True# Y1.037: short-clip VAE-streaming opt-out. Set the env var BEFORE# generate() so it propagates through the whole chain (the patched# decode_and_stream reads os.environ at decode call time).@@ -2853,6 +2858,12 @@ for line in sys.__stdin__:# the cap IS the iteration count (not just a safety bound).# Each iter is pure latent algebra — no model forwards.bongmath_max_iter=int(p.get("bongmath_max_iter", 100)),+ # Inspire on the HQ lane: skip the masked-sample re-pin so+ # the reference guides subject/style and the composition+ # re-imagines itself. False (default) anchors the image for+ # real on 2.5 — the fix for the owner-reported "High ignores+ # my reference". Filtered out on an older library.+ loose_reference=bool(p.get("loose_reference", False)),# video_skip_step / audio_skip_step removed (v4.0.5): the# pinned generate_and_save accepts neither kwarg, so# _filter_unsupported_kwargs discarded them every render —diff --git a/patch_ltx_codec.py b/patch_ltx_codec.pyindex 797418d..521529c 100644--- a/patch_ltx_codec.py+++ b/patch_ltx_codec.py@@ -255,7 +255,7 @@ def _shout(*lines: str) -> None:def main() -> int:- print("Applying LTX23MLX codec patch (ltx-2-mlx v0.14.19+ltx25.4 — only the codec edit remains):")+ print("Applying LTX23MLX codec patch (ltx-2-mlx v0.14.19+ltx25.5 — only the codec edit remains):")# `upgrade_marker="+faststart"` lets us upgrade installs where the# earlier version of this patch was applied (LTX_OUTPUT_PIX_FMT markerdiff --git a/scripts/pinokio/ltx_checkout.sh b/scripts/pinokio/ltx_checkout.shindex 03c1e80..edb301e 100644--- a/scripts/pinokio/ltx_checkout.sh+++ b/scripts/pinokio/ltx_checkout.sh@@ -39,7 +39,7 @@# A tag is the only form of this reference that an upstream history rewrite# cannot take away.#-# `v0.14.19+ltx25.4` on mrbizarro/ltx-2-mlx == v0.14.19 plus:+# `v0.14.19+ltx25.5` on mrbizarro/ltx-2-mlx == v0.14.19 plus:# - the LTX-2.5 port (versioned DiT config, duration head, Euler-ancestral# sampler, the vendored Gemma 4 text tower, encoder keyed off the checkpoint)# - unfused runtime LoRAs (c78cc71..3259338)@@ -56,14 +56,14 @@# step, so a 2.5 i2v render composed the clip without ever seeing the# supplied image and only the terminal step stamped it back in.#-# The three packages declare `0.14.19+ltx25.4`, and `_LTX_EXPECTED_VERSION` in+# The three packages declare `0.14.19+ltx25.5`, and `_LTX_EXPECTED_VERSION` in# mlx_warm_helper.py must equal that string. Move the two together or the# version-skew gate reports a permanent false alarm.## To bump: retag on the fork, change LTX_PIN here, change the documented value# in install.js, bump the three pyprojects AND _LTX_EXPECTED_VERSION, run# `node scripts/check_ltx_pin.js`, smoke-test on dev, push.-LTX_PIN="v0.14.19+ltx25.4"+LTX_PIN="v0.14.19+ltx25.5"LTX_FORK_URL="https://github.com/mrbizarro/ltx-2-mlx.git"ROOT="$(cd "$(dirname "$0")/../.." && pwd)"diff --git a/scripts/test_analytics_dryrun.py b/scripts/test_analytics_dryrun.pyindex e88287e..caac229 100644--- a/scripts/test_analytics_dryrun.py+++ b/scripts/test_analytics_dryrun.py@@ -486,7 +486,19 @@ class TestEventSchemas(AnalyticsTestCase):# os_version is major.minor only — no patch level.self.assertLessEqual(len(p["os_version"].split(".")), 2)+ # The schema-v2 render event's full closed field set (spec 2.4). Every+ # addition is a coarse class or a closed vocabulary — the exact-set+ # assertion is the guard that a content-shaped field cannot ride along.+ RENDER_V2_FIELDS = {+ "engine", "mode", "tier", "duration_bucket", "resolution", "frames",+ "version", "chip_family", "ram_gb", "os_version", "canvas_class",+ "steps", "accel", "temporal_mode", "upscale", "upscale_method",+ "schedule_preset", "chain_windows", "chain_prompts_used",+ "lora_count", "lora_kinds", "character_used", "audio_mode",+ }+def test_render_completed_fields(self):+ self.configure(analytics_first_render_reported=True)P._analytics_render_event({"status": "done", "elapsed_sec": 340.0,"params": {"mode": "t2v", "engine": "ltx", "quality": "standard",@@ -494,33 +506,126 @@ class TestEventSchemas(AnalyticsTestCase):})drain()p = self.props_of("render_completed")- self.assertEqual(set(p), {- "engine", "mode", "tier", "duration_bucket", "resolution", "frames"})+ self.assertEqual(set(p), self.RENDER_V2_FIELDS | {"wall_sec_bucket"})self.assertEqual(p["resolution"], "1216x704")self.assertEqual(p["duration_bucket"], "5-15m")+ self.assertEqual(p["wall_sec_bucket"], 300)+ self.assertEqual(p["canvas_class"], "720p")self.assertEqual(p["tier"], "standard")+ # The machine-class trio matches what app_boot sends — same values,+ # repeated so PostHog breakdowns need no join (spec F6).+ self.assertEqual(p["chip_family"], P._analytics_chip_family())+ self.assertIsInstance(p["ram_gb"], int)+ self.assertEqual(p["schedule_preset"], "default")+ self.assertEqual(p["lora_kinds"], "none")+ self.assertFalse(p["character_used"])+ self.assertEqual(p["audio_mode"], "joint")- def test_render_failed_adds_only_error_signature(self):+ def test_render_failed_adds_the_error_taxonomy(self):+ self.configure(analytics_first_render_reported=True)P._analytics_render_event({- "status": "failed", "error": "OOM during VAE decode",+ "status": "failed", "error": "OOM during VAE decode: SIGKILL","elapsed_sec": 61.0,"params": {"mode": "i2v", "engine": "h3", "h3_tier": "hq_5s","width": 1280, "height": 720, "frames": 90},})drain()p = self.props_of("render_failed")- self.assertEqual(set(p), {- "engine", "mode", "tier", "duration_bucket", "resolution",- "frames", "error_signature"})+ self.assertEqual(set(p), self.RENDER_V2_FIELDS+ | {"wall_sec_bucket", "error_class",+ "error_signature"})# h3_tier is the wire format, and every legacy key still resolves to# the cell it means: the quality x length refactor renamed hq_5s to# standard_5s, and a job replayed from an older sidecar must land in- # that bucket rather than inventing one. (The fixture here used to be- # "5s", which is a LENGTH and was never a tier key — see- # test_unrecognised_h3_tier_collapses_to_unknown for where it goes.)+ # that bucket rather than inventing one.self.assertEqual(p["tier"], "standard_5s","a legacy h3_tier must resolve to its current cell")self.assertEqual(p["duration_bucket"], "<2m")+ self.assertEqual(p["wall_sec_bucket"], 60)+ # SIGKILL classifies as the jetsam class; a classified error carries+ # NO fingerprint — that field exists only for `other`.+ self.assertEqual(p["error_class"], "oom_jetsam")+ self.assertNotIn("error_fingerprint", p)+ self.assertEqual(p["audio_mode"], "h3_native")++ def test_unknown_error_ships_class_other_plus_fingerprint(self):+ self.configure(analytics_first_render_reported=True)+ P._analytics_render_event({+ "status": "failed", "error": "ZeroDivisionError: division by zero",+ "elapsed_sec": 10.0,+ "params": {"mode": "t2v", "engine": "ltx", "quality": "quick",+ "width": 640, "height": 448, "frames": 73},+ })+ drain()+ p = self.props_of("render_failed")+ self.assertEqual(p["error_class"], "other")+ # 12 hex chars of the SCRUBBED line — countable, not readable.+ self.assertRegex(p["error_fingerprint"], r"^[0-9a-f]{12}$")+ self.assertEqual(+ p["error_fingerprint"],+ P._analytics_error_fingerprint(p["error_signature"]))++ def test_error_taxonomy_is_closed_and_ordered(self):+ cases = {+ "Command buffer exec failed: kIOGPUCommandBufferCallbackErrorTimeout":+ "metal_watchdog",+ # The watchdog marker must win over the generic signal words —+ # issue #44 must never be merged into native_crash.+ "SIGABRT after Caused GPU Timeout Error": "metal_watchdog",+ "helper died mid-job (no event)": "oom_jetsam",+ "signal SIGSEGV in worker": "native_crash",+ "helper failed to start: None": "helper_start_timeout",+ "Broken pipe while writing job": "helper_exit",+ "HTTP Error 403: gated repo": "download_failed",+ "checksum mismatch (download corrupt) - please retry":+ "download_failed",+ "safetensors header truncated": "model_corrupt",+ "Hailuo H3 isn't fully installed yet: dit": "model_missing",+ "No module named 'mlx'": "venv_broken",+ "OSError: [Errno 28] No space left on device": "disk_full",+ "input image does not exist": "input_missing",+ "ffmpeg exited 1": "export_failed",+ "prompt required": "bad_params",+ "phase timed out after 300s": "timeout",+ "cancel requested, landing as failed": "cancelled_race",+ "some brand new exploding thing": "other",+ }+ for raw, want in cases.items():+ self.assertEqual(P._analytics_error_class(raw), want, raw)++ def test_wall_ladder_edges(self):+ f = P._analytics_wall_sec_bucket+ self.assertIsNone(f(None))+ self.assertIsNone(f(0))+ self.assertEqual(f(7), 0)+ self.assertEqual(f(15), 15)+ self.assertEqual(f(499.3), 420)+ self.assertEqual(f(3599), 2400)+ self.assertEqual(f(99999), 5400)++ def test_canvas_classes(self):+ f = P._analytics_canvas_class+ self.assertEqual(f(640, 448), "<=480p")+ self.assertEqual(f(1024, 576), "576p")+ self.assertEqual(f(1280, 704), "720p")+ self.assertEqual(f(1920, 1080), "1080p")+ self.assertEqual(f(2560, 1440), "native+")+ self.assertEqual(f(0, 0), "unknown")++ def test_first_render_fires_once_ever(self):+ self.configure(analytics_first_render_reported=False)+ job = {"status": "done", "elapsed_sec": 60.0,+ "params": {"mode": "t2v", "engine": "ltx", "quality": "quick",+ "width": 640, "height": 448, "frames": 73}}+ P._analytics_render_event(job)+ drain()+ self.assertTrue(self.props_of("render_completed").get("first_render"))+ self.assertTrue(+ P.get_settings().get("analytics_first_render_reported"))+ self.spy.calls.clear()+ P._analytics_render_event(job)+ drain()+ self.assertNotIn("first_render", self.props_of("render_completed"))def test_app_installed_fields(self):"""Fires once per install, ever, immediately before its firstdiff --git a/test_schedule_preset.py b/test_schedule_preset.pyindex 9dfe560..16caaf9 100644--- a/test_schedule_preset.py+++ b/test_schedule_preset.py@@ -110,5 +110,110 @@ class TestTierTableStampsFastOnlyWhereItRuns(unittest.TestCase):self.assertNotIn("fast_eta", cell, cell["key"])+++class TestI2vReferenceMode(unittest.TestCase):+ """Anchor/Inspire is lane-gated exactly like the schedule preset."""++ def setUp(self):+ self.old_version = P.ACTIVE_MODEL_VERSION++ def tearDown(self):+ P.ACTIVE_MODEL_VERSION = self.old_version++ def test_inspire_rides_on_25_i2v(self):+ P.ACTIVE_MODEL_VERSION = "ltx25"+ job = job_for({"mode": "i2v", "i2v_reference_mode": "inspire"})+ self.assertEqual(job["params"]["i2v_reference_mode"], "inspire")++ def test_inspire_is_dropped_on_t2v(self):+ # No reference image, nothing to be loose about.+ P.ACTIVE_MODEL_VERSION = "ltx25"+ job = job_for({"mode": "t2v", "i2v_reference_mode": "inspire"})+ self.assertEqual(job["params"]["i2v_reference_mode"], "anchor")++ def test_inspire_is_dropped_on_23(self):+ # The engine only version-resolves the re-pin on 2.5; 2.3's bytes+ # are deliberately untouched, so the mode has no meaning there.+ P.ACTIVE_MODEL_VERSION = "ltx23"+ job = job_for({"mode": "i2v", "i2v_reference_mode": "inspire"})+ self.assertEqual(job["params"]["i2v_reference_mode"], "anchor")++ def test_inspire_is_dropped_on_h3(self):+ P.ACTIVE_MODEL_VERSION = "ltx25"+ job = job_for({"mode": "i2v", "engine": "h3",+ "i2v_reference_mode": "inspire"})+ self.assertEqual(job["params"]["i2v_reference_mode"], "anchor")++ def test_bogus_and_absent_normalize_to_anchor(self):+ P.ACTIVE_MODEL_VERSION = "ltx25"+ self.assertEqual(+ job_for({"mode": "i2v", "i2v_reference_mode": "wildcard"}+ )["params"]["i2v_reference_mode"], "anchor")+ self.assertEqual(+ job_for({"mode": "i2v"})["params"]["i2v_reference_mode"], "anchor")+++class TestIngredientsGeneration(unittest.TestCase):+ """Ingredients is offered exactly where its adapter works."""++ def test_predicate_matches_the_generation(self):+ self.assertFalse(P.ltx_generation_serves_ingredients("ltx25"))+ self.assertTrue(P.ltx_generation_serves_ingredients("ltx23"))++ def test_bootstrap_flags_follow_the_predicate(self):+ old = P.ACTIVE_MODEL_VERSION+ try:+ P.ACTIVE_MODEL_VERSION = "ltx25"+ boot = P.ltx_tiers_payload()+ self.assertFalse(boot["ingredients_available"])+ self.assertTrue(boot["inspire_available"])+ P.ACTIVE_MODEL_VERSION = "ltx23"+ boot = P.ltx_tiers_payload()+ self.assertTrue(boot["ingredients_available"])+ self.assertFalse(boot["inspire_available"])+ finally:+ P.ACTIVE_MODEL_VERSION = old+++class TestH3Orientation(unittest.TestCase):+ """Portrait rotates the resolved cell; it never invents a tier."""++ def h3_job(self, form: dict) -> dict:+ base = {"mode": "t2v", "engine": "h3", "prompt": "a lighthouse"}+ base.update(form)+ return P.make_job({k: [str(v)] for k, v in base.items()})++ def test_portrait_flips_the_cells_canvas(self):+ land = self.h3_job({})["params"]+ port = self.h3_job({"h3_orientation": "portrait"})["params"]+ self.assertEqual(port["width"], land["height"])+ self.assertEqual(port["height"], land["width"])+ self.assertGreater(port["height"], port["width"], "portrait must be tall")+ # Same tier key and same frame count: the wire format is untouched,+ # so every sidecar ever written still replays.+ self.assertEqual(port["h3_tier"], land["h3_tier"])+ self.assertEqual(port["frames"], land["frames"])++ def test_the_pixel_budget_is_identical(self):+ land = self.h3_job({})["params"]+ port = self.h3_job({"h3_orientation": "portrait"})["params"]+ self.assertEqual(land["width"] * land["height"],+ port["width"] * port["height"],+ "a rotation must not change cost")++ def test_bogus_and_absent_normalize_to_landscape(self):+ self.assertEqual(+ self.h3_job({"h3_orientation": "sideways"})["params"]["h3_orientation"],+ "landscape")+ self.assertEqual(self.h3_job({})["params"]["h3_orientation"], "landscape")++ def test_orientation_does_not_ride_the_ltx_lane(self):+ job = P.make_job({k: [v] for k, v in {+ "mode": "t2v", "engine": "ltx", "prompt": "x",+ "quality": "balanced", "h3_orientation": "portrait"}.items()})+ self.assertEqual(job["params"]["h3_orientation"], "landscape")++if __name__ == "__main__":unittest.main(verbosity=2)