eclise 0.1.0__tar.gz

eclise-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+Contract changes in `eclise.clips` and `eclise.vla` are documented here: they
+no longer have independent versions.
+
+## 0.1.0
+
+Single distribution: one `eclise` wheel, tagged `eclise-v<version>`. Heavy
+stacks live in pixi features, not wheel extras. `eclise.launch` obtains env
+definitions by cloning this repo at the wheel's own version tag.
+
+### Legacy distributions
+
+The per-package distributions are gone, with no compatibility shims. Only
+three were ever published; all are deleted from PyPI:
+
+| Deleted from PyPI | Replacement | Import |
+|---|---|---|
+| `eclise-clips` (0.1.0) | `eclise[clips]` | `eclise.clips` |
+| `eclise-phyworld` (0.2.0) | run from checkout: `pixi run -e phyworld generate` | `eclise.phyworld` |
+| `ecliseutils` (0.1.0–0.1.3) | `eclise[utils]` | `eclise.utils` |
+
+`eclise-utils`, `eclise-datasets`, `eclise-vla`, and `eclise-openvid` were
+never published. Downstream projects must switch their requirement to the
+`eclise[<extra>]` form; the `ecliseutils` import name has no successor.

eclise-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wentinn Liao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eclise-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+# Extra files for the sdist. Wheels are unaffected (pixi files are never
+# installed); shipping them makes the sdist a self-contained description of
+# the environments that `eclise.launch` provisions.
+include pixi.toml
+include pixi.lock
+include CHANGELOG.md

eclise-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: eclise
+Version: 0.1.0
+Summary: Shared research infrastructure: clip/VLA contracts, research utilities, and stdlib launchers for isolated robotics/data environments.
+Author: Wentinn Liao
+License: MIT
+Project-URL: Homepage, https://github.com/JophiArcana/eclise
+Project-URL: Repository, https://github.com/JophiArcana/eclise
+Project-URL: Issues, https://github.com/JophiArcana/eclise/issues
+Keywords: research-utilities,robotics,vla,datasets,clips
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: utils
+Requires-Dist: numpy; extra == "utils"
+Requires-Dist: torch; extra == "utils"
+Requires-Dist: tensordict; extra == "utils"
+Requires-Dist: einops; extra == "utils"
+Requires-Dist: scipy; extra == "utils"
+Requires-Dist: matplotlib; extra == "utils"
+Requires-Dist: tqdm; extra == "utils"
+Requires-Dist: pandas; extra == "utils"
+Provides-Extra: ode
+Requires-Dist: torchdiffeq; extra == "ode"
+Provides-Extra: datasets
+Requires-Dist: datasets<5.0,>=3.0; extra == "datasets"
+Requires-Dist: huggingface_hub<1.0,>=0.34.0; extra == "datasets"
+Requires-Dist: Pillow~=12.2.0; extra == "datasets"
+Requires-Dist: numpy~=2.4.0; extra == "datasets"
+Provides-Extra: clips
+Requires-Dist: numpy>=1.24; extra == "clips"
+Requires-Dist: h5py>=3.10; extra == "clips"
+Requires-Dist: imageio[ffmpeg]>=2.36; extra == "clips"
+Requires-Dist: av>=13.1; extra == "clips"
+Provides-Extra: vla
+Requires-Dist: numpy; extra == "vla"
+Requires-Dist: websockets>=14; extra == "vla"
+Requires-Dist: msgpack>=1.0.5; extra == "vla"
+Provides-Extra: octo
+Requires-Dist: eclise[vla]; extra == "octo"
+Provides-Extra: smolvla
+Requires-Dist: eclise[vla]; extra == "smolvla"
+Provides-Extra: pi0
+Requires-Dist: eclise[vla]; extra == "pi0"
+Provides-Extra: libero
+Requires-Dist: eclise[vla]; extra == "libero"
+Provides-Extra: all
+Requires-Dist: eclise[utils]; extra == "all"
+Requires-Dist: eclise[datasets]; extra == "all"
+Requires-Dist: eclise[clips]; extra == "all"
+Requires-Dist: eclise[vla]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: eclise[all]; extra == "dev"
+Requires-Dist: pytest~=8.4.0; extra == "dev"
+Dynamic: license-file
+
+# eclise
+
+Shared research infrastructure: one `eclise` wheel under the PEP 420 namespace
+`eclise.*`. The folder taxonomy is organizational only — imports are always
+flat `eclise.<name>`. Heavy stacks live in pixi environments, not in wheel
+metadata.
+
+## Extras (the published wheel)
+
+| Extra | Import | Purpose |
+|---|---|---|
+| `utils` | `eclise.utils` | Research utilities (tensor/module batching, linalg, ARE/ODE, labeled arrays, plotting) |
+| `ode` | `eclise.utils.ode` | `torchdiffeq` for `batch_odeint` |
+| `datasets` | `eclise.datasets` | Adapters for consuming external datasets (ImageNet-1k val sampling, label tables) |
+| `clips` | `eclise.clips` | First-party clip-shard data contract (mp4-in-HDF5 + per-frame state labels) |
+| `vla` | `eclise.vla` | Sim-/model-agnostic VLA obs/action schema + websocket env/policy serving |
+| `octo` / `smolvla` / `pi0` / `libero` | (client aliases) | `eclise[vla]` — talking to a server, not installing its stack |
+| `all` | | utils + datasets + clips + vla |
+| `dev` | | all + pytest |
+
+`eclise.octo` / `smolvla` / `libero` / `phyworld` / `openvid` / `pi0` / `launch`
+ship as inert source in the same wheel. Running a server or generator needs
+the matching pixi environment (or `python -m eclise.launch`).
+
+`models/vision/` is deliberately absent: a vision-model contract will be
+created only once it has at least two real consumers.
+
+## Pixi environments (from a checkout)
+
+| Environment | Python | Kind | Purpose |
+|---|---|---|---|
+| `dev` | 3.12 | library | `eclise[dev]` + contract/launcher tests |
+| `libero` | 3.10 | socket (env-server, port 9000) | LIBERO + robosuite/MuJoCo harness |
+| `octo` | 3.10 | socket (policy, port 8000) | Octo JAX 0.4.20 policy server |
+| `smolvla` | 3.12 | socket (policy, port 8000) | SmolVLA (LeRobot) policy server |
+| `pi0` | 3.11 | socket (policy, port 8000) | Tooling for upstream openpi (`uv` / git-lfs / gsutil) |
+| `phyworld` | 3.10 | batch | Box2D families → `eclise.clips` shards |
+| `phyworld-phyre` | 3.9 | batch | PHYRE combinatorial family (`phyre==0.2.2`) |
+| `openvid` | 3.10 | batch | OpenVid-1M mp4 → 256px fixed-FPS shards |
+
+## Installing
+
+Client-side (numpy-1.x-safe `eclise.vla` only — no torch/jax):
+
+```bash
+pip install "eclise[octo,libero]"
+python -m eclise.launch start octo --setup
+```
+
+`--setup` clones this repo at `eclise-v<wheel version>` (unless
+`ECLISE_ROOT` already points at a checkout), installs pixi if needed, and
+runs `pixi install -e <env>`. `start` returns a host/port; the caller wires
+`WebsocketPolicyClient` / `WebsocketEnvClient`.
+
+From a checkout:
+
+```bash
+pixi install -e dev
+pixi run -e dev test
+pixi run -e libero setup
+pixi run -e libero serve --port 9000
+```
+
+## Developing
+
+```bash
+pixi run -e dev test
+pixi run -e libero serve
+pixi run -e phyworld generate --family collision --grid in_dist_l0 --experiment smoke --limit 32
+```
+
+Editable extras without pixi: `pip install -e ".[dev]"`. Releases are tagged
+`eclise-v0.1.0`.
+
+## Design rules
+
+- **One distribution, environments at the pixi boundary.** Incompatible
+  stacks (JAX vs torch, numpy 1.x vs 2.x) do not share an environment.
+  Wheel extras stay light; pixi features own the heavy pins.
+- **Imports are flat, folders carry taxonomy.** Moving a package between
+  folders is never a breaking change for consumers.
+- **`eclise.clips` and `eclise.vla` are contracts.** Writers and readers may
+  live in different repos/envs; document schema changes in `CHANGELOG.md`.
+  `eclise[vla]` must remain numpy 1.x-compatible.
+
+## Package archetypes
+
+Every package is one of three kinds. New packages pick one and follow its
+rules rather than inventing a fourth layout.
+
+**Library extra** — published wheel, installed into a consumer's env, no
+server. `utils`, `datasets`, `clips`, `vla`.
+
+**Interactive socket service** — pixi env isolates an incompatible stack
+behind an `eclise.vla` websocket. `octo`, `smolvla`, `pi0`, `libero`.
+
+- Env: `pixi install -e <name>` (and `pixi run -e <name> setup` when the
+  feature defines a `setup` task).
+- Server logic lives in the package as `eclise.<name>.serve` (pi0 wraps
+  upstream openpi instead).
+- Launch: `python -m eclise.launch start <name>` → `pixi run -e <env> serve`.
+
+**Batch producer** — pixi env; decoupled via the on-disk `eclise.clips`
+shard contract (no socket). `phyworld`, `openvid`.
+
+- Env: `pixi install -e <name>` + `pixi run -e <name> setup` (scratch
+  `data/` / `outputs/` symlinks).
+- Job entrypoint: `scripts/<verb>.py` (+ `.sbatch` via `pixi run -e <env>`).
+- Producer verify: `scripts/verify_shards.py`.
+
+| Package | Archetype |
+|---|---|
+| `utils`, `datasets`, `clips`, `vla` | library extra |
+| `octo`, `smolvla`, `libero` | interactive socket service (`eclise.<name>.serve`) |
+| `pi0` | interactive socket service (`setup_pi0.sh` + `serve_pi0.sh` wrap openpi) |
+| `phyworld` | batch producer (`phyworld-phyre` is the PHYRE secondary env) |
+| `openvid` | batch producer |

eclise-0.1.0/README.md

@@ -0,0 +1,117 @@
+# eclise
+
+Shared research infrastructure: one `eclise` wheel under the PEP 420 namespace
+`eclise.*`. The folder taxonomy is organizational only — imports are always
+flat `eclise.<name>`. Heavy stacks live in pixi environments, not in wheel
+metadata.
+
+## Extras (the published wheel)
+
+| Extra | Import | Purpose |
+|---|---|---|
+| `utils` | `eclise.utils` | Research utilities (tensor/module batching, linalg, ARE/ODE, labeled arrays, plotting) |
+| `ode` | `eclise.utils.ode` | `torchdiffeq` for `batch_odeint` |
+| `datasets` | `eclise.datasets` | Adapters for consuming external datasets (ImageNet-1k val sampling, label tables) |
+| `clips` | `eclise.clips` | First-party clip-shard data contract (mp4-in-HDF5 + per-frame state labels) |
+| `vla` | `eclise.vla` | Sim-/model-agnostic VLA obs/action schema + websocket env/policy serving |
+| `octo` / `smolvla` / `pi0` / `libero` | (client aliases) | `eclise[vla]` — talking to a server, not installing its stack |
+| `all` | | utils + datasets + clips + vla |
+| `dev` | | all + pytest |
+
+`eclise.octo` / `smolvla` / `libero` / `phyworld` / `openvid` / `pi0` / `launch`
+ship as inert source in the same wheel. Running a server or generator needs
+the matching pixi environment (or `python -m eclise.launch`).
+
+`models/vision/` is deliberately absent: a vision-model contract will be
+created only once it has at least two real consumers.
+
+## Pixi environments (from a checkout)
+
+| Environment | Python | Kind | Purpose |
+|---|---|---|---|
+| `dev` | 3.12 | library | `eclise[dev]` + contract/launcher tests |
+| `libero` | 3.10 | socket (env-server, port 9000) | LIBERO + robosuite/MuJoCo harness |
+| `octo` | 3.10 | socket (policy, port 8000) | Octo JAX 0.4.20 policy server |
+| `smolvla` | 3.12 | socket (policy, port 8000) | SmolVLA (LeRobot) policy server |
+| `pi0` | 3.11 | socket (policy, port 8000) | Tooling for upstream openpi (`uv` / git-lfs / gsutil) |
+| `phyworld` | 3.10 | batch | Box2D families → `eclise.clips` shards |
+| `phyworld-phyre` | 3.9 | batch | PHYRE combinatorial family (`phyre==0.2.2`) |
+| `openvid` | 3.10 | batch | OpenVid-1M mp4 → 256px fixed-FPS shards |
+
+## Installing
+
+Client-side (numpy-1.x-safe `eclise.vla` only — no torch/jax):
+
+```bash
+pip install "eclise[octo,libero]"
+python -m eclise.launch start octo --setup
+```
+
+`--setup` clones this repo at `eclise-v<wheel version>` (unless
+`ECLISE_ROOT` already points at a checkout), installs pixi if needed, and
+runs `pixi install -e <env>`. `start` returns a host/port; the caller wires
+`WebsocketPolicyClient` / `WebsocketEnvClient`.
+
+From a checkout:
+
+```bash
+pixi install -e dev
+pixi run -e dev test
+pixi run -e libero setup
+pixi run -e libero serve --port 9000
+```
+
+## Developing
+
+```bash
+pixi run -e dev test
+pixi run -e libero serve
+pixi run -e phyworld generate --family collision --grid in_dist_l0 --experiment smoke --limit 32
+```
+
+Editable extras without pixi: `pip install -e ".[dev]"`. Releases are tagged
+`eclise-v0.1.0`.
+
+## Design rules
+
+- **One distribution, environments at the pixi boundary.** Incompatible
+  stacks (JAX vs torch, numpy 1.x vs 2.x) do not share an environment.
+  Wheel extras stay light; pixi features own the heavy pins.
+- **Imports are flat, folders carry taxonomy.** Moving a package between
+  folders is never a breaking change for consumers.
+- **`eclise.clips` and `eclise.vla` are contracts.** Writers and readers may
+  live in different repos/envs; document schema changes in `CHANGELOG.md`.
+  `eclise[vla]` must remain numpy 1.x-compatible.
+
+## Package archetypes
+
+Every package is one of three kinds. New packages pick one and follow its
+rules rather than inventing a fourth layout.
+
+**Library extra** — published wheel, installed into a consumer's env, no
+server. `utils`, `datasets`, `clips`, `vla`.
+
+**Interactive socket service** — pixi env isolates an incompatible stack
+behind an `eclise.vla` websocket. `octo`, `smolvla`, `pi0`, `libero`.
+
+- Env: `pixi install -e <name>` (and `pixi run -e <name> setup` when the
+  feature defines a `setup` task).
+- Server logic lives in the package as `eclise.<name>.serve` (pi0 wraps
+  upstream openpi instead).
+- Launch: `python -m eclise.launch start <name>` → `pixi run -e <env> serve`.
+
+**Batch producer** — pixi env; decoupled via the on-disk `eclise.clips`
+shard contract (no socket). `phyworld`, `openvid`.
+
+- Env: `pixi install -e <name>` + `pixi run -e <name> setup` (scratch
+  `data/` / `outputs/` symlinks).
+- Job entrypoint: `scripts/<verb>.py` (+ `.sbatch` via `pixi run -e <env>`).
+- Producer verify: `scripts/verify_shards.py`.
+
+| Package | Archetype |
+|---|---|
+| `utils`, `datasets`, `clips`, `vla` | library extra |
+| `octo`, `smolvla`, `libero` | interactive socket service (`eclise.<name>.serve`) |
+| `pi0` | interactive socket service (`setup_pi0.sh` + `serve_pi0.sh` wrap openpi) |
+| `phyworld` | batch producer (`phyworld-phyre` is the PHYRE secondary env) |
+| `openvid` | batch producer |

eclise-0.1.0/data/clips/src/eclise/clips/__init__.py

@@ -0,0 +1,97 @@
+"""A shared on-disk contract for video clips with per-frame state labels.
+
+Sits between anything that *produces* clips (a simulator, a download of a
+published dataset, eventually a real-video ingest) and anything that *consumes*
+them (a training project). Producers and consumers live in separate conda envs
+and never import each other; they agree on this package instead.
+
+    from eclise.clips import ClipDataset
+
+    data = ClipDataset("data/phyworld/data/collision_30K")
+    item = data[0]
+    item["pixels"]    # [3, T, H, W] float32 in [-1, 1]
+    item["positions"] # [T, n_objects, 2] world units, y up
+    item["velocity"]  # [2] px/frame, y down (image convention)
+    data.source_fps   # 1 / frame_dt -- authoritative, not the mp4 header
+
+Upstream phyworld's published HDF5 carries no metadata, so it needs its family
+named:
+
+    from eclise.clips.readers import phyworld_hdf5
+
+    shards = phyworld_hdf5.open_shard_set("collision_30K.hdf5", family="collision")
+    data = ClipDataset(shards, velocity_object=0)
+
+Writing is the mirror image: declare a
+:class:`~eclise.clips.schema.ShardMeta`, then append clips.
+
+    from eclise.clips import ShardMeta, ShardWriter, position_spec
+
+    meta = ShardMeta(
+        family="uniform_motion", num_clips=0, clip_len=32,
+        image_size=(256, 256), frame_dt=0.1, world_scale=10.0,
+        labels={"positions": position_spec()},
+    )
+    with ShardWriter("shard_000.hdf5", meta) as w:
+        w.append(frames, positions=positions)
+
+Torch is needed only for :class:`~eclise.clips.dataset.ClipDataset`; the schema,
+shard, and reader layers are pure numpy.
+"""
+
+from __future__ import annotations
+
+from .codec import decode_mp4, encode_mp4
+from .labels import (
+    collision_frame,
+    positions_to_pixels,
+    velocities_per_frame,
+    velocity_from_state,
+)
+from .schema import (
+    LABEL_GROUP,
+    META_ATTR,
+    SCHEMA_VERSION,
+    VIDEO_DATASET,
+    LabelSpec,
+    SchemaError,
+    ShardMeta,
+    object_attrs_spec,
+    params_spec,
+    position_spec,
+    velocity_field_spec,
+)
+from .shards import ShardReader, ShardSet, ShardWriter, write_shard
+
+__all__ = [
+    "LABEL_GROUP",
+    "META_ATTR",
+    "SCHEMA_VERSION",
+    "VIDEO_DATASET",
+    "LabelSpec",
+    "SchemaError",
+    "ShardMeta",
+    "ShardReader",
+    "ShardSet",
+    "ShardWriter",
+    "collision_frame",
+    "decode_mp4",
+    "encode_mp4",
+    "object_attrs_spec",
+    "params_spec",
+    "position_spec",
+    "positions_to_pixels",
+    "velocities_per_frame",
+    "velocity_field_spec",
+    "velocity_from_state",
+    "write_shard",
+]
+
+
+def __getattr__(name: str):
+    """Expose :class:`~eclise.clips.dataset.ClipDataset` without importing torch eagerly."""
+    if name in ("ClipDataset", "iter_clip_batches", "PIXEL_RANGES"):
+        from . import dataset
+
+        return getattr(dataset, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

eclise-0.1.0/data/clips/src/eclise/clips/codec.py

@@ -0,0 +1,85 @@
+"""In-memory mp4 encode/decode for clip bytestreams.
+
+Upstream phyworld carries a copy of this logic in every generator script (four
+copies of ``convert_frames_to_mp4_bytestream_wo_disk``, plus disk-roundtripping
+variants that were left behind after the in-memory version replaced them). This
+is the one home for it.
+
+Encoding is lossy. H.264 on synthetic content -- flat backgrounds with a few
+hard-edged coloured circles -- is close to visually lossless at sane bitrates,
+but "close" is not "exact", and every consumer of a decoded clip is looking at
+compression artifacts. That is a property of the storage format we inherit, not
+something this module can fix; it is why
+``data/phyworld/scripts/verify_shards.py`` measures state recovery *after* a
+decode round-trip rather than trusting the pre-encode frames.
+"""
+
+from __future__ import annotations
+
+from io import BytesIO
+
+import numpy as np
+
+#: Encoder quality knob. imageio/ffmpeg's default CRF is 23, visibly soft on
+#: hard synthetic edges; 18 is near-transparent for this content at a modest
+#: size increase. Applies only to clips this package writes.
+DEFAULT_CRF = 18
+
+
+def encode_mp4(frames: np.ndarray, *, crf: int = DEFAULT_CRF, fps: float = 24.0) -> np.ndarray:
+    """Encode ``[T, H, W, 3]`` uint8 frames to an mp4 bytestream as ``[n] uint8``.
+
+    ``fps`` lands in the container header only. It is *not* the physics frame
+    rate -- that is :attr:`eclise.clips.schema.ShardMeta.frame_dt`, recorded
+    separately. A value is passed anyway so the header is at least a valid,
+    deliberate number rather than an encoder default (upstream passes nothing,
+    which is how its stored clips ended up with a meaningless rate).
+
+    H.264 requires even frame dimensions; odd ones are rejected here rather than
+    silently rescaled, since a resized clip would invalidate every pixel-unit
+    label in the shard.
+    """
+    import imageio.v3 as iio
+
+    arr = np.asarray(frames)
+    if arr.ndim != 4 or arr.shape[-1] != 3:
+        raise ValueError(f"expected frames [T, H, W, 3], got {arr.shape}")
+    if arr.dtype != np.uint8:
+        raise ValueError(f"expected uint8 frames, got {arr.dtype}")
+    h, w = arr.shape[1:3]
+    if h % 2 or w % 2:
+        raise ValueError(
+            f"H.264 needs even frame dimensions; got {h}x{w}. Render at an even "
+            "size rather than resizing here, which would invalidate pixel labels."
+        )
+    with BytesIO() as buffer:
+        iio.imwrite(
+            buffer,
+            arr,
+            extension=".mp4",
+            fps=fps,
+            codec="libx264",
+            # The pixel format goes through imageio's own keyword, not
+            # output_params: the ffmpeg plugin always emits a -pix_fmt of its own,
+            # so passing a second one makes ffmpeg warn once per encoded clip --
+            # millions of stderr lines on a full generation run, for a flag that
+            # was already set to the same value.
+            pixelformat="yuv420p",
+            output_params=["-crf", str(crf)],
+        )
+        payload = buffer.getvalue()
+    return np.frombuffer(payload, dtype=np.uint8)
+
+
+def decode_mp4(stream: np.ndarray | bytes) -> np.ndarray:
+    """Decode an mp4 bytestream to ``[T, H, W, 3]`` uint8 frames."""
+    import imageio.v3 as iio
+
+    payload = stream.tobytes() if isinstance(stream, np.ndarray) else stream
+    frames = iio.imread(payload, index=None, extension=".mp4")
+    arr = np.asarray(frames)
+    if arr.ndim == 3:  # a single-frame clip decodes without the leading axis
+        arr = arr[None]
+    if arr.shape[-1] == 4:  # some decoders hand back RGBA
+        arr = arr[..., :3]
+    return arr