audioDataAugmenter
Augment audio data
Description
Enlarge your audio dataset using audio-specific augmentation techniques like pitch shifting, time-scale modification, time shifting, noise addition, and volume control. You can create cascaded or parallel augmentation pipelines to apply multiple algorithms deterministically or probabilistically.
Creation
Description
creates an audio
data augmenter object with default property values.aug
= audioDataAugmenter()
specifies nondefault properties for aug
= audioDataAugmenter(Name,Value
)aug
using one or more name-value
arguments.
Properties
Augmentation Pipeline
AugmentationMode
— Augmentation mode
'sequential'
(default) | 'independent'
Augmentation mode, specified as 'sequential'
or
'independent'
.
'sequential'
–– Augmentation algorithms are applied sequentially (in series).'independent'
–– Augmentation algorithms are applied independently (in parallel).
Data Types: char
| string
AugmentationParameterSource
— Source of augmentation parameters
'random'
(default) | 'specify'
Source of augmentation parameters, specified as 'random'
or
'specify'
.
'random'
–– Augmentation algorithms are applied probabilistically using a probability parameter and a range parameter.For example, to create an
audioDataAugmenter
that applies time-stretching using a speedup factor between0.5
and1.5
with a 60% probability, enter the following in the Command Window:When time-stretching is applied, the speedup factor is drawn from a uniform distribution centered at 1 (the mean of the range) with a minimum ofaug = audioDataAugmenter('AugmentationParameterSource','random', ... 'TimeStretchProbability',0.6, ... 'SpeedupFactorRange',[0.5,1.5]);
0.5
and a maximum of1.5
.'specify'
–– Augmentation algorithms are applied deterministically using a logical parameter and a specified parameter value. For example, to create anaudioDataAugmenter
that applies time-stretching using a1.5
speedup factor with a 100% probability, enter the following in the Command Window:aug = audioDataAugmenter('AugmentationParameterSource','specify', ... 'ApplyTimeStretch',true, ... 'SpeedupFactor',1.5);
Data Types: char
| string
NumAugmentations
— Number of augmented signals to output
1
(default) | positive integer
Number of augmented signals to output, specified as a positive integer.
Dependencies
To enable this property, set AugmentationParameterSource to 'random'
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
Stretch Time
TimeStretchProbability
— Probability of applying time stretch
0.5
(default) | scalar in the range [0, 1]
Probability of applying time stretch, specified as a scalar in the range [0, 1].
Set the probability to 1
to apply time stretching every time you
call augment
. Set
the probability to 0
to skip time stretching every time you call
augment
.
Dependencies
To enable this property, set AugmentationParameterSource to 'random'
and
AugmentationMode to 'sequential'
.
Data Types: single
| double
SpeedupFactorRange
— Range of time stretch speedup factor
[0.8 1.2]
(default) | two-element row vector of positive nondecreasing values
Range of time stretch speedup factor, specified as a two-element row vector of positive nondecreasing values.
Dependencies
To enable this property, set AugmentationParameterSource to 'random'
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
ApplyTimeStretch
— Apply time stretch
true
(default) | false
Apply time stretch, specified as true
or
false
.
Dependencies
To enable this property, set AugmentationParameterSource to 'specify'
.
Data Types: logical
SpeedupFactor
— Time stretch speedup factor
0.8
(default) | real positive scalar | real positive vector
Time stretch speedup factor, specified as a scalar or vector of real positive values.
Dependencies
To enable this property, set AugmentationParameterSource to 'specify'
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
Shift Pitch
PitchShiftProbability
— Probability of applying pitch shift
0.5
(default) | scalar in the range [0, 1]
Probability of applying pitch shift, specified as a scalar in the range [0, 1].
Set the probability to 1
to apply pitch shifting every time you
call augment
. Set
the probability to 0
to skip pitch shifting every time you call
augment
.
Dependencies
To enable this property, set AugmentationParameterSource to 'random'
and
AugmentationMode to 'sequential'
.
Data Types: single
| double
SemitoneShiftRange
— Range of pitch shift (semitones)
[-2,2]
(default) | two-element row vector of nondecreasing values
Range of pitch shift in semitones, specified as a two-element row vector of nondecreasing values.
Dependencies
To enable this property, set AugmentationParameterSource to 'random'
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
ApplyPitchShift
— Apply pitch shift
true
(default) | false
Apply pitch shift, specified as true
or
false
.
Dependencies
To enable this property, set AugmentationParameterSource to 'specify'
.
Data Types: logical
SemitoneShift
— Pitch shift (semitones)
-3
(default) | real scalar | real vector
Pitch shift in semitones, specified as a real scalar or vector.
Dependencies
To enable this property, set AugmentationParameterSource to 'specify'
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
Control Volume
VolumeControlProbability
— Probability of applying volume control
0.5
(default) | scalar in the range [0, 1]
Probability of applying volume control, specified as a scalar in the range [0, 1].
Set the probability to 1
to apply volume control every time you
call augment
. Set
the probability to 0
to skip volume control every time you call
augment
.
Dependencies
To enable this property, set AugmentationParameterSource to 'random'
and
AugmentationMode to 'sequential'
.
Data Types: single
| double
VolumeGainRange
— Range of volume gain (dB)
[-3,3]
(default) | two-element row vector of nondecreasing values
Range of volume gain in dB, specified as a two-element row vector of nondecreasing values.
Dependencies
To enable this property, set AugmentationParameterSource to 'random'
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
ApplyVolumeControl
— Apply volume gain
true
(default) | false
Apply volume gain, specified as true
or
false
.
Dependencies
To enable this property, set AugmentationParameterSource to 'specify'
.
Data Types: logical
VolumeGain
— Volume gain (dB)
-3
(default) | scalar | vector
Volume gain in dB, specified as a scalar or vector.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
Add Noise
AddNoiseProbability
— Probability of applying noise addition
0.5
(default) | scalar in the range [0, 1]
Probability of applying Gaussian white noise addition, specified as a scalar in
the range [0, 1]. Set the probability to 1
to add noise every time
you call augment
. Set
the probability to 0
to skip adding noise every time you call
augment
.
Dependencies
To enable this property, set AugmentationParameterSource to 'random'
and
AugmentationMode to 'sequential'
.
Data Types: single
| double
SNRRange
— Range of noise addition SNR (dB)
[0,10]
(default) | two-element row vector of nondecreasing values
Range of noise addition SNR in dB, specified as a two-element row vector of nondecreasing values.
Dependencies
To enable this property, set AugmentationParameterSource to 'range'
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
ApplyAddNoise
— Apply noise addition
true
(default) | false
Apply Gaussian white noise addition, specified as true
or
false
.
Dependencies
To enable this property, set AugmentationParameterSource to 'specify'
.
Data Types: logical
SNR
— Noise addition SNR (dB)
5
(default) | scalar | vector
Noise addition SNR in dB, specified as a scalar or vector.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
Shift Time
TimeShiftProbability
— Probability of applying time shift
0.5
(default) | scalar in the range [0, 1]
Probability of applying time shift, specified as a scalar in the range [0, 1]. Set
the probability to 1
to apply time shifting every time you call
augment
. Set
the property to 0
to skip time shifting every time you call
augment
.
Time-shifting applies a circular shift on the time-domain audio data.
Dependencies
To enable this property, set AugmentationParameterSource to 'random'
and
AugmentationMode to 'sequential'
.
Data Types: single
| double
TimeShiftRange
— Range of time shift (s)
[-5e-3,5e3]
(default) | two-element row vector of nondecreasing values.
Range of time shift in seconds, specified as a two-element row vector of nondecreasing values.
Dependencies
To enable this property, set AugmentationParameterSource to 'random'
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
ApplyTimeShift
— Apply time shift
true
(default) | false
Apply time shift, specified as true
or
false
.
Dependencies
To enable this property, set AugmentationParameterSource to 'specify'
.
Time-shifting applies a circular shift on the time-domain audio data.
Data Types: logical
TimeShift
— Time shift (s)
5e-3
(default) | scalar | vector
Time shift in seconds, specified as a scalar or vector.
Dependencies
To enable this property, set AugmentationParameterSource to 'specify'
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
Object Functions
addAugmentationMethod | Add custom augmentation method |
removeAugmentationMethod | Remove custom augmentation method |
augment | Augment audio data |
setAugmenterParams | Set parameters of augmentation algorithm |
getAugmenterParams | Get parameters of augmentation algorithm |
Examples
Apply Random Sequential Augmentations
Read in an audio signal and listen to it.
[audioIn,fs] = audioread("Counting-16-44p1-mono-15secs.wav");
sound(audioIn,fs)
Create an audioDataAugmenter
object that applies time stretching, volume control, and time shifting in cascade. Apply each of the augmentations with 80% probability. Set NumAugmentations
to 5
to output five independently augmented signals. To skip pitch shifting and noise addition for each augmentation, set the respective probabilities to 0
. Define parameter ranges for each relevant augmentation algorithm.
augmenter = audioDataAugmenter( ... "AugmentationMode","sequential", ... "NumAugmentations",5, ... ... "TimeStretchProbability",0.8, ... "SpeedupFactorRange", [1.3,1.4], ... ... "PitchShiftProbability",0, ... ... "VolumeControlProbability",0.8, ... "VolumeGainRange",[-5,5], ... ... "AddNoiseProbability",0, ... ... "TimeShiftProbability",0.8, ... "TimeShiftRange", [-500e-3,500e-3])
augmenter = audioDataAugmenter with properties: AugmentationMode: "sequential" AugmentationParameterSource: 'random' NumAugmentations: 5 TimeStretchProbability: 0.8000 SpeedupFactorRange: [1.3000 1.4000] PitchShiftProbability: 0 VolumeControlProbability: 0.8000 VolumeGainRange: [-5 5] AddNoiseProbability: 0 TimeShiftProbability: 0.8000 TimeShiftRange: [-0.5000 0.5000]
Call augment
on the audio to create 5 augmentations. The augmented audio is returned in a table with variables Audio
and AugmentationInfo
. The number of rows in the table is defined by NumAugmentations
.
data = augment(augmenter,audioIn,fs)
data=5×2 table
Audio AugmentationInfo
_________________ ________________
{685056x1 double} 1x1 struct
{685056x1 double} 1x1 struct
{505183x1 double} 1x1 struct
{685056x1 double} 1x1 struct
{490728x1 double} 1x1 struct
In the current augmentation pipeline, augmentation parameters are assigned randomly from within the specified ranges. To determine the exact parameters used for an augmentation, inspect AugmentationInfo
.
augmentationToInspect = 4;
data.AugmentationInfo(augmentationToInspect)
ans = struct with fields:
SpeedupFactor: 1
VolumeGain: 4.3399
TimeShift: 0.4502
Listen to the augmentation you are inspecting. Plot time representation of the original and augmented signals.
augmentation = data.Audio{augmentationToInspect}; sound(augmentation,fs) t = (0:(numel(audioIn)-1))/fs; taug = (0:(numel(augmentation)-1))/fs; plot(t,audioIn,taug,augmentation) legend("Original Audio","Augmented Audio") ylabel("Amplitude") xlabel("Time (s)")
Apply Specified Sequential Augmentations
Read in an audio signal and listen to it.
[audioIn,fs] = audioread("Counting-16-44p1-mono-15secs.wav");
sound(audioIn,fs)
Create an audioDataAugmenter
object that applies time stretching, pitch shifting, and noise corruption in cascade. Specify the time stretch speedup factors as 0.9
, 1.1
, and 1.2
. Specify the pitch shifting in semitones as -2
, -1
, 1
, and 2
. Specify the noise corruption SNR as 10
dB and 15
dB.
augmenter = audioDataAugmenter( ... "AugmentationMode","sequential", ... "AugmentationParameterSource","specify", ... "SpeedupFactor",[0.9,1.1,1.2], ... "ApplyTimeStretch",true, ... "ApplyPitchShift",true, ... "SemitoneShift",[-2,-1,1,2], ... "SNR",[10,15], ... "ApplyVolumeControl",false, ... "ApplyTimeShift",false)
augmenter = audioDataAugmenter with properties: AugmentationMode: "sequential" AugmentationParameterSource: "specify" ApplyTimeStretch: 1 SpeedupFactor: [0.9000 1.1000 1.2000] ApplyPitchShift: 1 SemitoneShift: [-2 -1 1 2] ApplyVolumeControl: 0 ApplyAddNoise: 1 SNR: [10 15] ApplyTimeShift: 0
Call augment
on the audio to create 24 augmentations. The augmentations represent every combination of the specified augmentation parameters ().
data = augment(augmenter,audioIn,fs)
data=24×2 table
Audio AugmentationInfo
_________________ ________________
{761243x1 double} 1x1 struct
{622888x1 double} 1x1 struct
{571263x1 double} 1x1 struct
{761243x1 double} 1x1 struct
{622888x1 double} 1x1 struct
{571263x1 double} 1x1 struct
{761243x1 double} 1x1 struct
{622888x1 double} 1x1 struct
{571263x1 double} 1x1 struct
{761243x1 double} 1x1 struct
{622888x1 double} 1x1 struct
{571263x1 double} 1x1 struct
{761243x1 double} 1x1 struct
{622888x1 double} 1x1 struct
{571263x1 double} 1x1 struct
{761243x1 double} 1x1 struct
⋮
You can check the parameter configuration of each augmentation using the AugmentationInfo
table variable.
augmentationToInspect = 1;
data.AugmentationInfo(augmentationToInspect)
ans = struct with fields:
SpeedupFactor: 0.9000
SemitoneShift: -2
SNR: 10
Listen to the augmentation you are inspecting. Plot the time-domain representation of the original and augmented signals.
augmentation = data.Audio{augmentationToInspect}; sound(augmentation,fs) t = (0:(numel(audioIn)-1))/fs; taug = (0:(numel(augmentation)-1))/fs; plot(t,audioIn,taug,augmentation) legend("Original Audio","Augmented Audio") ylabel("Amplitude") xlabel("Time (s)")
Apply Random Independent Augmentations
Read in an audio signal and listen to it.
[audioIn,fs] = audioread("Counting-16-44p1-mono-15secs.wav");
Create an audioDataAugmenter
object that applies noise corruption, and time shifting in parallel branches. For the noise corruption branch, randomly apply noise with an SNR in the range 0
dB to 20
dB. For the time shifting branch, randomly apply time shifting in the range -300
ms to 300
ms. Apply augmentation 2 times for each branch, for 4 total augmentations.
augmenter = audioDataAugmenter( ... "AugmentationMode","independent", ... "AugmentationParameterSource","random", ... "NumAugmentations",2, ... "ApplyTimeStretch",false, ... "ApplyPitchShift",false, ... "ApplyVolumeControl",false, ... "SNRRange",[0,20], ... "TimeShiftRange",[-300e-3,300e-3])
augmenter = audioDataAugmenter with properties: AugmentationMode: "independent" AugmentationParameterSource: "random" NumAugmentations: 2 ApplyTimeStretch: 0 ApplyPitchShift: 0 ApplyVolumeControl: 0 ApplyAddNoise: 1 SNRRange: [0 20] ApplyTimeShift: 1 TimeShiftRange: [-0.3000 0.3000]
Call augment
on the audio to create 3 augmentations.
data = augment(augmenter,audioIn,fs);
You can check the parameter configuration of each augmentation using the AugmentatioInfo
table variable.
augmentationToInspect = 4;
data.AugmentationInfo{augmentationToInspect}
ans = struct with fields:
TimeShift: 0.0016
Listen to the audio you are inspecting. Plot the time-domain representation of the original and augmented signals.
augmentation = data.Audio{augmentationToInspect}; sound(augmentation,fs) t = (0:(numel(audioIn)-1))/fs; taug = (0:(numel(augmentation)-1))/fs; plot(t,audioIn,taug,augmentation) legend("Original Audio","Augmented Audio") ylabel("Amplitude") xlabel("Time (s)")
Apply Specified Independent Augmentations
Read in an audio signal and listen to it.
[audioIn,fs] = audioread("Counting-16-44p1-mono-15secs.wav");
Create an audioDataAugmenter
object that applies volume control, noise corruption, and time shifting in parallel branches.
augmenter = audioDataAugmenter( ... "AugmentationMode","independent", ... "AugmentationParameterSource","specify", ... "ApplyTimeStretch",false, ... "ApplyPitchShift",false, ... "VolumeGain",2, ... "SNR",0, ... "TimeShift",2)
augmenter = audioDataAugmenter with properties: AugmentationMode: "independent" AugmentationParameterSource: "specify" ApplyTimeStretch: 0 ApplyPitchShift: 0 ApplyVolumeControl: 1 VolumeGain: 2 ApplyAddNoise: 1 SNR: 0 ApplyTimeShift: 1 TimeShift: 2
Call augment
on the audio to create 3 augmentations.
data = augment(augmenter,audioIn,fs)
data=3×2 table
Audio AugmentationInfo
_________________ ________________
{685056x1 double} {1x1 struct}
{685056x1 double} {1x1 struct}
{685056x1 double} {1x1 struct}
You can check the parameter configuration of each augmentation using the AugmentatioInfo
table variable.
augmentationToInspect = 3;
data.AugmentationInfo{augmentationToInspect}
ans = struct with fields:
TimeShift: 2
Listen to the audio you are inspecting. Plot the time-domain representations of the original and augmented signals.
augmentation = data.Audio{augmentationToInspect}; sound(augmentation,fs) t = (0:(numel(audioIn)-1))/fs; taug = (0:(numel(augmentation)-1))/fs; plot(t,audioIn,taug,augmentation) legend("Original Audio","Augmented Audio") ylabel("Amplitude") xlabel("Time (s)")
Augment Audio Dataset
The audioDataAugmenter
supports multiple workflows for augmenting your datastore, including:
Offline augmentation
Augmentation using tall arrays
Augmentation using transform datastores
In each workflow, begin by creating an audio datastore to point to your audio data. In this example, you create an audio datastore that points to audio samples included with Audio Toolbox™. Count the number of files in the dataset.
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 26 more } AlternateFileSystemRoots: {} OutputDataType: 'double' Labels: {}
numFilesInDataset = numel(ADS.Files)
numFilesInDataset = 29
Create an audioDataAugmenter
that applies random sequential augmentations. Set NumAugmentations
to 2
.
aug = audioDataAugmenter('NumAugmentations',2)
aug = audioDataAugmenter with properties: AugmentationMode: 'sequential' AugmentationParameterSource: 'random' NumAugmentations: 2 TimeStretchProbability: 0.5000 SpeedupFactorRange: [0.8000 1.2000] PitchShiftProbability: 0.5000 SemitoneShiftRange: [-2 2] VolumeControlProbability: 0.5000 VolumeGainRange: [-3 3] AddNoiseProbability: 0.5000 SNRRange: [0 10] TimeShiftProbability: 0.5000 TimeShiftRange: [-0.0050 0.0050]
Offline Augmentation
To augment the audio dataset, create two augmentations of each file and then write the augmentations as WAV files.
while hasdata(ADS) [audioIn,info] = read(ADS); data = augment(aug,audioIn,info.SampleRate); [~,fn] = fileparts(info.FileName); for i = 1:size(data,1) augmentedAudio = data.Audio{i}; % If augmentation caused an audio signal to have values outside of -1 and 1, % normalize the audio signal to avoid clipping when writing. if max(abs(augmentedAudio),[],'all')>1 augmentedAudio = augmentedAudio/max(abs(augmentedAudio),[],'all'); end audiowrite(sprintf('%s_aug%d.wav',fn,i),augmentedAudio,info.SampleRate) end end
Create an audioDatastore
that points to the augmented dataset and confirm that the number of files in the dataset is double the original number of files.
augmentedADS = audioDatastore(pwd)
augmentedADS = audioDatastore with properties: Files: { ' ...\Examples\audio-ex28074079\Ambiance-16-44p1-mono-12secs_aug1.wav'; ' ...\Examples\audio-ex28074079\Ambiance-16-44p1-mono-12secs_aug2.wav'; ' ...\Examples\audio-ex28074079\AudioArray-16-16-4channels-20secs_aug1.wav' ... and 55 more } AlternateFileSystemRoots: {} OutputDataType: 'double' Labels: {}
numFilesInAugmentedDataset = numel(augmentedADS.Files)
numFilesInAugmentedDataset = 58
Augment Using Tall Arrays
When augmenting a dataset using tall arrays, the input data to the augmenter should be sampled at a consistent rate. Subset the original audio dataset to only include files with a sample rate of 44.1 kHz. Most datasets are already cleaned to have a consistent sample rate.
keepFile = cellfun(@(x)contains(x,'44p1'),ADS.Files);
ads44p1 = subset(ADS,keepFile);
fs = 44.1e3;
Convert the audio datastore to a tall array. tall
arrays are evaluated only when you request them explicitly using gather
. MATLAB® automatically optimizes the queued calculations by minimizing the number of passes through the data. If you have the Parallel Computing Toolbox™, you can spread the calculations across multiple machines. The audio data is represented as an M-by-1 tall cell array, where M is the number of files in the audio datastore.
adsTall = tall(ads44p1)
Starting parallel pool (parpool) using the 'local' profile ... Connected to the parallel pool (number of workers: 6). adsTall = M×1 tall cell array { 539648×1 double} { 227497×1 double} { 8000×1 double} { 685056×1 double} { 882688×2 double} {1115760×2 double} { 505200×2 double} {3195904×2 double} : : : :
Define a cellfun
function so that augmentation is applied to each cell of the tall array. Call gather
to evaluate the tall array.
augTall = cellfun(@(x)augment(aug,x,fs),adsTall,"UniformOutput",false);
augmentedDataset = gather(augTall)
Evaluating tall expression using the Parallel Pool 'local': - Pass 1 of 1: Completed in 1 min 34 sec Evaluation completed in 1 min 34 sec
augmentedDataset=12×1 cell array
{2×2 table}
{2×2 table}
{2×2 table}
{2×2 table}
{2×2 table}
{2×2 table}
{2×2 table}
{2×2 table}
{2×2 table}
{2×2 table}
{2×2 table}
{2×2 table}
The augmented dataset is returned as a numFiles-by-1 cell array, where numFiles is the number of files in the datastore. Each element of the cell array is a numAugmentationsPerFile-by-2 table, where numAugmentationsPerFile is the number of augmentations returned per file.
numFiles = numel(augmentedDataset)
numFiles = 12
numAugmentationsPerFile = size(augmentedDataset{1},1)
numAugmentationsPerFile = 2
Augment Using Transform Datastore
You can perform online data augmentation while you train your machine learning application using a transform datastore. Call transform
to create a new datastore that applies data augmentation while reading.
transformADS = transform(ADS,@(x,info)augment(aug,x,info),'IncludeInfo',true)
transformADS = TransformedDatastore with properties: UnderlyingDatastore: [1×1 audioDatastore] Transforms: {@(x,info)augment(aug,x,info)} IncludeInfo: 1
Call read
to return the augmented first file from the transform datastore.
augmentedRead = read(transformADS)
augmentedRead=2×2 table
Audio AugmentationInfo
_________________ ________________
{539648×1 double} [1×1 struct]
{586683×1 double} [1×1 struct]
Add Custom Augmentation Method
You can expand the capabilities of audioDataAugmenter
by adding custom augmentation methods.
Read in an audio signal and listen to it.
[audioIn,fs] = audioread('Counting-16-44p1-mono-15secs.wav');
sound(audioIn,fs)
Create an audioDataAugmenter
object. Set the probability of applying white noise to 0
.
augmenter = audioDataAugmenter('AddNoiseProbability',0)
augmenter = audioDataAugmenter with properties: AugmentationMode: 'sequential' AugmentationParameterSource: 'random' NumAugmentations: 1 TimeStretchProbability: 0.5000 SpeedupFactorRange: [0.8000 1.2000] PitchShiftProbability: 0.5000 SemitoneShiftRange: [-2 2] VolumeControlProbability: 0.5000 VolumeGainRange: [-3 3] AddNoiseProbability: 0 TimeShiftProbability: 0.5000 TimeShiftRange: [-0.0050 0.0050]
Specify a custom augmentation algorithm that applies pink noise. The AddPinkNoise
algorithm is added to the augmenter
properties.
algorithmName = 'AddPinkNoise'; algorithmHandle = @(x)x+pinknoise(size(x),'like',x); addAugmentationMethod(augmenter,algorithmName,algorithmHandle) augmenter
augmenter = audioDataAugmenter with properties: AugmentationMode: 'sequential' AugmentationParameterSource: 'random' NumAugmentations: 1 TimeStretchProbability: 0.5000 SpeedupFactorRange: [0.8000 1.2000] PitchShiftProbability: 0.5000 SemitoneShiftRange: [-2 2] VolumeControlProbability: 0.5000 VolumeGainRange: [-3 3] AddNoiseProbability: 0 TimeShiftProbability: 0.5000 TimeShiftRange: [-0.0050 0.0050] AddPinkNoiseProbability: 0.5000
Set the probability of adding pink noise to 1
.
augmenter.AddPinkNoiseProbability = 1
augmenter = audioDataAugmenter with properties: AugmentationMode: 'sequential' AugmentationParameterSource: 'random' NumAugmentations: 1 TimeStretchProbability: 0.5000 SpeedupFactorRange: [0.8000 1.2000] PitchShiftProbability: 0.5000 SemitoneShiftRange: [-2 2] VolumeControlProbability: 0.5000 VolumeGainRange: [-3 3] AddNoiseProbability: 0 TimeShiftProbability: 0.5000 TimeShiftRange: [-0.0050 0.0050] AddPinkNoiseProbability: 1
Augment the original signal and listen to the result. Inspect parameters of the augmentation algorithms applied.
data = augment(augmenter,audioIn,fs); sound(data.Audio{1},fs) data.AugmentationInfo(1)
ans = struct with fields:
SpeedupFactor: 1
SemitoneShift: 0
VolumeGain: 2.4803
TimeShift: -0.0022
AddPinkNoise: 'Applied'
Plot the mel spectrograms of the original and augmented signals.
melSpectrogram(audioIn,fs)
title('Original Signal')
melSpectrogram(data.Audio{1},fs)
title('Augmented Signal')
Algorithms
The audioDataAugmenter
object enables you to configure your augmentation
pipeline as deterministic or probabilistic using the AugmentationParameterSource property. You can also choose to apply the
augmentations in series or in parallel using the AugmentationMode
property. The following sections describe the pipelines you can create and the applicable
properties for each architecture.
Random Sequential Augmentations
To define your augmentation as a sequence of probabilistically applied augmentations,
set AugmentationParameterSource to 'random'
and AugmentationMode
to 'sequential'
.
The order that augmentations are applied is always the same. If you specify custom algorithms, they are applied at the end of the sequence, in the order you specified them.
In this pipeline configuration, these parameters apply:
Augmentation Method | Parameters |
---|---|
Stretch Time | |
Shift Pitch | |
Control Volume | |
Add Noise | |
Shift Time |
If you specify NumAugmentations
as greater than 1, then the object applies NumAugmentations
parallel
random sequential augmentations. The probability of applying an augmentation, and the value
of any parameters that are probabilistically determined, are independent.
Specified Sequential Augmentations
To define your augmentation as a sequence of deterministically applied augmentations,
set AugmentationParameterSource to 'specify'
and AugmentationMode
to 'sequential'
.
The order that augmentations are applied is always the same. If you specify custom algorithms, they are applied at the end of the sequence, in the order you specified them.
In this pipeline configuration, these parameters apply:
Augmentation Method | Parameters |
---|---|
Stretch Time | |
Shift Pitch | |
Control Volume | |
Add Noise | |
Shift Time |
If you specify an augmentation method as a vector, then each element of the vector creates a separate branch in the augmentation pipeline. For example, the following object creates an augmentation pipeline that results in four separate augmentations:
aug = audioDataAugmenter("AugmentationMode","sequential", ... "AugmentationParameterSource","specify", ... "SpeedupFactor",[0.8,1.2], ... "VolumeGain",[-3,-1])
aug = audioDataAugmenter with properties: AugmentationMode: "sequential" AugmentationParameterSource: "specify" ApplyTimeStretch: 1 SpeedupFactor: [0.8000 1.2000] ApplyPitchShift: 1 SemitoneShift: -3 ApplyVolumeControl: 1 VolumeGain: [-3 -1] ApplyAddNoise: 1 SNR: 5 ApplyTimeShift: 1 TimeShift: 0.0050
Random Independent Augmentations
To define your augmentation as independently applied augmentations with randomly
determined parameters, set AugmentationParameterSource to 'random'
and AugmentationMode
to 'independent'
.
In this pipeline configuration, these parameters apply:
Augmentation Method | Parameters |
---|---|
Stretch Time | |
Shift Pitch | |
Control Volume | |
Add Noise | |
Shift Time |
If you specify NumAugmentations
as greater than 1, then the object applies NumAugmentations
parallel
random independent augmentations. The value of any parameters that are probabilistically
determined are independent.
Specified Independent Augmentations
To define your augmentation as deterministically applied independent augmentations with
deterministic parameters, set AugmentationParameterSource to 'specify'
and AugmentationMode
to 'independent'
.
In this pipeline configuration, these parameters apply:
Augmentation Method | Parameters |
---|---|
Stretch Time | |
Shift Pitch | |
Control Volume | |
Add Noise | |
Shift Time |
If you specify an augmentation method as a vector, then each element of the vector creates a separate branch in the augmentation pipeline. For example, the following object creates an augmentation pipeline that results in seven separate augmentations:
aug = audioDataAugmenter("AugmentationMode","independent", ... "AugmentationParameterSource","specify", ... "SpeedupFactor",[0.8,1.2], ... "VolumeGain",[-3,-1])
aug = audioDataAugmenter with properties: AugmentationMode: "independent" AugmentationParameterSource: "specify" ApplyTimeStretch: 1 SpeedupFactor: [0.8000 1.2000] ApplyPitchShift: 1 SemitoneShift: -3 ApplyVolumeControl: 1 VolumeGain: [-3 -1] ApplyAddNoise: 1 SNR: 5 ApplyTimeShift: 1 TimeShift: 0.0050
References
[1] Salamon, Justin, and Juan Pablo Bello. "Deep Convolutional Neural Networks and Data Augmentation for Environmental Sound Classification." IEEE Signal Processing Letters. Vol. 24, Issue 3, 2017.
Extended Capabilities
GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.
Usage notes and limitations:
LockPhase
must be set tofalse
for the time stretching and pitch shifting augmentations. For more information, seesetAugmenterParams
.Using
gpuArray
(Parallel Computing Toolbox) input withaudioDataAugmenter
is only recommended for a GPU with compute capability 7.0 ("Volta") or above. Other hardware might not offer any performance advantage. To check your GPU compute capability, seeComputeCompability
in the output from thegpuDevice
(Parallel Computing Toolbox) function. For more information, see GPU Computing Requirements (Parallel Computing Toolbox).
For an overview of GPU usage in MATLAB®, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).
Version History
Introduced in R2019b
See Also
shiftPitch
| stretchAudio
| audioTimeScaler
| audioFeatureExtractor
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)