multibandParametricEQ

Multiband parametric equalizer

Description

The multibandParametricEQ System object™ performs multiband parametric equalization independently across each channel of input using specified center frequencies, gains, and quality factors. You can configure the System object with up to 10 bands. You can add low-shelf and high-shelf filters, as well as highpass (low-cut) and lowpass (high-cut) filters.

To implement a multiband parametric equalizer:

1. Create the multibandParametricEQ object and set its properties.

2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

mPEQ = multibandParametricEQ

mPEQ = multibandParametricEQ(Name,Value)

Description

mPEQ = multibandParametricEQ creates a System object, mPEQ, that performs multiband parametric equalization.

mPEQ = multibandParametricEQ(Name,Value) sets each construction argument or property Name to the specified Value. Unspecified properties and creation arguments have default values.

Example: mPEQ = multibandParametricEQ('NumEQBands',3,'Frequencies',[300,1200,5000]) creates a multiband parametric equalizer System object, mPEQ, with NumEQBands set to 3 and the Frequencies property set to [300,1200,5000].

Note

The value specified by NumEQBands must be the length of the row vectors specified by Frequencies, QualityFactors, and PeakGains. During creation of the System object, the first property you specify locks the value.

Creation Arguments

Creation arguments are properties which are set during creation of the System object and cannot be modified later. If you do not explicitly set a creation argument value, the property takes a default value.

NumEQBands — Number of equalizer bands

3 (default) | integer in the range [1, 10]

Number of equalizer bands, specified as an integer in the range [1, 10]. The number of equalizer bands does not include shelving filters, highpass filters, or lowpass filters.

NumEQBands is set during creation of the System object and cannot be modified later. If you do not explicitly set its value, the property takes the default value.

Example: mPEQ = multibandParametricEQ('NumEQBands',5) creates a multiband parametric equalizer with 5 bands.

Data Types: single | double

EQOrder — Order of individual equalizer bands

2 (default) | even integer

Order of individual equalizer bands, specified as an even integer. All equalizer bands have the same order.

EQOrder is set during creation of the System object and cannot be modified later. If you do not explicitly set its value, the property takes the default value.

Example: mPEQ = multibandParametricEQ('EQOrder',6) creates a multiband parametric equalizer with the default 3 bands, all of order 6.

Data Types: single | double

HasLowShelfFilter — Low-shelf filter toggle

false (default) | true

Low-shelf filter toggle, specified as false or true.

• false –– Do not enable low-shelf filtering in multiband parametric equalizer implementation.

• true –– Enable low-shelf filtering in multiband parametric equalizer implementation.

HasLowShelfFilter is set during creation of the System object and cannot be modified later. If you do not explicitly set its value, the property takes the default value.

Example: mPEQ = multibandParametricEQ('HasLowShelfFilter',true) creates a default multiband parametric equalizer with low-shelf filtering enabled.

Data Types: logical

HasHighShelfFilter — High-shelf filter toggle

false (default) | true

High-shelf filter toggle, specified as false or true.

• false –– Do not enable high-shelf filtering in multiband parametric equalizer implementation.

• true –– Enable high-shelf filtering in multiband parametric equalizer implementation.

HasHighShelfFilter is set during creation of the System object and cannot be modified later. If you do not explicitly set its value, the property takes the default value.

Example: mPEQ = multibandParametricEQ('HasHighShelfFilter',true) creates a default multiband parametric equalizer with high-shelf filtering enabled.

Data Types: logical

HasLowpassFilter — Lowpass filter toggle

false (default) | true

Lowpass filter toggle, specified as false or true.

• false –– Do not enable lowpass filtering in multiband parametric equalizer implementation.

• true –– Enable lowpass filtering in multiband parametric equalizer implementation.

HasLowpassFilter is set during creation of the System object and cannot be modified later. If you do not explicitly set its value, the property takes the default value.

Example: mPEQ = multibandParametricEQ('HasLowpassFilter',true) creates a default multiband parametric equalizer with lowpass filtering enabled.

Data Types: logical

HasHighpassFilter — Highpass filter toggle

false (default) | true

Highpass filter toggle, specified as false or true.

• false –– Do not enable highpass filtering in multiband parametric equalizer implementation.

• true –– Enable highpass filtering in multiband parametric equalizer implementation.

HasHighpassFilter is set during creation of the System object and cannot be modified later. If you do not explicitly set its value, the property takes the default value.

Example: mPEQ = multibandParametricEQ('HasHighpassFilter',true) creates a default multiband parametric equalizer with highpass filtering enabled.

Data Types: logical

Oversample — Oversample toggle

false (default) | true

Oversample toggle, specified as false or true.

• false –– Runs the multiband parametric equalizer at the input sample rate.

• true –– Runs the multiband parametric equalizer at two times the input sample rate. Oversampling minimizes the frequency-warping effects introduced by the bilinear transformation.

  A halfband interpolator implements oversampling before equalization. A halfband decimator reduces the sample rate back to the input sampling rate after equalization.

Oversample is set during creation of the System object and cannot be modified later. If you do not explicitly set its value, the property takes the default value.

Example: mPEQ = multibandParametricEQ('Oversample',true) creates a default multiband parametric equalizer with oversampling enabled.

Data Types: logical

Properties

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Multiband Equalizer

Frequencies — Center frequencies of equalizer bands (Hz)

[100, 181, 325] (default) | row vector of length NumEQBands

Center frequencies of equalizer bands in Hz, specified as a row vector of length NumEQBands. The vector consists of real scalars in the range 0 to SampleRate/2.

Tunable: Yes

Data Types: single | double

QualityFactors — Quality factors of equalizer bands

[1.6,1.6,1.6] (default) | row vector of length NumEQBands

Quality factors of equalizer bands, specified as a row vector of length NumEQBands.

Tunable: Yes

Data Types: single | double

PeakGains — Peak or dip filter gains (dB)

[0,0,0] (default) | row vector of length NumEQBands

Peak or dip filter gains in dB, specified as a row vector of length NumEQBands. The vector consists of real scalars in the range [–inf, 20].

Tunable: Yes

Data Types: single | double

Low-Shelf Filter

LowShelfCutoff — Low-shelf filter cutoff (Hz)

200 (default) | scalar

Low-shelf filter cutoff in Hz, specified as a scalar greater than or equal to 0.

Tunable: Yes

Dependencies

To enable this property, set HasLowShelfFilter to true during creation.

Data Types: single | double

LowShelfSlope — Low-shelf filter slope coefficient

1.5 (default) | positive scalar

Low-shelf filter slope coefficient, specified as a positive scalar.

Tunable: Yes

Dependencies

To enable this property, set HasLowShelfFilter to true during creation.

Data Types: single | double

LowShelfGain — Low-shelf filter gain (dB)

0 (default) | real scalar

Low-shelf filter gain in dB, specified as a real scalar.

Tunable: Yes

Dependencies

To enable this property, set HasLowShelfFilter to true during creation.

Data Types: single | double

High-Shelf Filter

HighShelfCutoff — High-shelf filter cutoff (Hz)

15000 (default) | nonnegative real scalar

High-shelf filter cutoff in Hz, specified as a real scalar greater than or equal to 0.

Tunable: Yes

Dependencies

To enable this property, set HasHighShelfFilter to true during creation.

Data Types: single | double

HighShelfSlope — High-shelf slope coefficient

1.5 (default) | positive scalar

High-shelf filter slope coefficient, specified as a positive scalar.

Tunable: Yes

Dependencies

To enable this property, set HasHighShelfFilter to true during creation.

Data Types: single | double

HighShelfGain — High-shelf filter gain (dB)

0 (default) | real scalar

High-shelf filter gain in dB, specified as a real scalar.

Tunable: Yes

Dependencies

To enable this property, set HasHighShelfFilter to true during creation.

Data Types: single | double

Lowpass Filter

LowpassCutoff — Lowpass filter cutoff frequency (Hz)

18000 (default) | nonnegative real scalar

Lowpass filter cutoff frequency in Hz, specified as a real scalar greater than or equal to 0.

Tunable: Yes

Dependencies

To enable this property, set HasLowpassFilter to true during creation.

Data Types: single | double

LowpassSlope — Lowpass filter slope (dB/octave)

12 (default) | real scalar in the range [0:6:48]

Lowpass filter slope in dB/octave, specified as a real scalar in the range [0:6:48]. Values that are not multiples of 6 are rounded to the nearest multiple of 6.

Tunable: Yes

Dependencies

To enable this property, set HasLowpassFilter to true during creation.

Data Types: single | double

Highpass Filter

HighpassCutoff — Highpass filter cutoff frequency (Hz)

20 (default) | nonnegative real scalar

Highpass filter cutoff in Hz, specified as a real scalar greater than or equal to 0.

Tunable: Yes

Dependencies

To enable this property, set HasHighpassFilter to true during creation.

Data Types: single | double

HighpassSlope — Highpass filter slope (dB/octave)

30 (default) | real scalar in the range [0:6:48]

Highpass filter slope in dB/octave, specified as a real scalar in the range [0:6:48]. Values that are not multiples of 6 are rounded to the nearest multiple of 6.

Tunable: Yes

Dependencies

To enable this property, set HasHighpassFilter to true during creation.

Data Types: single | double

Sampling

SampleRate — Input sample rate (Hz)

44100 (default) | positive scalar

Input sample rate in Hz, specified as a positive scalar.

Tunable: Yes

Data Types: single | double

Usage

Syntax

audioOut = mPEQ(audioIn)

Description

audioOut = mPEQ(audioIn) performs multiband parametric equalization on the input signal, audioIn, and returns the filtered signal, audioOut. The type of equalization is specified by the algorithm and properties of the multibandParametricEQ System object, mPEQ.

Input Arguments

audioIn — Audio input to equalizer

matrix

Audio input to the equalizer, specified as a matrix. The columns of the matrix are treated as independent audio channels.

Data Types: single | double

Output Arguments

audioOut — Audio output from equalizer

matrix

Audio output from the equalizer, returned as a matrix the same size as audioIn.

Data Types: single | double

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

Specific to multibandParametricEQ

createAudioPluginClass	Create audio plugin class that implements functionality of System object
visualize	Visualize magnitude response of multiband parametric equalizer
parameterTuner	Tune object parameters while streaming

MIDI

configureMIDI	Configure MIDI connections between audio object and MIDI controller
disconnectMIDI	Disconnect MIDI controls from audio object
getMIDIConnections	Get MIDI connections of audio object

Common to All System Objects

clone	Create duplicate System object
isLocked	Determine if System object is in use
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object
step	Run System object algorithm

The createAudioPluginClass and configureMIDI functions map tunable properties of the multibandParametricEQ System object to user-facing parameters:

Property	Range	Mapping	Unit
Frequencies	[20, 20000]	log	Hz
QualityFactors	[0.2, 700]	linear	none
PeakGains	[–50, 20]	linear	dB
LowShelfCutoff	[20, 20000]	log	Hz
LowShelfSlope	[0.1, 5]	linear	none
LowShelfGain	[–12, 12]	linear	dB
HighShelfCutoff	[20, 20000]	log	Hz
HighShelfSlope	[0.1, 5]	linear	none
HighShelfGain	[–12, 12]	linear	dB
LowpassCutoff	[20, 20000]	log	Hz
LowpassSlope	[0, 48]	linear	dB/octave
HighpassCutoff	[20, 20000]	log	Hz
HighpassSlope	[0, 48]	linear	dB/octave

Examples

Multiband Parametric Equalization

Create dsp.AudioFileReader and audioDeviceWriter objects. Use the sample rate of the reader as the sample rate of the writer. Call setup to reduce the computational load of initialization in an audio stream loop.

frameLength = 512;

fileReader = dsp.AudioFileReader( ...
    'Filename','RockDrums-48-stereo-11secs.mp3', ...
    'SamplesPerFrame',frameLength);
deviceWriter = audioDeviceWriter( ...
    'SampleRate',fileReader.SampleRate);

setup(deviceWriter,ones(frameLength,2))

Construct a three-band parametric equalizer with a high-shelf filter.

mPEQ = multibandParametricEQ( ...
    'NumEQBands',3, ...
    'Frequencies',[300,1200,5000], ...
    'QualityFactors',[1,1,1], ...
    'PeakGains',[8,-10,7], ...
    'HasHighShelfFilter',true, ...
    'HighShelfCutoff',14000, ...
    'HighShelfSlope',0.3, ...
    'HighShelfGain',-5, ...
    'SampleRate',fileReader.SampleRate);

Visualize the magnitude frequency response of your multiband parametric equalizer.

visualize(mPEQ)

Play the equalized audio signal. Update the peak gains of your equalizer band to hear the effect of the equalizer and visualize the changing magnitude response.

count = 0;
while ~isDone(fileReader)
    originalSignal = fileReader();
    equalizedSignal = mPEQ(originalSignal);
    deviceWriter(equalizedSignal);
    if mod(count,100) == 0
        mPEQ.PeakGains(1) = mPEQ.PeakGains(1) - 1.5;
        mPEQ.PeakGains(2) = mPEQ.PeakGains(2) + 1.5;
        mPEQ.PeakGains(3) = mPEQ.PeakGains(3) - 1.5;
    end
    count = count + 1;
end

release(fileReader)
release(mPEQ)
release(deviceWriter)

Oversample Audio Signal

Reduce warping by specifying your multibandParametricEQ object to perform oversampling before equalization.

Create a one-band equalizer. Visualize the equalizer band as its center frequency approaches the Nyquist rate.

mPEQ = multibandParametricEQ( ...
    'NumEQBands',1, ...
    'Frequencies',9.5e3, ...
    'PeakGains',10);
visualize(mPEQ)

for i = 1:1000
    mPEQ.Frequencies = mPEQ.Frequencies + 8;
end

The equalizer band is warped.

Create a one-band equalizer with Oversample set to true. Visualize the equalizer band as its center frequency approaches the Nyquist rate.

mPEQOversampled = multibandParametricEQ( ...
    'NumEQBands',1, ...
    'Frequencies',9.5e3, ...
    'PeakGains',10, ...
    'Oversample',true);
visualize(mPEQOversampled)

for i = 1:1000
    mPEQOversampled.Frequencies = mPEQOversampled.Frequencies + 8;
end

Warping is reduced.

Tune Multiband Parametric EQ Parameters

Create a dsp.AudioFileReader to read in audio frame-by-frame. Create a audioDeviceWriter to write audio to your sound card. Create a multibandParametricEQ to process the audio data. Call visualize to plot the frequency response of the equalizer.

frameLength = 1024;
fileReader = dsp.AudioFileReader('RockDrums-44p1-stereo-11secs.mp3','SamplesPerFrame',frameLength);
deviceWriter = audioDeviceWriter('SampleRate',fileReader.SampleRate);

equalizer = multibandParametricEQ('SampleRate',fileReader.SampleRate, 'PeakGains',[-2,2,4]);
visualize(equalizer)

Call parameterTuner to open a UI to tune parameters of the equalizer while streaming.

parameterTuner(equalizer)

In an audio stream loop:

1. Read in a frame of audio from the file.

2. Apply equalization.

3. Write the frame of audio to your audio device for listening.

While streaming, tune parameters of the equalizer and listen to the effect.

while ~isDone(fileReader)
    audioIn = fileReader();
    audioOut = equalizer(audioIn);
    deviceWriter(audioOut);
    drawnow limitrate % required to update parameter
end

As a best practice, release your objects once done.

release(deviceWriter)
release(fileReader)
release(equalizer)

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

System Objects in MATLAB Code Generation (MATLAB Coder)

Version History

Introduced in R2016a