Welcome to the TorchCodec documentation!
========================================

TorchCodec is a PyTorch-native library for decoding and encoding media: videos,
audio, and images, 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, audio, or images, TorchCodec is how you turn these
into tensors, and back.

We achieve these capabilities through:

* Pythonic APIs that mirror Python and PyTorch conventions.
* Relying on `FFmpeg <https://www.ffmpeg.org/>`_ to do the video and audio
  decoding / encoding. 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. FFmpeg is optional:
  the image decoders and encoders don't need it.
* Returning data as PyTorch tensors, ready to be fed into PyTorch transforms
  or used directly to train models.

Installation instructions
^^^^^^^^^^^^^^^^^^^^^^^^^

.. grid:: 3

     .. grid-item-card:: :octicon:`file-code;1em`
        Installation instructions
        :link: https://github.com/meta-pytorch/torchcodec?tab=readme-ov-file#installing-torchcodec
        :link-type: url

        How to install TorchCodec

Decoding
^^^^^^^^

.. grid:: 3

     .. grid-item-card:: :octicon:`file-code;1em`
        Getting Started with TorchCodec
        :link: generated_examples/decoding/basic_example.html
        :link-type: url

        A simple video decoding example

     .. grid-item-card:: :octicon:`file-code;1em`
        Image Decoding
        :link: generated_examples/decoding/image_decoding.html
        :link-type: url

        How to decode images (JPEG on CPU and CUDA, PNG, WebP, and more)

     .. grid-item-card:: :octicon:`file-code;1em`
        Audio Decoding
        :link: generated_examples/decoding/audio_decoding.html
        :link-type: url

        A simple audio decoding example

     .. grid-item-card:: :octicon:`file-code;1em`
        GPU decoding
        :link: generated_examples/decoding/basic_cuda_example.html
        :link-type: url

        A simple example demonstrating CUDA GPU decoding

     .. grid-item-card:: :octicon:`file-code;1em`
        Streaming video
        :link: generated_examples/decoding/file_like.html
        :link-type: url

        How to efficiently decode videos from the cloud

     .. grid-item-card:: :octicon:`file-code;1em`
        Parallel decoding
        :link: generated_examples/decoding/parallel_decoding.html
        :link-type: url

        How to decode a video with multiple processes or threads.

     .. grid-item-card:: :octicon:`file-code;1em`
        Clip sampling
        :link: generated_examples/decoding/sampling.html
        :link-type: url

        How to sample regular and random clips from a video

     .. grid-item-card:: :octicon:`file-code;1em`
        Decoder transforms
        :link: generated_examples/decoding/transforms.html
        :link-type: url

        How to apply transforms while decoding

     .. grid-item-card:: :octicon:`file-code;1em`
        Performance Tips
        :link: generated_examples/decoding/performance_tips.html
        :link-type: url

        Tips for optimizing video decoding performance

     .. grid-item-card:: :octicon:`file-code;1em`
        HDR Decoding
        :link: generated_examples/decoding/hdr_decoding.html
        :link-type: url

        How to decode HDR videos with the ``output_dtype`` parameter


Encoding
^^^^^^^^

.. grid:: 3

     .. grid-item-card:: :octicon:`file-code;1em`
        Video and Audio Encoding
        :link: generated_examples/encoding/multi_stream_encoding.html
        :link-type: url

        How encode audio and video streams (CPU and CUDA)

     .. grid-item-card:: :octicon:`file-code;1em`
        Image Encoding
        :link: generated_examples/encoding/image_encoding.html
        :link-type: url

        How to encode image tensors into JPEG (CPU and CUDA) or PNG

     .. grid-item-card:: :octicon:`file-code;1em`
        Video Encoding
        :link: generated_examples/encoding/video_encoding.html
        :link-type: url

        How to encode video frames into a video file

     .. grid-item-card:: :octicon:`file-code;1em`
        Audio Encoding
        :link: generated_examples/encoding/audio_encoding.html
        :link-type: url

        How to encode audio samples into an audio file


Migrating from torchvision
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. grid:: 3

     .. grid-item-card:: :octicon:`file-code;1em`
        Migrating from torchvision
        :link: generated_examples/migration/torchvision_migration.html
        :link-type: url

        How to port ``torchvision.io`` image decoding and encoding code


.. toctree::
   :maxdepth: 1
   :hidden:

   Installation <https://github.com/meta-pytorch/torchcodec?tab=readme-ov-file#installing-torchcodec>

.. toctree::
   :maxdepth: 1
   :hidden:

   generated_examples/index

.. toctree::
   :maxdepth: 1
   :hidden:

   api_ref

.. toctree::
   :maxdepth: 1
   :hidden:

   glossary