Main Content

audioDatastore

数据存储for collection of audio files

expand all in page

Description

Use anaudioDatastoreobject 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 datastoreADSbased on an audio file or collection of audio files inlocation.

example

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

Input Arguments

expand all

Files or folders included in the datastore, specified as aFileSetobject, as file paths, or as aDsFileSetobject.

  • FileSetobject — You can specifylocationas aFileSetobject. Specifying the location as aFileSetobject leads to a faster construction time for datastores compared to specifying a path orDsFileSetobject. For more information, seematlab.io.datastore.FileSet.

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

  • DsFileSetobject — You can specify aDsFileSetobject. For more information, seematlab.io.datastore.DsFileSet.

Files or folders may be local or remote:

  • Local files or folders — Specify local paths to files or folders. If the files are not in the current folder, then 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.

  • Remote files or folders — Specify full paths to remote files or folders as a uniform resource locator (URL) of the formhdfs:///path_to_file. For more information, seeWork 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 theFileExtensionsproperty.

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 asName1=Value1,...,NameN=ValueN, whereNameis the argument name andValueis the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and encloseNamein quotes.

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

Subfolder inclusion flag, specified as the comma-separated pair consisting of'IncludeSubfolders'andtrueorfalse. Specifytrueto include all files and subfolders within each folder orfalseto include only the files within each folder.

If you do not specify'IncludeSubfolders', then the default value isfalse.

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 theLabelsproperty is empty. If'foldernames'is specified, then labels are assigned according to the folder names and stored in theLabelsproperty. You can later modify the labels by accessing theLabelsproperty 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', thenaudioDatastoreautomatically 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 theFilesproperty.

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. Thelocationargument in theaudioDatastoredefinesFileswhen the datastore is created.

Data Types:char|cell|string

This property is read-only.

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

Data Types:cell

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 specifyLabelSourceas'foldernames'when creating theaudioDatastoreobject, then the label name for a file is the name of the folder containing it. If you do not specifyLabelSourceas'foldernames', thenLabelsis an empty cell array or string array. If you change theFilesproperty after the datastore is created, then theLabelsproperty 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 toaudioreadfor more information about data types whenOutputDataTypeis set to native.

The default value of this property is'double'.

Data Types:char|string

替代的文件系统根路径,指定为一个年代tring row vector, a cell array of string vectors, or a cell array of character vectors. UseAlternateFileSystemRootswhen 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™ andMATLAB®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 useAlternateFileSystemRootsto associate the root paths.

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

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

  • To associate multiple sets of root paths that are equivalent for the datastore, specifyAlternateFileSystemRootsas 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:

    • SpecifyAlternateFileSystemRootsas a cell array of string vectors.

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

    • Alternatively, specifyAlternateFileSystemRootsas a cell array of cell arrays of character vectors.

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

The value ofAlternateFileSystemRootsmust satisfy these conditions:

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

  • 每一行指定多个根路径,每个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

This property is read-only.

Formats supported for writing audio files when using thewriteallfunction, specified as["wav","flac","ogg","mp4","m4a"].

Data Types:string

This property is read-only.

Default output format for writing audio files when using thewriteallfunction, specified as"wav".

Data Types:string

Object Functions

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

Examples

collapse all

Open Live Script

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 31 more } Folders: { '/mathworks/devel/bat/Bdoc22a/build/matlab/toolbox/audio/samples' } AlternateFileSystemRoots: {} OutputDataType: 'double' Labels: {} SupportedOutputFormats: ["wav" "flac" "ogg" "mp4" "m4a"] DefaultOutputFormat: "wav"
Open Live Script

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.oggfiles in the specified folder.

ADS = audioDatastore(folder,'FileExtension','.ogg')
ADS = audioDatastore with properties: Files: { ' .../build/matlab/toolbox/audio/samples/FemaleVolumeUp-16-mono-11secs.ogg'; ' .../bat/Bdoc22a/build/matlab/toolbox/audio/samples/Hey-16-mono-6secs.ogg'; ' .../build/matlab/toolbox/audio/samples/MaleVolumeUp-16-mono-6secs.ogg' ... and 2 more } Folders: { '/mathworks/devel/bat/Bdoc22a/build/matlab/toolbox/audio/samples' } AlternateFileSystemRoots: {} OutputDataType: 'double' Labels: {} SupportedOutputFormats: ["wav" "flac" "ogg" "mp4" "m4a"] DefaultOutputFormat: "wav"

版本历史

Introduced in R2018b

See Also

||

Topics