Skip to content

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

Y1.032 repoint Sharp export to PiperSR

mrbizarro85afc9ea55bd
diff --git a/README.md b/README.md
index d5a50ef..3ba79ce 100644
--- a/README.md
+++ b/README.md
@@ -113,24 +113,20 @@ Exported/upscaled files use the same **Output format** setting as native
renders. Standard stays compact (`yuv420p` / CRF 18); Video production stays
lossless (`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-stage
denoise/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 pipersr
ltx-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 this
possible
+- **[ModelPiper PiperSR](https://github.com/ModelPiper/PiperSR)** —
+ optional Sharp export upscaling on Apple Neural Engine
The 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/VERSION
index 69cdb22..361f8e4 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-Y1.031
+Y1.032
diff --git a/install.js b/install.js
index 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.py
index ba1d68c..2c88469 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -14,6 +14,7 @@ from __future__ import annotations
import atexit
import cgi
+import importlib.util
import json
import os
import 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, 576
upscale = 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_out
push(
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() {
// Speed
parts.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.py
index 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.js
index 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