DSPark 1.6.1
Header-only audio DSP framework in pure C++20 — zero dependencies
Loading...
Searching...
No Matches
dspark::Equalizer< T, MaxBands > Class Template Reference

Parametric multi-band EQ using cascaded biquads or FFT overlap-save convolution. More...

#include <Equalizer.h>

Collaboration diagram for dspark::Equalizer< T, MaxBands >:

Classes

struct  BandConfig
 Full configuration for a single EQ band. More...
 

Public Types

enum class  FilterMode { MinimumPhase , LinearPhase }
 Filter processing mode. More...
 
enum class  BandType {
  Peak , LowShelf , HighShelf , LowPass ,
  HighPass , Notch , BandPass , Tilt
}
 Filter type for each EQ band. More...
 

Public Member Functions

 ~Equalizer ()=default
 Non-virtual destructor to prevent vtable instantiation (zero virtual dispatch).
 
void prepare (const AudioSpec &spec)
 Prepares all bands and allocates necessary resources for processing.
 
void processBlock (AudioBufferView< T > buffer) noexcept
 Processes an audio buffer in-place.
 
processSample (T input, int channel) noexcept
 Processes a single sample through all enabled bands (IIR mode only).
 
void reset () noexcept
 Resets all filter states to zero to prevent ringing on playback start.
 
void setBand (int index, T frequency, T gainDb)
 Configures a band with frequency and gain (Peak filter).
 
void setBand (int index, T frequency, T gainDb, T q)
 Configures a band with frequency, gain, and Q.
 
void setBand (int index, const BandConfig &config)
 Configures a band with full control over all parameters. Thread-safe.
 
void setNumBands (int count)
 Sets the number of active bands with auto-logarithmic spacing.
 
int getNumBands () const noexcept
 Returns the number of active bands.
 
void setMatchedBells (bool enabled) noexcept
 Switches Peak bands to the Orfanidis matched (de-cramped) design.
 
BandConfig getBandConfig (int index) const noexcept
 Returns the current configuration of a band.
 
void setBandEnabled (int index, bool enabled) noexcept
 Enables or disables a band without changing its parameters.
 
void setFilterMode (FilterMode mode) noexcept
 Sets the filter processing mode (Minimum Phase or Linear Phase).
 
FilterMode getFilterMode () const noexcept
 Returns the current filter mode.
 
int getLatency () const noexcept
 Returns the latency in samples.
 
void setSoftMode (bool enabled) noexcept
 Enables soft mode (anti-ringing Q reduction dynamically based on gain).
 
bool getSoftMode () const noexcept
 Returns whether soft mode is enabled.
 
void getMagnitudeForFrequencyArray (const T *frequencies, T *magnitudes, int numPoints) const noexcept
 Computes the combined magnitude response of all enabled bands.
 
FilterEngine< T > & getBandFilter (int index)
 Direct access to a band's underlying FilterEngine.
 
const FilterEngine< T > & getBandFilter (int index) const
 Const overload.
 
std::vector< uint8_t > getState () const
 Serializes bands and modes (setup/UI threads; allocates).
 
bool setState (const uint8_t *data, size_t size)
 Restores bands and modes from a blob (tolerant; rejects foreign ids).
 
int buildBandStages (const BandConfig &cfg, BiquadCoeffs *stages) const noexcept
 Fills stages with the ACTUAL biquad cascade for a band (per-stage Butterworth Q for multi-stage LP/HP, single biquad otherwise) and returns the stage count. Public analysis API: UIs use it to draw a magnitude response that matches what the IIR FilterEngine really applies, including the user's resonance on LP/HP cascades, soft mode's Q cap and the matched-bell design. Mirrors the engine's own parameter sanitization (frequency and Q floors). Requires prepare().
 

Protected Member Functions

effectiveQ (const BandConfig &cfg) const noexcept
 The band Q the audio path actually uses (soft mode caps it by gain).
 
void updateActiveFilters () noexcept
 Translates BandConfigs into internal FilterEngine parameters safely. Called by processBlock when configDirty_ is true.
 
BiquadCoeffs computeBandCoeffs (const BandConfig &cfg) const noexcept
 Computes single-biquad coefficients for a band (analysis/kernel).
 
void recomputeLinearPhaseKernel () noexcept
 Mathematically robust Linear Phase kernel computation.
 
void processLinearPhase (AudioBufferView< T > buffer) noexcept
 Linear-phase processing via overlap-save FFT convolution.
 

Static Protected Member Functions

static double shelfSlopeFromQ (double q, double gainDb) noexcept
 Converts a user-facing shelf Q into the RBJ shelf slope S.
 

Protected Attributes

AudioSpec spec_ {}
 
std::atomic< int > numBands_ { 0 }
 
std::array< FilterEngine< T >, MaxBands > bands_ {}
 
std::array< BandConfig, MaxBands > configs_ {}
 
std::array< std::atomic< bool >, MaxBands > bandEnabled_ {}
 
std::atomic< bool > softMode_ { false }
 
std::atomic< bool > configDirty_ { false }
 
std::atomic< bool > matchedBells_ { false }
 
std::atomic< FilterModefilterMode_ { FilterMode::MinimumPhase }
 
std::atomic< bool > lpDirty_ { true }
 
std::unique_ptr< FFTReal< T > > lpFft_
 
int lpFftSize_ = 0
 
int lpBlock_ = 0
 Max block size the LP engine was sized for (= its latency).
 
std::vector< T > lpKernel_
 
std::vector< std::vector< T > > lpPrevBlock_
 
std::vector< T > lpFftIn_
 
std::vector< T > lpFftOut_
 
std::vector< T > lpMagScratch_
 
std::vector< T > lpTempFreq_
 
std::vector< T > lpImpulse_
 
std::vector< T > lpKernelSpace_
 

Static Protected Attributes

static constexpr int kLpMaxBlockSize = 1 << 18
 

Detailed Description

template<FloatType T, int MaxBands = 16>
class dspark::Equalizer< T, MaxBands >

Parametric multi-band EQ using cascaded biquads or FFT overlap-save convolution.

Template Parameters
TSample type (float or double).
MaxBandsMaximum number of EQ bands (compile-time, default 16).

Definition at line 56 of file Equalizer.h.

Member Enumeration Documentation

◆ BandType

template<FloatType T, int MaxBands = 16>
enum class dspark::Equalizer::BandType
strong

Filter type for each EQ band.

Enumerator
Peak 

Parametric bell (boost/cut around frequency).

LowShelf 

Shelf: boosts/cuts below frequency.

HighShelf 

Shelf: boosts/cuts above frequency.

LowPass 

Removes frequencies above cutoff.

HighPass 

Removes frequencies below cutoff.

Notch 

Narrow rejection at frequency.

BandPass 

Bandpass around frequency.

Tilt 

Tilt EQ: pivots spectrum around frequency.

Definition at line 70 of file Equalizer.h.

◆ FilterMode

template<FloatType T, int MaxBands = 16>
enum class dspark::Equalizer::FilterMode
strong

Filter processing mode.

Enumerator
MinimumPhase 

IIR biquads (zero latency, minimum phase shift). Default.

LinearPhase 

FFT-based overlap-save (block-size latency, zero phase distortion).

Definition at line 60 of file Equalizer.h.

Constructor & Destructor Documentation

◆ ~Equalizer()

template<FloatType T, int MaxBands = 16>
dspark::Equalizer< T, MaxBands >::~Equalizer ( )
default

Non-virtual destructor to prevent vtable instantiation (zero virtual dispatch).

Member Function Documentation

◆ buildBandStages()

template<FloatType T, int MaxBands = 16>
int dspark::Equalizer< T, MaxBands >::buildBandStages ( const BandConfig cfg,
BiquadCoeffs stages 
) const
inlinenoexcept

Fills stages with the ACTUAL biquad cascade for a band (per-stage Butterworth Q for multi-stage LP/HP, single biquad otherwise) and returns the stage count. Public analysis API: UIs use it to draw a magnitude response that matches what the IIR FilterEngine really applies, including the user's resonance on LP/HP cascades, soft mode's Q cap and the matched-bell design. Mirrors the engine's own parameter sanitization (frequency and Q floors). Requires prepare().

Parameters
stagesOutput buffer (capacity >= 5).

Definition at line 685 of file Equalizer.h.

◆ computeBandCoeffs()

template<FloatType T, int MaxBands = 16>
BiquadCoeffs dspark::Equalizer< T, MaxBands >::computeBandCoeffs ( const BandConfig cfg) const
inlineprotectednoexcept

Computes single-biquad coefficients for a band (analysis/kernel).

Parameters
cfgBand configuration (its q must already be the effective one).
Returns
BiquadCoeffs structure.

Definition at line 650 of file Equalizer.h.

◆ effectiveQ()

template<FloatType T, int MaxBands = 16>
T dspark::Equalizer< T, MaxBands >::effectiveQ ( const BandConfig cfg) const
inlineprotectednoexcept

The band Q the audio path actually uses (soft mode caps it by gain).

Definition at line 578 of file Equalizer.h.

◆ getBandConfig()

template<FloatType T, int MaxBands = 16>
BandConfig dspark::Equalizer< T, MaxBands >::getBandConfig ( int  index) const
inlinenoexcept

Returns the current configuration of a band.

Parameters
indexBand index.
Returns
Copy of the band's BandConfig.

Definition at line 391 of file Equalizer.h.

◆ getBandFilter() [1/2]

template<FloatType T, int MaxBands = 16>
FilterEngine< T > & dspark::Equalizer< T, MaxBands >::getBandFilter ( int  index)
inline

Direct access to a band's underlying FilterEngine.

Parameters
indexBand index.
Returns
Reference to the FilterEngine for this band.

Definition at line 504 of file Equalizer.h.

◆ getBandFilter() [2/2]

template<FloatType T, int MaxBands = 16>
const FilterEngine< T > & dspark::Equalizer< T, MaxBands >::getBandFilter ( int  index) const
inline

Const overload.

Definition at line 507 of file Equalizer.h.

◆ getFilterMode()

template<FloatType T, int MaxBands = 16>
FilterMode dspark::Equalizer< T, MaxBands >::getFilterMode ( ) const
inlinenoexcept

Returns the current filter mode.

Definition at line 431 of file Equalizer.h.

◆ getLatency()

template<FloatType T, int MaxBands = 16>
int dspark::Equalizer< T, MaxBands >::getLatency ( ) const
inlinenoexcept

Returns the latency in samples.

0 for MinimumPhase; the prepared max block size for LinearPhase. Reports 0 when the linear-phase engine is unavailable (not prepared yet), so the value always matches the path that actually runs.

Definition at line 443 of file Equalizer.h.

◆ getMagnitudeForFrequencyArray()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::getMagnitudeForFrequencyArray ( const T *  frequencies,
T *  magnitudes,
int  numPoints 
) const
inlinenoexcept

Computes the combined magnitude response of all enabled bands.

Evaluates the same per-stage cascade the audio path applies (including soft mode's Q cap and the matched-bell design), so the drawn curve matches what is heard in both filter modes.

Parameters
frequenciesArray of frequencies in Hz.
magnitudesOutput array (same size, linear scale).
numPointsNumber of frequency points.

Definition at line 476 of file Equalizer.h.

◆ getNumBands()

template<FloatType T, int MaxBands = 16>
int dspark::Equalizer< T, MaxBands >::getNumBands ( ) const
inlinenoexcept

Returns the number of active bands.

Definition at line 365 of file Equalizer.h.

◆ getSoftMode()

template<FloatType T, int MaxBands = 16>
bool dspark::Equalizer< T, MaxBands >::getSoftMode ( ) const
inlinenoexcept

Returns whether soft mode is enabled.

Definition at line 460 of file Equalizer.h.

◆ getState()

template<FloatType T, int MaxBands = 16>
std::vector< uint8_t > dspark::Equalizer< T, MaxBands >::getState ( ) const
inline

Serializes bands and modes (setup/UI threads; allocates).

Definition at line 511 of file Equalizer.h.

◆ prepare()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::prepare ( const AudioSpec spec)
inline

Prepares all bands and allocates necessary resources for processing.

Must be called from the host's prepareToPlay/setup method. Performs all memory allocations, including the linear-phase engine, so setFilterMode(LinearPhase) works even when called after prepare(). An invalid spec (non-positive or non-finite fields) is a no-op that keeps the previous state.

Parameters
specAudio environment (sample rate, max block size, channels).

Definition at line 108 of file Equalizer.h.

◆ processBlock()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::processBlock ( AudioBufferView< T >  buffer)
inlinenoexcept

Processes an audio buffer in-place.

Guarantees zero allocations. Checks atomic flags lock-free to update DSP state if the host changed parameters. In LinearPhase mode a pending band change recomputes the FIR kernel on this thread (a bounded, allocation- free spike); switching modes changes getLatency(), so notify the host and consider reset() to clear the other path's tail.

Parameters
bufferAudio data to process.

Definition at line 174 of file Equalizer.h.

◆ processLinearPhase()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::processLinearPhase ( AudioBufferView< T >  buffer)
inlineprotectednoexcept

Linear-phase processing via overlap-save FFT convolution.

Blocks larger than the prepared max block size pass through unprocessed (the engine's buffers are sized in prepare(); hosts honour maxBlockSize).

Parameters
bufferAudio buffer.

Definition at line 800 of file Equalizer.h.

◆ processSample()

template<FloatType T, int MaxBands = 16>
T dspark::Equalizer< T, MaxBands >::processSample ( input,
int  channel 
)
inlinenoexcept

Processes a single sample through all enabled bands (IIR mode only).

Pending band changes are consumed here too (applied immediately, without the block path's parameter smoothing), so per-sample streams that never call processBlock() still pick up setBand() and friends.

Parameters
inputInput sample.
channelChannel index (out-of-range channels pass through).
Returns
EQ'd output sample.

Definition at line 231 of file Equalizer.h.

◆ recomputeLinearPhaseKernel()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::recomputeLinearPhaseKernel ( )
inlineprotectednoexcept

Mathematically robust Linear Phase kernel computation.

Constructs a true zero-phase impulse response by evaluating the H(k) magnitude, performing IFFT, shifting by M/2 to make it causal, windowing it with Blackman-Harris to reduce truncation artifacts, zero-padding to N, and converting back to FFT for overlap-save.

Definition at line 726 of file Equalizer.h.

◆ reset()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::reset ( )
inlinenoexcept

Resets all filter states to zero to prevent ringing on playback start.

Definition at line 259 of file Equalizer.h.

◆ setBand() [1/3]

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::setBand ( int  index,
const BandConfig config 
)
inline

Configures a band with full control over all parameters. Thread-safe.

Non-finite frequency/gain/Q fields fall back to the band's current values (they would otherwise poison the serialized state, the analysis curve, and the linear-phase kernel); wild type/slope values clamp.

Parameters
indexBand index.
configComplete band configuration.

Definition at line 310 of file Equalizer.h.

◆ setBand() [2/3]

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::setBand ( int  index,
frequency,
gainDb 
)
inline

Configures a band with frequency and gain (Peak filter).

Parameters
indexBand index (0 to MaxBands-1).
frequencyCenter frequency in Hz.
gainDbBoost/cut in dB.

Definition at line 276 of file Equalizer.h.

◆ setBand() [3/3]

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::setBand ( int  index,
frequency,
gainDb,
q 
)
inline

Configures a band with frequency, gain, and Q.

Parameters
indexBand index.
frequencyCenter frequency in Hz.
gainDbBoost/cut in dB.
qQuality factor.

Definition at line 288 of file Equalizer.h.

◆ setBandEnabled()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::setBandEnabled ( int  index,
bool  enabled 
)
inlinenoexcept

Enables or disables a band without changing its parameters.

Parameters
indexBand index.
enabledTrue to enable, false to bypass.

Definition at line 402 of file Equalizer.h.

◆ setFilterMode()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::setFilterMode ( FilterMode  mode)
inlinenoexcept

Sets the filter processing mode (Minimum Phase or Linear Phase).

Works before or after prepare() (the linear-phase engine is always pre-allocated by prepare()). Wild enum values clamp. Switching modes changes getLatency(): hosts must be notified.

Parameters
modeFilter mode.

Definition at line 421 of file Equalizer.h.

◆ setMatchedBells()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::setMatchedBells ( bool  enabled)
inlinenoexcept

Switches Peak bands to the Orfanidis matched (de-cramped) design.

Bilinear bells cramp near Nyquist (narrower, response pinned at fs/2); the matched design prescribes the analog prototype's Nyquist gain so high bells keep their analog shape, the state-of-the-art digital EQ behaviour. Applies to the IIR engines, the linear-phase kernel, and the analysis curve alike. Off by default for bit-compatibility with previous output.

Definition at line 380 of file Equalizer.h.

◆ setNumBands()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::setNumBands ( int  count)
inline

Sets the number of active bands with auto-logarithmic spacing.

Parameters
countNumber of bands (1 to MaxBands).

Definition at line 338 of file Equalizer.h.

◆ setSoftMode()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::setSoftMode ( bool  enabled)
inlinenoexcept

Enables soft mode (anti-ringing Q reduction dynamically based on gain).

Parameters
enabledTrue to enable soft mode.

Definition at line 453 of file Equalizer.h.

◆ setState()

template<FloatType T, int MaxBands = 16>
bool dspark::Equalizer< T, MaxBands >::setState ( const uint8_t *  data,
size_t  size 
)
inline

Restores bands and modes from a blob (tolerant; rejects foreign ids).

Definition at line 540 of file Equalizer.h.

◆ shelfSlopeFromQ()

template<FloatType T, int MaxBands = 16>
static double dspark::Equalizer< T, MaxBands >::shelfSlopeFromQ ( double  q,
double  gainDb 
)
inlinestaticprotectednoexcept

Converts a user-facing shelf Q into the RBJ shelf slope S.

RBJ relation: 1/Q^2 = (A + 1/A) * (1/S - 1) + 2 with A = 10^(dB/40). Q = 0.7071 maps to S = 1 (the standard shelf). Out-of-domain values are clamped to the stable (0, 1] range that the coefficient factory accepts.

Definition at line 635 of file Equalizer.h.

◆ updateActiveFilters()

template<FloatType T, int MaxBands = 16>
void dspark::Equalizer< T, MaxBands >::updateActiveFilters ( )
inlineprotectednoexcept

Translates BandConfigs into internal FilterEngine parameters safely. Called by processBlock when configDirty_ is true.

Definition at line 594 of file Equalizer.h.

Member Data Documentation

◆ bandEnabled_

template<FloatType T, int MaxBands = 16>
std::array<std::atomic<bool>, MaxBands> dspark::Equalizer< T, MaxBands >::bandEnabled_ {}
protected

Definition at line 876 of file Equalizer.h.

◆ bands_

template<FloatType T, int MaxBands = 16>
std::array<FilterEngine<T>, MaxBands> dspark::Equalizer< T, MaxBands >::bands_ {}
protected

Definition at line 871 of file Equalizer.h.

◆ configDirty_

template<FloatType T, int MaxBands = 16>
std::atomic<bool> dspark::Equalizer< T, MaxBands >::configDirty_ { false }
protected

Definition at line 879 of file Equalizer.h.

◆ configs_

template<FloatType T, int MaxBands = 16>
std::array<BandConfig, MaxBands> dspark::Equalizer< T, MaxBands >::configs_ {}
protected

Definition at line 872 of file Equalizer.h.

◆ filterMode_

template<FloatType T, int MaxBands = 16>
std::atomic<FilterMode> dspark::Equalizer< T, MaxBands >::filterMode_ { FilterMode::MinimumPhase }
protected

Definition at line 883 of file Equalizer.h.

◆ kLpMaxBlockSize

template<FloatType T, int MaxBands = 16>
constexpr int dspark::Equalizer< T, MaxBands >::kLpMaxBlockSize = 1 << 18
staticconstexprprotected

Definition at line 866 of file Equalizer.h.

◆ lpBlock_

template<FloatType T, int MaxBands = 16>
int dspark::Equalizer< T, MaxBands >::lpBlock_ = 0
protected

Max block size the LP engine was sized for (= its latency).

Definition at line 888 of file Equalizer.h.

◆ lpDirty_

template<FloatType T, int MaxBands = 16>
std::atomic<bool> dspark::Equalizer< T, MaxBands >::lpDirty_ { true }
protected

Definition at line 884 of file Equalizer.h.

◆ lpFft_

template<FloatType T, int MaxBands = 16>
std::unique_ptr<FFTReal<T> > dspark::Equalizer< T, MaxBands >::lpFft_
protected

Definition at line 886 of file Equalizer.h.

◆ lpFftIn_

template<FloatType T, int MaxBands = 16>
std::vector<T> dspark::Equalizer< T, MaxBands >::lpFftIn_
protected

Definition at line 892 of file Equalizer.h.

◆ lpFftOut_

template<FloatType T, int MaxBands = 16>
std::vector<T> dspark::Equalizer< T, MaxBands >::lpFftOut_
protected

Definition at line 892 of file Equalizer.h.

◆ lpFftSize_

template<FloatType T, int MaxBands = 16>
int dspark::Equalizer< T, MaxBands >::lpFftSize_ = 0
protected

Definition at line 887 of file Equalizer.h.

◆ lpImpulse_

template<FloatType T, int MaxBands = 16>
std::vector<T> dspark::Equalizer< T, MaxBands >::lpImpulse_
protected

Definition at line 894 of file Equalizer.h.

◆ lpKernel_

template<FloatType T, int MaxBands = 16>
std::vector<T> dspark::Equalizer< T, MaxBands >::lpKernel_
protected

Definition at line 890 of file Equalizer.h.

◆ lpKernelSpace_

template<FloatType T, int MaxBands = 16>
std::vector<T> dspark::Equalizer< T, MaxBands >::lpKernelSpace_
protected

Definition at line 894 of file Equalizer.h.

◆ lpMagScratch_

template<FloatType T, int MaxBands = 16>
std::vector<T> dspark::Equalizer< T, MaxBands >::lpMagScratch_
protected

Definition at line 894 of file Equalizer.h.

◆ lpPrevBlock_

template<FloatType T, int MaxBands = 16>
std::vector<std::vector<T> > dspark::Equalizer< T, MaxBands >::lpPrevBlock_
protected

Definition at line 891 of file Equalizer.h.

◆ lpTempFreq_

template<FloatType T, int MaxBands = 16>
std::vector<T> dspark::Equalizer< T, MaxBands >::lpTempFreq_
protected

Definition at line 894 of file Equalizer.h.

◆ matchedBells_

template<FloatType T, int MaxBands = 16>
std::atomic<bool> dspark::Equalizer< T, MaxBands >::matchedBells_ { false }
protected

Definition at line 880 of file Equalizer.h.

◆ numBands_

template<FloatType T, int MaxBands = 16>
std::atomic<int> dspark::Equalizer< T, MaxBands >::numBands_ { 0 }
protected

Definition at line 869 of file Equalizer.h.

◆ softMode_

template<FloatType T, int MaxBands = 16>
std::atomic<bool> dspark::Equalizer< T, MaxBands >::softMode_ { false }
protected

Definition at line 878 of file Equalizer.h.

◆ spec_

template<FloatType T, int MaxBands = 16>
AudioSpec dspark::Equalizer< T, MaxBands >::spec_ {}
protected

Definition at line 868 of file Equalizer.h.


The documentation for this class was generated from the following file: