shelvingFilter

Second-order IIR shelving filter

Since R2022a

Description

The shelvingFilter System object™ implements a shelving filter, which boosts or cuts the frequency spectrum of the input signal above or below a given cutoff frequency.

To use a shelving filter:

1. Create the shelvingFilter 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

shelvFilt = shelvingFilter

shelvFilt = shelvingFilter(gain)

shelvFilt = shelvingFilter(gain,slope)

shelvFilt = shelvingFilter(gain,slope,cutoffFreq)

shelvFilt = shelvingFilter(gain,slope,cutoffFreq,type)

shelvFilt = shelvingFilter(___,Name=Value)

Description

shelvFilt = shelvingFilter creates a shelving filter with default values.

shelvFilt = shelvingFilter(gain) sets the Gain property to gain.

shelvFilt = shelvingFilter(gain,slope) sets the Slope property to slope.

shelvFilt = shelvingFilter(gain,slope,cutoffFreq) sets the CutoffFrequency property to cutoffFreq.

shelvFilt = shelvingFilter(gain,slope,cutoffFreq,type) sets the FilterType property to type.

shelvFilt = shelvingFilter(___,Name=Value) sets Properties using one or more name-value arguments in addition to the input arguments in previous syntaxes. For example, shelvFilt = shelvingFilter(SampleRate=96000) creates a shelving filter with a sample rate of 96,000 Hz.

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.

Gain — Peak gain (dB)

0 (default) | real scalar

Peak gain of the filter in dB, specified as a real scalar. The gain specifies how much the filter will boost (if the gain is positive) or cut (if the gain is negative) the frequency spectrum of the input signal.

Tunable: Yes

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

Slope — Filter slope

1.5 (default) | positive scalar

Slope of the filter, specified as a positive scalar. The slope controls the width of the transition band in the filter response.

Tunable: Yes

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

CutoffFrequency — Cutoff frequency of filter

200 (default) | nonnegative scalar

Cutoff frequency of the filter in Hz, specified as a nonnegative scalar in the range [0,SampleRate/2]. The cutoff frequency specifies the frequency at half of the peak gain of the filter, Gain/2 dB.

Tunable: Yes

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

FilterType — Type of filter

"lowpass" (default) | "highpass"

Type of shelving filter, specified as "lowpass" or "highpass".

• "lowpass" –– Boost or cut the frequency spectrum below the cutoff frequency.

• "highpass" –– Boost or cut the frequency spectrum above the cutoff frequency.

Tunable: Yes

Data Types: string | char

SampleRate — Sample rate of the input (Hz)

44100 (default) | positive scalar

Sample rate of the input in Hz, specified as a positive scalar.

Tunable: No

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

Usage

Syntax

audioOut = shelvFilt(audioIn)

Description

audioOut = shelvFilt(audioIn) applies the shelving filter to the input signal, audioIn and returns the output signal audioOut. The type of filtering applied by the function depends on the algorithm and properties of the shelvingFilter System object.

Input Arguments

audioIn — Audio input to shelving filter

column vector | matrix

Audio input to the shelving filter, specified as a column vector or a matrix. If the input is a matrix, the columns are treated as independent channels.

Data Types: single | double

Output Arguments

audioOut — Audio output of shelving filter

column vector | matrix

Audio output of the shelving filter, returned as a column vector or matrix with the same size and data type as the 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 shelvingFilter

visualize	Visualize magnitude response of shelving filter
createAudioPluginClass	Create audio plugin class that implements functionality of System object
coeffs	Get filter coefficients
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

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Examples

Filter Audio Using Shelving Filter

Create a lowpass shelvingFilter object with a gain of 10 dB, a slope of 1, and a cutoff frequency of 400 Hz.

shelvFilt = shelvingFilter(10,1,400,"lowpass");

Visualize the magnitude response of the filter.

visualize(shelvFilt)

Create a dsp.AudioFileReader object to read in the audio signal for filtering.

samplesPerFrame = 1024;
reader = dsp.AudioFileReader( ...
    Filename="RockGuitar-16-44p1-stereo-72secs.wav", ...
    SamplesPerFrame=samplesPerFrame);

Create a spectrumAnalyzer object to visualize the spectrum of the original audio signal and the spectrum of the filtered signal.

scope = spectrumAnalyzer( ...
    SampleRate=reader.SampleRate, ...
    PlotAsTwoSidedSpectrum=false, ...
    FrequencyScale="log", ...
    Title="Original and Filtered Signal", ...
    ShowLegend=true, ...
    ChannelNames=["Original Signal","Filtered Signal"]);

Filter the audio signal and visualize the results.

while ~isDone(reader)
    audioIn = reader();
    filteredSignal = shelvFilt(audioIn);
    scope([audioIn(:,1),filteredSignal(:,1)]);
end

Tune Shelving Filter Parameters

Create a highpass shelvingFilter object with a gain of 5 dB, a slope of 1, and a cutoff frequency of 400 Hz.

shelvFilt = shelvingFilter(5,1,400,"highpass");

Visualize the magnitude response of the filter.

visualize(shelvFilt)

Create dsp.AudioFileReader and audioDeviceWriter objects to read in the audio signal and write the filtered signal to your audio device to listen to it.

samplesPerFrame = 1024;
reader = dsp.AudioFileReader( ...
    Filename="RockGuitar-16-44p1-stereo-72secs.wav", ...
    SamplesPerFrame=samplesPerFrame);
deviceWriter = audioDeviceWriter(SampleRate=reader.SampleRate);

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

parameterTuner(shelvFilt)

In an audio stream loop:

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

2. Apply shelving filter.

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

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

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

As a best practice, release your objects once done.

release(reader)
release(shelvFilt)
release(deviceWriter)

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2022a