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
Description
creates a datastore ADS
= audioDatastore(location
)ADS
based on an audio file or collection of audio
files in location
.
specifies additional properties using one or more name-value arguments.ADS
= audioDatastore(location
,Name=Value
)
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 aFileSet
object leads to a faster construction time for datastores compared to specifying a path orDsFileSet
object. For more information, seematlab.io.datastore.FileSet
.DsFileSet
object — For more information, seematlab.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:///
. Internet URLs must include the protocol typepath_to_file
"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
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 toaudioread
for more information about data types whenOutputDataType
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.2679053/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.2679053/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 agpuArray
object by setting theOutputEnvironment
property to"gpu"
.
Version History
Introduced in R2018bR2024a: 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
).
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)