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

Syntax

equalizer = graphicEQ

equalizer = graphicEQ(Name,Value)

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

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.

Gains — Gain of each octave or fractional octave band (dB)

[0 0 0 0 0 0 0 0 0 0] (default) | 10-, 15-, or 30-element row vector

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

EQOrder — Order of individual equalizer bands

2 (default) | positive even integer

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

Tunable: No

Data Types: single | double

Bandwidth — Filter bandwidth (octaves)

'1 octave' (default) | '2/3 octave' | '1/3 octave'

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 frequencies	32 63 126 251 501 1000 1995 3981 7943 15849
Edge frequencies	22 45 89 178 355 708 1413 2818 5623 1122 22387
Preferred frequencies	31.5 63 125 250 500 1000 2000 4000 8000 16000

2/3-Octave Bandwidth

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

1/3-Octave Bandwidth

Center frequencies	25 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 frequencies	22 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 frequencies	25 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

Structure — Type of implementation

'Cascade' (default) | 'Parallel'

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

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 = equalizer(audioIn)

Description

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

audioIn — Audio input to graphic equalizer

matrix

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

audioOut — Audio output from graphic equalizer

matrix

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)

Specific to graphicEQ

createAudioPluginClass	Create audio plugin class that implements functionality of System object
coeffs	Get filter coefficients
info	Get filter information
visualize	Visualize magnitude response of graphic 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 graphicEQ System object to user-facing parameters:

Property	Range	Mapping	Unit
Gains	[–20, 20]	linear	dB

Examples

Perform Graphic Equalization

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)

Tune Graphic EQ Parameters

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

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

Parallel Structure

Filter Bank Design

The parallel implementation designs the individual equalizers using the octaveFilter design method and spaces them on the spectrum according to the ANSI S1.11-2004 standard.

If you set the SampleRate property so that the Nyquist frequency (SampleRate/2) is less than the final bandpass edge defined by the ANSI S1.11-2004 standard, then:

• The final bandpass filter is the one whose upper bandpass edge is less than the Nyquist frequency.

• The final filter is implemented as a highpass filter designed by the designParamEQ function.

Real-Time Computation

1. The input signal is fed into a filterbank of M filters, where M depends on the specified Bandwidth and SampleRate properties.

2. Each branch of the filterbank is multiplied by the linear form of the corresponding element of the Gains property.

3. The branches are summed and the output signal is returned.

Cascade Structure

Filter Bank Design

The cascade implementation designs the graphic equalizer filter bank using the multibandParametricEQ System object.

Gain Setting

If the EQOrder property is set to 2, then a gain correction is calculated according to [1]. The gain correction is independent of the requested gains. The gain correction is recomputed during the real-time processing only if the SampleRate property is modified.

If the EQOrder property is not set to 2, no gain correction is applied, and the requested gains are passed on to the multibandParametricEQ object.

Real-Time Computation

The input signal is fed into a cascade of M biquad filters, where M depends on the specified Bandwidth and SampleRate properties.

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

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 R2017b