Main Content

writeall

Write datastore to files

Since R2020a

collapse all in page

Syntax

writeall(ADS,outputLocation)
writeall(ADS,outputLocation,Name=Value)

Description

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

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

example

Examples

collapse all

Open Live Script

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: {
                              ' .../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: {
                              ' .../Bdoc24b.2725827/build/runnable/matlab/toolbox/audio/samples'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
           OutputEnvironment: 'cpu'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "opus"    "mp3"    "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
Open Live Script

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: {
                              ' .../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.2725827/build/runnable/matlab/toolbox/audio/samples'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
           OutputEnvironment: 'cpu'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "opus"    "mp3"    "mp4"    "m4a"]
         DefaultOutputFormat: "wav"

Create a custom write function that extracts mel frequency cepstral coefficients (mfcc) from the audio and writes 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 (14 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 36 more
                              }
                     Folders: {
                              '/tmp/Bdoc24b_2725827_3865233/tp964e69e1/audio-ex80013303'
                              }
                 UniformRead: 0
                    ReadMode: 'file'
                   BlockSize: Inf
                  PreviewFcn: @load
      SupportedOutputFormats: ["txt"    "csv"    "dat"    "asc"    "xlsx"    "xls"    "parquet"    "parq"    "png"    "jpg"    "jpeg"    "tif"    "tiff"    "wav"    "flac"    "ogg"    "opus"    "mp3"    "mp4"    "m4a"]
                     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
Open Live Script

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, myWriter, that applies the audioDataAugmenter object to an audio file and writes the resulting new signals to separate files.

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))

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

adsAug = audioDatastore(outputLocation,IncludeSubfolders=true);

myWriter Helper Function

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)
            x = x./max(abs(x));
        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
Open Live Script

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: {
                              ' .../tp9f84dd73/audio-ex78151030/KeywordSpeech-16-16-mono-34secs.flac';
                              '/tmp/Bdoc24b_2725827_3867044/tp9f84dd73/audio-ex78151030/Plosives.wav';
                              '/tmp/Bdoc24b_2725827_3867044/tp9f84dd73/audio-ex78151030/Sibilance.wav'
                              }
                     Folders: {
                              '/tmp/Bdoc24b_2725827_3867044/tp9f84dd73/audio-ex78151030'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
           OutputEnvironment: 'cpu'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "opus"    "mp3"    "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/Bdoc24b_2725827_3867044/segmented'
                              }
    AlternateFileSystemRoots: {}
              OutputDataType: 'double'
           OutputEnvironment: 'cpu'
                      Labels: {}
      SupportedOutputFormats: ["wav"    "flac"    "ogg"    "opus"    "mp3"    "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
Open Live Script

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, myTransform, that applies a sequence of operations on the audio data. 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);

myTransform Supporting Function

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

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 Arguments

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: FolderLayout="flatten"

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'FolderLayout','flatten'

Layout of files in output folder, specified as "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 "wav", "flac", "ogg", "opus", "mp3", "mp4", or "m4a".

Data Types: char | string

Number of output bits per sample, specified as 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 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

Quality setting for MP3, OGG, or OPUS files, specified as a number in the range [0, 100], where 0 is lower quality and higher compression, and 100 is higher quality and lower compression.

Dependencies

To enable this name-value pair argument, set OutputFormat to "mp3", "ogg" or "opus".

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

Prefix added to file name, specified 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 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 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 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

Version History

Introduced in R2020a

expand all

See Also