Main Content

shelvingFilter

Second-order IIR shelving filter

Since R2022a

expand all in page

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

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.

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

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

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

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.

example

Input Arguments

expand all

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

expand all

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)

expand all

visualizeVisualize magnitude response of shelving filter
createAudioPluginClassCreate audio plugin class that implements functionality of System object
coeffsGet filter coefficients
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
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

Open Live Script

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

Open Live Script

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

See Also

Blocks

Functions

Objects