torchcodec 0.3.0__cp313-cp313t-manylinux_2_28_x86_64.whl

torchcodec/samplers/_time_based.py

@@ -0,0 +1,348 @@
+from typing import Literal, Optional
+
+import torch
+
+from torchcodec import FrameBatch
+from torchcodec.samplers._common import (
+    _FRAMEBATCH_RETURN_DOCS,
+    _POLICY_FUNCTION_TYPE,
+    _POLICY_FUNCTIONS,
+    _reshape_4d_framebatch_into_5d,
+    _validate_common_params,
+)
+
+
+def _validate_params_time_based(
+    *,
+    decoder,
+    num_clips,
+    seconds_between_clip_starts,
+    seconds_between_frames,
+):
+
+    if (num_clips is None and seconds_between_clip_starts is None) or (
+        num_clips is not None and seconds_between_clip_starts is not None
+    ):
+        raise ValueError("This is internal only and should never happen.")
+
+    if seconds_between_clip_starts is not None and seconds_between_clip_starts <= 0:
+        raise ValueError(
+            f"seconds_between_clip_starts ({seconds_between_clip_starts}) must be > 0"
+        )
+
+    if num_clips is not None and num_clips <= 0:
+        raise ValueError(f"num_clips ({num_clips}) must be > 0")
+
+    if decoder.metadata.average_fps is None:
+        raise ValueError(
+            "Could not infer average fps from video metadata. "
+            "Try using an index-based sampler instead."
+        )
+
+    # Note that metadata.begin_stream_seconds is a property that will always yield a valid
+    # value; if it is not present in the actual metadata, the metadata object will return 0.
+    # Hence, we do not test for it here and only test metadata.end_stream_seconds.
+    if decoder.metadata.end_stream_seconds is None:
+        raise ValueError(
+            "Could not infer stream end from video metadata. "
+            "Try using an index-based sampler instead."
+        )
+
+    average_frame_duration_seconds = 1 / decoder.metadata.average_fps
+    if seconds_between_frames is None:
+        seconds_between_frames = average_frame_duration_seconds
+    elif seconds_between_frames <= 0:
+        raise ValueError(
+            f"seconds_between_clip_starts ({seconds_between_clip_starts}) must be > 0, got"
+        )
+
+    return seconds_between_frames
+
+
+def _validate_sampling_range_time_based(
+    *,
+    num_frames_per_clip,
+    seconds_between_frames,
+    sampling_range_start,
+    sampling_range_end,
+    begin_stream_seconds,
+    end_stream_seconds,
+):
+
+    if sampling_range_start is None:
+        sampling_range_start = begin_stream_seconds
+    else:
+        if sampling_range_start < begin_stream_seconds:
+            raise ValueError(
+                f"sampling_range_start ({sampling_range_start}) must be at least {begin_stream_seconds}"
+            )
+        if sampling_range_start >= end_stream_seconds:
+            raise ValueError(
+                f"sampling_range_start ({sampling_range_start}) must be smaller than {end_stream_seconds}"
+            )
+
+    if sampling_range_end is None:
+        # We allow a clip to start anywhere within
+        # [sampling_range_start, sampling_range_end)
+        # When sampling_range_end is None, we want to automatically set it to
+        # the largest possible value such that the sampled frames in any clip
+        # are within the bounds of the video duration (in other words, we don't
+        # want to have to resort to the `policy`).
+        # I.e. we want to guarantee that for all frames in any clip we have
+        # pts < end_stream_seconds.
+        #
+        # The frames of a clip will be sampled at the following pts:
+        # clip_timestamps = [
+        #  clip_start + 0 * seconds_between_frames,
+        #  clip_start + 1 * seconds_between_frames,
+        #  clip_start + 2 * seconds_between_frames,
+        #  ...
+        #  clip_start + (num_frames_per_clip - 1) * seconds_between_frames,
+        # ]
+        # To guarantee that any such value is < end_stream_seconds, we only need
+        # to guarantee that
+        # clip_start < end_stream_seconds - (num_frames_per_clip - 1) * seconds_between_frames
+        #
+        # So that's the value of sampling_range_end we want to use.
+        sampling_range_end = (
+            end_stream_seconds - (num_frames_per_clip - 1) * seconds_between_frames
+        )
+    elif sampling_range_end <= begin_stream_seconds:
+        raise ValueError(
+            f"sampling_range_end ({sampling_range_end}) must be at least {begin_stream_seconds}"
+        )
+
+    if sampling_range_start >= sampling_range_end:
+        raise ValueError(
+            f"sampling_range_start ({sampling_range_start}) must be smaller than sampling_range_end ({sampling_range_end})"
+        )
+
+    sampling_range_end = min(sampling_range_end, end_stream_seconds)
+
+    return sampling_range_start, sampling_range_end
+
+
+def _build_all_clips_timestamps(
+    *,
+    clip_start_seconds: torch.Tensor,  # 1D float tensor
+    num_frames_per_clip: int,
+    seconds_between_frames: float,
+    end_stream_seconds: float,
+    policy_fun: _POLICY_FUNCTION_TYPE,
+) -> list[float]:
+
+    all_clips_timestamps: list[float] = []
+    for start_seconds in clip_start_seconds:
+        clip_timestamps = [
+            timestamp
+            for i in range(num_frames_per_clip)
+            if (timestamp := start_seconds + i * seconds_between_frames)
+            < end_stream_seconds
+        ]
+
+        if len(clip_timestamps) < num_frames_per_clip:
+            clip_timestamps = policy_fun(clip_timestamps, num_frames_per_clip)
+        all_clips_timestamps += clip_timestamps
+
+    return all_clips_timestamps
+
+
+def _generic_time_based_sampler(
+    kind: Literal["random", "regular"],
+    decoder,
+    *,
+    num_clips: Optional[int],  # mutually exclusive with seconds_between_clip_starts
+    seconds_between_clip_starts: Optional[float],
+    num_frames_per_clip: int,
+    seconds_between_frames: Optional[float],
+    # None means "begining", which may not always be 0
+    sampling_range_start: Optional[float],
+    sampling_range_end: Optional[float],  # interval is [start, end).
+    policy: Literal["repeat_last", "wrap", "error"] = "repeat_last",
+) -> FrameBatch:
+    # Note: *everywhere*, sampling_range_end denotes the upper bound of where a
+    # clip can start. This is an *open* upper bound, i.e. we will make sure no
+    # clip starts exactly at (or above) sampling_range_end.
+
+    _validate_common_params(
+        decoder=decoder,
+        num_frames_per_clip=num_frames_per_clip,
+        policy=policy,
+    )
+
+    seconds_between_frames = _validate_params_time_based(
+        decoder=decoder,
+        num_clips=num_clips,
+        seconds_between_clip_starts=seconds_between_clip_starts,
+        seconds_between_frames=seconds_between_frames,
+    )
+
+    sampling_range_start, sampling_range_end = _validate_sampling_range_time_based(
+        num_frames_per_clip=num_frames_per_clip,
+        seconds_between_frames=seconds_between_frames,
+        sampling_range_start=sampling_range_start,
+        sampling_range_end=sampling_range_end,
+        begin_stream_seconds=decoder.metadata.begin_stream_seconds,
+        end_stream_seconds=decoder.metadata.end_stream_seconds,
+    )
+
+    if kind == "random":
+        assert num_clips is not None  # appease type-checker
+        sampling_range_width = sampling_range_end - sampling_range_start
+        # torch.rand() returns in [0, 1)
+        # which ensures all clip starts are < sampling_range_end
+        clip_start_seconds = (
+            torch.rand(num_clips) * sampling_range_width + sampling_range_start
+        )
+    else:
+        assert seconds_between_clip_starts is not None  # appease type-checker
+        clip_start_seconds = torch.arange(
+            sampling_range_start,
+            sampling_range_end,  # excluded
+            seconds_between_clip_starts,
+        )
+        num_clips = len(clip_start_seconds)
+
+    all_clips_timestamps = _build_all_clips_timestamps(
+        clip_start_seconds=clip_start_seconds,
+        num_frames_per_clip=num_frames_per_clip,
+        seconds_between_frames=seconds_between_frames,
+        end_stream_seconds=decoder.metadata.end_stream_seconds,
+        policy_fun=_POLICY_FUNCTIONS[policy],
+    )
+
+    frames = decoder.get_frames_played_at(seconds=all_clips_timestamps)
+    return _reshape_4d_framebatch_into_5d(
+        frames=frames,
+        num_clips=num_clips,
+        num_frames_per_clip=num_frames_per_clip,
+    )
+
+
+def clips_at_random_timestamps(
+    decoder,
+    *,
+    num_clips: int = 1,
+    num_frames_per_clip: int = 1,
+    seconds_between_frames: Optional[float] = None,
+    # None means "begining", which may not always be 0
+    sampling_range_start: Optional[float] = None,
+    sampling_range_end: Optional[float] = None,  # interval is [start, end).
+    policy: Literal["repeat_last", "wrap", "error"] = "repeat_last",
+) -> FrameBatch:
+    # See docstring below
+    return _generic_time_based_sampler(
+        kind="random",
+        decoder=decoder,
+        num_clips=num_clips,
+        seconds_between_clip_starts=None,
+        num_frames_per_clip=num_frames_per_clip,
+        seconds_between_frames=seconds_between_frames,
+        sampling_range_start=sampling_range_start,
+        sampling_range_end=sampling_range_end,
+        policy=policy,
+    )
+
+
+def clips_at_regular_timestamps(
+    decoder,
+    *,
+    seconds_between_clip_starts: float,
+    num_frames_per_clip: int = 1,
+    seconds_between_frames: Optional[float] = None,
+    # None means "begining", which may not always be 0
+    sampling_range_start: Optional[float] = None,
+    sampling_range_end: Optional[float] = None,  # interval is [start, end).
+    policy: Literal["repeat_last", "wrap", "error"] = "repeat_last",
+) -> FrameBatch:
+    # See docstring below
+    return _generic_time_based_sampler(
+        kind="regular",
+        decoder=decoder,
+        num_clips=None,
+        seconds_between_clip_starts=seconds_between_clip_starts,
+        num_frames_per_clip=num_frames_per_clip,
+        seconds_between_frames=seconds_between_frames,
+        sampling_range_start=sampling_range_start,
+        sampling_range_end=sampling_range_end,
+        policy=policy,
+    )
+
+
+_COMMON_DOCS = """
+    {maybe_note}
+
+    Args:
+        decoder (VideoDecoder): The :class:`~torchcodec.decoders.VideoDecoder`
+            instance to sample clips from.
+        {num_clips_or_seconds_between_clip_starts}
+        num_frames_per_clip (int, optional): The number of frames per clips. Default: 1.
+        seconds_between_frames (float or None, optional): The time (in seconds)
+            between each frame within a clip. More accurately, this defines the
+            time between the *frame sampling point*, i.e. the timestamps at
+            which we sample the frames. Because frames span intervals in time ,
+            the resulting start of frames within a clip may not be exactly
+            spaced by ``seconds_between_frames`` - but on average, they will be.
+            Default is None, which is set to the average frame duration
+            (``1/average_fps``).
+        sampling_range_start (float or None, optional): The start of the
+            sampling range, which defines the first timestamp (in seconds) that
+            a clip may *start* at. Default: None, which corresponds to the start
+            of the video. (Note: some videos start at negative values, which is
+            why the default is not 0).
+        sampling_range_end (float or None, optional): The end of the sampling
+            range, which defines the last timestamp (in seconds) that a clip may
+            *start* at. This value is exclusive, i.e. a clip may only start within
+            [``sampling_range_start``, ``sampling_range_end``). If None
+            (default), the value is set automatically such that the clips never
+            span beyond the end of the video, i.e. it is set to
+            ``end_video_seconds - (num_frames_per_clip - 1) *
+            seconds_between_frames``. When a clip spans beyond the end of the
+            video, the ``policy`` parameter defines how to construct such clip.
+        policy (str, optional): Defines how to construct clips that span beyond
+            the end of the video. This is best described with an example:
+            assuming the last valid (seekable) timestamp in a video is 10.9, and
+            a clip was sampled to start at timestamp 10.5, with
+            ``num_frames_per_clip=5`` and ``seconds_between_frames=0.2``, the
+            sampling timestamps of the frames in the clip are supposed to be
+            [10.5, 10.7, 10.9, 11.1, 11.2]. But 11.1 and 11.2 are invalid
+            timestamps, so the ``policy`` parameter defines how to replace those
+            frames, with valid sampling timestamps:
+
+            - "repeat_last": repeats the last valid frame of the clip. We would
+              get frames sampled at timestamps [10.5, 10.7, 10.9, 10.9, 10.9].
+            - "wrap": wraps around to the beginning of the clip. We would get
+              frames sampled at timestamps [10.5, 10.7, 10.9, 10.5, 10.7].
+            - "error": raises an error.
+
+            Default is "repeat_last". Note that when ``sampling_range_end=None``
+            (default), this policy parameter is unlikely to be relevant.
+
+    {return_docs}
+"""
+
+
+_NUM_CLIPS_DOCS = """
+        num_clips (int, optional): The number of clips to return. Default: 1.
+"""
+clips_at_random_timestamps.__doc__ = f"""Sample :term:`clips` at random timestamps.
+{_COMMON_DOCS.format(maybe_note="", num_clips_or_seconds_between_clip_starts=_NUM_CLIPS_DOCS, return_docs=_FRAMEBATCH_RETURN_DOCS)}
+"""
+
+
+_SECONDS_BETWEEN_CLIP_STARTS = """
+        seconds_between_clip_starts (float): The space (in seconds) between each
+            clip start.
+"""
+
+_NOTE_DOCS = """
+    .. note::
+        For consistency with existing sampling APIs (such as torchvision), this
+        sampler takes a ``seconds_between_clip_starts`` parameter instead of
+        ``num_clips``. If you find that supporting ``num_clips`` would be
+        useful, please let us know by `opening a feature request
+        <https://github.com/pytorch/torchcodec/issues?q=is:open+is:issue>`_.
+"""
+clips_at_regular_timestamps.__doc__ = f"""Sample :term:`clips` at regular (equally-spaced) timestamps.
+{_COMMON_DOCS.format(maybe_note=_NOTE_DOCS, num_clips_or_seconds_between_clip_starts=_SECONDS_BETWEEN_CLIP_STARTS, return_docs=_FRAMEBATCH_RETURN_DOCS)}
+"""

torchcodec/version.py

@@ -0,0 +1,2 @@
+# Note that this file is generated during install.
+__version__ = '0.3.0'

torchcodec-0.3.0.dist-info/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright 2024 Meta
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,this list
+of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this
+list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may
+be used to endorse or promote products derived from this software without specific
+prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
+SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.

torchcodec-0.3.0.dist-info/METADATA

@@ -0,0 +1,280 @@
+Metadata-Version: 2.1
+Name: torchcodec
+Version: 0.3.0
+Summary: A video decoder for PyTorch
+Author-email: PyTorch Team <packages@pytorch.org>
+License: BSD 3-Clause License
+        
+        Copyright 2024 Meta
+        
+        Redistribution and use in source and binary forms, with or without modification,
+        are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice,this list
+        of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice, this
+        list of conditions and the following disclaimer in the documentation
+        and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its contributors may
+        be used to endorse or promote products derived from this software without specific
+        prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY
+        EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+        OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
+        SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+        INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+        TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+        BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+        ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+        DAMAGE.
+        
+Project-URL: GitHub, https://github.com/pytorch/torchcodec
+Project-URL: Documentation, https://pytorch.org/torchcodec/stable/index.html
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: numpy ; extra == 'dev'
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: pillow ; extra == 'dev'
+
+[**Installation**](#installing-torchcodec) | [**Simple Example**](#using-torchcodec) | [**Detailed Example**](https://pytorch.org/torchcodec/stable/generated_examples/) | [**Documentation**](https://pytorch.org/torchcodec) | [**Contributing**](CONTRIBUTING.md) | [**License**](#license)
+
+# TorchCodec
+
+TorchCodec is a Python library for decoding video and audio data into PyTorch
+tensors, on CPU and CUDA GPU. It aims to be fast, easy to use, and well
+integrated into the PyTorch ecosystem. If you want to use PyTorch to train ML
+models on videos and audio, TorchCodec is how you turn these into data.
+
+We achieve these capabilities through:
+
+* Pythonic APIs that mirror Python and PyTorch conventions.
+* Relying on [FFmpeg](https://www.ffmpeg.org/) to do the decoding. TorchCodec
+  uses the version of FFmpeg you already have installed. FFmpeg is a mature
+  library with broad coverage available on most systems. It is, however, not
+  easy to use. TorchCodec abstracts FFmpeg's complexity to ensure it is used
+  correctly and efficiently.
+* Returning data as PyTorch tensors, ready to be fed into PyTorch transforms
+  or used directly to train models.
+
+> [!NOTE]
+> ⚠️ TorchCodec is still in development stage and some APIs may be updated
+> in future versions, depending on user feedback.
+> If you have any suggestions or issues, please let us know by
+> [opening an issue](https://github.com/pytorch/torchcodec/issues/new/choose)!
+
+## Using TorchCodec
+
+Here's a condensed summary of what you can do with TorchCodec. For more detailed
+examples, [check out our
+documentation](https://pytorch.org/torchcodec/stable/generated_examples/)!
+
+#### Decoding
+
+```python
+from torchcodec.decoders import VideoDecoder
+
+device = "cpu"  # or e.g. "cuda" !
+decoder = VideoDecoder("path/to/video.mp4", device=device)
+
+decoder.metadata
+# VideoStreamMetadata:
+#   num_frames: 250
+#   duration_seconds: 10.0
+#   bit_rate: 31315.0
+#   codec: h264
+#   average_fps: 25.0
+#   ... (truncated output)
+
+# Simple Indexing API
+decoder[0]  # uint8 tensor of shape [C, H, W]
+decoder[0 : -1 : 20]  # uint8 stacked tensor of shape [N, C, H, W]
+
+# Indexing, with PTS and duration info:
+decoder.get_frames_at(indices=[2, 100])
+# FrameBatch:
+#   data (shape): torch.Size([2, 3, 270, 480])
+#   pts_seconds: tensor([0.0667, 3.3367], dtype=torch.float64)
+#   duration_seconds: tensor([0.0334, 0.0334], dtype=torch.float64)
+
+# Time-based indexing with PTS and duration info
+decoder.get_frames_played_at(seconds=[0.5, 10.4])
+# FrameBatch:
+#   data (shape): torch.Size([2, 3, 270, 480])
+#   pts_seconds: tensor([ 0.4671, 10.3770], dtype=torch.float64)
+#   duration_seconds: tensor([0.0334, 0.0334], dtype=torch.float64)
+```
+
+#### Clip sampling
+
+```python
+
+from torchcodec.samplers import clips_at_regular_timestamps
+
+clips_at_regular_timestamps(
+    decoder,
+    seconds_between_clip_starts=1.5,
+    num_frames_per_clip=4,
+    seconds_between_frames=0.1
+)
+# FrameBatch:
+#   data (shape): torch.Size([9, 4, 3, 270, 480])
+#   pts_seconds: tensor([[ 0.0000,  0.0667,  0.1668,  0.2669],
+#         [ 1.4681,  1.5682,  1.6683,  1.7684],
+#         [ 2.9696,  3.0697,  3.1698,  3.2699],
+#         ... (truncated), dtype=torch.float64)
+#   duration_seconds: tensor([[0.0334, 0.0334, 0.0334, 0.0334],
+#         [0.0334, 0.0334, 0.0334, 0.0334],
+#         [0.0334, 0.0334, 0.0334, 0.0334],
+#         ... (truncated), dtype=torch.float64)
+```
+
+You can use the following snippet to generate a video with FFmpeg and tryout
+TorchCodec:
+
+```bash
+fontfile=/usr/share/fonts/dejavu-sans-mono-fonts/DejaVuSansMono-Bold.ttf
+output_video_file=/tmp/output_video.mp4
+
+ffmpeg -f lavfi -i \
+    color=size=640x400:duration=10:rate=25:color=blue \
+    -vf "drawtext=fontfile=${fontfile}:fontsize=30:fontcolor=white:x=(w-text_w)/2:y=(h-text_h)/2:text='Frame %{frame_num}'" \
+    ${output_video_file}
+```
+
+## Installing TorchCodec
+### Installing CPU-only TorchCodec
+
+1. Install the latest stable version of PyTorch following the
+   [official instructions](https://pytorch.org/get-started/locally/). For other
+   versions, refer to the table below for compatibility between versions of
+   `torch` and `torchcodec`.
+
+2. Install FFmpeg, if it's not already installed. Linux distributions usually
+   come with FFmpeg pre-installed. TorchCodec supports all major FFmpeg versions
+   in [4, 7].
+
+   If FFmpeg is not already installed, or you need a more recent version, an
+   easy way to install it is to use `conda`:
+
+   ```bash
+   conda install ffmpeg
+   # or
+   conda install ffmpeg -c conda-forge
+   ```
+
+3. Install TorchCodec:
+
+   ```bash
+   pip install torchcodec
+   ```
+
+The following table indicates the compatibility between versions of
+`torchcodec`, `torch` and Python.
+
+| `torchcodec`       | `torch`            | Python              |
+| ------------------ | ------------------ | ------------------- |
+| `main` / `nightly` | `main` / `nightly` | `>=3.9`, `<=3.13`   |
+| `0.2`              | `2.6`              | `>=3.9`, `<=3.13`   |
+| `0.1`              | `2.5`              | `>=3.9`, `<=3.12`   |
+| `0.0.3`            | `2.4`              | `>=3.8`, `<=3.12`   |
+
+### Installing CUDA-enabled TorchCodec
+
+First, make sure you have a GPU that has NVDEC hardware that can decode the
+format you want. Refer to Nvidia's GPU support matrix for more details
+[here](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new).
+
+1. Install Pytorch corresponding to your CUDA Toolkit using the
+   [official instructions](https://pytorch.org/get-started/locally/). You'll
+   need the `libnpp` and `libnvrtc` CUDA libraries, which are usually part of
+   the CUDA Toolkit.
+
+2. Install or compile FFmpeg with NVDEC support.
+   TorchCodec with CUDA should work with FFmpeg versions in [4, 7].
+
+   If FFmpeg is not already installed, or you need a more recent version, an
+   easy way to install it is to use `conda`:
+
+   ```bash
+   conda install ffmpeg
+   # or
+   conda install ffmpeg -c conda-forge
+   ```
+
+   If you are building FFmpeg from source you can follow Nvidia's guide to
+   configuring and installing FFmpeg with NVDEC support
+   [here](https://docs.nvidia.com/video-technologies/video-codec-sdk/12.0/ffmpeg-with-nvidia-gpu/index.html).
+
+   After installing FFmpeg make sure it has NVDEC support when you list the supported
+   decoders:
+
+   ```bash
+   ffmpeg -decoders | grep -i nvidia
+   # This should show a line like this:
+   # V..... h264_cuvid           Nvidia CUVID H264 decoder (codec h264)
+   ```
+
+   To check that FFmpeg libraries work with NVDEC correctly you can decode a sample video:
+
+   ```bash
+   ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i test/resources/nasa_13013.mp4 -f null -
+   ```
+
+3. Install TorchCodec by passing in an `--index-url` parameter that corresponds
+   to your CUDA Toolkit version, example:
+
+   ```bash
+   # This corresponds to CUDA Toolkit version 12.6. It should be the same one
+   # you used when you installed PyTorch (If you installed PyTorch with pip).
+   pip install torchcodec --index-url=https://download.pytorch.org/whl/cu126
+   ```
+
+   Note that without passing in the `--index-url` parameter, `pip` installs
+   the CPU-only version of TorchCodec.
+
+## Benchmark Results
+
+The following was generated by running [our benchmark script](./benchmarks/decoders/generate_readme_data.py) on a lightly loaded 22-core machine with an Nvidia A100 with
+5 [NVDEC decoders](https://docs.nvidia.com/video-technologies/video-codec-sdk/12.1/nvdec-application-note/index.html#).
+
+![benchmark_results](./benchmarks/decoders/benchmark_readme_chart.png)
+
+The top row is a [Mandelbrot](https://ffmpeg.org/ffmpeg-filters.html#mandelbrot) video
+generated from FFmpeg that has a resolution of 1280x720 at 60 fps and is 120 seconds long.
+The bottom row is [promotional video from NASA](https://download.pytorch.org/torchaudio/tutorial-assets/stream-api/NASAs_Most_Scientifically_Complex_Space_Observatory_Requires_Precision-MP4_small.mp4)
+that has a resolution of 960x540 at 29.7 fps and is 206 seconds long. Both videos were
+encoded with libx264 and yuv420p pixel format. All decoders, except for TorchVision, used FFmpeg 6.1.2. TorchVision used FFmpeg 4.2.2.
+
+For TorchCodec, the "approx" label means that it was using [approximate mode](https://pytorch.org/torchcodec/stable/generated_examples/approximate_mode.html)
+for seeking.
+
+## Planned future work
+
+We are actively working on the following features:
+
+- [Audio decoding](https://github.com/pytorch/torchcodec/issues/85)
+
+Let us know if you have any feature requests by [opening an
+issue](https://github.com/pytorch/torchcodec/issues/new?assignees=&labels=&projects=&template=feature-request.yml)!
+
+## Contributing
+
+We welcome contributions to TorchCodec! Please see our [contributing
+guide](CONTRIBUTING.md) for more details.
+
+## License
+
+TorchCodec is released under the [BSD 3 license](./LICENSE).
+
+However, TorchCodec may be used with code not written by Meta which may be
+distributed under different licenses.
+
+For example, if you build TorchCodec with ENABLE_CUDA=1 or use the CUDA-enabled
+release of torchcodec, please review CUDA's license here:
+[Nvidia licenses](https://docs.nvidia.com/cuda/eula/index.html).