rename codec_options to extra_options

Author: Dan-Flores

src/torchcodec/_core/Encoder.cpp

@@ -620,13 +620,13 @@ void tryToValidateCodecOption(
 }
 
 void sortCodecOptions(
-    const std::map<std::string, std::string>& codecOptions,
+    const std::map<std::string, std::string>& extraOptions,
     AVDictionary** codecDict,
     AVDictionary** formatDict) {
   // Accepts a map of options as input, then sorts them into codec options and
   // format options. The sorted options are returned into two separate dicts.
   const AVClass* formatClass = avformat_get_class();
-  for (const auto& [key, value] : codecOptions) {
+  for (const auto& [key, value] : extraOptions) {
     const AVOption* fmtOpt = av_opt_find2(
         &formatClass,
         key.c_str(),
@@ -798,12 +798,12 @@ void VideoEncoder::initializeEncoder(
 
   // Apply videoStreamOptions
   AVDictionary* avCodecOptions = nullptr;
-  if (videoStreamOptions.codecOptions.has_value()) {
-    for (const auto& [key, value] : videoStreamOptions.codecOptions.value()) {
+  if (videoStreamOptions.extraOptions.has_value()) {
+    for (const auto& [key, value] : videoStreamOptions.extraOptions.value()) {
       tryToValidateCodecOption(*avCodec, key.c_str(), value);
     }
     sortCodecOptions(
-        videoStreamOptions.codecOptions.value(),
+        videoStreamOptions.extraOptions.value(),
         &avCodecOptions,
         &avFormatOptions_);
   }

src/torchcodec/_core/StreamOptions.h

@@ -52,7 +52,7 @@ struct VideoStreamOptions {
   std::optional<std::string> pixelFormat;
   std::optional<double> crf;
   std::optional<std::string> preset;
-  std::optional<std::map<std::string, std::string>> codecOptions;
+  std::optional<std::map<std::string, std::string>> extraOptions;
 };
 
 struct AudioStreamOptions {

src/torchcodec/_core/custom_ops.cpp

@@ -37,11 +37,11 @@ TORCH_LIBRARY(torchcodec_ns, m) {
   m.def(
       "_encode_audio_to_file_like(Tensor samples, int sample_rate, str format, int file_like_context, int? bit_rate=None, int? num_channels=None, int? desired_sample_rate=None) -> ()");
   m.def(
-      "encode_video_to_file(Tensor frames, int frame_rate, str filename, str? codec=None, str? pixel_format=None, float? crf=None, str? preset=None, str[]? codec_options=None) -> ()");
+      "encode_video_to_file(Tensor frames, int frame_rate, str filename, str? codec=None, str? pixel_format=None, float? crf=None, str? preset=None, str[]? extra_options=None) -> ()");
   m.def(
-      "encode_video_to_tensor(Tensor frames, int frame_rate, str format, str? codec=None, str? pixel_format=None, float? crf=None, str? preset=None, str[]? codec_options=None) -> Tensor");
+      "encode_video_to_tensor(Tensor frames, int frame_rate, str format, str? codec=None, str? pixel_format=None, float? crf=None, str? preset=None, str[]? extra_options=None) -> Tensor");
   m.def(
-      "_encode_video_to_file_like(Tensor frames, int frame_rate, str format, int file_like_context, str? codec=None, str? pixel_format=None, float? crf=None, str? preset=None, str[]? codec_options=None) -> ()");
+      "_encode_video_to_file_like(Tensor frames, int frame_rate, str format, int file_like_context, str? codec=None, str? pixel_format=None, float? crf=None, str? preset=None, str[]? extra_options=None) -> ()");
   m.def(
       "create_from_tensor(Tensor video_tensor, str? seek_mode=None) -> Tensor");
   m.def(
@@ -158,8 +158,8 @@ std::string quoteValue(const std::string& value) {
   return "\"" + value + "\"";
 }
 
-// Helper function to unflatten codec_options, alternating keys and values
-std::map<std::string, std::string> unflattenCodecOptions(
+// Helper function to unflatten extra_options, alternating keys and values
+std::map<std::string, std::string> unflattenExtraOptions(
     const std::vector<std::string>& opts) {
   std::map<std::string, std::string> optionsMap;
   for (size_t i = 0; i < opts.size(); i += 2) {
@@ -617,16 +617,16 @@ void encode_video_to_file(
     std::optional<std::string_view> pixel_format = std::nullopt,
     std::optional<double> crf = std::nullopt,
     std::optional<std::string_view> preset = std::nullopt,
-    std::optional<std::vector<std::string>> codec_options = std::nullopt) {
+    std::optional<std::vector<std::string>> extra_options = std::nullopt) {
   VideoStreamOptions videoStreamOptions;
   videoStreamOptions.codec = codec;
   videoStreamOptions.pixelFormat = pixel_format;
   videoStreamOptions.crf = crf;
   videoStreamOptions.preset = preset;
 
-  if (codec_options.has_value()) {
-    videoStreamOptions.codecOptions =
-        unflattenCodecOptions(codec_options.value());
+  if (extra_options.has_value()) {
+    videoStreamOptions.extraOptions =
+        unflattenExtraOptions(extra_options.value());
   }
 
   VideoEncoder(
@@ -645,17 +645,17 @@ at::Tensor encode_video_to_tensor(
     std::optional<std::string_view> pixel_format = std::nullopt,
     std::optional<double> crf = std::nullopt,
     std::optional<std::string_view> preset = std::nullopt,
-    std::optional<std::vector<std::string>> codec_options = std::nullopt) {
+    std::optional<std::vector<std::string>> extra_options = std::nullopt) {
   auto avioContextHolder = std::make_unique<AVIOToTensorContext>();
   VideoStreamOptions videoStreamOptions;
   videoStreamOptions.codec = codec;
   videoStreamOptions.pixelFormat = pixel_format;
   videoStreamOptions.crf = crf;
   videoStreamOptions.preset = preset;
 
-  if (codec_options.has_value()) {
-    videoStreamOptions.codecOptions =
-        unflattenCodecOptions(codec_options.value());
+  if (extra_options.has_value()) {
+    videoStreamOptions.extraOptions =
+        unflattenExtraOptions(extra_options.value());
   }
 
   return VideoEncoder(
@@ -676,7 +676,7 @@ void _encode_video_to_file_like(
     std::optional<std::string_view> pixel_format = std::nullopt,
     std::optional<double> crf = std::nullopt,
     std::optional<std::string_view> preset = std::nullopt,
-    std::optional<std::vector<std::string>> codec_options = std::nullopt) {
+    std::optional<std::vector<std::string>> extra_options = std::nullopt) {
   auto fileLikeContext =
       reinterpret_cast<AVIOFileLikeContext*>(file_like_context);
   TORCH_CHECK(
@@ -689,9 +689,9 @@ void _encode_video_to_file_like(
   videoStreamOptions.crf = crf;
   videoStreamOptions.preset = preset;
 
-  if (codec_options.has_value()) {
-    videoStreamOptions.codecOptions =
-        unflattenCodecOptions(codec_options.value());
+  if (extra_options.has_value()) {
+    videoStreamOptions.extraOptions =
+        unflattenExtraOptions(extra_options.value());
   }
 
   VideoEncoder encoder(

src/torchcodec/_core/ops.py

@@ -217,7 +217,7 @@ def encode_video_to_file_like(
     pixel_format: Optional[str] = None,
     crf: Optional[Union[int, float]] = None,
     preset: Optional[str] = None,
-    codec_options: Optional[list[str]] = None,
+    extra_options: Optional[list[str]] = None,
 ) -> None:
     """Encode video frames to a file-like object.
 
@@ -230,7 +230,7 @@ def encode_video_to_file_like(
         pixel_format: Optional pixel format (e.g., "yuv420p", "yuv444p")
         crf: Optional constant rate factor for encoding quality
         preset: Optional encoder preset as string (e.g., "ultrafast", "medium")
-        codec_options: Optional list of codec options as flattened key-value pairs
+        extra_options: Optional list of extra options as flattened key-value pairs
     """
     assert _pybind_ops is not None
 
@@ -243,7 +243,7 @@ def encode_video_to_file_like(
         pixel_format,
         crf,
         preset,
-        codec_options,
+        extra_options,
     )
 
 
@@ -335,7 +335,7 @@ def encode_video_to_file_abstract(
     pixel_format: Optional[str] = None,
     preset: Optional[str] = None,
     crf: Optional[Union[int, float]] = None,
-    codec_options: Optional[list[str]] = None,
+    extra_options: Optional[list[str]] = None,
 ) -> None:
     return
 
@@ -349,7 +349,7 @@ def encode_video_to_tensor_abstract(
     pixel_format: Optional[str] = None,
     preset: Optional[str] = None,
     crf: Optional[Union[int, float]] = None,
-    codec_options: Optional[list[str]] = None,
+    extra_options: Optional[list[str]] = None,
 ) -> torch.Tensor:
     return torch.empty([], dtype=torch.long)
 
@@ -364,7 +364,7 @@ def _encode_video_to_file_like_abstract(
     pixel_format: Optional[str] = None,
     preset: Optional[str] = None,
     crf: Optional[Union[int, float]] = None,
-    codec_options: Optional[list[str]] = None,
+    extra_options: Optional[list[str]] = None,
 ) -> None:
     return
 

src/torchcodec/encoders/_video_encoder.py

@@ -35,7 +35,7 @@ def __init__(self, frames: Tensor, *, frame_rate: int):
     def to_file(
         self,
         dest: Union[str, Path],
-        codec_options: Optional[Dict[str, Any]] = None,
+        extra_options: Optional[Dict[str, Any]] = None,
         *,
         codec: Optional[str] = None,
         pixel_format: Optional[str] = None,
@@ -60,8 +60,8 @@ def to_file(
                 encoding speed and compression. Valid values depend on the encoder (commonly
                 a string: "fast", "medium", "slow"). Defaults to None
                 (which will use encoder's default).
-            codec_options (dict[str, Any], optional): A dictionary of codec-specific
-                options to pass to the encoder, e.g. ``{"qp": 5, "tune": "film"}``.
+            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.
         """
         preset = str(preset) if isinstance(preset, int) else preset
@@ -73,8 +73,8 @@ def to_file(
             pixel_format=pixel_format,
             crf=crf,
             preset=preset,
-            codec_options=[
-                x for k, v in (codec_options or {}).items() for x in (k, str(v))
+            extra_options=[
+                x for k, v in (extra_options or {}).items() for x in (k, str(v))
             ],
         )
 
@@ -86,7 +86,7 @@ def to_tensor(
         pixel_format: Optional[str] = None,
         crf: Optional[Union[int, float]] = None,
         preset: Optional[Union[str, int]] = None,
-        codec_options: Optional[Dict[str, Any]] = None,
+        extra_options: Optional[Dict[str, Any]] = None,
     ) -> Tensor:
         """Encode frames into raw bytes, as a 1D uint8 Tensor.
 
@@ -105,8 +105,8 @@ def to_tensor(
                 encoding speed and compression. Valid values depend on the encoder (commonly
                 a string: "fast", "medium", "slow"). Defaults to None
                 (which will use encoder's default).
-            codec_options (dict[str, Any], optional): A dictionary of codec-specific
-                options to pass to the encoder, e.g. ``{"preset": "slow", "tune": "film"}``.
+            extra_options (dict[str, Any], optional): A dictionary of additional
+                encoder options to pass, e.g. ``{"preset": "slow", "tune": "film"}``.
                 Values will be converted to strings before passing to the encoder.
 
         Returns:
@@ -121,8 +121,8 @@ def to_tensor(
             pixel_format=pixel_format,
             crf=crf,
             preset=preset_value,
-            codec_options=[
-                x for k, v in (codec_options or {}).items() for x in (k, str(v))
+            extra_options=[
+                x for k, v in (extra_options or {}).items() for x in (k, str(v))
             ],
         )
 
@@ -135,7 +135,7 @@ def to_file_like(
         pixel_format: Optional[str] = None,
         crf: Optional[Union[int, float]] = None,
         preset: Optional[Union[str, int]] = None,
-        codec_options: Optional[Dict[str, Any]] = None,
+        extra_options: Optional[Dict[str, Any]] = None,
     ) -> None:
         """Encode frames into a file-like object.
 
@@ -159,8 +159,8 @@ def to_file_like(
                 encoding speed and compression. Valid values depend on the encoder (commonly
                 a string: "fast", "medium", "slow"). Defaults to None
                 (which will use encoder's default).
-            codec_options (dict[str, Any], optional): A dictionary of codec-specific
-                options to pass to the encoder, e.g. ``{"preset": "slow", "tune": "film"}``.
+            extra_options (dict[str, Any], optional): A dictionary of additional
+                encoder options to pass, e.g. ``{"preset": "slow", "tune": "film"}``.
                 Values will be converted to strings before passing to the encoder.
         """
         preset = str(preset) if isinstance(preset, int) else preset
@@ -173,7 +173,7 @@ def to_file_like(
             pixel_format=pixel_format,
             crf=crf,
             preset=preset,
-            codec_options=[
-                x for k, v in (codec_options or {}).items() for x in (k, str(v))
+            extra_options=[
+                x for k, v in (extra_options or {}).items() for x in (k, str(v))
             ],
         )

test/test_encoders.py

@@ -726,7 +726,7 @@ def test_pixel_format_errors(self, method, tmp_path):
             getattr(encoder, method)(**valid_params, pixel_format="rgb24")
 
     @pytest.mark.parametrize(
-        "codec_options,error",
+        "extra_options,error",
         [
             ({"qp": -10}, "qp=-10 is out of valid range"),
             (
@@ -745,7 +745,7 @@ def test_pixel_format_errors(self, method, tmp_path):
         ],
     )
     @pytest.mark.parametrize("method", ("to_file", "to_tensor", "to_file_like"))
-    def test_codec_options_errors(self, method, tmp_path, codec_options, error):
+    def test_extra_options_errors(self, method, tmp_path, extra_options, error):
         frames = torch.zeros((5, 3, 64, 64), dtype=torch.uint8)
         encoder = VideoEncoder(frames, frame_rate=30)
 
@@ -762,7 +762,7 @@ def test_codec_options_errors(self, method, tmp_path, codec_options, error):
             RuntimeError,
             match=error,
         ):
-            getattr(encoder, method)(**valid_params, codec_options=codec_options)
+            getattr(encoder, method)(**valid_params, extra_options=extra_options)
 
     @pytest.mark.parametrize("method", ("to_file", "to_tensor", "to_file_like"))
     def test_contiguity(self, method, tmp_path):
@@ -1156,15 +1156,15 @@ def test_codec_spec_vs_impl_equivalence(self, tmp_path, codec_spec, codec_impl):
             ("high", "fcc", "pc"),
         ],
     )
-    def test_codec_options_utilized(self, tmp_path, profile, colorspace, color_range):
-        # Test setting profile, colorspace, and color_range via codec_options is utilized
+    def test_extra_options_utilized(self, tmp_path, profile, colorspace, color_range):
+        # Test setting profile, colorspace, and color_range via extra_options is utilized
         source_frames = torch.zeros((5, 3, 64, 64), dtype=torch.uint8)
         encoder = VideoEncoder(frames=source_frames, frame_rate=30)
 
         output_path = str(tmp_path / "output.mp4")
         encoder.to_file(
             dest=output_path,
-            codec_options={
+            extra_options={
                 "profile": profile,
                 "colorspace": colorspace,
                 "color_range": color_range,