inline-core 1.2.63__tar.gz → 1.2.64__tar.gz

{inline_core-1.2.63 → inline_core-1.2.64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: inline-core
-Version: 1.2.63
+Version: 1.2.64
 Summary: The generation engine behind Inline Studio.
 License-Expression: GPL-3.0-or-later
 Requires-Python: >=3.11
@@ -8,6 +8,7 @@ Requires-Dist: numpy>=1.26
 Requires-Dist: psutil>=5.9
 Provides-Extra: all
 Requires-Dist: accelerate>=0.30; extra == 'all'
+Requires-Dist: av>=12; extra == 'all'
 Requires-Dist: bitsandbytes>=0.43; (platform_system != 'Darwin') and extra == 'all'
 Requires-Dist: controlnet-aux>=0.0.7; extra == 'all'
 Requires-Dist: diffusers==0.39.0; extra == 'all'

{inline_core-1.2.63 → inline_core-1.2.64}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 # PyPI name; the import package is `inline_core` (src/inline_core).
 name = "inline-core"
-version = "1.2.63"
+version = "1.2.64"
 description = "The generation engine behind Inline Studio."
 readme = "README.md"
 license = "GPL-3.0-or-later"
@@ -82,6 +82,8 @@ all = [
   "accelerate>=0.30",
   "safetensors>=0.4",
   "torchao>=0.14",
+  # Clip decode for MiniMax H3 LoRA training, and H3's reference node.
+  "av>=12",
   "scipy>=1.11",
   "huggingface_hub>=0.23",
   "controlnet-aux>=0.0.7",
@@ -101,13 +103,18 @@ all = [
 ]
 
 # PyPI ships CPU-only torch on Windows; pin the CUDA index there (pip: see requirements.txt).
+# cu126 rather than a newer index because it is the last one still built for sm_50..sm_70 (Maxwell
+# through Volta), so it is the safe default for a card we know nothing about. Blackwell (sm_120) has
+# no wheel here at all - webui.sh/.bat detect the compute capability and pass the matching index.
 [[tool.uv.index]]
-name = "pytorch-cu124"
-url = "https://download.pytorch.org/whl/cu124"
+name = "pytorch-cu126"
+url = "https://download.pytorch.org/whl/cu126"
 explicit = true
 
+# Launcher installs pass `--no-sources-package torch` so their detected index wins over this pin;
+# anything else added to this table would still apply to them.
 [tool.uv.sources]
-torch = [{ index = "pytorch-cu124", marker = "sys_platform == 'win32'" }]
+torch = [{ index = "pytorch-cu126", marker = "sys_platform == 'win32'" }]
 
 [project.scripts]
 inline-studio = "inline_core.server.__main__:main"

{inline_core-1.2.63 → inline_core-1.2.64}/src/inline_core/device/detect.py

@@ -76,10 +76,58 @@ def cpu_only_torch_warning() -> str | None:
         "This install has a CPU-ONLY build of PyTorch, but an NVIDIA GPU was detected. "
         "Generation will run on the CPU and be roughly 100x slower. Reinstall torch from the CUDA "
         "index, e.g. `pip install --force-reinstall --extra-index-url "
-        "https://download.pytorch.org/whl/cu124 torch` (or re-run `webui.sh --install`)."
+        "https://download.pytorch.org/whl/cu126 torch` (or re-run `webui.sh --install`)."
     )
 
 
+def unsupported_arch_warning() -> str | None:
+    """A warning when the installed torch has no kernels for the GPU it is about to run on.
+
+    An RTX 50-series card (sm_120) under a wheel built for sm_50..sm_90 is the sharpest case: torch
+    reports a CUDA build and a visible device, so every check in ``cpu_only_torch_warning`` passes,
+    and the only clue the user gets is PyTorch's own late UserWarning followed by kernels that
+    cannot launch. Returns None on any uncertainty, same as the rest of this module.
+    """
+    try:
+        import torch
+
+        if getattr(torch.version, "hip", None):
+            return None  # the sm_ vocabulary is NVIDIA's; HIP reports gfx arches through it
+        get_arch_list = getattr(torch.cuda, "get_arch_list", None)
+        get_capability = getattr(torch.cuda, "get_device_capability", None)
+        device_count = getattr(torch.cuda, "device_count", None)
+        if get_arch_list is None or get_capability is None or device_count is None:
+            return None
+        if device_count() < 1:
+            return None
+        arches = [str(arch) for arch in get_arch_list() if str(arch).startswith("sm_")]
+        if not arches:
+            return None  # a CPU-only build; cpu_only_torch_warning owns that case
+        major, minor = get_capability(0)
+        target = f"sm_{major}{minor}"
+        # startswith, because a wheel lists tuned variants like sm_90a for the same architecture.
+        if any(arch.startswith(target) for arch in arches):
+            return None
+        name = _device_name(torch) or "The detected NVIDIA GPU"
+        return (
+            f"{name} is compute capability {target}, but this install's PyTorch only has kernels "
+            f"for {' '.join(arches)}. Generation will fail or fall back to the CPU. Re-run "
+            "`webui.sh --install` (Windows: `.\\webui.bat --install`) to pick the wheel index that "
+            "matches the card, or force one with `--torch-index cu130` - `cu128` if the driver "
+            "predates CUDA 13."
+        )
+    except Exception:  # noqa: BLE001 - a diagnostic must never break startup
+        return None
+
+
+def _device_name(torch: object) -> str | None:
+    try:
+        get_name = getattr(getattr(torch, "cuda", None), "get_device_name", None)
+        return str(get_name(0)) if get_name is not None else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
 def _nvidia_gpu_present() -> bool:
     """Best-effort check for NVIDIA hardware that does NOT rely on torch's CUDA support - that is
     the whole point, since we are called precisely when torch cannot see the GPU.

{inline_core-1.2.63 → inline_core-1.2.64}/src/inline_core/server/__main__.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging as _logging
 import os as _os
 
 # Default PyTorch to expandable CUDA segments before torch initializes its allocator (it reads this
@@ -19,7 +20,7 @@ _os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
 import uvicorn
 
 from ..config import data_dir, server_host, server_port
-from ..device.detect import cpu_only_torch_warning
+from ..device.detect import cpu_only_torch_warning, unsupported_arch_warning
 from ..device.memory import MemoryPolicy
 from ..extensions.loader import LoadedExtension
 from ..graph.cache import InMemoryCache
@@ -35,7 +36,20 @@ from .rpc import EventBroadcaster, RpcRouter
 from .run_store import SqliteRunStore
 
 
+def _quiet_dependency_noise() -> None:
+    """Two third-party import-time warnings that are noise here, not signal.
+
+    diffusers cannot build its torchao ``torch.load`` allowlist because torchao dropped
+    ``uint4_layout``; we never load torchao-serialized checkpoints, and quantization itself is
+    unaffected. torch's pytree then warns about torchao registering Enum subclasses - torchao's to
+    fix, not ours. Both loggers have exactly one warning site, so this hides nothing else.
+    """
+    for name in ("diffusers.quantizers.torchao.torchao_quantizer", "torch.utils._pytree"):
+        _logging.getLogger(name).setLevel(_logging.ERROR)
+
+
 def main() -> None:
+    _quiet_dependency_noise()  # before register_models, which is what pulls diffusers/torchao in
     policy = MemoryPolicy()
     registry = build_default_registry()
     data = data_dir()
@@ -47,20 +61,17 @@ def main() -> None:
     rpc = RpcRouter()
     events = EventBroadcaster()
     requirements = RequirementsRegistry()
-    registered, extensions = register_models(
+    _, extensions = register_models(
         registry, take_store, policy, requirements=requirements, rpc=rpc, events=events
     )
-    print(f"Registered models: {registered or 'none (source nodes only)'}")
     if extensions:
         print(f"Extensions: {_extension_summary(extensions)}")
     # A CPU-only torch wheel on a CUDA machine is a silent ~100x slowdown, so say it loudly here
     # rather than letting the user conclude the engine is just slow.
-    torch_warning = cpu_only_torch_warning()
+    torch_warning = cpu_only_torch_warning() or unsupported_arch_warning()
     if torch_warning:
         print(f"WARNING: {torch_warning}")
     frontend_root = resolve_frontend_root()
-    fe = frontend_root or "none (API only); use --front-end-root or install the frontend package"
-    print(f"Frontend: {fe}")
     # The Studio app-backend: Core is the sole native backend (projects, frames, moodboard, assets,
     # generation, fal, timeline). Every InlineStudioApi channel is handled here.
     store = StudioStore(
@@ -68,7 +79,9 @@ def main() -> None:
         studio_config.workspace_dir(),
         default_core_url=studio_config.DEFAULT_CORE_URL,
     )
-    print(f"Studio data: {studio_config.data_dir()}  |  workspace: {studio_config.workspace_dir()}")
+    # Reopen whatever was open before the restart, so a browser tab left open across it keeps
+    # working instead of failing every call with "No project is open."
+    store.restore_last_project()
     app = create_app(
         registry=registry,
         cache=InMemoryCache(),

{inline_core-1.2.63 → inline_core-1.2.64}/src/inline_core/studio/handlers.py

@@ -88,6 +88,7 @@ def register_studio_handlers(
     reg("project:openZip", lambda: None)
     reg("project:listRecent", store.list_recent)
     reg("project:current", store.current_project)
+    reg("project:close", store.close_project)
     reg("project:mediaDirs", store.media_dirs)
     reg("project:export", lambda _path: None)  # zip export: pending (see plan)
     reg("dialog:pickDirectory", lambda *_: str(cfg.workspace_dir()))
@@ -264,6 +265,7 @@ def register_studio_handlers(
         reg("training:createDataset", lambda inp: training.create_dataset(inp))
         reg("training:listItems", lambda did: training.list_items(did))
         reg("training:addItems", lambda did, aids: training.add_items(did, aids))
+        reg("training:addFromPath", lambda did, path: training.add_from_path(did, path))
         reg("training:removeItem", lambda iid: training.remove_item(iid))
         reg("training:setCaption", lambda iid, cap: training.set_caption(iid, cap))
         reg("training:autoCaption",

{inline_core-1.2.63 → inline_core-1.2.64}/src/inline_core/studio/store.py

@@ -131,6 +131,7 @@ class StudioStore:
         project = {"id": pid, "name": name, "path": str(folder), "createdAt": now, "updatedAt": now}
         self._current = project
         self.record_recent(name, str(folder))
+        self._remember_last_project(str(folder))
         return project
 
     def open_project(self, selected: str) -> dict[str, Any]:
@@ -143,6 +144,7 @@ class StudioStore:
         project = self._load_project_row(folder)
         self._current = project
         self.record_recent(project["name"], str(folder))
+        self._remember_last_project(str(folder))
         return project
 
     def _load_project_row(self, folder: Path) -> dict[str, Any]:
@@ -160,7 +162,44 @@ class StudioStore:
         }
 
     def current_project(self) -> dict[str, Any] | None:
-        return self._current
+        return self._current or self.restore_last_project()
+
+    def close_project(self) -> None:
+        self.close()
+        self._current = None
+        self._remember_last_project(None)
+
+    # --- last opened project ----------------------------------------------------------------------
+    # The open project is otherwise only in memory, so restarting Core left a still-open browser tab
+    # failing every call with "No project is open." Kept in its own file rather than settings.json,
+    # because _save_settings rewrites that from get_settings() and would drop any key it omits.
+
+    def _last_project_file(self) -> Path:
+        return self._app_data / "last_project"
+
+    def _remember_last_project(self, path: str | None) -> None:
+        file = self._last_project_file()
+        try:
+            if path:
+                file.write_text(path, encoding="utf-8")
+            elif file.exists():
+                file.unlink()
+        except OSError:
+            pass  # never fail an open just because the marker could not be written
+
+    def restore_last_project(self) -> dict[str, Any] | None:
+        """Reopen the project left open at shutdown. Best-effort: a moved or deleted one is
+        forgotten and the launcher shows instead."""
+        if self._conn is not None:
+            return self._current
+        file = self._last_project_file()
+        if not file.exists():
+            return None
+        try:
+            return self.open_project(file.read_text(encoding="utf-8").strip())
+        except (OSError, ValueError, sqlite3.Error):
+            self._remember_last_project(None)
+            return None
 
     def media_dirs(self) -> dict[str, str]:
         if self._folder is None:

{inline_core-1.2.63 → inline_core-1.2.64}/src/inline_core/studio/training.py

@@ -71,6 +71,42 @@ class Training:
     def add_items(self, dataset_id: str, asset_ids: list[str]) -> list[dict[str, Any]]:
         return ts.add_items(self._conn(), dataset_id, asset_ids)
 
+    def add_from_path(self, dataset_id: str, path: str) -> list[dict[str, Any]]:
+        """Import a folder of images and clips into the dataset, captions included.
+
+        The browser cannot hand over a folder, and uploading a clip dataset through it means
+        pushing gigabytes over HTTP to a server that can already see the disk. Paths come from the
+        client here the same way ``assets:importPaths`` already accepts them.
+        """
+        from . import assets as ax
+
+        folder = Path(path).expanduser()
+        if not folder.is_dir():
+            raise ValueError(f"Not a folder: {path}")
+        conn, project = self._conn(), self._store.folder()
+        media = [
+            p
+            for p in sorted(folder.iterdir())
+            if p.is_file() and ax.kind_for_file(str(p)) in ("image", "video")
+        ]
+        if not media:
+            raise ValueError(f"No images or clips in {path}")
+
+        imported = [(p, ax.import_file(conn, project, str(p), None)) for p in media]
+        added = ts.add_items(conn, dataset_id, [a["id"] for _p, a in imported if a])
+
+        # `NNNN.txt` beside `NNNN.png` is the caption, the convention the drag-drop path already
+        # follows. Only newly added items are touched, so re-importing cannot clobber an edit.
+        by_asset = {item["assetId"]: item for item in added}
+        for source, asset in imported:
+            item = by_asset.get(asset["id"]) if asset else None
+            sidecar = source.with_suffix(".txt")
+            if item and sidecar.is_file():
+                caption = sidecar.read_text(encoding="utf-8").strip()
+                if caption:
+                    ts.set_caption(conn, item["id"], caption)
+        return ts.list_items(conn, dataset_id)
+
     def remove_item(self, item_id: str) -> None:
         ts.remove_item(self._conn(), item_id)
 

{inline_core-1.2.63 → inline_core-1.2.64}/src/inline_core/training/arch.py

@@ -333,6 +333,22 @@ ARCHS: dict[str, TrainingArch] = {
 }
 
 
+def clip_frames(arch: TrainingArch, seconds: Any) -> int:
+    """How many frames of a clip to train on, snapped to the arch's frame grid.
+
+    1 for an arch with no clip support, which is what a still costs. For H3 the floor is a whole
+    17-frame chunk plus the 5-frame head, so a shorter request rounds up to 0.92s rather than being
+    refused; the VAE has no way to encode less.
+    """
+    if arch.key != MINIMAX_H3:
+        return 1
+    from ..models.minimaxh3.vendor.packing import MINIMAX_H3_FPS
+    from ..models.minimaxh3.vendor.packing_ref2va import trim_reference_num_frames
+
+    wanted = round(float(seconds) * MINIMAX_H3_FPS) if seconds else 1
+    return trim_reference_num_frames(max(1, wanted))
+
+
 def get(key: str | None) -> TrainingArch:
     """The arch to train. Defaults to Z-Image so a run predating Krea 2 still resumes."""
     arch = ARCHS.get(key or Z_IMAGE)

{inline_core-1.2.63 → inline_core-1.2.64}/src/inline_core/training/cache.py

@@ -7,6 +7,7 @@ them (see ``h3.py``). Either way the transformer loads into a card with nothing
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from typing import Any
 
 from . import arch as archs
@@ -28,13 +29,21 @@ def build(
     *,
     flip: bool = False,
     dropout: float = 0.0,
+    clip_frames: int = 1,
+    on_status: Callable[[str], None] | None = None,
 ) -> tuple[list[dict[str, Any]], dict[str, Any] | None, float]:
-    """Return ``(items, unconditional, shift)``, all as CPU tensors, with the encoders freed."""
+    """Return ``(items, unconditional, shift)``, all as CPU tensors, with the encoders freed.
+
+    ``on_status`` reports phase progress to the caller, which forwards it over the JSON protocol.
+    Precaching a large dataset takes minutes, and a logger call would be dropped here: the trainer
+    subprocess configures no logging handler, so anything below WARNING goes nowhere.
+    """
     if arch == archs.MINIMAX_H3:
         from . import h3
 
         items, unconditional = h3.precache(
-            dataset_dir, models_dir, device, dtype, resolution, flip, dropout > 0
+            dataset_dir, models_dir, device, dtype, resolution, flip, dropout > 0, clip_frames,
+            on_status=on_status,
         )
         return items, unconditional, _H3_SHIFT
 

{inline_core-1.2.63 → inline_core-1.2.64}/src/inline_core/training/caption.py

@@ -105,13 +105,30 @@ def _load_with_fallback(model_id: str) -> tuple[Any, Any, Any]:
             raise first from None
 
 
+def _open(path: str) -> Any:
+    """The frame to caption. A clip is captioned from its middle frame, which is more
+    representative than the first and stops PIL raising on a container it cannot read."""
+    from pathlib import Path
+
+    from PIL import Image
+
+    from . import dataset as ds
+
+    if not ds.is_video(Path(path)):
+        return Image.open(path).convert("RGB")
+
+    from ..models.minimaxh3.vendor.packing_ref2va import decode_reference_video
+
+    frames, _fps, _audio = decode_reference_video(path)
+    return Image.fromarray(frames[len(frames) // 2]).convert("RGB")
+
+
 def _caption_one(model: Any, processor: Any, device: str, path: str) -> str:
     """One caption. Handles both shapes: task-token models (Florence-2, which post-processes a
     tagged string) and plain image-captioning models (BLIP), which just decode the output."""
     import torch
-    from PIL import Image
 
-    image = Image.open(path).convert("RGB")
+    image = _open(path)
     task_style = hasattr(processor, "post_process_generation")
     inputs = (
         processor(text=_TASK, images=image, return_tensors="pt")

{inline_core-1.2.63 → inline_core-1.2.64}/src/inline_core/training/dataset.py

@@ -17,15 +17,25 @@ from . import arch as archs
 
 _IMAGE_SUFFIXES = (".png", ".jpg", ".jpeg", ".webp", ".bmp")
 
+#: Only the video archs pass these to ``_pairs``. An image arch handed a clip would reach PIL and
+#: raise, so the default stays images and each caller opts in.
+_VIDEO_SUFFIXES = (".mp4", ".mov", ".webm", ".mkv", ".avi")
 
-def _pairs(dataset_dir: Path) -> list[tuple[Path, str]]:
+
+def is_video(path: Path) -> bool:
+    return path.suffix.lower() in _VIDEO_SUFFIXES
+
+
+def _pairs(
+    dataset_dir: Path, suffixes: tuple[str, ...] = _IMAGE_SUFFIXES
+) -> list[tuple[Path, str]]:
     out: list[tuple[Path, str]] = []
-    for img in sorted(dataset_dir.iterdir()):
-        if img.suffix.lower() not in _IMAGE_SUFFIXES:
+    for media in sorted(dataset_dir.iterdir()):
+        if media.suffix.lower() not in suffixes:
             continue
-        caption_file = img.with_suffix(".txt")
+        caption_file = media.with_suffix(".txt")
         caption = caption_file.read_text(encoding="utf-8").strip() if caption_file.exists() else ""
-        out.append((img, caption))
+        out.append((media, caption))
     return out
 
 

{inline_core-1.2.63 → inline_core-1.2.64}/src/inline_core/training/h3.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 
 import gc
 import logging
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
@@ -29,6 +30,10 @@ AUDIO_LATENT_CHANNELS = 32
 #: caption dropout and an image whose ``.txt`` is missing.
 _EMPTY_CAPTION = " "
 
+#: H3's fixed frame rate, and the shortest clip its video VAE encodes (the first ``17n + 5``).
+_H3_FPS = 24
+_MIN_CLIP_FRAMES = 22
+
 
 def precache(
     dataset_dir: str,
@@ -38,38 +43,55 @@ def precache(
     resolution: int,
     flip: bool,
     want_unconditional: bool,
+    clip_frames: int = 1,
+    on_status: Callable[[str], None] | None = None,
 ) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
     """Every image as a latent and every caption as conditioning, as CPU tensors."""
     from . import dataset as ds
 
-    pairs = ds._pairs(Path(dataset_dir))
+    say = on_status or (lambda _text: None)
+    pairs = ds._pairs(Path(dataset_dir), ds._IMAGE_SUFFIXES + ds._VIDEO_SUFFIXES)
     if not pairs:
         raise RuntimeError("The exported dataset is empty.")
 
     root = Path(models_dir)
-    latents = _encode_pixels(root, pairs, device, resolution, flip)
-    captions = [caption for _img, caption in pairs for _ in ((False, True) if flip else (False,))]
+    # Only the clips that survived encoding carry captions, or every caption after the first skip
+    # would be paired with the wrong latent.
+    latents, kept = _encode_pixels(root, pairs, device, resolution, flip, clip_frames, say)
+    if not kept:
+        raise RuntimeError(
+            f"None of the {len(pairs)} dataset items could be encoded. For clips, each must be at "
+            f"least {_MIN_CLIP_FRAMES} frames at {_H3_FPS}fps "
+            f"({_MIN_CLIP_FRAMES / _H3_FPS:.2f}s)."
+        )
+    captions = [caption for _img, caption in kept for _ in ((False, True) if flip else (False,))]
     if want_unconditional:
         captions.append("")
-    embeds = _encode_captions(root, captions, device, dtype)
+    embeds = _encode_captions(root, captions, device, dtype, say)
+    say(f"cached {len(latents)} latents and {len(embeds)} captions")
 
     items = [
         {"latent": latent, **_conditioning(embed, tags, latent)}
         for latent, (embed, tags) in zip(latents, embeds, strict=False)
     ]
-    unconditional = None
     if want_unconditional:
+        # Dropout swaps a different text length in, which moves every row after it, so the whole
+        # layout travels with the embedding. It also depends on the latent grid, and a dataset
+        # mixing stills with clips has more than one, so each item carries its own rather than
+        # sharing the first item's and mis-sizing every clip.
         embed, tags = embeds[-1]
-        # Caption dropout swaps in a different text length, which moves every row after it, so the
-        # whole layout travels with the embedding rather than just the embedding.
-        unconditional = _conditioning(embed, tags, latents[0])
-    return items, unconditional
+        for item in items:
+            item["uncond"] = _conditioning(embed, tags, item["latent"])
+    # The per-item copies are what dropout uses; the loop keeps the global slot for the image archs.
+    return items, None
 
 
 def _encode_pixels(
-    root: Path, pairs: list[tuple[Path, str]], device: str, resolution: int, flip: bool
-) -> list[Any]:
-    """Pass one: the video VAE, then dropped."""
+    root: Path, pairs: list[tuple[Path, str]], device: str, resolution: int, flip: bool,
+    clip_frames: int = 1, say: Callable[[str], None] = lambda _text: None,
+) -> tuple[list[Any], list[tuple[Path, str]]]:
+    """Pass one: the video VAE, then dropped. Returns the latents and the pairs they came from."""
+    import numpy
     import torch
     from PIL import Image
 
@@ -84,45 +106,98 @@ def _encode_pixels(
     from . import dataset as ds
 
     out: list[Any] = []
+    kept: list[tuple[Path, str]] = []
+    skipped: list[str] = []
+    total = len(pairs)
+    say(f"encoding {total} items at {resolution}px through the video VAE")
     try:
-        for img_path, _caption in pairs:
+        for index, (path, _caption) in enumerate(pairs, start=1):
+            clip = ds.is_video(path)
+            try:
+                frames = _clip_frames(path, clip_frames) if clip else [Image.open(path)]
+            except ShortClipError as exc:
+                skipped.append(path.name)
+                say(f"skipped {exc}")
+                continue
+            # A long precache is otherwise silent for many minutes, so report often enough that it
+            # reads as progress rather than a hang.
+            if index == 1 or index % 5 == 0 or index == total:
+                say(f"caching latents {index}/{total}")
             for mirrored in (False, True) if flip else (False,):
-                square = ds._square(Image.open(img_path), resolution, mirrored)
-                # H3 normalises with ImageNet statistics, not to [-1, 1] like the image archs, and
-                # a still is one frame: (1, 3, 1, H, W).
-                raw = torch.from_numpy(_as_array(square)).to(device)
-                pixels = raw.permute(2, 0, 1)[None, :, None]
+                stack = [_as_array(ds._square(f, resolution, mirrored)) for f in frames]
+                # ImageNet statistics, not the [-1, 1] the image archs use, and always 5D:
+                # (1, 3, F, H, W).
+                raw = torch.from_numpy(numpy.stack(stack)).to(device)
+                pixels = raw.permute(3, 0, 1, 2)[None]
                 pixels = (pixels.to(torch.float32).div(255.0) - pixel_mean) / pixel_std
                 with torch.no_grad():
-                    # The spatial encoder alone, the path inference uses for a single frame; the
-                    # temporal chunking is for 17n+5 clips.
-                    latent = _sample(vae._encode_clip(pixels))
+                    # A single frame takes the spatial encoder; a 17n+5 clip takes the temporal
+                    # chunking. Mirrors the split the vendored reference encoder makes.
+                    moments = vae._encode(pixels) if clip else vae._encode_clip(pixels)
+                    latent = _sample(moments)
                 out.append(((latent.cpu() - mean) / std)[0])
+            kept.append((path, _caption))
     finally:
         del vae
         _reclaim()
-    logger.info("MiniMax H3: cached %d latents, video VAE released", len(out))
-    return out
+    if skipped:
+        say(f"skipped {len(skipped)} of {total} items as too short: {', '.join(skipped)}")
+    say(f"cached {len(out)} latents from {len(kept)} items, video VAE released")
+    return out, kept
+
+
+class ShortClipError(RuntimeError):
+    """A clip below H3's frame floor. Skipped, never fatal: one bad file in a large dataset must
+    not throw away a precache that takes many minutes."""
+
+
+def _clip_frames(path: Path, clip_frames: int) -> list[Any]:
+    """A clip as PIL frames on H3's 24fps, 17n+5 grid, taken from the start.
+
+    Trimmed rather than sampled: a fixed window keeps the precache to one encode per clip, and
+    re-encoding a different window every step would defeat caching the latents at all.
+    """
+    from PIL import Image
+
+    from ..models.minimaxh3.vendor.packing_ref2va import (
+        decode_reference_video,
+        resample_reference_frames,
+        trim_reference_num_frames,
+    )
+
+    decoded, fps, _audio = decode_reference_video(str(path))
+    frames = resample_reference_frames(decoded, fps)
+    keep = trim_reference_num_frames(min(frames.shape[0], clip_frames))
+    if keep > frames.shape[0]:
+        raise ShortClipError(
+            f"{path.name} is {frames.shape[0]} frames once resampled to {_H3_FPS}fps, below H3's "
+            f"{keep}-frame minimum ({keep / _H3_FPS:.2f}s). Skipped."
+        )
+    return [Image.fromarray(frame) for frame in frames[:keep]]
 
 
 def _encode_captions(
-    root: Path, captions: list[str], device: str, dtype: Any
+    root: Path, captions: list[str], device: str, dtype: Any,
+    say: Callable[[str], None] = lambda _text: None,
 ) -> list[tuple[Any, Any]]:
     """Pass two: the 4-bit conditioner, then dropped."""
     import torch
 
     from ..models.minimaxh3.vendor.encoders import MiniMaxH3TextEncoderStep
 
+    say("loading the 4-bit text conditioner (20.5GB)")
     pipeline = _load_conditioner(root, device, dtype)
     # Encode wherever it landed. It spills to host RAM on a card too small for 20.5GB, and the
     # vendored step builds its input ids on the device it is handed, so CUDA ids against a
     # CPU-resident encoder fail in `index_select`.
     where = next(pipeline.text_encoder.parameters()).device
     if where.type != torch.device(device).type:
-        logger.info("MiniMax H3: conditioner is on %s, encoding captions there", where)
+        say(f"conditioner spilled to {where}, encoding captions there (slower)")
     out: list[tuple[Any, Any]] = []
     try:
-        for caption in captions:
+        for index, caption in enumerate(captions, start=1):
+            if index == 1 or index % 10 == 0 or index == len(captions):
+                say(f"encoding captions {index}/{len(captions)}")
             caption = caption or _EMPTY_CAPTION
             with torch.no_grad():
                 # The staticmethod rather than the block, so nothing needs a PipelineState. `dtype`
@@ -134,7 +209,7 @@ def _encode_captions(
             out.append((embeds[0].cpu(), tags.cpu()))
     finally:
         _drop_conditioner(pipeline)
-    logger.info("MiniMax H3: cached %d captions, conditioner released", len(out))
+    say(f"cached {len(out)} captions, conditioner released")
     return out