Datastore for collection of audio files
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.
ADS = audioDatastore(location)ADS based on an audio file or collection of audio
files in location.
ADS = audioDatastore(location,Name,Value)
location — Files or folders to include in datastoreDsFileSet objectFiles or folders included in the datastore,
specified as a path or a DsFileSet object.
path — Specify the path as a character vector, cell array of character
vectors, string scalar, or a string array, containing the location of files or
folders. Specify location as a local path to files or
folders. If the files are not in the current folder, then local path must
specify full or relative paths. Files within subfolders of the 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.
DsFileSet object — You also can specify
location as a DsFileSet object. For more
information, see matlab.io.datastore.DsFileSet.
When location represents a folder, the datastore
includes only supported file formats and ignores any other format. To specify a custom
list of file extensions to include in your datastore, see the
FileExtensions property.
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
comma-separated pairs of Name,Value arguments. Name is
the argument name and Value is the corresponding value.
Name must appear inside quotes. You can specify several name and value
pair arguments in any order as
Name1,Value1,...,NameN,ValueN.
ADS =
audioDatastore('C:\dir\audiodata','FileExtensions','.ogg')'IncludeSubfolders' — Subfolder inclusion flagfalse (default) | trueSubfolder inclusion flag, specified as the comma-separated pair consisting of
'IncludeSubfolders' and true or
false. Specify true to include all files and
subfolders within each folder or false to include only the files
within each folder.
If you do not specify 'IncludeSubfolders', then the default
value is false.
Example: 'IncludeSubfolders',true
Data Types: logical | double
'LabelSource' — Source providing label data'none' (default) | 'foldernames'Source providing label data, specified as the comma-separated pair consisting of
'LabelSource' and '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 extensionsAudio file extensions, specified as the comma-separated pair consisting of
'FileExtensions' and 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
Example: 'FileExtensions','.wav'
Example: 'FileExtensions',{'.mp3','.mp4'}
Data Types: char | cell | string
In addition to these name-value pairs, you also can specify any of the properties on
this page as name-value pairs, except for the Files property.
Files — Files included in datastoreFiles 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 datastoreThis 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 labelsFile 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) | 'native'Data type of the output, specified as 'double' or
'native'.
'double' –– Double-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.
The default value of this property is 'double'.
Data Types: char | string
AlternateFileSystemRoots — Alternate file system root pathsAlternate 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","mp4","m4a"]This property is read-only.
Formats supported for writing audio files when using the writeall
function, specified as ["wav","flac","ogg","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, specified as "wav".
Data Types: string
read | Read next consecutive audio file |
readall | Read all audio files 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 |
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: {
' .../build/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 26 more
}
Folders: {
'/mathworks/devel/bat/BR2020ad/build/matlab/toolbox/audio/samples'
}
AlternateFileSystemRoots: {}
OutputDataType: 'double'
Labels: {}
SupportedOutputFormats: ["wav" "flac" "ogg" "mp4" "m4a"]
DefaultOutputFormat: "wav"
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: {
' .../build/matlab/toolbox/audio/samples/SoftGuitar-44p1_mono-10mins.ogg'
}
Folders: {
'/mathworks/devel/bat/BR2020ad/build/matlab/toolbox/audio/samples'
}
AlternateFileSystemRoots: {}
OutputDataType: 'double'
Labels: {}
SupportedOutputFormats: ["wav" "flac" "ogg" "mp4" "m4a"]
DefaultOutputFormat: "wav"
You have a modified version of this example. Do you want to open this example with your edits?