Add multithread options to docstring and default to single thread (#2949)

Summary:
One can pass "threads" and "thread_type" to `decoder_option` of StreamReaader to change the multithreading configuration.

These affects the timing that decoder starts emitting the decoded frames. i.e. how many packets at minimum have to be processed before the first frame is decoded.

Overall, multithreading in decoder does not improve the performance.
(One possible reason is because the design of StreamReader, "decode few frames then fetch them", does not suited to saturate the decoder with incoming packets.)

num_threads=1 seems to exhibit overall good performance/resource balance.

![Decoding time over threading](https://user-images.githubusercontent.com/855818/210380632-1ab72608-76aa-4445-808a-50cef215dbac.png)
![Decoding time over threading (1)](https://user-images.githubusercontent.com/855818/210380639-ec5574b0-9087-4f22-84a4-a2c0ee632dd9.png)
(Tested on 320x240 25 FPPS, YUV420P videos generated with `ffmpeg -f lavfi -t "${duration}" -i testsrc -pix_fmt "yuv420p"`)

For this reason, we default to single thread execution in StreamReader.
closes https://github.com/pytorch/audio/issues/2855

Follow-up: Apply similar change to encoder option in StreamWriter.

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

Reviewed By: carolineechen

Differential Revision: D42343951

Pulled By: mthrok

fbshipit-source-id: aea234717d37918f99fc24f575dbcfe7dcae1e80

torchaudio/csrc/ffmpeg/stream_reader/decoder.cpp

@@ -88,6 +88,12 @@ void init_codec_context(
 #endif
 
   AVDictionary* opts = get_option_dict(decoder_option);
+
+  // Default to single thread execution.
+  if (!av_dict_get(opts, "threads", nullptr, 0)) {
+    av_dict_set(&opts, "threads", "1", 0);
+  }
+
   ret = avcodec_open2(pCodecContext, pCodecContext->codec, &opts);
   clean_up_dict(opts);
 

torchaudio/io/_stream_reader.py

@@ -239,12 +239,26 @@ _decoder = """The name of the decoder to be used.
                 Default: ``None``."""
 
 _decoder_option = """Options passed to decoder.
-                Mapping from str to str.
+                Mapping from str to str. (Default: ``None``)
 
                 To list decoder options for a decoder, you can use
                 `ffmpeg -h decoder=<DECODER>` command.
 
-                Default: ``None``."""
+                In addition to decoder-specific options, you can also pass options related
+                to multithreading. They are effective only if the decoder support them.
+                If neither of them are provided, StreamReader defaults to single thread.
+
+                 - ``"threads"``: The number of threads (in str) or the value ``"0"``
+                   to let FFmpeg decides based on its heuristics.
+                 - ``"thread_type"``: Which multithreading method to use.
+                   The valid values are ``"frame"`` or ``"slice"``.
+                   Note that sach decoder supports different set of methods.
+                   If not provided, a default value is used.
+                    - ``"frame"``: Decode more than one frame at once.
+                      Each thread handles one frame.
+                      This will increase decoding delay by one frame per thread
+                    - ``"slice"``: Decode more than one part of a single frame at once.
+                """
 
 
 _hw_accel = """Enable hardware acceleration.