Main Content

graphicEQ

Standards-based graphic equalizer

Description

The graphicEQ System object™ implements a graphic equalizer that can tune the gain on individual octave or fractional octave bands. The object filters the data independently across each input channel over time using the filter specifications. Center and edge frequencies of the bands are based on the ANSI S1.11-2004 standard.

To equalize an audio signal:

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

equalizer = graphicEQ creates a graphic equalizer with default values.

equalizer = graphicEQ(Name,Value) sets each property Name to the specified Value. Unspecified properties have default values.

Example: equalizer = graphicEQ('Structure','Parallel','EQOrder','1/3 octave') creates a System object, equalizer, which implements filtering using a parallel structure and one-third octave filter bandwidth.

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.

Gain of each octave of fractional octave band in dB, specified as a row vector with a length determined by the Bandwidth property:

  • '1 octave' –– Specify gains as a 10-element row vector.

  • '2/3 octave' –– Specify gains as a 15-element row vector.

  • '1/3 octave' –– Specify gains as a 30-element row vector.

Example: equalizer = graphicEQ('Bandwidth','2/3 octave','Gains',[5,5,5,5,5,0,0,0,0,0,-5,-5,-5,-5,-5]) creates a two-third octave graphic equalizer with specified gains.

You can tune the gains of your graphic equalizer when the object is locked. However, you cannot tune the length of the gains when the object is locked.

Tunable: Yes

Data Types: single | double

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

Tunable: No

Data Types: single | double

Filter bandwidth in octaves, specified as '1 octave', '2/3 octave', or '1/3 octave'.

The ANSI S1.11-2004 standard defines the center and edge frequencies of your equalizer. The ISO 266:1997(E) standard specifies corresponding preferred frequencies for labeling purposes.

1-Octave Bandwidth

Center frequencies32 63 126 251 501 1000 1995 3981 7943 15849
Edge frequencies22 45 89 178 355 708 1413 2818 5623 1122 22387
Preferred frequencies31.5 63 125 250 500 1000 2000 4000 8000 16000

2/3-Octave Bandwidth

Center frequencies25 40 63 100 158 251 398 631 1000 1585 2512 3981 6310 10000 15849
Edge frequencies20 32 50 79 126 200 316 501 794 1259 1995 3162 5012 7943 12589 19953
Preferred frequencies25 40 63 100 160 250 400 630 1000 1600 2500 4000 6300 10000 16000

1/3-Octave Bandwidth

Center frequencies25 32 40 50 63 79 100 126 158 200 251 316 398 501 631 794 1000 1259 1585 1995 2512 3162 3981 5012 6310 7943 10000 12589 15849 19953
Edge frequencies22 28 35 45 56 71 89 112 141 178 224 282 355 447 562 708 891 1122 1413 1778 2239 2818 3548 4467 5623 7079 8913 11220 14125 17783 22387
Preferred frequencies25 31.5 40 50 63 80 100 125 160 200 250 315 400 500 630 800 1000 1250 1600 2000 2500 3150 4000 5000 6300 8000 10000 12500 16000 20000

Tunable: No

Data Types: char | string

Type of implementation, specified as 'Cascade' or 'Parallel'. See Algorithms and Graphic Equalization for information about these implementation structures.

Tunable: No

Data Types: char | string

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

Tunable: Yes

Data Types: single | double

Usage

Description

example

audioOut = equalizer(audioIn) performs graphic equalization on the input signal, audioIn, and returns the equalized signal, audioOut. The type of equalization is specified by the algorithm and properties of the graphicEQ System object, equalizer.

Input Arguments

expand all

Audio input to the graphic 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 graphic 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
coeffsGet filter coefficients
infoGet filter information
visualizeVisualize magnitude response of graphic 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 graphicEQ System object to user-facing parameters:

PropertyRangeMappingUnit
Gains[–20, 20]lineardB

Examples

collapse all

Create objects to read from an audio file and write to your audio device. Use the sample rate of the reader as the sample rate of the writer.

frameLength = 512;
reader = dsp.AudioFileReader('RockDrums-48-stereo-11secs.mp3','SamplesPerFrame',frameLength);
player = audioDeviceWriter('SampleRate',reader.SampleRate);

In an audio stream loop, read audio from a file and play the audio through your audio device.

while ~isDone(reader)
    x = reader();
    player(x);
end
release(reader)
release(player)

Create a one-octave graphic equalizer implemented with a cascade structure. Use the sample rate of the reader as the sample rate of the equalizer.

equalizer = graphicEQ( ...
    'Bandwidth','1 octave', ...    
    'Structure','Cascade', ...
    'SampleRate',reader.SampleRate);

Specify to increase the gain on low frequencies and then visualize the equalizer.

equalizer.Gains = [5,5,5,5,0,0,0,0,0,0];
visualize(equalizer)

In an audio stream loop, read audio from a file, apply equalization, and then play the equalized audio through your audio device.

while ~isDone(reader)
    x = reader();
    y = equalizer(x);
    player(y);
end
release(reader)
release(player)

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

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

equalizer = graphicEQ('SampleRate',fileReader.SampleRate,'Gains',[0,10,-10,5,-5,2,-2,1,-1,0]);
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)

Algorithms

expand all

The implementation of your graphic equalizer depends on the Structure property. See Graphic Equalization for a discussion of the pros and cons of the parallel and cascade implementations. Refer to the following sections to understand how these algorithms are implemented in Audio Toolbox™.

References

[1] Oliver, Richard J., and Jean-Marc Jot. "Efficient Multi-Band Digital Audio Graphic Equalizer with Accurate Frequency Response Control." Presented at the 139th Convention of the AES, New York, October 2015.

[2] Acoustical Society of America. American National Standard Specification for Octave-Band and Fractional-Octave-Band Analog and Digital Filters. ANSI S1.11-2004. Melville, NY: Acoustical Society of America, 2009.

[3] International Organization for Standardization. Acoustics –– Preferred frequencies. ISO 266:1997(E). Second Edition. 1997.

Extended Capabilities

Version History

Introduced in R2017b