Polish Encoder docs (#1430)

Author: NicolasHug

docs/source/api_ref_encoders.rst

@@ -7,8 +7,8 @@ torchcodec.encoders
 .. currentmodule:: torchcodec.encoders
 
 
-Multi-stream encoder
---------------------
+Multi-stream encoder for audio and video
+----------------------------------------
 
 For a tutorial, see: :ref:`sphx_glr_generated_examples_encoding_multi_stream_encoding.py`.
 
@@ -25,10 +25,6 @@ For a tutorial, see: :ref:`sphx_glr_generated_examples_encoding_multi_stream_enc
 Single-stream encoders
 ----------------------
 
-For a video encoder tutorial, see: :ref:`sphx_glr_generated_examples_encoding_video_encoding.py`.
-
-For an audio encoder tutorial, see: :ref:`sphx_glr_generated_examples_encoding_audio_encoding.py`.
-
 .. autosummary::
     :toctree: generated/
     :nosignatures:

docs/source/index.rst

@@ -98,18 +98,11 @@ Encoding
 .. grid:: 3
 
      .. grid-item-card:: :octicon:`file-code;1em`
-        Audio Encoding
-        :link: generated_examples/encoding/audio_encoding.html
+        Video and Audio Encoding
+        :link: generated_examples/encoding/multi_stream_encoding.html
         :link-type: url
 
-        How encode audio samples
-
-     .. grid-item-card:: :octicon:`file-code;1em`
-        Video Encoding
-        :link: generated_examples/encoding/video_encoding.html
-        :link-type: url
-
-        How to encode video frames
+        How encode audio and video streams
 
 .. toctree::
    :maxdepth: 1

examples/encoding/audio_encoding.py

@@ -11,6 +11,14 @@
 
 In this example, we'll learn how to encode audio samples to a file or to raw
 bytes using the :class:`~torchcodec.encoders.AudioEncoder` class.
+
+.. note::
+    This is a convenience class for simple, one-shot audio encoding. For
+    multi-stream encoding (e.g. video + audio), incremental encoding, or
+    encoding multiple audio streams, use
+    :class:`~torchcodec.encoders.Encoder` instead. See
+    :ref:`sphx_glr_generated_examples_encoding_multi_stream_encoding.py` for
+    a tutorial.
 """
 
 # %%

examples/encoding/multi_stream_encoding.py

@@ -172,9 +172,11 @@
 #
 # Instead of encoding to a file path, you can encode to any file-like object
 # (e.g. ``io.BytesIO()``) using
-# :meth:`~torchcodec.encoders.Encoder.open_file_like`. In this case, you must
-# specify the container ``format`` explicitly since there is no file extension to
-# infer it from.
+# :meth:`~torchcodec.encoders.Encoder.open_file_like`. This is useful for
+# example when you need to upload the encoded data directly to a remote server
+# or cloud storage without writing it to disk.  In this case, you must specify
+# the container ``format`` explicitly since there is no file extension to infer
+# it from.
 
 import io
 
@@ -192,4 +194,7 @@
 encoded_bytes = buf.getvalue()
 print(f"Encoded to BytesIO, size: {len(encoded_bytes)} bytes")
 
+# Or convert to a bytes tensor:
+bytes_tensor = torch.frombuffer(encoded_bytes, dtype=torch.uint8)
+
 # %%

examples/encoding/video_encoding.py

@@ -94,6 +94,7 @@ def play_video(encoded_bytes):
 )
 with encoder.open_file(output_path):
     video_stream.add_frames(frames)
+    # More frames can be submitted by calling video_stream.add_frames
 
 print(f"Encoded to {output_path}, size: {Path(output_path).stat().st_size} bytes")
 

src/torchcodec/encoders/_audio_encoder.py

@@ -9,11 +9,13 @@
 class AudioEncoder:
     """A single-stream audio encoder.
 
-    This is a convenience class for simple, one-shot audio encoding. For
-    multi-stream encoding (e.g. video + audio), incremental encoding, or
-    encoding multiple audio streams, use :class:`~torchcodec.encoders.Encoder`
-    instead. See :ref:`sphx_glr_generated_examples_encoding_multi_stream_encoding.py`
-    for a tutorial.
+    .. note::
+        This is a convenience class for simple, one-shot audio encoding. For
+        multi-stream encoding (e.g. video + audio), incremental encoding, or
+        encoding multiple audio streams, use
+        :class:`~torchcodec.encoders.Encoder` instead. See
+        :ref:`sphx_glr_generated_examples_encoding_multi_stream_encoding.py` for
+        a tutorial.
 
     Args:
         samples (``torch.Tensor``): The samples to encode. This must be a 2D

src/torchcodec/encoders/_multi_stream_encoder.py

@@ -66,7 +66,7 @@ def add_samples(self, samples: Tensor) -> None:
 
 
 class Encoder:
-    """A multi-stream encoder for encoding video and/or audio into a file or file-like object.
+    """A multi-stream encoder for encoding video and/or audio streams.
 
     Unlike :class:`VideoEncoder` and :class:`AudioEncoder` which encode a
     single stream in one shot, ``Encoder`` supports multiple streams and
@@ -89,6 +89,8 @@ class Encoder:
             with encoder.open_file("output.mp4"):
                 video_stream.add_frames(frames_tensor)
                 audio_stream.add_samples(samples_tensor)
+                # Add more frames by calling video_stream.add_frames again
+                # Add more samples by calling audio_stream.add_samples again
 
         To encode to a file-like object (e.g. ``io.BytesIO()``), use
         :meth:`open_file_like` instead:
@@ -103,6 +105,8 @@ class Encoder:
             with encoder.open_file_like(buf, format="mp4"):
                 video_stream.add_frames(frames_tensor)
             encoded_bytes = buf.getvalue()
+            # Optionally convert to a uint8 tensor of bytes with
+            # bytes_tensor = torch.frombuffer(encoded_bytes, dtype=torch.uint8)
     """
 
     def __init__(self):

src/torchcodec/encoders/_video_encoder.py

@@ -10,11 +10,13 @@
 class VideoEncoder:
     """A single-stream video encoder on CPU or CUDA.
 
-    This is a convenience class for simple, one-shot video encoding. For
-    multi-stream encoding (e.g. video + audio), incremental encoding, or mixing
-    CPU and CUDA streams, use :class:`~torchcodec.encoders.Encoder` instead.
-    See :ref:`sphx_glr_generated_examples_encoding_video_encoding.py` for a
-    tutorial.
+    .. note::
+        This is a convenience class for simple, one-shot video encoding. For
+        multi-stream encoding (e.g. video + audio), incremental encoding, or
+        mixing CPU and CUDA streams, use :class:`~torchcodec.encoders.Encoder`
+        instead. See
+        :ref:`sphx_glr_generated_examples_encoding_video_encoding.py` for a
+        tutorial.
 
     Args:
         frames (``torch.Tensor``): The frames to encode. This must be a 4D