[BC-breaking] Make I/O optional arguments kw-only (#3227)

Summary:
Recently, we added bunch of options to make StreamReader/Writer flexible. As a result, their methods have many number of arguments, and some of them have semantic grouping.

For example, the arguments of ``StreamWriter.add_video_stream`` are roughly grouped as follow;

- Information about input media format
   `frame_rate`, `width`, `height`, `format`
- Information about encoder
   `encoder`, `encoder_option`
- Information about codec configuration
   `codec_config`
- Information about encode media format
   `encoder_format`, `encoder_frame_rate`, `encoder_width`, `encoder_height`
- Information about additional processing
   `filter_desc`
- Hardware acceleration
   `hw_accel`

We do not know what arguments will be added in the future, but when we do,
we want to keep them roughly grouped, by inserting the new argument
somewhere in a middle without breaking backward compatibility.

This commit puts most of them in keyword-only argument, so that we can
rearrange them without breaking backward compatibility.

Pull Request resolved: https://github.com/pytorch/audio/pull/3227

Reviewed By: hwangjeff

Differential Revision: D44681620

Pulled By: mthrok

fbshipit-source-id: b55f6168f4c2f3d0f59731b9bb0db4ae54e5a90f

torchaudio/io/_compat.py

@@ -216,11 +216,10 @@ def save_audio(
         src = src.T
     s.add_audio_stream(
         sample_rate,
-        src.size(-1),
-        _get_sample_format(src.dtype),
-        _get_encoder(src.dtype, format, encoding, bits_per_sample),
-        {"strict": "experimental"},
-        _get_encoder_format(format, bits_per_sample),
+        num_channels=src.size(-1),
+        format=_get_sample_format(src.dtype),
+        encoder=_get_encoder(src.dtype, format, encoding, bits_per_sample),
+        encoder_format=_get_encoder_format(format, bits_per_sample),
     )
     with s.open():
         s.write_audio_chunk(0, src)

torchaudio/io/_stream_reader.py

@@ -630,6 +630,7 @@ class StreamReader:
         self,
         frames_per_chunk: int,
         buffer_chunk_size: int = 3,
+        *,
         stream_index: Optional[int] = None,
         decoder: Optional[str] = None,
         decoder_option: Optional[Dict[str, str]] = None,
@@ -674,10 +675,10 @@ class StreamReader:
         self.add_audio_stream(
             frames_per_chunk,
             buffer_chunk_size,
-            stream_index,
-            decoder,
-            decoder_option,
-            _get_afilter_desc(sample_rate, format, num_channels),
+            stream_index=stream_index,
+            decoder=decoder,
+            decoder_option=decoder_option,
+            filter_desc=_get_afilter_desc(sample_rate, format, num_channels),
         )
 
     @_format_video_args
@@ -685,14 +686,15 @@ class StreamReader:
         self,
         frames_per_chunk: int,
         buffer_chunk_size: int = 3,
+        *,
         stream_index: Optional[int] = None,
         decoder: Optional[str] = None,
         decoder_option: Optional[Dict[str, str]] = None,
-        hw_accel: Optional[str] = None,
         format: Optional[str] = "rgb24",
         frame_rate: Optional[int] = None,
         width: Optional[int] = None,
         height: Optional[int] = None,
+        hw_accel: Optional[str] = None,
     ):
         """Add output video stream
 
@@ -707,8 +709,6 @@ class StreamReader:
 
             decoder_option (dict or None, optional): {decoder_option}
 
-            hw_accel (str or None, optional): {hw_accel}
-
             format (str, optional): Change the format of image channels. Valid values are,
 
                 - ``"rgb24"``: 8 bits * 3 channels (R, G, B)
@@ -723,15 +723,17 @@ class StreamReader:
             width (int or None, optional): If provided, change the image width. Unit: Pixel.
 
             height (int or None, optional): If provided, change the image height. Unit: Pixel.
+
+            hw_accel (str or None, optional): {hw_accel}
         """
         self.add_video_stream(
             frames_per_chunk,
             buffer_chunk_size,
-            stream_index,
-            decoder,
-            decoder_option,
-            hw_accel,
-            _get_vfilter_desc(frame_rate, width, height, format),
+            stream_index=stream_index,
+            decoder=decoder,
+            decoder_option=decoder_option,
+            filter_desc=_get_vfilter_desc(frame_rate, width, height, format),
+            hw_accel=hw_accel,
         )
 
     @_format_audio_args
@@ -739,6 +741,7 @@ class StreamReader:
         self,
         frames_per_chunk: int,
         buffer_chunk_size: int = 3,
+        *,
         stream_index: Optional[int] = None,
         decoder: Optional[str] = None,
         decoder_option: Optional[Dict[str, str]] = None,
@@ -780,11 +783,12 @@ class StreamReader:
         self,
         frames_per_chunk: int,
         buffer_chunk_size: int = 3,
+        *,
         stream_index: Optional[int] = None,
         decoder: Optional[str] = None,
         decoder_option: Optional[Dict[str, str]] = None,
-        hw_accel: Optional[str] = None,
         filter_desc: Optional[str] = None,
+        hw_accel: Optional[str] = None,
     ):
         """Add output video stream
 

torchaudio/io/_stream_writer.py

@@ -178,11 +178,12 @@ class StreamWriter:
         sample_rate: int,
         num_channels: int,
         format: str = "flt",
+        *,
         encoder: Optional[str] = None,
         encoder_option: Optional[Dict[str, str]] = None,
-        encoder_format: Optional[str] = None,
         encoder_sample_rate: Optional[int] = None,
         encoder_num_channels: Optional[int] = None,
+        encoder_format: Optional[str] = None,
         codec_config: Optional[CodecConfig] = None,
         filter_desc: Optional[str] = None,
     ):
@@ -209,8 +210,6 @@ class StreamWriter:
 
             encoder_option (dict or None, optional): {encoder_option}
 
-            encoder_format (str or None, optional): {encoder_format}
-
             encoder_sample_rate (int or None, optional): Override the sample rate used for encoding time.
                 Some encoders pose restriction on the sample rate used for encoding.
                 If the source sample rate is not supported by the encoder, the source sample rate is used,
@@ -243,6 +242,8 @@ class StreamWriter:
                 make encoder attempt to use the provided number of channels.
                 The provided value must be one support by the encoder.
 
+            encoder_format (str or None, optional): {encoder_format}
+
             codec_config (CodecConfig or None, optional): {codec_config}
 
             filter_desc (str or None, optional): {filter_desc}
@@ -267,15 +268,16 @@ class StreamWriter:
         width: int,
         height: int,
         format: str = "rgb24",
+        *,
         encoder: Optional[str] = None,
         encoder_option: Optional[Dict[str, str]] = None,
-        encoder_format: Optional[str] = None,
         encoder_frame_rate: Optional[float] = None,
         encoder_width: Optional[int] = None,
         encoder_height: Optional[int] = None,
-        hw_accel: Optional[str] = None,
+        encoder_format: Optional[str] = None,
         codec_config: Optional[CodecConfig] = None,
         filter_desc: Optional[str] = None,
+        hw_accel: Optional[str] = None,
     ):
         """Add an output video stream.
 
@@ -305,8 +307,6 @@ class StreamWriter:
 
             encoder_option (dict or None, optional): {encoder_option}
 
-            encoder_format (str or None, optional): {encoder_format}
-
             encoder_frame_rate (float or None, optional): Override the frame rate used for encoding.
 
                 Some encoders, (such as ``"mpeg1"`` and ``"mpeg2"``) pose restriction on the
@@ -325,6 +325,12 @@ class StreamWriter:
             encoder_height (int or None, optional): Height of the image used for encoding.
                 This allows to change the image size during encoding.
 
+            encoder_format (str or None, optional): {encoder_format}
+
+            codec_config (CodecConfig or None, optional): {codec_config}
+
+            filter_desc (str or None, optional): {filter_desc}
+
             hw_accel (str or None, optional): Enable hardware acceleration.
 
                 When video is encoded on CUDA hardware, for example
@@ -334,10 +340,6 @@ class StreamWriter:
 
                 If `None`, the video chunk Tensor has to be CPU Tensor.
                 Default: ``None``.
-
-            codec_config (CodecConfig or None, optional): {codec_config}
-
-            filter_desc (str or None, optional): {filter_desc}
         """
         self._s.add_video_stream(
             frame_rate,