Docs for creating an audio dataset (#4872)

* 📝 add docs for creating audio dataset

* 🖍 small edits, encourage TAR archives more

* 🖍 apply polina feedbacks

* audiofolder and metadata first

* oops metadata first also in audio load

* replace vivos with librivox indonesia, describe streaming in more detail

* taking over the PR

* check if i can push to other's fork don't look at this

* git back vivos as main example, simplify instructions. add librivox-indonesia as an advanced example

* Apply some suggestions from code review

Co-authored-by: Quentin Lhoest <42851186+lhoestq@users.noreply.github.com>

* Update docs/source/audio_dataset_repo.mdx

Co-authored-by: Quentin Lhoest <42851186+lhoestq@users.noreply.github.com>

* fix something i don't remember what, integrate changes from #4925

* integrate #4952 to image docs too

* rename audio and image datasets guides consistently (to audio/image_dataset.mdx)

* remove outdated doc

* fix audio guide name

* fix link + minor changes

Co-authored-by: Quentin Lhoest <lhoest.q@gmail.com>
Co-authored-by: Quentin Lhoest <42851186+lhoestq@users.noreply.github.com>
Co-authored-by: polinaeterna <polina@huggingface.co>

docs/source/_toctree.yml

@@ -50,13 +50,15 @@
       title: Load audio data
     - local: audio_process
       title: Process audio data
+    - local: audio_dataset
+      title: Create an audio dataset
     title: "Audio"
   - sections:
     - local: image_load
       title: Load image data
     - local: image_process
       title: Process image data
-    - local: image_dataset_script
+    - local: image_dataset
       title: Create an image dataset
     - local: image_classification
       title: Image classification

docs/source/about_dataset_features.mdx

@@ -56,11 +56,52 @@ See the [flatten](./process#flatten) section to learn how you can extract the ne
 The array feature type is useful for creating arrays of various sizes. You can create arrays with two dimensions using [`Array2D`], and even arrays with five dimensions using [`Array5D`]. 
 
 ```py
->>> features = Features({'a': Array2D(shape=(1, 3), dtype='int32'))
+>>> features = Features({'a': Array2D(shape=(1, 3), dtype='int32')})
 ```
 
 The array type also allows the first dimension of the array to be dynamic. This is useful for handling sequences with variable lengths such as sentences, without having to pad or truncate the input to a uniform shape.
 
 ```py
 >>> features = Features({'a': Array3D(shape=(None, 5, 2), dtype='int32')})
 ```
+
+# The Audio type
+
+Audio datasets have a column with type [`Audio`], which contains three important fields:
+
+* `array`: the decoded audio data represented as a 1-dimensional array.
+* `path`: the path to the downloaded audio file.
+* `sampling_rate`: the sampling rate of the audio data.
+
+When you load an audio dataset and call the audio column, the [`Audio`] feature automatically decodes and resamples the audio file:
+
+```py
+>>> from datasets import load_dataset, Audio
+
+>>> dataset = load_dataset("PolyAI/minds14", "en-US", split="train")
+>>> dataset[0]["audio"]
+{'array': array([ 0.        ,  0.00024414, -0.00024414, ..., -0.00024414,
+         0.        ,  0.        ], dtype=float32),
+ 'path': '/root/.cache/huggingface/datasets/downloads/extracted/f14948e0e84be638dd7943ac36518a4cf3324e8b7aa331c5ab11541518e9368c/en-US~JOINT_ACCOUNT/602ba55abb1e6d0fbce92065.wav',
+ 'sampling_rate': 8000}
+```
+
+<Tip warning={true}>
+
+Index into an audio dataset using the row index first and then the `audio` column - `dataset[0]["audio"]` - to avoid decoding and resampling all the audio files in the dataset. Otherwise, this can be a slow and time-consuming process if you have a large dataset.
+
+</Tip>
+
+With `decode=False`, the [`Audio`] type simply gives you the path or the bytes of the audio file, without decoding it into an `array`, 
+
+```py
+>>> dataset = load_dataset("PolyAI/minds14", "en-US", split="train").cast_column("audio", Audio(decode=False))
+>>> dataset[0]
+{'audio': {'bytes': None,
+  'path': '/root/.cache/huggingface/datasets/downloads/extracted/f14948e0e84be638dd7943ac36518a4cf3324e8b7aa331c5ab11541518e9368c/en-US~JOINT_ACCOUNT/602ba55abb1e6d0fbce92065.wav'},
+ 'english_transcription': 'I would like to set up a joint account with my partner',
+ 'intent_class': 11,
+ 'lang_id': 4,
+ 'path': '/root/.cache/huggingface/datasets/downloads/extracted/f14948e0e84be638dd7943ac36518a4cf3324e8b7aa331c5ab11541518e9368c/en-US~JOINT_ACCOUNT/602ba55abb1e6d0fbce92065.wav',
+ 'transcription': 'I would like to set up a joint account with my partner'}
+```