Merge branch 'main' of github.com:pytorch/torchcodec into new-theme

Author: NicolasHug

README.md

@@ -3,17 +3,18 @@
 # 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.
+tensors, on CPU and CUDA GPU. It also supports audio encoding, and video
+encoding will come soon!  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
+* Relying on [FFmpeg](https://www.ffmpeg.org/) to do the decoding and 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.

docs/source/api_ref.rst

@@ -28,8 +28,8 @@ torchcodec.decoders
 .. currentmodule:: torchcodec.decoders
 
 
-For a video decoder tutorial, see: :ref:`sphx_glr_generated_examples_basic_example.py`.
-For an audio decoder tutorial, see: :ref:`sphx_glr_generated_examples_audio_decoding.py`.
+For a video decoder tutorial, see: :ref:`sphx_glr_generated_examples_decoding_basic_example.py`.
+For an audio decoder tutorial, see: :ref:`sphx_glr_generated_examples_decoding_audio_decoding.py`.
 
 
 .. autosummary::
@@ -49,6 +49,25 @@ For an audio decoder tutorial, see: :ref:`sphx_glr_generated_examples_audio_deco
     VideoStreamMetadata
     AudioStreamMetadata
 
+.. _encoders:
+
+torchcodec.encoders
+-------------------
+
+.. currentmodule:: torchcodec.encoders
+
+
+For an audio decoder tutorial, see: :ref:`sphx_glr_generated_examples_encoding_audio_encoding.py`.
+
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+    :template: class.rst
+
+    AudioEncoder
+
+
 .. _samplers:
 
 torchcodec.samplers
@@ -57,7 +76,7 @@ torchcodec.samplers
 
 .. currentmodule:: torchcodec.samplers
 
-For a tutorial, see: :ref:`sphx_glr_generated_examples_sampling.py`.
+For a tutorial, see: :ref:`sphx_glr_generated_examples_decoding_sampling.py`.
 
 .. autosummary::
     :toctree: generated/

docs/source/conf.py

@@ -72,18 +72,27 @@ class CustomGalleryExampleSortKey:
     def __init__(self, src_dir):
         self.src_dir = src_dir
 
-    order = [
-        "basic_example.py",
-        "audio_decoding.py",
-        "basic_cuda_example.py",
-        "file_like.py",
-        "approximate_mode.py",
-        "sampling.py",
-    ]
-
     def __call__(self, filename):
+        # We have two top-level galleries, one for decoding examples and one for
+        # encoding examples. We define the example order within each gallery
+        # individually.
+        if "examples/decoding" in self.src_dir:
+            order = [
+                "basic_example.py",
+                "audio_decoding.py",
+                "basic_cuda_example.py",
+                "file_like.py",
+                "approximate_mode.py",
+                "sampling.py",
+            ]
+        else:
+            assert "examples/encoding" in self.src_dir
+            order = [
+                "audio_encoding.py",
+            ]
+
         try:
-            return self.order.index(filename)
+            return order.index(filename)
         except ValueError as e:
             raise ValueError(
                 "Looks like you added an example in the examples/ folder?"

docs/source/index.rst

@@ -2,21 +2,25 @@ 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 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.
+tensors, on CPU and CUDA GPU. It also supports audio encoding, and video encoding will come soon!
+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. FMPEG 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.
+* Relying on `FFmpeg <https://www.ffmpeg.org/>`_ to do the decoding / encoding.
+  TorchCodec uses the version of FFmpeg you already have installed. FMPEG 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`
@@ -27,46 +31,64 @@ We achieve these capabilities through:
 
         How to install TorchCodec
 
+Decoding
+^^^^^^^^
+
+.. grid:: 3
+
      .. grid-item-card:: :octicon:`file-code;1em`
         Getting Started with TorchCodec
         :img-top: _static/img/card-background.svg
-        :link: generated_examples/basic_example.html
+        :link: generated_examples/decoding/basic_example.html
         :link-type: url
 
         A simple video decoding example
 
      .. grid-item-card:: :octicon:`file-code;1em`
         Audio Decoding
         :img-top: _static/img/card-background.svg
-        :link: generated_examples/audio_decoding.html
+        :link: generated_examples/decoding/audio_decoding.html
         :link-type: url
 
         A simple audio decoding example
 
      .. grid-item-card:: :octicon:`file-code;1em`
         GPU decoding
         :img-top: _static/img/card-background.svg
-        :link: generated_examples/basic_cuda_example.html
+        :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
         :img-top: _static/img/card-background.svg
-        :link: generated_examples/file_like.html
+        :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`
         Clip sampling
         :img-top: _static/img/card-background.svg
-        :link: generated_examples/sampling.html
+        :link: generated_examples/decoding/sampling.html
         :link-type: url
 
         How to sample regular and random clips from a video
 
+Encoding
+^^^^^^^^
+
+.. grid:: 3
+
+     .. grid-item-card:: :octicon:`file-code;1em`
+        Audio Encoding
+        :img-top: _static/img/card-background.svg
+        :link: generated_examples/encoding/audio_encoding.html
+        :link-type: url
+
+        How encode audio samples
+
 .. toctree::
    :maxdepth: 1
    :caption: Installation

examples/decoding/README.rst

@@ -0,0 +1,2 @@
+Decoding
+--------

examples/approximate_mode.py renamed to examples/decoding/approximate_mode.py

@@ -96,7 +96,7 @@ def bench(f, average_over=10, warmup=2):
 # the :class:`~torchcodec.decoders.VideoDecoder` class to ``"approximate"``. We do
 # this to avoid scanning the entire video during initialization, which would
 # require downloading the entire video even if we only want to decode the first
-# frame. See :ref:`sphx_glr_generated_examples_approximate_mode.py` for more.
+# frame. See :ref:`sphx_glr_generated_examples_decoding_approximate_mode.py` for more.
 
 
 def decode_from_existing_download():