Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.
Python ai-filmmakingai-videoai-video-generatorapple-siliconhailuoimage-to-videolip-synclocal-ailora-trainingltx-2ltx-2-5ltx-videomacosminimax-h3mlxmusic-generationoffline-aipinokiotext-to-videovideo-generation
release(v4.8.1): the update that actually delivers the memory fix
mrbizarrod79020320c4a
diff --git a/VERSION b/VERSIONindex 88f1811..2871567 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-4.8.0+4.8.1\ No newline at end of filediff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex 5f432c0..4dec3c8 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -9298,14 +9298,13 @@ def _h3_q8_dit_dir() -> Path | None:def h3_dit_choice() -> tuple[str, Path | None]:"""Which DiT this Mac should render with: ("bf16"|"q8", path).- The system decides from RAM, the same signal every other capability tier- uses — a 64 GB Mac keeps the bf16 master (max quality, its peak fits), a- sub-60 GB Mac gets the Q8 pack (27.3 vs 42.8 GiB measured peak, +3% wall,- faces held in the 2026-08-10 A/B). `h3_dit` in Settings overrides both- ways: "q8" lets a 64 GB machine reclaim ~15 GiB for the rest of the OS- (the mic-dies / video-stalls complaint), "bf16" forces max quality where- it fits. An override that names a pack that is not on disk falls back- loudly in /status rather than silently."""+ AUTO prefers the compact Q8 engine wherever the pack exists, on every+ size of Mac (owner-graded A/B; numbers in the comment below). `h3_dit`+ in Settings overrides both ways: "bf16" forces the full master, "q8"+ forces compact. Any resolution that lands on bf16 without the user+ asking for it — the pre-v4.8.0-install case where the Q8 pack was never+ built — is surfaced loudly in /status (`dit_choice.reason`) and in the+ render log at dispatch, never silently."""pref = str(get_settings().get("h3_dit") or "auto").strip().lower()q8 = _h3_q8_dit_dir()if pref == "q8" and q8 is not None:@@ -10930,10 +10929,19 @@ def h3_status() -> dict:"base_model": _CIVITAI_VIDEO_FAMILIES["h3"][0]}),"min_ram_gb": H3_MIN_RAM_GB,"min_ram_gb_q8": H3_MIN_RAM_GB_Q8,- "dit_choice": (lambda _c: {"kind": _c[0],- "q8_pack": str(_c[1]) if _c[1] else None,- "q8_available": _h3_q8_dit_dir() is not None,- "pref": str(get_settings().get("h3_dit") or "auto")})(h3_dit_choice()),+ "dit_choice": (lambda _c, _p: {+ "kind": _c[0],+ "q8_pack": str(_c[1]) if _c[1] else None,+ "q8_available": _h3_q8_dit_dir() is not None,+ "pref": _p,+ # Names the situation instead of making the reader derive it:+ # "auto_no_q8_pack" is the pre-v4.8.0-install case where AUTO+ # wants the compact engine and Install never built one.+ "reason": ("auto_no_q8_pack" if (_c[0] == "bf16" and _p != "bf16")+ else "explicit" if _p == _c[0]+ else "auto_q8")})(+ h3_dit_choice(),+ str(get_settings().get("h3_dit") or "auto").strip().lower()),"ram_gb": round(SYSTEM_RAM_GB, 1),"root": paths["root"],"models": paths["models"],@@ -20841,6 +20849,17 @@ def run_h3_job_inner(job: dict) -> None:if chain_prompts_path is None:cmd.append(prompt)_dit_kind, _dit_q8 = h3_dit_choice()+ if _dit_kind == "bf16" and \+ str(get_settings().get("h3_dit") or "auto").strip().lower() != "bf16":+ # AUTO wanted the compact engine and there is none on disk. Installs+ # made before v4.8.0 never built the Q8 pack on 64 GB+ Macs, and+ # Update ships code, not weights — so "I updated but the memory is+ # the same" is exactly this line's job to explain, in the log the+ # user actually reads, at the moment it matters.+ push("H3 is rendering with the FULL bf16 engine (~39-48 GB resident): "+ "the compact Q8 engine is not built on this install. Re-run the "+ "H3 engine Install (safe to repeat, ~5 min) to build it and "+ "halve H3's memory.")_dit_path = _dit_q8 if (_dit_kind == "q8" and _dit_q8 is not None) else paths["dit"]cmd += ["--dit", str(_dit_path),@@ -44879,10 +44898,11 @@ HTML = r"""<!doctype html><div class="hint" id="settingsH3DitHint" style="margin-top:6px" hidden>Measured on the same prompt and seed: <b>Full 38.9 GiB</b> peak in 196.9 sversus <b>Compact 21.4 GiB</b> in 200.1 s — <b>45 % less memory for 1.6 %- more time</b>. Automatic gives a 64 GB Mac the full model and anything- smaller the compact one. Choose Compact if you want to keep using the Mac- while it renders; the memory it gives back is memory H3 was holding, not- memory it needed.+ more time</b>. Automatic prefers the Compact engine on every size of Mac;+ Full runs only when you choose it here — or when the Compact engine is+ not built on this install (re-run the H3 engine Install to build it).+ The memory Compact gives back is memory H3 was holding, not memory it+ needed.</div><div class="hint" style="margin-top:6px">Never changes the result — the clip is byte-for-byte the same either way.diff --git a/mlx_warm_helper.py b/mlx_warm_helper.pyindex ebb888a..3911a3a 100644--- a/mlx_warm_helper.py+++ b/mlx_warm_helper.py@@ -207,6 +207,101 @@ def _aggressive_cleanup_before_generate() -> None:pass+# =============================================================================+# A2V AUDIO ADHESION — the slider that was never connected (on the Q8 path)+# =============================================================================+#+# The panel has shipped an "Audio conditioning strength" control (0.5-5.0,+# "Higher = stronger audio adhesion") since A2V landed. On the Q8 two-stage+# path the engine has never had a parameter by that name: the vendored+# `A2VidPipelineTwoStage.generate_and_save()` does not accept+# `audio_conditioning_scale`, so `_filter_unsupported_kwargs` DROPPED it on+# every render. Verified by introspection, not by reading:+#+# DROPPED every a2v render: ['audio_conditioning_scale']+#+# The real knob there is `modality_scale` on MultiModalGuiderParams — "how+# strongly the model reacts to the modality perturbation" — and+# `_denoise_stage1` hardcodes it: video 3.0, audio bare default. Nobody had+# ever swept it, because the control that looked like it did was inert.+#+# The Q4 distilled path is DIFFERENT and this patch must stay away from it:+# `A2VidDistilledPipeline` (local a2vid_distilled.py) natively accepts+# `audio_conditioning_scale` (it amplifies the audio tokens before the DiT)+# and its overridden generate_and_save uses plain `denoise_loop` — no+# guiders, so no `modality_scale` exists on that path at all. The distilled+# branch passes the kwarg through natively and does not touch this state.+#+# Patched here rather than in the vendored engine so it costs no fork tag and+# an older pipeline simply keeps its own defaults.+# Holder dict, not a module global: the a2v branch lives deep inside the+# main loop where a `global` statement collides with earlier assignments.+_A2V_STATE = {"modality_scale": None}+++def _a2v_modality_scale_value(raw):+ """Parse the slider off the job params: '14.0' -> 14.0; ''/None/0/'0'/+ garbage/negative -> None (= keep the engine's own 3.0 default)."""+ try:+ value = float(raw or 0)+ except (TypeError, ValueError):+ return None+ return value if value > 0 else None+++def _a2v_stage1_guider_params(guider_params_cls, cfg_scale, stg_scale):+ """The (video, audio) guider params for a2v stage 1, exactly as the+ vendored `_denoise_stage1` builds them — except `modality_scale` reads+ `_A2V_STATE` instead of the hardcoded 3.0. Split out so the test suite+ can drive the real MultiModalGuiderParams class through it."""+ ms = _A2V_STATE.get("modality_scale")+ ms = 3.0 if ms is None else float(ms)+ video_gp = guider_params_cls(cfg_scale=cfg_scale, stg_scale=stg_scale,+ rescale_scale=0.7, modality_scale=ms,+ stg_blocks=[28])+ audio_gp = guider_params_cls()+ return video_gp, audio_gp+++def _install_a2v_modality_patch() -> bool:+ """Make `_denoise_stage1` read `_A2V_STATE['modality_scale']`. Idempotent."""+ try:+ from ltx_pipelines_mlx.a2vid_two_stage import ( # noqa: PLC0415+ A2VidPipelineTwoStage as _P,+ )+ from ltx_core_mlx.components.guiders import ( # noqa: PLC0415+ MultiModalGuiderParams as _GP,+ create_multimodal_guider_factory as _mk,+ )+ from ltx_pipelines_mlx.utils.samplers import ( # noqa: PLC0415+ guided_denoise_loop as _loop,+ )+ except Exception: # noqa: BLE001+ return False+ if getattr(_P, "_phos_modality_patched", False):+ return True++ def _denoise_stage1(self, x0_model, video_state, audio_state, video_embeds,+ audio_embeds, neg_video_embeds, neg_audio_embeds,+ sigmas, cfg_scale=3.0, stg_scale=1.0):+ video_gp, audio_gp = _a2v_stage1_guider_params(_GP, cfg_scale, stg_scale)+ # Build the factories BEFORE the flush, exactly as upstream does — the+ # flush frees memory and the original ordering is part of its contract.+ video_factory = _mk(video_gp, negative_context=neg_video_embeds)+ audio_factory = _mk(audio_gp, negative_context=neg_audio_embeds)+ self._pre_denoise_flush(video_state, audio_state)+ return _loop(+ model=x0_model, video_state=video_state, audio_state=audio_state,+ video_text_embeds=video_embeds, audio_text_embeds=audio_embeds,+ video_guider_factory=video_factory,+ audio_guider_factory=audio_factory,+ sigmas=sigmas)++ _P._denoise_stage1 = _denoise_stage1+ _P._phos_modality_patched = True+ return True++def _apply_vae_streaming_decision(num_frames: int) -> None:"""Set/unset os.environ['LTX_VAE_STREAMING'] for the upcoming decode.No-op if the user pinned a value at helper start time. Threshold reads@@ -3362,6 +3457,18 @@ for line in sys.__stdin__:stg_scale=float(p.get("stg_scale", 1.0)),audio_start_time=float(p.get("audio_start_time", 0.0)),)+ # Route the "Audio conditioning strength" slider to the knob that+ # exists. It was sent for years as an `audio_conditioning_scale`+ # kwarg that `generate_and_save` does not accept, so the signature+ # filter dropped it on EVERY render. The real control is+ # `modality_scale` on the stage-1 video guider, hardcoded to 3.0.+ _A2V_STATE["modality_scale"] = _a2v_modality_scale_value(+ p.get("audio_conditioning_scale"))+ if _A2V_STATE["modality_scale"] is not None:+ ok = _install_a2v_modality_patch()+ emit({"event": "log",+ "line": f"[a2v] audio adhesion modality_scale="+ f"{_A2V_STATE['modality_scale']:.2f} (patched={ok})"})# Optional reference image — when present, conditions frame 0# so the audio-driven generation opens on the user's still.ref_image = p.get("image") or None@@ -3465,7 +3572,13 @@ for line in sys.__stdin__:stage1_steps=int(p.get("stage1_steps", 8)),stage2_steps=int(p.get("stage2_steps", 3)),audio_start_time=float(p.get("audio_start_time", 0.0)),- audio_conditioning_scale=float(p.get("audio_conditioning_scale", 1.0)),+ # NATIVE here, unlike the Q8 path: A2VidDistilledPipeline+ # accepts this kwarg and amplifies the audio tokens with it+ # before the DiT. Its denoise is plain `denoise_loop` — no+ # guiders — so the modality_scale patch has nothing to drive+ # on this path and must not claim otherwise in the log.+ audio_conditioning_scale=float(+ p.get("audio_conditioning_scale") or 1.0),)ref_image = p.get("image") or Noneif ref_image:diff --git a/scripts/check_post_update.js b/scripts/check_post_update.jsindex da7b7e4..69a994b 100644--- a/scripts/check_post_update.js+++ b/scripts/check_post_update.js@@ -56,6 +56,7 @@ const optional = [["smolagents", /smolagents>=/],["the mosaic upscaler fetch", /spatial_upscaler_x2_v1_1/],["the LTX-2.5 weight fetch", /fetch_pack_release\.py/],+ ["the H3 compact-engine build", /h3_build_q8\.sh/],["the model trim", /^rm -f /],]diff --git a/scripts/pinokio/h3_build_q8.sh b/scripts/pinokio/h3_build_q8.shindex 9fe8382..cccb254 100644--- a/scripts/pinokio/h3_build_q8.sh+++ b/scripts/pinokio/h3_build_q8.sh@@ -19,8 +19,8 @@# deterministic), so the build runs fine on the same 48 GB machine that could# never load the model whole. ~22 GB on disk, ~5 min.#-# 64 GB+ Macs skip it: bf16 is the quality default there, and the panel can-# build the pack later from Settings if the user wants the low-RAM mode.+# Since v4.8.0 the Q8 engine is the panel's AUTO DEFAULT on every machine,+# so every machine builds the pack — see the gate comment below.APP_ROOT="$1"if [ -z "$APP_ROOT" ]; then@@ -28,14 +28,20 @@ if [ -z "$APP_ROOT" ]; thenexit 2fi-MEM_BYTES=$(sysctl -n hw.memsize 2>/dev/null)PACK="$APP_ROOT/mlx_models/hailuo-h3/models/h3-dit-q8"SRC="$APP_ROOT/mlx_models/hailuo-h3/models/deepbeep-pruned-bf16/MiniMax-H3-FL2VA-pruned_bf16.safetensors"+# EVERY machine builds the pack now. Until v4.8.0 this step was skipped on+# 64 GB+ Macs ("bf16 is the quality default there") — and then v4.8.0 made Q8+# the AUTO DEFAULT everywhere without un-gating this build, so on a big Mac+# the new default silently fell back to bf16 for want of a pack that Install+# refused to build. Field report, day one: "i updated but still getting this+# much memory" — python3.11 at 47.76 GB, which is the bf16 engine plus cache.+# The default's weights must be installable wherever the default applies;+# 22 GB of disk and ~5 min is the price of the halving the release notes+# promised. Idempotent via the pack's own quant_config.json, as before.if [ -f "$PACK/quant_config.json" ]; thenecho 'Q8 engine already built - skipping'-elif echo "$MEM_BYTES" | grep -qE '^[0-9]+$' && [ "$MEM_BYTES" -lt 60000000000 ]; then+elseecho '=== Building the reduced-RAM Q8 engine (~5 min, one time) ==='.venv/bin/python scripts/quantize_stream.py --src "$SRC" --out "$PACK"-else- echo '64 GB-class Mac - bf16 engine is the default, Q8 not built'fidiff --git a/scripts/post_update.sh b/scripts/post_update.shindex 37deed7..826f7d6 100644--- a/scripts/post_update.sh+++ b/scripts/post_update.sh@@ -237,6 +237,22 @@ echo 'Ensuring the Control IC-LoRA is present (Union, control mode, optional)…"$HF" download Lightricks/LTX-2.3-22b-IC-LoRA-Union-Control --local-dir "$ROOT/mlx_models/loras/ic" --include 'ltx-2.3-22b-ic-lora-union-control-ref0.5.safetensors' \|| echo 'WARN: Control IC-LoRA fetch failed — the Control mode will fetch it on first use, or click Repair.'+# ---- 8b. H3 compact (Q8) engine — the memory-halving default (optional) ----+# v4.8.0 made the Q8 DiT H3's AUTO default on every machine, but installs made+# before that never built the pack on 64 GB+ Macs — the install skipped it+# when bf16 was their default — so Update-only users kept rendering bf16+# silently at ~40-48 GB ("i updated but still getting this much memory").+# Update ships code; this step ships the default's weights. Gated on H3+# actually being installed here (pure-LTX installs skip in one stat call),+# idempotent via the pack's own quant_config.json, ~5 min and ~22 GB disk on+# the one run that builds. Cannot fail the update.+if [ -f "$ROOT/mlx_models/hailuo-h3/models/deepbeep-pruned-bf16/MiniMax-H3-FL2VA-pruned_bf16.safetensors" ] \+ && [ -d "$ROOT/minimax-h3-mlx" ]; then+ echo 'Ensuring the H3 compact (Q8) engine is built (halves H3 render memory)…'+ ( cd "$ROOT/minimax-h3-mlx" && bash "$ROOT/scripts/pinokio/h3_build_q8.sh" "$ROOT" ) \+ || echo 'WARN: H3 Q8 build failed — H3 keeps the full bf16 engine for now; re-run the H3 engine Install to retry.'+fi+# ---- 9. Trim variants we never load ----------------------------------------# Pre-Y1.024 installs downloaded whole repos (Q4 56 GB instead of 20, Q8 82 GB# instead of 37). `rm -f` is a no-op when the file is already gone.diff --git a/storyboard.py b/storyboard.pyindex e3feff7..b38c616 100644--- a/storyboard.py+++ b/storyboard.py@@ -917,6 +917,11 @@ _IMPLIES_SPEECH_RE = re.compile(r"|murmur(?:s|ing)|mutter(?:s|ing)|whisper(?:s|ing)|mumbl(?:es|ing)"r"|ask(?:s|ing)|answer(?:s|ing)|repl(?:y|ies|ying)|shout(?:s|ing)"r"|order(?:s|ing) (?:him|her|them|the)|instruct(?:s|ing))\b"+ # SUNG is a mouth producing words just as much as SPOKEN is — a "he sings"+ # shot with no line renders the same babbling jaw a "he says" shot does.+ # The lookbehinds keep birdsong out: "birds singing" is scenery, not a+ # mouth this law owns (same caution as `brief` needing an object above).+ r"|(?<!birds )(?<!bird )\b(?:sing(?:s|ing)|chant(?:s|ing))\b"r"|\b(?:his|her|their|its) voice\b"r"|\bin a (?:low|quiet|soft|hushed|loud|steady|calm|firm|gravelly|deep) voice\b"r"|\bmid-sentence\b|\bmid-speech\b", re.IGNORECASE)@@ -959,6 +964,19 @@ _SLOW_READ_RE = re.compile(r"|\bunder (?:his|her|their) breath\b|\blazy half-smile\b"r"|\bdrawls?\b|\bwhispers?\b",re.IGNORECASE)+# SUNG delivery is slower than speech but not half-tempo — a lyric stretches+# over the beat. Measured on the AVRELIVS "Amor fati" joint takes (2026-08-30):+# the owner-graded 121-frame take closed 6 sung words in 5.04 s, which needs+# the budget to allow >= 1.49 w/s after settle, and the 241-frame take carries+# 12 words in 10.04 s (>= 1.33). 1.5 admits both delivered cases; there is no+# truncated-sung case yet to bracket the refusal side, so the constant hugs+# the delivered evidence rather than guessing a ceiling. The 2.4 speaking+# budget would approve 21 words in the 10 s shot — nearly double what a sung+# mantra actually carries — which is why SUNG needs its own rate at all.+SPEECH_WORDS_PER_SEC_SUNG = 1.5+_SUNG_READ_RE = re.compile(+ r"(?<!birds )(?<!bird )\b(?:sing(?:s|ing)|chant(?:s|ing)|sung)\b",+ re.IGNORECASE)SPEECH_SETTLE_S = 1.0@@ -966,6 +984,11 @@ def is_slow_read(prompt: str) -> bool:"""True when the voice descriptor asks for slow delivery."""return bool(_SLOW_READ_RE.search(prompt or ""))++def is_sung(prompt: str) -> bool:+ """True when the line is sung or chanted rather than spoken."""+ return bool(_SUNG_READ_RE.search(prompt or ""))+# Spoken spans, with their words, in both dialects. The single-quote form must# survive apostrophes: a quote FLANKED BY LETTERS is punctuation inside a word# ("There's"), not the end of the line — without that rule the counter stops@@ -985,9 +1008,12 @@ def spoken_spans(prompt: str) -> list[str]:return [s for s in out if s]-def speech_fit_frames(word_count: int, fps: int = 24, slow: bool = False) -> int:+def speech_fit_frames(word_count: int, fps: int = 24, slow: bool = False,+ sung: bool = False) -> int:"""The smallest legal frame count (fps*n+1) that fits `word_count` words."""- rate = SPEECH_WORDS_PER_SEC_SLOW if slow else SPEECH_WORDS_PER_SEC+ rate = (SPEECH_WORDS_PER_SEC_SUNG if sung+ else SPEECH_WORDS_PER_SEC_SLOW if slow+ else SPEECH_WORDS_PER_SEC)need_s = word_count / rate + SPEECH_SETTLE_Sn = max(1, int((need_s * fps + fps - 1) // fps))return fps * n + 1@@ -1012,15 +1038,20 @@ def shot_pacing_problem(prompt: str, duration_s: float) -> str | None:except (TypeError, ValueError):dur = 0.0if dur > 0:+ sung = is_sung(prompt)slow = is_slow_read(prompt)- rate = SPEECH_WORDS_PER_SEC_SLOW if slow else SPEECH_WORDS_PER_SEC+ rate = (SPEECH_WORDS_PER_SEC_SUNG if sung+ else SPEECH_WORDS_PER_SEC_SLOW if slow+ else SPEECH_WORDS_PER_SEC)allowed = max(0.0, (dur - SPEECH_SETTLE_S) * rate)if words > allowed:- pace = "at this SLOW delivery" if slow else "at speaking pace"+ pace = ("at singing tempo" if sung+ else "at this SLOW delivery" if slow+ else "at speaking pace")return (f"{words} spoken words in a {dur:.1f}s shot — {pace} only "f"~{int(allowed)} fit, so the line is cut off "f"mid-sentence. Shorten the line, or lengthen the shot to "- f"at least {speech_fit_frames(words, slow=slow)} frames")+ f"at least {speech_fit_frames(words, slow=slow, sung=sung)} frames")last = spans[-1].rstrip()if last and last[-1] not in ".!?":return (f"the line ends {last[-12:]!r} — no full stop, so it plays as "diff --git a/storyboard_planner.py b/storyboard_planner.pyindex 4a98c47..0b0bf6f 100644--- a/storyboard_planner.py+++ b/storyboard_planner.py@@ -316,18 +316,25 @@ L12 A CAST CHARACTER'S APPEARANCE IS FIXED, AND YOU CANNOT SEE IT. A cast characthem. Do not write a sentence explaining why they look different. Give the castcharacter a role, a uniform and an action, describe everyone else exactly as thepremise demands, and let the trained face answer the only question you left open.-L13 NEVER WRITE SPEECH THE VIEWER CANNOT HEAR. A shot is either SPOKEN or SILENT, and you+L13 NEVER WRITE SPEECH THE VIEWER CANNOT HEAR. A shot is SPOKEN, SUNG or SILENT, and youmust choose one on purpose.SPOKEN the exact words are in the shot, in the dialogue form: <d>[English] Move out,and keep to the treeline.</d> Short - one or two sentences. The words beingpresent IN THAT TAG is what switches the voice on. Quotation marks are not asubstitute: He says, "Move out" leaves the voice switched OFF and the modelguessing. The tag, every time.+ SUNG the exact lyric is in the shot in the same dialogue form, and the description+ says the character SINGS it: He sings <d>[English] Love your fate.</d> The+ mouth then performs the lyric — this is how a music video's lip-sync shot is+ written, and the real track is laid over the cut afterwards. Sung delivery is+ SLOW: budget about 1.5 words per second against speech's 2.5. A "sings" or+ "chants" with no lyric written is the same violation as a wordless "explains".SILENT no speech happens at all. Then the description must not say that speechhappens: no explains, briefs, tells, discusses, talks, orders, argues,- murmurs, mutters, whispers, addresses, announces - and no describing a voice- ("his voice low and authoritative"). The soundscape must not carry speech- either: no murmur, chatter, voices, conversation, talking.+ murmurs, mutters, whispers, addresses, announces, sings, chants - and no+ describing a voice ("his voice low and authoritative"). The soundscape must+ not carry speech either: no murmur, chatter, voices, conversation, talking,+ singing."He explains the mission, his voice low and authoritative" with no words written is theworst of both: the model is told a man is speaking and given nothing to say, so itinvents mouth noise. If the beat needs him to brief the unit, WRITE THE LINE. If it@@ -513,9 +520,11 @@ ACID TEST before you write a shot: can a reader point at exactly one subject thewill hold? If not, rewrite it.DURATION: 3 s for a beat or a cutaway, 5 s for one action or one short spoken line, 10 s-only when a line genuinely needs it. Speech runs about 2.5 words per second; add one second-of breath before the line and about one and a half seconds of silence after it, then round-up. Never trim a line the brief gave you in order to fit a duration - lengthen the shot.+only when a line genuinely needs it. Speech runs about 2.5 words per second; a SUNG line+runs about 1.5 - a lyric stretches over the beat, so a sung shot needs noticeably more+seconds than its spoken twin. Add one second of breath before the line and about one and a+half seconds of silence after it, then round up. Never trim a line the brief gave you in+order to fit a duration - lengthen the shot.VARIETY IS A HARD REQUIREMENT, not a preference. Before you answer, look down the list of"camera" values you have written: no two consecutive shots may share one, and a six-shot@@ -654,6 +663,8 @@ Rules:equally-weighted moments is not a scene.3. WRITE THE ACTUAL LINES. Every line of dialogue is words a person says out loud, in doublequotes, attributed by name. Never "he explains the situation" — write what he says.+ A sung line works the same way: write the exact lyric in double quotes and mark the+ attribution "(sings)" after the name. Never "she sings the chorus" — write the words.4. Spread the dialogue across the scene. Do not put every line in the first beat.5. Some beats have no dialogue at all. Those are where the scene breathes; say what theperson is DOING instead.@@ -686,7 +697,9 @@ def _screenplay_text(resp: Dict[str, Any]) -> str:# A beat line or an attributed line of dialogue. Anything else is chatter.-_SCREENPLAY_LINE_RE = re.compile(r"^(?:BEAT\b|[A-Z][A-Za-z0-9 _\'-]{0,30}:)")+# The class carries parentheses so a sung attribution — NAME (sings): "..." —+# survives the filter; without them every lyric line was silently dropped.+_SCREENPLAY_LINE_RE = re.compile(r"^(?:BEAT\b|[A-Z][A-Za-z0-9 _\'()-]{0,30}:)")def _build_screenplay_prompt(concept: str, n_shots: int, style: str,@@ -1488,7 +1501,10 @@ _SPEECH_VERB_RE = re.compile(r"announc(?:es|ing)|declar(?:es|ing)|recit(?:es|ing)|narrat(?:es|ing)|"r"chat(?:s|ting)?|converse(?:s)?|conversing|reply|replies|replying|"r"answer(?:s|ing)?|ask(?:s|ing)?|shout(?:s|ing)?|call(?:s|ing) out|"- r"read(?:s|ing)? (?:it )?(?:aloud|out))\b", re.IGNORECASE)+ r"read(?:s|ing)? (?:it )?(?:aloud|out))\b"+ # SUNG counts: a singing mouth with no lyric babbles exactly like a+ # speaking one. Bird guards keep "birds singing" scenery out of the law.+ r"|(?<!birds )(?<!bird )\b(?:sing(?:s|ing)|chant(?:s|ing))\b", re.IGNORECASE)# Describing a voice is describing speech, even with no verb._VOICE_DESC_RE = re.compile(@@ -1541,6 +1557,10 @@ _SILENT_VERB_SWAP = (r"|\baddress(?:es|ing)?\b|\brecit(?:es|ing)\b|\bnarrat(?:es|ing)\b"r"|\bask(?:s|ing)?\b|\banswer(?:s|ing)?\b|\brepl(?:y|ies|ying)\b"r"|\bshout(?:s|ing)?\b", re.IGNORECASE), "looks up"),+ # A wordless singing shot must not keep the claim that a mouth carries a+ # melody — swaying keeps the musical beat in the body instead.+ (re.compile(r"(?<!birds )(?<!bird )\bsing(?:s|ing)\b|\bchant(?:s|ing)\b",+ re.IGNORECASE), "sways"),)diff --git a/test_a2v_audio_adhesion.py b/test_a2v_audio_adhesion.pynew file mode 100644index 0000000..fdbe15b--- /dev/null+++ b/test_a2v_audio_adhesion.py@@ -0,0 +1,258 @@+"""The A2V "Audio conditioning strength" slider — routed to a knob that exists.++The panel shipped this slider (0.5-5.0, "Higher = stronger audio adhesion")+from the day A2V landed, and on the Q8 two-stage path it did NOTHING for its+whole life: the vendored `A2VidPipelineTwoStage.generate_and_save()` has no+`audio_conditioning_scale` parameter, so `_filter_unsupported_kwargs` dropped+the kwarg silently on every render. The fix routes the slider to the knob+that does exist — `modality_scale` on the stage-1 video guider, which the+vendored `_denoise_stage1` hardcodes to 3.0 — via a helper-side monkeypatch.++The Q4 distilled path is the OPPOSITE case and this suite pins both sides:+`A2VidDistilledPipeline` (local a2vid_distilled.py) natively accepts+`audio_conditioning_scale` (it amplifies the audio tokens before the DiT) and+its denoise is plain `denoise_loop` — no guiders, so no `modality_scale`+exists there. The first draft of the fix removed that working native kwarg+and staged the (inert) guider patch with a `patched=True` log line. This+suite exists so that class of confusion cannot ship again.++House rules honoured here:+- Helper functions are read out of `mlx_warm_helper.py` with `ast`, never+ imported — the module body ends in a blocking stdin read.+- The vendored original is asserted from its FILE, not from the class —+ installing the patch in-process replaces the class attribute, and a test+ that inspects the patched method thinks upstream still matches forever.+- The guider params object driven through the plumbing is the REAL+ `MultiModalGuiderParams`, not a stub.+"""++import ast+import importlib.util+import inspect+import unittest+from pathlib import Path++HELPER = Path(__file__).with_name("mlx_warm_helper.py")++_WANTED = {+ "_A2V_STATE",+ "_a2v_modality_scale_value",+ "_a2v_stage1_guider_params",+ "_install_a2v_modality_patch",+}++# The vendored method's exact positional shape. The replacement must match it+# name-for-name, default-for-default: pipelines call it positionally.+_STAGE1_ARGS = [+ "self", "x0_model", "video_state", "audio_state", "video_embeds",+ "audio_embeds", "neg_video_embeds", "neg_audio_embeds", "sigmas",+ "cfg_scale", "stg_scale",+]+_STAGE1_DEFAULTS = {"cfg_scale": 3.0, "stg_scale": 1.0}+++def _extract_helpers() -> dict:+ """Exec ONLY the a2v adhesion state + functions, out of the real file."""+ tree = ast.parse(HELPER.read_text())+ picked, seen = [], set()+ for node in tree.body:+ if isinstance(node, ast.Assign):+ names = {t.id for t in node.targets if isinstance(t, ast.Name)}+ if names & _WANTED:+ picked.append(node)+ seen |= names & _WANTED+ elif isinstance(node, ast.FunctionDef) and node.name in _WANTED:+ picked.append(node)+ seen.add(node.name)+ missing = _WANTED - seen+ if missing:+ raise AssertionError(+ f"mlx_warm_helper.py no longer defines: {sorted(missing)}")+ ns: dict = {"__name__": "a2v_adhesion_extract"}+ exec(compile(ast.Module(body=picked, type_ignores=[]), str(HELPER), "exec"), ns)+ return ns+++def _vendored_source() -> str:+ """The a2vid_two_stage FILE — immune to in-process monkeypatching."""+ spec = importlib.util.find_spec("ltx_pipelines_mlx.a2vid_two_stage")+ if spec is None or not spec.origin:+ raise AssertionError("ltx_pipelines_mlx.a2vid_two_stage is not installed")+ return Path(spec.origin).read_text()+++def _vendored_stage1_def() -> ast.FunctionDef:+ tree = ast.parse(_vendored_source())+ for node in ast.walk(tree):+ if isinstance(node, ast.ClassDef) and node.name == "A2VidPipelineTwoStage":+ for item in node.body:+ if isinstance(item, ast.FunctionDef) and item.name == "_denoise_stage1":+ return item+ raise AssertionError(+ "A2VidPipelineTwoStage._denoise_stage1 no longer exists upstream — "+ "the adhesion patch targets a method that is gone")+++class SliderParse(unittest.TestCase):+ """'14.0' -> 14.0; everything that means 'unset' -> None."""++ def setUp(self):+ self.parse = _extract_helpers()["_a2v_modality_scale_value"]++ def test_table(self):+ for raw, want in (+ ("14.0", 14.0), ("9", 9.0), ("3.5", 3.5), (5, 5.0), (0.5, 0.5),+ ("", None), (None, None), ("0", None), (0, None), (0.0, None),+ ("-2", None), ("garbage", None), ([], None),+ ):+ with self.subTest(raw=raw):+ self.assertEqual(self.parse(raw), want)+++class UpstreamContract(unittest.TestCase):+ """The vendored engine still has the shape the patch assumes."""++ def test_q8_generate_and_save_still_lacks_the_kwarg(self):+ # The day this fails is a GOOD day: upstream grew a native audio+ # conditioning parameter. Route the slider to it and delete+ # _install_a2v_modality_patch — do not keep both.+ from ltx_pipelines_mlx.a2vid_two_stage import A2VidPipelineTwoStage+ sig = inspect.signature(A2VidPipelineTwoStage.generate_and_save)+ self.assertNotIn(+ "audio_conditioning_scale", sig.parameters,+ "Upstream generate_and_save now accepts audio_conditioning_scale "+ "natively — pass it through and remove the modality_scale patch.")++ def test_vendored_stage1_signature_matches_the_replacement(self):+ node = _vendored_stage1_def()+ args = [a.arg for a in node.args.args]+ self.assertEqual(args, _STAGE1_ARGS,+ "Upstream _denoise_stage1 changed shape — the "+ "replacement in mlx_warm_helper.py must be re-mirrored")+ defaults = {+ a.arg: d.value+ for a, d in zip(args[-len(node.args.defaults):] and+ node.args.args[-len(node.args.defaults):],+ node.args.defaults)+ if isinstance(d, ast.Constant)+ }+ self.assertEqual(defaults, _STAGE1_DEFAULTS)++ def test_vendored_stage1_still_hardcodes_3_0(self):+ # The patch exists BECAUSE upstream hardcodes modality_scale=3.0 on+ # the stage-1 video guider. If that line changes, the replacement's+ # None -> 3.0 fallback no longer reproduces upstream behaviour.+ src = ast.get_source_segment(_vendored_source(), _vendored_stage1_def())+ self.assertIn("modality_scale=3.0", src)++ def test_guider_params_accepts_what_we_pass(self):+ from ltx_core_mlx.components.guiders import MultiModalGuiderParams+ gp = MultiModalGuiderParams(cfg_scale=2.0, stg_scale=1.0,+ rescale_scale=0.7, modality_scale=14.0,+ stg_blocks=[28])+ self.assertEqual(gp.modality_scale, 14.0)++ def test_guided_denoise_loop_accepts_our_kwargs(self):+ from ltx_pipelines_mlx.utils.samplers import guided_denoise_loop+ params = inspect.signature(guided_denoise_loop).parameters+ for name in ("model", "video_state", "audio_state", "video_text_embeds",+ "audio_text_embeds", "video_guider_factory",+ "audio_guider_factory", "sigmas"):+ self.assertIn(name, params)++ def test_install_succeeds_and_is_idempotent(self):+ ns = _extract_helpers()+ install = ns["_install_a2v_modality_patch"]+ self.assertTrue(install(), "patch failed to install against the venv")+ from ltx_pipelines_mlx.a2vid_two_stage import A2VidPipelineTwoStage+ self.assertTrue(A2VidPipelineTwoStage._phos_modality_patched)+ first = A2VidPipelineTwoStage._denoise_stage1+ self.assertTrue(install())+ self.assertIs(A2VidPipelineTwoStage._denoise_stage1, first,+ "second install re-wrapped the method")++ def test_factories_are_built_before_the_flush(self):+ # Upstream builds both guider factories and THEN calls+ # _pre_denoise_flush; the flush frees memory and that ordering is part+ # of its contract. The replacement must keep it.+ src = HELPER.read_text()+ tree = ast.parse(src)+ block = None+ for node in tree.body:+ if isinstance(node, ast.FunctionDef) and \+ node.name == "_install_a2v_modality_patch":+ block = ast.get_source_segment(src, node)+ self.assertIsNotNone(block)+ self.assertLess(block.index("_mk("), block.index("_pre_denoise_flush("))+++class ValuePlumbing(unittest.TestCase):+ """The slider value reaches the real MultiModalGuiderParams object."""++ def setUp(self):+ self.ns = _extract_helpers()+ from ltx_core_mlx.components.guiders import MultiModalGuiderParams+ self.gp_cls = MultiModalGuiderParams++ def _params(self, staged, cfg_scale=3.0, stg_scale=1.0):+ self.ns["_A2V_STATE"]["modality_scale"] = staged+ return self.ns["_a2v_stage1_guider_params"](self.gp_cls,+ cfg_scale, stg_scale)++ def test_staged_value_lands_on_the_video_guider(self):+ for staged in (0.5, 3.0, 9.0, 14.0):+ with self.subTest(staged=staged):+ video_gp, _ = self._params(staged)+ self.assertEqual(video_gp.modality_scale, staged)++ def test_unset_reproduces_upstream_exactly(self):+ video_gp, _ = self._params(None)+ self.assertEqual(video_gp.modality_scale, 3.0)++ def test_cfg_and_stg_pass_through(self):+ video_gp, _ = self._params(9.0, cfg_scale=2.5, stg_scale=0.5)+ self.assertEqual(video_gp.cfg_scale, 2.5)+ self.assertEqual(video_gp.stg_scale, 0.5)+ self.assertEqual(video_gp.rescale_scale, 0.7)+ self.assertEqual(video_gp.stg_blocks, [28])++ def test_audio_guider_stays_bare_default(self):+ # Stage 1 freezes audio; upstream gives it a bare params object. The+ # slider must never leak onto the audio guider.+ _, audio_gp = self._params(14.0)+ bare = self.gp_cls()+ self.assertEqual(audio_gp.modality_scale, bare.modality_scale)+ self.assertEqual(audio_gp.cfg_scale, bare.cfg_scale)+++class DistilledPathStaysNative(unittest.TestCase):+ """Q4 distilled has its OWN knob and no guiders — leave it alone."""++ def test_distilled_accepts_the_kwarg_natively(self):+ from a2vid_distilled import A2VidDistilledPipeline+ sig = inspect.signature(A2VidDistilledPipeline.generate_and_save)+ self.assertIn("audio_conditioning_scale", sig.parameters)+ self.assertEqual(+ sig.parameters["audio_conditioning_scale"].default, 1.0)++ def test_distilled_never_reaches_the_patched_method(self):+ # The fact that makes the guider patch inert on this path. If the+ # distilled pipeline ever starts calling _denoise_stage1 or a guided+ # loop, the helper's distilled branch needs the modality routing too.+ src = Path(__file__).with_name("a2vid_distilled.py").read_text()+ self.assertNotIn("_denoise_stage1", src)+ self.assertNotIn("guided_denoise_loop", src)++ def test_helper_stages_modality_scale_on_exactly_one_branch(self):+ # The Q8 branch stages the patch; the distilled branch passes the+ # native kwarg. A second staging site means someone re-attached the+ # inert patch to the distilled path (the first-draft mistake).+ src = HELPER.read_text()+ self.assertEqual(+ src.count('_A2V_STATE["modality_scale"] = _a2v_modality_scale_value('),+ 1)+ self.assertIn("audio_conditioning_scale=float(", src)+++if __name__ == "__main__":+ unittest.main()diff --git a/test_h3_q8_default_buildable.py b/test_h3_q8_default_buildable.pynew file mode 100644index 0000000..b9f3ea9--- /dev/null+++ b/test_h3_q8_default_buildable.py@@ -0,0 +1,61 @@+"""The default's weights must be installable wherever the default applies.++v4.8.0 made the compact Q8 engine H3's AUTO default on every machine — but+`h3_build_q8.sh` still skipped the build on 64 GB+ Macs from the era when+bf16 was their default. Result, field-reported the day after release: a+fully-updated install rendering H3 at 47.76 GB resident, because AUTO wanted+a pack that Install had refused to build and fell back to bf16 without a+word. This suite pins the three parts of the fix:++ 1. the build script has NO memory gate — every machine builds the pack;+ 2. the dispatch says OUT LOUD when it falls back to bf16 un-asked;+ 3. /status names the situation (`dit_choice.reason = auto_no_q8_pack`)+ instead of making the reader derive it from three booleans.+"""++import re+import unittest+from pathlib import Path++ROOT = Path(__file__).parent+BUILD_SH = ROOT / "scripts" / "pinokio" / "h3_build_q8.sh"+PANEL = ROOT / "mlx_ltx_panel.py"+++class BuildScriptBuildsEverywhere(unittest.TestCase):+ def setUp(self):+ self.src = BUILD_SH.read_text()++ def test_no_memory_gate(self):+ self.assertNotIn("hw.memsize", self.src,+ "the Q8 build is gated on RAM again — but Q8 is the "+ "AUTO default on every machine, so every machine "+ "must be able to build the pack")+ self.assertNotIn("bf16 engine is the default", self.src)++ def test_still_idempotent(self):+ # The re-run gate is the pack's own quant_config.json; losing it+ # would re-quantize 22 GB on every Install click.+ self.assertIn("quant_config.json", self.src)+ self.assertIn("already built", self.src)+++class TheFallbackIsLoud(unittest.TestCase):+ def setUp(self):+ self.src = PANEL.read_text()++ def test_dispatch_announces_unasked_bf16(self):+ # The push() at the H3 dispatch. Silent bf16 is the bug that made+ # "I updated but the memory is the same" undiagnosable from the log.+ self.assertIn("the compact Q8 engine is not built on this install",+ self.src)++ def test_status_names_the_reason(self):+ self.assertIn("auto_no_q8_pack", self.src)++ def test_hint_no_longer_promises_bf16_to_big_macs(self):+ self.assertNotIn("Automatic gives a 64 GB Mac the full model", self.src)+++if __name__ == "__main__":+ unittest.main()diff --git a/test_storyboard_sung.py b/test_storyboard_sung.pynew file mode 100644index 0000000..f415bae--- /dev/null+++ b/test_storyboard_sung.py@@ -0,0 +1,129 @@+"""SUNG — the third honest state of the speech law.++The storyboard's dialogue machinery has always known SPOKEN and SILENT, and+singing fell through the crack in both directions: a "he sings" shot with no+lyric escaped the board-level law entirely (`_IMPLIES_SPEECH_RE` had no sing+verb), and a sung line WITH words was paced against the 2.4 w/s speaking+budget — nearly double what a sung mantra actually carries, so a correctly+written lyric shot either got refused as overstuffed at honest durations or+approved with double the words it could sing.++The rate is measured, not styled: the owner-graded AVRELIVS "Amor fati"+joint takes (2026-08-30) delivered 6 sung words in a 5.04 s shot (needs the+budget to allow >= 1.49 w/s after the 1 s settle) and 12 words in 10.04 s+(>= 1.33). SPEECH_WORDS_PER_SEC_SUNG = 1.5 admits both.++Also pinned: the bird guard. "birds singing at dawn" is scenery, not a mouth+this law owns — the same false-positive caution `_IMPLIES_SPEECH_RE` already+carries for "brief(ing room)".+"""++import unittest++from storyboard import (+ SPEECH_WORDS_PER_SEC,+ SPEECH_WORDS_PER_SEC_SUNG,+ is_sung,+ shot_pacing_problem,+ shot_speech_problem,+ speech_fit_frames,+)+from storyboard_planner import (+ _neutralise_speech,+ _speech_violations,+)+++class SungImpliesSpeech(unittest.TestCase):+ """A singing mouth with no lyric is the wordless-explains bug in a robe."""++ def test_sings_with_no_words_is_blocked(self):+ for prompt in (+ "A marble bust of a hooded man sings directly to the camera",+ "She is chanting under the arch, arms raised",+ ):+ with self.subTest(prompt=prompt):+ self.assertIsNotNone(shot_speech_problem(prompt))++ def test_sings_with_the_lyric_is_legal(self):+ self.assertIsNone(shot_speech_problem(+ "A marble bust sings 'Amor fati. Love your fate.' directly to camera"))++ def test_birdsong_is_scenery_not_speech(self):+ for prompt in (+ "Dawn light over the marsh, birds singing in the reeds",+ "A single bird singing somewhere above the courtyard",+ ):+ with self.subTest(prompt=prompt):+ self.assertIsNone(shot_speech_problem(prompt))+++class SungDetection(unittest.TestCase):+ def test_positive_forms(self):+ for p in ("he sings 'Love your fate.'",+ "chanting 'Amor fati.' slowly",+ "the sung line 'Love your fate.' lands on the downbeat"):+ with self.subTest(p=p):+ self.assertTrue(is_sung(p))++ def test_negative_forms(self):+ for p in ("he says 'Love your fate.' slowly",+ "birds singing over the field as he watches",+ "a single tone rings out"):+ with self.subTest(p=p):+ self.assertFalse(is_sung(p))+++class SungPacing(unittest.TestCase):+ """The measured evidence, admitted; the speaking budget's blind spot, closed."""++ def test_rate_sits_between_the_evidence_and_speech(self):+ self.assertGreaterEqual(SPEECH_WORDS_PER_SEC_SUNG, 1.49,+ "refuses the owner-graded 6-words-in-5.04s take")+ self.assertLess(SPEECH_WORDS_PER_SEC_SUNG, SPEECH_WORDS_PER_SEC)++ def test_the_delivered_takes_fit(self):+ # 121f take: 6 words in 5.04 s. 241f take: 12 words in 10.04 s.+ self.assertIsNone(shot_pacing_problem(+ "He sings 'Amor fati. Love your fate.' like a mantra.", 5.04))+ self.assertIsNone(shot_pacing_problem(+ "He sings 'Amor fati. Love your fate. Amor fati. Love your fate.' "+ "twice, slowly.", 10.04))++ def test_a_spoken_sized_line_is_refused_when_sung(self):+ # 12 words in 6 s: fine spoken (allowed 12.0), overstuffed sung (7.5).+ line = "'One two three four five six seven eight nine ten eleven twelve.'"+ self.assertIsNone(shot_pacing_problem("He says " + line, 6.0))+ problem = shot_pacing_problem("He sings " + line, 6.0)+ self.assertIsNotNone(problem)+ self.assertIn("singing tempo", problem)++ def test_fit_frames_reproduces_the_graded_take(self):+ # 6 sung words -> exactly the 121-frame shot that delivered.+ self.assertEqual(speech_fit_frames(6, sung=True), 121)+++class PlannerSungLaw(unittest.TestCase):+ """Planner side: same blind spot closed, and neutralisation stays honest."""++ def test_wordless_sings_is_a_violation(self):+ problems = _speech_violations("She sings to the empty hall", "")+ self.assertTrue(any("sing" in p.lower() for p in problems))++ def test_sung_line_in_the_tag_is_no_violation(self):+ self.assertEqual(_speech_violations(+ "She sings <d>[English] Love your fate.</d> to the empty hall", ""), [])++ def test_birdsong_is_no_violation(self):+ self.assertEqual(_speech_violations(+ "He kneels in the grass, birds singing above him", ""), [])++ def test_neutralised_singing_stops_claiming_a_melody_from_a_mouth(self):+ desc, _, notes = _neutralise_speech("She sings to the empty hall", "")+ self.assertNotIn("sings", desc)+ self.assertIn("sways", desc)+ self.assertTrue(any("silenced" in n for n in notes))+++if __name__ == "__main__":+ unittest.main()