AudioScience HPI Version_4.18.
Enumerations | Functions

Parametric Equalizer control

Controls

The parametric equalizer control consists of a series of filters that are applied successively to the signal. More...

Enumerations

enum  HPI_FILTER_TYPE {
  HPI_FILTER_TYPE_BYPASS = 0, HPI_FILTER_TYPE_LOWSHELF = 1, HPI_FILTER_TYPE_HIGHSHELF = 2, HPI_FILTER_TYPE_EQ_BAND = 3,
  HPI_FILTER_TYPE_LOWPASS = 4, HPI_FILTER_TYPE_HIGHPASS = 5, HPI_FILTER_TYPE_BANDPASS = 6, HPI_FILTER_TYPE_BANDSTOP = 7
}
 

Equalizer filter types.

More...

Functions

hpi_err_t HPI_ParametricEQ_GetInfo (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint16_t *pwNumberOfBands, uint16_t *pwOnOff)
 Find out the number of available bands of a parametric equalizer, and whether it is enabled or not.
hpi_err_t HPI_ParametricEQ_SetState (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint16_t wOnOff)
 Turn a parametric equalizer on or off.
hpi_err_t HPI_ParametricEQ_GetBand (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint16_t wIndex, uint16_t *pnType, uint32_t *pdwFrequencyHz, short *pnQ100, short *pnGain0_01dB)
 Get the settings of one of the filters in a parametric equalizer.
hpi_err_t HPI_ParametricEQ_SetBand (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint16_t wIndex, uint16_t nType, uint32_t dwFrequencyHz, short nQ100, short nGain0_01dB)
 Set up one of the filters in a parametric equalizer.
hpi_err_t HPI_ParametricEQ_GetCoeffs (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint16_t wIndex, short coeffs[5])
 Retrieve the calculated IIR filter coefficients (scaled by 1000 into integers).

Detailed Description

The parametric equalizer control consists of a series of filters that are applied successively to the signal.

The number of filters available is obtained by calling HPI_ParametricEQ_GetInfo(), then the characteristics of each filter are configured using HPI_ParametricEQ_SetBand().

The equalizer as a whole can be turned on and off using HPI_ParametricEQ_SetState(). Filters can still be set up when the equalizer is switched off.

Equalizers are typically located on a LineIn input node or an OutStream node.

Obtain a control handle to an equalizer like this:

err = HPI_MixerGetControl(
                phSubSys,
                hMixer,
                HPI_SOURCENODE_LINEIN, 0,
                0,0,  // No destination node
                HPI_CONTROL_PARAMETRIC_EQ,
                &hControl
                );

Enumeration Type Documentation

Equalizer filter types.

Used by HPI_ParametricEQ_SetBand()

Enumerator:
HPI_FILTER_TYPE_BYPASS 

Filter is turned off.

HPI_FILTER_TYPE_LOWSHELF 

EQ low shelf.

HPI_FILTER_TYPE_HIGHSHELF 

EQ high shelf.

HPI_FILTER_TYPE_EQ_BAND 

EQ gain.

HPI_FILTER_TYPE_LOWPASS 

Standard low pass.

HPI_FILTER_TYPE_HIGHPASS 

Standard high pass.

HPI_FILTER_TYPE_BANDPASS 

Standard band pass.

HPI_FILTER_TYPE_BANDSTOP 

Standard band stop/notch.


Function Documentation

hpi_err_t HPI_ParametricEQ_GetInfo ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint16_t *  pwNumberOfBands,
uint16_t *  pwOnOff 
)

Find out the number of available bands of a parametric equalizer, and whether it is enabled or not.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlEqualizer control handle.
pwNumberOfBandsReturned number of bands available.
pwOnOffReturned enabled status. 1 indicates enabled and 0 indicates disabled.
hpi_err_t HPI_ParametricEQ_SetState ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint16_t  wOnOff 
)

Turn a parametric equalizer on or off.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlEqualizer control handle
wOnOffState setting, one of the HPI_SWITCH_STATES
hpi_err_t HPI_ParametricEQ_GetBand ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint16_t  wIndex,
uint16_t *  pnType,
uint32_t *  pdwFrequencyHz,
short *  pnQ100,
short *  pnGain0_01dB 
)

Get the settings of one of the filters in a parametric equalizer.

See HPI_ParametricEQ_SetBand() for details of parameter interpretation.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlEqualizer control handle
wIndexIndex of band to Get.
pnTypeReturned band type.
pdwFrequencyHzReturned band frequency.
pnQ100Returned filter Q * 100.
pnGain0_01dBReturned filter gain in 100ths of a dB.
hpi_err_t HPI_ParametricEQ_SetBand ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint16_t  wIndex,
uint16_t  nType,
uint32_t  dwFrequencyHz,
short  nQ100,
short  nGain0_01dB 
)

Set up one of the filters in a parametric equalizer.

Set the parameters for one equalizer filter. The overall equalizer response will be a product of all its filter responses.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlEqualizer control handle.
wIndexIndex of band to set.
nTypeThe kind of filter that the band will implement has many different options. In the following descriptions, low and high frequencies mean relative to dwBandFrequency. "Elsewhere" means at frequencies different from dwBandFrequency, how different depends on Q (look at the following figures)

  • HPI_FILTER_TYPE_BYPASS
    The filter is bypassed (turned off). Other parameters are ignored
  • HPI_FILTER_TYPE_LOWPASS
    Has unity gain at low frequencies, and attenuation tending towards infinite at high frequencies. nGain0_01dB parameter is ignored. See "lp" in the following diagrams.
  • HPI_FILTER_TYPE_HIGHPASS
    Has unity gain at high frequencies, and attenuation tending towards infinite at low frequencies. nGain0_01dB parameter is ignored. (Not illustrated, basically the opposite of lowpass)
  • HPI_FILTER_TYPE_BANDPASS
    Has unity gain at dwFrequencyHz and tends towards infinite attenuation elsewhere. nGain0_01dB parameter is ignored. See "bp" in the following diagrams.
  • HPI_FILTER_TYPE_BANDSTOP
    Maximum attenuation at dwFrequencyHz, tends towards unity gain elsewhere. nGain0_01dB parameter is ignored. See "bs" in the following diagrams.
  • HPI_FILTER_TYPE_LOWSHELF
    Has gain of nGain0_01dB at low frequencies and unity gain at high frequencies. See "ls" in the following diagrams.
  • HPI_FILTER_TYPE_HIGHSHELF
    Has gain of nGain0_01dB at high frequencies and unity gain at low frequencies. See "hs" in the following diagrams.
  • HPI_FILTER_TYPE_EQ_BAND
    Has gain of nGain0_01dB at dwFrequencyHz and unity gain elsewhere. See "eq" in the following diagrams.
dwFrequencyHzis the defining frequency of the filter. It is the center frequency of types HPI_FILTER_TYPE_ BANDPASS, HPI_FILTER_TYPE_BANDSTOP, HPI_FILTER_TYPE_EQ_BAND. It is the -3dB frequency of HPI_FILTER_TYPE_LOWPASS, HPI_FILTER_TYPE_HIGHPASS when Q=1 or resonant frequency when Q>1 and it is the half gain frequency of HPI_FILTER_TYPE_LOWSHELF, HPI_FILTER_TYPE_HIGHSHELF. The maximum allowable value is half the current adapter samplerate i.e. Fs/2. When the adapter samplerate is changed, the equalizer filters will be recalculated. If this results in the band frequency being greater than Fs/2, then the filter will be turned off.
nQ100controls filter sharpness. To allow the use of an integer parameter, Filter Q = dwQ100/100.
In the following figure, gain is 20dB (10x) (nGain0_01dB=2000) and sampling frequency is normalized to 1Hz (10^0) and nFrequency is 0.1 x sampling frequency. Q=[0.2 0.5 1 2 4 8].
Q can also be thought of as affecting bandwidth or shelf slope of some of these filters.
Bandwidth is measured in octaves (between -3 dB frequencies for BPF and notch or between midpoint (dBgain/2) gain frequencies for peaking EQ).
The relationship between bandwidth and Q is:

 1/Q = 2*sinh[ln(2)/2*bandwidth*omega/sin(omega)]  (digital filter using BLT)
 or      1/Q = 2*sinh[ln(2)/2*bandwidth])           (analog filter prototype)
Where omega = 2*pi*frequency/sampleRate

Shelf slope S, a "shelf slope" parameter (for shelving EQ only). When S = 1, the shelf slope is as steep as it can be and remain monotonically increasing or decreasing gain with frequency. The shelf slope, in dB/octave, remains proportional to S for all other values.
The relationship between shelf slope and Q is 1/Q = sqrt[(A + 1/A)*(1/S - 1) + 2]
where A = 10^(dBgain/40)
Effect of Q on EQ filters

EQ_effect_of_Q.png
nGain0_01dBThe gain is expressed in milliBels (100ths of a decibel). Allowable range is -1000 to +1000 mB. Usable range will likely be less than this. This parameter is only applicable to the equalizer filter types HPI_FILTER_TYPE_LOWSHELF,HPI_FILTER_TYPE_HIGHSHELF and HPI_FILTER_TYPE_EQ_BAND. Other filters always have unity gain in the passband.
In the following figure, Q=1.0 and sampling frequency is normalized to 1Hz (10^0) and nFrequency is 0.1 x sampling frequency. dBgain=[-20 -10 0 10 20]
For example, to produce the upper (red) curve in the "Filtertype_eq_band" graph:

err= HPI_ParametricEQ_SetBand(
                phSubsys,
                hMicrophoneControl,
                HPI_FILTER_TYPE_EQ_BAND,
                4410    // 4.41khz
                100                     // Q=1
                20*100, // 20dB
                );

Effect of gain on EQ filters

EQ_effect_of_gain.png
hpi_err_t HPI_ParametricEQ_GetCoeffs ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint16_t  wIndex,
short  coeffs[5] 
)

Retrieve the calculated IIR filter coefficients (scaled by 1000 into integers).

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlEqualizer control handle.
wIndexIndex of band to Get.
coeffsReturned IIR filter coefficients * 1000 a1,a2,b0,b1,b2 (a0==0).