|
DSPark 1.6.1
Header-only audio DSP framework in pure C++20 — zero dependencies
|
Parametric multi-band EQ using cascaded biquads or FFT overlap-save convolution. More...
#include <Equalizer.h>

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. | |
| T | 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 | |
| T | 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< FilterMode > | filterMode_ { 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 |
Parametric multi-band EQ using cascaded biquads or FFT overlap-save convolution.
| T | Sample type (float or double). |
| MaxBands | Maximum number of EQ bands (compile-time, default 16). |
Definition at line 56 of file Equalizer.h.
|
strong |
Filter type for each EQ band.
Definition at line 70 of file Equalizer.h.
|
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.
|
default |
Non-virtual destructor to prevent vtable instantiation (zero virtual dispatch).
|
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().
| stages | Output buffer (capacity >= 5). |
Definition at line 685 of file Equalizer.h.
|
inlineprotectednoexcept |
Computes single-biquad coefficients for a band (analysis/kernel).
| cfg | Band configuration (its q must already be the effective one). |
Definition at line 650 of file Equalizer.h.
|
inlineprotectednoexcept |
The band Q the audio path actually uses (soft mode caps it by gain).
Definition at line 578 of file Equalizer.h.
|
inlinenoexcept |
Returns the current configuration of a band.
| index | Band index. |
Definition at line 391 of file Equalizer.h.
|
inline |
Direct access to a band's underlying FilterEngine.
| index | Band index. |
Definition at line 504 of file Equalizer.h.
|
inline |
Const overload.
Definition at line 507 of file Equalizer.h.
|
inlinenoexcept |
Returns the current filter mode.
Definition at line 431 of file Equalizer.h.
|
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.
|
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.
| frequencies | Array of frequencies in Hz. |
| magnitudes | Output array (same size, linear scale). |
| numPoints | Number of frequency points. |
Definition at line 476 of file Equalizer.h.
|
inlinenoexcept |
Returns the number of active bands.
Definition at line 365 of file Equalizer.h.
|
inlinenoexcept |
Returns whether soft mode is enabled.
Definition at line 460 of file Equalizer.h.
|
inline |
Serializes bands and modes (setup/UI threads; allocates).
Definition at line 511 of file Equalizer.h.
|
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.
| spec | Audio environment (sample rate, max block size, channels). |
Definition at line 108 of file Equalizer.h.
|
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.
| buffer | Audio data to process. |
Definition at line 174 of file Equalizer.h.
|
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).
| buffer | Audio buffer. |
Definition at line 800 of file Equalizer.h.
|
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.
| input | Input sample. |
| channel | Channel index (out-of-range channels pass through). |
Definition at line 231 of file Equalizer.h.
|
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.
|
inlinenoexcept |
Resets all filter states to zero to prevent ringing on playback start.
Definition at line 259 of file Equalizer.h.
|
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.
| index | Band index. |
| config | Complete band configuration. |
Definition at line 310 of file Equalizer.h.
|
inline |
Configures a band with frequency and gain (Peak filter).
| index | Band index (0 to MaxBands-1). |
| frequency | Center frequency in Hz. |
| gainDb | Boost/cut in dB. |
Definition at line 276 of file Equalizer.h.
|
inline |
Configures a band with frequency, gain, and Q.
| index | Band index. |
| frequency | Center frequency in Hz. |
| gainDb | Boost/cut in dB. |
| q | Quality factor. |
Definition at line 288 of file Equalizer.h.
|
inlinenoexcept |
Enables or disables a band without changing its parameters.
| index | Band index. |
| enabled | True to enable, false to bypass. |
Definition at line 402 of file Equalizer.h.
|
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.
| mode | Filter mode. |
Definition at line 421 of file Equalizer.h.
|
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.
|
inline |
Sets the number of active bands with auto-logarithmic spacing.
| count | Number of bands (1 to MaxBands). |
Definition at line 338 of file Equalizer.h.
|
inlinenoexcept |
Enables soft mode (anti-ringing Q reduction dynamically based on gain).
| enabled | True to enable soft mode. |
Definition at line 453 of file Equalizer.h.
|
inline |
Restores bands and modes from a blob (tolerant; rejects foreign ids).
Definition at line 540 of file Equalizer.h.
|
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.
|
inlineprotectednoexcept |
Translates BandConfigs into internal FilterEngine parameters safely. Called by processBlock when configDirty_ is true.
Definition at line 594 of file Equalizer.h.
|
protected |
Definition at line 876 of file Equalizer.h.
|
protected |
Definition at line 871 of file Equalizer.h.
|
protected |
Definition at line 879 of file Equalizer.h.
|
protected |
Definition at line 872 of file Equalizer.h.
|
protected |
Definition at line 883 of file Equalizer.h.
|
staticconstexprprotected |
Definition at line 866 of file Equalizer.h.
|
protected |
Max block size the LP engine was sized for (= its latency).
Definition at line 888 of file Equalizer.h.
|
protected |
Definition at line 884 of file Equalizer.h.
|
protected |
Definition at line 886 of file Equalizer.h.
|
protected |
Definition at line 892 of file Equalizer.h.
|
protected |
Definition at line 892 of file Equalizer.h.
|
protected |
Definition at line 887 of file Equalizer.h.
|
protected |
Definition at line 894 of file Equalizer.h.
|
protected |
Definition at line 890 of file Equalizer.h.
|
protected |
Definition at line 894 of file Equalizer.h.
|
protected |
Definition at line 894 of file Equalizer.h.
|
protected |
Definition at line 891 of file Equalizer.h.
|
protected |
Definition at line 894 of file Equalizer.h.
|
protected |
Definition at line 880 of file Equalizer.h.
|
protected |
Definition at line 869 of file Equalizer.h.
|
protected |
Definition at line 878 of file Equalizer.h.
|
protected |
Definition at line 868 of file Equalizer.h.