docs: add documentation

Signed-off-by: anna-charlotte <[email protected]>
docarray · JoanFM · Jan 3, 2023 · Dec 14, 2022 · Dec 14, 2022 · Dec 15, 2022
commit 797f488e30113f7122353e8817700a64eff2c611
diff --git a/docarray/typing/tensor/audio/audio_ndarray.py b/docarray/typing/tensor/audio/audio_ndarray.py
@@ -10,7 +10,48 @@
 
 
 class AudioNdArray(NdArray):
-    """ """
+    """
+    Subclass of NdArray, to represent an audio tensor.
+    Additionally, this allows storing such a tensor as a .wav audio file.
+
+
+    EXAMPLE USAGE
+
+    .. code-block:: python
+
+        from typing import Optional
+
+        from pydantic import parse_obj_as
+
+        from docarray import Document
+        from docarray.typing import AudioNdArray, AudioUrl
+        import numpy as np
+
+
+        class MyAudioDoc(Document):
+            title: str
+            audio_tensor: Optional[AudioNdArray]
+            url: Optional[AudioUrl]
+
+
+        # from tensor
+        doc_1 = MyAudioDoc(
+            title='my_first_audio_doc',
+            audio_tensor=np.random.rand(1000, 2),
+        )
+
+        doc_1.audio_tensor.save_audio_tensor_to_file(file_path='path/to/file_1.wav')
+
+        # from url
+        doc_2 = MyAudioDoc(
+            title='my_second_audio_doc',
+            url='https://www.kozco.com/tech/piano2.wav',
+        )
+
+        doc_2.audio_tensor = parse_obj_as(AudioNdArray, doc_2.url.load())
+        doc_2.audio_tensor.save_audio_tensor_to_file(file_path='path/to/file_2.wav')
+
+    """
 
     def _to_node_protobuf(self: T, field: str = 'ndarray') -> 'NodeProto':
         """Convert itself into a NodeProto protobuf message. This function should
@@ -30,14 +71,6 @@ def save_audio_tensor_to_file(
         sample_rate: int = 44100,
         sample_width: int = 2,
     ) -> None:
-        """
-        Save :attr:`.tensor` into a .wav file. Mono/stereo is preserved.
-
-        :param file_path: if file is a string, open the file by that name, otherwise
-            treat it as a file-like object.
-        :param sample_rate: sampling frequency
-        :param sample_width: sample width in bytes
-        """
 
         max_int16 = 2**15
         tensor = (self * max_int16).astype('<h')

diff --git a/docarray/typing/tensor/audio/audio_torch_tensor.py b/docarray/typing/tensor/audio/audio_torch_tensor.py
@@ -7,26 +7,59 @@
 
 
 class AudioTorchTensor(TorchTensor, metaclass=metaTorchAndNode):
-    """ """
+    """
+    Subclass of TorchTensor, to represent an audio tensor.
+    Additionally, this allows storing such a tensor as a .wav audio file.
+
+
+    EXAMPLE USAGE
+
+    .. code-block:: python
+
+        from typing import Optional
+
+        import torch
+        from pydantic import parse_obj_as
+
+        from docarray import Document
+        from docarray.typing import AudioTorchTensor, AudioUrl
+
+
+        class MyAudioDoc(Document):
+            title: str
+            audio_tensor: Optional[AudioTorchTensor]
+            url: Optional[AudioUrl]
+
+
+        doc_1 = MyAudioDoc(
+            title='my_first_audio_doc',
+            audio_tensor=torch.randn(size=(1000, 2)),
+        )
+
+        doc_1.audio_tensor.save_audio_tensor_to_file(file_path='path/to/file_1.wav')
+
+
+        doc_2 = MyAudioDoc(
+            title='my_second_audio_doc',
+            url='https://www.kozco.com/tech/piano2.wav',
+        )
+
+        doc_2.audio_tensor = parse_obj_as(AudioTorchTensor, doc_2.url.load())
+        doc_2.audio_tensor.save_audio_tensor_to_file(file_path='path/to/file_2.wav')
+
+    """
 
     def save_audio_tensor_to_file(
         self: 'T',
         file_path: Union[str, BinaryIO],
         sample_rate: int = 44100,
         sample_width: int = 2,
     ) -> None:
-        """
-        Save :attr:`.tensor` into a .wav file. Mono/stereo is preserved.
-
-        :param file_path: if file is a string, open the file by that name, otherwise
-            treat it as a file-like object.
-        :param sample_rate: sampling frequency
-        :param sample_width: sample width in bytes
-        """
         import torch
 
         max_int16 = 2**15
-        tensor = torch.tensor(self * max_int16, dtype=torch.int16)
+        tensor = self * max_int16
+        tensor.to(dtype=torch.int16)
         n_channels = 2 if self.ndim > 1 else 1
 
         with wave.open(file_path, 'w') as f:

diff --git a/docarray/typing/url/audio_url.py b/docarray/typing/url/audio_url.py
@@ -100,21 +100,15 @@ class MyDoc(Document):
 
             # Normalise float32 array so that values are between -1.0 and +1.0
             max_int16 = 2**15
-            audio_normalised = audio_as_np_float32 / max_int16
+            audio_norm = audio_as_np_float32 / max_int16
 
             channels = ifile.getnchannels()
             if channels == 2:
                 # 1 for mono, 2 for stereo
-                audio_stereo = np.empty(
-                    (int(len(audio_normalised) / channels), channels)
-                )
-                audio_stereo[:, 0] = audio_normalised[
-                    range(0, len(audio_normalised), 2)
-                ]
-                audio_stereo[:, 1] = audio_normalised[
-                    range(1, len(audio_normalised), 2)
-                ]
+                audio_stereo = np.empty((int(len(audio_norm) / channels), channels))
+                audio_stereo[:, 0] = audio_norm[range(0, len(audio_norm), 2)]
+                audio_stereo[:, 1] = audio_norm[range(1, len(audio_norm), 2)]
 
                 return audio_stereo
             else:
-                return audio_normalised
+                return audio_norm