Main Content

writeall

Write datastore to files

Description

example

writeall(ADS,outputLocation) writes the data from the audio datastore ADS to files located at outputLocation.

example

writeall(ADS,outputLocation,Name,Value) writes the data with additional options specified by one or more name-value pair arguments.

Example: writeall(ADS,outputLocation,'OutputFormat','flac') writes the data to FLAC files.

Examples

collapse all

Create an audioDatastore object that points to the WAV audio samples included with Audio Toolbox™. The audioDatastore object includes read-only properties indicating the supported file formats, and the default output format (WAV).

folder = fullfile(matlabroot,'toolbox','audio','samples');
ads = audioDatastore(folder,'FileExtensions','.wav')
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 17 more
                              }
                     Folders: {
                              '/mathworks/devel/bat/Bdoc20b/build/matlab/toolbox/audio/samples'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "mp4"    "m4a"]
         DefaultOutputFormat: "wav"

Write the audio data set to your current folder. Save all files in the default (WAV) format.

outputLocation = pwd;
writeall(ads,outputLocation)

The folder, samples, and the audio files that the folder contains have been written to your current folder.

dir samples
.                                             
..                                            
Ambiance-16-44p1-mono-12secs.wav              
AudioArray-16-16-4channels-20secs.wav         
ChurchImpulseResponse-16-44p1-mono-5secs.wav  
Click-16-44p1-mono-0.2secs.wav                
Counting-16-44p1-mono-15secs.wav              
Engine-16-44p1-stereo-20sec.wav               
FemaleSpeech-16-8-mono-3secs.wav              
Heli_16ch_ACN_SN3D.wav                        
JetAirplane-16-11p025-mono-16secs.wav         
Laughter-16-8-mono-4secs.wav                  
MainStreetOne-16-16-mono-12secs.wav           
NoisySpeech-16-22p5-mono-5secs.wav            
Rainbow-16-8-mono-114secs.wav                 
RainbowNoisy-16-8-mono-114secs.wav            
RockGuitar-16-44p1-stereo-72secs.wav          
SpeechDFT-16-8-mono-5secs.wav                 
TrainWhistle-16-44p1-mono-9secs.wav           
Turbine-16-44p1-mono-22secs.wav               
WashingMachine-16-44p1-stereo-10secs.wav      
multipleSounds-16-16-mono-18secs.wav          

You can use pre-extracted features to reduce iteration time when developing a machine learning or deep learning system. It is also a common practice to use pre-extracted features for unsupervised learning tasks such as similarity clustering, and for content-based indexing tasks such as music information retrieval (MIR).

Create an audioDatastore object that points to the audio samples included with Audio Toolbox™.

folder = fullfile(matlabroot,"toolbox","audio","samples");
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 27 more
                              }
                     Folders: {
                              '/mathworks/devel/bat/Bdoc20b/build/matlab/toolbox/audio/samples'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "mp4"    "m4a"]
         DefaultOutputFormat: "wav"

Create a custom write function that extracts mel frequency cepstral coefficients (mfcc) from the audio and writes the them to a MAT file. The function definition is located at the end of this example.

function myWriter(audioIn,info,~)
    fs = info.ReadInfo.SampleRate;

    % Extract MFCC
    [coeffs,delta,deltaDelta] = mfcc(audioIn,fs);

    % Replace the file extension of the suggested output name with MAT.
    filename = strrep(info.SuggestedOutputName,".wav",".mat");

    % Save the MFCC coefficients to the MAT file.
    save(filename,"coeffs","delta","deltaDelta")
end

Define the output location for the extracted features.

outputLocation = pwd;

Call the writeall function with the audioDatastore object, output location, and custom write function. Also specify the suffix _MFCC to the file names.

tic
writeall(ads,outputLocation,"WriteFcn",@myWriter,"FilenameSuffix","_MFCC")
fprintf("Data set creation completed (%0.0f seconds)\n",toc)
Data set creation completed (290 seconds)

You have now created a data set consisting of MFCCs for each audio file.

fds = fileDatastore(pwd,"ReadFcn",@load,"FileExtensions",".mat","IncludeSubfolders",true)
fds = 
  FileDatastore with properties:

                       Files: {
                              ' .../audio-ex80013303/samples/Ambiance-16-44p1-mono-12secs_MFCC.mat';
                              ' .../audio-ex80013303/samples/AudioArray-16-16-4channels-20secs_MFCC.mat';
                              ' .../samples/ChurchImpulseResponse-16-44p1-mono-5secs_MFCC.mat'
                               ... and 27 more
                              }
                     Folders: {
                              '/tmp/Bdoc20b_1465442_41040/tp1af1251e/audio-ex80013303'
                              }
                 UniformRead: 0
                    ReadMode: 'file'
                   BlockSize: Inf
                  PreviewFcn: @load
      SupportedOutputFormats: [1x16 string]
                     ReadFcn: @load
    AlternateFileSystemRoots: {}

Helper Function

function myWriter(audioIn,info,~)
    fs = info.ReadInfo.SampleRate;
    [coeffs,delta,deltaDelta] = mfcc(audioIn,fs);
    filename = strrep(info.SuggestedOutputName,".wav",".mat");
    save(filename,"coeffs","delta","deltaDelta")
end

Create an audioDatastore object that points to the audio samples included with Audio Toolbox™.

folder = fullfile(matlabroot,"toolbox","audio","samples");
ads = audioDatastore(folder);

Create an audioDataAugmenter object that outputs two augmentations for every input signal.

augmenter = audioDataAugmenter("NumAugmentations",2);

Define a custom write function that applies the audioDataAugmenter object to an audio file and writes the resulting new signals to separate files. The function definition is located at the end of this example.

function myWriter(audioIn,info,fileExtension,varargin)
    % create convenient variables for the augmenter and sample rate
    augmenter = varargin{1};
    fs = info.ReadInfo.SampleRate;

    % perform augmentation
    augmentations = augment(augmenter,audioIn,fs);
    
    for ii = 1:augmenter.NumAugmentations
        x = augmentations.Audio{ii};

        % protect against clipping
        if any(x<-1|x>1)
            [S,L] = bounds(x);
            x = x/max(abs([S,L]));
        end

        % update the audio file name to include the augmentation number
        filename = insertBefore(info.SuggestedOutputName,("."+fileExtension),string(ii));

        % write the audio file
        audiowrite(filename,x,fs)
    end
end

Call the writeall function to create a new augmented data set. To speed up processing, set UseParallel to true.

outputLocation = pwd;
writeall(ads,outputLocation,"FilenameSuffix","_Aug","UseParallel",true,"WriteFcn",@(x,y,z,a)myWriter(x,y,z,augmenter))
Starting parallel pool (parpool) using the 'local' profile ...
Connected to the parallel pool (number of workers: 6).

Create a new datastore that points to the augmented audio data set.

adsAug = audioDatastore(outputLocation,"IncludeSubfolders",true)
adsAug = 
  audioDatastore with properties:

                       Files: {
                              ' ...\audio-ex06587246\samples\Ambiance-16-44p1-mono-12secs_Aug1.wav';
                              ' ...\audio-ex06587246\samples\Ambiance-16-44p1-mono-12secs_Aug2.wav';
                              ' ...\audio-ex06587246\samples\AudioArray-16-16-4channels-20secs_Aug1.wav'
                               ... and 55 more
                              }
                     Folders: {
                              ' ...\vmgr$\home07\bhemmat\Documents\MATLAB\Examples\audio-ex06587246'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "mp4"    "m4a"]
         DefaultOutputFormat: "wav"

Helper Function

function myWriter(audioIn,info,fileExtension,varargin)
    augmenter = varargin{1};
    fs = info.ReadInfo.SampleRate;
    augmentations = augment(augmenter,audioIn,fs);
    for ii = 1:augmenter.NumAugmentations
        x = augmentations.Audio{ii};
        if any(x<-1|x>1)
            x = x./max(abs(x));
        end
        filename = insertBefore(info.SuggestedOutputName,("."+fileExtension),string(ii));
        audiowrite(filename,x,fs)
    end
end

Use the detectSpeech and writeall functions to create a new audio data set that contains isolated speech segments.

Create an audioDatastore object that points to the audio samples included with this example.

ads = audioDatastore(pwd)
ads = 
  audioDatastore with properties:

                       Files: {
                              ' .../tpa8dd60ea/audio-ex78151030/KeywordSpeech-16-16-mono-34secs.flac';
                              '/tmp/Bdoc20b_1465442_1586/tpa8dd60ea/audio-ex78151030/Plosives.wav';
                              '/tmp/Bdoc20b_1465442_1586/tpa8dd60ea/audio-ex78151030/Sibilance.wav'
                              }
                     Folders: {
                              '/tmp/Bdoc20b_1465442_1586/tpa8dd60ea/audio-ex78151030'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "mp4"    "m4a"]
         DefaultOutputFormat: "wav"

Define a custom write function that first determines the regions of speech in the audio signals read from the datastore, then writes the individual regions of speech to separate files. Append the region number to the file names. The function definition is located at the end of this example.

function myWriter(audioIn,info,fileExtension)
    fs = info.ReadInfo.SampleRate;

    % Get indices corresponding to regions of speech
    idx = detectSpeech(audioIn,fs);

    % For each region of speech
    for ii = 1:size(idx,1)
        x = audioIn(idx(ii,1):idx(ii,2),:);
         
        % Create a unique file name
        filename = insertBefore(info.SuggestedOutputName,("."+fileExtension),string(ii));

        % Write the detected region of speech
        audiowrite(filename,x,fs)
    end
end

Call the writeall function using the custom write function to create a new data set that consists of the isolated speech segments. Create a folder named segmented in your temporary directory and then write the data to that folder.

outputLocation = fullfile(tempdir,"segmented");
writeall(ads,outputLocation,'WriteFcn',@myWriter)

Create a new audioDatastore object that points to the segmented data set.

adsSegmented = audioDatastore(outputLocation,"IncludeSubfolders",true)
adsSegmented = 
  audioDatastore with properties:

                       Files: {
                              ' .../segmented/audio-ex78151030/KeywordSpeech-16-16-mono-34secs1.wav';
                              ' .../segmented/audio-ex78151030/KeywordSpeech-16-16-mono-34secs10.wav';
                              ' .../segmented/audio-ex78151030/KeywordSpeech-16-16-mono-34secs11.wav'
                               ... and 24 more
                              }
                     Folders: {
                              '/tmp/Bdoc20b_1465442_1586/segmented'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "mp4"    "m4a"]
         DefaultOutputFormat: "wav"

Read a sample from the datastore and listen to it.

[audioIn,adsInfo] = read(adsSegmented);
sound(audioIn,adsInfo.SampleRate)

Supporting Function

function myWriter(audioIn,info,fileExtension)
    fs = info.ReadInfo.SampleRate;
    idx = detectSpeech(audioIn,fs);
    for ii = 1:size(idx,1)
        x = audioIn(idx(ii,1):idx(ii,2),:);
        filename = insertBefore(info.SuggestedOutputName,("."+fileExtension),string(ii));
        audiowrite(filename,x,fs)
    end
end

Audio data sets, especially open-source audio data sets, might have inconsistent sampling rates, numbers of channels, or durations. They might also contain garbage data, such as clips that are labeled as containing speech but contain silence.

It is often a first step in machine learning and deep learning workflows to clean the audio data set. This is particularly important for the validation and test data sets. Common types of cleaning include resampling, converting to mono or stereo, trimming or expanding the duration of clips to a consistent length, removing periods of silence, removing background noise, or gain normalization.

In this example, you clean an audio data set so that all the files have a sample rate of 16 kHz, are mono, are in the FLAC format, and are normalized such that the max absolute magnitude of a signal is 1.

Create an audioDatastore object that points to the audio samples included with Audio Toolbox™.

folder = fullfile(matlabroot,"toolbox","audio","samples");
ads = audioDatastore(folder);

Define a function to apply a sequence of operations on the audio data. The function definition is located at the end of this example.

function [audioOut,adsInfo] = myTransform(audioIn,adsInfo)
    fs = adsInfo.SampleRate;
    desiredFs = 16e3;
    
    % Convert to mono
    x = mean(audioIn,2);
    
    % Resample to 16 kHz
    y = resample(x,desiredFs,fs);
    adsInfo.SampleRate = desiredFs;
    
    % Normalize so that the max absolute value of a signal is 1 
    audioOut = y/max(abs(y));
end

Create a transform datastore object that applies the cleaning operations.

adsTransform = transform(ads,@myTransform,"IncludeInfo",true);

Call writeall on the transform datastore object to create the clean data set. Specify the format as FLAC. Write the data set to your current folder.

outputLocation = pwd;
writeall(adsTransform,outputLocation,"OutputFormat","flac")

Create a new datastore object that points to the clean data set.

adsClean = audioDatastore(outputLocation,"IncludeSubfolders",true)
adsClean = 
  audioDatastore with properties:

                       Files: {
                              ' ...\Examples\audio-ex59507606\samples\Ambiance-16-44p1-mono-12secs.flac';
                              ' ...\audio-ex59507606\samples\AudioArray-16-16-4channels-20secs.flac';
                              ' ...\samples\ChurchImpulseResponse-16-44p1-mono-5secs.flac'
                               ... and 26 more
                              }
                     Folders: {
                              ' ...\vmgr$\home07\bhemmat\Documents\MATLAB\Examples\audio-ex59507606'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "mp4"    "m4a"]
         DefaultOutputFormat: "wav"

Supporting Function

function [audioOut,adsInfo] = myTransform(audioIn,adsInfo)
    fs = adsInfo.SampleRate;
    desiredFs = 16e3;
    x = mean(audioIn,2);
    y = resample(x,desiredFs,fs);
    adsInfo.SampleRate = desiredFs;
    audioOut = y/max(abs(y));
end

Input Arguments

collapse all

Audio datastore, specified as an audioDatastore object.

Folder location to write data, specified as a character vector or string. You can specify a full or relative path in outputLocation.

Example: outputLocation = '../../dir/data'

Example: outputLocation = 'C:\Users\MyName\Desktop'

Data Types: char | string

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: 'FolderLayout','flatten'

Layout of files in output folder, specified as the comma-separated pair consisting of 'FolderLayout' and 'duplicate' or 'flatten'.

  • 'duplicate' –– Replicate the folder structure of the data that the audio datastore points to. Specify the FolderLayout as 'duplicate' to maintain correspondence between the input and output data sets.

  • 'flatten' –– Write all the files from the input to the specified output folder without any intermediate folders.

Data Types: char | string

Output file format, specified as the comma-separated pair consisting of 'OutputFormat' and 'wav', 'flac', 'ogg', 'mp4', or 'm4a'.

Data Types: char | string

Number of output bits per sample, specified as the comma-separated pair consisting of 'BitsPerSample' and an integer.

Dependencies

To enable this name-value pair argument, set OutputFormat to 'wav' or 'flac'.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Number of kilobits per second (kbit/s) used to compress audio files, specified as the comma-separated pair consisting of 'BitRate' and an integer. On Windows® 7 or later, the only valid values are 96, 128, 160, and 192.

In general, a larger BitRate value results in higher compression quality.

Dependencies

To enable this name-value pair argument, set OutputFormat to 'm4a' or 'mp4'.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Prefix added to file name, specified as the comma-separated pair consisting of 'FilenamePrefix' and a character vector or string.

The writeall function adds the specified prefix to the output file names. For example, the following code adds today's date as the prefix to all the output file names:

prefixText = string(datetime('today'));
writeall(ADS,'C:\myFolder','FilenamePrefix',prefixText);

Data Types: char | string

Suffix added to the file name, specified as the comma-separated pair consisting of 'FilenameSuffix' and a character vector or string. The file name suffix is applied before the file extension.

The writeall function adds the specified suffix to the output file names. For example, the following code adds the descriptive text 'clean' as the suffix to all the output file names:

writeall(ADS,'C:\myFolder','FilenameSuffix','clean');

Data Types: char | string

Indicator to write in parallel, specified as the comma-separated pair consisting of 'UseParallel' and false or true.

By default, the writeall function writes in serial. If you set UseParallel to true, then the writeall function writes the output files in parallel.

Note

Writing in parallel requires Parallel Computing Toolbox™.

Data Types: logical

Custom write function, specified as the comma-separated pair consisting of 'WriteFcn' and a function handle. The specified function is responsible for creating the output files. You can use WriteFcn to write data in a variety of formats, even if writeall does not directly support the output format.

Function Signature

The custom write function requires three input arguments: audioIn, info, and suggestedOutputType. The function can also accept additional inputs, such as name-value pairs, after the first three required inputs.

function myWriter(audioIn,info,suggestedOutputType,varargin)

  • audioIn contains data read from the input datastore ADS.

  • info is an object of type matlab.io.datastore.WriteInfo with fields listed in the table.

    FieldDescriptionType
    ReadInfoThe second output of the read method.struct
    SuggestedOutputNameA fully qualified, globally unique file name that meets the location and naming requirements.string
    LocationThe specified outputLocation passed to writeall.string

  • suggestedOutputType –– Suggested output file type.

Example Function

A simple write function that resamples audio to 44.1 kHz before writing.

function myWriter(data,info,~)
  fs = info.ReadInfo.SampleRate;
  desiredFs = 44.1e3;
  data = resample(data,desiredFs,fs);
  audiowrite(writeInfo.SuggestedOutputName,data,desiredFs);
end
To use myWriter as in the writeall function, use these commands:
ads = audioDatastore(location);
outputLocation = 'C:/tmp/MyData';
writeall(ads,outputLocation,'WriteFcn',@myWriter)

Data Types: function_handle

Introduced in R2020a