Merge branch 'main' of github.com:pytorch/torchcodec into avio

Author: NicolasHug

.github/workflows/linux_wheel.yaml

@@ -104,7 +104,6 @@ jobs:
 
       - name: Install test dependencies
         run: |
-          python -m pip install --pre torchvision --index-url https://download.pytorch.org/whl/nightly/cpu
           # Ideally we would find a way to get those dependencies from pyproject.toml
           python -m pip install numpy pytest pillow
 

.github/workflows/macos_wheel.yaml

@@ -103,7 +103,6 @@ jobs:
 
       - name: Install test dependencies
         run: |
-          python -m pip install --pre torchvision --index-url https://download.pytorch.org/whl/nightly/cpu
           python -m pip install numpy pytest pillow
 
       - name: Delete the src/ folder just for fun

.github/workflows/reference_resources.yaml

@@ -42,7 +42,7 @@ jobs:
         run: |
           # Note that we're installing stable - this is for running a script where we're a normal PyTorch
           # user, not for building TorhCodec.
-          python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
+          python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
           python -m pip install numpy pillow
 
       - name: Check out repo

CONTRIBUTING.md

@@ -48,7 +48,7 @@ pip install -e ".[dev]" --no-build-isolation -vv
 
 ### Running unit tests
 
-To run python tests run (please make sure `torchvision` is installed):
+To run python tests run:
 
 ```bash
 pytest test -vvv

README.md

@@ -2,10 +2,10 @@
 
 # TorchCodec
 
-TorchCodec is a Python library for decoding videos 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,
-TorchCodec is how you turn those videos into data.
+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:
 

docs/requirements.txt

@@ -6,4 +6,6 @@ sphinx-tabs
 matplotlib
 torchvision
 ipython
+fsspec
+aiohttp
 -e git+https://github.com/pytorch/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme

docs/source/conf.py

@@ -57,13 +57,44 @@
     "sphinx_copybutton",
 ]
 
+
+class CustomGalleryExampleSortKey:
+    # This class defines the order in which our examples appear in
+    # https://pytorch.org/torchcodec/stable/generated_examples/index.html
+    # They would otherwise be sorted alphabetically.
+    #
+    # See https://sphinx-gallery.github.io/stable/configuration.html#sorting-gallery-examples
+    # and https://github.com/sphinx-gallery/sphinx-gallery/blob/master/sphinx_gallery/sorting.py
+    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):
+        try:
+            return self.order.index(filename)
+        except ValueError as e:
+            raise ValueError(
+                "Looks like you added an example in the examples/ folder?"
+                "You need to specify its order in docs/source/conf.py. Look for CustomGalleryExampleSortKey."
+            ) from e
+
+
 sphinx_gallery_conf = {
     "examples_dirs": "../../examples/",  # path to your example scripts
     "gallery_dirs": "generated_examples",  # path to where to save gallery generated output
     "filename_pattern": ".py",
     "backreferences_dir": "gen_modules/backreferences",
     "doc_module": ("torchcodec",),
     "remove_config_comments": True,
+    "within_subsection_order": CustomGalleryExampleSortKey,
 }
 
 # We override sphinx-gallery's example header to prevent sphinx-gallery from

docs/source/index.rst

@@ -1,10 +1,10 @@
 Welcome to the TorchCodec documentation!
 ========================================
 
-TorchCodec is a Python library for decoding videos 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,
-TorchCodec is how you turn those videos into data.
+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:
 
@@ -36,12 +36,12 @@ We achieve these capabilities through:
         A simple video decoding example
 
      .. grid-item-card:: :octicon:`file-code;1em`
-        Clip sampling
+        Audio Decoding
         :img-top: _static/img/card-background.svg
-        :link: generated_examples/sampling.html
+        :link: generated_examples/audio_decoding.html
         :link-type: url
 
-        How to sample regular and random clips from a video
+        A simple audio decoding example
 
      .. grid-item-card:: :octicon:`file-code;1em`
         GPU decoding
@@ -51,6 +51,22 @@ We achieve these capabilities through:
 
         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-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-type: url
+
+        How to sample regular and random clips from a video
+
 .. note::
 
    TorchCodec is still in development stage and we are actively seeking

examples/basic_example.py

@@ -93,6 +93,16 @@ def plot(frames: torch.Tensor, title : Optional[str] = None):
 # :class:`~torchcodec.decoders.VideoDecoder`. Frames are always of
 # ``torch.uint8`` dtype.
 #
+# .. note::
+#
+#     If you need to decode multiple frames, we recommend using the batch
+#     methods instead, since they are faster:
+#     :meth:`~torchcodec.decoders.VideoDecoder.get_frames_at`,
+#     :meth:`~torchcodec.decoders.VideoDecoder.get_frames_in_range`,
+#     :meth:`~torchcodec.decoders.VideoDecoder.get_frames_played_at`, and
+#     :meth:`~torchcodec.decoders.VideoDecoder.get_frames_played_in_range`. They
+#     are described below.
+
 
 plot(first_frame, "First frame")