Skip to content

Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.

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.md
index 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.md
index 51970c9..2ce055b 100644
--- a/README.md
+++ b/README.md
@@ -135,8 +135,8 @@ cd phosphene
git clone https://github.com/dgrauet/ltx-2-mlx.git ltx-2-mlx
cd ltx-2-mlx
git 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.5
cd ..
# 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.
## Interface
diff --git a/VERSION b/VERSION
index d13e837..43beb40 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-4.0.6
+4.0.7
diff --git a/docs/ANALYTICS.md b/docs/ANALYTICS.md
index 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 about
the software.
@@ -259,7 +280,7 @@ network is touched, and independently of whether the send then succeeds. One
JSON 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 Usage
diff --git a/docs/STATE.md b/docs/STATE.md
index 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.js
index 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 the
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index 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 by
data-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 is
neither 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 construct
fd.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.py
index 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.py
index 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 marker
diff --git a/scripts/pinokio/ltx_checkout.sh b/scripts/pinokio/ltx_checkout.sh
index 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.py
index 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 first
diff --git a/test_schedule_preset.py b/test_schedule_preset.py
index 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)