tensorcodec 0.1.3__tar.gz → 0.1.4__tar.gz

{tensorcodec-0.1.3 → tensorcodec-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensorcodec
-Version: 0.1.3
+Version: 0.1.4
 Classifier: Development Status :: 3 - Alpha
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS :: MacOS X
@@ -34,7 +34,7 @@ CPU video/audio decoding with TorchCodec-style APIs and NumPy output.
 <a href="https://pypi.org/project/tensorcodec/"><img src="https://img.shields.io/pypi/v/tensorcodec" alt="PyPI"></a>
 <a href="https://pypi.org/project/tensorcodec/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python"></a>
 <!-- wheel-size-badge:start -->
-<a href="#package-size"><img src="https://img.shields.io/badge/wheel-10.4%20MiB-blue" alt="Wheel download"></a>
+<a href="#package-size"><img src="https://img.shields.io/badge/wheel-10.5%20MiB-blue" alt="Wheel download"></a>
 <!-- wheel-size-badge:end -->
 <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue" alt="License: MIT"></a>
 </p>
@@ -48,8 +48,9 @@ CPU video/audio decoding with TorchCodec-style APIs and NumPy output.
 - **Validated playback semantics.** Frame selection, ordering, timestamps and audio
   ranges are checked against TorchCodec 0.17.0 and independently generated media.
 - **Efficient batch decoding.** Rust/PyO3 bindings to FFmpeg process frame batches
-  in a single native call, avoiding per-frame Python calls.
-- **Lightweight installation.** Linux wheels are 10.2–10.4 MiB (v0.1.2), including
+  in a single native call, avoiding per-frame Python calls. Closing a decoder
+  releases its FFmpeg resources without waiting for Python's cyclic GC.
+- **Lightweight installation.** Linux wheels are 10.3–10.5 MiB (v0.1.3), including
   FFmpeg shared libraries. NumPy is the only Python dependency.
 
 ## Quick start
@@ -77,9 +78,20 @@ with AudioDecoder("audio.wav", sample_rate=16000, num_channels=1) as audio:
 Arrays keep their storage after the decoder closes. Paths, URLs, encoded bytes,
 1-D uint8 arrays and seekable file objects are supported.
 
+For time-based windows without an initial full packet scan (since v0.1.4):
+
+```python
+with VideoDecoder("video.mkv", seek_mode="timestamp") as decoder:
+    frames = decoder.get_frames_played_at([10.0, 10.1, 10.2])
+```
+
+This TensorCodec extension selects by actual PTS and retries seeks that overshoot.
+It supports time queries, including ranges with explicit `fps`, but not frame
+indices, `len(decoder)`, or `get_all_frames()`. See [the contract](docs/compatibility.md#timestamp-mode).
+
 ## Features
 
-TensorCodec 0.1.3 relative to TorchCodec 0.17.0.
+TensorCodec 0.1.4 relative to TorchCodec 0.17.0.
 ✓ supported · △ partial support · — not implemented.
 
 | Component | TensorCodec | TorchCodec 0.17.0 |
@@ -132,7 +144,7 @@ Linux CPU wheels, Python 3.12. Download / unpacked size in MiB.
 
 | Package | x86_64 | ARM64 |
 | --- | ---: | ---: |
-| TensorCodec | 10.2 / 24.7 | 10.4 / 22.9 |
+| TensorCodec | 10.3 / 24.8 | 10.5 / 23.0 |
 | PyAV | 33.4 / 125.5 | 31.2 / 90.4 |
 | TorchCodec + PyTorch (CPU) | 196.7 / 704.7 | 160.3 / 585.7 |
 <!-- wheel-size:end -->

{tensorcodec-0.1.3 → tensorcodec-0.1.4}/README.md

@@ -9,7 +9,7 @@ CPU video/audio decoding with TorchCodec-style APIs and NumPy output.
 <a href="https://pypi.org/project/tensorcodec/"><img src="https://img.shields.io/pypi/v/tensorcodec" alt="PyPI"></a>
 <a href="https://pypi.org/project/tensorcodec/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python"></a>
 <!-- wheel-size-badge:start -->
-<a href="#package-size"><img src="https://img.shields.io/badge/wheel-10.4%20MiB-blue" alt="Wheel download"></a>
+<a href="#package-size"><img src="https://img.shields.io/badge/wheel-10.5%20MiB-blue" alt="Wheel download"></a>
 <!-- wheel-size-badge:end -->
 <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue" alt="License: MIT"></a>
 </p>
@@ -23,8 +23,9 @@ CPU video/audio decoding with TorchCodec-style APIs and NumPy output.
 - **Validated playback semantics.** Frame selection, ordering, timestamps and audio
   ranges are checked against TorchCodec 0.17.0 and independently generated media.
 - **Efficient batch decoding.** Rust/PyO3 bindings to FFmpeg process frame batches
-  in a single native call, avoiding per-frame Python calls.
-- **Lightweight installation.** Linux wheels are 10.2–10.4 MiB (v0.1.2), including
+  in a single native call, avoiding per-frame Python calls. Closing a decoder
+  releases its FFmpeg resources without waiting for Python's cyclic GC.
+- **Lightweight installation.** Linux wheels are 10.3–10.5 MiB (v0.1.3), including
   FFmpeg shared libraries. NumPy is the only Python dependency.
 
 ## Quick start
@@ -52,9 +53,20 @@ with AudioDecoder("audio.wav", sample_rate=16000, num_channels=1) as audio:
 Arrays keep their storage after the decoder closes. Paths, URLs, encoded bytes,
 1-D uint8 arrays and seekable file objects are supported.
 
+For time-based windows without an initial full packet scan (since v0.1.4):
+
+```python
+with VideoDecoder("video.mkv", seek_mode="timestamp") as decoder:
+    frames = decoder.get_frames_played_at([10.0, 10.1, 10.2])
+```
+
+This TensorCodec extension selects by actual PTS and retries seeks that overshoot.
+It supports time queries, including ranges with explicit `fps`, but not frame
+indices, `len(decoder)`, or `get_all_frames()`. See [the contract](docs/compatibility.md#timestamp-mode).
+
 ## Features
 
-TensorCodec 0.1.3 relative to TorchCodec 0.17.0.
+TensorCodec 0.1.4 relative to TorchCodec 0.17.0.
 ✓ supported · △ partial support · — not implemented.
 
 | Component | TensorCodec | TorchCodec 0.17.0 |
@@ -107,7 +119,7 @@ Linux CPU wheels, Python 3.12. Download / unpacked size in MiB.
 
 | Package | x86_64 | ARM64 |
 | --- | ---: | ---: |
-| TensorCodec | 10.2 / 24.7 | 10.4 / 22.9 |
+| TensorCodec | 10.3 / 24.8 | 10.5 / 23.0 |
 | PyAV | 33.4 / 125.5 | 31.2 / 90.4 |
 | TorchCodec + PyTorch (CPU) | 196.7 / 704.7 | 160.3 / 585.7 |
 <!-- wheel-size:end -->

tensorcodec-0.1.4/benchmarks/README.md

@@ -0,0 +1,99 @@
+# TensorCodec benchmarks
+
+These tools measure the current TensorCodec implementation and optional comparison
+backends. Performance depends on the input, seek mode, thread count, storage and
+cache state. Measure your workload before choosing a decoder.
+
+## Setup
+
+Use the [development environment](../README.md#development-and-verification).
+TensorCodec-only runs need NumPy and TensorCodec; TorchCodec comparisons also need
+the pinned oracle group. FFmpeg CLI with the requested encoders is required to
+generate fixtures. Run from the repository root.
+
+```sh
+uv run --no-sync python -m benchmarks --list-decoders
+uv run --no-sync python -m benchmarks --prepare --num-videos 4 --video-duration 10
+uv run --no-sync python -m benchmarks --no-io --decoders tensorcodec \
+  --runs 3 --output json --save benchmarks/results/speed.json
+```
+
+For a CPU comparison, explicitly select the same thread count and seek mode:
+
+```sh
+uv run --no-sync python -m benchmarks --no-io \
+  --decoders tensorcodec 'torchcodec(seek=exact,thr=1)' \
+  --runs 3 --output json --save benchmarks/results/speed.json
+```
+
+## Measurements
+
+| Scenario | Workload | Included costs |
+| --- | --- | --- |
+| `temporal_window` | Random playback queries, 11 samples over a 1-second window | Decoder open, exact-mode packet scan, seeking, decoding, NumPy output |
+| `sequential_range` | Decode the full video range | Decoder open, range selection, decoding, NumPy output |
+
+The TensorCodec adapter opens and closes a decoder for each request. Results do
+not represent a persistent decoder cache such as MediaRef's. Compare exact and
+approximate modes separately: approximate mode does not guarantee exact VFR frame
+selection. GPU comparison adapters include transfer back to CPU NumPy arrays.
+
+For codec/container throughput experiments:
+
+```sh
+uv run --no-sync python -m benchmarks.container_bench --help
+uv run --no-sync python -m benchmarks.container_bench
+```
+
+This tool generates fresh inputs with FFmpeg. Its codec matrix measures speed;
+it does not assert pixel or timestamp correctness. See
+[container and seek behavior](../docs/container_robustness.md) for tested guarantees.
+
+## Optional I/O and plotting
+
+To separate opening from an 11-frame playback window, counting bytes returned by
+file reads (including rereads, **not** physical disk or network traffic):
+
+```sh
+ffprobe -v error -select_streams v:0 -show_frames \
+  -show_entries frame=pts,duration,key_frame -of json video.mp4 > frames.json
+uv run --no-sync python -m benchmarks.open_cost video.mp4 --start 10 \
+  --backends tensorcodec torchcodec --mappings frames.json
+```
+
+Both libraries scan packets to EOF on each fresh default `exact` open. Precomputed
+`custom_frame_mappings` skip that scan while preserving exact selection; header
+probing and window reads remain. Generate mappings once for the **same encoded
+stream**, outside training. PTS alone is insufficient: durations and keyframe flags
+are also required, in the stream's integer time base. The tool checks mapped
+window pixels/PTS/durations against exact, and rotates mode order between trials;
+it does not control OS caches. `approximate` is measured separately without an
+accuracy guarantee. Container seek indexes are not generally complete frame maps
+(e.g. MKV Cues); they cannot universally replace an exact scan.
+
+FUSE measurements require Linux FUSE access, `pyfuse3` and `trio`. Install these
+only in the benchmark environment, then omit `--no-io`. The runner can fall back
+to speed-only results when FUSE is unavailable; check that `io_bytes` is populated
+before reporting I/O figures. FUSE timing includes its own filesystem overhead.
+
+```sh
+uv run --no-sync python -m benchmarks --decoders tensorcodec \
+  'torchcodec(seek=exact,thr=1)' --scenarios temporal_window \
+  --runs 3 --output json --save benchmarks/results/io.json
+```
+
+Install `matplotlib` in the benchmark environment to plot measurements:
+
+```sh
+uv run --no-sync python -m benchmarks.plot_results \
+  --speed benchmarks/results/speed.json --io benchmarks/results/io.json
+```
+
+## Reporting results
+
+Generated JSON and charts stay in `benchmarks/results/`, which is gitignored.
+Publish results only with the TensorCodec/TorchCodec/FFmpeg/NumPy versions,
+hardware, corpus, seek/thread settings, cache conditions and commands. Identify
+timeouts as partial results. Check frame selection and pixel agreement separately
+using the [compatibility contract](../docs/compatibility.md); throughput alone is
+not a correctness check.

tensorcodec-0.1.4/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""tensorcodec benchmark suite — FPS and disk I/O measurement for video decoders."""

tensorcodec-0.1.4/benchmarks/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m benchmarks`` to launch the runner."""
+
+from benchmarks.runner import main
+
+main()

tensorcodec-0.1.4/benchmarks/container_bench.py

@@ -0,0 +1,157 @@
+"""Container & codec robustness benchmark.
+
+Generates synthetic videos in various codec × container combinations and
+measures random-seek performance for tensorcodec and (optionally) TorchCodec.
+
+Usage::
+
+    uv run --no-sync python -m benchmarks.container_bench
+    uv run --no-sync python -m benchmarks.container_bench --duration 60 --queries 200
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import random
+import subprocess
+import tempfile
+import time
+
+import numpy as np
+
+# ---------------------------------------------------------------------------
+# Video generation
+# ---------------------------------------------------------------------------
+
+COMBOS: list[tuple[str, str, str, str, dict]] = [
+    # (codec_label, extension, av_codec, pix_fmt, encoder_opts)
+    ("h264", "mp4", "libx264", "yuv420p", {"g": "10"}),
+    ("h264", "mkv", "libx264", "yuv420p", {"g": "10"}),
+    ("h264", "avi", "libx264", "yuv420p", {"g": "10"}),
+    ("h264", "ts", "libx264", "yuv420p", {"g": "10"}),
+    ("h265", "mp4", "libx265", "yuv420p", {"g": "10", "x265-params": "log-level=error"}),
+    ("h265", "mkv", "libx265", "yuv420p", {"g": "10", "x265-params": "log-level=error"}),
+    ("h265", "ts", "libx265", "yuv420p", {"g": "10", "x265-params": "log-level=error"}),
+    ("vp9", "mkv", "libvpx-vp9", "yuv420p", {"g": "10", "quality": "realtime", "speed": "8"}),
+    ("vp9", "webm", "libvpx-vp9", "yuv420p", {"g": "10", "quality": "realtime", "speed": "8"}),
+    ("mpeg4", "mp4", "mpeg4", "yuv420p", {"g": "10"}),
+    ("mpeg4", "mkv", "mpeg4", "yuv420p", {"g": "10"}),
+    ("mpeg4", "avi", "mpeg4", "yuv420p", {"g": "10"}),
+    ("mjpeg", "mkv", "mjpeg", "yuvj420p", {}),
+    ("mjpeg", "avi", "mjpeg", "yuvj420p", {}),
+]
+
+
+def _create_video(
+    path: str,
+    codec: str,
+    pix_fmt: str = "yuv420p",
+    duration_sec: int = 30,
+    fps: int = 30,
+    opts: dict | None = None,
+) -> None:
+    cmd = [
+        "ffmpeg",
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-y",
+        "-f",
+        "lavfi",
+        "-i",
+        f"testsrc2=size=640x480:rate={fps}:duration={duration_sec}",
+        "-c:v",
+        codec,
+        "-pix_fmt",
+        pix_fmt,
+    ]
+    for key, value in (opts or {}).items():
+        cmd.extend([f"-{key}", str(value)])
+    subprocess.run([*cmd, path], capture_output=True, check=True)
+
+
+# ---------------------------------------------------------------------------
+# Benchmark helpers
+# ---------------------------------------------------------------------------
+
+
+def _bench_tensorcodec(path: str, windows: list[list[float]]) -> str:
+    from tensorcodec.decoders import VideoDecoder
+
+    try:
+        with VideoDecoder(path) as d:
+            d.get_frames_played_at([1.0])
+    except (RuntimeError, ValueError, OSError):
+        return "FAIL"
+    t0 = time.perf_counter()
+    total = 0
+    for w in windows:
+        with VideoDecoder(path) as d:
+            total += d.get_frames_played_at(w).data.shape[0]
+    return f"{total / (time.perf_counter() - t0):.0f}"
+
+
+def _bench_torchcodec(path: str, windows: list[list[float]], seek_mode: str) -> str:
+    try:
+        from torchcodec.decoders import VideoDecoder
+    except ImportError:
+        return "N/A"
+    try:
+        VideoDecoder(path, seek_mode=seek_mode, num_ffmpeg_threads=1).get_frames_played_at([1.0])
+    except (RuntimeError, ValueError, OSError):
+        return "FAIL"
+    t0 = time.perf_counter()
+    total = 0
+    for w in windows:
+        dec = VideoDecoder(path, seek_mode=seek_mode, num_ffmpeg_threads=1)
+        total += dec.get_frames_played_at(w).data.shape[0]
+    return f"{total / (time.perf_counter() - t0):.0f}"
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Container robustness benchmark")
+    parser.add_argument("--duration", type=int, default=30, help="Video duration in seconds")
+    parser.add_argument("--queries", type=int, default=100, help="Number of random-seek queries")
+    parser.add_argument("--seed", type=int, default=42)
+    args = parser.parse_args()
+
+    random.seed(args.seed)
+    lo = max(2.0, args.duration * 0.1)
+    hi = args.duration - 1.0
+    ts = [random.uniform(lo, hi) for _ in range(args.queries)]
+    windows = [[t + o for o in np.arange(-1.0, 0.05, 0.1).tolist()] for t in ts]
+
+    with tempfile.TemporaryDirectory(prefix="container_bench_") as tmp:
+        hdr = (
+            f"{'codec.container':20s} {'tensorcodec':>10s} {'TC(apx)':>10s} {'TC(ext)':>10s}  {'apx/tensorcodec':>10s}"
+        )
+        print(hdr)
+        print("-" * len(hdr))
+
+        for codec_label, ext, av_codec, pix, opts in COMBOS:
+            path = os.path.join(tmp, f"{codec_label}.{ext}")
+            try:
+                _create_video(path, av_codec, pix, args.duration, opts=opts)
+            except (OSError, subprocess.CalledProcessError) as e:
+                print(f"{codec_label}.{ext:20s} CREATE FAILED: {e}")
+                continue
+
+            r1 = _bench_tensorcodec(path, windows)
+            r2 = _bench_torchcodec(path, windows, "approximate")
+            r3 = _bench_torchcodec(path, windows, "exact")
+            try:
+                ratio = f"{float(r2) / float(r1):.2f}x"
+            except (ValueError, ZeroDivisionError):
+                ratio = "N/A"
+            label = f"{codec_label}.{ext}"
+            print(f"{label:20s} {r1:>10s} {r2:>10s} {r3:>10s}  {ratio:>10s}")
+
+
+if __name__ == "__main__":
+    main()

tensorcodec-0.1.4/benchmarks/counting_fs.py

@@ -0,0 +1,128 @@
+"""FUSE passthrough filesystem that counts read I/O.
+
+Requires ``pyfuse3`` and ``trio``.  The benchmark runner gracefully
+falls back to speed-only measurement when these are unavailable.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import threading
+
+import pyfuse3
+
+
+class CountingFS(pyfuse3.Operations):
+    """Passthrough FS that transparently counts bytes read and read calls."""
+
+    def __init__(self, root: str):
+        super().__init__()
+        self.root = root
+        self.read_bytes = 0
+        self.read_calls = 0
+        self._lock = threading.Lock()
+        self._fd_map: dict[int, int] = {}
+        self._inode_path: dict[int, str] = {pyfuse3.ROOT_INODE: root}
+        self._path_inode: dict[str, int] = {root: pyfuse3.ROOT_INODE}
+        self._next_inode = pyfuse3.ROOT_INODE + 1
+
+    # ---- helpers -----------------------------------------------------------
+    def _get_path(self, inode: int) -> str | None:
+        return self._inode_path.get(inode)
+
+    def _get_or_create_inode(self, path: str) -> int:
+        if path in self._path_inode:
+            return self._path_inode[path]
+        inode = self._next_inode
+        self._next_inode += 1
+        self._inode_path[inode] = path
+        self._path_inode[path] = inode
+        return inode
+
+    def reset_stats(self) -> None:
+        with self._lock:
+            self.read_bytes = 0
+            self.read_calls = 0
+
+    def get_stats(self) -> dict[str, int]:
+        with self._lock:
+            return {"bytes": self.read_bytes, "calls": self.read_calls}
+
+    # ---- FUSE ops ----------------------------------------------------------
+    async def getattr(self, inode, ctx=None):
+        path = self._get_path(inode)
+        if path is None:
+            raise pyfuse3.FUSEError(errno.ENOENT)
+        try:
+            st = os.lstat(path)
+        except OSError as exc:
+            raise pyfuse3.FUSEError(exc.errno)
+        entry = pyfuse3.EntryAttributes()
+        entry.st_ino = inode
+        entry.st_mode = st.st_mode
+        entry.st_nlink = st.st_nlink
+        entry.st_uid = st.st_uid
+        entry.st_gid = st.st_gid
+        entry.st_size = st.st_size
+        entry.st_atime_ns = int(st.st_atime * 1e9)
+        entry.st_mtime_ns = int(st.st_mtime * 1e9)
+        entry.st_ctime_ns = int(st.st_ctime * 1e9)
+        entry.st_blksize = 512
+        entry.st_blocks = (st.st_size + 511) // 512
+        return entry
+
+    async def lookup(self, parent_inode, name, ctx=None):
+        parent_path = self._get_path(parent_inode)
+        if parent_path is None:
+            raise pyfuse3.FUSEError(errno.ENOENT)
+        name = name.decode("utf-8") if isinstance(name, bytes) else name
+        path = os.path.join(parent_path, name)
+        if not os.path.exists(path):
+            raise pyfuse3.FUSEError(errno.ENOENT)
+        inode = self._get_or_create_inode(path)
+        return await self.getattr(inode)
+
+    async def opendir(self, inode, ctx):
+        path = self._get_path(inode)
+        if path is None or not os.path.isdir(path):
+            raise pyfuse3.FUSEError(errno.ENOENT)
+        return inode
+
+    async def readdir(self, inode, start_id, token):
+        path = self._get_path(inode)
+        if path is None:
+            raise pyfuse3.FUSEError(errno.ENOENT)
+        entries = list(os.listdir(path))
+        for i, name in enumerate(entries[start_id:], start=start_id):
+            child_path = os.path.join(path, name)
+            child_inode = self._get_or_create_inode(child_path)
+            attr = await self.getattr(child_inode)
+            if not pyfuse3.readdir_reply(token, name.encode(), attr, i + 1):
+                break
+
+    async def open(self, inode, flags, ctx):
+        path = self._get_path(inode)
+        if path is None:
+            raise pyfuse3.FUSEError(errno.ENOENT)
+        fd = os.open(path, flags)
+        # Key by fd (not inode) so concurrent opens of the same file
+        # each get their own entry and don't overwrite each other.
+        self._fd_map[fd] = fd
+        return pyfuse3.FileInfo(fh=fd, direct_io=True)
+
+    async def read(self, fh, offset, size):
+        fd = self._fd_map.get(fh)
+        if fd is None:
+            raise pyfuse3.FUSEError(errno.EBADF)
+        os.lseek(fd, offset, os.SEEK_SET)
+        data = os.read(fd, size)
+        with self._lock:
+            self.read_bytes += len(data)
+            self.read_calls += 1
+        return data
+
+    async def release(self, fh):
+        fd = self._fd_map.pop(fh, None)
+        if fd is not None:
+            os.close(fd)

tensorcodec-0.1.4/benchmarks/decoders/__init__.py

@@ -0,0 +1,85 @@
+"""Decoder implementations for benchmarks.
+
+The registry maps decoder names to either *classes* (instantiated with no
+args) or *pre-built instances* (used as-is).  This allows parameterised
+decoders like TorchCodec to expose multiple configurations.
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+from benchmarks.decoders.tensorcodec_decoder import TensorCodecDecoder
+from benchmarks.protocol import VideoDecoderProtocol
+
+# Values are either a class (called with no args) or a ready instance.
+_Entry = Union[type[VideoDecoderProtocol], VideoDecoderProtocol]
+
+DECODERS: dict[str, _Entry] = {
+    "tensorcodec": TensorCodecDecoder,
+}
+
+# Optional decoders — register only when the library is importable.
+try:
+    from benchmarks.decoders.torchcodec_decoder import TORCHCODEC_CONFIGS
+
+    for _cfg in TORCHCODEC_CONFIGS:
+        DECODERS[_cfg.name] = _cfg
+except ImportError:
+    pass
+
+try:
+    import torch as _torch
+
+    if _torch.cuda.is_available():
+        from benchmarks.decoders.torchcodec_decoder import TORCHCODEC_GPU_CONFIGS
+
+        for _cfg in TORCHCODEC_GPU_CONFIGS:
+            DECODERS[_cfg.name] = _cfg
+except ImportError:
+    pass
+
+try:
+    from benchmarks.decoders.decord_decoder import DecordDecoder
+
+    DECODERS["decord"] = DecordDecoder
+except ImportError:
+    pass
+
+try:
+    from benchmarks.decoders.opencv_decoder import OpenCVDecoder
+
+    DECODERS["opencv"] = OpenCVDecoder
+except ImportError:
+    pass
+
+try:
+    from benchmarks.decoders.torchvision_decoder import (
+        TorchVisionPyAVDecoder,
+        TorchVisionVideoReaderDecoder,
+        available_backends,
+    )
+
+    _tv_backends = available_backends()
+    if "pyav" in _tv_backends:
+        DECODERS["torchvision-pyav"] = TorchVisionPyAVDecoder
+    if "video_reader" in _tv_backends:
+        DECODERS["torchvision-video_reader"] = TorchVisionVideoReaderDecoder
+except ImportError:
+    pass
+
+
+def get_decoder(name: str) -> VideoDecoderProtocol:
+    """Return a decoder by name (instantiating if needed)."""
+    if name not in DECODERS:
+        available = ", ".join(DECODERS.keys())
+        raise ValueError(f"Unknown decoder: {name}. Available: {available}")
+    entry = DECODERS[name]
+    if isinstance(entry, type):
+        return entry()
+    return entry  # already an instance
+
+
+def list_available_decoders() -> list[str]:
+    """Return names of all importable decoders."""
+    return list(DECODERS.keys())

tensorcodec-0.1.4/benchmarks/decoders/decord_decoder.py

@@ -0,0 +1,50 @@
+"""Benchmark adapter for Decord.
+
+Requires ``decord`` to be installed.  The benchmark registry in
+``__init__.py`` catches the ``ImportError`` if it is missing.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import numpy as np
+from decord import VideoReader, cpu
+
+
+class DecordDecoder:
+    """Wraps :class:`decord.VideoReader` for the benchmark protocol."""
+
+    name = "decord"
+
+    def get_frames_played_at(self, video_path: str, seconds: List[float]) -> np.ndarray:
+        vr = VideoReader(video_path, ctx=cpu(0))
+        fps = vr.get_avg_fps()
+        # Convert timestamps to frame indices using playback-frame semantics:
+        # frame[i].pts <= timestamp < frame[i+1].pts
+        indices = [min(int(t * fps), len(vr) - 1) for t in seconds]
+        frames = vr.get_batch(indices).asnumpy()  # (N, H, W, C)
+        return np.transpose(frames, (0, 3, 1, 2))  # -> NCHW
+
+    def get_frames_played_in_range(
+        self,
+        video_path: str,
+        start_seconds: float,
+        stop_seconds: float,
+        fps: Optional[float] = None,
+    ) -> np.ndarray:
+        if fps is not None:
+            raise ValueError("DecordDecoder does not support the fps parameter")
+        vr = VideoReader(video_path, ctx=cpu(0))
+        avg_fps = vr.get_avg_fps()
+        start_idx = int(start_seconds * avg_fps)
+        stop_idx = min(int(stop_seconds * avg_fps), len(vr))
+        indices = list(range(start_idx, stop_idx))
+        if not indices:
+            return np.empty((0, 3, 0, 0), dtype=np.uint8)
+        frames = vr.get_batch(indices).asnumpy()  # (N, H, W, C)
+        return np.transpose(frames, (0, 3, 1, 2))  # -> NCHW
+
+    def get_video_duration(self, video_path: str) -> float:
+        vr = VideoReader(video_path, ctx=cpu(0))
+        return len(vr) / vr.get_avg_fps()