Update docs

Author: mthrok

docs/source/index.rst

@@ -13,6 +13,7 @@ The :mod:`torchaudio` package consists of I/O, popular datasets and common audio
    kaldi_io
    transforms
    functional
+   utils
 
 .. automodule:: torchaudio
    :members:

docs/source/sox_effects.rst

@@ -4,20 +4,15 @@
 torchaudio.sox_effects
 ======================
 
-Create SoX effects chain for preprocessing audio.
-
 .. currentmodule:: torchaudio.sox_effects
 
-:hidden:`apply_effects_tensor`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Apply SoX effects chain on torch.Tensor or on file and load as torch.Tensor.
 
 .. autofunction:: apply_effects_tensor
 
-:hidden:`apply_effects_file`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 .. autofunction:: apply_effects_file
 
+Create SoX effects chain for preprocessing audio.
 
 :hidden:`SoxEffect`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/utils.rst

@@ -0,0 +1,21 @@
+.. role:: hidden
+    :class: hidden-section
+
+torchaudio.utils.sox_utils
+==========================
+
+Utility module to configure libsox. This affects functionalities in ``sox_io`` backend and ``torchaudio.sox_effects``.
+
+.. currentmodule:: torchaudio.utils.sox_utils
+
+.. autofunction:: set_seed
+
+.. autofunction:: set_verbosity
+
+.. autofunction:: set_buffer_size
+
+.. autofunction:: set_use_threads
+
+.. autofunction:: list_effects
+
+.. autofunction:: list_formats

torchaudio/sox_effects/sox_effects.py

@@ -79,6 +79,13 @@ def apply_effects_tensor(
         the same channels order. The shape of the Tensor can be different based on the
         effects applied. Sample rate can also be different based on the effects applied.
 
+    Notes:
+        This function works in the way very similar to ``sox`` command, however there are slight
+        differences. For example, ``sox`` commnad adds certain effects automatically (such as
+        ``rate`` effect after ``speed`` and ``pitch`` and other effects), but this function does
+        only applies the given effects. (Therefore, to actually apply ``speed`` effect, you also
+        need to give ``rate`` effect with desired sampling rate.)
+
     Examples:
         >>> # Defines the effects to apply
         >>> effects = [
@@ -98,7 +105,7 @@ def apply_effects_tensor(
         >>> # Apply effects
         >>> waveform, sample_rate = apply_effects_tensor(
         ...     wave_form, sample_rate, effects, channels_first=True)
-        >>> # The new waveform his sampling rate 8000, 1 second.
+        >>> # The new waveform is sampling rate 8000, 1 second.
         >>> # normalization and channel order are preserved
         >>> waveform.shape
         torch.Size([2, 8000])
@@ -107,13 +114,6 @@ def apply_effects_tensor(
                 [ 0.1331,  0.0436, -0.3783,  ..., -0.0035,  0.0012,  0.0008]])
         >>> sample_rate
         8000
-
-    Notes:
-        This function works in the way very similar to ``sox`` command, however there are slight
-        differences. For example, ``sox`` commnad adds certain effects automatically (such as
-        ``rate`` effect after ``speed`` and ``pitch`` and other effects), but this function does
-        only applies the given effects. (Therefore, to actually apply ``speed`` effect, you also
-        need to give ``rate`` effect with desired sampling rate.)
     """
     in_signal = torch.classes.torchaudio.TensorSignal(tensor, sample_rate, channels_first)
     out_signal = torch.ops.torchaudio.sox_effects_apply_effects_tensor(in_signal, effects)
@@ -127,7 +127,7 @@ def apply_effects_file(
         normalize: bool = True,
         channels_first: bool = True,
 ) -> Tuple[torch.Tensor, int]:
-    """Apply sox effects to the audio file and load Tensor
+    """Apply sox effects to the audio file and load the resulting data as Tensor
 
     Args:
         path (str): Path to the audio file.
@@ -147,6 +147,14 @@ def apply_effects_file(
         If ``channels_first=True``, the resulting Tensor has dimension ``[channel, time]``,
         otherwise ``[time, channel]``.
 
+    Notes:
+        This function works in the way very similar to ``sox`` command, however there are slight
+        differences. For example, ``sox`` commnad adds certain effects automatically (such as
+        ``rate`` effect after ``speed``, ``pitch`` etc), but this function only applies the given
+        effects. Therefore, to actually apply ``speed`` effect, you also need to give ``rate``
+        effect with desired sampling rate, because internally, ``speed`` effects only alter sampling
+        rate and leave samples untouched.
+
     Examples:
         >>> # Defines the effects to apply
         >>> effects = [
@@ -165,14 +173,6 @@ def apply_effects_file(
                  -5.6159e-07,  4.8103e-07]])
         >>> sample_rate
         8000
-
-    Notes:
-        This function works in the way very similar to ``sox`` command, however there are slight
-        differences. For example, ``sox`` commnad adds certain effects automatically (such as
-        ``rate`` effect after ``speed``, ``pitch`` etc), but this function only applies the given
-        effects. Therefore, to actually apply ``speed`` effect, you also need to give ``rate``
-        effect with desired sampling rate, because internally, ``speed`` effects only alter sampling
-        rate and leave samples untouched.
     """
     signal = torch.ops.torchaudio.sox_effects_apply_effects_file(path, effects, normalize, channels_first)
     return signal.get_tensor(), signal.get_sample_rate()

torchaudio/utils/sox_utils.py

@@ -12,7 +12,7 @@ def set_seed(seed: int):
     """Set libsox's PRNG
 
     Args:
-        seed: seed value. valid range is int32.
+        seed (int): seed value. valid range is int32.
 
     See Also:
         http://sox.sourceforge.net/sox.html
@@ -25,7 +25,7 @@ def set_verbosity(verbosity: int):
     """Set libsox's verbosity
 
     Args:
-        verbosity: Set verbosity level of libsox.
+        verbosity (int): Set verbosity level of libsox.
             1: failure messages
             2: warnings
             3: details of processing
@@ -42,7 +42,7 @@ def set_buffer_size(buffer_size: int):
     """Set buffer size for sox effect chain
 
     Args:
-        buffer_size: Set the size in bytes of the buffers used for processing audio.
+        buffer_size (int): Set the size in bytes of the buffers used for processing audio.
 
     See Also:
         http://sox.sourceforge.net/sox.html
@@ -55,7 +55,7 @@ def set_use_threads(use_threads: bool):
     """Set multithread option for sox effect chain
 
     Args:
-        use_threads: When True, enables libsox's parallel effects channels processing.
+        use_threads (bool): When True, enables libsox's parallel effects channels processing.
             To use mutlithread, the underlying libsox has to be compiled with OpenMP support.
 
     See Also:
@@ -69,7 +69,7 @@ def list_effects() -> Dict[str, str]:
     """List the available sox effect names
 
     Returns:
-        Mapping from "effect name" to "usage"
+        Dict[str, str]: Mapping from "effect name" to "usage"
     """
     return dict(torch.ops.torchaudio.sox_utils_list_effects())
 
@@ -78,7 +78,7 @@ def list_effects() -> Dict[str, str]:
 def list_formats() -> List[str]:
     """List the supported audio formats
 
-    Returns: list[str]
-        List of supported audio formats
+    Returns:
+        List[str]: List of supported audio formats
     """
     return torch.ops.torchaudio.sox_utils_list_formats()