Skip to content

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

v4.13.1 — Hailuo H3 that looks right

mrbizarroba83d51e1c84
diff --git a/README.md b/README.md
index 80da39d..17aab86 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@
</p>
-> **Current release: v4.13.0.** **The editor you already know**: a clip bar above the tracks for the everyday cuts, select several clips and move them together, right-click menus, keys from Premiere and Final Cut, and **Docs built into the app** (the Docs button, or press ?). One Shot gets its own tab, and Storyboard scores spoken shots for lip-sync. Full notes on the [releases page](https://github.com/mrbizarro/Phosphene/releases).
+> **Current release: v4.13.1.** **Hailuo H3 that looks right**: High clips run twice the sampler steps, so faces and motion come out sharp (a 5 s High clip now takes about 34 min instead of 19); every clip keeps its last frame; Turbo applies its whole adapter; Upscale ×2 no longer flashes white at the end; twelve more H3 fixes. Full notes on the [releases page](https://github.com/mrbizarro/Phosphene/releases).
## Overview
diff --git a/VERSION b/VERSION
index 813b83b..56d2fb5 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-4.13.0
+4.13.1
diff --git a/docs/H3_ENGINE.md b/docs/H3_ENGINE.md
index 0b3cd43..8d16ea0 100644
--- a/docs/H3_ENGINE.md
+++ b/docs/H3_ENGINE.md
@@ -136,7 +136,7 @@ its chips from `/status.h3.tiers`, so a tier change is one Python edit.
| Draft · 3s | 640×384 · 73f | 5:3 | 1 | 9 (8 forwards) | ~3 min |
| HQ · 3s | 768×448 · 73f | 12:7 | 1 | 9 (8 forwards) | ~4-5 min |
| HQ · 5s | 768×448 · 124f | 12:7 | 1 | 9 (8 forwards) | ~8 min |
-| **Wide · 5s** | **1024×576 · 124f** | **16:9** | 1 | 9 (8 forwards) | **~17-19 min** |
+| **Wide / High · 5s** | **1024×576 · 124f** | **16:9** | 1 | **16 (15 forwards)** since 2026-09-16 | **~34 min** (was ~19 at 8 forwards) |
| Long · 10s | 768×448 · 243f | 12:7 | **2 × 124f chained** | 9 (8 forwards) | ~17 min |
| Long · 15s | 768×448 · 362f | 12:7 | **3 × 124f chained** | 9 (8 forwards) | ~27 min · batch |
@@ -174,7 +174,17 @@ Each tier's `aspect` is derived from its own width/height (`_h3_aspect`) and
appended to the `spec` string the chip prints, so the advertised ratio can never
drift from the geometry that renders.
-**Why 9 points everywhere now.** `--steps` is sigma *points*; the runner does
+**High runs 16 points (2026-09-16).** Every High cell (1024×576, any length)
+now runs 16 sigma points = 15 forwards per window. A matched gym A/B (same seed,
+still and prompt) at 15 forwards was clearly better than at 8, where the face was
+blurry; 1024×576/124f is ~22.9k packed rows, well past the ~13k envelope below.
+Knobs: `H3_HIGH_STEPS` and `H3_NATIVE_STEPS` in `mlx_ltx_panel.py` (Native stays
+at 9 until its own 15-forward test is judged). A cell runs
+`max(length steps, canvas steps)`. `H3_MEASURED_ETA` entries carry the forwards
+they were measured at, so the old 18.8 min High receipt no longer prints as
+"measured" for a 15-forward cell.
+
+**Why 9 points everywhere else.** `--steps` is sigma *points*; the runner does
`points - 1` forwards. A matched-cost A/B showed 8 forwards is visually free at
or below ~13k packed rows (640×384/73f ≈ 5.6k, 768×448/124f ≈ 13.7k). A *dense*
768×448/243f pass is ~25k rows, where 8 forwards **ghosts** (two astronauts on
diff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md
index ee9c108..985cd96 100644
--- a/docs/RELEASE_CHECKLIST.md
+++ b/docs/RELEASE_CHECKLIST.md
@@ -254,6 +254,31 @@ leaves it staging the promote tree — reset it when you are done. And any weigh
pack published for this release must be tagged on the **public main commit you
just pushed** (§3b), which means the packs go up *after* step 4, not before.
+## 6. Announce on Pinokio — part of every release
+
+A release is not done until its Pinokio post is live and the post's URL is in
+the release report. Owner, 2026-08-05 and again 2026-09-13: "This should be
+part of the protocol for releases."
+
+- **Check the login BEFORE promoting.** Open the app page on pinokio.co in the
+ owner's Chrome. A **Log in** link in the header means the session dropped:
+ tell the owner at once, so he signs in while the gates run. Never type
+ credentials on his behalf.
+- **Enter through the app page's Post button** (owner-only, top right).
+ Navigating straight to `/posts/new` bounces and can drop the session.
+- **Size the post to the release.** x.y.Z: a short text post (headline title,
+ 4–6 bullets in user language, credit the reporters, link the release).
+ x.Y.0: media-rich, with a hero image or clip made from real Phosphene output,
+ screenshots of the new surface, and the fuller story.
+- **Paste ASCII only** (straight quotes, `-` instead of dashes). Non-ASCII
+ mojibakes through the clipboard paste.
+- **Media goes in through the composer's own file input**, so it lands on
+ Pinokio's CDN before publishing.
+- **Publish → Review → pick the feed cover → Publish.** Write the post URL into
+ the release's `docs/STATE.md` entry.
+- **Missed a release?** The next post covers every unannounced version, one
+ section each.
+
---
If any gate fails, **do not ship** — that's the whole point of this file.
diff --git a/docs/STATE.md b/docs/STATE.md
index 7b5e8eb..fd8feaa 100644
--- a/docs/STATE.md
+++ b/docs/STATE.md
@@ -1,5 +1,231 @@
# Phosphene — project state, history, open work
+> **🚀 2026-09-16 — v4.13.1 released: the H3 + ×2 fix wave (owner's order: "fix it and ship it").**
+> **Shipped (cherry-picked onto public 4.13.0, NOT a dev read-tree):** `3a5c5cc` autoplay only on click,
+> `85a7098` H3 reference image validated with PIL, `745dc9c` Turbo adaLN + provenance, `8eafdc5` High = 16
+> sigma points, `1e1ec51` ×2 int32 tail + full frame count, `3a4d9ad`, `a1c9808` the twelve round-2 fixes,
+> plus `docs/RELEASE_CHECKLIST.md` (Pinokio step) from dev. **Held back on dev (headline Editor work, gated on
+> owner use):** audio tracks (`d12dc30` `d3c5dfb` `d8b280a`), A/B clip-sound lanes (`02a7e30`), compact sound
+> lanes (`e588b52`) — their panel/editor/API/doc hunks are the ONLY difference between the release tree and dev.
+> **Runner:** no SHA pin exists — `install_h3.js` clones and `scripts/pinokio/h3_checkout.sh` (run by Install
+> and by every Update through `post_update.sh` when H3 is installed) resets to the tip of
+> `minimax-h3-mlx codex/h3-engine-v2`, which is `11b90a0` (mux keeps every frame, LoRA accounting). So H3
+> users get the runner fix by pressing Update; no reinstall.
+> **Gates:** full `release_gates.sh` 93 PASS / 0 FAIL / 0 SKIP in the release worktree, MLX forced to the CPU
+> device via a `sitecustomize` shim (the GPU was rendering the owner's jobs on 8199). Clean-room boot of a
+> fresh clone on a spare port: see the release report in the PM hub.
+
+> **🔎 2026-09-16 — H3 round-2 review: High runs 15 forwards, twelve bugs fixed (UNRELEASED, `dev`).**
+> **High = 16 points (`8eafdc5`).** The owner ran a matched gym A/B: High 1024×576 was clearly better at 15
+> forwards than at 8, where the face was blurry. Every High cell now bakes `H3_HIGH_STEPS = 16`. A cell runs
+> `max(length steps, canvas steps)`, so dense 10 s stays at 16. **Native is unchanged** and waits for its own
+> 15-forward test: flip `H3_NATIVE_STEPS` (today `= H3_STEPS_DEFAULT`). `H3_MEASURED_ETA` entries now carry the
+> forwards they were measured at. The 8-forward 18.8 min receipt therefore no longer prices High; the model
+> says ~34 min for High 5 s. Storyboard "standard"/"high" passes use the High canvas, so **storyboard H3
+> films now take about 1.8× longer**. Queued jobs keep the steps stamped at queue time.
+> **Round-2 audit (`a1c9808`).** Codex's report is PM hub `notes/h3-review/FINDINGS_R2.md`; the triage is
+> `FINDINGS_R2_TRIAGE.md`. All 12 findings were confirmed and fixed:
+> - the ×2 handoff now keeps the prompt and seed
+> - Finish restores LoRAs, orientation and the adapter slot
+> - a salvage needs a verified frame count
+> - kohya imports are no longer double-scaled; stored strengths are corrected on read
+> - mixed per-module alphas are folded
+> - No Music reaches written chain windows
+> - the sidecar keeps the user's reference image
+> - pinned steps 4–30 survive a replay
+> - measured and pinned ETAs carry the hardware factor
+> - Turbo ETAs re-price live
+> - codec provenance is truthful (runner `--crf ≤ 18`)
+> - Stop early is withdrawn after the last abort boundary
+>
+> **Not changed:** the ×2 lane's 129-frame ceiling (the upscaler agent's `1e1ec51`) and the runner's fixed `yuv420p`.
+> **Gates:** `test_h3_review_r2` 31 new, `test_h3_high_steps` 12 new. `release_gates.sh --fast`: 94 PASS / 0 FAIL
+> / 2 SKIP. MLX tests were run on the CPU device because renders were on the GPU.
+> **Needs a panel restart** for the Python changes. The web changes (Finish, Steps, No Music) arrive on a hard refresh.
+> **Runner:** `46f718e` is cherry-picked onto a local `codex/h3-engine-v2` (`11b90a0`, worktree
+> `hailuo-mlx/codex/h3-engine-v2-wt`) and is NOT pushed. Until it is pushed, fresh installs still lose the
+> last frame.
+
+> **🩹 2026-09-16 — LTX Upscale ×2: the white tail (and the early flash) was an int32 wrap in the VAE decode; the ×2 keeps every frame (UNRELEASED, `dev`).**
+> **Symptom.** Every ×2 of a 5 s 1024×576 H3 clip (→ 2048×1152, 121 f) blew frames 113–120 to near-white, on every
+> seed and source (13/13 in `state/panel_queue.json` history); some runs also flashed ~frames 18–27. 3 s sources
+> (65 f) and 640×384 sources (→ 1280×768) were clean (15/15). Per-band diffs vs the source show a razor-sharp
+> horizontal edge 3/4 down frame 112 — a flat-index boundary, not a bad latent frame.
+> **Cause.** MLX's Metal conv3d (`steel_conv_3d.h`, implicit GEMM) offsets its output with 32-bit ints. The conv VAE
+> decoder's stage 8 at that size is 128 × 121 × 288 × 512 = **2.28e9 elements > 2³¹**; the wrap lands at frame
+> 112.8 and the tail is never written. The early flash is the same wrap: its corrupted run is 7.2 frames long —
+> exactly the 136 M elements past 2³¹ — written into whichever buffer the allocator put there (hence "random per
+> seed"). Upstream `_compute_decode_tiling` only tiles past an 8 GB *memory* budget (this decode is 2.3 GB).
+> **Fix.** `mlx_warm_helper.py`: `_DECODE_MAX_ELEMENTS` (0.9·2³¹), `_vae_decode_peak_elements`,
+> `_int32_safe_decode_tiling`, `_install_decode_int32_guard()` — wraps the module global every decode reads and
+> returns upstream's own temporal tiling with tiles under the cap (2048×1152: 96-frame tiles, 24 overlap).
+> Installed once at the generate/extend choke point, so every lane is covered; decodes that fit keep upstream's
+> answer. **Frame count:** the lane rounded DOWN to 1+8k (124 → 121) and muxed with `-shortest`. Now
+> `upscale_frame_plan()` delivers the source's own count (ceiling 129, or the form's frames if larger), the model
+> renders the next grid UP from a lossless copy with the last frame held (`_upscale_hold_tail_cmd`), and
+> `_upscale_finish()` cuts back to exactly N frames with the source audio `apad,atrim`'d to N/fps.
+> Sidecar: `delivered_frames`, `video_duration_sec`, `render_frames`, `source_frames`.
+> **Gates.** `test_upscale_x2_tail` 16 (decoder walk proves the peak formula; tiles from the vendored tiler all
+> under the cap and covering the clip; frame plan; real ffmpeg: held copy lossless, 124 in → 124 out + sound,
+> short audio keeps every frame — the old mux lost 7 of 121). `release_gates.sh --fast` 93 PASS / 0 FAIL / 2 SKIP.
+> **Not yet validated live:** needs a panel restart, then one queued ×2 of `integrated_multimodal_description_shot_1_a_h3_8.mp4`
+> (params of j-1a0a8e34dbf-055). The fork (`ltx-2-mlx`) should absorb the element cap at the next re-pin.
+
+> **🛠️ 2026-09-16 — H3: Turbo v4 gets its 51 adaLN pairs back; every clip keeps its last frame (UNRELEASED, `dev`).**
+> Two bugs CONFIRMED by the Codex audit (PM hub `notes/h3-review/FINDINGS.md`, §2 and §4). Both are now fixed.
+> **Turbo adaLN (§2).** larryvrh v4 step600 EMA has 259 LoRA pairs. 51 of them are adaLN pairs (50 blocks + the
+> final layer), and the pruned DiT cannot wrap those. The runner folds them into the modulation cache only when it
+> gets `--lora-adaln <upstream_time_embedder.safetensors>`. The 2026-08-14 LightX2V switch (below) removed that
+> flag, and v4 later came back as the preferred adapter without it. Result: every v4 render since then logged
+> `208 applied, 51 skipped` and dropped all 51. **Fix:** `h3_lora_adaln_pairs()` counts the pairs from the
+> adapter's safetensors HEADER, so detection never depends on the filename. `h3_turbo_paths()` now carries
+> `adaln_pairs` and `embedder`. `h3_turbo_adaln_state()` returns `none` / `absorbed` / `no_embedder` /
+> `runner_old`. `h3_turbo_argv()` adds `--lora-adaln` only in the `absorbed` state. The dispatch log names the
+> state, and says it loudly when the pairs will be skipped. /status has `turbo.adaln`. Getting the file to users:
+> `_h3_turbo_fetch_embedder()` runs the pack's own `scripts/fetch_time_embedder.py` (~60 MB range read). It runs
+> after the managed v4 download, from `/h3/turbo/install` when the adapter is already on disk (an embedder-only
+> fetch), and once at the first Turbo render that is missing the file (300 s cap). It is non-fatal everywhere.
+> **NOT exercised live:** that fetch; the mocks cover it. The dev box already has the file.
+> **Frame loss (§4).** The runner's `save_mp4` used `-shortest`, and that cut the last video frame of every
+> delivery (73→72, 124→123). Runner `codex/live-preview` @ `46f718e` fixes it: the audio is padded, then trimmed to
+> exactly frames/fps (`apad,atrim`), and video is capped with `-frames:v`. `delivered_frames` now comes from
+> ffprobe on the encoded file. The panel sidecar's `video_duration_sec` now reads that number.
+> **Provenance (§6, the cheap part).** The sidecar `model` is now the DiT that actually RAN (`_dit_path`), not
+> `paths["dit"]`. New fields: `model_precision`, plus `h3.turbo.adaln` and `h3.turbo.accounting` (the runner's
+> `lora_accounting`: wrapped / absorbed / unaccounted). The runner names its load phase `dit_load_q8` /
+> `dit_load_bf16` to match what it loaded, and the phase-label map knows both names.
+> **Validated.** One direct runner draft: Turbo v4 on Q8, 640×384/73f, 6 forwards (2.4 min). It logged
+> `208 wrapped, 51/51 adaLN absorbed (50 blocks + final layer, |dM|/|M| 2.9e-4), 0 unaccounted`. ffprobe on the
+> mp4 shows **73** video frames, with video and audio both 3.042 s. The frame looks coherent.
+> **Gates:** `test_h3_turbo_adapter` 22 (9 new: header detector, argv in all four states, the real v4 file = 51,
+> fetch success/failure, embedder-only install). Runner `tests/test_mux_frame_count.py` 35 checks: the old mux
+> fails 15 of them, and both Homebrew 8.1.2 and Pinokio 8.0.1 ffmpeg pass. `release_gates.sh --fast`: 91 PASS /
+> 0 FAIL / 2 SKIP (fast).
+> **Still open:** the runner fix sits on `codex/live-preview` and is NOT pushed. The pack that users clone
+> (`codex/h3-engine`) still has `-shortest` until it is ported. The panel was not restarted. The only render was
+> the draft above.
+
+> **🔇 2026-09-16 — The sound lanes make themselves small (branch `feat/compact-audio-lanes`, UNRELEASED).**
+> Owner, cutting a 13-shot film with clip sound on A/B and four audio tracks:
+> "the sound expands lower. The picture is so tiny, and it's a problem. I cannot
+> see anything in the image, and I can also not push it down if I want to compact
+> it… compact all audio lanes when I am not working with them and make them
+> little." **Measured, that was literal**: A/B + four tracks cost 246px of
+> `sbeExtraLanesH`, all of it out of the monitor, and `SBE_TL_MIN_H` was a
+> CONSTANT 280 (the sum of every lane's full base), so the drag handle could
+> never push the box lower than its sound lanes' 44 + 108.
+> **Model:** the lane table carries a second height — `audio: true, small: 18`
+> on `alane` (so A/B and every A3+ track follow it) and `small: 20` on `wave`.
+> `sbeTlFloor(small)` / `sbeTlRoof(small)` REPLACE the two constants (which are
+> now `sbeTlFloor(false)` / `sbeTlRoof(false)`), `sbeLaneHeights(tlH, small)`
+> gives a thin lane no share of a dragged pixel, and `sbeFitMonitors` budgets
+> against the current pair — so the whole saving reaches the picture.
+> **Auto:** `sbeAudioWant()` reads the state the audio gestures already write —
+> any audio drag, the height drag, playback, an open menu, a selected strip or
+> sound, the pointer over a lane or head, the Sound pool, focus in a sound head —
+> and `sbeAudioArm()` (re-armed by every `sbePaint`) makes them small 2.4s after
+> the last of it. Hover, click, a sound verb, + Add audio track, Add sound file
+> and pulling the edge up past the thin roof all open it at once.
+> **Manual:** ▾ / ▸ on the **A1 Clip sound A** head and **⇧A**
+> (`editor.soundLanes` in the one SHORTCUTS table) pin `small` or `open`;
+> clicking a thin lane hands the decision back to auto. Pinned in
+> `localStorage` as `phos_sbe_audio`, NEVER in `edit.json` — the rule above
+> `sbeTlPrefRead`. First auto-collapse says so in a toast, once per browser.
+> **Small is a picture, not a control surface:** CSS (inside `min-width: 901px`,
+> so the stacked page is untouched) drops grips, corner fades, the level line,
+> its points and the labels, keeps the waveform silhouette and the selection,
+> and the three pointer handlers short-circuit to `sbeAudioOpenFrom`.
+> **Measured** on a copy of the owner's four-track board, real Chrome at
+> 1600x1000 (scratch panel 8392, screenshots in the PM hub's
+> `notes/compact-audio-lanes-2026-09-16/`): program monitor **132px → 300px**
+> tall (235 → 532 wide), timeline floor **280 → 166**, extra lanes **246 → 116**,
+> the box **527 → 363**. Handle pushed all the way down: it stops at 280 with the
+> sound open (picture 132) and reaches **197 with it small (picture 349**, where
+> the 16:9 picture becomes width-limited and stops asking for height). Auto
+> expands on touch and compacts after the idle; it held open through a 3.4s drag
+> and 3.6s of playback and collapsed only after each ended; at 860px the lanes
+> keep their full height and their grips. Console clean.
+> **Gates:** `test_audio_compact.py` (13 new), the floor test rewritten to assert
+> the RULE at both sizes plus a lane-height probe, 483 in
+> `test_storyboard_editor_ui` + `test_docs_and_shortcuts`, 82 in the two audio
+> suites, `lint_webapp` clean, `release_gates.sh --fast` 88 PASS / 3 FAIL (the
+> worktree's known missing model packs + characters). `measure_editor_layout.py`
+> now pins the lanes open before it measures the handles.
+> **UI-only** — no Python touched, so it reaches a running dev panel on a hard
+> refresh with no restart.
+
+> **🎚️ 2026-09-15 — Clip sound on two lanes, A/B (branch `feat/audio-ab-lanes`, UNRELEASED).**
+> Owner: "When the app creates a timeline, the sound between clips should already
+> be intercalated into two different lanes … if I want to blend and dissolve from
+> both sides, cut a little, and bring the clips together to make it more realistic,
+> it's easy. This should be the default."
+> **Model:** `clip.sound_lane: 2` puts a video clip's own sound on lane B; absent
+> (or 1) is lane A, so every existing edit reads, digests and renders as before.
+> `clips_audio_overlap` is now checked WITHIN a lane (message names the lane);
+> across lanes sounds overlap and mix. `alternate_sound_lanes`, `sound_lane_after`,
+> `clip_sound_lane` in storyboard_editor.py; mirrors `sbeSoundLane`,
+> `sbeAlternateLanes`, `sbeLaneAfter`, `sbeLaneFit`, `sbeSetSoundLane` in editor.js.
+> **Default:** `edit_from_plan` lays every fresh timeline A, B, A… by film order
+> (video clips only); insert, fill-a-hole (pool +, Place) and Duplicate put the new
+> clip on the lane its previous neighbour is not on; Split keeps both halves on one.
+> **UI (A1 is one box, two strip lanes):** heads "A1 Clip sound A" / "A1 Clip sound
+> B"; **Alternate A/B** on the B head and **Alternate sound lanes** in the right-click
+> menu of any shot or sound re-lay an existing timeline (nothing moves in time, one
+> Undo); drag a sound up/down to change lane (linked ones too); right-click a sound →
+> **Move sound to lane B / A**; a dragged sound edge also snaps to other sounds' edges.
+> Preview already plays every overlapping strip. `sbeExtraLanesH` pays the timeline
+> height for lane B the way tracks are paid; SBE_LANES and the floor are unchanged.
+> **Render:** `_sb_split_audio_plan` returns `lanes` (A) and `lanes_b`; lane B is its
+> own `concat` (`[alb]`, silences `aqb*`), summed into the same `amix … asoftclip` as
+> the bed and A3+; `replace` drops both. Legacy graphs are BYTE-IDENTICAL: 42 golden
+> hashes from 85a7098 in `test_audio_ab_lanes` (linked/J-cut/muted/gain/speed/tx/still
+> × none/under/replace × strips); normalise/digest/cuts/XML/JSX of the owner's Saint
+> Feld edit also diffed identical. The bed duck already keys on every clip's window.
+> **Export:** FCP7 writes lane B as its own audio track straight after lane A (only
+> when used). **Measured** on a copy of Saint Feld (scratch panel 8391, UI: Alternate
+> A/B, S01's sound pulled 1 s under S02 with a 1 s fade, Save, Render): no silence gaps,
+> film peak −1.2 dBFS; S01+S02 pair rendered two-lane vs one-lane through the same
+> path — 2.75–3.45 s +6.6 dB RMS, difference −17.9 dB RMS vs S01's own −19.2 dB (the
+> outgoing line now plays under the incoming one instead of being cut at 2.746 s).
+> Tones: both at source level across the cut on two lanes; one lane cuts the tail.
+> **To convert the owner's board** once 8199 runs this: open Saint Feld in the Editor
+> → **Alternate A/B** (Clip sound B head) → Save. Audible change: existing J-cuts that
+> overlapped on one lane (S02 under S01) now sum instead of trimming the outgoing tail.
+
+> **🎚️ 2026-09-14 — Audio tracks in the Editor (branch `feat/audio-tracks`, UNRELEASED, not on dev).**
+> Owner: "you actually need to have multiple audio clips, like we have multiple
+> video layers" — a laugh track, a slap-bass sting and a looping bed on one film
+> had nowhere to go (A1 = each shot's own sound, A2 = ONE soundtrack), and
+> "the duplicate button is disabled when you're touching the sound/music area".
+> **Model:** `edit.audio_tracks = [{id, name, muted, gain, strips: [{id, path,
+> start, end, film_start, duration, gain, muted, locked, title, afx}]}]`; `afx`
+> is the same envelope clip sound and the bed carry; strip × track faders
+> multiply it (`track_strip_gain_points`). Same-track overlap is an error
+> (`audio_track_strips_overlap`), different tracks mix. Absent = none: old
+> edits normalise, digest and build the graph byte-identically (tested).
+> **Render:** each audible strip is a `-vn -i` after the overlays, atrim →
+> volume → aresample → adelay (samples) → apad → atrim, all `amix`ed under the
+> one `asoftclip`. Measured on a cloned 15-clip board through the UI: a bed with
+> a 1.5 s fade rose −14.4 → −8.8 → −6.5 → −4.8 dB max over a −22.7 dB
+> clips-only floor, its Duplicate at 17.08 s carried its own fade, `mix_peak`
+> 0.767 unlimited. Synthetic tones: source level exact (−27.1 / −27.1 dB),
+> half gain −6.0 dB, silence −91 dB outside the strips.
+> **Export:** one FCP7 audio track per A3/A4…, level keyframes, mutes disabled;
+> AE layers named `<track> · <title>`. **UI:** lanes + heads (name, M, level, ×),
+> "+ Add audio track", a Sound pool source (film `audio/` + OUTPUT sounds), ♪ on
+> video rows for sound only, drop on a lane or the dashed row (new track),
+> "Add sound file…" (hardlinked into the film's `audio/` when outside OUTPUT),
+> drag within/between tracks, trims, splits, fades, points, snapping, mute, lock,
+> multi-select, undo/redo, inspector, right-click. **Duplicate on sound:** a
+> track strip copies right after itself on its track; the A2 bed and an A1
+> clip's sound copy onto the first track with room (else a new one); a retimed
+> clip's sound and a bed of unknown length say why. Tests: `test_audio_tracks`
+> (35, incl. a real ffmpeg render and node-run client model).
+> **Found, not fixed (outside this change):** the Editor's save and backup
+> callers never pass `transitions` to `sbeSaveBody`, which writes
+> `transitions: []` from `state.transitions || []` — a pressed Save looks like
+> it drops every transition. Needs its own check and fix.
+
> **🚀 2026-09-13 — v4.13.0 ships: "the editor you already know".** Owner:
> "ship everything". Promoted dev's whole tree (5a1675a) onto origin/main by
> read-tree: the Editor clip bar + multi-select + right-click + gap audit
@@ -14,6 +240,8 @@
> a scratch panel: all seven tabs, Editor on a cloned 13-clip board with the
> clip bar, Docs, One Shot composer, zero console errors. From-zero install
> NOT re-run (6 GB free disk); the change set is panel code and webapp only.
+> Pinokio Official Update (covers 4.12.4 + 4.13.0, hero image from the car
+> wash film + Editor and Docs screenshots): https://pinokio.co/posts/01m2dh42thptx8ggqcax8k7484
> **📖 2026-09-13 — Docs inside the panel, and one table for every shortcut.**
> A **Docs** button beside the settings gear (and `?` anywhere) opens a
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index 02b7321..cac47a3 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -2961,6 +2961,66 @@ def _h3_turbo_asset(key: str | None = None) -> dict:
"sha256": H3_TURBO_ASSET_SHA256, "bytes": H3_TURBO_ASSET_BYTES}
+def _h3_turbo_fetch_embedder(target_dir, push_log, runner=None) -> bool:
+ """Fetch Turbo's adaLN companion (H3_TURBO_EMBEDDER_FILE, ~63 MB) with the
+ H3 pack's own `scripts/fetch_time_embedder.py`, when the resolved adapter
+ carries adaLN pairs and the file is not already there.
+
+ Best-effort by design: the adapter works without it (208 of 259 pairs),
+ so a failure here is logged loudly and the render log repeats it — it
+ never fails the adapter download. Returns True when the file is present
+ afterwards (or was never needed)."""
+ import subprocess
+ target_dir = Path(target_dir)
+ target = target_dir / H3_TURBO_EMBEDDER_FILE
+ resolved = h3_turbo_paths()
+ if not resolved.get("adaln_pairs"):
+ return True
+ if _h3_real_file(target, H3_TURBO_EMBEDDER_MIN_BYTES):
+ return True
+ python = _h3_python()
+ fetcher = H3_ROOT / "scripts" / "fetch_time_embedder.py"
+ if python is None or not fetcher.is_file():
+ push_log(f"[h3:turbo] WARNING: cannot fetch {H3_TURBO_EMBEDDER_FILE} "
+ f"(H3 pack venv or {fetcher.name} missing) — Turbo's "
+ f"{resolved['adaln_pairs']} adaLN pairs will be skipped")
+ return False
+ env = dict(os.environ)
+ hf_token = _active_hf_token()
+ if hf_token:
+ env["HF_TOKEN"] = hf_token
+ env["HUGGING_FACE_HUB_TOKEN"] = hf_token
+ # One small index JSON goes through the hub cache; keep it inside the H3
+ # models tree instead of ~/.cache/huggingface.
+ env.setdefault("HF_HOME", str(H3_MODELS / "hf_home"))
+ env["PYTHONUNBUFFERED"] = "1"
+ tmp = target.with_name(target.name + ".partial")
+ push_log(f"[h3:turbo] fetching {H3_TURBO_EMBEDDER_FILE} (~60 MB, four "
+ f"tensors range-read from MiniMaxAI/MiniMax-H3) for the "
+ f"adapter's {resolved['adaln_pairs']} adaLN pairs…")
+ try:
+ target_dir.mkdir(parents=True, exist_ok=True)
+ proc = (runner or subprocess.run)(
+ [str(python), str(fetcher), "--out", str(tmp)],
+ capture_output=True, text=True, env=env, timeout=1800)
+ if proc.returncode != 0:
+ raise RuntimeError((proc.stderr or proc.stdout or "")[-300:].strip()
+ or f"exit {proc.returncode}")
+ if not _h3_real_file(tmp, H3_TURBO_EMBEDDER_MIN_BYTES):
+ raise RuntimeError("fetch wrote no usable file")
+ tmp.replace(target)
+ except Exception as e: # noqa: BLE001
+ try:
+ tmp.unlink()
+ except OSError:
+ pass
+ push_log(f"[h3:turbo] WARNING: {H3_TURBO_EMBEDDER_FILE} fetch failed "
+ f"({e}) — Turbo still works, but its adaLN pairs are skipped")
+ return False
+ push_log(f"[h3:turbo] adaLN companion installed → {target}")
+ return True
+
+
def _h3_turbo_download_bg(target_dir, push_log, asset: dict | None = None) -> None:
"""Stream the digest-pinned v1.0 repack release asset into the H3 pack."""
import urllib.request
@@ -2972,6 +3032,7 @@ def _h3_turbo_download_bg(target_dir, push_log, asset: dict | None = None) -> No
target_dir.mkdir(parents=True, exist_ok=True)
target = target_dir / asset['file']
if target.is_file():
+ _h3_turbo_fetch_embedder(target_dir, push_log)
_set_h3_turbo_dl(status="done", mb=total_mb, total_mb=total_mb,
error=None)
return
@@ -3008,9 +3069,10 @@ def _h3_turbo_download_bg(target_dir, push_log, asset: dict | None = None) -> No
raise RuntimeError("checksum mismatch (download corrupt) — "
"please retry")
tmp.replace(target)
+ push_log(f"[h3:turbo] adapter installed → {target}")
+ _h3_turbo_fetch_embedder(target_dir, push_log)
_set_h3_turbo_dl(status="done", mb=total_mb, total_mb=total_mb,
error=None)
- push_log(f"[h3:turbo] adapter installed → {target}")
except Exception as e: # noqa: BLE001
if tmp is not None:
try:
@@ -3022,7 +3084,7 @@ def _h3_turbo_download_bg(target_dir, push_log, asset: dict | None = None) -> No
push_log(f"[h3:turbo] FAILED: {e}")
-def _h3_install_turbo(push_log, download_fn=None) -> dict:
+def _h3_install_turbo(push_log, download_fn=None, embedder_fn=None) -> dict:
"""Fetch the digest-pinned runner-layout Turbo adapter on demand.
The v1.0 repack is a published release asset with a pinned SHA-256
@@ -3045,6 +3107,28 @@ def _h3_install_turbo(push_log, download_fn=None) -> dict:
"clone — it keeps every weight already on disk."}
target = _h3_turbo_dir()
if any((target / f).is_file() for f, _v, _fb in H3_TURBO_LORA_CANDIDATES):
+ # The adapter is here; an install from before the adaLN companion came
+ # back still lacks it. Fetch just that (~60 MB) instead of saying
+ # "installed" over an adapter that is silently missing 51 pairs.
+ if h3_turbo_adaln_state() == "no_embedder":
+ with _h3_turbo_dl_lock:
+ if _h3_turbo_dl_state.get("status") == "downloading":
+ return {"ok": False,
+ "error": "a Turbo download is already active"}
+ _h3_turbo_dl_state.update(status="downloading", mb=0,
+ total_mb=60, error=None)
+
+ def _embedder_only():
+ ok = (embedder_fn or _h3_turbo_fetch_embedder)(target, push_log)
+ _set_h3_turbo_dl(status="done" if ok else "error", mb=60,
+ total_mb=60,
+ error=None if ok else
+ "adaLN companion fetch failed (see log)")
+
+ threading.Thread(target=_embedder_only, daemon=True,
+ name="h3-turbo-embedder").start()
+ return {"ok": True, "started": True, "already_installed": True,
+ "embedder_only": True, "dir": str(target)}
return {"ok": True, "started": False, "already_installed": True,
"dir": str(target)}
with _h3_turbo_dl_lock:
@@ -7775,6 +7859,17 @@ H3_TURBO_DOWNLOAD_GB = 0.8 # the v4 adapter is 779,849,816 bytes
# short file that loads far enough to fail 30 s into a render, which is exactly
# the failure mode the H3-vanish lesson says to catch at status time instead.
H3_TURBO_LORA_MIN_BYTES = 600 * 1024 * 1024
+# The adaLN companion. larryvrh's adapters carry 51 adaLN pairs (50 blocks +
+# the final layer) trained against the ORIGINAL 2688-d timestep embedding,
+# which the pruned DiT replaced with a 64-d curve — so the runner can only
+# wrap the other 208 pairs, and applies these 51 by folding their exact delta
+# into the modulation cache, given the upstream `time_embedder` tensors
+# (`--lora-adaln`). Four tensors, 63 MB, range-read out of the 66 GB MiniMax
+# release by the pack's own scripts/fetch_time_embedder.py. Without it the
+# 51 pairs are dropped: the 2026-08-14 LightX2V switch removed the flag, and
+# v4 came back without it (Codex audit 2026-09-16, finding 2).
+H3_TURBO_EMBEDDER_FILE = "upstream_time_embedder.safetensors"
+H3_TURBO_EMBEDDER_MIN_BYTES = 32 * 1024 * 1024
# Forwards Turbo runs, whatever shape the render asks for. Turbo ALWAYS runs 3
# forwards, so the saving depends entirely on how many forwards the render would
# otherwise have run — and on the fixed cost (staged loads, prompt + adaLN cache,
@@ -8095,6 +8190,17 @@ H3_TIER_WIDE_DRAFT_NOTE = (
# 2.05× a 5 s window rather than 2.0×, and it is why the estimates below are not
# simply proportional to duration.
H3_STEPS_DEFAULT = 9 # sigma POINTS; the runner does points-1 forwards
+# Per-CANVAS Auto sampler depth, in sigma points (forwards = points - 1). A cell
+# runs max(its length's steps, its canvas's steps), so dense-10s (16) is never
+# lowered by a canvas.
+# High 1024x576: owner ruling 2026-09-16 — a matched gym A/B (same seed, still and
+# prompt) at 15 forwards was clearly better than at 8, whose face was blurry.
+# 1024x576 x 124f is 22.9k packed rows, ~1.8x the ~13k envelope where 8 forwards
+# was validated (round-1 audit, notes/h3-review/FINDINGS.md §1).
+H3_HIGH_STEPS = 16
+# Native 1344x768 (40k rows) is presumed under-stepped too, but a Native-15 A/B is
+# still pending. Flip this ONE constant to 16 when it lands.
+H3_NATIVE_STEPS = H3_STEPS_DEFAULT
H3_ROWS_REF = 22923 # measured packed rows at the reference canvas
H3_ROWS_AUDIO = 500 # rows that don't scale with the canvas
H3_REF_W, H3_REF_H, H3_REF_FRAMES = 1024, 576, 124
@@ -8264,12 +8370,16 @@ def _fmt_eta(minutes: float) -> str:
# exact canvas" vs "estimated for this shape"). The model agrees with every one
# of these to within a minute, which is the point: these are a regression guard
# on the model as much as they are the numbers we print.
-H3_MEASURED_ETA: dict[tuple[str, str, bool], tuple[float, str]] = {
- ("draft", "3s", False): (3.0, "~3 min"),
- ("standard", "5s", False): (9.1, "~9 min"),
- ("standard", "10s", False): (17.1, "~17 min"),
- ("standard", "15s", False): (26.6, "~27 min · batch"),
- ("standard", "10s_dense", False): (36.2, "~36 min · batch"),
+# Each entry also records the FORWARDS PER WINDOW it was measured at. A cell only
+# prints a measurement taken at its own sampler depth: when a canvas's Auto step
+# count moves (High 8 -> 15 forwards, 2026-09-16), its old wall clock must stop
+# being shown as "measured" and the model prices the new depth instead.
+H3_MEASURED_ETA: dict[tuple[str, str, bool], tuple[float, str, int]] = {
+ ("draft", "3s", False): (3.0, "~3 min", 8),
+ ("standard", "5s", False): (9.1, "~9 min", 8),
+ ("standard", "10s", False): (17.1, "~17 min", 8),
+ ("standard", "15s", False): (26.6, "~27 min · batch", 8),
+ ("standard", "10s_dense", False): (36.2, "~36 min · batch", 15),
# These Turbo measurements belong to the RETIRED ckpt500-EMA adapter and
# remain documented in docs/STATE.md as historical evidence. Do not put
# them in this active table: LightX2V v1.0 passed visual review, but has no
@@ -8289,8 +8399,8 @@ H3_MEASURED_ETA: dict[tuple[str, str, bool], tuple[float, str]] = {
# Note the Turbo forwards are slightly SLOWER per forward than the
# 9-step ones (331 vs 315 s) — small enough to ignore in the model,
# large enough that the measurement is the number we print.
- ("high", "5s", False): (18.8, "~19 min"),
- ("native", "5s", False): (44.85, "~45 min · batch"),
+ ("high", "5s", False): (18.8, "~19 min", 8),
+ ("native", "5s", False): (44.85, "~45 min · batch", 8),
}
@@ -8337,8 +8447,10 @@ def _h3_qualities() -> dict[str, dict]:
"width": 1024, "height": 576,
"blurb": "True 16:9 — the only canvas that exports to 720p as a "
"pure 1.25× scale with no bars, and it resolves face "
- "detail 768×448 cannot. The recommended delivery canvas: "
- "Native is sharper still, but costs more and needs bars.",
+ "detail 768×448 cannot. Auto runs 15 forwards here, not 8: "
+ "at 8 faces in motion come out soft. The recommended "
+ "delivery canvas.",
+ "steps": H3_HIGH_STEPS,
"offered": True,
},
# H3's OWN canvas — what `resolve_canvas_size` picks for itself at the
@@ -8357,6 +8469,7 @@ def _h3_qualities() -> dict[str, dict]:
"detail H3 can produce. 7:4, so an export adds thin bars "
"top and bottom. Worth it with Turbo on; a long wait "
"without.",
+ "steps": H3_NATIVE_STEPS,
"offered": True,
},
# Off by default, behind an env flag, for the same reason the dense pass
@@ -8380,6 +8493,8 @@ def _h3_qualities() -> dict[str, dict]:
q["spec"] = f"{q['canvas']} · {q['aspect']}"
q.setdefault("draft", False)
q.setdefault("note", "")
+ # 0 = no canvas opinion; the length's own count applies.
+ q.setdefault("steps", 0)
return out
@@ -8478,8 +8593,12 @@ def _build_h3_tiers() -> dict[str, dict]:
windows = max(1, int(ln["windows"]))
window_frames = int(ln["window_frames"])
frames = int(ln["frames"])
- steps = int(ln["steps"])
- forwards = windows * max(1, steps - 1)
+ # The deeper of the two axes wins: a canvas can ask for more
+ # forwards (High), a length can too (dense 10 s); neither lowers
+ # the other.
+ steps = max(int(ln["steps"]), int(q.get("steps") or 0))
+ win_fwd = max(1, steps - 1)
+ forwards = windows * win_fwd
eta_min = h3_estimate_minutes(w, h, window_frames, windows,
max(1, steps - 1))
turbo_min = h3_estimate_minutes(w, h, window_frames, windows,
@@ -8487,13 +8606,19 @@ def _build_h3_tiers() -> dict[str, dict]:
# Turbo removes forwards; it can never make a shape slower.
turbo_min = min(eta_min, turbo_min)
eta, eta_measured = _fmt_eta(eta_min), False
+ # Receipts are M4 Max wall clocks. The model above already carries
+ # this Mac's factor, so a receipt must carry it too or an M4 Pro is
+ # promised the M4 Max number exactly where a measurement exists.
+ hw = _hw_speed_factor("h3")
hit = H3_MEASURED_ETA.get((q["key"], ln["key"], False))
- if hit:
- eta_min, eta, eta_measured = hit[0], hit[1], True
+ if hit and int(hit[2]) == win_fwd:
+ eta_min, eta_measured = hit[0] * hw, True
+ eta = hit[1] if hw == 1.0 else _fmt_eta(eta_min)
turbo_eta, turbo_measured = _fmt_eta(turbo_min), False
hit = H3_MEASURED_ETA.get((q["key"], ln["key"], True))
- if hit:
- turbo_min, turbo_eta, turbo_measured = hit[0], hit[1], True
+ if hit and int(hit[2]) == H3_TURBO_FORWARDS:
+ turbo_min, turbo_measured = hit[0] * hw, True
+ turbo_eta = hit[1] if hw == 1.0 else _fmt_eta(turbo_min)
spec = f"{w}×{h} · {frames}f"
if windows > 1:
spec += f" · {windows}×5s"
@@ -8527,9 +8652,11 @@ def _build_h3_tiers() -> dict[str, dict]:
# The two model outputs the browser needs to price a shape the
# server didn't pre-compute — a pinned Steps override. Same
# function, same numbers, no second cost model in JS.
+ # Scaled by this Mac's factor, as h3_estimate_minutes is, so a
+ # pinned count prices on the same clock as Auto.
"per_forward_sec": round(
- _h3_forward_seconds(_h3_packed_rows(w, h, window_frames)), 2),
- "fixed_sec": round(_h3_fixed_seconds(w, h, window_frames), 2),
+ _h3_forward_seconds(_h3_packed_rows(w, h, window_frames)) * hw, 2),
+ "fixed_sec": round(_h3_fixed_seconds(w, h, window_frames) * hw, 2),
"packed_rows": _h3_packed_rows(w, h, window_frames),
"blurb": f"{q['blurb']} {ln['blurb']}",
# The honest artefact warnings, joined: a Draft 10 s clip owes
@@ -10220,6 +10347,7 @@ def h3_turbo_paths() -> dict:
+ H3_TURBO_FALLBACK_LORA_FILE
+ ")"
]
+ embedder = directory / H3_TURBO_EMBEDDER_FILE
return {
"dir": directory,
"lora": lora,
@@ -10227,9 +10355,76 @@ def h3_turbo_paths() -> dict:
"fallback": fallback,
"missing": missing,
"files_ok": lora is not None,
+ # Read from the adapter's own header, never assumed from its name.
+ "adaln_pairs": h3_lora_adaln_pairs(lora) if lora is not None else 0,
+ "embedder": (embedder if _h3_real_file(embedder, H3_TURBO_EMBEDDER_MIN_BYTES)
+ else None),
}
+_H3_ADALN_PAIRS_CACHE: dict[tuple, int] = {}
+
+
+def h3_lora_adaln_pairs(path: Path | str | None) -> int:
+ """How many adaLN LoRA pairs (`*.adaln_proj.linear.lora_A/B`) a
+ safetensors adapter carries, from its JSON header alone — no tensor is
+ read, so this is cheap enough for /status. 0 for anything unreadable,
+ which is the safe answer: no `--lora-adaln` is emitted for it."""
+ if path is None:
+ return 0
+ path = Path(path)
+ try:
+ st = path.stat()
+ except OSError:
+ return 0
+ key = (str(path), st.st_mtime_ns, st.st_size)
+ if key in _H3_ADALN_PAIRS_CACHE:
+ return _H3_ADALN_PAIRS_CACHE[key]
+ count = 0
+ try:
+ with open(path, "rb") as fh:
+ head = fh.read(8)
+ if len(head) == 8:
+ size = int.from_bytes(head, "little")
+ if 0 < size <= 100 * 1024 * 1024 and size <= st.st_size - 8:
+ header = json.loads(fh.read(size))
+ if isinstance(header, dict):
+ a = {k[:-len(".lora_A.weight")] for k in header
+ if k.endswith("adaln_proj.linear.lora_A.weight")}
+ b = {k[:-len(".lora_B.weight")] for k in header
+ if k.endswith("adaln_proj.linear.lora_B.weight")}
+ count = len(a & b)
+ except (OSError, ValueError, UnicodeDecodeError):
+ count = 0
+ if len(_H3_ADALN_PAIRS_CACHE) > 64:
+ _H3_ADALN_PAIRS_CACHE.clear()
+ _H3_ADALN_PAIRS_CACHE[key] = count
+ return count
+
+
+def h3_supports_lora_adaln() -> bool:
+ """Whether the INSTALLED runner accepts `--lora-adaln` (every runner with
+ `--lora` does today; probed anyway, same as every other runner flag)."""
+ return _h3_runner_has_flag("--lora-adaln")
+
+
+def h3_turbo_adaln_state(paths: dict | None = None) -> str:
+ """What happens to the adapter's adaLN pairs on this install:
+ none — the adapter has none (LightX2V repacks); nothing to do
+ absorbed — companion + runner support present: `--lora-adaln` rides
+ no_embedder — pairs present, companion file missing: they are DROPPED
+ runner_old — pairs + companion present, runner lacks the flag
+ """
+ resolved = paths or h3_turbo_paths()
+ if not resolved.get("adaln_pairs"):
+ return "none"
+ if resolved.get("embedder") is None:
+ return "no_embedder"
+ if not h3_supports_lora_adaln():
+ return "runner_old"
+ return "absorbed"
+
+
def h3_turbo_steps(paths: dict | None = None) -> int:
"""Sigma points for the Turbo adapter that will actually run: 7 (six
forwards) for v4-600 EMA, 4 for the 4-step adapters. Anything that says
@@ -10238,16 +10433,25 @@ def h3_turbo_steps(paths: dict | None = None) -> int:
return int(H3_TURBO_VERSION_STEPS.get(resolved.get("version") or "", H3_TURBO_STEPS))
+# Forwards the tier table's Turbo cells are currently priced at.
+_H3_TURBO_PRICED_FWD = H3_TURBO_FORWARDS
+
+
def _h3_retune_turbo_estimates() -> None:
"""The tier table priced Turbo at import with the 4-step forwards, before
the adapter directory could be resolved. Re-price every cell for the
adapter that is actually installed — six forwards for v4 — so the chips,
the Speed pills and the Storyboard estimate say what will happen."""
+ global _H3_TURBO_PRICED_FWD
try:
fwd = max(1, h3_turbo_steps() - 1)
except Exception: # noqa: BLE001
return
- if fwd == H3_TURBO_FORWARDS:
+ # Called at import AND from h3_turbo_status(), so an in-app install (or a
+ # removal that falls back to another adapter) re-prices a running panel.
+ # Compare against what the table is priced at NOW, not the import default,
+ # or a v4 → 4-step change could never be priced back.
+ if fwd == _H3_TURBO_PRICED_FWD:
return
for cell in H3_TIERS.values():
try:
@@ -10258,8 +10462,10 @@ def _h3_retune_turbo_estimates() -> None:
cell["turbo_min"] = round(tm, 2)
cell["turbo_eta"] = _fmt_eta(tm)
cell["turbo_forwards"] = windows * fwd
+ cell["turbo_measured"] = False
except Exception: # noqa: BLE001
continue
+ _H3_TURBO_PRICED_FWD = fwd
def h3_turbo_lora_spec(paths: dict | None = None) -> str:
@@ -10271,8 +10477,17 @@ def h3_turbo_lora_spec(paths: dict | None = None) -> str:
def h3_turbo_argv(paths: dict | None = None) -> list[str]:
- """The exact runner argv fragment, kept executable as a contract test."""
- return ["--lora", h3_turbo_lora_spec(paths)]
+ """The exact runner argv fragment, kept executable as a contract test.
+
+ `--lora-adaln` rides only when the adapter really carries adaLN pairs
+ (read from its header) AND the companion embedder is on disk AND the
+ runner takes the flag. The runner absorbs adaLN pairs for every adapter
+ in the `--lora` stack, and one without any is a logged no-op."""
+ resolved = paths or h3_turbo_paths()
+ argv = ["--lora", h3_turbo_lora_spec(resolved)]
+ if h3_turbo_adaln_state(resolved) == "absorbed":
+ argv += ["--lora-adaln", str(resolved["embedder"])]
+ return argv
def h3_turbo_status() -> dict:
@@ -10286,6 +10501,8 @@ def h3_turbo_status() -> dict:
supported = h3_supports_lora()
paths = h3_turbo_paths()
downloaded = paths["files_ok"]
+ # Cheap no-op unless the resolved adapter changed since the last price.
+ _h3_retune_turbo_estimates()
if not supported:
reason = "runner_too_old"
elif not downloaded:
@@ -10316,6 +10533,10 @@ def h3_turbo_status() -> dict:
"missing": paths["missing"],
"note": h3_turbo_note(paths),
"label": "Turbo",
+ "adaln": {"pairs": paths.get("adaln_pairs", 0),
+ "embedder": (str(paths["embedder"])
+ if paths.get("embedder") else None),
+ "state": h3_turbo_adaln_state(paths)},
}
@@ -10809,11 +11030,23 @@ def _h3_lora_effective_alpha(path: Path, header: dict,
dimension. Returns (effective_scale, evidence) or (None, "") when the file
declares no per-module alpha at all — the common, already-handled case.
"""
+ ratios = _h3_lora_alpha_ratios(path, header, buf_start)
+ if not ratios:
+ return None, ""
+ lo, hi = min(ratios), max(ratios)
+ ev = (f"{len(ratios)} module(s), alpha/rank "
+ + (f"{lo:.4g}" if abs(hi - lo) < 1e-6 else f"{lo:.4g}–{hi:.4g}"))
+ return (hi if abs(hi - lo) < 1e-6 else max(ratios, key=lambda r: abs(r - 1.0))), ev
+
+
+def _h3_lora_alpha_ratios(path: Path, header: dict, buf_start: int) -> list[float]:
+ """alpha/rank for every module whose `.alpha` scalar can be read from a
+ few bytes (header offsets; no tensor load). [] when the file has none."""
_WIDTH = {"F64": 8, "F32": 4, "F16": 2, "BF16": 2, "I64": 8, "I32": 4}
alpha_keys = [k for k in header
if k != "__metadata__" and k.endswith(".alpha")]
if not alpha_keys:
- return None, ""
+ return []
def _rank_for(module: str) -> int | None:
ent = header.get(module + _H3_LORA_A_SUFFIX) or {}
@@ -10851,12 +11084,7 @@ def _h3_lora_effective_alpha(path: Path, header: dict,
rank = _rank_for(k[: -len(".alpha")])
if rank:
ratios.append(float(val) / float(rank))
- if not ratios:
- return None, ""
- lo, hi = min(ratios), max(ratios)
- ev = (f"{len(ratios)} module(s), alpha/rank "
- + (f"{lo:.4g}" if abs(hi - lo) < 1e-6 else f"{lo:.4g}–{hi:.4g}"))
- return (hi if abs(hi - lo) < 1e-6 else max(ratios, key=lambda r: abs(r - 1.0))), ev
+ return ratios
# Metadata keys an exporter uses to say "the PEFT alpha/rank multiplier is
@@ -10902,6 +11130,18 @@ def _h3_lora_scale_report(path: Path, header: dict, buf_start: int) -> dict:
if not isinstance(meta, dict):
meta = {}
+ if str(meta.get("converted_by") or "") == "phosphene" and (
+ meta.get("converted_from") == "kohya"
+ or meta.get("peft_scale_folded_into_B") is not None):
+ # Our own converters fold alpha/rank into lora_B per module. That
+ # includes kohya files converted before they wrote the marker, which
+ # still carry the trainer's `ss_network_alpha`.
+ return {"strength": 1.0, "source": "folded",
+ "evidence": (f"converted by Phosphene from "
+ f"{meta.get('converted_from') or 'per-module alpha'}: "
+ f"alpha/rank {meta.get('alpha_over_rank') or '?'} is "
+ f"already folded into lora_B, so 1.0 is the correct "
+ f"strength")}
for key in _H3_LORA_FOLDED_SCALE_KEYS:
raw = meta.get(key)
if raw is None:
@@ -11183,6 +11423,11 @@ def _h3_lora_convert_kohya(path: Path) -> dict:
meta.update({
"converted_from": "kohya",
"converted_by": "phosphene",
+ # The canonical "load me at 1.0" claim _h3_lora_scale_report reads.
+ # Without it the trainer's own `ss_network_alpha` (kept above as
+ # history) was divided by the rank a SECOND time at import.
+ "peft_scale_folded_into_B": (f"{quotients[0]:g}" if len(quotients) == 1
+ else "per-module"),
"alpha_over_rank": ",".join(f"{v:g}" for v in quotients),
"converted_modules": str(len(out) // 2),
"dropped_modules": str(len(dropped)),
@@ -11221,6 +11466,14 @@ def _h3_lora_prepare(path: Path) -> dict:
a bare-layout file is inspected and returned untouched."""
info = _h3_lora_layout(path)
if info["ok"]:
+ folded = _h3_lora_fold_mixed_alphas(path)
+ if folded:
+ push(f"[h3:lora] {path.name}: per-module alpha/rank "
+ f"{folded['lo']:g}–{folded['hi']:g} folded into lora_B for "
+ f"{folded['modules']} modules (one strength cannot represent "
+ f"them) — load at 1.0")
+ return {"layout": "bare", "converted": True, "prefix": "",
+ "pairs": info["pairs"]}
return {"layout": "bare", "converted": False, "prefix": "",
"pairs": info["pairs"]}
if not info["convertible"]:
@@ -11248,10 +11501,82 @@ def _h3_lora_prepare(path: Path) -> dict:
n = _h3_lora_strip_prefix(path, info["prefix"])
push(f"[h3:lora] {path.name}: stripped `{info['prefix']}` from {n} keys "
f"(ComfyUI repack → bare layout; tensors untouched)")
+ folded = _h3_lora_fold_mixed_alphas(path)
+ if folded:
+ push(f"[h3:lora] {path.name}: per-module alpha/rank "
+ f"{folded['lo']:g}–{folded['hi']:g} folded into lora_B for "
+ f"{folded['modules']} modules — load at 1.0")
return {"layout": "comfyui", "converted": True, "prefix": info["prefix"],
"pairs": info["pairs"]}
+def _h3_lora_fold_mixed_alphas(path: Path) -> dict | None:
+ """Fold per-module `.alpha` scalars into lora_B when they DISAGREE.
+
+ The runner applies one strength per adapter and ignores `.alpha`. When
+ every module has the same alpha/rank that one strength is exact, and the
+ scale report recommends it (nothing to rewrite). When they differ, no
+ single strength is right — the old report picked the ratio farthest from
+ 1.0 and applied it to every module. Here each B takes its own quotient,
+ the `.alpha` tensors are dropped, and the file says it is folded, so it
+ loads at 1.0 as trained. Returns None when there is nothing to fold."""
+ header, buf_start = _safetensors_header(path)
+ alpha_keys = [k for k in header if k != "__metadata__" and k.endswith(".alpha")]
+ if not alpha_keys:
+ return None
+ ratios = _h3_lora_alpha_ratios(path, header, buf_start)
+ if not ratios or (max(ratios) - min(ratios)) < 1e-6:
+ return None # uniform (or unreadable): header only
+ import mlx.core as mx
+ tensors = mx.load(str(path))
+ out: dict = {}
+ quotients: list[float] = []
+ for k, v in tensors.items():
+ if k.endswith(".alpha"):
+ continue
+ out[k] = v
+ for k in alpha_keys:
+ module = k[: -len(".alpha")]
+ a = tensors.get(module + _H3_LORA_A_SUFFIX)
+ b = tensors.get(module + _H3_LORA_B_SUFFIX)
+ if a is None or b is None:
+ continue
+ rank = int(a.shape[0])
+ q = float(tensors[k].astype(mx.float32).item()) / rank if rank else 1.0
+ quotients.append(q)
+ if abs(q - 1.0) > 1e-6:
+ out[module + _H3_LORA_B_SUFFIX] = (b.astype(mx.float32) * q).astype(b.dtype)
+ if not quotients or (max(quotients) - min(quotients)) < 1e-6:
+ del tensors, out
+ return None # uniform: the strength is exact
+ meta = {str(k): str(v) for k, v in (header.get("__metadata__") or {}).items()}
+ meta.update({
+ "converted_by": "phosphene",
+ "converted_from": meta.get("converted_from") or "per-module-alpha",
+ "peft_scale_folded_into_B": "per-module",
+ "alpha_over_rank": ",".join(f"{v:g}" for v in sorted(set(round(x, 6) for x in quotients))),
+ })
+ tmp = path.with_name(path.stem + ".alpha-tmp.safetensors")
+ pairs_before = _h3_lora_layout(path)["pairs"]
+ try:
+ mx.save_safetensors(str(tmp), out, metadata=meta)
+ check = _h3_lora_layout(tmp)
+ if check["layout"] != "bare" or check["pairs"] != pairs_before:
+ raise RuntimeError(
+ f"post-fold check failed (layout={check['layout']}, "
+ f"pairs={check['pairs']}) — leaving the original untouched.")
+ os.replace(tmp, path)
+ except Exception:
+ try:
+ tmp.unlink()
+ except OSError:
+ pass
+ raise
+ finally:
+ del tensors, out
+ return {"modules": len(quotients), "lo": min(quotients), "hi": max(quotients)}
+
+
# Layout probes are cheap but not free, and h3_status() runs on every /status
# tick. Cache on (path, mtime_ns, size) so an unchanged file is classified
# once per edit rather than once per poll.
@@ -11323,7 +11648,12 @@ def list_h3_user_loras() -> list[dict]:
"size_bytes": size_bytes,
"lane": "h3",
"trigger_words": list(meta.get("trigger_words") or []),
- "recommended_strength": float(meta.get("recommended_strength") or 1.0),
+ # A kohya file is always converted with alpha/rank folded into
+ # lora_B, so 1.0 is right. Imports before 2026-09-16 saved the
+ # trainer's alpha/rank here as well — a double scale — and are
+ # corrected on read rather than trusted.
+ "recommended_strength": (1.0 if meta.get("lora_layout") == "kohya"
+ else float(meta.get("recommended_strength") or 1.0)),
"preview_url": preview_url,
"preview_type": preview_type,
"base_model": meta.get("base_model") or "MiniMax H3",
@@ -13941,28 +14271,111 @@ def _video_has_audio(path: str) -> bool:
return False
-def _mux_audio_from(video_path: Path, audio_source: str) -> bool:
- """Copy the source clip's audio track onto `video_path` (video stream
- untouched). The whole point of the H3 → LTX ×2 lane: H3 wrote the
- dialogue and the sound; the upscaler must not throw them away."""
- if not _video_has_audio(audio_source):
+def ltx_grid_frames_up(frames: int) -> int:
+ """The smallest LTX frame count (1 + 8k, at least 9) that holds `frames`."""
+ frames = max(1, int(frames))
+ return max(9, 1 + 8 * (-(-(frames - 1) // 8)))
+
+
+# The longest clip the ×2 lane renders whole unless the form asks for more:
+# a 5 s H3 High render (124 frames) on its LTX grid (129). Measured there.
+UPSCALE_FULL_CLIP_FRAMES = 129
+
+
+def upscale_frame_plan(src_frames: int, form_frames=None) -> tuple[int, int]:
+ """(frames the ×2 delivers, frames the model renders) for a source clip.
+
+ Delivered = the source's own count, up to the ceiling; rendered = the
+ next 1+8k at or above it (the held tail is cut off afterwards). A clip
+ past the ceiling is covered from its start, on a grid that fits."""
+ try:
+ asked = int(form_frames or 0)
+ except (TypeError, ValueError):
+ asked = 0
+ out_frames = int(src_frames or 0) or asked or 49
+ ceiling = max(UPSCALE_FULL_CLIP_FRAMES, asked)
+ out_frames = min(out_frames, ceiling)
+ grid = ltx_grid_frames_up(out_frames)
+ if grid > ceiling:
+ grid = max(9, 1 + 8 * ((ceiling - 1) // 8))
+ out_frames = grid
+ return out_frames, grid
+
+
+def _upscale_hold_tail_cmd(src: str, out: str, frames: int, grid: int) -> list[str]:
+ """ffmpeg argv: `src` with its last frame held until it is `grid` frames.
+
+ Lossless RGB (libx264rgb, crf 0), so the loader reads the clip's own
+ pixels for frames 0..frames-1 and the held copies after them."""
+ return [str(FFMPEG), "-y", "-loglevel", "error", "-i", str(src),
+ "-map", "0:v:0", "-an",
+ "-vf", f"tpad=stop_mode=clone:stop={max(0, grid - frames)}",
+ "-frames:v", str(grid),
+ "-c:v", "libx264rgb", "-crf", "0", "-preset", "veryfast",
+ "-pix_fmt", "rgb24", "-f", "mp4", str(out)]
+
+
+def _upscale_finish_cmd(video: str, audio_source: str | None, out: str, *,
+ frames: int, fps: float, trim: bool,
+ codec: dict[str, str]) -> list[str]:
+ """ffmpeg argv that makes the upscale exactly `frames` long, sound included.
+
+ `trim`: the render ran on a longer 1+8k grid, so the held tail is cut
+ (a re-encode — a stream copy cannot cut B-frame H.264 on an exact frame).
+ Without it the video is copied untouched. The sound is the source's,
+ padded then cut to frames/fps: never `-shortest`, which drops the last
+ video frame whenever the audio ends first."""
+ cmd = [str(FFMPEG), "-y", "-loglevel", "error", "-i", str(video)]
+ if audio_source:
+ cmd += ["-i", str(audio_source)]
+ cmd += ["-map", "0:v:0"]
+ if audio_source:
+ cmd += ["-map", "1:a:0"]
+ cmd += ["-frames:v", str(int(frames))]
+ if trim:
+ cmd += ["-c:v", "libx264", "-pix_fmt", codec["pix_fmt"], "-crf", codec["crf"],
+ "-preset", "medium"]
+ else:
+ cmd += ["-c:v", "copy"]
+ if audio_source:
+ cmd += ["-af", f"apad,atrim=end={int(frames) / float(fps):.6f}",
+ "-c:a", "aac", "-b:a", "192k"]
+ else:
+ cmd += ["-an"]
+ cmd += ["-movflags", "+faststart", "-f", "mp4", str(out)]
+ return cmd
+
+
+def _upscale_finish(video_path: Path, audio_source: str, *, frames: int,
+ fps: float, trim: bool) -> bool:
+ """Bring the ×2 render back to the source clip's length and soundtrack.
+
+ Returns whether the source's audio is on the result. The whole point of
+ the H3 → LTX ×2 lane: H3 wrote the dialogue and the sound; the upscaler
+ must not throw them away, nor a single frame of the picture."""
+ has_audio = _video_has_audio(audio_source)
+ if not (has_audio or trim):
return False
tmp = video_path.with_name(video_path.stem + ".mux.mp4")
+ cmd = _upscale_finish_cmd(str(video_path), audio_source if has_audio else None,
+ str(tmp), frames=frames, fps=fps, trim=trim,
+ codec=output_codec_settings())
try:
- r = subprocess.run(
- [str(FFMPEG), "-y", "-loglevel", "error",
- "-i", str(video_path), "-i", str(audio_source),
- "-map", "0:v:0", "-map", "1:a:0", "-c:v", "copy", "-c:a", "aac",
- "-b:a", "192k", "-shortest", "-movflags", "+faststart", str(tmp)],
- capture_output=True, text=True, timeout=300)
+ r = subprocess.run(cmd, capture_output=True, text=True, timeout=900)
if r.returncode != 0 or not tmp.is_file():
- push(f"Upscale: audio mux failed ({(r.stderr or '')[-160:].strip()}); clip kept silent")
tmp.unlink(missing_ok=True)
+ if trim:
+ raise RuntimeError("Upscale ×2: could not cut the render back to "
+ f"{frames} frames: {(r.stderr or '')[-200:].strip()}")
+ push(f"Upscale: audio mux failed ({(r.stderr or '')[-160:].strip()}); clip kept silent")
return False
tmp.replace(video_path)
- return True
- except Exception as exc: # noqa: BLE001
- push(f"Upscale: audio mux failed ({exc}); clip kept silent")
+ return has_audio
+ except subprocess.TimeoutExpired:
+ tmp.unlink(missing_ok=True)
+ if trim:
+ raise RuntimeError("Upscale ×2: cutting the render back to length timed out")
+ push("Upscale: audio mux timed out; clip kept silent")
return False
@@ -21263,7 +21676,9 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,
}
prompt = override_prompt if override_prompt is not None else f("prompt", "")
- if not prompt:
+ # Upscale ×2 keeps an empty prompt: its worker falls back to the source
+ # clip's own prompt, which a generic filler here would shadow.
+ if not prompt and mode_in != "upscale":
prompt = "A cinematic atmospheric scene"
# Resolve a character token BEFORE reading the quality cell. The two
# character surfaces submit ``quality_choice`` (draft/pro/high/high720),
@@ -21454,7 +21869,7 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,
if _h3_upscale not in H3_UPSCALE_MODES:
_h3_upscale = H3_UPSCALE_DEFAULT
# Sampler depth override for an H3 render ("Steps" pills). 0 = Auto = the
- # tier's tuned count (9 → 8 forwards, the validated speed/quality point).
+ # tier's tuned count (9 points → 8 forwards; High 16 → 15 since 2026-09-16).
# The official reference recipe runs 20; wall time scales ~(steps-1)/8.
_h3_steps_raw = (f("h3_steps", "") or "").strip().lower()
if _h3_steps_raw in ("", "auto", "0"):
@@ -23604,25 +24019,51 @@ def _h3_fit_first_frame(src: Path, width: int, height: int, job_id: str) -> Path
return src
-def _h3_clip_is_complete(path: Path, started_at: float) -> bool:
- """True when the H3 output at `path` is a whole, playable clip written by
- THIS run: exists, newer than the process start, non-trivial size, and
- ffprobe (when present) reads a duration from it."""
+def _h3_clip_is_complete(path: Path, started_at: float,
+ expect_frames: int | None = None) -> bool:
+ """True when the H3 output at `path` is a whole clip written by THIS run:
+ exists, newer than the process start, non-trivial size, and ffprobe reads
+ a VIDEO stream carrying at least `expect_frames` frames.
+
+ A nonzero exit is only turned into success on this answer, so "plays for
+ a moment" is not enough: an 8-frame partial or an audio-only container
+ must stay a failure. Without ffprobe nothing can be verified, and the
+ failure stands."""
try:
st = path.stat()
except OSError:
return False
if st.st_mtime < started_at - 1 or st.st_size < 200_000:
return False
- ffprobe = shutil.which("ffprobe")
+ ffprobe = str(FFPROBE) if Path(str(FFPROBE)).is_file() else shutil.which("ffprobe")
if not ffprobe:
- return True
+ return False
try:
out = subprocess.run(
- [ffprobe, "-v", "error", "-show_entries", "format=duration",
- "-of", "default=nw=1:nk=1", str(path)],
+ [ffprobe, "-v", "error", "-select_streams", "v:0",
+ "-show_entries", "stream=codec_type,nb_frames:format=duration",
+ "-of", "json", str(path)],
capture_output=True, text=True, timeout=20)
- return out.returncode == 0 and float((out.stdout or "0").strip() or 0) > 0
+ if out.returncode != 0:
+ return False
+ info = json.loads(out.stdout or "{}")
+ streams = [x for x in (info.get("streams") or [])
+ if x.get("codec_type") == "video"]
+ if not streams:
+ return False
+ if float((info.get("format") or {}).get("duration") or 0) <= 0:
+ return False
+ if expect_frames:
+ try:
+ have = int(streams[0].get("nb_frames") or 0)
+ except (TypeError, ValueError):
+ have = 0
+ # One short is tolerated: runners before the mux fix (the public
+ # pack until it is updated) cut the last frame with `-shortest`
+ # on every clip, and #76's shutdown abort must still salvage those.
+ if have < int(expect_frames) - 1:
+ return False
+ return True
except Exception: # noqa: BLE001
return False
@@ -23639,8 +24080,13 @@ def _chain_upscale_after_h3(job: dict, p: dict, native_path: Path) -> None:
"engine": "ltx",
"upscale_source_path": str(native_path),
"keep_shot": str(p.get("keep_shot") or "1.0"),
- "seed": str(p.get("seed") if p.get("seed") not in (None, "") else "-1"),
- "prompt": "",
+ # The seed THIS render resolved, not the form's "-1".
+ "seed": str(p.get("seed_used") if p.get("seed_used") is not None
+ else (p.get("seed") if p.get("seed") not in (None, "") else "-1")),
+ # The draft's own prompt. An empty one used to be replaced by
+ # make_job's generic "A cinematic atmospheric scene", so the ×2
+ # never read the source's description.
+ "prompt": str(p.get("prompt") or ""),
"label": f"{p.get('label') or native_path.stem} · LTX ×2",
}
nxt = make_job(form)
@@ -23927,6 +24373,14 @@ def run_h3_job_inner(job: dict) -> None:
+ f". Expected under {turbo_paths['dir']} — turn Turbo off, or "
f"install {H3_TURBO_V4_FILE} (or {H3_TURBO_LORA_FILE}, or the safe "
f"folded v0.1 fallback) under {turbo_paths['dir']}.")
+ if h3_turbo_adaln_state(turbo_paths) == "no_embedder":
+ # An adapter downloaded before the adaLN companion came back.
+ # ~60 MB, once; a failure leaves the render running without the
+ # pairs, and the dispatch log below says so.
+ _h3_turbo_fetch_embedder(
+ turbo_paths["dir"], push,
+ runner=lambda *a, **kw: subprocess.run(*a, **{**kw, "timeout": 300}))
+ turbo_paths = h3_turbo_paths()
steps = h3_turbo_steps(turbo_paths)
# First-frame conditioning (Image mode). The flag landed on the runner
@@ -23940,6 +24394,18 @@ def run_h3_job_inner(job: dict) -> None:
raise RuntimeError(
"Image mode on H3 needs a reference image — pick one, or "
"switch to Text mode.")
+ # Reject unreadable images before the H3 subprocess starts — the runner
+ # also uses PIL and crashes with PIL.UnidentifiedImageError there instead
+ # of a useful message (fleet: 4 installs, v4.12.2).
+ try:
+ from PIL import Image as _PilImg
+ with _PilImg.open(Path(src)):
+ pass
+ except Exception as _pil_err:
+ raise RuntimeError(
+ f"The reference image can't be read ({_pil_err.__class__.__name__}). "
+ "Export it as a JPEG or PNG and try again."
+ ) from None
if not h3_supports_first_frame():
raise RuntimeError(
"Image mode conditions on a first frame: "
@@ -24044,6 +24510,21 @@ def run_h3_job_inner(job: dict) -> None:
"--steps", str(steps),
"--seed", str(seed),
]
+ # Codec, frozen for this job: the runner's own encode is what a Native /
+ # Off / ×2 delivery ships, so it gets the configured CRF, and the sidecar
+ # records what the encoder actually used (the runner always writes
+ # yuv420p) rather than re-reading mutable settings at the end.
+ # Never coarser than the runner's own 18: when an export pass follows, this
+ # file is its intermediate, and a web-grade CRF here would be compounded.
+ job_codec = output_codec_settings()
+ native_codec = {"crf": "18", "pix_fmt": "yuv420p", "encoder": "runner"}
+ try:
+ _native_crf = min(18, max(0, int(float(job_codec["crf"]))))
+ except (TypeError, ValueError):
+ _native_crf = 18
+ if _native_crf != 18 and _h3_runner_has_flag("--crf"):
+ cmd += ["--crf", str(_native_crf)]
+ native_codec["crf"] = str(_native_crf)
if chain_windows > 1:
# Window chaining: each window after the first is conditioned on its
# predecessor's last decoded frame, and --chain-total-frames trims the
@@ -24159,6 +24640,21 @@ def run_h3_job_inner(job: dict) -> None:
+ (f" · first frame {first_frame.name}" if first_frame else ""))
if turbo:
push(f"[h3] {h3_turbo_note(turbo_paths)}")
+ _adaln_state = h3_turbo_adaln_state(turbo_paths)
+ if _adaln_state == "absorbed":
+ push(f"[h3] Turbo adaLN: {turbo_paths['adaln_pairs']} pairs folded "
+ f"into the modulation cache (--lora-adaln)")
+ elif _adaln_state != "none":
+ # Loud, not silent: the render still runs, but without these
+ # pairs it is not the adapter its author published.
+ push(f"[h3] WARNING Turbo adaLN: this adapter's "
+ f"{turbo_paths['adaln_pairs']} adaLN pairs will be SKIPPED — "
+ + ("the companion " + H3_TURBO_EMBEDDER_FILE + " is missing "
+ "from " + str(turbo_paths['dir']) + " (re-run the Turbo "
+ "download to fetch it)"
+ if _adaln_state == "no_embedder" else
+ "the installed H3 runner has no --lora-adaln (update the "
+ "H3 pack)"))
# The shot list, in the log, in render order — so a clip whose second beat
# didn't land can be diagnosed from the log alone.
for _i, _wp in enumerate(chain_prompts, 1):
@@ -24194,6 +24690,13 @@ def run_h3_job_inner(job: dict) -> None:
window_prefix_rx = re.compile(r"^w(\d+)_")
cur_window, tot_windows = 1, max(1, chain_windows)
phase_label = "Loading H3 text encoder"
+ # The runner's own phase, unprefixed. After the last forward the runner
+ # decodes and muxes with NO further Stop-early check in that window, so
+ # progress must stop calling itself `denoise` the moment decode starts.
+ bare_phase = ""
+ _H3_POST_PHASES = ("video_vae_decode", "audio_vae_decode", "encode_mux", "stitch")
+ _decode_est = (H3_DECODE_SEC_PER_PX_FRAME * int(width) * int(height)
+ * int(window_frames) * _hw_speed_factor("h3"))
last_step, total_steps = 0, max(1, steps - 1)
try:
proc = subprocess.Popen(
@@ -24286,6 +24789,8 @@ def run_h3_job_inner(job: dict) -> None:
"text_cache_load": "Loading cached prompt embedding",
"keyframe_encode": "Encoding first frame",
"dit_load_bf16": "Loading H3 transformer (bf16)",
+ "dit_load_q8": "Loading H3 transformer (Q8)",
+ "dit_load_q4": "Loading H3 transformer (Q4)",
"adaln_cache_and_noise": "Building AdaLN cache",
"joint_denoise": "Denoising video + audio",
"video_vae_decode": "Decoding video",
@@ -24311,15 +24816,22 @@ def run_h3_job_inner(job: dict) -> None:
win_span = 87.0 / float(tot_windows)
win_base = 5.0 + win_span * (cur_window - 1)
win_tag = f"Window {cur_window}/{tot_windows} · " if tot_windows > 1 else ""
+ post = bool(last_step) and bare_phase in _H3_POST_PHASES
if last_step:
pct = win_base + win_span * (last_step / float(total_steps))
spent = elapsed if denoise_t0 is None else max(0.0, time.time() - denoise_t0)
per_step = spent / max(1, last_step)
# Remaining steps in this window, plus every step of every
- # window still to come.
- left = (total_steps - last_step) + total_steps * (tot_windows - cur_window)
- eta = max(0.0, left * per_step)
- label = f"{win_tag}{phase_label} · step {last_step} / {total_steps}"
+ # window still to come — and the decodes still owed, so the
+ # clock does not read 0 through a minutes-long VAE decode.
+ later = tot_windows - cur_window
+ left = (total_steps - last_step) + total_steps * later
+ eta = max(0.0, left * per_step
+ + _decode_est * (later + (1 if not post
+ or bare_phase == "video_vae_decode"
+ else 0)))
+ label = (f"{win_tag}{phase_label}" if post else
+ f"{win_tag}{phase_label} · step {last_step} / {total_steps}")
else:
pct, eta = max(3.0, win_base), 0.0
label = f"{win_tag}{phase_label}"
@@ -24327,7 +24839,8 @@ def run_h3_job_inner(job: dict) -> None:
cur = STATE.get("current")
if cur and cur.get("id") == job["id"]:
cur["progress"] = {
- "phase": "denoise" if last_step else "load",
+ "phase": ("decode" if post else
+ "denoise" if last_step else "load"),
"phase_label": label,
"pct": min(99.0, pct),
"elapsed_sec": elapsed,
@@ -24348,7 +24861,7 @@ def run_h3_job_inner(job: dict) -> None:
# LTX. It is a viewer decision, not a crash; worker_loop maps this
# exception to the neutral `stopped` history state.
raise JobStopped("H3 render stopped early at the next forward boundary")
- if rc != 0 and _h3_clip_is_complete(out_path, t0):
+ if rc != 0 and _h3_clip_is_complete(out_path, t0, expect_frames=frames):
# #76 (@PhantombrainM): the engine finished the clip, then aborted
# during interpreter shutdown (mlx stream teardown after the
# runtime was gone → PyThreadState_Get / SIGABRT). The file is
@@ -24436,7 +24949,7 @@ def run_h3_job_inner(job: dict) -> None:
except RuntimeError as exc:
push(f"[h3] export target ignored: {exc}")
if upscale_plan:
- codec = output_codec_settings()
+ codec = job_codec
export_preset = os.environ.get("LTX_UPSCALE_PRESET", "medium")
upscaled_out = OUTPUT / (
f"{out_path.stem}_{upscale_plan['tag']}{out_path.suffix}")
@@ -24505,7 +25018,13 @@ def run_h3_job_inner(job: dict) -> None:
"h3_turbo": turbo,
"width": width, "height": height, "frames": frames, "steps": steps,
"seed_used": seed,
- "image": str(first_frame) if first_frame else None,
+ # The user's OWN reference, not the canvas crop made from it: the
+ # crop is deterministic from this file, so a same-canvas replay
+ # reproduces it, and a Finish at another canvas re-fits from the
+ # full image instead of enlarging a Draft-sized crop. The crop
+ # that conditioned THIS render is h3.first_frame.
+ "image": ((p.get("image") or "").strip() or str(first_frame))
+ if first_frame else None,
},
"command": "hailuo_h3",
"engine": "h3",
@@ -24518,11 +25037,23 @@ def run_h3_job_inner(job: dict) -> None:
else None),
"started": job.get("started_at"),
"elapsed_sec": elapsed,
- "video_duration_sec": round(max(0.0, frames / H3_FPS), 3),
+ # What the runner verified in the encoded file (ffprobe), falling back
+ # to the request only when an older runner did not report it.
+ "video_duration_sec": round(
+ max(0.0, int(metrics.get("delivered_frames") or frames) / H3_FPS), 3),
"fps": H3_FPS,
- "model": str(paths["dit"]),
+ # The checkpoint that RAN, not the bf16 default path: a Q8 render must
+ # not read as "full bf16" in its own provenance.
+ "model": str(_dit_path),
+ "model_precision": (metrics.get("dit_precision")
+ or metrics.get("w1_dit_precision")
+ or ("bf16" if _dit_path == paths["dit"] else "q8")),
"queue_id": job["id"],
- "output_codec": output_codec_settings(),
+ # What encoded the delivered file: the panel's export pass when one ran
+ # (it re-encodes with the job's settings), else the runner's own mp4.
+ "output_codec": (dict(job_codec, encoder="panel_export") if upscale_plan
+ else dict(native_codec)),
+ "native_codec": dict(native_codec),
"h3": {
"tier": tier["key"],
"quality": tier["quality"],
@@ -24536,6 +25067,8 @@ def run_h3_job_inner(job: dict) -> None:
"phase_seconds": {k: v.get("seconds") for k, v in phases.items()},
"peak_gib": max([v.get("peak_gib") or 0 for v in phases.values()] or [0]),
"first_frame": str(first_frame) if first_frame else None,
+ "first_frame_source": ((p.get("image") or "").strip() or None)
+ if first_frame else None,
"turbo": ({"lora": str(turbo_paths["lora"]),
"adapter_version": turbo_paths["version"],
"fallback": turbo_paths["fallback"],
@@ -24544,7 +25077,12 @@ def run_h3_job_inner(job: dict) -> None:
"repo": H3_TURBO_REPO,
# The runner's own report: how many modules landed.
"applied": (metrics.get("lora")
- or metrics.get("w1_lora"))}
+ or metrics.get("w1_lora")),
+ "adaln": (metrics.get("lora_adaln")
+ or metrics.get("w1_lora_adaln")),
+ # wrapped + absorbed + unaccounted; unaccounted must be 0.
+ "accounting": (metrics.get("lora_accounting")
+ or metrics.get("w1_lora_accounting"))}
if turbo else None),
"chain_windows": chain_windows,
"window_frames": window_frames,
@@ -24563,7 +25101,7 @@ def run_h3_job_inner(job: dict) -> None:
if upscale_plan:
sidecar["upscale"] = (
{k: v for k, v in upscale_plan.items() if k != "vf"}
- | {"source": str(native_path), "codec": output_codec_settings()}
+ | {"source": str(native_path), "codec": dict(job_codec)}
)
write_sidecar(final_target.with_suffix(final_target.suffix + ".json"), sidecar)
job["output_path"] = str(final_target)
@@ -25578,14 +26116,19 @@ def run_job_inner(job: dict) -> None:
f"tier, and {source.name} is already {sw}×{sh}. Use a smaller "
"source clip.")
up_w, up_h = ltx_floor_canvas(int(sw * scale), int(sh * scale))
- # LTX's grid is 1+8k frames and the IC reference loader rounds the
- # source DOWN to that grid, so the target must match it exactly or
- # the last latent frame renders unconditioned. A 72-frame H3 clip
- # becomes 65 frames (0.3 s trimmed at the tail); the soundtrack is
- # trimmed to match at mux time.
- frames = int(p.get("frames") or 0) or src_frames or 49
- frames = min(frames, src_frames or frames)
- frames = max(9, 1 + 8 * ((frames - 1) // 8))
+ # The ×2 is the same clip: same frame count, same duration, same
+ # sound. LTX's grid is 1+8k frames and the IC reference loader
+ # rounds whatever it is given DOWN to that grid, so the render runs
+ # on the next grid length UP (124 → 129) from a copy of the clip
+ # whose last frame is held for the extra frames, and the held tail
+ # is cut off again afterwards (124 out). It used to round DOWN
+ # instead, silently dropping up to 7 frames (124 → 121, 72 → 65).
+ # The form's generation length is not an upscale control; it only
+ # widens the ceiling past the length this lane is measured at.
+ out_frames, frames = upscale_frame_plan(src_frames, p.get("frames"))
+ if src_frames and out_frames < src_frames:
+ push(f"Upscale ×2: {source.name} is {src_frames} frames; the ×2 covers "
+ f"its first {out_frames}")
try:
keep = float(p.get("keep_shot") or 1.0)
except (TypeError, ValueError):
@@ -25628,6 +26171,22 @@ def run_job_inner(job: dict) -> None:
out_name = f"{source.stem}_x2_{stamp}.mp4"
final_out = OUTPUT / out_name
job["raw_path"] = str(final_out)
+ # The clip the model reads: the source itself when it already covers
+ # the grid, else a lossless copy with its last frame held to `frames`.
+ import tempfile as _tempfile
+ work_dir = Path(_tempfile.mkdtemp(prefix="phosphene_x2_"))
+ model_src = src
+ if frames > (src_frames or frames):
+ model_src = str(work_dir / f"{source.stem}_hold{frames}.mp4")
+ _r = subprocess.run(_upscale_hold_tail_cmd(src, model_src, src_frames, frames),
+ capture_output=True, text=True, timeout=600)
+ if _r.returncode != 0 or _probe_video_frames(model_src) != frames:
+ shutil.rmtree(work_dir, ignore_errors=True)
+ raise RuntimeError(
+ f"Upscale ×2: could not extend {source.name} to {frames} frames "
+ f"for the model: {(_r.stderr or '')[-200:].strip()}")
+ push(f"Upscale ×2: {src_frames} frames → the model renders {frames} "
+ f"(last frame held), the ×2 is cut back to {out_frames}")
job_spec = {
"action": "generate_restore",
"id": job["id"],
@@ -25641,10 +26200,10 @@ def run_job_inner(job: dict) -> None:
"frames": frames,
"frame_rate": src_fps,
"seed": p["seed"],
- "video_conditioning": [[src, keep]],
+ "video_conditioning": [[model_src, keep]],
"conditioning_attention_strength": keep,
"single_stage": start_from == "noise",
- "source_video": src if start_from == "source" else "",
+ "source_video": model_src if start_from == "source" else "",
"refine_steps": refine_steps if start_from == "source" else None,
# Q4 cannot hold a fused adapter (see the helper); Q8 can, at a
# measured 22.6% loss. Exact runtime attachment on request.
@@ -25663,15 +26222,27 @@ def run_job_inner(job: dict) -> None:
f"{up_w}×{up_h} {frames}f · keep-the-shot {keep:.2f} · {quant.upper()} distilled · "
+ (f"from the clip's own latent, {refine_steps}-step refine + Pixel Spatial Upscaler"
if start_from == "source" else "full re-render from noise + Pixel Spatial Upscaler"))
- result = HELPER.run(job_spec)
- if "seed_used" in result:
- push(f"seed used: {result['seed_used']}")
- p["seed_used"] = result["seed_used"]
- muxed = _mux_audio_from(final_out, src)
+ try:
+ result = HELPER.run(job_spec)
+ if "seed_used" in result:
+ push(f"seed used: {result['seed_used']}")
+ p["seed_used"] = result["seed_used"]
+ muxed = _upscale_finish(final_out, src, frames=out_frames, fps=src_fps,
+ trim=frames != out_frames)
+ finally:
+ shutil.rmtree(work_dir, ignore_errors=True)
+ delivered = _probe_video_frames(str(final_out))
+ if delivered and delivered != out_frames:
+ push(f"Upscale ×2: WARNING — {final_out.name} has {delivered} frames, "
+ f"expected {out_frames}")
sidecar = {
"output": str(final_out), "raw_output": str(final_out),
"params": {**p, "command": "upscale", "keep_shot": keep,
+ "frames": out_frames, "render_frames": frames,
+ "source_frames": src_frames,
"source_size": [sw, sh], "audio_from_source": muxed},
+ "delivered_frames": delivered or None,
+ "video_duration_sec": (round(delivered / src_fps, 4) if delivered else None),
"started": job.get("started_at"),
"elapsed_sec": round(time.time() - job["started_ts"], 2) if job.get("started_ts") else None,
"fps": src_fps, "model": up_model_dir, "queue_id": job["id"],
@@ -30747,6 +31318,11 @@ def _h3_preview_progress(current: dict | None) -> dict:
has_frame = latest.is_file() and forward >= 1
status = str(st.get("status") or "")
phase = str((current.get("progress") or {}).get("phase") or "")
+ try:
+ _prog_window = int((current.get("progress") or {}).get("window") or 1)
+ _prog_windows = int((current.get("progress") or {}).get("window_total") or 1)
+ except (TypeError, ValueError):
+ _prog_window = _prog_windows = 1
try:
remaining = max(0.0, float(st.get("eta_seconds") or 0.0))
except (TypeError, ValueError):
@@ -30764,8 +31340,13 @@ def _h3_preview_progress(current: dict | None) -> dict:
"meaningful": has_frame,
# The runner checks immediately after every forward, including the
# last one before VAE decode/mux, so there is still work to save at N/N.
+ # ...but NOT after the final window's last forward: decode and mux
+ # run with no further check, so a Stop there would be acknowledged
+ # and then ignored. Between windows the next window's first forward
+ # still honours it.
"abortable": bool(has_frame and status in ("starting", "running")
- and phase == "denoise"),
+ and (phase == "denoise"
+ or (phase == "decode" and _prog_window < _prog_windows))),
"remaining_sec": remaining,
"saves_sec": remaining,
"window": window,
diff --git a/mlx_warm_helper.py b/mlx_warm_helper.py
index 7751d86..f5b66a5 100644
--- a/mlx_warm_helper.py
+++ b/mlx_warm_helper.py
@@ -759,6 +759,107 @@ def _filter_unsupported_kwargs(fn, kwargs: dict) -> dict:
_LORA_PATCH_INSTALLED = False
_VIDEO_DECODER_PATCH_INSTALLED = False
_A2V_FRAME_RATE_PATCH_INSTALLED = False
+_DECODE_INT32_GUARD_INSTALLED = False
+
+# The VAE decoder's biggest activation, in ELEMENTS, has to stay below this.
+# MLX's Metal conv3d (implicit GEMM, steel_conv_3d.h) addresses its output
+# buffer with 32-bit ints: `C += c_row * (N * groups) + c_col`. Once a conv
+# output passes 2**31 elements the offset wraps, the tail of the tensor is
+# never written, and every frame past that point decodes as garbage.
+# Measured on Upscale ×2 (2048×1152, 121 frames): the last conv stage is
+# 128 × 121 × 288 × 512 = 2.28e9 elements, the wrap lands at frame 112.8,
+# and every such render shows a clean horizontal edge 3/4 down frame 112
+# and near-white frames 113–120 — on every seed and every source. The same
+# canvas at 65 frames (1.23e9) and 1280×768 at 121 frames (0.95e9) are
+# clean. 10 % headroom for the conv's padded input and upstream changes.
+_DECODE_MAX_ELEMENTS = int(0.9 * 2 ** 31)
+
+
+def _vae_decode_peak_elements(latent_frames: int, h_lat: int, w_lat: int) -> int:
+ """Largest single tensor the conv VAE decoder builds for this latent.
+
+ Stage 8 (128 ch, 8× the latent's height and width, 8L-7 frames) is the
+ biggest for any real clip; stage 4 (512 ch, 4×, 4L-3 frames) only wins
+ at a single latent frame. Both are conv INPUTS, which carry one frame and
+ one pixel of padding on every side. Every other tensor is smaller — the
+ whole decoder is walked in test_upscale_x2_tail.py."""
+ n, h, w = max(1, int(latent_frames)), int(h_lat), int(w_lat)
+ stage8 = 128 * (8 * n - 7 + 2) * (8 * h + 2) * (8 * w + 2)
+ stage4 = 512 * (4 * n - 3 + 2) * (4 * h + 2) * (4 * w + 2)
+ return max(stage8, stage4)
+
+
+def _vae_decode_max_latent_frames(h_lat: int, w_lat: int) -> int:
+ """How many latent frames one decode pass may carry without the wrap."""
+ n = 1
+ while _vae_decode_peak_elements(n + 1, h_lat, w_lat) <= _DECODE_MAX_ELEMENTS:
+ n += 1
+ return n
+
+
+def _int32_safe_decode_tiling(orig, latent_shape, frame_rate=24.0):
+ """`_compute_decode_tiling`, plus an element cap next to its byte budget.
+
+ Upstream only tiles when a decode would exceed a MEMORY budget (8 GB by
+ default), so a 2048×1152 × 121-frame clip — 2.3 GB of block-3 activation —
+ decodes in one pass and runs straight into the int32 wrap above. When the
+ pass is too big, this returns the same temporal tiling upstream uses for
+ long clips, with tiles small enough to stay under the cap. Everything
+ that already fits keeps upstream's answer untouched."""
+ cfg = orig(latent_shape, frame_rate=frame_rate)
+ _, _, f_lat, h_lat, w_lat = (int(v) for v in latent_shape)
+ max_lat = _vae_decode_max_latent_frames(h_lat, w_lat)
+ if f_lat <= max_lat:
+ return cfg
+ # split_temporal_latents moves every tile after the first one latent
+ # frame earlier (causal continuity), so those tiles are size + 1 long.
+ size = max(2, max_lat - 1)
+ tc = getattr(cfg, "temporal_config", None) if cfg is not None else None
+ if tc is not None and tc.tile_size_in_frames // 8 <= size:
+ return cfg
+ from ltx_core_mlx.model.video_vae.tiling import TemporalTilingConfig, TilingConfig
+ tile_frames = size * 8
+ one_second = max(8, (int(frame_rate) // 8) * 8)
+ overlap = min(one_second, (tile_frames // 32) * 8)
+ if overlap >= tile_frames:
+ overlap = tile_frames - 8
+ return TilingConfig(
+ spatial_config=getattr(cfg, "spatial_config", None) if cfg is not None else None,
+ temporal_config=TemporalTilingConfig(
+ tile_size_in_frames=tile_frames, tile_overlap_in_frames=overlap))
+
+
+def _install_decode_int32_guard() -> None:
+ """Route every conv-VAE decode through `_int32_safe_decode_tiling`.
+
+ `VideoDecoder.decode_and_stream` looks `_compute_decode_tiling` up as a
+ module global at call time, so replacing the module attribute covers
+ every pipeline (t2v, i2v, extend, HQ, A2V, HDR, every IC lane). Idempotent."""
+ global _DECODE_INT32_GUARD_INSTALLED
+ if _DECODE_INT32_GUARD_INSTALLED:
+ return
+ import ltx_core_mlx.model.video_vae.video_vae as _vv
+ orig = _vv._compute_decode_tiling
+ if getattr(orig, "_phosphene_int32_guard", False):
+ _DECODE_INT32_GUARD_INSTALLED = True
+ return
+
+ def _guarded(latent_shape, frame_rate: float = 24.0):
+ cfg = _int32_safe_decode_tiling(orig, latent_shape, frame_rate=frame_rate)
+ tc =getattr(cfg, "temporal_config", None) if cfg is not None else None
+ if tc is not None:
+ _, _, f_lat, h_lat, w_lat = (int(v) for v in latent_shape)
+ if f_lat > _vae_decode_max_latent_frames(h_lat, w_lat):
+ emit({"event": "log",
+ "line": f"vae-decode int32 guard: {f_lat} latent frames at "
+ f"{w_lat * 32}×{h_lat * 32} decode in tiles of "
+ f"{tc.tile_size_in_frames} frames "
+ f"(overlap {tc.tile_overlap_in_frames})"})
+ return cfg
+
+ _guarded._phosphene_int32_guard = True
+ _vv._compute_decode_tiling = _guarded
+ _DECODE_INT32_GUARD_INSTALLED = True
# NOTE — an earlier `_PostDecodeWatchdog` daemon-thread class lived
@@ -2869,6 +2970,13 @@ for line in sys.__stdin__:
# lane added tomorrow would otherwise inherit whatever the last job left.
if isinstance(action, str) and action.startswith(("generate", "extend")):
apply_mlx_cache_policy()
+ # And the decoder's int32 cap (see _DECODE_MAX_ELEMENTS): once, for
+ # every lane, before any of them can decode.
+ try:
+ _install_decode_int32_guard()
+ except Exception as _exc: # noqa: BLE001
+ emit({"event": "log",
+ "line": f"vae-decode int32 guard NOT installed: {_exc}"})
if action == "generate":
job_id = msg.get("id", "?")
diff --git a/storyboard.py b/storyboard.py
index 5c6e888..2d69878 100644
--- a/storyboard.py
+++ b/storyboard.py
@@ -256,11 +256,12 @@ _PIPELINE_LOAD_SECS = 90.0
# same measurements rather than invented:
# draft 3s 3.0 min / 3 s = 60 s per video-second
# standard 5s 9.1 min / 5 s = 109
-# high 5s 18.8 min / 5 s = 226 (no Turbo)
+# high 5s 34 min / 5 s = 408 (no Turbo; model-derived at 15 forwards since
+# 2026-09-16 — the 18.8 min receipt was 8 forwards)
# native 5s 44.9 min / 5 s = 538 (no Turbo, never selected by a pass)
# An H3 clip is a fresh subprocess that loads its own weights, so this per-clip number is
# END TO END — which is why an H3 bucket adds no separate pipeline-load charge below.
-_H3_SECS_PER_VIDEO_SEC = {"draft": 60.0, "standard": 109.0, "high": 226.0, "native": 538.0}
+_H3_SECS_PER_VIDEO_SEC = {"draft": 60.0, "standard": 109.0, "high": 408.0, "native": 538.0}
class StoryboardError(Exception):
diff --git a/test_autoplay_only_on_click.py b/test_autoplay_only_on_click.py
new file mode 100644
index 0000000..0119d7b
--- /dev/null
+++ b/test_autoplay_only_on_click.py
@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Opening the panel must not play a clip ("it's still playing a clip every
+time you open it", owner 2026-09-14). The 4.9 fix passed `autoplay: false` at
+the four boot-time selections, but a storyboard poll, the clip restored after a
+live preview and the finished-take handoff still selected with the old default
+and played with sound. The rule now lives inside selectOutput itself."""
+from __future__ import annotations
+
+import re
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+
+
+def _select_output_body() -> str:
+ js = (ROOT / "webapp" / "js" / "queue.js").read_text(encoding="utf-8")
+ i = js.index("function selectOutput(path, options)")
+ j = js.index("\nfunction ", i + 1)
+ return js[i:j]
+
+
+class AutoplayIsForAClick(unittest.TestCase):
+ def test_autoplay_follows_a_trusted_event(self):
+ body = _select_output_body()
+ m = re.search(r"const autoplay\s*=([^;]+);", body)
+ self.assertIsNotNone(m, "selectOutput must compute autoplay once")
+ rule = m.group(1)
+ self.assertIn("userSelected", rule,
+ "a selection nobody clicked must not autoplay")
+ self.assertIn("options.autoplay === true", rule)
+ self.assertLess(body.index("const userSelected"), body.index("const autoplay"),
+ "autoplay reads userSelected, so it must come after it")
+
+ def test_no_other_video_on_the_stage_hardcodes_autoplay(self):
+ body = _select_output_body()
+ tags = re.findall(r"<video[^>]*>", body)
+ self.assertTrue(tags)
+ for tag in tags:
+ # `${autoplay ? ' autoplay' : ''}` is the computed flag; a bare
+ # attribute outside an interpolation would play regardless.
+ self.assertNotIn("autoplay", re.sub(r"\$\{[^}]*\}", "", tag),
+ "stage <video> tags must use the computed flag")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/test_h3_high_steps.py b/test_h3_high_steps.py
new file mode 100644
index 0000000..e6fc207
--- /dev/null
+++ b/test_h3_high_steps.py
@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Contract gate: Auto H3 High runs 16 sigma points (15 forwards) per window.
+
+Owner ruling 2026-09-16, from a matched gym A/B: High 1024x576 at 15 forwards is
+clearly better than at 8 (the face was blurry at 8). Native stays on its own
+constant until its 15-forward test is judged. A measured wall clock only prints
+for a cell sampled at the depth it was measured at.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+STATE = Path(tempfile.mkdtemp(prefix="phos-h3-high-steps-"))
+os.environ["LTX_STATE_DIR"] = str(STATE)
+os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"
+os.environ["PHOSPHENE_DISABLE_VERSION_CHECK"] = "1"
+os.environ["LTX_H3_FORCE_CAPABLE"] = "1"
+os.environ.setdefault("LTX_PORT", "8296")
+sys.path.insert(0, str(ROOT))
+
+import mlx_ltx_panel as P # noqa: E402
+import storyboard as SB # noqa: E402
+
+
+def h3_job(form: dict) -> dict:
+ base = {"mode": "t2v", "engine": "h3", "prompt": "a man lifts a dumbbell",
+ "h3_turbo": "0"}
+ base.update(form)
+ return P.make_job({k: [v] for k, v in base.items()})
+
+
+class TestHighCellsRunFifteenForwards(unittest.TestCase):
+ def test_the_constants(self):
+ self.assertEqual(P.H3_HIGH_STEPS, 16)
+ # Native is deliberately ONE constant away from the same change.
+ self.assertEqual(P.H3_NATIVE_STEPS, P.H3_STEPS_DEFAULT)
+ self.assertEqual(P.H3_QUALITIES["high"]["steps"], P.H3_HIGH_STEPS)
+ self.assertEqual(P.H3_QUALITIES["native"]["steps"], P.H3_NATIVE_STEPS)
+
+ def test_every_high_cell_is_sixteen_points(self):
+ for key, cell in P.H3_TIERS.items():
+ if cell["quality"] != "high":
+ continue
+ with self.subTest(cell=key):
+ self.assertEqual(cell["steps"], 16)
+ self.assertEqual(cell["forwards"], 15 * cell["chain_windows"])
+
+ def test_other_canvases_keep_their_length_count(self):
+ for key, cell in P.H3_TIERS.items():
+ if cell["quality"] == "high":
+ continue
+ want = 16 if cell["dense"] else P.H3_STEPS_DEFAULT
+ if cell["quality"] == "native":
+ want = max(want, P.H3_NATIVE_STEPS)
+ with self.subTest(cell=key):
+ self.assertEqual(cell["steps"], want)
+
+ def test_a_canvas_never_lowers_a_dense_length(self):
+ self.assertEqual(P.H3_TIERS["high_10s_dense"]["steps"], 16)
+ self.assertEqual(P.H3_TIERS["native_10s_dense"]["steps"], 16)
+ self.assertEqual(P.H3_TIERS["standard_10s_dense"]["steps"], 16)
+
+
+class TestMeasuredEtaMatchesDepth(unittest.TestCase):
+ def test_eight_forward_receipt_no_longer_prices_high(self):
+ cell = P.H3_TIERS["high_5s"]
+ self.assertFalse(cell["eta_measured"])
+ model = P.h3_estimate_minutes(1024, 576, 124, 1, 15)
+ self.assertAlmostEqual(cell["eta_min"], round(model, 2), places=2)
+ # ~15 x 126 s + ~131 s fixed; well past the old 18.8.
+ self.assertGreater(cell["eta_min"], 30.0)
+
+ def test_receipts_at_their_own_depth_still_print(self):
+ for key in ("draft_3s", "standard_5s", "standard_10s", "native_5s",
+ "standard_10s_dense"):
+ with self.subTest(cell=key):
+ self.assertTrue(P.H3_TIERS[key]["eta_measured"])
+
+ def test_every_receipt_names_its_depth(self):
+ for k, v in P.H3_MEASURED_ETA.items():
+ with self.subTest(key=k):
+ self.assertEqual(len(v), 3)
+ self.assertGreaterEqual(int(v[2]), 1)
+
+ def test_storyboard_fallback_tracks_the_model(self):
+ per_sec = P.H3_TIERS["high_5s"]["eta_min"] * 60 / 5
+ self.assertLess(abs(SB._H3_SECS_PER_VIDEO_SEC["high"] - per_sec),
+ 0.1 * per_sec)
+
+
+class TestMakeJobStampsTheDepth(unittest.TestCase):
+ def test_auto_high_stamps_sixteen(self):
+ p = h3_job({"h3_quality": "high", "h3_length": "5s"})["params"]
+ self.assertEqual(p["h3_tier"], "high_5s")
+ self.assertEqual(p["steps"], 16)
+ self.assertEqual(p["h3_steps"], 0)
+
+ def test_auto_standard_and_native_stay_at_nine(self):
+ for q in ("standard", "native"):
+ with self.subTest(quality=q):
+ p = h3_job({"h3_quality": q, "h3_length": "5s"})["params"]
+ self.assertEqual(p["steps"], P.H3_TIERS[f"{q}_5s"]["steps"])
+
+ def test_a_pinned_count_still_wins_on_high(self):
+ p = h3_job({"h3_quality": "high", "h3_length": "5s",
+ "h3_steps": "12"})["params"]
+ self.assertEqual(p["steps"], 12)
+
+
+class TestUiReadsTheCell(unittest.TestCase):
+ def test_no_hardcoded_eight_forward_title(self):
+ html = (ROOT / "webapp" / "index.html").read_text()
+ self.assertNotIn("9 sigma points, 8 forwards per window", html)
+ js = (ROOT / "webapp" / "js" / "engines.js").read_text()
+ self.assertIn("function _h3SyncSamplerTitles", js)
+ self.assertRegex(js, re.compile(r"renderH3Turbo\(\)\s*\{[\s\S]*?_h3SyncSamplerTitles\(\)"))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/test_h3_review_r2.py b/test_h3_review_r2.py
new file mode 100644
index 0000000..df8d6a1
--- /dev/null
+++ b/test_h3_review_r2.py
@@ -0,0 +1,438 @@
+#!/usr/bin/env python3
+"""Contract gate for the H3 review round 2 fixes (PM hub notes/h3-review/FINDINGS_R2.md).
+
+ 1 H3 -> LTX x2 handoff carries the draft's prompt and resolved seed
+ 2 Finish restores the source's LoRAs, orientation and adapter slot
+ 3 a nonzero exit is only salvaged for a verified, full-length video file
+ 4 a Phosphene kohya conversion loads at 1.0 (no second alpha/rank)
+ 5 disagreeing per-module alphas are folded per module, not collapsed
+ 6 No Music reaches written chain-window prompts
+ 7 (worker) the sidecar keeps the user's own reference image
+ 8 a replayed pinned step count (4-30) survives Load Params and Finish
+ 9 measured and pinned-step ETAs carry this Mac's speed factor
+10 Turbo estimates follow the adapter installed now, both directions
+11 (worker) the codec record says what encoded the file
+12 Stop early is not offered after the final window's last forward
+
+MLX runs on the CPU here, on purpose: this gate must never touch the GPU.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import struct
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+STATE = Path(tempfile.mkdtemp(prefix="phos-h3-r2-"))
+os.environ["LTX_STATE_DIR"] = str(STATE)
+os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"
+os.environ["PHOSPHENE_DISABLE_VERSION_CHECK"] = "1"
+os.environ.setdefault("LTX_PORT", "8294")
+sys.path.insert(0, str(ROOT))
+
+import mlx_ltx_panel as P # noqa: E402
+
+PANEL_SRC = (ROOT / "mlx_ltx_panel.py").read_text(encoding="utf-8")
+NODE = shutil.which("node")
+
+
+def _safetensors(path: Path, tensors: dict, meta: dict | None = None) -> None:
+ """Tiny F32 safetensors writer (no mlx): {name: (shape, [values])}."""
+ header, blobs, off = {}, [], 0
+ for name, (shape, vals) in tensors.items():
+ raw = struct.pack(f"<{len(vals)}f", *vals)
+ header[name] = {"dtype": "F32", "shape": list(shape),
+ "data_offsets": [off, off + len(raw)]}
+ blobs.append(raw)
+ off += len(raw)
+ if meta:
+ header["__metadata__"] = {k: str(v) for k, v in meta.items()}
+ hb = json.dumps(header).encode()
+ hb += b" " * (-len(hb) % 8)
+ path.write_bytes(struct.pack("<Q", len(hb)) + hb + b"".join(blobs))
+
+
+def _pair(prefix: str, rank: int, fill: float = 0.5) -> dict:
+ return {f"{prefix}.lora_A.weight": ((rank, 3), [fill] * (rank * 3)),
+ f"{prefix}.lora_B.weight": ((4, rank), [fill] * (4 * rank))}
+
+
+# ---------------------------------------------------------------- 1
+class TestUpscaleHandoff(unittest.TestCase):
+ def test_empty_upscale_prompt_stays_empty(self):
+ j = P.make_job({k: [v] for k, v in {
+ "mode": "upscale", "engine": "ltx", "upscale_source_path": "/x.mp4",
+ "prompt": "", "seed": "-1"}.items()})
+ self.assertEqual(j["params"]["prompt"], "")
+
+ def test_other_modes_keep_the_filler(self):
+ j = P.make_job({k: [v] for k, v in {
+ "mode": "t2v", "engine": "ltx", "prompt": ""}.items()})
+ self.assertTrue(j["params"]["prompt"])
+
+ def test_handoff_carries_prompt_and_resolved_seed(self):
+ seen = {}
+ old_mj, old_pq = P.make_job, P.persist_queue
+
+ def fake(form):
+ seen.update(form)
+ return {"id": "x2job", "params": {}}
+ P.make_job, P.persist_queue = fake, (lambda: None)
+ try:
+ P._chain_upscale_after_h3(
+ {"id": "draft1"},
+ {"prompt": "A woman lifts a dumbbell", "seed": "-1",
+ "seed_used": 52190, "label": "gym"},
+ Path("/tmp/gym.mp4"))
+ finally:
+ P.make_job, P.persist_queue = old_mj, old_pq
+ with P.QUEUE_COND:
+ P.STATE["queue"] = [j for j in P.STATE["queue"] if j.get("id") != "x2job"]
+ self.assertEqual(seen["prompt"], "A woman lifts a dumbbell")
+ self.assertEqual(seen["seed"], "52190")
+
+
+# ---------------------------------------------------------------- 3
[email protected](Path(str(P.FFMPEG)).is_file(), "ffmpeg missing")
+class TestSalvageVerifiesTheFile(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ cls.dir = Path(tempfile.mkdtemp(prefix="phos-h3-salvage-"))
+
+ def mk(name, frames=None, audio_only=False):
+ out = cls.dir / name
+ if audio_only:
+ cmd = [str(P.FFMPEG), "-y", "-loglevel", "error", "-f", "lavfi",
+ "-i", "anoisesrc=d=4:r=48000", "-c:a", "pcm_s16le",
+ "-threads", "1", str(out)]
+ else:
+ cmd = [str(P.FFMPEG), "-y", "-loglevel", "error", "-f", "lavfi",
+ "-i", "nullsrc=s=320x192:r=24,geq=random(1)*255:128:128",
+ "-frames:v", str(frames), "-c:v", "libx264", "-crf", "0",
+ "-preset", "ultrafast", "-pix_fmt", "yuv444p",
+ "-threads", "1", str(out)]
+ subprocess.run(cmd, check=True, timeout=120)
+ return out
+ cls.full = mk("full.mp4", 73)
+ cls.short1 = mk("short1.mp4", 72)
+ cls.partial = mk("partial.mp4", 8)
+ cls.audio = mk("audio.wav", audio_only=True)
+
+ def test_sizes_pass_the_old_floor(self):
+ for f in (self.full, self.partial, self.audio):
+ self.assertGreaterEqual(f.stat().st_size, 200_000, f.name)
+
+ def test_full_clip_is_salvaged(self):
+ self.assertTrue(P._h3_clip_is_complete(self.full, time.time() - 60, 73))
+
+ def test_one_short_is_tolerated_for_old_runners(self):
+ self.assertTrue(P._h3_clip_is_complete(self.short1, time.time() - 60, 73))
+
+ def test_partial_clip_is_not(self):
+ self.assertFalse(P._h3_clip_is_complete(self.partial, time.time() - 60, 73))
+
+ def test_audio_only_is_not(self):
+ self.assertFalse(P._h3_clip_is_complete(self.audio, time.time() - 60, 73))
+
+ def test_stale_file_is_not(self):
+ self.assertFalse(P._h3_clip_is_complete(self.full, time.time() + 60, 73))
+
+ def test_worker_passes_the_delivered_count(self):
+ self.assertIn("_h3_clip_is_complete(out_path, t0, expect_frames=frames)", PANEL_SRC)
+
+
+# ---------------------------------------------------------------- 4 / 5
+class TestLoraScale(unittest.TestCase):
+ def setUp(self):
+ self.tmp = Path(tempfile.mkdtemp(prefix="phos-h3-scale-"))
+
+ def _report(self, path):
+ header, start = P._safetensors_header(path)
+ return P._h3_lora_scale_report(path, header, start)
+
+ def test_phosphene_kohya_conversion_is_folded(self):
+ f = self.tmp / "old_convert.safetensors"
+ _safetensors(f, _pair("blocks.3.attn.qkv_proj", 32),
+ {"converted_from": "kohya", "converted_by": "phosphene",
+ "alpha_over_rank": "0.5", "ss_network_alpha": "16"})
+ r = self._report(f)
+ self.assertEqual(r["source"], "folded")
+ self.assertEqual(r["strength"], 1.0)
+
+ def test_foreign_metadata_alpha_still_divides(self):
+ f = self.tmp / "foreign.safetensors"
+ _safetensors(f, _pair("blocks.3.attn.qkv_proj", 32), {"ss_network_alpha": "16"})
+ r = self._report(f)
+ self.assertEqual(r["source"], "uniform")
+ self.assertAlmostEqual(r["strength"], 0.5)
+
+ def test_converter_writes_the_marker(self):
+ self.assertIn('"peft_scale_folded_into_B": (f"{quotients[0]:g}"', PANEL_SRC)
+
+ def test_listing_corrects_saved_kohya_strength(self):
+ d = self.tmp / "loras"
+ d.mkdir()
+ f = d / "person.safetensors"
+ _safetensors(f, _pair("blocks.3.attn.qkv_proj", 32))
+ f.with_suffix(".json").write_text(json.dumps(
+ {"name": "person", "recommended_strength": 0.5,
+ "lora_layout": "kohya", "kind": "import"}))
+ old = P._h3_loras_dir
+ P._h3_loras_dir = lambda: d
+ try:
+ rows = [r for r in P.list_h3_user_loras() if r["filename"] == f.name]
+ finally:
+ P._h3_loras_dir = old
+ self.assertEqual(rows[0]["recommended_strength"], 1.0)
+
+ def test_uniform_alphas_are_not_rewritten(self):
+ f = self.tmp / "uniform.safetensors"
+ t = {**_pair("blocks.1.attn.qkv_proj", 4), **_pair("blocks.2.attn.qkv_proj", 4)}
+ t["blocks.1.attn.qkv_proj.alpha"] = ((), [2.0])
+ t["blocks.2.attn.qkv_proj.alpha"] = ((), [2.0])
+ _safetensors(f, t)
+ before = f.read_bytes()
+ self.assertIsNone(P._h3_lora_fold_mixed_alphas(f))
+ self.assertEqual(f.read_bytes(), before)
+ r = self._report(f)
+ self.assertEqual(r["source"], "per_module")
+ self.assertAlmostEqual(r["strength"], 0.5)
+
+ def test_mixed_alphas_fold_per_module(self):
+ import mlx.core as mx
+ mx.set_default_device(mx.cpu)
+ f = self.tmp / "mixed.safetensors"
+ t = {**_pair("blocks.1.attn.qkv_proj", 4, 1.0),
+ **_pair("blocks.2.attn.qkv_proj", 4, 1.0)}
+ t["blocks.1.attn.qkv_proj.alpha"] = ((), [2.0]) # 0.5
+ t["blocks.2.attn.qkv_proj.alpha"] = ((), [4.0]) # 1.0
+ _safetensors(f, t)
+ out = P._h3_lora_fold_mixed_alphas(f)
+ self.assertEqual(out["modules"], 2)
+ w = mx.load(str(f))
+ self.assertFalse(any(k.endswith(".alpha") for k in w))
+ self.assertAlmostEqual(float(w["blocks.1.attn.qkv_proj.lora_B.weight"][0, 0].item()), 0.5)
+ self.assertAlmostEqual(float(w["blocks.2.attn.qkv_proj.lora_B.weight"][0, 0].item()), 1.0)
+ self.assertAlmostEqual(float(w["blocks.1.attn.qkv_proj.lora_A.weight"][0, 0].item()), 1.0)
+ r = self._report(f)
+ self.assertEqual((r["source"], r["strength"]), ("folded", 1.0))
+ # Idempotent: prepare again changes nothing.
+ before = f.read_bytes()
+ P._h3_lora_prepare(f)
+ self.assertEqual(f.read_bytes(), before)
+
+
+# ---------------------------------------------------------------- 9
+class TestHardwareFactor(unittest.TestCase):
+ def tearDown(self):
+ os.environ.pop("PHOSPHENE_SPEED_FACTOR", None)
+
+ def test_measured_and_coefficients_scale(self):
+ base = P._build_h3_tiers()
+ os.environ["PHOSPHENE_SPEED_FACTOR"] = "2"
+ slow = P._build_h3_tiers()
+ self.assertTrue(slow["standard_5s"]["eta_measured"])
+ self.assertAlmostEqual(slow["standard_5s"]["eta_min"],
+ 2 * base["standard_5s"]["eta_min"], places=2)
+ self.assertEqual(slow["standard_5s"]["eta"], "~18 min")
+ self.assertAlmostEqual(slow["high_5s"]["per_forward_sec"],
+ 2 * base["high_5s"]["per_forward_sec"], delta=0.02)
+ self.assertAlmostEqual(slow["high_5s"]["fixed_sec"],
+ 2 * base["high_5s"]["fixed_sec"], delta=0.02)
+ # Browser arithmetic for Auto reproduces the server's model number.
+ c = slow["high_5s"]
+ js = (c["chain_windows"] * 15 * c["per_forward_sec"]
+ + c["chain_windows"] * c["fixed_sec"]) / 60
+ self.assertAlmostEqual(js, c["eta_min"], delta=0.05)
+
+ def test_factor_one_keeps_the_receipt_string(self):
+ os.environ["PHOSPHENE_SPEED_FACTOR"] = "1"
+ self.assertEqual(P._build_h3_tiers()["standard_5s"]["eta"], "~9 min")
+
+
+# ---------------------------------------------------------------- 10
+class TestTurboRetune(unittest.TestCase):
+ def test_install_and_removal_reprice(self):
+ old_steps, old_fwd = P.h3_turbo_steps, P._H3_TURBO_PRICED_FWD
+ saved = {k: dict(v) for k, v in P.H3_TIERS.items()}
+ try:
+ P._H3_TURBO_PRICED_FWD = P.H3_TURBO_FORWARDS
+ P.h3_turbo_steps = lambda paths=None: 7
+ P._h3_retune_turbo_estimates()
+ self.assertEqual(P.H3_TIERS["standard_10s"]["turbo_forwards"], 12)
+ v4_min = P.H3_TIERS["standard_5s"]["turbo_min"]
+ P.h3_turbo_steps = lambda paths=None: P.H3_TURBO_STEPS
+ P._h3_retune_turbo_estimates()
+ self.assertEqual(P.H3_TIERS["standard_10s"]["turbo_forwards"],
+ 2 * P.H3_TURBO_FORWARDS)
+ self.assertLess(P.H3_TIERS["standard_5s"]["turbo_min"], v4_min)
+ finally:
+ P.h3_turbo_steps, P._H3_TURBO_PRICED_FWD = old_steps, old_fwd
+ for k, v in saved.items():
+ P.H3_TIERS[k].clear()
+ P.H3_TIERS[k].update(v)
+
+ def test_status_reprices(self):
+ body = PANEL_SRC.split("def h3_turbo_status()", 1)[1].split("\ndef ", 1)[0]
+ self.assertIn("_h3_retune_turbo_estimates()", body)
+
+
+# ---------------------------------------------------------------- 12
+class TestStopEarlyBoundary(unittest.TestCase):
+ def setUp(self):
+ self.dir = Path(tempfile.mkdtemp(prefix="phos-h3-lp-"))
+ (self.dir / "preview_latest.png").write_bytes(b"x")
+ (self.dir / "status.json").write_text(json.dumps({
+ "schema": "h3-live-preview/1", "status": "running",
+ "forward": 8, "total_forwards": 8, "window": 1, "total_windows": 1}))
+ self.old = (P.h3_live_preview_ready, P.live_preview_dir)
+ P.h3_live_preview_ready = lambda: True
+ P.live_preview_dir = lambda job_id: self.dir
+
+ def tearDown(self):
+ P.h3_live_preview_ready, P.live_preview_dir = self.old
+
+ def _abortable(self, phase, window=1, total=1):
+ cur = {"id": "j", "progress": {"phase": phase, "window": window,
+ "window_total": total}}
+ return P._h3_preview_progress(cur)["live_preview"]["abortable"]
+
+ def test_denoise_is_abortable(self):
+ self.assertTrue(self._abortable("denoise"))
+
+ def test_final_decode_is_not(self):
+ self.assertFalse(self._abortable("decode", 1, 1))
+ self.assertFalse(self._abortable("decode", 3, 3))
+
+ def test_decode_before_another_window_is(self):
+ self.assertTrue(self._abortable("decode", 1, 2))
+
+ def test_worker_reports_decode_after_the_last_forward(self):
+ self.assertIn('"decode" if post else', PANEL_SRC)
+ self.assertIn('_H3_POST_PHASES = ("video_vae_decode", "audio_vae_decode", '
+ '"encode_mux", "stitch")', PANEL_SRC)
+
+
+# ---------------------------------------------------------------- 7 / 11 (worker source)
+class TestWorkerProvenance(unittest.TestCase):
+ def test_sidecar_image_is_the_users_file(self):
+ self.assertIn('"image": ((p.get("image") or "").strip() or str(first_frame))', PANEL_SRC)
+ self.assertIn('"first_frame_source":', PANEL_SRC)
+
+ def test_codec_record_names_the_encoder(self):
+ self.assertIn('"native_codec": dict(native_codec)', PANEL_SRC)
+ self.assertIn('dict(job_codec, encoder="panel_export") if upscale_plan', PANEL_SRC)
+ self.assertNotIn('"output_codec": output_codec_settings(),\n "h3"', PANEL_SRC)
+
+
+# ---------------------------------------------------------------- 2 / 6 / 8 (browser)
+_JS = r"""
+const fs = require('fs'), vm = require('vm');
+function extract(file, name) {
+ const s = fs.readFileSync(file, 'utf8');
+ const start = s.indexOf('function ' + name + '(');
+ if (start < 0) throw new Error('missing ' + name);
+ return s.slice(start, s.indexOf('\n}', start) + 2);
+}
+const Q = process.argv[1] + '/webapp/js/queue.js', E = process.argv[1] + '/webapp/js/engines.js';
+const fields = { h3_steps: {value: 'auto'}, steps: {value: 9} };
+const hint = {textContent: ''};
+const ctx = {
+ document: {getElementById: id => fields[id],
+ querySelectorAll: () => [], querySelector: () => hint},
+ localStorage: {setItem() {}},
+ h3TierByKeyExact: key => ({key, quality: 'high', length: '5s'}),
+ h3CurrentCell: () => ({steps: 16}),
+ out: {},
+};
+vm.createContext(ctx);
+for (const [f, n] of [[Q, '_h3FinishSteps'], [Q, 'h3FinishFieldsFromSidecar'],
+ [E, 'h3NormalizeSteps'], [E, 'setH3Steps']]) {
+ vm.runInContext(extract(f, n), ctx);
+}
+vm.runInContext(`
+ const src = {engine: 'h3', mode: 'i2v', prompt: 'p', seed: '-1', seed_used: 52190,
+ image: '/orig.png', h3_steps: 21, h3_orientation: 'portrait',
+ loras: [{path: '/actorA.safetensors', strength: 0.8}], h3_lora_slot: 'user'};
+ out.finish = h3FinishFieldsFromSidecar(src, 'high_5s');
+ out.finishBare = h3FinishFieldsFromSidecar({engine: 'h3', mode: 't2v', prompt: 'q',
+ seed_used: 3, h3_steps: 0}, 'high_5s');
+ out.steps = {};
+ for (const n of ['4', '7', '12', '16', '20', '21', '30', '31', '3', 'auto', 'x']) {
+ setH3Steps(n);
+ out.steps[n] = [document.getElementById('h3_steps').value,
+ document.getElementById('steps').value];
+ }
+`, ctx);
+process.stdout.write(JSON.stringify(ctx.out));
+"""
+
+
[email protected](NODE, "node missing")
+class TestBrowserReplay(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ r = subprocess.run([NODE, "-e", _JS, str(ROOT)], capture_output=True,
+ text=True, timeout=60)
+ if r.returncode:
+ raise AssertionError(r.stderr)
+ cls.out = json.loads(r.stdout)
+
+ def test_finish_carries_the_recipe(self):
+ f = self.out["finish"]
+ self.assertEqual(f["loras"], [{"path": "/actorA.safetensors", "strength": 0.8}])
+ self.assertEqual(f["h3_orientation"], "portrait")
+ self.assertEqual(f["h3_lora_slot"], "user")
+ self.assertEqual(f["h3_steps"], "21")
+ self.assertEqual(f["seed"], "52190")
+ self.assertEqual(f["image"], "/orig.png")
+
+ def test_finish_without_adapters_clears_the_picker(self):
+ f = self.out["finishBare"]
+ self.assertEqual(f["loras"], [])
+ self.assertEqual(f["h3_orientation"], "landscape")
+ self.assertEqual(f["h3_steps"], "auto")
+
+ def test_every_server_valid_count_survives(self):
+ s = self.out["steps"]
+ for n in ("4", "7", "12", "16", "20", "21", "30"):
+ self.assertEqual(s[n], [n, int(n)], n)
+ for n in ("31", "3", "auto", "x"):
+ self.assertEqual(s[n], ["auto", 16], n)
+
+ def test_finish_restores_before_the_shape(self):
+ js = (ROOT / "webapp" / "js" / "queue.js").read_text(encoding="utf-8")
+ body = js.split("async function h3FinishActive()", 1)[1]
+ self.assertLess(body.index("_restoreLoraPicker(fields.loras)"),
+ body.index("setH3Tier(fields.h3_tier)"))
+ self.assertLess(body.index("setH3Orientation(fields.h3_orientation)"),
+ body.index("setH3Tier(fields.h3_tier)"))
+ self.assertIn("setH3LoraSlot(fields.h3_lora_slot)", body)
+
+ def test_no_music_reaches_written_windows(self):
+ js = (ROOT / "webapp" / "js" / "queue.js").read_text(encoding="utf-8")
+ start = js.index("const cpRaw = String(fd.get('h3_chain_prompts')")
+ block = js[start:js.index("} catch (_)", start)]
+ prog = ("const fd = new Map([['h3_chain_prompts', process.argv[1]]]);"
+ "fd.set = fd.set.bind(fd);"
+ "{" + block + "} catch (_) {} } }"
+ "process.stdout.write(fd.get('h3_chain_prompts'));")
+ raw = json.dumps(["Shot one", "", "Shot three\nnon_diegetic_music: soft piano"])
+ r = subprocess.run([NODE, "-e", prog, raw], capture_output=True,
+ text=True, timeout=30)
+ self.assertEqual(r.returncode, 0, r.stderr)
+ got = json.loads(r.stdout)
+ self.assertEqual(got[0], "Shot one\n\nnon_diegetic_music: N/A")
+ self.assertEqual(got[1], "") # blank inherits the main prompt
+ self.assertEqual(got[2], "Shot three\nnon_diegetic_music: soft piano")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/test_h3_turbo_adapter.py b/test_h3_turbo_adapter.py
index 827da28..a0e49a8 100644
--- a/test_h3_turbo_adapter.py
+++ b/test_h3_turbo_adapter.py
@@ -194,6 +194,195 @@ class TestH3TurboInstallContract(unittest.TestCase):
self.assertIn(P.H3_TURBO_LORA_FILE, status["install_note"])
+def _write_lora_fixture(path: Path, adaln_modules: list[str],
+ other_modules: list[str]) -> Path:
+ """A real (tiny) safetensors file: header + zero bytes, one 1x1 tensor per
+ lora_A / lora_B key. Only the header is ever read by the panel."""
+ import json as _json
+ import struct as _struct
+ header, offset = {}, 0
+ for module in adaln_modules + other_modules:
+ for suffix in (".lora_A.weight", ".lora_B.weight"):
+ header[module + suffix] = {"dtype": "F32", "shape": [1, 1],
+ "data_offsets": [offset, offset + 4]}
+ offset += 4
+ header["__metadata__"] = {"base_model": "fixture"}
+ raw = _json.dumps(header).encode()
+ raw += b" " * (-len(raw) % 8)
+ path.write_bytes(_struct.pack("<Q", len(raw)) + raw + b"\0" * offset)
+ return path
+
+
+V4_ADALN = ([f"blocks.{i}.adaln_proj.linear" for i in range(50)]
+ + ["final_layer.adaln_proj.linear"])
+V4_OTHER = [f"blocks.{i}.attn.out_proj" for i in range(4)]
+
+
+class TestH3TurboAdaln(unittest.TestCase):
+ """Turbo v4 carries 51 adaLN pairs the pruned DiT cannot wrap; the runner
+ absorbs them only when handed `--lora-adaln`. The panel dropped that flag
+ on 2026-08-14 and every v4 render since lost all 51 (Codex audit
+ 2026-09-16, finding 2). Detection is by header, never by filename."""
+
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory(prefix="phos-turbo-adaln-")
+ self.directory = Path(self.tmp.name)
+ self.saved = {name: getattr(P, name) for name in (
+ "_h3_turbo_dir", "H3_TURBO_LORA_MIN_BYTES",
+ "H3_TURBO_EMBEDDER_MIN_BYTES", "h3_supports_lora_adaln",
+ "h3_supports_lora", "h3_paths", "_h3_python", "H3_ROOT")}
+ P._h3_turbo_dir = lambda: self.directory
+ P.H3_TURBO_LORA_MIN_BYTES = 1
+ P.H3_TURBO_EMBEDDER_MIN_BYTES = 1
+ P.h3_supports_lora_adaln = lambda: True
+ _reset_dl_state()
+
+ def tearDown(self):
+ for name, value in self.saved.items():
+ setattr(P, name, value)
+ self.tmp.cleanup()
+ _reset_dl_state()
+
+ def v4(self) -> Path:
+ return _write_lora_fixture(self.directory / P.H3_TURBO_V4_FILE,
+ V4_ADALN, V4_OTHER)
+
+ def embedder(self) -> Path:
+ path = self.directory / P.H3_TURBO_EMBEDDER_FILE
+ path.write_bytes(b"embedder fixture")
+ return path
+
+ def test_header_count_is_the_detector(self):
+ self.assertEqual(P.h3_lora_adaln_pairs(self.v4()), 51)
+ plain = _write_lora_fixture(self.directory / "plain.safetensors",
+ [], V4_OTHER)
+ self.assertEqual(P.h3_lora_adaln_pairs(plain), 0)
+ # An A without its B is not a pair.
+ junk = self.directory / "junk.safetensors"
+ junk.write_bytes(b"not a safetensors file at all")
+ self.assertEqual(P.h3_lora_adaln_pairs(junk), 0)
+ self.assertEqual(P.h3_lora_adaln_pairs(self.directory / "nope"), 0)
+ self.assertEqual(P.h3_lora_adaln_pairs(None), 0)
+
+ def test_v4_with_companion_emits_lora_adaln(self):
+ v4, emb = self.v4(), self.embedder()
+ resolved = P.h3_turbo_paths()
+ self.assertEqual(resolved["adaln_pairs"], 51)
+ self.assertEqual(resolved["embedder"], emb)
+ self.assertEqual(P.h3_turbo_adaln_state(resolved), "absorbed")
+ self.assertEqual(P.h3_turbo_argv(resolved),
+ ["--lora", f"{v4}:1.0", "--lora-adaln", str(emb)])
+ status = P.h3_turbo_status()
+ self.assertEqual(status["adaln"],
+ {"pairs": 51, "embedder": str(emb), "state": "absorbed"})
+
+ def test_v4_without_companion_is_named_not_silent(self):
+ v4 = self.v4()
+ resolved = P.h3_turbo_paths()
+ self.assertIsNone(resolved["embedder"])
+ self.assertEqual(P.h3_turbo_adaln_state(resolved), "no_embedder")
+ self.assertEqual(P.h3_turbo_argv(resolved), ["--lora", f"{v4}:1.0"])
+
+ def test_old_runner_never_gets_the_flag(self):
+ v4, _ = self.v4(), self.embedder()
+ P.h3_supports_lora_adaln = lambda: False
+ resolved = P.h3_turbo_paths()
+ self.assertEqual(P.h3_turbo_adaln_state(resolved), "runner_old")
+ self.assertEqual(P.h3_turbo_argv(resolved), ["--lora", f"{v4}:1.0"])
+
+ def test_adapter_without_adaln_pairs_gets_no_flag(self):
+ # LightX2V repacks carry none; a companion on disk must not change that.
+ lx = _write_lora_fixture(self.directory / P.H3_TURBO_LORA_FILE,
+ [], V4_OTHER)
+ self.embedder()
+ resolved = P.h3_turbo_paths()
+ self.assertEqual(resolved["lora"], lx)
+ self.assertEqual(P.h3_turbo_adaln_state(resolved), "none")
+ self.assertEqual(P.h3_turbo_argv(resolved), ["--lora", f"{lx}:1.0"])
+
+ def test_the_real_v4_adapter_has_51_pairs_when_present(self):
+ real = Path("/Users/salo/AI/projects/hailuo-mlx/codex/models/turbo-lora/"
+ + P.H3_TURBO_V4_FILE)
+ if not real.is_file():
+ self.skipTest("v4 adapter not on this machine")
+ self.assertEqual(P.h3_lora_adaln_pairs(real), 51)
+
+ def test_render_dispatch_uses_the_argv_helper(self):
+ src = (ROOT / "mlx_ltx_panel.py").read_text(encoding="utf-8")
+ body = src[src.index("def run_h3_job_inner("):]
+ body = body[:body.index("\ndef ", 10)]
+ self.assertIn("cmd += h3_turbo_argv(turbo_paths)", body)
+ self.assertIn('h3_turbo_adaln_state(turbo_paths) == "no_embedder"', body)
+ # provenance: the checkpoint that ran, not the bf16 default path
+ self.assertIn('"model": str(_dit_path)', body)
+ self.assertNotIn('"model": str(paths["dit"])', body)
+
+ def test_fetch_embedder_uses_the_pack_script_and_is_non_fatal(self):
+ self.v4()
+ root = self.directory / "pack"
+ (root / "scripts").mkdir(parents=True)
+ (root / "scripts" / "fetch_time_embedder.py").write_text("# fixture")
+ P.H3_ROOT = root
+ P._h3_python = lambda: Path("/usr/bin/python3")
+ calls, logs = [], []
+
+ class Done:
+ returncode, stdout, stderr = 0, "", ""
+
+ def ok_runner(cmd, **kw):
+ calls.append(cmd)
+ Path(cmd[cmd.index("--out") + 1]).write_bytes(b"tensors")
+ return Done()
+
+ self.assertTrue(P._h3_turbo_fetch_embedder(self.directory, logs.append,
+ runner=ok_runner))
+ self.assertEqual(calls[0][1], str(root / "scripts" / "fetch_time_embedder.py"))
+ self.assertTrue((self.directory / P.H3_TURBO_EMBEDDER_FILE).is_file())
+ self.assertFalse(list(self.directory.glob("*.partial")))
+ # already there: no second fetch
+ self.assertTrue(P._h3_turbo_fetch_embedder(self.directory, logs.append,
+ runner=ok_runner))
+ self.assertEqual(len(calls), 1)
+
+ (self.directory / P.H3_TURBO_EMBEDDER_FILE).unlink()
+
+ class Fail:
+ returncode, stdout, stderr = 1, "", "HTTP 403"
+
+ logs.clear()
+ self.assertFalse(P._h3_turbo_fetch_embedder(
+ self.directory, logs.append, runner=lambda cmd, **kw: Fail()))
+ self.assertTrue(any("WARNING" in m and "HTTP 403" in m for m in logs))
+ self.assertFalse((self.directory / P.H3_TURBO_EMBEDDER_FILE).exists())
+
+ def test_install_on_an_existing_v4_fetches_only_the_companion(self):
+ self.v4()
+ P.h3_paths = lambda: {"missing": []}
+ P.h3_supports_lora = lambda: True
+ done = threading.Event()
+ seen = []
+
+ def fake_embedder(target_dir, push_log):
+ seen.append(target_dir)
+ done.set()
+ return True
+
+ result = P._h3_install_turbo(lambda _m: None,
+ download_fn=lambda *a: self.fail("no adapter download"),
+ embedder_fn=fake_embedder)
+ self.assertTrue(result["ok"])
+ self.assertTrue(result["started"])
+ self.assertTrue(result["embedder_only"])
+ self.assertTrue(done.wait(timeout=5))
+ self.assertEqual(seen, [self.directory])
+ # with the companion present, it is a plain "already installed"
+ self.embedder()
+ _reset_dl_state()
+ again = P._h3_install_turbo(lambda _m: None, download_fn=lambda *a: None,
+ embedder_fn=lambda *a: self.fail("refetch"))
+ self.assertFalse(again["started"])
+
+
class TestH3TurboPins(unittest.TestCase):
def _load_fetch_script(self):
spec = importlib.util.spec_from_file_location(
diff --git a/test_upscale_x2_tail.py b/test_upscale_x2_tail.py
new file mode 100644
index 0000000..4632678
--- /dev/null
+++ b/test_upscale_x2_tail.py
@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""LTX Upscale ×2 tail flash (2026-09-16) — and the frames it used to drop.
+
+Symptom: every ×2 of a 5 s 1024×576 H3 clip (2048×1152, 121 frames) blew its
+last 8 frames to near-white, with a clean horizontal edge 3/4 of the way
+down frame 112, on every seed and every source. 3 s sources (65 frames) and
+640×384 sources (1280×768) were clean.
+
+Cause: MLX's Metal conv3d addresses its output with 32-bit ints. The VAE
+decoder's last stage at that size is 128 × 121 × 288 × 512 = 2.28e9
+elements > 2**31, so the tail of the tensor is never written. Upstream only
+tiles a decode past an 8 GB MEMORY budget, and this one is 2.3 GB, so it ran
+in one pass. The helper now caps the ELEMENT count too.
+
+Second bug, same lane: the frame count rounded DOWN to LTX's 1+8k grid
+(124 → 121), and the audio mux used `-shortest`. Now the model renders the
+next grid length UP from a copy with the last frame held, and the result is
+cut back to the source's exact count and duration.
+
+No GPU: the helper functions are exec'd from source (the helper is a script
+with a blocking main loop), the tiling is checked against the vendored
+tiler's own tile layout, and the ffmpeg half runs on a tiny synthetic clip."""
+from __future__ import annotations
+
+import ast
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+import unittest.mock
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+sys.path.insert(0, str(ROOT))
+HELPER_SRC = (ROOT / "mlx_warm_helper.py").read_text(encoding="utf-8")
+INT32 = 2 ** 31
+
+try:
+ from ltx_core_mlx.model.video_vae import video_vae as _vv
+ from ltx_core_mlx.model.video_vae.tiling import prepare_tiles_for_decoding
+ HAVE_LTX = True
+except Exception: # noqa: BLE001
+ HAVE_LTX = False
+
+
+def _helper_ns() -> dict:
+ tree = ast.parse(HELPER_SRC)
+ names = {"_vae_decode_peak_elements", "_vae_decode_max_latent_frames",
+ "_int32_safe_decode_tiling"}
+ picked = [n for n in tree.body if isinstance(n, ast.FunctionDef) and n.name in names]
+ assert {n.name for n in picked} == names
+ consts = [n for n in tree.body if isinstance(n, ast.Assign)
+ and any(getattr(t, "id", "") == "_DECODE_MAX_ELEMENTS" for t in n.targets)]
+ assert len(consts) == 1
+ ns: dict = {}
+ exec(compile(ast.Module(body=consts + picked, type_ignores=[]), "helper", "exec"), ns)
+ return ns
+
+
+def _decoder_tensor_sizes(lat_f: int, h: int, w: int) -> list[int]:
+ """Every conv input (padded) and output the conv VAE decoder builds,
+ walked from VideoDecoder.__init__ / decode (video_vae.py)."""
+ sizes = []
+
+ def conv(c_in, c_out, f, hh, ww):
+ sizes.append(c_in * (f + 2) * (hh + 2) * (ww + 2))
+ sizes.append(c_out * f * hh * ww)
+
+ f, hh, ww = lat_f, h, w
+ conv(128, 1024, f, hh, ww) # conv_in
+ for _ in range(4):
+ conv(1024, 1024, f, hh, ww) # stage 0
+ conv(1024, 4096, f, hh, ww) # block 1
+ f, hh, ww = 2 * f - 1, 2 * hh, 2 * ww
+ for _ in range(4):
+ conv(512, 512, f, hh, ww) # stage 2
+ conv(512, 4096, f, hh, ww) # block 3
+ f, hh, ww = 2 * f - 1, 2 * hh, 2 * ww
+ for _ in range(8):
+ conv(512, 512, f, hh, ww) # stage 4
+ conv(512, 512, f, hh, ww) # block 5 (time only)
+ f = 2 * f - 1
+ for _ in range(12):
+ conv(256, 256, f, hh, ww) # stage 6
+ conv(256, 512, f, hh, ww) # block 7 (space only)
+ hh, ww = 2 * hh, 2 * ww
+ for _ in range(8):
+ conv(128, 128, f, hh, ww) # stage 8
+ conv(128, 48, f, hh, ww) # conv_out
+ sizes.append(3 * f * hh * 4 * ww * 4) # unpatchified pixels
+ return sizes
+
+
+class TheWrapIsWhereTheFlashIs(unittest.TestCase):
+ def test_the_measured_geometry_crosses_int32_and_the_clean_ones_do_not(self):
+ ns = _helper_ns()
+ peak = ns["_vae_decode_peak_elements"]
+ self.assertGreater(peak(16, 36, 64), INT32) # 2048×1152 × 121: flashes
+ self.assertLess(peak(9, 36, 64), INT32) # 2048×1152 × 65: clean
+ self.assertLess(peak(16, 24, 40), INT32) # 1280×768 × 121: clean
+ # The wrap lands in frame 112/113 — where every bad render breaks.
+ at = INT32 / (128 * 288 * 512)
+ self.assertTrue(112 < at < 114, at)
+
+ def test_the_peak_bounds_every_decoder_tensor(self):
+ ns = _helper_ns()
+ for lat_f, h, w in [(16, 36, 64), (17, 36, 64), (9, 36, 64), (16, 24, 40),
+ (13, 18, 32), (31, 45, 80), (2, 36, 64), (1, 12, 20)]:
+ self.assertEqual(max(_decoder_tensor_sizes(lat_f, h, w)),
+ ns["_vae_decode_peak_elements"](lat_f, h, w),
+ (lat_f, h, w))
+
+ def test_max_latent_frames_is_the_largest_safe_count(self):
+ ns = _helper_ns()
+ cap = ns["_DECODE_MAX_ELEMENTS"]
+ self.assertLess(cap, INT32)
+ for h, w in [(36, 64), (24, 40), (45, 80), (18, 32)]:
+ n = ns["_vae_decode_max_latent_frames"](h, w)
+ self.assertLessEqual(ns["_vae_decode_peak_elements"](n, h, w), cap)
+ self.assertGreater(ns["_vae_decode_peak_elements"](n + 1, h, w), cap)
+
+
[email protected](HAVE_LTX, "ltx_core_mlx not importable (run with the repo venv)")
+class TheGuardTilesOnlyWhatWouldWrap(unittest.TestCase):
+ def _cfg(self, shape, fps=24.0):
+ return _helper_ns()["_int32_safe_decode_tiling"](
+ _vv._compute_decode_tiling, shape, frame_rate=fps)
+
+ def test_upstream_alone_decodes_the_bad_clip_in_one_pass(self):
+ # The bug: the byte budget does not see it.
+ os.environ.pop("LTX2_VAE_DECODE_BUDGET_GB", None)
+ self.assertIsNone(_vv._compute_decode_tiling((1, 128, 16, 36, 64), frame_rate=24.0))
+
+ def test_small_decodes_keep_upstreams_answer(self):
+ os.environ.pop("LTX2_VAE_DECODE_BUDGET_GB", None)
+ for shape in [(1, 128, 16, 24, 40), (1, 128, 9, 36, 64), (1, 128, 16, 18, 32)]:
+ self.assertIsNone(self._cfg(shape), shape)
+
+ def test_every_tile_stays_under_the_cap_and_the_tiles_cover_the_clip(self):
+ os.environ.pop("LTX2_VAE_DECODE_BUDGET_GB", None)
+ ns = _helper_ns()
+ for f_lat, h, w in [(16, 36, 64), (17, 36, 64), (31, 36, 64), (61, 36, 64),
+ (31, 45, 80)]:
+ shape = (1, 128, f_lat, h, w)
+ cfg = self._cfg(shape)
+ self.assertIsNotNone(cfg, shape)
+ tiles = prepare_tiles_for_decoding(shape, cfg)
+ covered = set()
+ for t in tiles:
+ n = t.in_coords[2].stop - t.in_coords[2].start
+ self.assertLessEqual(ns["_vae_decode_peak_elements"](n, h, w),
+ ns["_DECODE_MAX_ELEMENTS"], (shape, n))
+ covered.update(range(t.out_coords[2].start, t.out_coords[2].stop))
+ self.assertEqual(covered, set(range(8 * f_lat - 7)), shape)
+
+ def test_a_budget_tiling_already_small_enough_is_kept(self):
+ os.environ["LTX2_VAE_DECODE_BUDGET_GB"] = "0.5"
+ try:
+ up = _vv._compute_decode_tiling((1, 128, 16, 36, 64), frame_rate=24.0)
+ self.assertEqual(self._cfg((1, 128, 16, 36, 64)).temporal_config.tile_size_in_frames,
+ up.temporal_config.tile_size_in_frames)
+ finally:
+ os.environ.pop("LTX2_VAE_DECODE_BUDGET_GB", None)
+
+
+class TheGuardIsWired(unittest.TestCase):
+ def test_installed_at_the_generate_choke_point(self):
+ i = HELPER_SRC.index("# ---- main loop ----")
+ j = HELPER_SRC.index('if action == "generate":', i)
+ block = HELPER_SRC[i:j]
+ self.assertIn('action.startswith(("generate", "extend"))', block)
+ self.assertIn("_install_decode_int32_guard()", block)
+
+ def test_the_installer_replaces_the_module_global_decode_and_stream_reads(self):
+ i = HELPER_SRC.index("def _install_decode_int32_guard")
+ body = HELPER_SRC[i:i + 2000]
+ self.assertIn("_vv._compute_decode_tiling = _guarded", body)
+ if HAVE_LTX:
+ import inspect
+ src = inspect.getsource(_vv.VideoDecoder.decode_and_stream)
+ self.assertIn("_compute_decode_tiling(", src)
+
+
+import mlx_ltx_panel as panel # noqa: E402
+
+
+class TheFramePlan(unittest.TestCase):
+ def test_grid_rounds_up(self):
+ g = panel.ltx_grid_frames_up
+ self.assertEqual([g(1), g(9), g(10), g(65), g(72), g(73), g(121), g(123), g(124), g(129)],
+ [9, 9, 17, 65, 73, 73, 121, 129, 129, 129])
+
+ def test_the_source_length_is_delivered(self):
+ plan = panel.upscale_frame_plan
+ # The owner's clip: 124 in, 124 out, rendered on 129. The form's
+ # stale 121 does not cut it any more.
+ self.assertEqual(plan(124, 121), (124, 129))
+ self.assertEqual(plan(124, None), (124, 129))
+ self.assertEqual(plan(123, "121"), (123, 129))
+ self.assertEqual(plan(73, 121), (73, 73))
+ self.assertEqual(plan(72, 121), (72, 73))
+ self.assertEqual(plan(121, 121), (121, 121))
+
+ def test_long_clips_are_covered_from_the_start_on_a_grid_that_fits(self):
+ plan = panel.upscale_frame_plan
+ self.assertEqual(plan(243, 121), (129, 129))
+ self.assertEqual(plan(243, 241), (241, 241))
+ self.assertEqual(plan(200, 200), (193, 193))
+ self.assertEqual(plan(0, 0), (49, 49))
+
+
+def _ffprobe(path, *entries, stream="v:0"):
+ out = subprocess.run(
+ [str(panel.FFPROBE), "-v", "error", "-select_streams", stream, "-count_frames",
+ "-show_entries", ",".join(entries), "-of", "json", str(path)],
+ capture_output=True, text=True, check=True).stdout
+ return (json.loads(out).get("streams") or [{}])[0]
+
+
+def _rgb_frames(path, w, h):
+ raw = subprocess.run([str(panel.FFMPEG), "-v", "error", "-i", str(path),
+ "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+ capture_output=True, check=True).stdout
+ n = w * h * 3
+ return [raw[i:i + n] for i in range(0, len(raw), n)]
+
+
[email protected](Path(str(panel.FFMPEG)).is_file(), "ffmpeg not installed")
+class TheClipGoesInAndComesOutTheSameLength(unittest.TestCase):
+ def setUp(self):
+ self.tmp = Path(tempfile.mkdtemp(prefix="x2tail_"))
+ self.src = self.tmp / "src.mp4"
+ # 124 frames at 24 fps, H3's 5 s shape, with a 5.2 s soundtrack.
+ subprocess.run([str(panel.FFMPEG), "-y", "-v", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=64x36:rate=24",
+ "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000",
+ "-frames:v", "124", "-t", "5.2", "-c:v", "libx264",
+ "-pix_fmt", "yuv420p", "-c:a", "aac", str(self.src)],
+ check=True, capture_output=True)
+
+ def tearDown(self):
+ import shutil
+ shutil.rmtree(self.tmp, ignore_errors=True)
+
+ def _render(self, model_src, frames, name, audio_secs):
+ """Stand-in for the helper: the model's clip at ×2, with the model's
+ own (discarded) audio, `frames` long."""
+ out = self.tmp / name
+ subprocess.run([str(panel.FFMPEG), "-y", "-v", "error", "-i", str(model_src),
+ "-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo",
+ "-map", "0:v", "-map", "1:a", "-vf", "scale=128:72",
+ "-frames:v", str(frames), "-af", f"atrim=end={audio_secs}",
+ "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac", str(out)],
+ check=True, capture_output=True)
+ return out
+
+ def test_hold_tail_is_lossless_and_holds_the_last_frame(self):
+ held = self.tmp / "held.mp4"
+ subprocess.run(panel._upscale_hold_tail_cmd(str(self.src), str(held), 124, 129),
+ check=True, capture_output=True)
+ self.assertEqual(panel._probe_video_frames(str(held)), 129)
+ src = _rgb_frames(self.src, 64, 36)
+ got = _rgb_frames(held, 64, 36)
+ self.assertEqual(len(src), 124)
+ self.assertEqual(got[:124], src)
+ for i in range(124, 129):
+ self.assertEqual(got[i], src[123], i)
+
+ def test_trimmed_render_is_124_frames_with_the_source_sound(self):
+ held = self.tmp / "held.mp4"
+ subprocess.run(panel._upscale_hold_tail_cmd(str(self.src), str(held), 124, 129),
+ check=True, capture_output=True)
+ render = self._render(held, 129, "x2.mp4", 5.375)
+ self.assertEqual(panel._probe_video_frames(str(render)), 129)
+ with unittest.mock.patch.object(panel, "output_codec_settings",
+ return_value={"pix_fmt": "yuv444p", "crf": "0",
+ "preset": "lossless"}):
+ kept = panel._upscale_finish(render, str(self.src), frames=124, fps=24.0,
+ trim=True)
+ self.assertTrue(kept)
+ v = _ffprobe(render, "stream=nb_read_frames,width,height,duration")
+ self.assertEqual(int(v["nb_read_frames"]), 124)
+ self.assertEqual((v["width"], v["height"]), (128, 72))
+ self.assertAlmostEqual(float(v["duration"]), 124 / 24, places=2)
+ a = _ffprobe(render, "stream=duration,codec_type", stream="a:0")
+ self.assertEqual(a.get("codec_type"), "audio")
+ self.assertAlmostEqual(float(a["duration"]), 124 / 24, delta=0.03)
+ self.assertEqual(len(_rgb_frames(render, 128, 72)), 124)
+
+ def test_short_audio_no_longer_costs_a_frame(self):
+ # A 121-frame source whose sound ends early: `-shortest` used to cut
+ # the picture to the sound.
+ src = self.tmp / "short_audio.mp4"
+ subprocess.run([str(panel.FFMPEG), "-y", "-v", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=64x36:rate=24",
+ "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000",
+ "-map", "0:v", "-map", "1:a", "-frames:v", "121",
+ "-af", "atrim=end=4.9", "-c:v", "libx264", "-pix_fmt", "yuv420p",
+ "-c:a", "aac", str(src)], check=True, capture_output=True)
+ self.assertEqual(panel._probe_video_frames(str(src)), 121)
+ render = self._render(src, 121, "x2b.mp4", 5.0)
+ self.assertEqual(panel._probe_video_frames(str(render)), 121)
+ self.assertTrue(panel._upscale_finish(render, str(src), frames=121, fps=24.0,
+ trim=False))
+ self.assertEqual(int(_ffprobe(render, "stream=nb_read_frames")["nb_read_frames"]), 121)
+ a = _ffprobe(render, "stream=duration", stream="a:0")
+ self.assertAlmostEqual(float(a["duration"]), 121 / 24, delta=0.03)
+
+ def test_the_upscale_lane_feeds_the_held_copy_and_cuts_back(self):
+ src = panel.Path(panel.__file__).read_text(encoding="utf-8")
+ i = src.index(' if mode == "upscale":')
+ j = src.index(' if mode == "ingredients":', i)
+ body = src[i:j]
+ self.assertIn("upscale_frame_plan(src_frames", body)
+ self.assertIn('"video_conditioning": [[model_src, keep]]', body)
+ self.assertIn('"source_video": model_src if start_from == "source"', body)
+ self.assertIn("trim=frames != out_frames", body)
+ self.assertNotIn("-shortest", src[src.index("def _upscale_finish_cmd"):
+ src.index("def _upscale_finish(")].split('"""', 2)[2])
+
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/webapp/index.html b/webapp/index.html
index baf70f8..57dfc4b 100644
--- a/webapp/index.html
+++ b/webapp/index.html
@@ -1207,7 +1207,7 @@
</div>
<div class="pill-group cols-2" id="h3TurboGroup">
<button type="button" class="pill-btn active" data-h3-turbo="0"
- title="This shape's own sampler — 9 sigma points, 8 forwards per window.">
+ title="This shape's own sampler — its tuned sigma points per window.">
<span>Standard</span><span class="sub" id="h3StdPillSub"></span>
</button>
<button type="button" class="pill-btn" data-h3-turbo="1" id="h3TurboPill">
@@ -1242,8 +1242,9 @@
<div class="h3-turbo-note" id="h3LoraSlotNote"></div>
</div>
- <!-- H3 sampler depth. Every cell bakes 9 steps (8 forwards per
- window) — the validated speed/quality point; the official
+ <!-- H3 sampler depth. Cells bake 9 steps (8 forwards per window),
+ except High and dense 10 s, which bake 16 (15 forwards) — High
+ since the 2026-09-16 gym A/B; the official
reference recipe runs 20. Four honest pills beat an unbounded
numeric box, and the chips above re-price live when one is
pinned, so the multiplier does not have to live in a tooltip. -->
diff --git a/webapp/js/engines.js b/webapp/js/engines.js
index 00dd0e7..45e3767 100644
--- a/webapp/js/engines.js
+++ b/webapp/js/engines.js
@@ -184,7 +184,7 @@ function h3CurrentCell() {
if (!st) return;
let savedSt = null;
try { savedSt = localStorage.getItem('phos_h3_steps'); } catch (e) {}
- if (savedSt && ['auto', '12', '16', '20'].indexOf(savedSt) !== -1) st.value = savedSt;
+ if (savedSt) st.value = h3NormalizeSteps(savedSt);
// And Turbo — but only restore an ON state when this install can actually
// serve it. A user who downloaded the adapter, deleted it and reloaded must
// come back on Standard, not on a mode that would fail at queue time.
@@ -282,13 +282,32 @@ document.querySelectorAll('#h3OrientationGroup [data-h3-orientation]').forEach(b
// 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.
+// Any count the server accepts (4-30) is kept: a replayed render pinned at 21
+// or 7 must replay at 21 or 7, not silently at the target's Auto. No pill lights
+// for such a count and the row hint names it instead.
+function h3NormalizeSteps(v) {
+ const t = String(v == null ? '' : v).trim().toLowerCase();
+ if (/^\d+$/.test(t)) {
+ const n = parseInt(t, 10);
+ if (n >= 4 && n <= 30) return String(n);
+ }
+ return 'auto';
+}
function setH3Steps(v) {
- const allowed = ['auto', '12', '16', '20'];
- v = allowed.indexOf(String(v)) !== -1 ? String(v) : 'auto';
+ v = h3NormalizeSteps(v);
const inp = document.getElementById('h3_steps');
if (inp) inp.value = v;
- document.querySelectorAll('#h3StepsGroup [data-h3-steps]').forEach(b =>
- b.classList.toggle('active', b.dataset.h3Steps === v));
+ let lit = false;
+ document.querySelectorAll('#h3StepsGroup [data-h3-steps]').forEach(b => {
+ const on = b.dataset.h3Steps === v;
+ lit = lit || on;
+ b.classList.toggle('active', on);
+ });
+ const hint = document.querySelector('#h3StepsRow .cz-label-hint');
+ if (hint) {
+ hint.textContent = lit ? "Auto = this shape's tuned count"
+ : ('Pinned at ' + v + ' (from a saved render) · pick a pill to change');
+ }
// Mirror the resolved count into the shared hidden `steps` so the queue
// card and the estimate line read the truth (make_job re-stamps anyway).
const tier = h3CurrentCell();
@@ -397,6 +416,31 @@ function h3TurboPillLabel() {
return 'Turbo · ' + h3TurboPillSub();
}
+// The sampler depth each shape runs is per CELL (High runs 16 sigma points,
+// Draft/Standard/Native 9, dense 10 s 16), so the Standard and Auto tooltips
+// read it from the cell rather than printing one number for every shape.
+function _h3SyncSamplerTitles() {
+ const cell = h3CurrentCell();
+ const pts = (cell && cell.steps) || 9;
+ const fwd = Math.max(1, pts - 1);
+ const std = document.querySelector('#h3TurboGroup [data-h3-turbo="0"]');
+ if (std) std.title = "This shape's own sampler — " + pts + ' sigma points, '
+ + fwd + ' forwards per window.';
+ const auto = document.querySelector('#h3StepsGroup [data-h3-steps="auto"]');
+ if (auto) auto.title = "This shape's tuned count — " + pts + ' sigma points ('
+ + fwd + ' forwards per window) at this canvas.';
+ if (!cell || !cell.eta_min) return;
+ document.querySelectorAll('#h3StepsGroup [data-h3-steps]').forEach(b => {
+ const n = b.dataset.h3Steps;
+ if (!/^\d+$/.test(n)) return;
+ const k = h3CellEtaMin(cell, { turbo: false, steps: n }) / cell.eta_min;
+ const rel = Math.abs(k - 1) < 0.05 ? 'the same time as Auto at this shape'
+ : '~' + k.toFixed(1) + '× Auto\'s render time at this shape';
+ b.title = n + ' sigma points (' + (parseInt(n, 10) - 1) + ' forwards) — ' + rel
+ + (n === '20' ? '. The official reference recipe.' : '.');
+ });
+}
+
function renderH3Turbo() {
const row = document.getElementById('h3TurboRow');
const pill = document.getElementById('h3TurboPill');
@@ -407,6 +451,7 @@ function renderH3Turbo() {
if (sub) sub.textContent = h3SpeedSub('turbo');
const stdSub = document.getElementById('h3StdPillSub');
if (stdSub) stdSub.textContent = h3SpeedSub('standard');
+ _h3SyncSamplerTitles();
pill.classList.toggle('needs-download', !t.downloaded);
// Two different kinds of number, and the tooltip must not blur them: the ONE
// shape that has actually been rendered with the adapter end to end says so,
@@ -445,7 +490,7 @@ function _h3SyncStepsEnabled() {
});
if (row) {
row.style.opacity = on ? '.5' : '';
- row.title = on ? 'Turbo pins the sampler at 4 steps.' : '';
+ row.title = on ? ('Turbo pins the sampler at ' + (h3TurboState().steps || 7) + ' sigma points.') : '';
}
}
diff --git a/webapp/js/queue.js b/webapp/js/queue.js
index 1e23036..6ae4d49 100644
--- a/webapp/js/queue.js
+++ b/webapp/js/queue.js
@@ -98,6 +98,10 @@ function h3FinishSetTier(key) {
// seed, image. A field that isn't in that dict silently no-ops on /queue/add,
// which is the known trap in this codebase; adding a key here means adding it
// there too.
+function _h3FinishSteps(v) {
+ const n = parseInt(String(v == null ? '' : v), 10);
+ return (Number.isFinite(n) && n >= 4 && n <= 30) ? String(n) : 'auto';
+}
function h3FinishFieldsFromSidecar(p, tierKey) {
if (!p || typeof p !== 'object') return null;
if (p.engine !== 'h3') return null;
@@ -133,11 +137,20 @@ function h3FinishFieldsFromSidecar(p, tierKey) {
// matters for sidecars written before h3_upscale existed.
h3_upscale: (typeof p.h3_upscale === 'string' && p.h3_upscale) ? p.h3_upscale : '',
// The sidecar stores the resolved override as an int, 0 = "the cell's own
- // count". The form's pills speak 'auto' | '12' | '16' | '20'; anything
- // outside that set (an older sidecar, a curl'd job) reads as auto so the
- // target canvas's tuned count is used rather than a depth no pill can show.
- h3_steps: (['12', '16', '20'].indexOf(String(p.h3_steps)) !== -1)
- ? String(p.h3_steps) : 'auto',
+ // count" (Auto, which follows the TARGET canvas). Any other count the
+ // server accepts (4-30) is a deliberate pin and carries over as-is, even
+ // when no pill shows it.
+ h3_steps: _h3FinishSteps(p.h3_steps),
+ // The adapters and the framing are part of the recipe being finished.
+ // Absent `loras` means the source ran without any: the Finish must clear
+ // whatever the picker holds now, not inherit it.
+ loras: Array.isArray(p.loras)
+ ? p.loras.filter(l => l && l.path)
+ .map(l => ({ path: String(l.path),
+ strength: (typeof l.strength === 'number') ? l.strength : 1.0 }))
+ : [],
+ h3_orientation: (p.h3_orientation === 'portrait') ? 'portrait' : 'landscape',
+ h3_lora_slot: (p.h3_lora_slot === 'user') ? 'user' : 'turbo',
// Turbo carries over: a draft judged with the 4-step sampler should be
// finished with it too, or the Finish render is a different recipe as well
// as a different canvas. setH3Turbo re-checks availability, so a sidecar
@@ -287,6 +300,10 @@ async function h3FinishActive() {
}
}
if (fields.h3_upscale && typeof setH3Upscale === 'function') setH3Upscale(fields.h3_upscale);
+ // The source's adapters, not whatever the picker holds now (an empty list
+ // clears it), and its framing BEFORE the shape stamps geometry.
+ _restoreLoraPicker(fields.loras);
+ if (typeof setH3Orientation === 'function') setH3Orientation(fields.h3_orientation);
if (typeof setH3Steps === 'function') setH3Steps(fields.h3_steps);
// Turbo before the shape: setH3Turbo forces the Steps pills back to 'auto',
// and setH3Tier below re-reads them when it stamps the resolved count.
@@ -301,6 +318,9 @@ async function h3FinishActive() {
if (typeof setH3ChainPrompts === 'function') {
try { setH3ChainPrompts(fields.h3_chain_prompts); } catch (e) {}
}
+ // After Turbo and the picker: the slot row re-renders from both and resets
+ // itself when there is no conflict.
+ if (typeof setH3LoraSlot === 'function') { try { setH3LoraSlot(fields.h3_lora_slot); } catch (e) {} }
// Seed after the shape for the same reason it comes last in loadParams:
// nothing downstream may quietly re-randomise it.
document.getElementById('seed').value = fields.seed;
@@ -3131,15 +3151,19 @@ function stageMayAutoSelectOutput() {
}
function selectOutput(path, options) {
options = options || {};
- // AUTOPLAY IS FOR A CLICK, NOT FOR BOOT. The stage selects the newest
- // output on load and after every refresh or filter change; those used to
- // build the player with `autoplay`, so the panel opened already playing
- // the last clip, sound and all. A selection the person did not make shows
- // the clip paused on its first frame; a click plays.
- const autoplay = options.autoplay !== false;
activePath = path;
const _uev = (typeof window !== 'undefined') ? window.event : null;
const userSelected = !!(_uev && _uev.isTrusted);
+ // AUTOPLAY IS FOR A CLICK, NOT FOR BOOT. The stage selects outputs on its
+ // own in many places — the newest clip on load, a storyboard putting its
+ // film's newest shot up on every poll, the clip coming back after a live
+ // preview, a finished take handed over. Each of those used to build the
+ // player with `autoplay`, so the panel kept opening with a clip playing,
+ // sound and all. The rule is decided HERE, once, not at each caller: only a
+ // real click or key press plays; every other selection shows the clip
+ // paused on its first frame. `autoplay: true` forces it, `false` forbids it.
+ const autoplay = options.autoplay === true
+ || (options.autoplay !== false && userSelected);
if (userSelected) window._stagePlaybackIntentAt = Date.now();
// The credit names the weights that made THIS clip.
if (typeof updateModelCredit === 'function') { try { updateModelCredit(path); } catch (e) {} }
@@ -3537,6 +3561,33 @@ function setUpscalePreset(btn) {
b.classList.toggle('active', b === btn));
}
+// Put a saved {path, strength} list into the LoRA picker (Load Params and
+// Finish share this). Re-decorated with name + trigger words from
+// _knownUserLoras so the chips render nicely.
+function _restoreLoraPicker(list) {
+ if (!Array.isArray(list)) return;
+ _activeLoras = list.map(l => {
+ const path = l && l.path;
+ const strength = (l && typeof l.strength === 'number') ? l.strength : 1.0;
+ const meta = (Array.isArray(_knownUserLoras)
+ ? _knownUserLoras.find(u => u.path === path)
+ : null) || {};
+ return {
+ path,
+ strength,
+ name: meta.name || (path ? path.split('/').pop() : 'LoRA'),
+ trigger_words: meta.trigger_words || [],
+ compatible_modes: meta.compatible_modes || ['unknown'],
+ };
+ }).filter(x => x.path);
+ if (typeof renderLorasList === 'function') {
+ try { renderLorasList(); } catch (_) {}
+ }
+ if (typeof _serializeLoras === 'function') {
+ try { _serializeLoras(); } catch (_) {}
+ }
+}
+
async function loadParams() {
if (!activePath) return;
const r = await fetch('/sidecar?path='+encodeURIComponent(activePath));
@@ -3836,28 +3887,7 @@ async function loadParams() {
// without fusion (no face/style transfer). Wire shape on the sidecar is
// a list of {path, strength}; we re-decorate with `name` + `trigger_words`
// from _knownUserLoras when available so the chip renders nicely.
- if (lorasForPicker) {
- _activeLoras = lorasForPicker.map(l => {
- const path = l.path;
- const strength = (typeof l.strength === 'number') ? l.strength : 1.0;
- const meta = (Array.isArray(_knownUserLoras)
- ? _knownUserLoras.find(u => u.path === path)
- : null) || {};
- return {
- path,
- strength,
- name: meta.name || (path ? path.split('/').pop() : 'LoRA'),
- trigger_words: meta.trigger_words || [],
- compatible_modes: meta.compatible_modes || ['unknown'],
- };
- }).filter(x => x.path);
- if (typeof renderLorasList === 'function') {
- try { renderLorasList(); } catch (_) {}
- }
- if (typeof _serializeLoras === 'function') {
- try { _serializeLoras(); } catch (_) {}
- }
- }
+ if (lorasForPicker) _restoreLoraPicker(lorasForPicker);
// ---- Engine + engine-specific settings ----------------------------------
// Params restored geometry and prompt but NOT the engine, so loading an LTX
@@ -4547,6 +4577,22 @@ document.getElementById('genForm').addEventListener('submit', async e => {
if (!lower.includes('non_diegetic_music')) {
fd.set('prompt', original.trim() + '\n\nnon_diegetic_music: N/A');
}
+ // A chained length sends its own prompt per window, and a WRITTEN box
+ // replaces the main prompt for that window — so the field has to ride
+ // in every written box too (blank boxes inherit the main prompt above).
+ const cpRaw = String(fd.get('h3_chain_prompts') || '');
+ if (cpRaw.trim()) {
+ try {
+ const cps = JSON.parse(cpRaw);
+ if (Array.isArray(cps)) {
+ fd.set('h3_chain_prompts', JSON.stringify(cps.map(x => {
+ const t = String(x == null ? '' : x);
+ if (!t.trim() || t.toLowerCase().includes('non_diegetic_music')) return t;
+ return t.trim() + '\n\nnon_diegetic_music: N/A';
+ })));
+ }
+ } catch (_) { /* not JSON (a hand-rolled ' ||| ' string): leave it */ }
+ }
} else {
const constraint = ' Audio: voice and ambient sounds only, no music, no soundtrack, no score, no melody.';
if (!lower.includes('no music')) {