iterframes 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -147,6 +147,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 +235,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.5.0/.release-please-manifest.json

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

{iterframes-0.4.0 → iterframes-0.5.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,24 @@ 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`).
 - 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,28 +72,33 @@ 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 |
@@ -110,7 +133,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

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

@@ -6,6 +6,19 @@ 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.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.5.0}/Cargo.lock

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

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

@@ -1,6 +1,6 @@
 [package]
 name = "iterframes"
-version = "0.4.0"
+version = "0.5.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.5.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: iterframes
+Version: 0.5.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 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).
+
+## 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.
+

iterframes-0.5.0/README.md

@@ -0,0 +1,172 @@
+# 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 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).
+
+## 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.

{iterframes-0.4.0 → iterframes-0.5.0}/build.rs

@@ -52,7 +52,7 @@ fn build_ffmpeg(script: &Path, prefix: &Path) {
     lock.lock().expect("cannot lock the FFmpeg build");
 
     let log = prefix.with_extension("log");
-    let status = Command::new("bash")
+    let status = Command::new(bash())
         .arg(script)
         .arg(prefix)
         .stdout(File::create(&log).expect("cannot create the build log"))
@@ -88,6 +88,22 @@ fn build_ffmpeg(script: &Path, prefix: &Path) {
     }
 }
 
+/// The shell that runs the build script. On Windows, Rust looks for a bare
+/// `bash` in the system directory before `PATH`, and would find WSL's
+/// there instead of MSYS2's.
+fn bash() -> PathBuf {
+    if cfg!(windows) {
+        let path = env::var_os("PATH").unwrap_or_default();
+        if let Some(bash) = env::split_paths(&path)
+            .map(|dir| dir.join("bash.exe"))
+            .find(|bash| bash.is_file())
+        {
+            return bash;
+        }
+    }
+    PathBuf::from("bash")
+}
+
 /// Link the static libraries and return their include paths.
 fn link_ffmpeg(prefix: &Path) -> Vec<PathBuf> {
     // SAFETY: the build script is single-threaded.