adjust docstirngs, apply nits

Author: Dan-Flores

examples/encoding/video_encoding.py

@@ -155,10 +155,6 @@ def play_video(encoded_bytes):
     )
     print(f"Codec used in {name}: {result.stdout.strip()}")
 
-# %%
-# For most cases, you can simply specify the format parameter and let the FFmpeg select the default codec.
-# However, specifying the codec parameter is useful to select a particular codec implementation
-# (``libx264`` vs ``libx265``) or to have more control over the encoding behavior.
 
 # %%
 # .. _pixel_format:
@@ -199,7 +195,7 @@ def play_video(encoded_bytes):
 # For example, with the commonly used H.264 codec, ``libx264``:
 #
 # - Values range from 0 (lossless) to 51 (worst quality)
-# - Values 17 or 18 are conisdered visually lossless, and the default is 23.
+# - Values 17 or 18 are considered visually lossless, and the default is 23.
 #
 # .. note::
 #
@@ -228,10 +224,11 @@ def play_video(encoded_bytes):
 # Faster presets encode faster but produce larger files, while slower
 # presets take more time to encode but result in better compression.
 #
-# For example, with the commonly used H.264 codec, ``libx264`` presets include:
-#
-# - ``"ultrafast"`` (fastest), ``"fast"``, ``"medium"`` (default), ``"slow"``, ``"veryslow"`` (slowest, best compression).
-# - See additional details in the `H.264 Video Encoding Guide <https://trac.ffmpeg.org/wiki/Encode/H.264#a2.Chooseapresetandtune>`_.
+# For example, with the commonly used H.264 codec, ``libx264`` presets include
+# ``"ultrafast"`` (fastest), ``"fast"``, ``"medium"`` (default), ``"slow"``, and
+# ``"veryslow"`` (slowest, best compression). See the
+# `H.264 Video Encoding Guide <https://trac.ffmpeg.org/wiki/Encode/H.264#a2.Chooseapresetandtune>`_
+# for additional details.
 #
 # .. note::
 #
@@ -272,13 +269,12 @@ def play_video(encoded_bytes):
 #
 
 
-# Custom GOP size and tuning
 custom_output = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False).name
 encoder.to_file(
     custom_output,
     codec="libx264",
     extra_options={
-        "g": 50,               # Keyframe every 50 frames
+        "g": 50,                # Keyframe every 50 frames
         "max_b_frames": 0,      # Disable B-frames for faster decoding
         "tune": "fastdecode",   # Optimize for fast decoding
     }

src/torchcodec/encoders/_video_encoder.py

@@ -56,17 +56,16 @@ def to_file(
                 "yuv420p", "yuv444p"). If not specified, uses codec's default format.
                 See :ref:`pixel_format` for details.
             crf (int or float, optional): Constant Rate Factor for encoding quality. Lower values
-                mean better quality. Valid range depends on the encoder (commonly 0-51).
+                mean better quality. Valid range depends on the encoder (e.g.  0-51 for libx264).
                 Defaults to None (which will use encoder's default).
                 See :ref:`crf` for details.
             preset (str or int, optional): Encoder option that controls the tradeoff between
-                encoding speed and compression. Valid values depend on the encoder (commonly
+                encoding encoding speed and compression (output size). Valid on the encoder (commonly
                 a string: "fast", "medium", "slow"). Defaults to None
                 (which will use encoder's default).
                 See :ref:`preset` for details.
             extra_options (dict[str, Any], optional): A dictionary of additional
                 encoder options to pass, e.g. ``{"qp": 5, "tune": "film"}``.
-                Values will be converted to strings before passing to the encoder.
                 See :ref:`extra_options` for details.
         """
         preset = str(preset) if isinstance(preset, int) else preset
@@ -106,17 +105,16 @@ def to_tensor(
                 "yuv420p", "yuv444p"). If not specified, uses codec's default format.
                 See :ref:`pixel_format` for details.
             crf (int or float, optional): Constant Rate Factor for encoding quality. Lower values
-                mean better quality. Valid range depends on the encoder (commonly 0-51).
+                mean better quality. Valid range depends on the encoder (e.g.  0-51 for libx264).
                 Defaults to None (which will use encoder's default).
                 See :ref:`crf` for details.
             preset (str or int, optional): Encoder option that controls the tradeoff between
-                encoding speed and compression. Valid values depend on the encoder (commonly
+                encoding encoding speed and compression (output size). Valid on the encoder (commonly
                 a string: "fast", "medium", "slow"). Defaults to None
                 (which will use encoder's default).
                 See :ref:`preset` for details.
             extra_options (dict[str, Any], optional): A dictionary of additional
                 encoder options to pass, e.g. ``{"qp": 5, "tune": "film"}``.
-                Values will be converted to strings before passing to the encoder.
                 See :ref:`extra_options` for details.
 
         Returns:
@@ -165,17 +163,16 @@ def to_file_like(
                 "yuv420p", "yuv444p"). If not specified, uses codec's default format.
                 See :ref:`pixel_format` for details.
             crf (int or float, optional): Constant Rate Factor for encoding quality. Lower values
-                mean better quality. Valid range depends on the encoder (commonly 0-51).
+                mean better quality. Valid range depends on the encoder (e.g.  0-51 for libx264).
                 Defaults to None (which will use encoder's default).
                 See :ref:`crf` for details.
             preset (str or int, optional): Encoder option that controls the tradeoff between
-                encoding speed and compression. Valid values depend on the encoder (commonly
+                encoding encoding speed and compression (output size). Valid on the encoder (commonly
                 a string: "fast", "medium", "slow"). Defaults to None
                 (which will use encoder's default).
                 See :ref:`preset` for details.
             extra_options (dict[str, Any], optional): A dictionary of additional
                 encoder options to pass, e.g. ``{"qp": 5, "tune": "film"}``.
-                Values will be converted to strings before passing to the encoder.
                 See :ref:`extra_options` for details.
         """
         preset = str(preset) if isinstance(preset, int) else preset