iterframes 0.6.0__tar.gz → 0.7.0__tar.gz

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

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

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

@@ -61,6 +61,11 @@ as `iterframes.iterframes`, and `iterframes/__init__.py` wraps its
   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.
+- `interpolation` picks the `SWS_*` flag of the `Scaler`
+  (`ffmpeg::Interpolation`); `None` is `SWS_BILINEAR`. A named one also
+  turns off the `resize` option of the `*_cuvid` decoders
+  (`resize_on_device` in `Source`), so the CPU resizes what the GPU
+  decoded, since NVIDIA's method cannot be chosen.
 - 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
@@ -85,6 +90,10 @@ as `iterframes.iterframes`, and `iterframes/__init__.py` wraps its
   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`.
+- iterframes itself is Apache-2.0. The wheels carry the licenses of what
+  they bundle, listed in `NOTICE` with their texts in `licenses/`: when a
+  version in `scripts/build-ffmpeg.sh` changes, or a library is added,
+  update both.
 - Hardware decoding (`device="mps"` / `"cuda"`, PyTorch's names, mapped
   to FFmpeg's in `hardware_devices` in `src/lib.rs`): VideoToolbox on
   macOS; on Linux and Windows
@@ -147,11 +156,14 @@ locally.
 
 ## Docs
 
-Three pages: `index.md` (overview), `reference.md` (API and errors),
-`development.md`. Every example must match the behavior of a freshly
-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.
+Four pages: `index.md` (overview and quick start), `guides.md` (what the
+arguments are for, and what they cost), `api.md` (signatures, arguments,
+and errors), `development.md`. `scripts/docs_redirects.py` sends links to
+the old `reference/` page, anchors included, to the page that now holds
+each section; add to it when a section moves. Every example must match
+the behavior of a freshly 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

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

@@ -6,6 +6,13 @@ 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.7.0](https://github.com/alesanfra/iterframes/compare/v0.6.0...v0.7.0) (2026-09-29)
+
+
+### Features
+
+* choose how frames are resized with interpolation ([#15](https://github.com/alesanfra/iterframes/issues/15)) ([6317322](https://github.com/alesanfra/iterframes/commit/63173220228303d0ca508e00037260ffe272b69c))
+
 ## [0.6.0](https://github.com/alesanfra/iterframes/compare/v0.5.0...v0.6.0) (2026-09-20)
 
 

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

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

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

@@ -1,12 +1,12 @@
 [package]
 name = "iterframes"
-version = "0.6.0"
+version = "0.7.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"
 homepage = "https://github.com/alesanfra/iterframes"
 repository = "https://github.com/alesanfra/iterframes"
-license = "LGPL-3.0-only"
+license = "Apache-2.0"
 publish = false
 readme = "README.md"
 

iterframes-0.7.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

iterframes-0.7.0/NOTICE

@@ -0,0 +1,19 @@
+iterframes
+Copyright 2020 Alessio Sanfratello
+
+This product is licensed under the Apache License, Version 2.0, found in
+the LICENSE file.
+
+The wheels also include software by third parties, under their own
+licenses, whose texts are in the licenses directory:
+
+- FFmpeg 9.0.2 (https://ffmpeg.org/), under the GNU Lesser General
+  Public License, version 2.1 or later: licenses/FFmpeg-LGPL-2.1.txt.
+  It is built without its GPL and nonfree parts. Its source and the
+  script that builds it, scripts/build-ffmpeg.sh, are available, so that
+  it can be modified, rebuilt, and relinked.
+- dav1d 1.5.4 (https://code.videolan.org/videolan/dav1d), under the BSD
+  2-clause license: licenses/dav1d-BSD-2-Clause.txt.
+- nv-codec-headers 13.0.19.0 (https://github.com/FFmpeg/nv-codec-headers),
+  in the Linux and Windows wheels only, under the MIT license:
+  licenses/nv-codec-headers-MIT.txt.

{iterframes-0.6.0 → iterframes-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iterframes
-Version: 0.6.0
+Version: 0.7.0
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: Implementation :: CPython
@@ -8,11 +8,15 @@ Classifier: Programming Language :: Rust
 Classifier: Topic :: Multimedia :: Video
 Requires-Dist: numpy>=1.21
 License-File: LICENSE
+License-File: NOTICE
+License-File: licenses/FFmpeg-LGPL-2.1.txt
+License-File: licenses/dav1d-BSD-2-Clause.txt
+License-File: licenses/nv-codec-headers-MIT.txt
 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
+License-Expression: Apache-2.0
 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
@@ -47,8 +51,8 @@ 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
+[guides](https://iterframes.readthedocs.io/en/latest/guides/) explain the features, the
+[API](https://iterframes.readthedocs.io/en/latest/api/) documents every argument and error, and the
 [development guide](https://iterframes.readthedocs.io/en/latest/development/)
 covers building from source.
 
@@ -78,7 +82,8 @@ twice as long: the decoding had already happened.
   `(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.
+- **Resizing while decoding**, not a `cv2.resize` afterwards, from
+  nearest to Lanczos.
 - **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
@@ -113,7 +118,7 @@ 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).
+[Reading frames by number](https://iterframes.readthedocs.io/en/latest/guides/#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
@@ -124,7 +129,7 @@ the key frame on:
 frames = list(iterframes.read("video.mp4", frames=[100, 200, 300], approximate=5))
 ```
 
-See [Approximate frames](https://iterframes.readthedocs.io/en/latest/reference/#approximate-frames).
+See [Approximate frames](https://iterframes.readthedocs.io/en/latest/guides/#approximate-frames).
 
 ## Hardware decoding
 
@@ -149,7 +154,7 @@ 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).
+[Hardware decoding](https://iterframes.readthedocs.io/en/latest/guides/#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:
@@ -162,7 +167,7 @@ for frame in iterframes.read("video.mp4", device="cuda", on_device=True):
     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
+[Frames on the GPU](https://iterframes.readthedocs.io/en/latest/guides/#frames-on-the-gpu) shows how to
 convert them to RGB there.
 
 ## Compared with OpenCV, decord, and PyAV
@@ -202,8 +207,11 @@ 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
+iterframes is released under the [Apache License 2.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.
+license. They are listed in
+[`NOTICE`](https://github.com/alesanfra/iterframes/blob/main/NOTICE), with
+their license texts in
+[`licenses/`](https://github.com/alesanfra/iterframes/tree/main/licenses).
 

{iterframes-0.6.0 → iterframes-0.7.0}/README.md

@@ -24,8 +24,8 @@ 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
+[guides](https://iterframes.readthedocs.io/en/latest/guides/) explain the features, the
+[API](https://iterframes.readthedocs.io/en/latest/api/) documents every argument and error, and the
 [development guide](https://iterframes.readthedocs.io/en/latest/development/)
 covers building from source.
 
@@ -55,7 +55,8 @@ twice as long: the decoding had already happened.
   `(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.
+- **Resizing while decoding**, not a `cv2.resize` afterwards, from
+  nearest to Lanczos.
 - **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
@@ -90,7 +91,7 @@ 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).
+[Reading frames by number](https://iterframes.readthedocs.io/en/latest/guides/#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
@@ -101,7 +102,7 @@ the key frame on:
 frames = list(iterframes.read("video.mp4", frames=[100, 200, 300], approximate=5))
 ```
 
-See [Approximate frames](https://iterframes.readthedocs.io/en/latest/reference/#approximate-frames).
+See [Approximate frames](https://iterframes.readthedocs.io/en/latest/guides/#approximate-frames).
 
 ## Hardware decoding
 
@@ -126,7 +127,7 @@ 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).
+[Hardware decoding](https://iterframes.readthedocs.io/en/latest/guides/#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:
@@ -139,7 +140,7 @@ for frame in iterframes.read("video.mp4", device="cuda", on_device=True):
     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
+[Frames on the GPU](https://iterframes.readthedocs.io/en/latest/guides/#frames-on-the-gpu) shows how to
 convert them to RGB there.
 
 ## Compared with OpenCV, decord, and PyAV
@@ -179,7 +180,10 @@ 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
+iterframes is released under the [Apache License 2.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.
+license. They are listed in
+[`NOTICE`](https://github.com/alesanfra/iterframes/blob/main/NOTICE), with
+their license texts in
+[`licenses/`](https://github.com/alesanfra/iterframes/tree/main/licenses).

iterframes-0.7.0/docs/api.md

@@ -0,0 +1,151 @@
+# API
+
+Everything lives in the top-level `iterframes` module.
+
+## read
+
+```python
+read(path, height=None, width=None, prefetch_frames=1, device="cpu", on_device=False, frames=None, start=0, stop=None, step=1, approximate=None, interpolation=None) -> Iterator[numpy.ndarray]
+```
+
+Yields the frames of the video at `path`, in order, or with `frames`, or
+`start`, `stop`, and `step`, only those frames, in the order asked for.
+Each frame is a C-contiguous, writable `numpy.ndarray` of shape
+`(height, width, 3)` and dtype `uint8`, holding RGB pixels.
+
+| Argument | Description |
+| --- | --- |
+| `path` | Path of the video, as a `str` or `os.PathLike` |
+| `height` | Height of the frames. Defaults to the height of the video |
+| `width` | Width of the frames. Defaults to the width of the video |
+| `prefetch_frames` | How many decoded frames may wait for your code. Defaults to 1 |
+| `device` | Where to decode: `"cpu"`, `"auto"`, or a name from `DEVICES`. Defaults to `"cpu"`. See [Hardware decoding](guides.md#hardware-decoding) |
+| `on_device` | With `device="cuda"`, yield `CudaFrame` objects left on the GPU instead of arrays. See [Frames on the GPU](guides.md#frames-on-the-gpu) |
+| `frames` | The numbers of the frames to read, in the order to read them. See [Reading frames by number](guides.md#reading-frames-by-number) |
+| `start`, `stop`, `step` | The frames to read, as a slice of the video |
+| `approximate` | With `frames`, read the key frame nearest to each of them instead, when it is within this many frames. `True` is any distance. See [Approximate frames](guides.md#approximate-frames) |
+| `interpolation` | How frames are resized: `"nearest"`, `"bilinear"`, `"bicubic"`, `"area"`, or `"lanczos"`. Defaults to bilinear on the CPU. See [Resizing](guides.md#resizing) |
+
+Frames are resized with bilinear interpolation, unless `interpolation`
+says otherwise. When only one of `height`
+and `width` is given, the other keeps the size of the video, so the aspect
+ratio changes.
+
+Decoding starts when the first frame is requested, on a background thread
+that runs ahead of your code by up to `prefetch_frames` frames. The thread
+never takes the GIL, so it decodes the next frames while your code
+processes the current one, even when that code holds the GIL. A larger
+`prefetch_frames` smooths out frames that take longer to decode, at the
+cost of memory: one 1080p frame takes about 6 MB.
+
+The decoder stops when the iterator is exhausted or garbage-collected, for
+example after a `break`.
+
+```python
+import iterframes
+
+for frame in iterframes.read("video.mp4", height=270, width=480):
+    print(frame.shape)  # (270, 480, 3)
+```
+
+## read_batches
+
+```python
+read_batches(path, batch_size, height=None, width=None, prefetch_frames=1, device="cpu", drop_last=False, frames=None, start=0, stop=None, step=1, approximate=None, interpolation=None) -> Iterator[numpy.ndarray]
+```
+
+Yields the frames of the video in batches, in order, for models that take
+several frames at once. Each batch is a C-contiguous, writable
+`numpy.ndarray` of shape `(batch_size, height, width, 3)` and dtype
+`uint8`. The frames are decoded straight into it, so unlike `numpy.stack`
+over the frames of `read`, making a batch costs your code no copy.
+
+| Argument | Description |
+| --- | --- |
+| `batch_size` | Frames per batch, at least 1 |
+| `prefetch_frames` | How many decoded frames may wait for your code, rounded up to whole batches. Defaults to 1, that is one batch |
+| `drop_last` | Drop the last batch when the video ends before it is full. By default it is yielded with the frames left over |
+
+The other arguments are those of [`read`](#read); `on_device` is not
+supported. Every frame of a batch has the size of the first frame of the
+video, or `height` and `width`.
+
+```python
+for batch in iterframes.read_batches("video.mp4", 12, height=224, width=224):
+    print(batch.shape)  # (12, 224, 224, 3), except maybe the last one
+```
+
+## Errors
+
+Errors are raised by the first `next()` on the iterator, not by the call
+to `read`, because decoding starts only then.
+
+| Exception | When |
+| --- | --- |
+| `FileNotFoundError`, `PermissionError`, `OSError` | The file cannot be opened. The exception carries `errno` and `filename` |
+| `ValueError` | The file is not a video FFmpeg can read, or has no video stream |
+| `RuntimeError` | Decoding fails after the video has been opened, for instance on a codec that the build does not include |
+| `IndexError` | `frames` asks for a frame the video does not have |
+
+```python
+try:
+    frames = list(iterframes.read("missing.mp4"))
+except FileNotFoundError as error:
+    print(error.filename)  # missing.mp4
+```
+
+## FrameReader
+
+```python
+FrameReader(path, height=None, width=None, prefetch_frames=1, device="cpu", on_device=False, batch_size=None, drop_last=False, frames=None, start=0, stop=None, step=1, approximate=None, interpolation=None)
+```
+
+The iterator behind `read` and `read_batches`. It yields `Frame` objects,
+`CudaFrame` objects with `on_device=True`, or `Batch` objects with
+`batch_size`.
+
+## Frame
+
+A decoded frame. It holds the pixels and exposes them through the buffer
+protocol as a writable, C-contiguous `(height, width, 3)` block of
+unsigned bytes, so that other libraries can read them without a copy:
+
+```python
+import numpy as np
+from iterframes import FrameReader
+
+for frame in FrameReader("video.mp4"):
+    array = np.asarray(frame)   # what read() yields
+    view = memoryview(frame)    # no NumPy needed
+```
+
+The pixels stay alive as long as the frame or any array or view on it.
+See [Frames without a copy](guides.md#frames-without-a-copy).
+
+## Batch
+
+Frames decoded into a single block of memory, which the buffer protocol
+exposes as a writable, C-contiguous `(frames, height, width, 3)` block of
+unsigned bytes. `read_batches` wraps it with `numpy.asarray`, which copies
+nothing; its pixels stay alive as long as the batch or any array or view on
+it.
+
+## Constants
+
+| Name | Value |
+| --- | --- |
+| `__version__` | Version of iterframes, such as `"0.4.0"` |
+| `FFMPEG_VERSION` | Version of the FFmpeg that iterframes is linked to, such as `"9.0.2"` |
+| `DEVICES` | Names accepted by `device` besides `"auto"`, such as `("cpu", "mps")` |
+
+## Types
+
+For type checkers, `iterframes.Device` and `iterframes.Interpolation` are
+the `Literal` types of `device` and `interpolation`:
+
+```python
+Device = Literal["cpu", "mps", "cuda", "auto"]
+Interpolation = Literal["nearest", "bilinear", "bicubic", "area", "lanczos"]
+```
+
+`Device` lists every name, while `DEVICES` lists those this platform has.