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

TorchCodec is a Python library for decoding video and audio data into PyTorch
tensors, on CPU and CUDA GPU. It also supports audio and video encoding!
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 / 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.
* 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`
        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

     .. 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

.. 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
