Implementation:Huggingface Datasets AudioFolder Builder

Knowledge Sources	Huggingface Datasets HF Datasets Docs
Domains	Data_Loading, Audio
Last Updated	2026-02-14 18:00 GMT

Overview

Folder-based dataset builder for loading audio files organized in directories, provided by the HuggingFace Datasets library.

Description

AudioFolder is a packaged dataset builder that extends FolderBasedBuilder and loads audio files from directory structures. It is paired with AudioFolderConfig, which extends FolderBasedBuilderConfig with optional drop_labels and drop_metadata parameters.

The builder sets BASE_FEATURE = datasets.Audio and BASE_COLUMN_NAME = "audio", establishing that each loaded file is treated as an audio feature in a column named "audio". Directory names can be automatically used as classification labels (unless drop_labels=True), and metadata files (e.g., metadata.csv or metadata.jsonl) can provide additional columns.

The EXTENSIONS class attribute is populated at module level with a comprehensive list of supported audio and video container formats, including .wav, .mp3, .flac, .ogg, .opus, .aiff, .mp4, .webm, and many others. Both the lowercase extensions and their uppercase counterparts are registered in the extension-to-module mapping.

Usage

Use this builder via load_dataset("audiofolder", data_dir=...) to load audio datasets organized in folders. It is also triggered automatically when files with recognized audio extensions are detected by the dataset loading pipeline.

Code Reference

Source Location

• Repository: datasets
• File: src/datasets/packaged_modules/audiofolder/audiofolder.py
• Lines: 1-86

Signature

class AudioFolderConfig(folder_based_builder.FolderBasedBuilderConfig):
    """Builder Config for AudioFolder."""
    drop_labels: bool = None
    drop_metadata: bool = None

class AudioFolder(folder_based_builder.FolderBasedBuilder):
    BASE_FEATURE = datasets.Audio
    BASE_COLUMN_NAME = "audio"
    BUILDER_CONFIG_CLASS = AudioFolderConfig
    EXTENSIONS: list[str]  # set at module level

Supported extensions (set at module level):

AUDIO_EXTENSIONS = [
    ".aiff", ".au", ".avr", ".caf", ".flac", ".htk", ".svx",
    ".mat4", ".mat5", ".mpc2k", ".ogg", ".paf", ".pvf", ".raw",
    ".rf64", ".sd2", ".sds", ".ircam", ".voc", ".w64", ".wav",
    ".nist", ".wavex", ".wve", ".xi", ".mp3", ".opus",
    ".3gp", ".3g2", ".avi", ".asf", ".flv", ".mp4", ".mov",
    ".m4v", ".mkv", ".mpg", ".webm", ".f4v", ".wmv", ".wma",
    ".ogg", ".ogm", ".mxf", ".nut",
]
AudioFolder.EXTENSIONS = AUDIO_EXTENSIONS

Import

# Used via load_dataset
from datasets import load_dataset
ds = load_dataset("audiofolder", data_dir="path/to/audio_directory")

I/O Contract

Inputs

Name	Type	Required	Description
data_dir	str	Yes	Path to the root directory containing audio files, optionally organized in subdirectories by label.
data_files	str, list, or dict	No	Explicit file paths or patterns. Alternative to data_dir.
drop_labels	bool	No	If True, do not infer labels from directory names. Defaults to None (auto-detect).
drop_metadata	bool	No	If True, ignore metadata files. Defaults to None (auto-detect).

Outputs

Name	Type	Description
dataset	Dataset or DatasetDict	The loaded dataset containing an "audio" column with Audio features, plus optional "label" and metadata columns.

Usage Examples

Basic Usage

from datasets import load_dataset

# Load audio files from a directory (labels inferred from subdirectory names)
# data/
#   cats/
#     cat_001.wav
#     cat_002.wav
#   dogs/
#     dog_001.wav
#     dog_002.wav
ds = load_dataset("audiofolder", data_dir="data/", split="train")
print(ds[0])
# {'audio': {'path': 'data/cats/cat_001.wav', 'array': array([...]), 'sampling_rate': 16000}, 'label': 0}

Without Labels

from datasets import load_dataset

# Load without inferring labels from directory structure
ds = load_dataset("audiofolder", data_dir="data/", drop_labels=True, split="train")
print(ds.column_names)  # ['audio']

With Metadata File

from datasets import load_dataset

# data/
#   metadata.csv  (columns: file_name, transcription, speaker_id)
#   audio_001.wav
#   audio_002.wav
ds = load_dataset("audiofolder", data_dir="data/", split="train")
print(ds.column_names)  # ['audio', 'transcription', 'speaker_id']

Related Pages

Implements Principle

• Principle:Huggingface_Datasets_AudioFolder_Dataset_Building