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
Y1.032 repoint Sharp export to PiperSR
mrbizarro85afc9ea55bd
diff --git a/README.md b/README.mdindex d5a50ef..3ba79ce 100644--- a/README.md+++ b/README.md@@ -113,24 +113,20 @@ Exported/upscaled files use the same **Output format** setting as nativerenders. Standard stays compact (`yuv420p` / CRF 18); Video production stayslossless (`yuv444p` / CRF 0).-The public export path uses ffmpeg Lanczos. The experimental LTX latent x2-upscaler can be forced with `LTX_ENABLE_MODEL_UPSCALE=1`, but it is hidden by-default: the official LTX upscaler is meant to be followed by a second-stage+The **Fast** export method uses ffmpeg Lanczos. The **Sharp** export method uses+PiperSR, a lightweight Apple Neural Engine 2× post-upscaler, then ffmpeg handles+the final fit/pad/encode step. The old experimental LTX latent x2 upscaler can+still be forced with `LTX_ENABLE_MODEL_UPSCALE=1`, but it is hidden by default:+the official LTX upscaler is meant to be followed by a second-stagedenoise/refinement pass, and direct decode distorted faces in release tests.-Dev builds include an opt-in PiperSR comparison tool for testing a lightweight-Apple Neural Engine 2× post-upscaler against Lanczos:+Dev builds also include a PiperSR comparison tool for testing Sharp against+Lanczos on any existing clip:```bash-ltx-2-mlx/env/bin/pip install pipersrltx-2-mlx/env/bin/python scripts/upscale_compare_pipersr.py path/to/input.mp4```-PiperSR is not bundled or enabled in the public app yet. Its code is AGPL-3.0,-and its model license requires visible attribution for public-facing apps plus-separate licensing for commercial use. Keep it as a lab experiment until that-licensing decision is settled.-Standard T2V/I2V also has an opt-in **Speed** control:- **Exact** is the default full sampler.@@ -419,6 +415,8 @@ This is a wrapper, not a fork. All the hard model work belongs to:- **[@cocktailpeanut](https://twitter.com/cocktailpeanut)** —Pinokio itself, which makes one-click installers like thispossible+- **[ModelPiper PiperSR](https://github.com/ModelPiper/PiperSR)** —+ optional Sharp export upscaling on Apple Neural EngineThe panel adds: persistent batch queue, warm helper subprocess,hardware-tier feature gating, lossless H.264 + faststart output,@@ -468,3 +466,7 @@ commercial use.**MLX framework:** Apache 2.0.**Gemma 3 12B weights:** Google's terms.++**PiperSR:** code is AGPL-3.0; model usage requires ModelPiper attribution+and may require separate commercial licensing. Review its model license before+commercial redistribution.diff --git a/VERSION b/VERSIONindex 69cdb22..361f8e4 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-Y1.031+Y1.032diff --git a/install.js b/install.jsindex 342fcb9..219bd1d 100644--- a/install.js+++ b/install.js@@ -150,7 +150,7 @@ module.exports = {// than the default Python downloader for big repos like Q8 (~25 GB).// The panel sets HF_HUB_ENABLE_HF_TRANSFER=1 in download envs; if the// package is missing the hf CLI falls back gracefully with a warning.- "uv pip install --python env/bin/python pillow numpy 'huggingface-hub>=1.0' 'hf_transfer>=0.1.6'"+ "uv pip install --python env/bin/python pillow numpy 'huggingface-hub>=1.0' 'hf_transfer>=0.1.6' 'pipersr==1.0.0'"]}},diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex ba1d68c..2c88469 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -14,6 +14,7 @@ from __future__ import annotationsimport atexitimport cgi+import importlib.utilimport jsonimport osimport re@@ -125,6 +126,7 @@ PROFILE = _detect_profile()# Running upsampler -> decode directly distorted faces and produced bad tail# frames in release tests, so keep it hidden unless explicitly opted in.MODEL_UPSCALE_ENABLED = _optional_bool_env("LTX_ENABLE_MODEL_UPSCALE") is True+PIPERSR_UPSCALE_ENABLED = _optional_bool_env("LTX_ENABLE_PIPERSR") is not False and importlib.util.find_spec("pipersr") is not None# Default port: 8198 production, 8199 dev — so both panels can run side by# side. LTX_PORT env var still overrides if the user wants something else.DEFAULT_PORT = 8199 if PROFILE == "dev" else 8198@@ -2413,8 +2415,8 @@ def compute_upscale_plan(w: int, h: int, mode: str | None,}-def run_ffmpeg_tracked(cmd: list[str], label: str) -> tuple[str, str]:- """Run an ffmpeg process in its own process group so /stop can kill it."""+def run_postprocess_tracked(cmd: list[str], label: str) -> tuple[str, str]:+ """Run a post-process in its own process group so /stop can kill it."""push(f"{label}: " + " ".join(shlex.quote(c) for c in cmd))env = os.environ.copy()env["PATH"] = f"{FFMPEG_BIN}:{env.get('PATH', '')}"@@ -2436,6 +2438,29 @@ def run_ffmpeg_tracked(cmd: list[str], label: str) -> tuple[str, str]:return stdout or "", stderr or ""+def run_ffmpeg_tracked(cmd: list[str], label: str) -> tuple[str, str]:+ """Run an ffmpeg process in its own process group so /stop can kill it."""+ return run_postprocess_tracked(cmd, label)+++def run_pipersr_tracked(source: Path, output: Path, mode: str, crf: str,+ pix_fmt: str, preset: str) -> tuple[str, str]:+ script = ROOT / "scripts" / "upscale_compare_pipersr.py"+ if not script.exists():+ raise RuntimeError("PiperSR upscale script is missing")+ if not PIPERSR_UPSCALE_ENABLED:+ raise RuntimeError("PiperSR is not installed in this environment")+ return run_postprocess_tracked([+ sys.executable, str(script), str(source),+ "--pipersr-only",+ "--mode", mode,+ "--output", str(output),+ "--crf", crf,+ "--pix-fmt", pix_fmt,+ "--preset", preset,+ ], "Sharp upscale")++def video_duration(frames: int) -> float:return round(frames / FPS, 3)@@ -2490,6 +2515,13 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,else:default_w, default_h = 1024, 576upscale = f("upscale", "fit_720p" if quality == "balanced" else "off")+ requested_upscale_method = (f("upscale_method", "lanczos") or "lanczos").strip().lower()+ if requested_upscale_method == "model":+ requested_upscale_method = "pipersr"+ if requested_upscale_method == "pipersr" and not PIPERSR_UPSCALE_ENABLED:+ requested_upscale_method = "lanczos"+ if requested_upscale_method not in ("lanczos", "pipersr"):+ requested_upscale_method = "lanczos"return {"id": _new_job_id(),@@ -2526,11 +2558,7 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,"quality": quality, # quick / balanced / standard / high"accel": f("accel", "off"), # off / boost / turbo"upscale": upscale, # off / fit_720p / x2- "upscale_method": (- "model"- if MODEL_UPSCALE_ENABLED and f("upscale_method", "lanczos") == "model"- else "lanczos"- ), # lanczos / model (model is lab-only; see LTX_ENABLE_MODEL_UPSCALE)+ "upscale_method": requested_upscale_method, # lanczos / pipersr# LoRAs the user has enabled for this job. The UI submits a# JSON-encoded array via the `loras` form field; we parse +# validate here so the worker / helper layers receive a clean@@ -2872,11 +2900,11 @@ def run_job_inner(job: dict) -> None:"image": p["image"] if mode != "t2v" else None,"loras": loras,"accel": p.get("accel", "off"),- # Normal builds force this to Lanczos in make_job(); only- # explicit lab opt-in passes "model" so the helper can run- # the experimental latent x2 upscaler.+ # Sharp/PiperSR is a panel-side post-render pass. Do not pass it+ # through to the helper; the helper's old "model" path is the+ # hidden LTX latent upscaler experiment that distorted faces."upscale": p.get("upscale", "off"),- "upscale_method": p.get("upscale_method", "lanczos"),+ "upscale_method": "lanczos",},}if loras:@@ -2934,24 +2962,37 @@ def run_job_inner(job: dict) -> None:mux_pix_fmt = codec["pix_fmt"]mux_crf = codec["crf"]upscale_preset = os.environ.get("LTX_UPSCALE_PRESET", "medium")+ upscale_method = (p.get("upscale_method", "lanczos") or "lanczos").strip().lower()+ if upscale_method == "model":+ upscale_method = "pipersr"upscaled_out = OUTPUT / (f"{final_target.stem}_{upscale_plan['tag']}{final_target.suffix}")- upscale_cmd = [- str(FFMPEG), "-y", "-i", str(final_target),- "-vf", upscale_plan["vf"],- "-c:v", "libx264", "-pix_fmt", mux_pix_fmt, "-crf", mux_crf,- "-preset", upscale_preset,- "-movflags", "+faststart",- "-c:a", "copy",- str(upscaled_out),- ]- run_ffmpeg_tracked(upscale_cmd, "Upscale")+ if upscale_method == "pipersr":+ push("Sharp upscale: PiperSR/CoreML 2× pass, then ffmpeg fit/export.")+ run_pipersr_tracked(+ final_target, upscaled_out, p.get("upscale", "fit_720p"),+ mux_crf, mux_pix_fmt, upscale_preset,+ )+ upscale_plan["method"] = "pipersr_coreml"+ upscale_plan["pre_pass"] = "pipersr_x2"+ else:+ upscale_cmd = [+ str(FFMPEG), "-y", "-i", str(final_target),+ "-vf", upscale_plan["vf"],+ "-c:v", "libx264", "-pix_fmt", mux_pix_fmt, "-crf", mux_crf,+ "-preset", upscale_preset,+ "-movflags", "+faststart",+ "-c:a", "copy",+ str(upscaled_out),+ ]+ run_ffmpeg_tracked(upscale_cmd, "Upscale")+ upscale_plan["method"] = "ffmpeg_lanczos"final_target = upscaled_outpush(f"Upscale done → {upscaled_out.name} "f"({upscale_plan['target_w']}×{upscale_plan['target_h']}, no crop, "- f"{mux_pix_fmt} crf {mux_crf}, preset={upscale_preset})"+ f"{upscale_plan['method']}, {mux_pix_fmt} crf {mux_crf}, preset={upscale_preset})")set_hidden(str(native_target), True)push(f"Native source kept but hidden from gallery → {native_target.name}")@@ -3925,6 +3966,7 @@ def page() -> str:"fps": FPS, "model": MODEL_ID,"profile": PROFILE,"model_upscale_enabled": MODEL_UPSCALE_ENABLED,+ "pipersr_upscale_enabled": PIPERSR_UPSCALE_ENABLED,# Hardware-aware time estimates for the Quality pills. The pill HTML# ships with the Comfortable-tier defaults; on boot we rewrite the# subtext using the active tier's quality_times. Compact users see@@ -5753,22 +5795,18 @@ HTML = r"""<!doctype html></div></div>- <!-- Upscale method (Y1.021). Hidden when Export = Native. Fast- = ffmpeg Lanczos resize, no detail recovery, near-instant.- Sharp = LTX 2.3 latent upscaler (~1 GB model), invents real- detail in latent space before VAE decode, ~30-60s slower.- Sharp is hidden unless LTX_ENABLE_MODEL_UPSCALE=1 because- release tests showed the standalone latent x2 path can- distort faces and corrupt tail frames. The official LTX- contract is upsample + second-stage refinement, not direct- decode. -->+ <!-- Upscale method. Hidden when Export = Native. Fast = ffmpeg+ Lanczos resize, no detail recovery, near-instant. Sharp =+ PiperSR/CoreML 2× post-upscale on Apple Neural Engine, then+ ffmpeg fit/export. The old LTX latent upscaler path remains+ hidden behind LTX_ENABLE_MODEL_UPSCALE for lab archaeology. --><div class="cz-control" id="upscaleMethodRow" style="display:none;"><div class="cz-label">Method<span class="cz-label-hint">how the upscale is done</span></div><div class="pill-group cols-2" id="upscaleMethodGroup"><button type="button" class="pill-btn active" data-method="lanczos"><span>Fast</span><span class="sub">ffmpeg Lanczos · instant</span></button>- <button type="button" class="pill-btn" data-method="model"><span>Sharp</span><span class="sub">LTX upscaler · +30-60 s · real detail</span></button>+ <button type="button" class="pill-btn" data-method="pipersr"><span>Sharp</span><span class="sub">PiperSR ANE · +10-40 s</span></button></div><input type="hidden" name="upscale_method" id="upscale_method" value="lanczos"></div>@@ -6119,6 +6157,7 @@ const BOOT = __BOOTSTRAP__;const ASPECTS = BOOT.aspects;const FPS = BOOT.fps;const MODEL_UPSCALE_ENABLED = !!BOOT.model_upscale_enabled;+const PIPERSR_UPSCALE_ENABLED = !!BOOT.pipersr_upscale_enabled;// Apply tier-aware time estimates to the Quality pill subtitles. The HTML// ships with the Comfortable-tier (M4 Studio 64 GB) numbers as defaults;@@ -6237,13 +6276,14 @@ function setUpscale(u) {// actually being applied. When toggled to "off", revert method to Fast// so a later toggle back to fit_720p starts from the safe default.const methodRow = document.getElementById('upscaleMethodRow');- if (methodRow) methodRow.style.display = (v === 'off' || !MODEL_UPSCALE_ENABLED) ? 'none' : '';- if (v === 'off' || !MODEL_UPSCALE_ENABLED) setUpscaleMethod('lanczos');+ if (methodRow) methodRow.style.display = (v === 'off' || !PIPERSR_UPSCALE_ENABLED) ? 'none' : '';+ if (v === 'off' || !PIPERSR_UPSCALE_ENABLED) setUpscaleMethod('lanczos');updateCustomizeSummary();updateDerived();}function setUpscaleMethod(m) {- const v = (MODEL_UPSCALE_ENABLED && m === 'model') ? 'model' : 'lanczos';+ if (m === 'model') m = 'pipersr'; // legacy sidecars from the retired LTX Sharp path+ const v = (PIPERSR_UPSCALE_ENABLED && m === 'pipersr') ? 'pipersr' : 'lanczos';document.getElementById('upscale_method').value = v;document.querySelectorAll('#upscaleMethodGroup .pill-btn').forEach(b => b.classList.toggle('active', b.dataset.method === v));updateCustomizeSummary();@@ -6290,7 +6330,7 @@ function updateCustomizeSummary() {// Speedparts.push(accel === 'off' ? 'exact speed' : (accel === 'boost' ? 'boost' : 'turbo'));const method = (document.getElementById('upscale_method')?.value || 'lanczos');- const methodTag = method === 'model' ? ' sharp' : '';+ const methodTag = method === 'pipersr' || method === 'model' ? ' sharp' : '';if (upscale === 'fit_720p') parts.push('720p export' + methodTag);else if (upscale === 'x2') parts.push('2× export' + methodTag);el.textContent = parts.join(' · ');@@ -7238,9 +7278,9 @@ function renderOutputInfoBody(path, data) {if (p.upscale && p.upscale !== 'off') {const up = data.upscale || {};const target = up.target_w && up.target_h ? ` → ${up.target_w} × ${up.target_h}` : '';- const isModel = p.upscale_method === 'model' || (data.upscale && (data.upscale.method === 'ltx_latent_x2' || (data.upscale.pre_pass === 'ltx_latent_x2')));+ const isSharp = p.upscale_method === 'pipersr' || p.upscale_method === 'model' || (data.upscale && (data.upscale.method === 'pipersr_coreml' || data.upscale.pre_pass === 'pipersr_x2' || data.upscale.method === 'ltx_latent_x2' || data.upscale.pre_pass === 'ltx_latent_x2'));const baseLabel = p.upscale === 'fit_720p' ? '720p fit (no crop)' : (p.upscale === 'x2' ? '2×' : p.upscale);- const label = isModel ? `${baseLabel} · Sharp (LTX upscaler)` : `${baseLabel} · Fast (Lanczos)`;+ const label = isSharp ? `${baseLabel} · Sharp (PiperSR)` : `${baseLabel} · Fast (Lanczos)`;genRows.push(`<dt>Upscale</dt><dd>${escapeHtml(label + target)}</dd>`);}const codec = data.output_codec || (data.upscale && data.upscale.codec);diff --git a/scripts/upscale_compare_pipersr.py b/scripts/upscale_compare_pipersr.pyindex 482b29a..e55632a 100755--- a/scripts/upscale_compare_pipersr.py+++ b/scripts/upscale_compare_pipersr.py@@ -63,7 +63,12 @@ def probe_video(path: Path) -> dict:return data["streams"][0]-def target_for_fit_720p(width: int, height: int) -> tuple[int, int, str]:+def target_for_mode(width: int, height: int, mode: str) -> tuple[int, int, str]:+ mode = (mode or "fit_720p").strip().lower()+ if mode == "x2":+ return width * 2, height * 2, "up2x"+ if mode not in ("fit_720p", "720p"):+ raise SystemExit(f"Unsupported upscale mode for PiperSR compare: {mode}")if width >= height:return 1280, 720, "720p"return 720, 1280, "v720p"@@ -77,9 +82,9 @@ def fit_filter(target_w: int, target_h: int) -> str:)-def make_lanczos(input_mp4: Path, output_mp4: Path, crf: str, pix_fmt: str, preset: str) -> float:+def make_lanczos(input_mp4: Path, output_mp4: Path, crf: str, pix_fmt: str, preset: str, mode: str) -> float:info = probe_video(input_mp4)- target_w, target_h, _ = target_for_fit_720p(int(info["width"]), int(info["height"]))+ target_w, target_h, _ = target_for_mode(int(info["width"]), int(info["height"]), mode)t0 = time.perf_counter()run([str(ffmpeg_path()), "-hide_banner", "-y",@@ -163,10 +168,10 @@ def piper_upscale_frames(frames_in: Path, frames_out: Path) -> float:return time.perf_counter() - t0-def make_pipersr(input_mp4: Path, output_mp4: Path, crf: str, pix_fmt: str, preset: str, keep_work: bool) -> float:+def make_pipersr(input_mp4: Path, output_mp4: Path, crf: str, pix_fmt: str, preset: str, keep_work: bool, mode: str) -> float:info = probe_video(input_mp4)fps = info.get("avg_frame_rate") or "24/1"- target_w, target_h, _ = target_for_fit_720p(int(info["width"]), int(info["height"]))+ target_w, target_h, _ = target_for_mode(int(info["width"]), int(info["height"]), mode)t0 = time.perf_counter()work_parent = output_mp4.parent if keep_work else None@@ -231,6 +236,9 @@ def main() -> int:ap.add_argument("--pix-fmt", default="yuv420p")ap.add_argument("--preset", default="medium")ap.add_argument("--keep-work", action="store_true")+ ap.add_argument("--mode", default="fit_720p", choices=("fit_720p", "x2"))+ ap.add_argument("--pipersr-only", action="store_true")+ ap.add_argument("--output", type=Path, default=None)args = ap.parse_args()input_mp4 = args.input.expanduser().resolve()@@ -239,13 +247,22 @@ def main() -> int:out_dir = (args.output_dir or input_mp4.parent).expanduser().resolve()out_dir.mkdir(parents=True, exist_ok=True)- lanczos = out_dir / f"{input_mp4.stem}_compare_lanczos_720p.mp4"- piper = out_dir / f"{input_mp4.stem}_compare_pipersr_720p.mp4"+ _, _, tag = target_for_mode(int(probe_video(input_mp4)["width"]), int(probe_video(input_mp4)["height"]), args.mode)+ lanczos = out_dir / f"{input_mp4.stem}_compare_lanczos_{tag}.mp4"+ piper = args.output.expanduser().resolve() if args.output else out_dir / f"{input_mp4.stem}_compare_pipersr_{tag}.mp4"sheet = out_dir / f"{input_mp4.stem}_compare_sheet.jpg"print("PiperSR attribution: Powered by PiperSR from ModelPiper — https://modelpiper.com", flush=True)- lanczos_sec = make_lanczos(input_mp4, lanczos, args.crf, args.pix_fmt, args.preset)- piper_sec = make_pipersr(input_mp4, piper, args.crf, args.pix_fmt, args.preset, args.keep_work)+ if args.pipersr_only:+ piper.parent.mkdir(parents=True, exist_ok=True)+ piper_sec = make_pipersr(input_mp4, piper, args.crf, args.pix_fmt, args.preset, args.keep_work, args.mode)+ print("\nDone:")+ print(f" Source: {input_mp4}")+ print(f" PiperSR: {piper} ({piper.stat().st_size / 1024 / 1024:.2f} MB, {piper_sec:.2f}s)")+ return 0++ lanczos_sec = make_lanczos(input_mp4, lanczos, args.crf, args.pix_fmt, args.preset, args.mode)+ piper_sec = make_pipersr(input_mp4, piper, args.crf, args.pix_fmt, args.preset, args.keep_work, args.mode)make_contact_sheet([input_mp4, lanczos, piper], sheet)print("\nDone:")diff --git a/update.js b/update.jsindex 62991e8..3e15b40 100644--- a/update.js+++ b/update.js@@ -84,7 +84,7 @@ module.exports = {{method: "shell.run",params: {- message: "./ltx-2-mlx/env/bin/pip install --upgrade 'hf_transfer>=0.1.6'"+ message: "./ltx-2-mlx/env/bin/pip install --upgrade 'hf_transfer>=0.1.6' 'pipersr==1.0.0'"}},// Re-apply patches. Codec patch is required; I2V OOM patch is a no-op