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.022 fix Q8 download stalls: hf_transfer + retry loop + auth pass-through

mrbizarroa70223b048fc
diff --git a/download_q8.js b/download_q8.js
index cbb882f..7e4df43 100644
--- a/download_q8.js
+++ b/download_q8.js
@@ -13,6 +13,11 @@ module.exports = {
method: "shell.run",
params: {
venv: "ltx-2-mlx/env",
+ // Y1.022: HF_HUB_ENABLE_HF_TRANSFER=1 turns on the Rust downloader
+ // (~5-10× faster on the 25 GB Q8 bundle). hf_transfer is added by
+ // install.js / update.js. Falls back to plain Python downloader
+ // with a warning if the package isn't on disk for any reason.
+ env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },
message: [
"hf download dgrauet/ltx-2.3-mlx-q8 --local-dir mlx_models/ltx-2.3-mlx-q8"
]
diff --git a/download_upscaler.js b/download_upscaler.js
index 826bf17..9b996d1 100644
--- a/download_upscaler.js
+++ b/download_upscaler.js
@@ -14,6 +14,7 @@ module.exports = {
method: "shell.run",
params: {
venv: "ltx-2-mlx/env",
+ env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },
message: [
"hf download dgrauet/ltx-2.3-mlx-q8 spatial_upscaler_x2_v1_1.safetensors --local-dir mlx_models/ltx-2.3-mlx-q8"
]
diff --git a/install.js b/install.js
index 3c3db2b..1253021 100644
--- a/install.js
+++ b/install.js
@@ -146,7 +146,11 @@ module.exports = {
// resolve to the pinned version instead of pulling latest 0.31.x.
"uv pip install --python env/bin/python 'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1'",
"uv pip install --python env/bin/python ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx",
- "uv pip install --python env/bin/python pillow numpy 'huggingface-hub>=1.0'"
+ // hf_transfer is HuggingFace's Rust-based downloader — 5-10× faster
+ // 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'"
]
}
},
@@ -174,6 +178,10 @@ module.exports = {
params: {
venv: "env",
path: "ltx-2-mlx",
+ // Y1.022: HF_HUB_ENABLE_HF_TRANSFER=1 enables the Rust accelerator,
+ // ~5-10× faster on 25 GB. Falls back gracefully if hf_transfer
+ // isn't yet on disk (warning + plain Python downloader).
+ env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },
message: [
"hf download dgrauet/ltx-2.3-mlx-q4 --local-dir ../mlx_models/ltx-2.3-mlx-q4"
]
@@ -190,6 +198,7 @@ module.exports = {
params: {
venv: "env",
path: "ltx-2-mlx",
+ env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },
message: [
"hf download mlx-community/gemma-3-12b-it-4bit --local-dir ../mlx_models/gemma-3-12b-it-4bit"
]
@@ -207,6 +216,7 @@ module.exports = {
params: {
venv: "env",
path: "ltx-2-mlx",
+ env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },
message: [
"hf download dgrauet/ltx-2.3-mlx-q8 spatial_upscaler_x2_v1_1.safetensors --local-dir ../mlx_models/ltx-2.3-mlx-q8 || true"
]
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index 67b4670..1c6a398 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -1183,51 +1183,104 @@ def _download_thread(repo: dict) -> None:
stdout/stderr line-by-line into STATE['log']. Sets DOWNLOAD["active"]
back to False on exit (success or fail). Files land at repo['local_dir']
relative to ROOT, which is exactly where the completeness checks look —
- so the moment hf finishes, /status flips to complete + the UI updates."""
+ so the moment hf finishes, /status flips to complete + the UI updates.
+
+ Y1.022 — enables hf_transfer (Rust accelerator, ~5-10× faster on big
+ repos) via env var, threads the user's HF token through if set
+ (anonymous HF is throttled to ~50 KB/s and stalls Q8), and wraps the
+ download in a 3-attempt retry loop with exponential backoff. hf is
+ resumable, so retries pick up from where the previous attempt
+ stopped. User cancellations (DOWNLOAD["active"] flipping to False)
+ break the loop early."""
repo_id = repo["repo_id"]
target = ROOT / repo["local_dir"]
target.mkdir(parents=True, exist_ok=True)
cmd = [str(HF_BIN), "download", repo_id, "--local-dir", str(target)]
push(f"[hf] {repo_id} → {target} (~{repo.get('size_gb','?')} GB) — resumable")
+
+ # Build the env once. HF_HUB_ENABLE_HF_TRANSFER=1 turns on the Rust
+ # downloader; if hf_transfer isn't installed the hf CLI logs a warning
+ # and falls back to the Python downloader (slower but still works).
+ # HF_TOKEN unlocks faster throughput for users who configured a token
+ # in Settings — anonymous HF is throttled hard.
+ env = os.environ.copy()
+ env["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
+ hf_token = _active_hf_token()
+ if hf_token:
+ env["HF_TOKEN"] = hf_token
+ env["HUGGING_FACE_HUB_TOKEN"] = hf_token
+ push(f"[hf] using authenticated download (HF token configured) — ~10× faster than anonymous.")
+ else:
+ push(f"[hf] no HF token configured — downloads run on the throttled anonymous tier. Set one in Settings → Hugging Face token for ~10× faster downloads.")
+
+ max_attempts = 3
+ backoff_sec = 5
try:
- proc = subprocess.Popen(
- cmd,
- stdout=subprocess.PIPE,
- stderr=subprocess.STDOUT,
- text=True,
- bufsize=1,
- start_new_session=True,
- )
- with DOWNLOAD_LOCK:
- DOWNLOAD["proc"] = proc
+ for attempt in range(1, max_attempts + 1):
+ with DOWNLOAD_LOCK:
+ if not DOWNLOAD["active"]:
+ push(f"[hf] {repo_id} cancelled before attempt {attempt}.")
+ break
+ if attempt > 1:
+ push(f"[hf] {repo_id} attempt {attempt}/{max_attempts} — resuming from where the previous attempt stopped.")
try:
- DOWNLOAD["pgid"] = os.getpgid(proc.pid)
- except ProcessLookupError:
- DOWNLOAD["pgid"] = None
- # Stream every line. hf emits a tqdm progress bar with carriage
- # returns; we split on \r as well as \n so progress updates show
- # up live in the panel log instead of being buffered until done.
- buf = ""
- while True:
- ch = proc.stdout.read(1)
- if not ch:
+ proc = subprocess.Popen(
+ cmd,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT,
+ text=True,
+ bufsize=1,
+ env=env,
+ start_new_session=True,
+ )
+ except Exception as exc:
+ push(f"[hf] failed to spawn hf: {exc}")
+ break
+ with DOWNLOAD_LOCK:
+ DOWNLOAD["proc"] = proc
+ try:
+ DOWNLOAD["pgid"] = os.getpgid(proc.pid)
+ except ProcessLookupError:
+ DOWNLOAD["pgid"] = None
+ # Stream every line. hf emits a tqdm progress bar with carriage
+ # returns; we split on \r as well as \n so progress updates show
+ # up live in the panel log instead of being buffered until done.
+ buf = ""
+ while True:
+ ch = proc.stdout.read(1)
+ if not ch:
+ break
+ if ch in ("\n", "\r"):
+ line = buf.strip()
+ buf = ""
+ if line:
+ with DOWNLOAD_LOCK:
+ DOWNLOAD["last_line"] = line[:200]
+ push(f"[hf:{repo['key']}] {line[:300]}")
+ else:
+ buf += ch
+ if buf.strip():
+ push(f"[hf:{repo['key']}] {buf.strip()[:300]}")
+ rc = proc.wait()
+ if rc == 0:
+ push(f"[hf] {repo_id} downloaded successfully.")
break
- if ch in ("\n", "\r"):
- line = buf.strip()
- buf = ""
- if line:
+ with DOWNLOAD_LOCK:
+ still_active = DOWNLOAD["active"]
+ if not still_active:
+ push(f"[hf] {repo_id} cancelled (exit {rc}).")
+ break
+ if attempt < max_attempts:
+ push(f"[hf] {repo_id} attempt {attempt} failed (exit {rc}). Retrying in {backoff_sec}s — hf will resume from the last completed file.")
+ # Sleep in 1-second slices so a cancel during backoff is responsive.
+ for _ in range(backoff_sec):
+ time.sleep(1)
with DOWNLOAD_LOCK:
- DOWNLOAD["last_line"] = line[:200]
- push(f"[hf:{repo['key']}] {line[:300]}")
+ if not DOWNLOAD["active"]:
+ break
+ backoff_sec = min(backoff_sec * 2, 60) # 5 → 10 → 20s cap by attempt 3
else:
- buf += ch
- if buf.strip():
- push(f"[hf:{repo['key']}] {buf.strip()[:300]}")
- rc = proc.wait()
- if rc == 0:
- push(f"[hf] {repo_id} downloaded successfully.")
- else:
- push(f"[hf] {repo_id} FAILED — exit {rc}. Click Download again to retry/resume.")
+ push(f"[hf] {repo_id} FAILED after {max_attempts} attempts (last exit {rc}). Click Download again to keep retrying — hf will resume.")
except Exception as exc:
push(f"[hf] {repo_id} crashed: {exc}")
finally:
diff --git a/update.js b/update.js
index 5f1e57f..eadac73 100644
--- a/update.js
+++ b/update.js
@@ -74,6 +74,19 @@ module.exports = {
message: "./env/bin/pip install --force-reinstall --no-deps ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx"
}
},
+ // Y1.022: hf_transfer is HuggingFace's Rust accelerator — 5-10× faster
+ // downloads on big repos (notably the ~25 GB Q8 bundle). Existing
+ // installs that pre-date Y1.022 don't have it, so a Q8 download was
+ // bottlenecked at ~50 KB/s on throttled HF anonymous tier. Update
+ // installs it idempotently. The panel sets HF_HUB_ENABLE_HF_TRANSFER=1
+ // when invoking hf download; if the package is missing for any reason
+ // the hf CLI just emits a warning and falls back to plain Python.
+ {
+ method: "shell.run",
+ params: {
+ message: "./ltx-2-mlx/env/bin/pip install --upgrade 'hf_transfer>=0.1.6'"
+ }
+ },
// Re-apply patches. Codec patch is required; I2V OOM patch is a no-op
// on dcd639e (older I2V structure) and reports drift gracefully now.
// Pin to the venv's python3.11 to match install.js — `python3` on