Main Content

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

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

expand all

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.

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

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

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

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

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

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

expand all

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

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

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

Tunable: Yes

Data Types: single | double

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

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

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

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

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

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

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

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

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

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

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

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

Tunable: Yes

Data Types: single | double

Usage

Description

example

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

expand all

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

expand all

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)

expand all

createAudioPluginClassCreate audio plugin class that implements functionality of System object
visualizeVisualize magnitude response of multiband parametric equalizer
parameterTunerTune object parameters while streaming
configureMIDIConfigure MIDI connections between audio object and MIDI controller
disconnectMIDIDisconnect MIDI controls from audio object
getMIDIConnectionsGet MIDI connections of audio object
cloneCreate duplicate System object
isLockedDetermine if System object is in use
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object
stepRun System object algorithm

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

PropertyRangeMappingUnit
Frequencies[20, 20000]logHz
QualityFactors[0.2, 700]linearnone
PeakGains[–50, 20]lineardB
LowShelfCutoff[20, 20000]logHz
LowShelfSlope[0.1, 5]linearnone
LowShelfGain[–12, 12]lineardB
HighShelfCutoff[20, 20000]logHz
HighShelfSlope [0.1, 5]linearnone
HighShelfGain[–12, 12]lineardB
LowpassCutoff[20, 20000]logHz
LowpassSlope[0, 48]lineardB/octave
HighpassCutoff[20, 20000]logHz
HighpassSlope[0, 48]lineardB/octave

Examples

collapse all

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)

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.

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

Version History

Introduced in R2016a