iterframes 0.4.0__tar.gz → 0.6.0__tar.gz

iterframes-0.6.0/.github/scripts/check_site.py

@@ -0,0 +1,50 @@
+"""Check that every local reference in the landing page resolves to a file.
+
+The page has no build step, so nothing else would catch a renamed asset or a
+typo in a path until the deployed site showed a broken image.
+"""
+
+import re
+import sys
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+# href="...", src="..." and url(...) in CSS.
+REFERENCES = re.compile(
+    r"""(?:href|src)\s*=\s*["']([^"']+)["']|url\(\s*["']?([^"')]+)["']?\s*\)"""
+)
+
+
+def local(reference: str) -> bool:
+    parsed = urlparse(reference)
+    return not parsed.scheme and not parsed.netloc and bool(parsed.path)
+
+
+def main(root: Path) -> int:
+    missing = []
+    for source in sorted(root.rglob("*")):
+        if source.suffix not in {".html", ".css", ".js"}:
+            continue
+        text = source.read_text(encoding="utf-8")
+        for match in REFERENCES.finditer(text):
+            reference = match.group(1) or match.group(2)
+            if not local(reference):
+                continue
+            path = unquote(urlparse(reference).path)
+            if path in {"./", "."}:
+                continue
+            target = (source.parent / path).resolve()
+            if not target.exists():
+                line = text.count("\n", 0, match.start()) + 1
+                missing.append(f"{source}:{line}: {reference}")
+
+    for problem in missing:
+        print(f"missing: {problem}", file=sys.stderr)
+    if missing:
+        return 1
+    print(f"every local reference under {root} resolves")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(Path(sys.argv[1] if len(sys.argv) > 1 else "web")))

{iterframes-0.4.0 → iterframes-0.6.0}/.github/workflows/ci.yaml

@@ -8,11 +8,20 @@ name: CI
 # updates its release pull request, and merging that pull request creates
 # the tag and a draft GitHub release, then the jobs below attach the
 # wheels, publish them to PyPI, and publish the release.
+# The landing page has its own workflow, and nothing here builds it, so a
+# commit that only touches web/ skips the wheel matrix. release-please skips
+# with it, and picks those commits up on the next push that does build
+# something.
 on:
   push:
     branches:
       - main
+    paths-ignore: &page
+      - 'web/**'
+      - '.github/workflows/pages.yaml'
+      - '.github/scripts/check_site.py'
   pull_request:
+    paths-ignore: *page
   workflow_dispatch:
 
 permissions:
@@ -147,6 +156,75 @@ jobs:
           uv pip install --reinstall-package iterframes dist/*.whl
           uv run --no-sync pytest
 
+  windows:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: windows-2025
+            target: x64
+    defaults:
+      run:
+        # MSYS2 runs the FFmpeg build script; path-type inherit keeps MSVC,
+        # cargo, and uv on PATH, after MSYS2's own tools.
+        shell: msys2 {0}
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up MSVC
+        uses: ilammy/msvc-dev-cmd@v1
+        with:
+          arch: ${{ matrix.platform.target }}
+      - name: Set up MSYS2
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: UCRT64
+          path-type: inherit
+          # Native pkg-config and nasm; FFmpeg and dav1d compile with MSVC.
+          install: >-
+            make diffutils curl tar xz
+            mingw-w64-ucrt-x86_64-pkgconf
+            mingw-w64-ucrt-x86_64-nasm
+      - name: Remove MSYS2's link
+        # It would shadow MSVC's link.exe, for rustc among others.
+        run: rm -f /usr/bin/link.exe
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.1.0
+      - name: Install meson and ninja
+        # With a native Python, so that meson sees Windows and uses MSVC.
+        run: |
+          uv tool install meson
+          uv tool install ninja
+          echo "$(cygpath -u "$(uv tool dir --bin)")" >> "$GITHUB_PATH"
+      - name: Cache FFmpeg
+        uses: actions/cache@v6
+        with:
+          path: build/ffmpeg
+          key: ffmpeg-windows-${{ matrix.platform.target }}-${{ hashFiles('scripts/build-ffmpeg.sh') }}
+      - name: Build wheels
+        run: |
+          uv sync --frozen --no-install-project
+          uv run --no-sync maturin build --release --out dist
+      - name: Show the FFmpeg build log
+        if: failure()
+        run: |
+          tail -n 200 build/ffmpeg.log
+          cat build/ffmpeg/lib/pkgconfig/*.pc
+      - name: Upload wheels
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheels-windows-${{ matrix.platform.target }}
+          path: dist
+      - name: Run tests
+        run: |
+          for python in 3.11 3.14; do
+            uv sync --frozen --no-install-project --python $python
+            uv pip install --reinstall-package iterframes dist/*.whl
+            uv run --no-sync pytest
+          done
+      - name: Lint Rust
+        # The only job that compiles the Windows code paths.
+        run: cargo clippy --all-targets -- -D warnings
+
   sdist:
     runs-on: ubuntu-latest
     steps:
@@ -166,7 +244,7 @@ jobs:
     name: Attach to the GitHub release
     runs-on: ubuntu-latest
     if: ${{ needs.release-please.outputs.release_created == 'true' }}
-    needs: [release-please, lint, linux, macos, sdist]
+    needs: [release-please, lint, linux, macos, windows, sdist]
     permissions:
       # Used to sign the attestations
       id-token: write

iterframes-0.6.0/.github/workflows/pages.yaml

@@ -0,0 +1,61 @@
+# Publishes web/ to https://alesanfra.github.io/iterframes/.
+#
+# The page is plain HTML, CSS and JavaScript, so there is nothing to build:
+# the job uploads the directory and hands it to Pages. It runs only when
+# web/ changes, and ci.yaml ignores web/ for the same reason, so a change
+# to one never spends minutes on the other.
+#
+# Pages must be set to "GitHub Actions" under Settings > Pages for the
+# deployment to be accepted.
+name: Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths: &page
+      - 'web/**'
+      - '.github/workflows/pages.yaml'
+      - '.github/scripts/check_site.py'
+  pull_request:
+    paths: *page
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# One deployment at a time, and never cancel one halfway: a cancelled
+# deployment leaves the live site on the previous version.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  check:
+    name: Check the page
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Check every local link and asset resolves
+        run: python3 .github/scripts/check_site.py web
+
+  deploy:
+    name: Deploy to GitHub Pages
+    # Pull requests get the check above; only main is published.
+    if: ${{ github.event_name != 'pull_request' }}
+    needs: check
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: web
+      - id: deployment
+        uses: actions/deploy-pages@v5

iterframes-0.6.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.6.0"
+}

{iterframes-0.4.0 → iterframes-0.6.0}/AGENTS.md

@@ -17,7 +17,7 @@ decodes the next ones. Keep that true, and say so in the docs.
 
 The package uses maturin's mixed layout: the compiled module is installed
 as `iterframes.iterframes`, and `iterframes/__init__.py` wraps its
-`FrameReader` into `read` and `read_all`.
+`FrameReader` into `read` and `read_batches`.
 
 ## How decoding works
 
@@ -36,6 +36,31 @@ as `iterframes.iterframes`, and `iterframes/__init__.py` wraps its
   Python code holds it. Never attach to Python there (no `Python::attach`,
   no Python objects in `decoder.rs`); `test_benchmark.py` checks the
   overlap.
+- With `batch_size`, the thread allocates one `ffmpeg::Buffer` per batch
+  and swscale writes each frame into its slice (`Scaler::run_into`); the
+  batch is sent when full, or at the end of the video unless `drop_last`.
+  Python gets it as a `Batch`, a 4-dimensional buffer, with no copy. The
+  channel then holds batches: `prefetch_frames` rounds up to whole ones.
+- `frames`, or `start`, `stop`, and `step`, pick the frames to decode by
+  number. `start=0` with `step=1` is `Selection::First`, which reads the
+  video straight through and stops early, with no index and no seek: keep
+  that path, since it is the common one. Otherwise the thread indexes the
+  file first (`index` in
+  `src/decoder.rs`), demuxing every packet without decoding it to map each
+  frame to its timestamp and mark the key frames, and `Seeker` decodes each
+  frame asked for from the key frame before it, or goes on from the frame
+  it decoded last when that is closer, or when the stream does not seek. Frames passed on the way are never
+  converted to RGB. The index leaves out the frames before the first key
+  frame, which decoding cannot return either, so frame numbers are those of
+  a plain `read`. A stream that cannot seek, such as raw H.264, is opened
+  again and read from the start (`Source::open`).
+- `approximate` goes with `frames` only, and carries a tolerance in frames
+  (`True` is `usize::MAX`), in `Selection::Frames`. `selected` then maps
+  each index through `Seeker::nearest_key`, which snaps it to the key frame
+  closest to it when that is within the tolerance, and leaves it alone
+  otherwise. Nothing else changes: the index pass still runs, and two
+  indices that snap to the same key frame decode it once each, so the caller
+  gets one frame per number asked for.
 - Errors travel through the channel and become Python exceptions in
   `impl From<Error> for PyErr`. A closed channel means the end of the video.
 - Dropping the reader closes the channel; the thread notices on its next
@@ -54,32 +79,38 @@ as `iterframes.iterframes`, and `iterframes/__init__.py` wraps its
   as `AVERROR` are written by hand in the `sys` module of `src/ffmpeg.rs`.
 - The build disables autodetection, so the wheel depends on libc and
   system frameworks only; dav1d is added for AV1.
+- On Windows the script runs in MSYS2 but compiles with MSVC
+  (`--toolchain=msvc`, `-MD`), because the wheels target
+  `x86_64-pc-windows-msvc`; it copies each `libx.a` to `x.lib` for MSVC's
+  linker. `build.rs` finds `bash.exe` on `PATH` itself, since Rust would
+  otherwise pick WSL's from the system directory.
 - Keep the build LGPL: never pass `--enable-gpl` or `--enable-nonfree`.
 - Hardware decoding (`device="mps"` / `"cuda"`, PyTorch's names, mapped
   to FFmpeg's in `hardware_devices` in `src/lib.rs`): VideoToolbox on
-  macOS; on Linux the `*_cuvid`
-  decoders, which load the NVIDIA driver with dlopen and resize on the
-  GPU. Both add no library to the wheel. The macOS build needs clang's
+  macOS; on Linux and Windows
+  the `*_cuvid` decoders, which load the NVIDIA driver at run time and
+  resize on the GPU. Both add no library to the wheel. The macOS build needs clang's
   compiler-rt for `@available`, which `build.rs` links.
 - NVDEC has never run on a GPU in this project: CI has none, and the
   `cuda` tests skip when the device does not open. The same goes for
   `on_device=True` (`CudaFrame`, `Plane`, `src/dlpack.rs`), which waits on
-  cuvid's copy with CUDA driver calls found through dlopen
-  (`ffmpeg::cuda`).
+  cuvid's copy with CUDA driver calls found through dlopen, or
+  `LoadLibraryA` on Windows (`ffmpeg::cuda`).
 
 ## Layout
 
 | Path | Contents |
 | --- | --- |
-| `src/lib.rs` | PyO3 module: `Frame`, `FrameReader`, error mapping, module init |
+| `src/lib.rs` | PyO3 module: `Frame`, `Batch`, `FrameReader`, error mapping, module init |
 | `src/decoder.rs` | Decoding thread |
 | `src/ffmpeg.rs` | Safe wrappers over the FFmpeg calls the crate needs |
 | `src/dlpack.rs` | DLPack capsules for the planes of `CudaFrame` |
-| `iterframes/__init__.py` | `read`, `read_all` |
+| `iterframes/__init__.py` | `read`, `read_batches` |
 | `build.rs` | Builds and links FFmpeg, generates its bindings |
 | `scripts/build-ffmpeg.sh` | Static FFmpeg and dav1d, run by `build.rs` |
 | `tests/` | pytest suite; frames are compared with PyAV |
 | `docs/` | MkDocs site published on Read the Docs |
+| `web/` | Landing page published on GitHub Pages |
 
 ## Environment
 
@@ -110,7 +141,8 @@ uv run --no-sync pytest
 ```
 
 CI runs the same four, plus `ruff check .` and `ruff format --check .` for
-the Python files. `pre-commit run -a` covers the formatters and linters
+the Python files. Only the `windows` job compiles the `cfg(windows)`
+code, and runs clippy on it. `pre-commit run -a` covers the formatters and linters
 locally.
 
 ## Docs
@@ -121,6 +153,34 @@ built module; check them instead of writing them from memory. Keep the
 text short, in American English, with no performance claims that have not
 been measured.
 
+The landing page in `web/` is part of the docs: whenever an argument, a
+default, or the behavior of a feature changes, update it in the same
+change as the code, and say so in the pull request. Its diagrams are
+drawn from the numbers declared in `web/main.js`, so change the number
+and let the drawing and the captions follow; never write a figure into
+the HTML that the script also computes. `web/README.md` lists those
+numbers and the files. Check the result in a browser before proposing the
+change: open `web/index.html`, or serve the directory with
+`python3 -m http.server --directory web`. The page has no build step and no
+third-party request: its two typefaces are self-hosted woff2 files in
+`web/assets/fonts/`, and everything else is plain HTML, CSS, and JavaScript.
+`web/README.md` describes the look and the colour rules; keep them rather
+than restyling one component on its own.
+
+## Landing page
+
+`web/` is the page at
+[alesanfra.github.io/iterframes](https://alesanfra.github.io/iterframes/):
+plain HTML, CSS and JavaScript, no build step, no framework, no web fonts and
+no third-party script. `.github/workflows/pages.yaml` uploads the directory
+and runs only when it changes; `ci.yaml` ignores it, so neither spends minutes
+on the other. Its two animated diagrams are built from constants at the top of
+`main.js`, and their captions are computed from the same constants, so a
+number cannot appear in the drawing and the prose with two different values.
+`web/README.md` has the `ffmpeg` commands that made the images.
+
+Keep its claims to what the benchmarks measured, as in the docs.
+
 ## Conventions
 
 - Commits follow [Conventional Commits](https://www.conventionalcommits.org/),

{iterframes-0.4.0 → iterframes-0.6.0}/CHANGELOG.md

@@ -6,6 +6,26 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 From 0.4.0 on, [release-please](https://github.com/googleapis/release-please)
 writes each entry from the Conventional Commits since the previous release.
 
+## [0.6.0](https://github.com/alesanfra/iterframes/compare/v0.5.0...v0.6.0) (2026-09-20)
+
+
+### Features
+
+* read approximate frames ([#11](https://github.com/alesanfra/iterframes/issues/11)) ([2158899](https://github.com/alesanfra/iterframes/commit/2158899f72f73d69c0020236181e340bb8648fc1))
+
+## [0.5.0](https://github.com/alesanfra/iterframes/compare/v0.4.0...v0.5.0) (2026-09-20)
+
+
+### ⚠ BREAKING CHANGES
+
+* `read_all` is removed; use `list(iterframes.read(...))`.
+
+### Features
+
+* build wheels for Windows ([#4](https://github.com/alesanfra/iterframes/issues/4)) ([39702a5](https://github.com/alesanfra/iterframes/commit/39702a5b55333824956827c5cf23b50cf150fb22))
+* read frames by number, in the style of decord ([#10](https://github.com/alesanfra/iterframes/issues/10)) ([6d0627e](https://github.com/alesanfra/iterframes/commit/6d0627e65d357667ba28f274c780c3a58da541cb))
+* read frames in batches with read_batches ([#6](https://github.com/alesanfra/iterframes/issues/6)) ([136ae14](https://github.com/alesanfra/iterframes/commit/136ae14ad6cccfa3459f69518a610dd94957d4c1))
+
 ## [0.4.0](https://github.com/alesanfra/iterframes/compare/v0.3.0...v0.4.0) (2026-09-19)
 
 The rewrite: static FFmpeg wheels, frames without copies, and hardware

{iterframes-0.4.0 → iterframes-0.6.0}/Cargo.lock

@@ -96,7 +96,7 @@ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
 [[package]]
 name = "iterframes"
-version = "0.4.0"
+version = "0.6.0"
 dependencies = [
  "bindgen",
  "crossbeam-channel",

{iterframes-0.4.0 → iterframes-0.6.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "iterframes"
-version = "0.4.0"
+version = "0.6.0"
 edition = "2024"
 rust-version = "1.89"
 description = "Iterate over the frames of a video as NumPy arrays, decoded on a background thread while you process them"

iterframes-0.6.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: iterframes
+Version: 0.6.0
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Multimedia :: Video
+Requires-Dist: numpy>=1.21
+License-File: LICENSE
+Summary: Iterate over the frames of a video as NumPy arrays, decoded on a background thread while you process them
+Keywords: video,decoder,ffmpeg,frames,numpy,video-reader,pytorch,deep-learning,computer-vision,nvdec,videotoolbox
+Home-Page: https://github.com/alesanfra/iterframes
+Author-email: Alessio Sanfratello <sanfra90@gmail.com>
+License-Expression: LGPL-3.0-only
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/alesanfra/iterframes/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://iterframes.readthedocs.io
+Project-URL: Homepage, https://github.com/alesanfra/iterframes
+Project-URL: Issues, https://github.com/alesanfra/iterframes/issues
+Project-URL: Source, https://github.com/alesanfra/iterframes
+
+# iterframes
+
+[![PyPI](https://img.shields.io/pypi/v/iterframes.svg)](https://pypi.org/project/iterframes/)
+[![CI](https://github.com/alesanfra/iterframes/actions/workflows/ci.yaml/badge.svg)](https://github.com/alesanfra/iterframes/actions/workflows/ci.yaml)
+[![Documentation](https://readthedocs.org/projects/iterframes/badge/?version=latest)](https://iterframes.readthedocs.io)
+
+**Video frames as NumPy arrays, decoded while your code is busy with the
+last one.**
+
+```python
+import iterframes
+
+for frame in iterframes.read("video.mp4", height=224, width=224):
+    model(frame)  # (224, 224, 3) uint8 RGB, resized by FFmpeg, no copy
+```
+
+`model` runs on one frame while a Rust thread decodes the next ones. That
+thread never takes the GIL, so decoding overlaps with your work instead of
+adding to it, even when your code is pure Python. `pip install iterframes`
+brings FFmpeg with it: nothing else to install, no system packages, no
+`ffmpeg` binary to call.
+
+The landing page at
+[alesanfra.github.io/iterframes](https://alesanfra.github.io/iterframes/)
+shows what the decoder does while your loop runs. The documentation is at
+[iterframes.readthedocs.io](https://iterframes.readthedocs.io): the
+[reference](https://iterframes.readthedocs.io/en/latest/reference/)
+documents every argument and error, and the
+[development guide](https://iterframes.readthedocs.io/en/latest/development/)
+covers building from source.
+
+## Numbers
+
+One video, 901 frames of 480x270 H.264, decoded and converted to RGB,
+best of seven runs on an Apple silicon Mac with the bundled FFmpeg 9.0.2.
+The benchmarks are in
+[`tests/test_benchmark.py`](https://github.com/alesanfra/iterframes/blob/main/tests/test_benchmark.py);
+run them on your own videos before believing them.
+
+| | Time |
+| --- | --- |
+| Every frame, iterframes | **0.046 s** |
+| Every frame, PyAV, same decode and conversion | 0.208 s |
+| 32 frames at random positions | 0.036 s |
+| First 10 frames (`stop=10`) | 0.003 s |
+| Second half (`start=450`) | 0.028 s |
+
+In the overlap benchmark, which upscales the same video to 1080p, adding
+per-frame work as expensive as decoding took 16% longer in total, not
+twice as long: the decoding had already happened.
+
+## What you get
+
+- **Frames without copies.** RGB `uint8` arrays of shape
+  `(height, width, 3)`, straight out of FFmpeg's buffers.
+- **Batches as one array.** `read_batches` decodes into a single
+  `(batch, height, width, 3)` block, ready for a model.
+- **Resizing while decoding**, not a `cv2.resize` afterwards.
+- **Random access.** Read frames by number, without decoding the rest.
+- **Hardware decoding** on NVIDIA GPUs (NVDEC) and Apple silicon
+  (VideoToolbox), in the wheels. On NVIDIA the frames can stay on the GPU
+  for PyTorch.
+- **Wheels** for Linux (x86_64, aarch64), macOS (Apple silicon), and
+  Windows, for every CPython from 3.11 on.
+
+```python
+# Batches of 12 frames, decoded into one (12, 224, 224, 3) array
+for batch in iterframes.read_batches("video.mp4", 12, height=224, width=224):
+    ...
+
+# Stop whenever you like; the decoder stops with the loop
+for index, frame in enumerate(iterframes.read("video.mp4")):
+    if index == 100:
+        break
+```
+
+## Random access
+
+Sample clips for training, or grab a thumbnail, without reading the whole
+file:
+
+```python
+clip = list(iterframes.read("video.mp4", frames=[0, 30, 60]))
+every_fifth = iterframes.read("video.mp4", start=100, stop=200, step=5)
+last = next(iterframes.read("video.mp4", frames=[-1]))
+```
+
+Both work with `read_batches`. Negative numbers count from the end, and
+frame `n` is the one `read` yields `n`-th. iterframes indexes the file
+once, without decoding it, then decodes each frame from the key frame
+before it; frames asked for in order cost no more than reading the video
+straight through. See
+[Reading frames by number](https://iterframes.readthedocs.io/en/latest/reference/#reading-frames-by-number).
+
+When a frame nearby will do, `approximate` reads the key frame closest to
+each of `frames`, which costs one decoded frame instead of the frames from
+the key frame on:
+
+```python
+# The nearest key frame within 5 frames, else the frame itself.
+frames = list(iterframes.read("video.mp4", frames=[100, 200, 300], approximate=5))
+```
+
+See [Approximate frames](https://iterframes.readthedocs.io/en/latest/reference/#approximate-frames).
+
+## Hardware decoding
+
+Pass `device` to decode on a GPU instead of the CPU, which then stays free
+for your model. The names are PyTorch's:
+
+```python
+# NVIDIA GPU on Linux and Windows; with height and width, the GPU resizes too
+for frame in iterframes.read("video.mp4", height=224, width=224, device="cuda"):
+    ...
+
+# Apple silicon (VideoToolbox)
+for frame in iterframes.read("video.mp4", device="mps"):
+    ...
+
+# Whatever the machine has, else the CPU
+for frame in iterframes.read("video.mp4", device="auto"):
+    ...
+
+print(iterframes.DEVICES)  # ('cpu', 'mps') on a Mac
+```
+
+The frames still arrive as NumPy arrays in memory. A GPU saves CPU time
+but is not always faster than the CPU decoder, so measure both; see
+[Hardware decoding](https://iterframes.readthedocs.io/en/latest/reference/#hardware-decoding).
+
+With an NVIDIA GPU, `on_device=True` keeps the frames on it, in NV12, for
+PyTorch and other libraries to take without a copy:
+
+```python
+import torch
+
+for frame in iterframes.read("video.mp4", device="cuda", on_device=True):
+    y = torch.from_dlpack(frame.y)    # (height, width) uint8, on the GPU
+    uv = torch.from_dlpack(frame.uv)  # (height / 2, width / 2, 2)
+```
+
+[Frames on the GPU](https://iterframes.readthedocs.io/en/latest/reference/#frames-on-the-gpu) shows how to
+convert them to RGB there.
+
+## Compared with OpenCV, decord, and PyAV
+
+| | iterframes | OpenCV `VideoCapture` | decord | PyAV |
+| --- | --- | --- | --- | --- |
+| Decoding runs | Ahead of your code, on a background thread | When you call `read()` | When you index the reader | When you ask for the next frame |
+| Pixels | RGB | BGR | RGB | Any format FFmpeg supports |
+| Resize while decoding | Yes | No, with `cv2.resize` after | Yes | Yes, with `reformat` |
+| Batches as one array | Yes, `read_batches` | No | Yes, `get_batch` | No |
+| Seeking and random access | Yes, `frames=[...]` or `start`, `stop`, `step` | Yes | Yes, fast | Yes |
+| Audio, encoding, muxing | No | Encoding with `VideoWriter` | Audio reading | Yes |
+| Hardware decoding | NVIDIA, Apple silicon, in the wheels | Depends on the build and backend | NVIDIA, when built from source | Depends on the build |
+| Latest wheels | Linux, macOS, Windows, CPython 3.11+ | Linux, macOS, Windows | x86_64 only, last release in 2021 | Linux, macOS, Windows |
+
+Pick iterframes to read videos into a model, in order or by frame number,
+and keep decoding out of your loop's way. Pick PyAV when you need the rest
+of FFmpeg: audio, encoding, streams, or precise control over the decoder.
+OpenCV is the natural choice when the rest of the pipeline already uses
+it.
+
+## Installation
+
+```console
+pip install iterframes
+```
+
+The wheels bundle FFmpeg and work on any CPython from 3.11 on, on Linux
+(x86_64, aarch64), macOS (Apple silicon), and Windows (x86_64). Other
+platforms build from source, FFmpeg included.
+
+## Contributing
+
+Contributions are welcome. The
+[development guide](https://iterframes.readthedocs.io/en/latest/development/#help-wanted)
+lists features that are waiting for someone to build them.
+
+## License
+
+iterframes is released under the [LGPL-3.0](https://github.com/alesanfra/iterframes/blob/main/LICENSE). The wheels include
+[FFmpeg](https://ffmpeg.org/), built under the LGPL, and
+[dav1d](https://code.videolan.org/videolan/dav1d), under the BSD 2-clause
+license.
+