This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

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

example

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

example

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

Input Arguments

expand all

Files or folders to include in the datastore, specified as a character vector, cell array of character vectors, string scalar, or string array. If the files are not in the current folder, then location must be full or relative paths. Files within subfolders of the specified folder are not automatically included in the datastore. Use the IncludeSubfolders property to include files within subfolders in the datastore.

You can use the wildcard character (*) when specifying location. This character indicates that all matching files or all files in the matching folders are included in the datastore.

If the files are not available locally, then the full path of the files or folders must be an internationalized resource identifier (IRI), such as hdfs:///path_to_file.

For information on using the datastore with Amazon S3™, Windows Azure® Blob Storage, and HDFS™, see Work with Remote Data (MATLAB).

When location represents a folder, the datastore includes only files in supported audio file formats and ignores any other files.

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 Pair Arguments

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.

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

Subfolder 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

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

Audio 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.

Properties

expand all

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

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

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

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® Distributed Computing 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

Object Functions

readRead next consecutive audio file
readallRead all audio files from datastore
resetReset datastore read pointer to start of data
hasdataReturn true if there is more data in datastore
shuffleShuffle files in datastore
subsetCreate datastore with subset of files
previewRead first file from datastore for preview
progressFraction of files read
splitEachLabelSplits datastore according to specified label proportions
countEachLabelCount number of unique labels
partitionPartition datastore and return on partitioned portion
numpartitionsReturn estimate for reasonable number of partitions for parallel processing

Examples

collapse all

Specify the file path to the audio samples included with Audio System 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
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
                      Labels: {}

Specify the file path to the audio samples included with Audio System 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'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
                      Labels: {}

Introduced in R2018b