# 加载音频数据

您可以使用 [Audio](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Audio) 功能加载音频数据集，该功能会在访问示例时自动解码并重采样音频文件。音频解码基于 [`torchcodec`](https://github.com/pytorch/torchcodec) Python 包，其底层使用 [`FFmpeg`](https://www.ffmpeg.org/) C 库。

## 安装

要处理音频数据集，您需要安装 `audio` 依赖项。请参阅 [安装](./installation#audio) 指南了解如何安装。

## 本地文件

您可以使用音频文件的路径来加载自己的数据集。使用 [cast_column()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Dataset.cast_column) 函数获取音频文件路径列，并将其转换为 [Audio](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Audio) 特征：

```py
>>> audio_dataset = Dataset.from_dict({"audio": ["path/to/audio_1", "path/to/audio_2", ..., "path/to/audio_n"]}).cast_column("audio", Audio())
>>> audio_dataset[0]["audio"]
<datasets.features._torchcodec.AudioDecoder object at 0x11642b6a0>
```

## AudioFolder

你也可以使用 `AudioFolder` 数据集构建器来加载数据集。它无需编写自定义数据加载器，因此非常适合快速创建和加载包含数千个音频文件的数据集。

## 带有元数据的 AudioFolder

要将音频文件与元数据信息关联起来，请确保您的数据集中包含一个 `metadata.csv` 文件。您的数据集结构可能如下所示：

```
folder/train/metadata.csv
folder/train/first_audio_file.mp3
folder/train/second_audio_file.mp3
folder/train/third_audio_file.mp3
```

`metadata.csv` 文件必须包含一个 `file_name` 列，用于将音频文件与其元数据关联起来。`metadata.csv` 文件的示例可能如下所示：

```text
file_name,transcription
first_audio_file.mp3,znowu się duch z ciałem zrośnie w młodocianej wstaniesz wiosnie i możesz skutkiem tych leków umierać wstawać wiek wieków dalej tam były przestrogi jak siekać głowę jak nogi
second_audio_file.mp3,już u źwierzyńca podwojów król zasiada przy nim książęta i panowie rada a gdzie wzniosły krążył ganek rycerze obok kochanek król skinął palcem zaczęto igrzysko
third_audio_file.mp3,pewnie kędyś w obłędzie ubite minęły szlaki zaczekajmy dzień jaki poślemy szukać wszędzie dziś jutro pewnie będzie posłali wszędzie sługi czekali dzień i drugi gdy nic nie doczekali z płaczem chcą jechać dali
```

`AudioFolder` 将加载音频数据并创建一个 `transcription` 列，其中包含来自 `metadata.csv` 的文本：

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_name")
>>> # OR locally:
>>> dataset = load_dataset("/path/to/folder")
```

对于本地数据集，这相当于在 [load_dataset()](/docs/datasets/v5.2.0/zh/package_reference/loading_methods#datasets.load_dataset) 中手动传入 `audiofolder` 以及 `data_dir` 中的目录：

```py
>>> dataset = load_dataset("audiofolder", data_dir="/path/to/folder")
```

元数据也可以以 JSON Lines 格式指定，此时请使用 `metadata.jsonl` 作为元数据文件的名称。当其中一列是复杂类型（例如浮点数列表）时，这种格式非常有用，可以避免解析错误或将复杂值读取为字符串。

若要忽略元数据文件中的信息，请在 [load_dataset()](/docs/datasets/v5.2.0/zh/package_reference/loading_methods#datasets.load_dataset) 中设置 `drop_metadata=True`：

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_with_metadata", drop_metadata=True)
```

如果没有元数据文件，`AudioFolder` 会自动从目录名推断标签名称。如果要丢弃自动创建的标签，请设置 `drop_labels=True`。在这种情况下，您的数据集将只包含一个音频列：

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_without_metadata", drop_labels=True)
```

最后，`filters` 参数允许你基于标签或元数据中的条件，仅加载数据集的一个子集。如果元数据采用 Parquet 格式，这一点尤其有用，因为该格式支持快速过滤。同时，建议将此参数与 `streaming=True` 一起使用，因为默认情况下，数据集会在过滤之前被完整下载。

```python
>>> filters = [("label", "=", 0)]
>>> dataset = load_dataset("username/dataset_name", streaming=True, filters=filters)
```

> [!TIP]
> 有关创建自己的 `AudioFolder` 数据集的更多信息，请参阅 [创建音频数据集](./audio_dataset) 指南。

如需了解如何加载任意类型的数据集，请参阅通用加载指南。

## 音频解码

默认情况下，在迭代数据集时，音频文件会按顺序解码为 [`AudioDecoder`](https://meta-pytorch.org/torchcodec/stable/generated/torchcodec.decoders.AudioDecoder.html#torchcodec.decoders.AudioDecoder) 对象。不过，使用多线程解码可以显著加快数据集的处理速度：

```python
>>> import os
>>> num_threads = num_threads = min(32, (os.cpu_count() or 1) + 4)
>>> dataset = dataset.decode(num_threads=num_threads)
>>> for example in dataset:  # up to 20 times faster !
...     ...
```

您可以使用 `num_threads` 来启用多线程。这对于加速远程数据流式传输特别有用。不过，对于位于高速磁盘上的本地数据，它可能比 `num_threads=0` 更慢。

如果您对解码为 NumPy 数组的图像不感兴趣，而是希望访问路径/字节，则可以禁用解码：

```python
>>> dataset = dataset.decode(False)
```

注意：[IterableDataset.decode()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.IterableDataset.decode) 目前仅适用于流式数据集。

