Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.
Python ai-filmmakingai-videoai-video-generatorapple-siliconhailuoimage-to-videolip-synclocal-ailora-trainingltx-2ltx-2-5ltx-videomacosminimax-h3mlxmusic-generationoffline-aipinokiotext-to-videovideo-generation
"""/queue family routes — moved out of the chain (slice 4).
Bodies are verbatim from mlx_ltx_panel.py's do_GET/do_POST chains except
the two mechanical renames the move forces: `self` -> `h`, and panel
globals -> `P.<name>`. See panel/routes_stats.py for the pattern and
panel/__init__.py for why P is assigned rather than imported.
"""
from __future__ import annotations
import threading
from urllib.parse import parse_qs
from panel.routes import get, post
P = None # the running mlx_ltx_panel module; assigned at wiring time
# SAFETY-7: one recovery join at a time owns STATE["take_join_pgid"].
_TAKE_JOIN_LOCK = threading.Lock()
@get("/status")
def get_status(h, parsed) -> None:
qs = P.parse_qs(parsed.query)
include_hidden = qs.get("include_hidden", ["0"])[0] == "1"
# Deep-snapshot STATE under lock — payload built with refs only
# is racy when JSON serialization happens after lock release
# (worker thread could mutate current/queue mid-encode and we'd
# ship torn state to the browser).
import copy as _copy
with P.LOCK:
avg = P._avg_elapsed()
avg_image = P._avg_elapsed("image")
avg_video = P._avg_elapsed("video")
payload = _copy.deepcopy({
"running": P.STATE["running"], "paused": P.STATE["paused"],
"paused_reason": P.STATE.get("paused_reason"),
"current": P.STATE["current"], "queue": P.STATE["queue"],
"history": P.STATE["history"][:P.HISTORY_API_LIMIT], "log": P.STATE["log"],
"pid": P.STATE["pid"], "pgid": P.STATE["pgid"],
})
hidden_count = len(P.HIDDEN_PATHS)
# Human title per job, derived at read time (old history included).
for _j in ([payload["current"]] if payload.get("current") else []) + \
list(payload.get("queue") or []) + list(payload.get("history") or []):
try:
_p = _j.get("params") or {}
_j["title"] = P.clip_title.display_title(_p.get("prompt"), _p.get("label") or _j.get("label"))
except Exception:
pass
# Polling fast path — newest 60 only. outputs_total tells the
# carousel header "X older outputs not shown" so the "Show all"
# button can surface them via the /outputs endpoint.
_outs, _outs_total = P.list_outputs(
include_hidden=include_hidden, limit=60, return_total=True,
)
payload["outputs"] = _outs
payload["outputs_total"] = _outs_total
payload["hidden_count"] = hidden_count
# The one-time "star us on GitHub" card (owner, 2 Nov 2026): true only
# between the fifth finished render and the page putting the card up.
payload["star_prompt_due"] = P.star_prompt_due()
# Storyboards — one line per board. Three jobs, all of them cheap:
# the `S03/12` badge on a queue card needs the denominator, the tab
# count during an overnight run needs `running`, and `To film` in
# the player overlay stays hidden until this list is non-empty
# (rule 5 — with no film in progress the panel looks exactly as it
# did yesterday).
payload["storyboards"] = P._sb_all_summaries()
payload["memory"] = P.get_memory()
payload["comfy_pids"] = P.find_comfy_pids()
payload["server_now"] = P.time.time()
payload["avg_elapsed_sec"] = avg
# v3.0.7 (P2): surface the installed ltx-2-mlx version (from the
# helper's ready event) so every bug report — not just a mismatch
# log — carries what's actually running. Empty until the helper
# has booted at least once this session.
payload["ltx_version"] = P.HELPER.ready_info.get("ltx_version")
payload["ltx_version_expected"] = P.HELPER.ready_info.get("ltx_version_expected")
payload["ltx_version_match"] = P.HELPER.ready_info.get("ltx_version_match")
# Runtime fingerprint (mlx/chip/macOS) for triaging the "mosaic"
# MLX-numerical bug — surfaces in every bug report's /status.
payload["mlx_version"] = P.HELPER.ready_info.get("mlx_version")
payload["mlx_metal_version"] = P.HELPER.ready_info.get("mlx_metal_version")
payload["chip"] = P.HELPER.ready_info.get("chip")
payload["macos"] = P.HELPER.ready_info.get("macos")
# #44: null on a healthy machine. Non-null means this boot hit the
# Metal GPU watchdog during prompt encoding and Gemma is now
# encoding at the shorter padded length — the single most useful
# field on a "my prompts feel weaker" follow-up report.
payload["gemma_max_length"] = P.HELPER.gemma_max_length
# Per-kind avg ETA: image jobs are 30s–2min, video jobs are
# 5–30min. Computing queue ETA from one mixed avg makes an
# image queued after a few videos show "~30 min" — the
# videos drown out the truth. Use the kind-specific avg per
# queued job and fall back to category-appropriate defaults
# when history is empty (90s for images, 420s for videos).
def _eta_for(job: dict) -> float:
params = job.get("params") or {}
# VC-26: prefer the PRICED number the quality chips themselves show
# (LTX_TIERS/H3_TIERS eta_min) over the coarse per-kind average —
# it is the same table VC-28 already made honest, and a queue row
# showing a different number than the chip it was submitted from
# would just be a second class of the VC-28 bug.
priced = P.job_priced_eta_sec(params)
if priced is not None:
return priced
if params.get("engine") == "music":
return P.music_estimate(params["music_quality"], params["music_max_seconds"])["eta_sec"]
if params.get("engine") == "speech":
return P.speech_estimate(params.get("speech_text") or "", params.get("speech_speed") or 1.0)["eta_sec"]
if params.get("mode") == "image":
return float(avg_image) if avg_image else 90.0
return float(avg_video) if avg_video else 420.0
# Stamped per-row (VC-26: "an ETA per job") as well as summed for the
# existing total — one call per job either way, just captured once.
for _j in payload["queue"]:
_j["eta_sec"] = round(_eta_for(_j))
payload["eta_sec"] = round(sum(_j["eta_sec"] for _j in payload["queue"]))
# Y1.039 — per-job progress for the Now-card. Phase-aware,
# config-bucketed ETA, denoise-step extrapolation. Replaces the
# old elapsed/global-avg ratio that mis-paced Quick/High renders.
#
# Train jobs OWN their own progress dict — the trainer writes
# step / phase / eta directly into STATE["current"]["progress"]
# at runtime (see run_train_job_inner around line 5212 for the
# face phase and 5461 for the voice phase). _compute_progress
# is built around the video helper's log-tail format and would
# blindly stamp a "phase=setup" snapshot on top of the trainer's
# real "Training face · step N / total", making the Now card
# appear stuck at Loading pipeline. Skip the override when the
# job mode is "train".
#
# Hailuo H3 renders are in the SAME boat and for the same reason:
# run_h3_job_inner writes its own phase + step progress from the
# staged runner's stdout ("== joint_denoise ==", "step 3/8: 57.9s"),
# which _compute_progress can't parse — leaving the Now card on
# "Loading pipeline" for the whole render. Caught in validation.
if payload.get("current"):
_cur_params = (payload["current"].get("params") or {})
_mode = (_cur_params.get("mode") or "").lower()
_engine = (_cur_params.get("engine") or "ltx").lower()
_waiting = payload["current"].get("waiting_note")
if _waiting:
# 4.17.4: a voice-only Lip-sync job holding for the separator
# install says so, instead of "Loading pipeline" at 0 %.
_started = payload["current"].get("started_ts") or 0
payload["current"]["progress"] = {
"phase": "waiting", "pct": 0, "phase_label": str(_waiting),
"elapsed_sec": max(0.0, P.time.time() - _started) if _started else 0,
}
elif _mode != "train" and _engine not in ("h3", "music", "speech"):
payload["current"]["progress"] = P._compute_progress(
payload["current"], payload.get("log") or [],
)
elif _engine == "h3":
# The H3 runner owns its progress object, so preserve it
# and layer the separate h3-live-preview/1 file contract
# onto the snapshot. This executes in the existing status
# poll; there is no preview-specific request or timer.
_h3_progress = dict(payload["current"].get("progress") or {})
_h3_progress.update(P._h3_preview_progress(payload["current"]))
payload["current"]["progress"] = _h3_progress
payload["helper"] = {
"alive": P.HELPER.is_alive(), "pid": P.HELPER.pid(),
"low_memory": P.HELPER_LOW_MEMORY == "true",
"idle_timeout_sec": P.HELPER_IDLE_TIMEOUT,
}
# Completeness checks come from the shared required_files.json so
# the menu, the UI, and the run-time job validator all agree on
# what counts as "installed". Single source of truth — see the
# _load_required_files() helper near the top of this file.
_q8_missing = P.q8_missing_files()
_base_missing = P.base_missing()
# q8_available consults BOTH layers (local + HF cache) via
# q8_available_anywhere() so the FFLF/Extend/HQ gate agrees
# with the model browser modal. Closes issue #9 (oo2music).
# q8_missing keeps reporting local-dir-missing so the user
# can still see what would be needed for a fresh install;
# we zero it out when Q8 is reachable via cache so the UI
# doesn't show a spurious "missing files" warning alongside
# an enabled FFLF button.
# The UI reads q8_available to enable High / Extend / Keyframe /
# FFLF. Those need the HQ add-on as well as the pack, so a pack-only
# answer would light the pill up and let the job fail at load time
# -- the same wave-through e870061 closed, moved to the UI layer.
# For 2.3 `hq_addon_missing()` is [] and this is byte-for-byte the
# old expression.
_hq_addon_missing = P.hq_addon_missing()
_q8_available = P.q8_available_anywhere() and not _hq_addon_missing
payload["q8_available"] = _q8_available
payload["q8_missing"] = [] if _q8_available else _q8_missing
# THE Q8 WEIGHTS PACK, on its own — distinct from `q8_available`
# above, which folds in the HQ add-on because High / Extend /
# Keyframe genuinely need both.
#
# Characters need the PACK and not the add-on: on 2.5 they render on
# q8 + distilled, which is the recipe every graded 2.5 character
# clip ran. Reading `q8_available` for them would tell a user who
# has the full 30 GB pack that they must "Install Q8 (30 GB)"
# because a DIFFERENT 29.5 GB download is absent — the pack they
# already have, demanded again, to run a path that does not use the
# missing file. One conflated boolean, two very different questions.
payload["q8_pack_available"] = P.q8_available_anywhere()
payload["q8_pack_missing"] = _q8_missing
# Reported separately so the Models page can say WHICH download is
# the one standing between the user and the High tier.
payload["hq_addon_missing"] = _hq_addon_missing
payload["hq_surface_missing"] = P.hq_surface_missing()
payload["q8_path"] = str(P.pack_path("q8"))
payload["base_available"] = not _base_missing
payload["base_missing"] = _base_missing
path_errors = [P.model_path_problem(P._deferred_repo(k), write=bool(_base_missing))
for k in P.capability_repo_keys("render")]
payload["model_path_error"] = next((e for e in path_errors if e), "")
# Repo-level counts for the header pill — granular view that
# matches the modal's per-repo rows (Q4 + Gemma + Q8 = 3 in the
# default manifest). Avoids the pill claiming "2/2 ready" while
# the modal shows three rows.
#
# VC-32: this used to count ALL of required_files.json's repos (12,
# once the 2.5 generation and four IC-LoRA/tae extras joined the 2.3
# trio the comment above still describes) — so a complete, working 2.5
# install with no IC-LoRAs read "models 4/12", and a partial-but-
# correctly-green pill (every REQUIRED file present) still showed a
# scary-looking fraction. relevant_repo_keys() scopes this to the
# ACTIVE generation's own packs plus the version-agnostic extras —
# never another generation's base pack the install isn't running.
_repo_snap = P.repo_status_list()
_relevant_keys = P.relevant_repo_keys()
_relevant_snap = [r for r in _repo_snap if r.get("key") in _relevant_keys]
payload["repos_total"] = len(_relevant_snap)
payload["repos_ready"] = sum(1 for r in _relevant_snap if r.get("complete"))
# Structural integrity of installed weights — corrupt/partial
# safetensors decode to a garbage "mosaic". Cached + header-only.
payload["model_integrity"] = P._model_integrity(force=False)
with P._DEEP_VERIFY_LOCK:
payload["deep_verify"] = {
"active": P._DEEP_VERIFY["active"],
"progress": P._DEEP_VERIFY["progress"],
"result": P._DEEP_VERIFY["result"],
}
# Hardware tier — UI uses this to disable mode pills / quality
# buttons / show a helpful banner explaining what this Mac can
# and can't do. Detected once at startup; the override env
# var lets users force a tier for testing.
payload["tier"] = {
"key": P.SYSTEM_TIER,
"label": P.SYSTEM_CAPS["label"],
"ram_label": P.SYSTEM_CAPS["ram_label"],
"tagline": P.SYSTEM_CAPS["tagline"],
"blurb": P.SYSTEM_CAPS["blurb"],
"allows_q8": P.SYSTEM_CAPS["allows_q8"],
"allows_keyframe": P.SYSTEM_CAPS["allows_keyframe"],
"allows_extend": P.SYSTEM_CAPS["allows_extend"],
"t2v_max_dim": P.SYSTEM_CAPS["t2v_max_dim"],
"i2v_max_dim": P.SYSTEM_CAPS["i2v_max_dim"],
"keyframe_max_dim": P.SYSTEM_CAPS["keyframe_max_dim"],
"extend_max_dim": P.SYSTEM_CAPS["extend_max_dim"],
# VC-12 / SYS-20: computed live from the same model the Quality
# chips use, not the old hand-typed CAPABILITIES[tier]["times"]
# table that disagreed with them on every tier.
"times": P.honest_tier_times(),
# VA-11 / VA-12: keyframe/extend price the ACTUAL pipeline that
# runs (Q8 two-stage at a clamped canvas; the extend step count),
# not whatever Quality pill happens to be selected in the strip.
"keyframe_price": P.ltx_mode_price_card("keyframe"),
"extend_price_draft": P.ltx_mode_price_card("extend", steps=8),
"extend_price_pro": P.ltx_mode_price_card("extend", steps=30),
# SYS-03: the Train tab needs the exact RAM figure (not just the
# tier label) to gate itself before a Mac under TRAIN_MIN_RAM_GB
# can even see the 41 GB download offer. One number, one source
# (SYSTEM_RAM_GB / TRAIN_MIN_RAM_GB), so the client never hardcodes
# its own copy of the threshold.
"ram_gb": round(P.SYSTEM_RAM_GB, 1),
"train_min_ram_gb": P.TRAIN_MIN_RAM_GB,
}
# Hailuo H3 — the optional second video engine. Re-read every tick
# (it's a handful of stat() calls) so an install finishing in the
# Pinokio sidebar unlocks the engine pill without a panel restart,
# exactly like the Q8 download already does.
payload["h3"] = P.h3_status()
payload["music"] = P.music_status()
payload["music_install"] = P.music_install_status()
payload["speech"] = P.speech_status()
payload["speech_install"] = P.speech_install_status()
# 4.17.4: can a render start at all (the engine venv), and the one-click
# repair's progress. File checks only - cheap enough for every poll.
payload["engine_env"] = P.engine_env_status()
# 4.19.5: the same question for the Hailuo H3 venv - on its known-good set
# (scripts/pinokio/h3_constraints.txt) or not - and its repair's progress.
payload["h3_env"] = P.h3_env_status()
payload["train_profile"] = P.TRAIN_PROFILE
payload["train_presets"] = P.TRAIN_PRESETS
payload["train_style_presets"] = P.TRAIN_STYLE_PRESETS
payload["train_default_preset"] = P.TRAIN_DEFAULT_PRESET
payload["generation_profile"] = P.GENERATION_PROFILE
# Active model-download status — UI shows a progress strip when
# this is set. last_line is the most recent hf output line so the
# user gets live feedback even before opening the log panel.
with P.DOWNLOAD_LOCK:
if P.DOWNLOAD["active"]:
_dl_repo = next((r for r in P._repos() if r.get("key") == P.DOWNLOAD["key"]), {})
payload["download"] = {
"active": True,
"key": P.DOWNLOAD["key"],
"repo_id": P.DOWNLOAD["repo_id"],
"started_ts": P.DOWNLOAD["started_ts"],
"last_line": P.DOWNLOAD["last_line"],
# A bundle request uses the shared background queue.
"background": bool(P.DOWNLOAD.get("background")),
"name": _dl_repo.get("name") or P.DOWNLOAD["key"],
"size_gb": _dl_repo.get("size_gb"),
**P.model_download_progress(_dl_repo),
}
else:
payload["download"] = {"active": False}
# Requested model packs and progress. Empty on a fresh first open.
payload["deferred_downloads"] = P.deferred_status()
# Mac app review #11: the process-wide GPU gate. `current` shows the queued
# job; an inline image render, a character sheet, Enhance, a lyrics request
# or the post-update script hold the GPU OUTSIDE the queue and showed
# nowhere, so a client deciding "is it safe to stop the studio" must read
# this too: {busy, holder, since, outside_queue}.
payload["gpu"] = P.gpu_gate_status()
# Mac app only: the app's own model download (app_models.json). The
# "Base models needed" card names it instead of offering a second fetch.
_app = P.app_models_state()
if _app is not None:
payload["app_models"] = _app
payload["hf_available"] = P.HF_BIN is not None
# Settings snapshot — only needs the public-safe view (booleans
# for token presence, no secret values). The UI reads
# `settings.models_card_dismissed` on each /status tick to know
# whether to keep the inline models card hidden.
payload["settings"] = P.get_settings_public()
h._json(payload)
@get("/outputs")
def get_outputs(h, parsed) -> None:
# Paginated unified gallery — full history, not just the newest
# 60 that /status surfaces. Carousel's "Show all (N)" button
# calls this when the user wants to scroll older renders.
# Defaults: include_hidden=0, limit=10000 (effectively all on
# a typical install), offset=0. Negative values are rejected.
qs = P.parse_qs(parsed.query)
include_hidden = qs.get("include_hidden", ["0"])[0] == "1"
try:
limit = int(qs.get("limit", ["10000"])[0])
offset = int(qs.get("offset", ["0"])[0])
except (TypeError, ValueError):
h._json({"error": "limit/offset must be integers"}, 400); return
if limit < 0 or offset < 0:
h._json({"error": "limit/offset must be >= 0"}, 400); return
_outs, _total = P.list_outputs(
include_hidden=include_hidden, limit=limit, offset=offset,
return_total=True,
)
h._json({
"outputs": _outs,
"total": _total,
"offset": offset,
"limit": limit,
"returned": len(_outs),
})
# ====== Re-submit a failed/cancelled job by id ====================
# The Recent tab's Retry button hits this. We look up the source
# job in history (and current/queue defensively), clone its params,
# and append a new entry to the queue. The new job gets a fresh id;
# the source row stays in history so the user can see they retried.
@post("/queue/retry")
def post_queue_retry(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
source_id = (form.get("id", [""])[0] or "").strip()
if not source_id:
h._json({"error": "id required"}, 400); return
source = None
with P.LOCK:
for j in P.STATE.get("history") or []:
if j.get("id") == source_id:
source = j; break
if source is None:
for j in P.STATE.get("queue") or []:
if j.get("id") == source_id:
source = j; break
cur = P.STATE.get("current")
if source is None and cur and cur.get("id") == source_id:
source = cur
if source is None:
h._json({"error": f"job {source_id!r} not found in history/queue"}, 404); return
src_params = source.get("params") or {}
new_params = dict(src_params)
# VC-08: the OOM/jetsam failure card's ONLY action used to be "Retry"
# of the identical job — same size, same length, same failure, another
# 10+ minutes on a memory-pressured Mac. "Retry smaller" sends a small,
# explicit allowlist of overrides (never an arbitrary form) that the
# client fills in from the SAME quality ladder and frame-count math the
# render form itself uses — this route never invents a size, it only
# accepts one the client already knows how to produce.
overrides_raw = (form.get("overrides", [""])[0] or "").strip()
if overrides_raw:
try:
overrides = P.json.loads(overrides_raw)
except (TypeError, ValueError):
h._json({"error": "overrides must be JSON"}, 400); return
if not isinstance(overrides, dict):
h._json({"error": "overrides must be a JSON object"}, 400); return
allowed = {"quality", "frames"}
unknown = set(overrides) - allowed
if unknown:
h._json({"error": f"overrides may only set {sorted(allowed)}, "
f"got {sorted(unknown)}"}, 400); return
if "quality" in overrides and overrides["quality"] not in (
"quick", "balanced", "standard", "high"):
h._json({"error": f"unknown quality {overrides['quality']!r}"}, 400); return
if "frames" in overrides:
try:
overrides["frames"] = int(overrides["frames"])
except (TypeError, ValueError):
h._json({"error": "frames override must be an int"}, 400); return
new_params.update(overrides)
# Defense-in-depth: re-queuing a historical job with character_id
# + balanced quality (or a raw train_character LoRA + non-high
# quality) reproduces the bug /queue/add already rejects. Wrap
# new_params into the form-shape the validator expects: it reads
# `character_id`, `quality`, and `loras`. The first two are
# already strings; `loras` lives in new_params as a parsed list
# and needs to be re-encoded as JSON so parse_loras_from_form
# round-trips it cleanly. Validated against new_params (post-
# overrides) — a "smaller" retry must not reintroduce the exact
# character+quality combination this gate exists to refuse.
_retry_form = {
"character_id": new_params.get("character_id") or "",
"quality": new_params.get("quality") or "",
"loras": P.json.dumps(new_params.get("loras") or []),
"engine": new_params.get("engine") or P.ENGINE_DEFAULT,
"mode": new_params.get("mode") or "t2v",
"no_voice": new_params.get("no_voice") or "off",
}
err = P._validate_character_quality(_retry_form)
if err:
h._json({"error": err}, 400); return
# Build a fresh job — copy params (verbatim, or with the validated
# overrides applied above), mint a new id, drop any open_when_done
# flag (retries are usually background; user is mid-other-work and
# doesn't want the OS jumping windows).
new_job = {
"id": P._new_job_id(),
"status": "queued",
"queued_at": P.time.strftime("%Y-%m-%d %H:%M:%S"),
"started_at": None,
"finished_at": None,
"elapsed_sec": None,
"params": new_params,
"raw_path": None,
"output_path": None,
"error": None,
}
new_job["params"]["open_when_done"] = False
new_job["params"].pop("face_fix_result", None)
if new_job["params"].get("face_fix_targets"):
new_job["params"]["face_fix_targets"] = [list(x) for x in new_job["params"]["face_fix_targets"]]
new_job["params"]["source"] = "retry"
# SYS-07: "Retry smaller" — the failure card for the Metal-watchdog /
# jetsam classes (the two biggest fleet failures) used to offer only a
# plain Retry, which re-queues the SAME size and SAME length that just
# died of a GPU timeout or an OOM kill. This re-queues one quality rung
# down, at a scaled-and-grid-snapped canvas (via the same ltx_fit_canvas
# every hardware clamp goes through, so the result is never an
# off-grid size the pipeline would reject), and roughly halves the
# clip length toward the 8k+1 frame grid — real, not cosmetic, relief
# for the two failure classes it's offered on.
if (form.get("smaller", ["0"])[0] or "0") == "1":
p = new_job["params"]
step_down = {"pro": "high", "high": "standard", "standard": "balanced", "balanced": "quick"}
p["quality"] = step_down.get(str(p.get("quality") or "balanced").lower(), "quick")
# 4.17 Codex SAFETY-2: the height used to be bound to `h` — the HTTP
# handler — so the reply below raised AttributeError AFTER the
# smaller job was queued: the button reported failure and a second
# click queued a second replacement.
try:
w, ht = int(p.get("width") or 0), int(p.get("height") or 0)
if w > 0 and ht > 0:
p["width"], p["height"] = P.ltx_fit_canvas(w, ht, int(max(w, ht) * 0.75))
except (TypeError, ValueError):
pass
try:
frames = int(p.get("frames") or 121)
if frames > 41:
p["frames"] = max(41, ((frames // 2) // 8) * 8 + 1)
except (TypeError, ValueError):
pass
# 4.17.5 (Codex): Extend renders `extend_frames` latents, not
# `frames` - halve what that pipeline actually consumes, or "smaller"
# re-ran the same workload.
if str(p.get("mode") or "") == "extend":
try:
ef = int(p.get("extend_frames") or 0)
if ef > 1:
p["extend_frames"] = max(1, ef // 2)
except (TypeError, ValueError):
pass
# 4.17.5: a retry of a job whose input is gone (or was never there) can
# only fail again - say so now instead of after its turn in the queue.
refusal = P.job_input_refusal(new_job["params"])
if refusal:
h._json({"error": refusal, "code": "input_missing"}, 400); return
# Fleet 2 Nov 2026: Retry on a failed training run re-queued the same run
# the trainer had just refused for want of its weights. Say it here.
if str(new_job["params"].get("mode") or "") == "train":
_weights = P.train_weights_refusal()
if _weights:
h._json({"error": _weights, "code": "train_models"}, 409); return
_lic = P.job_licence_refusal(new_job["params"])
if _lic:
h._json(_lic, 451); return
with P.QUEUE_COND:
P.STATE["queue"].append(new_job)
P.QUEUE_COND.notify_all()
P.persist_queue()
h._json({"ok": True, "id": new_job["id"], "source_id": source_id})
@post("/queue/batch")
def post_queue_batch(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
err = P._validate_character_quality(form)
if err:
h._json({"error": err}, 400); return
raw = (form.get("prompts", [""])[0] or "").strip()
if not raw:
h._json({"error": "no prompts"}, 400); return
chunks = [c.strip() for c in P.re.split(r"^\s*---\s*$", raw, flags=P.re.MULTILINE)]
chunks = [c for c in chunks if c]
if not chunks:
h._json({"error": "no prompts after split"}, 400); return
# The character contract applies here too. /queue/batch accepts any
# form the Manual tab can build, character_id included, and it was
# the one enqueue path that neither validated up front nor caught
# CharacterRequestError — so a batch cast with a voice-less
# character raised mid-loop, INSIDE the queue lock, after some jobs
# were already appended and before persist_queue() or any response.
# Half a batch, no answer, and the refusal the rest of the panel
# makes politely arriving as a 500.
err = P._validate_character_quality(form)
if err:
h._json({"error": err}, 400); return
ids = []
try:
built = [P.make_job(form, override_prompt=pr) for pr in chunks]
except P.CharacterRequestError as exc:
h._json({"error": str(exc)}, 400); return
# 4.19.2: the same up-front refusals /queue/add makes. A batch skipped
# them, so a batch of image prompts whose picture had gone failed once per
# prompt, each after its turn (fleet 4.19.1: 12 in a row on one Mac).
for job in built:
refusal = P.job_input_refusal(job.get("params") or {})
if refusal:
h._json({"error": refusal, "code": "input_missing"}, 400); return
for job in built[:1]: # the form is shared; one licence screen
_lic = P.job_licence_refusal(job.get("params") or {})
if _lic:
h._json(_lic, 451); return
for job in built[:1]: # the form is shared; one install offer
refusal = P.a2v_stem_refusal(job["params"])
if refusal:
h._json({"error": refusal, "code": "vocal_separator_missing"}, 400); return
# Built first, appended second: a batch is all-or-nothing, so a
# refusal on prompt 7 cannot leave prompts 1-6 queued.
with P.QUEUE_COND:
for job in built:
job["params"]["open_when_done"] = False
P.STATE["queue"].append(job)
ids.append(job["id"])
P.QUEUE_COND.notify_all()
P.persist_queue()
h._json({"ok": True, "added": len(ids), "ids": ids})
@post("/queue/remove")
def post_queue_remove(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
job_id = qs.get("id", [""])[0] or form.get("id", [""])[0]
removed = False
with P.LOCK:
for i, j in enumerate(P.STATE["queue"]):
if j["id"] == job_id:
P.STATE["queue"].pop(i)
removed = True
break
P.persist_queue()
h._json({"removed": removed}); return
@post("/queue/reorder")
def post_queue_reorder(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
job_id = (form.get("id", [""])[0] or qs.get("id", [""])[0] or "").strip()
direction = (form.get("direction", [""])[0] or qs.get("direction", [""])[0] or "").strip()
if not job_id:
h._json({"ok": False, "error": "no job id given"}, 400); return
out = P.queue_move_job(job_id, direction)
h._json(out, 200 if out.get("ok") else 400)
@post("/queue/update")
def post_queue_update(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
job_id = (form.get("id", [""])[0] or qs.get("id", [""])[0] or "").strip()
if not job_id:
h._json({"ok": False, "error": "no job id given"}, 400); return
try:
out = P.queue_update_job(job_id, form)
except Exception as exc: # noqa: BLE001
h._json({"ok": False, "error": f"could not update job: {exc}"}, 500)
return
h._json(out, 200 if out.get("ok") else 400)
@post("/queue/clear")
def post_queue_clear(h, path, qs, ctype) -> None:
# SAFETY-9: the reply carries a single-use `undo_token` for exactly the
# jobs this call removed (see P.queue_clear_with_undo).
out = P.queue_clear_with_undo()
P.persist_queue()
h._json(out); return
@post("/queue/pause")
def post_queue_pause(h, path, qs, ctype) -> None:
with P.QUEUE_COND:
P.STATE["paused"] = True
P.QUEUE_COND.notify_all()
P.persist_queue()
h._json({"paused": True}); return
@post("/queue/resume")
def post_queue_resume(h, path, qs, ctype) -> None:
with P.QUEUE_COND:
P.STATE["paused"] = False
# SYS-32: clear the breaker's reason on any resume, manual or not —
# otherwise a stale "last 3 renders failed" notice would keep
# showing after the user fixed the cause and pressed Resume.
P.STATE["paused_reason"] = None
P.QUEUE_COND.notify_all()
P.persist_queue()
h._json({"paused": False}); return
@post("/helper/restart")
def post_helper_restart(h, path, qs, ctype) -> None:
# Mark any in-flight job as user-cancelled BEFORE killing the
# helper. Otherwise the worker sees the helper exit and writes
# status=failed/"helper exited" instead of status=cancelled.
with P.LOCK:
cur = P.STATE.get("current")
if cur is not None:
cur["cancel_requested"] = True
P.HELPER.kill()
h._json({"ok": True}); return
@post("/prompt/enhance")
def post_prompt_enhance(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
# Gemma-driven prompt enhancement, routed through the warm
# helper subprocess. First call after panel start eats a
# ~10-15s Gemma load; cached afterwards (subsequent enhances
# ~3-5s). Helper's release_pipelines frees Gemma when a real
# render comes in, so memory doesn't accumulate on top of
# the dev transformer.
user_prompt = (form.get("prompt", [""])[0] or "").strip()
mode = (form.get("mode", ["t2v"])[0] or "t2v").lower()
# VC-13: default TRUE (unchanged behaviour — Enhance has always
# translated to English). "0"/"false"/"off" is the explicit opt-out
# from the prompt box's "Translate to English" toggle, which only
# shows once a non-Latin-script prompt is typed.
translate = (form.get("translate", ["1"])[0] or "1").strip().lower() not in ("0", "false", "off")
source_non_latin = P.prompt_looks_non_latin(user_prompt)
# A2V (VA-24): the t2v Gemma prompt asks for "describe the scene AND the
# sound" and readily invents camera-restraint sentences — both wrong on a
# shot driven by supplied audio (a sound description competes with the
# real track; a stillness sentence freezes the mouth, the exact bug this
# week's A2V prompt law exists to prevent). There is no dedicated a2v
# Gemma system prompt, so this borrows the i2v one (closer: an image
# anchors the shot, the prompt directs motion, no "and the sound" ask)
# and then runs the result through the same stillness-cleanup + word-cap
# every other a2v prompt gets before it reaches the engine.
a2v_mode = (mode == "a2v")
if a2v_mode:
mode = "i2v"
elif mode not in ("t2v", "i2v"):
mode = "t2v"
if not user_prompt:
h._json({"error": "no prompt provided"}, 400); return
# 4.20: Gemma 3 is downloaded in the background after the first boot, so
# for a while after a fresh install it is not on disk yet. Say so - with
# what to do - instead of letting the helper fail to load a model that is
# still arriving.
if P.enhance_model_missing():
h._json(P.gemma3_refusal("Enhance", "its language model, Gemma 3", P.GEMMA), 409); return
# 2026-05-20 — collect trigger tokens that Gemma MUST preserve
# case-exact. Three sources, unioned:
# 1. The panel-supplied `preserve_tokens` form field (the
# Enhance button sends active-LoRA triggers + character
# trigger).
# 2. Known character names from list_characters() — covers
# the case where the user typed a character name without
# having loaded the LoRA yet (e.g. typing "bizarrotrn" in
# a fresh session before the avatar picker fired).
# 3. Tokens in the user's prompt that look like trigger words
# (lowercase, no spaces, ends in `trn` or matches a known
# character id) — defense in depth against (1) being
# empty.
preserve_raw = (form.get("preserve_tokens", [""])[0] or "").strip()
preserve_set: set[str] = set()
if preserve_raw:
try:
preserve_set.update(
str(t).strip() for t in P.json.loads(preserve_raw)
if str(t).strip()
)
except (TypeError, ValueError, P.json.JSONDecodeError):
# Allow plain comma-separated fallback for API users
preserve_set.update(
t.strip() for t in preserve_raw.split(",")
if t.strip()
)
try:
for char in P.list_characters():
trig = (char.get("trigger") or "").strip()
if trig and trig in user_prompt:
preserve_set.add(trig)
except Exception:
pass
# 4.18.0: the LoRAs on this render, as the prompt helper should know them
# (name, trigger words, the guide or the creator's note). Bounded and only
# read from files the LoRA library lists — see lora_enhance_context.
loras_raw = (form.get("loras", [""])[0] or "").strip()
try:
lora_ctx = P.lora_enhance_context(P.json.loads(loras_raw)) if loras_raw else []
except (TypeError, ValueError):
lora_ctx = []
preserve_tokens = sorted(preserve_set)
P.push(f"[enhance] {mode}: {user_prompt[:80]}…"
+ (f" preserve={preserve_tokens}" if preserve_tokens else ""))
# THE GPU GATE, like every other GPU user (routes_music._helper_run). The
# queue unloads the LTX helper before an H3 or music render; an Enhance
# click mid-render respawned it and loaded Gemma beside that engine — two
# models on a Mac sized for one. The worker holds _GPU_LOCK for a whole
# job, so during any render this answers "busy" at once instead of
# queueing behind it until the enhance timeout.
if not P._GPU_LOCK.acquire(timeout=3.0):
# VC-16: name what's actually rendering (and how long, when the
# priced tier table can say) instead of a flat "a render" refusal.
reason = P.current_render_busy_reason()
P.push(f"[enhance] skipped: {reason}")
h._json({"error": f"{reason} Enhance works again when it finishes."}, 409); return
P.gpu_gate_mark("enhance")
try:
result = P.HELPER.run({
"action": "enhance_prompt",
"id": f"enh-{int(P.time.time()*1000)}",
"params": {"prompt": user_prompt, "mode": mode, "seed": 10,
"preserve_tokens": preserve_tokens, "translate": translate,
"lora_notes": lora_ctx},
}, timeout=P.PROMPT_ENHANCE_TIMEOUT)
except Exception as exc:
P.push(f"[enhance] failed: {exc}")
h._json({"error": str(exc)}, 500); return
finally:
P.gpu_gate_unmark()
P._GPU_LOCK.release()
# A malformed terminal helper event must still become JSON. Before
# this guard, None/non-string values raised after the only try/except
# in the lane and BaseHTTPRequestHandler closed the socket empty.
if not isinstance(result, dict):
h._json({"error": "Gemma returned an invalid helper response"}, 500); return
enhanced_raw = result.get("enhanced", "")
if not isinstance(enhanced_raw, str):
h._json({"error": "Gemma returned an invalid enhanced prompt"}, 500); return
enhanced = enhanced_raw.strip()
if a2v_mode:
# Same law every other a2v prompt goes through (storyboard.a2v_prompt):
# stillness words out, capped to the direction word budget, the
# lip-sync contract appended. Gemma's i2v system prompt has no reason
# to know any of that.
enhanced = P.storyboard.a2v_prompt(enhanced, silent=False)
if not enhanced:
h._json({"error": "Gemma returned empty result"}, 500); return
# A LoRA whose trigger word the result never names would not fire — put
# its first trigger back at the front (after the a2v law above, so the
# word cap there cannot cut it off again).
enhanced, triggers_added = P.ensure_lora_triggers(enhanced, lora_ctx)
if triggers_added:
P.push(f"[enhance] added trigger word(s): {', '.join(triggers_added)}")
P.push(f"[enhance] → {enhanced[:120]}… ({result.get('elapsed_sec','?')}s)")
# `enhance_prompt` was in the feature vocabulary and the /analytics/ui
# allowlist since v4.9.7, but nothing ever sent it: the fleet showed 0
# Enhance uses across 809 active installs (2026-09-19 -> 10-19), which is
# "unmeasured", not "unused". Counted here, on success, where it happens.
# It decides whether the 6 GB Gemma 3 that Enhance runs on has to be
# downloaded before a new user can press Start at all.
P._analytics_feature("enhance_prompt", "a2v" if a2v_mode else mode)
h._json({
"ok": True,
"original": user_prompt,
"enhanced": enhanced,
"mode": "a2v" if a2v_mode else mode,
"elapsed_sec": result.get("elapsed_sec"),
# VC-13: lets the client say "Translated to English." without
# re-deriving the same script check the toggle's visibility used.
"source_non_latin": source_non_latin,
"translated": bool(source_non_latin and translate),
# 4.18.0: which LoRAs' notes the helper read, and the trigger words
# put back — the Enhance panel says both in one line.
"lora_notes_used": [c["name"] for c in lora_ctx if c.get("note")],
"lora_triggers_added": triggers_added,
})
@post("/run")
@post("/queue/add")
def post_run(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
err = P._validate_character_quality(form)
if err:
h._json({"error": err}, 400); return
# The validator runs FIRST, so make_job's own refusals should be
# unreachable here — but "should be" is not a guarantee: the two
# seams read the same form through different code, and a character
# deleted between the two calls is a plain TOCTOU. This endpoint has no
# top-level handler, so an escaping CharacterRequestError becomes a
# traceback and a dropped connection instead of the 400 the rest of
# this endpoint answers with. The refusal is polite everywhere else;
# it must be polite here too.
try:
job = P.make_job(form)
except P.CharacterRequestError as exc:
h._json({"error": str(exc)}, 400); return
# 4.17.5: a job that can only fail for want of its input (Upscale or
# Control with no clip, Image with no picture, an unknown mode) is refused
# here, in the form's own words, instead of failing after its turn.
refusal = P.job_input_refusal(job.get("params") or {})
if refusal:
h._json({"error": refusal, "code": "input_missing"}, 400); return
# 4.19.8: a model whose licence asks for an explicit "I accept" (H3, the
# non-commercial models) is refused with 451 until it is accepted; the
# panel's licences.js shows the screen and re-sends this request.
_lic = P.job_licence_refusal(job.get("params") or {})
if _lic:
h._json(_lic, 451); return
# 4.17 Codex EST-10: a follow-up that can never queue is refused NOW,
# not discovered in the log after a long Extend render.
refusal = P.extend_face_fix_refusal(job["params"])
if refusal:
h._json({"error": refusal, "code": "pack_missing",
"pinokio": P.face_fix_pinokio_offer()}, 400); return
# Upscale ×2 above QHD exhausted 96 GB + swap: refused before it queues.
_up = job["params"]
if _up.get("mode") == "upscale" and _up.get("upscale_source_path"):
_sw, _sh = P._probe_video_dims(str(_up["upscale_source_path"]))
refusal = P.upscale_output_refusal(_sw, _sh)
if refusal:
h._json({"error": refusal, "code": "hardware_tier"}, 400); return
# "Listen to the voice only" on an install that cannot separate a voice:
# refused NOW with an install offer, never rendered on the full mix.
refusal = P.a2v_stem_refusal(job["params"])
if refusal:
h._json({"error": refusal, "code": "vocal_separator_missing"}, 400); return
with P.QUEUE_COND:
P.STATE["queue"].append(job)
P.QUEUE_COND.notify_all()
P.persist_queue()
h._json({"ok": True, "id": job["id"]})
# UPSCALE & FACE FIX as a clip action: one click on a finished clip (player,
# Outputs card, history row, Editor clip bar) queues the face-safe recipe for
# that clip. Server-side so the prompt/seed come from the clip's own sidecar
# and every door queues exactly the same job.
@post("/queue/facefix")
def post_queue_facefix(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
def f(name: str) -> str:
v = form.get(name, "")
if isinstance(v, list):
v = v[0] if v else ""
return str(v or "").strip()
try:
out = P.queue_face_fix(f("path"), board_id=f("board"), clip_id=f("clip"))
except P.CharacterRequestError as exc:
h._json({"ok": False, "error": str(exc)}, 400); return
except Exception as exc: # noqa: BLE001
h._json({"ok": False, "error": f"could not queue {P.FACE_FIX_NAME}: {exc}"}, 500)
return
h._json(out, 200 if out.get("ok") else 400)
@post("/queue/sharp_export")
def post_queue_sharp_export(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
src = (form.get("path", [""])[0] or qs.get("path", [""])[0] or "").strip()
try:
out = P.queue_sharp_export(src)
except Exception as exc: # noqa: BLE001
h._json({"ok": False, "error": f"could not queue Sharp export: {exc}"}, 500)
return
h._json(out, 200 if out.get("ok") else 400)
# The chain held /stop as TWO arms split on ?mode=early; one path, one
# handler, the same two branches.
@post("/stop")
def post_stop(h, path, qs, ctype) -> None:
if qs.get("mode", [""])[0] == "early":
# STOP EARLY — distinct from the hard /stop below, which kills the
# helper. This one touches the ABORT sentinel the runner checks
# between forwards; it stops cleanly at the next boundary and
# exits 75.
#
# The two must not be the same button: a kill leaves a half-written
# process to reap and reports as a cancellation of unknown shape,
# while this is the render agreeing to stop.
#
# A FILE, not a signal, and that is the runner's design: a sentinel
# works across a UI, a shell, an ssh session and a supervisor
# without any of them holding the process handle. It also means
# this endpoint cannot half-kill a render — the worst case is a
# file nobody reads.
with P.LOCK:
cur = P.STATE.get("current")
job_id = (cur or {}).get("id")
# A One Shot's preview lives under the PART rendering now.
preview_id = P.live_preview_job_id(cur) if cur else ""
if not job_id:
h._json({"error": "nothing is rendering"}, 404); return
expect = (qs.get("id", [""])[0] or "").strip()
if expect and expect != job_id: # SAFETY-3, same as below
h._json({"ok": False, "stale": True,
"error": "That render already finished — nothing was stopped."}, 409); return
d = P.live_preview_dir(preview_id)
if not d.is_dir():
h._json({"error": "this render has no live preview to stop "
"through — use Cancel."}, 409); return
try:
(d / "ABORT").touch()
except OSError as exc:
h._json({"error": f"could not write the stop sentinel: {exc}"}, 500); return
P.push("Stop early requested — finishing the current step, then stopping.")
h._json({"ok": True, "id": job_id}); return
# The HARD stop: kill the helper. Still what the Stop button does.
# SAFETY-3: `id` names the job the user confirmed; if it already
# finished and another started, nothing is stopped (409, stale).
expect = (qs.get("id", [""])[0] or "").strip() or None
if not P.stop_current_job(expect_id=expect):
h._json({"ok": False, "stale": True,
"error": "That render already finished — nothing was stopped."}, 409); return
h._json({"ok": True})
@get("/a2v/estimate")
def get_a2v_estimate(h, parsed) -> None:
"""VA-06: the Audio -> Video footer showed no time estimate at all.
Priced the same way /oneshot/estimate and /take/estimate already are —
server-side, from the exact pipeline (Q8 two-stage vs Q4 distilled)
and the exact clamp run_job_inner applies — so the browser computes
nothing of its own (Structure Law)."""
qs = P.parse_qs(parsed.query)
try:
frames = int((qs.get("frames", ["121"])[0] or "121"))
except (TypeError, ValueError):
frames = 121
try:
width = int((qs.get("width", ["0"])[0] or "0")) or None
except (TypeError, ValueError):
width = None
try:
height = int((qs.get("height", ["0"])[0] or "0")) or None
except (TypeError, ValueError):
height = None
# Fleet first (4.17 integration): the cost model runs ~2x low for a2v
# against the fleet's own wall clocks. ltx_a2v_price is the one pricing
# function — the queue row reads it too (4.17 Codex EST-5).
h._json({"ok": True, **P.ltx_a2v_price(frames, width, height)})
@get("/keyframe/estimate")
def get_keyframe_estimate(h, parsed) -> None:
"""4.17 Codex EST-7: Keyframe's footer and Shot setup summary read ONE
price card priced at 5 s on the default canvas, whatever duration and
aspect the form held. This prices the frames and canvas actually asked
for (ltx_mode_price_card — clamp, pipeline and fleet range as the
render and BOOT's first-paint card); the browser prices nothing."""
qs = P.parse_qs(parsed.query)
def _int(name: str) -> int | None:
try:
return int((qs.get(name, ["0"])[0] or "0")) or None
except (TypeError, ValueError):
return None
card = P.ltx_mode_price_card("keyframe", frames=_int("frames"),
width=_int("width"), height=_int("height"))
if not card:
h._json({"ok": False, "error": "keyframe is not available on this Mac"}); return
h._json({"ok": True, **card})
# ====== Lip-sync keyframe helpers (VA "Continue the song") =================
# Both routes are pure reads (plus one PNG write for the anchor image) — no
# job queued, no GPU lock taken. See mlx_ltx_panel.py's mouth_open_ratio /
# find_closed_mouth_frame / extract_frame_png for the cv2 mechanics, and the
# "Keyframe + lip-sync" section of report_video-advanced.txt for why a
# lip-sync anchor is frame_idx-0-only and closed-mouth-only.
def _lipsync_media_path(raw: str):
"""LIPSYNC-1: the lip-sync helpers open a picture/clip by path and write a
frame of it into uploads (served by /image). Same boundary as /image:
resolve (symlinks and .. included) and require the file to live under
outputs, uploads or state — anything else would copy private media out.
Returns the resolved path, or None when it is outside the roots."""
try:
media = P.Path(raw).resolve()
roots = [P.OUTPUT.resolve(), P.UPLOADS.resolve(), P.STATE_DIR.resolve()]
except Exception: # noqa: BLE001
return None
if not any(media.is_relative_to(r) for r in roots):
return None
return media
@post("/a2v/mouth_check")
def post_a2v_mouth_check(h, path, qs, ctype) -> None:
"""Open-mouth warning for a picked lip-sync start frame. The 2026-09-22
anchor lesson: a still with the mouth open, pinned as a strength-1.0
frame-0 anchor, freezes the performance open-mouthed for the whole clip —
this is the one check that catches it before a 10-25 minute render."""
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
img = (form.get("image", [""])[0] or "").strip()
if not img:
h._json({"error": "image not found"}, 400); return
media = _lipsync_media_path(img)
if media is None:
h._json({"error": "pick a picture from your uploads or outputs"}, 403); return
if not media.is_file():
h._json({"error": "image not found"}, 400); return
img = str(media)
ratio = P.mouth_open_ratio(img)
if ratio is None:
# No face found, or cv2 unavailable — not a verdict either way.
h._json({"ok": True, "measured": False}); return
h._json({"ok": True, "measured": True, "ratio": round(ratio, 4),
"open": ratio > P.MOUTH_OPEN_WARN,
"threshold": P.MOUTH_OPEN_WARN})
@post("/a2v/continue_song")
def post_a2v_continue_song(h, path, qs, ctype) -> None:
""""Continue the song": scans the last ~0.5s of a finished a2v clip for
its most-closed-mouth frame, saves that frame as a new upload, and
returns where in the song the NEXT clip should start reading. The
picture is deliberately NOT the clip's literal last frame — a2v's own
last frame is usually mid-syllable, and anchoring the next clip there
pins an open mouth for its whole duration (see the "Keyframe +
lip-sync" section of report_video-advanced.txt). Queues nothing; the
caller uses the returned anchor_image + audio_start_time to fill the
next lip-sync job."""
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
src = (form.get("clip", [""])[0] or "").strip()
if not src:
h._json({"error": "clip not found"}, 400); return
media = _lipsync_media_path(src)
if media is None:
h._json({"error": "only a clip from your outputs or uploads can be continued"}, 403); return
if not media.is_file():
h._json({"error": "clip not found"}, 400); return
src = str(media)
hit = P.find_closed_mouth_frame(src)
if hit is None:
h._json({"error": "could not find a face in the last half-second of "
"this clip — pick a start frame by hand instead."},
422); return
P.UPLOADS.mkdir(parents=True, exist_ok=True)
dest = P.UPLOADS / f"{int(P.time.time() * 1000)}_continue_anchor.png"
if not P.extract_frame_png(src, hit["time_s"], dest):
h._json({"error": "could not extract the anchor frame"}, 500); return
# Where the NEXT clip should start reading the song: the source clip's
# own offset into the file, plus how far into the CLIP the anchor sits
# (the anchor is picked from the last ~0.5s, not necessarily the very
# last frame, so this is a few frames short of "start + full duration").
src_start = 0.0
sidecar_path = P.Path(str(src) + ".json")
if sidecar_path.exists():
try:
meta = P.json.loads(sidecar_path.read_text())
src_start = float((meta.get("params") or {}).get("audio_start_time") or 0.0)
except Exception: # noqa: BLE001
src_start = 0.0
h._json({
"ok": True,
"anchor_image": str(dest),
"anchor_time_s": hit["time_s"],
"anchor_openness": hit["openness"],
"audio_start_time": round(src_start + hit["time_s"], 3),
})
@get("/ltx/windows_plan")
def get_ltx_windows_plan(h, parsed) -> None:
"""VA-18: the REAL per-window schedule (start_sec/end_sec, count), so the
Windows UI can render one labelled box per window ("Window 2 · 0:05-0:09")
instead of a free-text textarea whose first typed line silently replaces
the main prompt (ltx_windows.window_prompts: index 0 blank means "use the
main prompt" — the UI used to invite a user to put THEIR first line
there). Pure read: ltx_windows.plan_windows is a pure function, no job,
no render."""
qs = parse_qs(parsed.query)
try:
frames = int((qs.get("frames", ["121"])[0] or "121"))
except (TypeError, ValueError):
frames = 121
frames = max(1, frames)
import ltx_windows as _lw # noqa: PLC0415
try:
plan = _lw.plan_windows(frames)
except ValueError as exc:
h._json({"error": str(exc)}, 400); return
h._json({
"ok": True,
"count": plan["count"],
"windows": [{"index": w["index"], "start_sec": w["start_sec"],
"end_sec": w["end_sec"]} for w in plan["windows"]],
"notes": plan["notes"],
})
@post("/a2v/prompt_check")
def post_a2v_prompt_check(h, path, qs, ctype) -> None:
"""Live stillness-phrase check for the lip-sync prompt box (VA-05, the
client half — the server ALWAYS applies storyboard.a2v_prompt() before a
render regardless of what this endpoint says, so a client that never
calls this is still safe). Pure read: no job, no render."""
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
prompt = (form.get("prompt", [""])[0] or "")
problems = P.storyboard.a2v_stillness_problems(prompt)
h._json({
"ok": True,
"problems": problems,
"cleaned": P.storyboard.a2v_clean_prompt(prompt) if problems else prompt,
})
# VC-05 / H3-11: the third stop shape, next to hard-kill and stop-early.
# Neither of those is right mid-chain — a hard kill loses the part/window
# rendering right now AND every part/window already finished, and stop-early
# only reaches through a live preview. This sets a flag the render loop
# checks at each PART/WINDOW BOUNDARY (never mid-part, never mid-window):
# what's in flight finishes (or is asked to stop as cleanly as the engine
# allows), the loop stops there instead of starting the next one, and
# whatever is done gets published — a clean finish, not a failure.
#
# Two shapes share this one endpoint and one flag:
# - a One Shot (params.take): run_take_job_inner joins the finished parts.
# - a plain H3 chained render (no take, 2+ windows): run_h3_job_inner asks
# the engine's own process group to stop at the next window boundary and
# publishes whatever landed on disk, honestly labelled if the engine
# can't hand back a clean partial.
# Refused outside both so the button can't appear to do something on an
# ordinary single-shot render.
@post("/stop/after_part")
def post_stop_after_part(h, path, qs, ctype) -> None:
# SAFETY-3: `id` = the job whose dialog the user confirmed. Checked in
# the same LOCK section that sets the flag, so a dialog left open while
# that job finished can never flag its successor.
expect = (qs.get("id", [""])[0] or "").strip()
with P.LOCK:
cur = P.STATE.get("current")
if cur is None:
h._json({"error": "nothing is rendering"}, 404); return
if expect and cur.get("id") != expect:
h._json({"ok": False, "stale": True,
"error": "That render already finished — nothing was stopped."}, 409); return
cur_params = cur.get("params") or {}
is_take = bool(cur_params.get("take"))
window_total = (cur.get("progress") or {}).get("window_total") or 1
is_h3_chain = (not is_take
and (cur_params.get("engine") or "").strip().lower() == "h3"
and window_total > 1)
if not is_take and not is_h3_chain:
h._json({"error": "this render has no parts or windows to stop "
"between — use Stop."}, 409); return
if is_h3_chain and not P.H3_RUNNER_KEEPS_WINDOWS_ON_STOP:
# 4.17 Codex review: the H3 runner stitches and writes its ONE
# output only after the last window (generate_staged.py), so a
# SIGTERM between windows leaves nothing to publish — promising
# "keep what's done" would throw the finished windows away.
h._json({"error": "this H3 engine can't keep finished windows when "
"stopped mid-chain yet — use Stop, or let it finish."},
409); return
cur["stop_after_part"] = True
job_id = cur.get("id")
P.push("Stop-after-this-part requested — finishing what's in progress, "
"then keeping what's done." if is_take else
"Stop-after-this-window requested — asking the engine to stop "
"before the next window, then keeping what rendered.")
h._json({"ok": True, "id": job_id, "shape": "take" if is_take else "h3_chain"})
# VC-03: the #1 creator gesture, one click. Sourced from the clip's own
# sidecar on disk (not job history, which rotates) so New Take works on any
# clip still in the gallery, not only a recent one. The ONLY thing this
# changes from the original recipe is the seed — same prompt, size, quality,
# LoRAs, character, engine — so what comes back answers "another one like
# this" rather than "something different." Shared by the board's own New
# Take (FILM-22): both read a sidecar's `params` and replay it with seed=-1
# through this one endpoint, so the two features can't drift into two
# different ideas of what "the same recipe" means.
#
# A One Shot clip (params.take) gets the same answer at the SHOT level: the
# whole take re-runs from part 1 with a fresh seed, same beats/camera/lock/
# handoff — not a per-part reseed, which would need each part's own retake
# logic to agree on what "the same take" means and wasn't verified. See the
# take-rebuild block below for why the sidecar's take block can't be reused
# verbatim.
@post("/queue/newtake")
def post_queue_newtake(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
raw = (form.get("path", [""])[0] or qs.get("path", [""])[0] or "").strip()
if not raw:
h._json({"error": "path required"}, 400); return
try:
media = P.Path(raw).resolve()
except Exception:
h._json({"error": "bad path"}, 400); return
try:
roots = [P.OUTPUT.resolve(), P.UPLOADS.resolve()]
except Exception:
roots = []
if not any(media.is_relative_to(r) for r in roots):
h._json({"error": "path must resolve under outputs/ or uploads/"}, 404); return
sidecar = media.with_suffix(media.suffix + ".json")
if not sidecar.is_file():
h._json({"error": "no sidecar for this clip — nothing to replay"}, 404); return
try:
side = P.json.loads(sidecar.read_text(encoding="utf-8"))
except (OSError, P.json.JSONDecodeError):
h._json({"error": "sidecar is unreadable"}, 500); return
src_params = side.get("params") or {}
if not src_params:
h._json({"error": "sidecar has no params to replay"}, 400); return
# A Sharp export of a clip that had no settings of its own (an imported
# mp4) records only {mode: t2v, sharp_export_*}: no prompt, no canvas. New
# Take queued that as a t2v job, which died on its first missing field -
# the bare `'stop_comfy'` in the fleet (4.19.5). Nothing to re-roll.
if src_params.get("sharp_export_source") and not (
src_params.get("prompt") or src_params.get("width")):
h._json({"error": "This clip is a Sharp export of a clip with no "
"recorded settings, so there is nothing to re-roll."},
400); return
new_params = dict(src_params)
stored_take = new_params.get("take")
if stored_take:
# A One Shot's New Take means what it means everywhere else: the same
# recipe, a fresh seed, re-run from scratch — not a per-part reseed
# (each part's own seed is derived by run_take_job_inner from the
# parent's, and letting that reroll independently was the half-
# verified idea this endpoint used to refuse over). The sidecar's
# `take.parts`/`take.beats` are POST-COMPLETION fields — parts is the
# rendered file list, beats is the resolved text list — not the
# beat-index/part-count shape run_take_job_inner needs to start a
# fresh take, so that shape is rebuilt from take_plan() (exactly what
# a fresh One Shot submit does) rather than replayed as-is.
fresh = P.take_plan(stored_take.get("seconds"), stored_take.get("engine"))
if fresh is None:
h._json({"error": "This One Shot's length isn't valid anymore — "
"use Params, then Generate, instead."}, 400); return
stored_beat_texts = stored_take.get("beats")
if not isinstance(stored_beat_texts, list):
# SAFETY-11: a take joined from a stopped One Shot before this fix
# kept the INPUT shape — `beats` a count, the text in
# `beat_prompts` — and New Take dropped every written beat.
stored_beat_texts = stored_take.get("beat_prompts")
fresh["beat_prompts"] = (list(stored_beat_texts)
if isinstance(stored_beat_texts, list) else [])
fresh["light_lock"] = stored_take.get("light_lock") or ""
fresh["retake"] = stored_take.get("retake", True) is not False
fresh["camera"] = stored_take.get("camera") or ""
fresh["handoff"] = stored_take.get("handoff") or "last"
new_params["take"] = fresh
new_params["seed"] = "-1"
new_params.pop("seed_used", None)
new_params["open_when_done"] = False
new_params.pop("face_fix_result", None)
new_params["source"] = "new_take"
new_job = {
"id": P._new_job_id(),
"status": "queued",
"queued_at": P.time.strftime("%Y-%m-%d %H:%M:%S"),
"started_at": None, "finished_at": None, "elapsed_sec": None,
"params": new_params, "raw_path": None, "output_path": None, "error": None,
}
# 4.19.8: a model whose licence asks for an "I accept" (model_licences.py).
_lic = P.job_licence_refusal(new_job.get("params") or {})
if _lic:
h._json(_lic, 451); return
with P.QUEUE_COND:
P.STATE["queue"].append(new_job)
P.QUEUE_COND.notify_all()
P.persist_queue()
# The real elapsed time of the clip being re-rolled — the honest ETA for
# "about the same again", cheaper than re-deriving one from the tier table.
h._json({"ok": True, "id": new_job["id"], "eta_sec": side.get("elapsed_sec")})
# VC-06's undo path. `{"token": ...}` (what the panel sends) restores the
# exact jobs /queue/clear removed, under their original ids — see
# P.queue_clear_with_undo for why the browser's own snapshot was wrong.
# `{"jobs": [{"params": ...}, ...]}` still re-queues arbitrary params, in
# order, with fresh ids (P._new_job_id — never a clock + small random suffix,
# which collided inside a 200-job restore). Accepts a JSON body so a queue of
# arbitrary size/shape round-trips without URL-length limits.
@post("/queue/restore")
def post_queue_restore(h, path, qs, ctype) -> None:
try:
length = int(h.headers.get("Content-Length") or "0")
except ValueError:
h._json({"error": "invalid Content-Length"}, 400); return
if length <= 0:
h._json({"error": "Content-Length required for JSON body"}, 411); return
if length > 2_000_000:
h._json({"error": "body too large (max 2000000 bytes)"}, 413); return
try:
payload = P.json.loads(h.rfile.read(length).decode() or "{}")
except (P.json.JSONDecodeError, UnicodeDecodeError):
h._json({"error": "invalid JSON body"}, 400); return
# SAFETY-8/9/10: the Undo toast sends the token /queue/clear returned —
# the server puts back exactly the jobs it removed, original ids and
# all, once. The `jobs` list form below stays for API callers.
token = payload.get("token") if isinstance(payload, dict) else None
if token:
out = P.queue_restore_cleared(str(token))
if not out.get("ok"):
h._json({"ok": False, "error": out.get("error")}, out.get("status") or 410); return
P.persist_queue()
h._json(out); return
jobs = payload.get("jobs") if isinstance(payload, dict) else None
if not isinstance(jobs, list) or not jobs:
h._json({"error": "jobs: [...] required"}, 400); return
if len(jobs) > 200:
h._json({"error": "too many jobs to restore at once"}, 400); return
restored = []
with P.QUEUE_COND:
for entry in jobs:
params = entry.get("params") if isinstance(entry, dict) else None
if not isinstance(params, dict) or not params:
continue
new_job = {
"id": P._new_job_id(),
"status": "queued",
"queued_at": P.time.strftime("%Y-%m-%d %H:%M:%S"),
"started_at": None, "finished_at": None, "elapsed_sec": None,
"params": dict(params), "raw_path": None, "output_path": None, "error": None,
}
P.STATE["queue"].append(new_job)
restored.append(new_job["id"])
if restored:
P.QUEUE_COND.notify_all()
P.persist_queue()
h._json({"ok": True, "restored": len(restored), "ids": restored})
# VA-17: the two ways back for a One Shot that stopped or failed mid-chain.
# Both read the `one_shot_unfinished` block run_take_job_inner's recovery
# path stashes on the LAST finished part's sidecar — see the except clause
# there. `path` names that part (the un-hidden card the user is looking at).
def _load_take_manifest(h, form_or_qs) -> dict | None:
raw = (form_or_qs.get("path", [""])[0] or "").strip()
if not raw:
h._json({"error": "path required"}, 400); return None
try:
media = P.Path(raw).resolve()
except Exception:
h._json({"error": "bad path"}, 400); return None
try:
roots = [P.OUTPUT.resolve(), P.UPLOADS.resolve()]
except Exception:
roots = []
if not any(media.is_relative_to(r) for r in roots):
h._json({"error": "path must resolve under outputs/ or uploads/"}, 404); return None
sidecar = media.with_suffix(media.suffix + ".json")
if not sidecar.is_file():
h._json({"error": "no sidecar for this part"}, 404); return None
try:
side = P.json.loads(sidecar.read_text(encoding="utf-8"))
except (OSError, P.json.JSONDecodeError):
h._json({"error": "sidecar is unreadable"}, 500); return None
manifest = side.get("one_shot_unfinished")
if not manifest or not manifest.get("outs"):
h._json({"error": "this clip has no unfinished One Shot to resume — "
"it may already have been joined or resumed."}, 404); return None
return manifest
@post("/take/resume")
def post_take_resume(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
manifest = _load_take_manifest(h, form)
if manifest is None:
return
take = dict(manifest.get("take") or {})
take["_resume"] = {
"outs": manifest.get("outs") or [],
# SAFETY-5/6/12: the rendered parts' own files, their seeds, and the
# speech handoff's pending tail; the handoff frame is rebuilt by the
# take itself from the last part, so `last_png` is informational.
"visible": manifest.get("visible") or [],
"part_seeds": manifest.get("part_seeds"),
"tail_wav": manifest.get("tail_wav"),
"last_png": manifest.get("last_png"),
"start_k": manifest.get("done_parts"),
}
base_params = dict(manifest.get("p") or {})
base_params["take"] = take
base_params["label"] = manifest.get("label") or base_params.get("label") or ""
base_params["open_when_done"] = False
new_job = {
"id": P._new_job_id(),
"status": "queued",
"queued_at": P.time.strftime("%Y-%m-%d %H:%M:%S"),
"started_at": None, "finished_at": None, "elapsed_sec": None,
"params": base_params, "raw_path": None, "output_path": None, "error": None,
}
# 4.19.8: a model whose licence asks for an "I accept" (model_licences.py).
_lic = P.job_licence_refusal(new_job.get("params") or {})
if _lic:
h._json(_lic, 451); return
with P.QUEUE_COND:
P.STATE["queue"].append(new_job)
P.QUEUE_COND.notify_all()
P.persist_queue()
h._json({"ok": True, "id": new_job["id"],
"resumed_from_part": manifest.get("done_parts"),
"total_parts": manifest.get("total_parts")})
@post("/take/join_partial")
def post_take_join_partial(h, path, qs, ctype) -> None:
_rb = h._read_form_body()
if _rb is None:
return
body, form = _rb
manifest = _load_take_manifest(h, form)
if manifest is None:
return
outs = [str(o) for o in (manifest.get("outs") or []) if o and P.Path(o).is_file()]
if not outs:
h._json({"error": "none of this take's parts are still on disk"}, 404); return
label = manifest.get("label") or ""
prompt = ((manifest.get("p") or {}).get("prompt")) or ""
take = manifest.get("take") or {}
final = P._unique_output_path(
P.OUTPUT,
P._descriptive_filename(label, prompt, fallback="take")
+ f"_take{take.get('seconds', len(outs) * 10)}s_partial")
# SAFETY-7: this join runs on the HTTP thread, outside the queue. It used
# `mux_pgid` — the generation queue's slot — so a join overlapping a
# queued render's encode overwrote that render's registration (Stop then
# killed the join and left the encode running, unstoppable). It has its
# own slot now, and one join at a time owns it.
if not _TAKE_JOIN_LOCK.acquire(blocking=False):
h._json({"error": "Another “Join what’s done” is still running — "
"try again when it finishes."}, 409); return
try:
P._join_take_parts(str(P.FFMPEG), outs, final, job=None,
pgid_key="take_join_pgid")
except Exception as exc: # noqa: BLE001
h._json({"error": f"join failed: {exc}"}, 500); return
finally:
_TAKE_JOIN_LOCK.release()
# SAFETY-11: the joined clip's take block has the COMPLETED shape (what a
# finished One Shot writes): `beats` is the beat TEXT, not the manifest's
# input-shaped count — New Take and Load Params read it as text.
beat_texts = take.get("beat_prompts") if isinstance(take.get("beat_prompts"), list) \
else (take.get("beats") if isinstance(take.get("beats"), list) else [])
seeds = manifest.get("part_seeds") if isinstance(manifest.get("part_seeds"), list) else []
done_take = {**{k: v for k, v in take.items() if k != "_resume"},
"beats": list(beat_texts), "parts": outs, "stopped_early": True,
"joined_partial": True,
"parts_meta": [{"seed_used": sd} for sd in seeds]}
side = {
"output": str(final), "raw_output": str(final), "native_output": str(final),
"mode": (manifest.get("p") or {}).get("mode", "t2v"),
"engine": manifest.get("engine"), "prompt": prompt,
"label": f"{label or 'one shot'} · {len(outs)} of {manifest.get('total_parts')} parts (stopped early)",
"take": done_take,
"params": {**(manifest.get("p") or {}), "take": done_take},
}
P.write_sidecar(final.with_suffix(final.suffix + ".json"), side)
# The joined file is now the canonical output; the raw parts go back to
# being hidden working files, same as a take that finished normally —
# the rendered cards (SAFETY-5) as well as any speech intermediates.
for o in dict.fromkeys(outs + [str(v) for v in (manifest.get("visible") or []) if v]):
try:
P.set_hidden(o, True)
except Exception: # noqa: BLE001
pass
h._json({"ok": True, "output": str(final), "parts_joined": len(outs)})