audioDatastore

Datastore for collection of audio files

Description

Use an audioDatastore object to manage a collection of audio files, where each individual audio file fits in memory, but the entire collection of audio files does not necessarily fit.

Creation

Syntax

ADS = audioDatastore(location)

ADS = audioDatastore(location,Name=Value)

Description

ADS = audioDatastore(location) creates a datastore ADS based on an audio file or collection of audio files in location.

ADS = audioDatastore(location,Name=Value) specifies additional properties using one or more name-value arguments.

Input Arguments

location — Files or folders to include in datastore

FileSet object | path | DsFileSet object

Files or folders to include in the datastore, specified as one of these values:

• FileSet object — Specifying the location as a FileSet object leads to a faster construction time for datastores compared to specifying a path or DsFileSet object. For more information, see matlab.io.datastore.FileSet.

• DsFileSet object — For more information, see matlab.io.datastore.DsFileSet.

• File path — You can specify a single file path as a string scalar or character vector. You can specify multiple file paths as a string array or cell array of character vectors.

Files or folders can be local or remote:

• Local files or folders — If the files are not in the current folder, then specify full or relative paths. Files within subfolders of a specified folder are not automatically included in the datastore. You can use the wildcard character (*) when specifying the local path. This character specifies that the datastore include all matching files or all files in the matching folders.

• Remote files or folders — Specify full paths to remote files or folders as a uniform resource locator (URL) of the form hdfs:///path_to_file. Internet URLs must include the protocol type "http://" or "https://". For more information, see Work with Remote Data.

When you specify a folder, the datastore includes only files with supported file formats and ignores files with any other format. To specify a custom list of file extensions to include in your datastore, see the FileExtensions name-value argument.

Example: 'song.wav'

Example: '../dir/music/song.wav'

Example: {'C:\dir\music\song.wav','C:\dir\speech\english.mp3'}

Example: 'C:\dir\music\*.ogg'

Data Types: char | string | cell

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: ADS = audioDatastore("C:\dir\audiodata",FileExtensions=".ogg")

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

IncludeSubfolders — Subfolder inclusion flag

false (default) | true

Subfolder inclusion flag, specified as true or false. Specify true to include all files and subfolders within each folder or false to include only the files within each folder.

Data Types: logical | double

LabelSource — Source providing label data

"none" (default) | "foldernames"

Source providing label data, specified as "none" or "foldernames". If "none" is specified, then the Labels property is empty. If "foldernames" is specified, then labels are assigned according to the folder names and stored in the Labels property. You can later modify the labels by accessing the Labels property directly.

Data Types: char | string

FileExtensions — Audio file extensions

character vector | cell array of character vectors | string scalar | string array

Audio file extensions, specified as a character vector, cell array of character vectors, string scalar, or string array. If you do not specify FileExtensions, then audioDatastore automatically includes all supported file types:

• .wav

• .avi

• .aif

• .aifc

• .aiff

• .mp3

• .au

• .snd

• .mp4

• .m4a

• .flac

• .ogg

• .mov

• .opus

Example: FileExtensions=".wav"

Example: FileExtensions={'.mp3','.mp4'}

Data Types: char | cell | string

In addition to these name-value arguments, you also can specify any of the properties on this page as name-value arguments, except for the Files property.

Properties

Files — Files included in datastore

character vector | cell array of character vectors | string scalar | string array

Files included in the datastore, specified as a character vector, cell array of character vectors, string scalar, or string array. Each character vector or string is a full path to a file. The location argument in the audioDatastore defines Files when the datastore is created.

Data Types: char | cell | string

Folders — Folders used to create audio datastore

N-by-1 cell array of character vectors

This property is read-only.

Folders used to create the audio datastore, returned as an N-by-1 cell array of character vectors. Each row specifies a unique folder containing audio files that the audioDatastore object points to.

Data Types: cell

Labels — File labels

categorical, logical, or numeric vector | cell array | string array | table

File labels for the files in the datastore, specified as a vector, a cell array, a string array, or a table. The order of the labels in the array or table corresponds to the order of the associated files in the datastore.

If you specify LabelSource as "foldernames" when creating the audioDatastore object, then the label name for a file is the name of the folder containing it. If you do not specify LabelSource as "foldernames", then Labels is an empty cell array or string array. If you change the Files property after the datastore is created, then the Labels property is not automatically updated to incorporate the added fields.

Data Types: categorical | cell | logical | double | single | string | table

OutputDataType — Data type of output read

"double" (default) | "single" | "native"

Data type of the output, specified as "double", "single", or "native".

• "double" –– Double-precision normalized samples.

• "single" –– Single-precision normalized samples.

• "native" –– Native data type found in the file. Refer to audioread for more information about data types when OutputDataType is set to native.

Data Types: char | string

OutputEnvironment — Hardware resource for output data

"cpu" (default) | "gpu"

Hardware resource for output data, specified as "cpu" or "gpu".

• "cpu" –– Return variables on the CPU.

• "gpu" –– Return variables on the GPU.

Using a GPU requires Parallel Computing Toolbox™ and a supported GPU device. For information on supported devices, see GPU Computing Requirements (Parallel Computing Toolbox).

Data Types: char | string

AlternateFileSystemRoots — Alternate file system root paths

string row vector | cell array of string vectors | cell array of character vectors

Alternate file system root paths, specified as a string row vector, a cell array of string vectors, or a cell array of character vectors. Use AlternateFileSystemRoots when you create a datastore on a local machine but must access and process data on another machine (possibly of a different operating system). Also, when processing data using Parallel Computing Toolbox and MATLAB^® Parallel Server™, and the data is stored on your local machines with a copy of the data available on different platform cloud or cluster machines, you must use AlternateFileSystemRoots to associate the root paths.

• To associate a set of root paths that are equivalent to one another, specify AlternateFileSystemRoots as a string vector. For example:

  ["Z:\datasets","/mynetwork/datasets"]

• To associate multiple sets of root paths that are equivalent for the datastore, specify AlternateFileSystemRoots as a cell array containing multiple rows, where each row represents a set of equivalent root paths. Specify each row in the cell array as either a string vector or a cell array of character vectors. For example:

  • Specify AlternateFileSystemRoots as a cell array of string vectors.

    {["Z:\datasets", "/mynetwork/datasets"]; ...
     ["Y:\datasets", "/mynetwork2/datasets","S:\datasets"]}

  • Alternatively, specify AlternateFileSystemRoots as a cell array of cell arrays of character vectors.

    {{'Z:\datasets', '/mynetwork/datasets'}; ...
     {'Y:\datasets", '/mynetwork2/datasets','S:\datasets'}}

The value of AlternateFileSystemRoots must satisfy these conditions:

• Contains one or more rows, where each row specifies a set of equivalent root paths.

• Each row specifies multiple root paths, and each root path must contain at least two characters.

• Root paths are unique and are not subfolders of one another.

• Contains at least one root path entry that points to the location of the files.

Data Types: char | cell | string

SupportedOutputFormats — Formats supported for writing audio files

["wav","flac","ogg","opus","mp3","mp4","m4a"]

This property is read-only.

Formats supported for writing audio files when using the writeall function, returned as ["wav","flac","ogg","opus","mp3","mp4","m4a"].

Data Types: string

DefaultOutputFormat — Default output audio file format

"wav" (default)

This property is read-only.

Default output format for writing audio files when using the writeall function, returned as "wav".

Data Types: string

Object Functions

read	Read next consecutive audio file
readall	Read all audio files from datastore
readfile	Read specified audio file from datastore
reset	Reset datastore read pointer to start of data
hasdata	Return true if there is more data in datastore
shuffle	Shuffle files in datastore
subset	Create datastore with subset of files
preview	Read first file from datastore for preview
progress	Fraction of files read
splitEachLabel	Splits datastore according to specified label proportions
countEachLabel	Count number of unique labels
partition	Partition datastore and return on partitioned portion
numpartitions	Return estimate for reasonable number of partitions for parallel processing
combine	Combine data from multiple datastores
transform	Transform audio datastore
writeall	Write datastore to files
isPartitionable	Determine whether datastore is partitionable
isShuffleable	Determine whether datastore is shuffleable

Examples

Create Audio Datastore

Specify the file path to the audio samples included with Audio Toolbox™.

folder = fullfile(matlabroot,'toolbox','audio','samples');

Create an audio datastore that points to the specified folder.

ADS = audioDatastore(folder)

ADS = 
  audioDatastore with properties:

                       Files: {
                              ' .../matlab/toolbox/audio/samples/Ambiance-16-44p1-mono-12secs.wav';
                              ' .../matlab/toolbox/audio/samples/AudioArray-16-16-4channels-20secs.wav';
                              ' .../toolbox/audio/samples/ChurchImpulseResponse-16-44p1-mono-5secs.wav'
                               ... and 36 more
                              }
                     Folders: {
                              ' .../Bdoc24b.2725827/build/runnable/matlab/toolbox/audio/samples'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
           OutputEnvironment: 'cpu'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "opus"    "mp3"    "mp4"    "m4a"]
         DefaultOutputFormat: "wav"

Specify File Extensions to Include

Specify the file path to the audio samples included with Audio Toolbox™.

folder = fullfile(matlabroot,'toolbox','audio','samples');

Create an audio datastore that points to the .ogg files in the specified folder.

ADS = audioDatastore(folder,'FileExtension','.ogg')

ADS = 
  audioDatastore with properties:

                       Files: {
                              ' .../runnable/matlab/toolbox/audio/samples/CleanSpeech-16-mono-3secs.ogg';
                              ' .../matlab/toolbox/audio/samples/FemaleVolumeUp-16-mono-11secs.ogg';
                              ' .../build/runnable/matlab/toolbox/audio/samples/Hey-16-mono-6secs.ogg'
                               ... and 5 more
                              }
                     Folders: {
                              ' .../Bdoc24b.2725827/build/runnable/matlab/toolbox/audio/samples'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
           OutputEnvironment: 'cpu'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "opus"    "mp3"    "mp4"    "m4a"]
         DefaultOutputFormat: "wav"

Specify Output Data Options

Create an audioDatastore object containing WAV and MP3 files. Set OutputDataType to "single" and OutputEnvironment to "gpu" to output single-precision data stored on the GPU.

folder = fullfile(matlabroot,"toolbox","audio","samples");
ads = audioDatastore(folder,FileExtensions=[".wav",".mp3"], ...
    OutputDataType="single",OutputEnvironment="gpu");

Create an audioFeatureExtractor object to extract the pitch and mel-frequency cepstral coefficients (MFCCs). Call extract on the datastore to read single-precision data from the files onto the GPU and perform the feature extraction. Setting SampleRateMismatchRule to "resample" resamples the audio signals whose sample rate does not match that of the audioFeatureExtractor object.

Using single-precision data and running code on the GPU can speed up computations.

afe = audioFeatureExtractor(pitch=true,mfcc=true);
features = extract(afe,ads,SampleRateMismatchRule="resample");

Extended Capabilities

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The audioDatastore function supports GPU array input with these usage notes and limitations:

• This object can generate GPU arrays, but does not run on a GPU. An audioDatastore object can return data on the GPU in a gpuArray object by setting the OutputEnvironment property to "gpu".

Version History

Introduced in R2018b

R2024a: Read specified audio file

Use the readfile object function to read a specified audio file from the datastore.

R2024a: GPU and single-precision options for output data

Set the OutputDataType property of the audioDatastore object to "single" to return single-precision data. Set OutputEnvironment to "gpu" to return data on the GPU.

R2024a: Support for writing MP3 files

The audioDatastore object supports writing MP3 files (.mp3).

R2022b: Support for OPUS audio file format

The audioDatastore object supports reading and writing OPUS file format (.opus).