Thread HF_TOKEN through gated Lightricks loads; local GGUF first; fail-fast fingerprint

app.py

@@ -20,9 +20,11 @@ is a hard no-op here so no rewrite happens.
 
 from __future__ import annotations
 
+import glob
 import os
 import subprocess
 import threading
+from pathlib import Path
 
 # ZeroGPU rule #1: `import spaces` must precede any CUDA-touching import
 # (torch etc.) — it monkey-patches torch.cuda at import time.
@@ -31,15 +33,22 @@ import spaces  # noqa: E402
 import numpy as np
 import torch
 
-HF_TOKEN = os.environ.get("HF_TOKEN", "")
+# Requires the Space secret HF_TOKEN after accepting the LTX-2.x Community
+# License (free for entities under $10M annual revenue). Needed for every file
+# served from the gated Lightricks/LTX-2.5-Diffusers repo (config, Gemma-4-12B
+# text encoder, VAEs, connectors, audio_vae + vocoder).
+HF_TOKEN = os.environ.get("HF_TOKEN", "").strip()
 
 # Direct download URL of the distilled GGUF transformer (~15GB). The backend
-# only needs LTX_SPACE_URL; this key is configured in the Space.
+# only needs LTX_SPACE_URL; this key is configured in the Space. A GGUF the
+# user uploads into the repo `model/` folder is preferred over this URL.
 LTX_MODEL_URL = os.environ.get(
     "LTX_MODEL_URL",
     "https://huggingface.co/realrebelai/LTX-2.5_GGUFs/resolve/main/LTX-2.5-Distilled-Q4_K_M.gguf",
 )
 PIPELINE_ID = "Lightricks/LTX-2.5-Diffusers"
+# Overridable repo id (e.g. a locally mirrored copy: LTX_PIPELINE_ID=/app/ltx25).
+LTX_PIPELINE_ID = os.environ.get("LTX_PIPELINE_ID", PIPELINE_ID)
 SEED = int(os.environ.get("LTX_SEED", "0"))
 FPS = int(os.environ.get("LTX_FPS", "24"))
 
@@ -60,6 +69,49 @@ _model = None
 # ----------------------------------------------------------------- model load
 
 
+def _find_local_gguf() -> str | None:
+    """Pick a GGUF the user uploaded into the repo (web UI ``model/`` folder)."""
+    for folder in ("model", "models", "weights"):
+        hits = [p for p in glob.glob(os.path.join(folder, "**", "*.gguf"), recursive=True) if os.path.isfile(p)]
+        if hits:
+            return sorted(hits)[0]
+    return None
+
+
+def _gguf_fingerprint(path: str) -> None:
+    """Fail fast if the GGUF is not an LTX-2 video transformer.
+
+    diffusers 0.40 converts GGUFs that keep the ComfyUI/native
+    ``model.diffusion_model.*`` tensor names (llama.cpp-style ``blk.*`` renames
+    are not supported by the LTX-2 GGUF converter).
+    """
+    from gguf import GGUFReader
+
+    reader = GGUFReader(path)
+    names = [tensor.name for tensor in reader.tensors]
+    print(f"[ltx] gguf tensors={len(names)}")
+
+    def count(marker: str) -> int:
+        return sum(1 for name in names if marker in name)
+
+    blocks = count("transformer_blocks.")
+    ltx2_av_gate = count("model.diffusion_model.av_ca_a2v_gate_adaln_single")
+    llama_blk = count("blk.") + count(".attn_qkv.")
+    print(
+        f"[ltx] gguf fingerprint blocks={blocks} ltx2_av_gate={ltx2_av_gate} llama_blk={llama_blk}"
+    )
+    if blocks == 0 and llama_blk == 0:
+        raise RuntimeError(
+            "GGUF does not look like an LTX-2 video transformer (no transformer_blocks found)"
+        )
+    if blocks == 0 and llama_blk > 0:
+        raise RuntimeError(
+            "GGUF uses llama.cpp-renamed tensors (blk.*); diffusers 0.40's LTX-2 GGUF "
+            "converter expects the native model.diffusion_model.* names. Use a GGUF "
+            "converted from the ComfyUI/native checkpoint instead."
+        )
+
+
 def _download_gguf(dest: str) -> str:
     import httpx
 
@@ -76,7 +128,17 @@ def _download_gguf(dest: str) -> str:
 
     # Support "repo_id:filename" shorthand.
     repo, _, filename = LTX_MODEL_URL.partition(":")
-    return hf_hub_download(repo, filename or "LTX-2.5-Distilled-Q4_K_M.gguf", token=HF_TOKEN)
+    return hf_hub_download(repo, filename or "LTX-2.5-Distilled-Q4_K_M.gguf", token=HF_TOKEN or None)
+
+
+def _ensure_gguf() -> str:
+    """Local vendored GGUF first, then network download."""
+    local = _find_local_gguf()
+    if local is not None:
+        print(f"[ltx] using vendored GGUF: {local}")
+        return local
+    print("[ltx] no local GGUF found; downloading…")
+    return _download_gguf(os.environ.get("LTX_GGUF_CACHE", "/tmp/ltx-model.gguf"))
 
 
 def _build_transformer(gguf_path: str):
@@ -97,11 +159,14 @@ def _build_transformer(gguf_path: str):
         quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
         dtype=torch.bfloat16,
     )
+    _gguf_fingerprint(gguf_path)
+    token = HF_TOKEN or None
     try:
-        return TransformerCls.from_single_file(gguf_path, config=PIPELINE_ID, **kwargs)
+        # `config=` pulls transformer/config.json from the gated repo (token).
+        return TransformerCls.from_single_file(gguf_path, config=LTX_PIPELINE_ID, token=token, **kwargs)
     except Exception as exc:  # config may live elsewhere; trust the GGUF KV metadata
         print(f"[ltx] from_single_file with config failed ({exc}), retrying without")
-        return TransformerCls.from_single_file(gguf_path, **kwargs)
+        return TransformerCls.from_single_file(gguf_path, token=token, **kwargs)
 
 
 def _load_model() -> dict:
@@ -113,9 +178,16 @@ def _load_model() -> dict:
         if _model is not None:
             return _model
 
+        if not HF_TOKEN and not os.path.isdir(LTX_PIPELINE_ID):
+            raise RuntimeError(
+                "HF_TOKEN secret is not set. Open the Space → Settings → Variables and "
+                "secrets and create a secret named HF_TOKEN: a fine-grained token with "
+                "read access to Lightricks/LTX-2.5-Diffusers (after accepting its "
+                "LTX-2.x Community License on that repo)."
+            )
+
         print("[ltx] downloading GGUF transformer…")
-        gguf_path = os.environ.get("LTX_GGUF_CACHE", "/tmp/ltx-model.gguf")
-        gguf_path = _download_gguf(gguf_path)
+        gguf_path = _ensure_gguf()
 
         print("[ltx] building quantized transformer…")
         transformer = _build_transformer(gguf_path)
@@ -125,17 +197,22 @@ def _load_model() -> dict:
         built = {
             "transformer": transformer,
         }
+        token = HF_TOKEN or None
         try:
             built["t2v"] = LTX2Pipeline.from_pretrained(
-                PIPELINE_ID, transformer=transformer, torch_dtype=torch.bfloat16
+                LTX_PIPELINE_ID, transformer=transformer, torch_dtype=torch.bfloat16, token=token
             )
             built["i2v"] = LTX2ImageToVideoPipeline.from_pretrained(
-                PIPELINE_ID, transformer=transformer, torch_dtype=torch.bfloat16
+                LTX_PIPELINE_ID, transformer=transformer, torch_dtype=torch.bfloat16, token=token
             )
         except Exception as exc:  # pragma: no cover - component layout differences
+            msg = str(exc)
+            hint = ""
+            if "401" in msg or "is not a valid model identifier" in msg or "gated" in msg.lower():
+                hint = " (hint: accept the LTX-2.x Community License on the repo + set the HF_TOKEN secret)"
             raise RuntimeError(
-                "[ltx] pipeline build failed - check Lightricks/LTX-2.5-Diffusers "
-                f"component layout. {exc}"
+                f"[ltx] pipeline build failed - check Lightricks/LTX-2.5-Diffusers "
+                f"component layout. {msg}{hint}"
             ) from exc
 
         for pipe in (built["t2v"], built["i2v"]):
@@ -182,11 +259,11 @@ def _extract_audio(output):
     if torch.is_tensor(arr):
         arr = arr.detach().float().cpu().numpy()
     arr = np.asarray(arr)
-    if arr.ndim == 3:  # (batch, samples, channels)
+    if arr.ndim == 3:  # (batch, channels, samples)
         arr = arr[0]
-    if arr.ndim == 2:  # downmix to mono for a clean narration bed
-        arr = arr.mean(axis=1)
-    return arr.astype(np.float32), int(sr)
+    if arr.ndim == 2:  # collapse to mono; channel axis is the smaller dimension
+        arr = arr.mean(axis=int(arr.shape[0] < arr.shape[1]))
+    return np.ascontiguousarray(arr.astype(np.float32)), int(sr)
 
 
 def _mux_audio(video_path, frames, fps, audio) -> str:
@@ -200,10 +277,11 @@ def _mux_audio(video_path, frames, fps, audio) -> str:
     from scipy.io import wavfile
 
     arr, sr = audio
-    wav_path = video_path.with_suffix(".wav")
+    vp = Path(video_path)
+    wav_path = vp.with_suffix(".wav")
     wavfile.write(str(wav_path), sr, arr)
     ffmpeg = imageio_ffmpeg.get_ffmpeg_exe()
-    muxed = str(video_path.with_suffix("_mux.mp4"))
+    muxed = str(vp.with_name(vp.stem + "_mux.mp4"))
     subprocess.run(
         [
             ffmpeg, "-y",