Improve CUDA documentation by adding TorchCodec installation instructions (meta-pytorch#365)

Author: ahmadsharif1

README.md

@@ -93,6 +93,7 @@ ffmpeg -f lavfi -i \
 ```
 
 ## 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
@@ -127,6 +128,61 @@ The following table indicates the compatibility between versions of
 | not yet supported  | `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 CUDA Toolkit. Pytorch and TorchCodec supports CUDA Toolkit
+   versions 11.8, 12.1 or 12.4. In particular TorchCodec depends on
+   CUDA libraries libnpp and libnvrtc (which are part of CUDA Toolkit).
+
+2. Install Pytorch that corresponds to your CUDA Toolkit version using the
+   [official instructions](https://pytorch.org/get-started/locally/).
+
+3. 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 -
+   ```
+
+4. 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.4 and nightly Pytorch.
+   pip install torchcodec --index-url=https://download.pytorch.org/whl/nightly/cu124
+   ```
+
+   Note that without passing in the `--index-url` parameter, `pip` installs TorchCodec
+   binaries from PyPi which are CPU-only and do not have CUDA support.
+
 ## Benchmark Results
 
 The following was generated by running [our benchmark script](./benchmarks/decoders/generate_readme_data.py) on a lightly loaded 56-core machine.

examples/basic_cuda_example.py

@@ -18,6 +18,9 @@
 running the transform steps. Encoded packets are often much smaller than decoded frames so
 CUDA decoding also uses less PCI-e bandwidth.
 
+When to and when not to use CUDA Decoding
+-----------------------------------------
+
 CUDA Decoding can offer speed-up over CPU Decoding in a few scenarios:
 
 #. You are decoding a large resolution video
@@ -37,28 +40,10 @@
 TorchCodec you can simply pass in a device parameter to the
 :class:`~torchcodec.decoders.VideoDecoder` class to use CUDA Decoding.
 
+Installing TorchCodec with CUDA Enabled
+---------------------------------------
 
-In order to use CUDA Decoding will need the following installed in your environment:
-
-#. An Nvidia GPU that supports decoding the video format you want to decode. See
-   the support matrix `here <https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new>`_
-#. `CUDA-enabled pytorch <https://pytorch.org/get-started/locally/>`_
-#. FFmpeg binaries that support
-   `NVDEC-enabled <https://docs.nvidia.com/video-technologies/video-codec-sdk/12.0/ffmpeg-with-nvidia-gpu/index.html>`_
-   codecs
-#. libnpp and nvrtc (these are usually installed when you install the full cuda-toolkit)
-
-
-FFmpeg versions 5, 6 and 7 from conda-forge are built with
-`NVDEC support <https://docs.nvidia.com/video-technologies/video-codec-sdk/12.0/ffmpeg-with-nvidia-gpu/index.html>`_
-and you can install them with conda. For example, to install FFmpeg version 7:
-
-
-.. code-block:: bash
-
-    conda install ffmpeg=7 -c conda-forge
-    conda install libnpp cuda-nvrtc -c nvidia
-
+Refer to the installation guide in the `README <https://github.com/pytorch/torchcodec#installing-cuda-enabled-torchcodec>`_.
 
 """