iterframes 0.5.0__cp311-abi3-win_amd64.whl

iterframes/__init__.py

@@ -0,0 +1,149 @@
+"""Iterate over the frames of a video as NumPy arrays.
+
+The frames are decoded on a background thread that never takes the GIL,
+so the next ones are decoded while your code processes the current one.
+"""
+
+import os
+from typing import Iterator, Optional, Sequence, Union
+
+import numpy as np
+
+from .iterframes import (
+    DEVICES,
+    FFMPEG_VERSION,
+    Batch,
+    CudaFrame,
+    Frame,
+    FrameReader,
+    Plane,
+    __version__,
+)
+
+__all__ = [
+    "DEVICES",
+    "Batch",
+    "FFMPEG_VERSION",
+    "CudaFrame",
+    "Frame",
+    "FrameReader",
+    "Plane",
+    "__version__",
+    "read",
+    "read_batches",
+]
+
+PathLike = Union[str, "os.PathLike[str]"]
+
+
+def read(
+    path: PathLike,
+    height: Optional[int] = None,
+    width: Optional[int] = None,
+    prefetch_frames: int = 1,
+    device: str = "cpu",
+    on_device: bool = False,
+    frames: Optional[Sequence[int]] = None,
+    start: int = 0,
+    stop: Optional[int] = None,
+    step: int = 1,
+) -> Iterator[Union[np.ndarray, CudaFrame]]:
+    """Yield the frames of the video at ``path``, in order.
+
+    With ``frames``, or ``start``, ``stop``, and ``step``, only those
+    frames are read, in the order asked for.
+
+    Each frame is a ``(height, width, 3)`` array of ``uint8`` RGB pixels.
+    ``height`` and ``width`` resize the frames; when only one is given, the
+    other keeps the size of the video. While your code processes a frame, a
+    background thread decodes up to ``prefetch_frames`` frames ahead of it,
+    without taking the GIL.
+
+    ``device`` is where to decode, named as in PyTorch: ``"cpu"``,
+    ``"mps"`` (Apple's VideoToolbox), or ``"cuda"`` (NVIDIA's NVDEC); see
+    :data:`DEVICES`. ``"auto"`` picks the first hardware device that opens
+    and falls back to the CPU, while a hardware name raises
+    ``RuntimeError`` when its device cannot be opened. Codecs the device
+    does not support are decoded on the CPU either way. The frames reach
+    your code as NumPy arrays in memory.
+
+    With ``device="cuda"``, ``on_device=True`` leaves the frames on the GPU
+    instead, as :class:`CudaFrame` objects in NV12 whose planes PyTorch and
+    other libraries take through DLPack without a copy. The frames must
+    then be decoded on the GPU: other codecs raise ``RuntimeError``.
+
+    ``frames`` reads the frames with those numbers, in that order, instead
+    of the whole video; ``start``, ``stop``, and ``step`` read a slice of
+    it, with the meaning they have when slicing a list. Negative numbers
+    count from the end of the video, and a number the video does not have
+    raises ``IndexError``. ``start=0`` with ``step=1`` reads the video
+    straight through and stops at ``stop``; every other selection indexes
+    the file first, by reading its packets without decoding them, and then
+    decodes each frame from the key frame before it, so frames asked for
+    in order cost no more than reading the video straight through.
+    """
+    reader = FrameReader(
+        path,
+        height,
+        width,
+        prefetch_frames,
+        device,
+        on_device,
+        frames=frames if frames is None else list(frames),
+        start=start,
+        stop=stop,
+        step=step,
+    )
+    if on_device:
+        yield from reader
+        return
+    # The arrays share memory with the frames, which they keep alive.
+    for frame in reader:
+        yield np.asarray(frame)
+
+
+def read_batches(
+    path: PathLike,
+    batch_size: int,
+    height: Optional[int] = None,
+    width: Optional[int] = None,
+    prefetch_frames: int = 1,
+    device: str = "cpu",
+    drop_last: bool = False,
+    frames: Optional[Sequence[int]] = None,
+    start: int = 0,
+    stop: Optional[int] = None,
+    step: int = 1,
+) -> Iterator[np.ndarray]:
+    """Yield the frames of the video at ``path`` in batches, in order.
+
+    Each batch is a ``(batch_size, height, width, 3)`` array of ``uint8``
+    RGB pixels. The frames are decoded straight into it, so it costs no
+    copy. The last batch holds the frames left over, unless ``drop_last``
+    drops it. The frames of a batch have the size of the first frame of the
+    video, or ``height`` and ``width``.
+
+    Takes the same arguments as :func:`read`, except ``on_device``, so
+    ``frames``, or ``start``, ``stop``, and ``step``, batch the frames
+    with those numbers instead of the whole video. The background thread
+    decodes up to ``prefetch_frames`` frames ahead, rounded up to whole
+    batches.
+    """
+    if batch_size < 1:
+        raise ValueError("batch_size must be at least 1")
+    reader = FrameReader(
+        path,
+        height,
+        width,
+        prefetch_frames,
+        device,
+        batch_size=batch_size,
+        drop_last=drop_last,
+        frames=frames if frames is None else list(frames),
+        start=start,
+        stop=stop,
+        step=step,
+    )
+    # The arrays share memory with the batches, which they keep alive.
+    for batch in reader:
+        yield np.asarray(batch)

iterframes-0.5.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+iterframes/__init__.py,sha256=7mtAkZujhGGI4-M928Hu9ZXWlJ4XSYWQXNzGFp8rthQ,5094
+iterframes/iterframes.pyd,sha256=bw0JJpH-NPVHhmLUx4-aFvfAxTW_qicL_418_DbebSQ,17415168
+iterframes-0.5.0.dist-info/METADATA,sha256=ajWImwnAamKPppG3_KlNsV_5uYeefWXtWzNrdVnuJEI,8410
+iterframes-0.5.0.dist-info/WHEEL,sha256=I37eTNpE2wbBLxuGAyG7p6lFvJQiIjnLN05rBA0wN9g,96
+iterframes-0.5.0.dist-info/licenses/LICENSE,sha256=fTqV5eBpeAZO0_jit8j4Ref9ikBSlHJ8xwj5TLg7gFk,7817
+iterframes-0.5.0.dist-info/sboms/iterframes.cyclonedx.json,sha256=aamhyrnizmBReavFEAqj9t-Y8lE3Ko1-Ks6dfZY1RTA,42879
+iterframes-0.5.0.dist-info/RECORD,,

iterframes-0.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: cp311-abi3-win_amd64

iterframes-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.