N-Band Equalizer using FIR filters with logarithmically spaced bands. More...

#include <EqualizerNBands.h>

Inheritance diagram for EqualizerNBands< SampleT, AccT, NUM_TAPS, NUM_BANDS >:

Classes
class	EQFIRFilter

Public Member Functions
	EqualizerNBands (AudioOutput &out)

	EqualizerNBands (AudioStream &stream)

	EqualizerNBands (Print &out)

	EqualizerNBands (Stream &in)

virtual void	addNotifyAudioChange (AudioInfoSupport &bi)
	Adds target to be notified about audio changes.

virtual AudioInfo	audioInfo () override
	provides the actual input AudioInfo

virtual AudioInfo	audioInfoOut ()

virtual int	available () override

virtual int	availableForWrite () override

bool	begin () override
	Initializes the equalizer with the current audio info.

bool	begin (AudioInfo info)

virtual void	clearNotifyAudioChange ()
	Deletes all change notify subscriptions.

void	end ()

virtual void	flush () override

int	getBandCount () const
	Get number of bands.

float	getBandDB (int band) const

float	getBandFrequency (int band) const

float	getBandGain (int band)
	Get current gain for a specific band as normalized volume (-1.0 to 1.0)

bool	isNotifyActive ()
	Checks if the automatic AudioInfo update is active.

virtual	operator bool ()

size_t	readBytes (uint8_t *data, size_t len) override

virtual size_t	readSilence (uint8_t *buffer, size_t length)
	Source to generate silence: just sets the buffer to 0.

virtual bool	removeNotifyAudioChange (AudioInfoSupport &bi)
	Removes a target in order not to be notified about audio changes.

virtual void	setAudioInfo (AudioInfo newInfo) override
	Defines the input AudioInfo.

void	setAutoUpdate (bool enabled)

bool	setBandDB (int band, float gainDb)

bool	setBandGain (int band, float volume)

bool	setBandGains (float volume)
	Set same gain for all frequency bands.

void	setNotifyActive (bool flag)
	Deactivate/Reactivate automatic AudioInfo updates: (default is active)

void	setOutput (Print &out) override

void	setStream (Stream &io) override

void	setWriteBufferSize (int size)

bool	update ()

size_t	write (const uint8_t *data, size_t len) override

virtual size_t	write (uint8_t ch) override

virtual void	writeSilence (size_t len)
	Writes len bytes of silence (=0).

Protected Member Functions
void	enterCritical ()

void	exitCritical ()

void	initializeKernel (volatile int16_t *kernel)

template<typename T >
float	map (T x, T in_min, T in_max, T out_min, T out_max)

void	maybeUpdateKernel ()

virtual int	not_supported (int out, const char *msg="")

void	notifyAudioChange (AudioInfo info)

void	preCalculateWindow ()

void	refillReadBuffer ()

void	setupFrequencies (int sampleRate)

float	sinc (float x)

bool	updateFIRKernel ()

Protected Attributes
int	_timeout = 10

volatile int16_t *	activeKernel

bool	autoUpdate = false

float	centerFreqs [NUM_BANDS]

int	currentSampleRate = 0

FilteredStream< SampleT, SampleT >	filtered

Vector< EQFIRFilter >	fir_vector
	Vector of FIR filters for each channel.

float	gains [NUM_BANDS] = {0}

volatile bool	gainsDirty = false

AudioInfo	info

bool	is_notify_active = true

volatile bool	isUpdating = false

int16_t	kernelA [NUM_TAPS]

int16_t	kernelB [NUM_TAPS]

Vector< AudioInfoSupport * >	notify_vector

Print *	p_print = nullptr
	Output stream for write operations.

Stream *	p_stream = nullptr
	Input stream for read operations.

float	pendingGains [NUM_BANDS] = {0}

float	tempFloat [NUM_TAPS] = {0}

RingBuffer< uint8_t >	tmp_in {0}

RingBuffer< uint8_t >	tmp_out {0}

volatile int16_t *	updateKernel

float	windowCoeffs [NUM_TAPS]

int	write_buffer_size = MAX_SINGLE_CHARS

Static Protected Attributes
static constexpr float	Q15_SCALE = 32767.0f

Detailed Description

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>
class audio_tools::EqualizerNBands< SampleT, AccT, NUM_TAPS, NUM_BANDS >

N-Band Equalizer using FIR filters with logarithmically spaced bands.

This class implements a graphic equalizer with configurable number of bands using FIR (Finite Impulse Response) filtering. Frequency bands are logarithmically spaced between 20Hz and Nyquist frequency.

Features:

Template-based configuration for number of taps and bands
Fixed-point Q15 arithmetic for efficient processing on embedded systems
Blackman windowing for reduced spectral leakage
Per-band gain control (-90dB to +12dB)
Multi-channel support
Double-buffered kernel for thread-safe real-time updates

Thread Safety: Uses double-buffering with two kernel buffers. Audio processing reads from the active kernel while updates are written to the inactive kernel. An atomic pointer swap ensures glitch-free transitions without blocking audio processing.

Template Parameters

NUM_TAPS	Number of FIR filter taps (higher = sharper transitions, more CPU usage). Typical values: 64, 128, 256
NUM_BANDS	Number of frequency bands. Typical values: 3, 5, 10, 31

Note: NUM_TAPS should be odd for symmetric filter response; Higher NUM_TAPS values require more memory and processing time

Constructor & Destructor Documentation

◆ EqualizerNBands() [1/4]

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

EqualizerNBands ( Print & out )

inline

Constructor with Print output

Parameters

out	Print stream for output

◆ EqualizerNBands() [2/4]

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

EqualizerNBands ( Stream & in )

inline

Constructor with Stream input

Parameters

in	Stream for input

◆ EqualizerNBands() [3/4]

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

EqualizerNBands ( AudioOutput & out )

inline

Constructor with AudioOutput

Parameters

out	AudioOutput for output with automatic audio change notifications

◆ EqualizerNBands() [4/4]

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

EqualizerNBands ( AudioStream & stream )

inline

Constructor with AudioStream

Parameters

stream AudioStream for input/output with automatic audio change notifications

Member Function Documentation

◆ addNotifyAudioChange()

virtual void addNotifyAudioChange ( AudioInfoSupport & bi )

inlinevirtualinherited

Adds target to be notified about audio changes.

Reimplemented in CodecNOP, EncodedAudioOutput, EncodedAudioStream, AACDecoderFDK, DecoderBasic, CodecChain, MP3DecoderHelix, MP3DecoderMAD, OggContainerDecoder, RTSPClient< TcpClient, UdpSocket >, Pipeline, and Pipeline::ModifyingStreamAdapter.

◆ audioInfo()

virtual AudioInfo audioInfo ( )

inlineoverridevirtualinherited

provides the actual input AudioInfo

Implements AudioInfoSupport.

Reimplemented in JupyterAudioT< T >, MozziStream, TimerCallbackAudioStream, EncodedAudioStream, PureDataStream, AdapterAudioOutputToAudioStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, and InputMerge< T >.

◆ audioInfoOut()

virtual AudioInfo audioInfoOut ( )

inlinevirtualinherited

provides the actual output AudioInfo: this is usually the same as audioInfo() unless we use a transforming stream

Reimplemented in PureDataStream, PWMAudioOutput, ChannelFormatConverterStreamT< T >, ChannelFormatConverterStream, NumberFormatConverterStreamT< TFrom, TTo >, NumberFormatConverterStream, FormatConverterStream, Pipeline, ResampleStream, and ResampleStreamT< TInterpolator >.

◆ available()

virtual int available ( )

inlineoverridevirtualinherited

◆ availableForWrite()

virtual int availableForWrite ( )

inlineoverridevirtualinherited

Reimplemented from Print.

Reimplemented in UDPStream, AudioFFTBase, I2SCodecStream, A2DPStream, AbstractURLStream, URLStreamESP32, Equalizer3Bands, Equalizer3BandsPerChannel, I2SStream, MeasuringStream, ProgressStream, FrequencyDetectorAutoCorrelation, FrequencyDetectorZeroCrossing, and VolumeStream.

◆ begin()

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

bool begin ( )

inlineoverridevirtual

Initializes the equalizer with the current audio info.

Reimplemented from BaseStream.

◆ clearNotifyAudioChange()

virtual void clearNotifyAudioChange ( )

inlinevirtualinherited

Deletes all change notify subscriptions.

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

◆ end()

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

void end ( )

inlinevirtual

Reimplemented from BaseStream.

◆ flush()

virtual void flush ( )

inlineoverridevirtualinherited

Reimplemented from Print.

Reimplemented in ResampleStream, BufferedTaskStream, and BufferedStream.

◆ getBandDB()

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

float getBandDB ( int band ) const

inline

Get current gain for a specific band in dB

Parameters

band	Band index (0 to NUM_BANDS-1)

Returns: Gain in dB (-90 to +12), or 0 if band index invalid

◆ getBandFrequency()

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

float getBandFrequency ( int band ) const

inline

Get center frequency for a specific band

Parameters

band	Band index (0 to NUM_BANDS-1)

Returns: Center frequency in Hz, or 0 if band index invalid

◆ operator bool()

virtual operator bool ( )

inlinevirtualinherited

Reimplemented in A2DPStream, ICYStreamT< T >, I2SStream, MemoryStream, and Pipeline.

◆ readBytes()

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

size_t readBytes	(	uint8_t *	data,
		size_t	len
	)

inlineoverridevirtual

Reimplemented from AudioStream.

◆ removeNotifyAudioChange()

virtual bool removeNotifyAudioChange ( AudioInfoSupport & bi )

inlinevirtualinherited

Removes a target in order not to be notified about audio changes.

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

◆ setAudioInfo()

virtual void setAudioInfo ( AudioInfo info )

inlineoverridevirtualinherited

Defines the input AudioInfo.

Implements AudioInfoSupport.

Reimplemented in VS1053Stream, WM8960Stream, ChannelFormatConverterStreamT< T >, ChannelFormatConverterStream, VolumeStream, MiniAudioStream, PortAudioStream, I2SCodecStream, MozziStream, SPDIFOutput, AudioLoRa, AnalogAudioStream, I2SStream, TimerCallbackAudioStream, AudioBLEStream, LoRaStream, AudioFFTBase, AudioKitStream, VBANStream, AnalogAudioArduino, Equalizer3Bands, Equalizer3BandsPerChannel, AdapterAudioOutputToAudioStream, TimedStream, MeasuringStream, ProgressStream, CallbackStream, VolumeMeter, AudioInputMonitor, FormatConverterStream, FadeStream, GoertzelStream, Pipeline::ModifyingStreamAdapter, MDFEchoCancellationStream< Allocator >, EncodedAudioStream, PureDataStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, NumberFormatConverterStreamT< TFrom, TTo >, NumberFormatConverterStream, Pipeline, ResampleStream, and ResampleStreamT< TInterpolator >.

◆ setAutoUpdate()

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

void setAutoUpdate ( bool enabled )

inline

Enable/disable automatic kernel updates during read/write

Parameters

enabled When true, pending gain changes are applied automatically

◆ setBandDB()

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

bool setBandDB	(	int	band,
		float	gainDb
	)

inline

Set gain for a specific band directly in dB

Parameters

band	Band index (0 to NUM_BANDS-1)
gainDb	Gain in dB (-90 to +12). The lower limit matches Q15 dynamic range; the upper limit prevents clipping.

◆ setBandGain()

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

bool setBandGain	(	int	band,
		float	volume
	)

inline

Set gain for a specific frequency band

Parameters

band	Band index (0 to NUM_BANDS-1)
volume	Volume level (-1.0 to 1.0) mapped to -12dB to +12dB. For deeper cuts use setBandDB() directly.

◆ setOutput()

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

void setOutput ( Print & out )

inlineoverridevirtual

Defines/Changes the output target

Parameters

out	Print stream where processed audio will be written

Implements ModifyingStream.

◆ setStream()

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

void setStream ( Stream & io )

inlineoverridevirtual

Defines/Changes the input & output stream

Parameters

io	Stream to use for both reading and writing audio data

Implements ModifyingStream.

◆ write() [1/2]

template<typename SampleT = int16_t, typename AccT = int64_t, int NUM_TAPS = 128, int NUM_BANDS = 12>

size_t write	(	const uint8_t *	data,
		size_t	len
	)

inlineoverridevirtual

Reimplemented from AudioStream.

◆ write() [2/2]

virtual size_t write ( uint8_t ch )

inlineoverridevirtualinherited

Reimplemented in BufferedTaskStream, and BufferedStream.

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

src/AudioTools/Sandbox/EqualizerNBands.h

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ EqualizerNBands() [1/4]

◆ EqualizerNBands() [2/4]

◆ EqualizerNBands() [3/4]

◆ EqualizerNBands() [4/4]

Member Function Documentation

◆ addNotifyAudioChange()

◆ audioInfo()

◆ audioInfoOut()

◆ available()

◆ availableForWrite()

◆ begin()

◆ clearNotifyAudioChange()

◆ end()

◆ flush()

◆ getBandDB()

◆ getBandFrequency()

◆ operator bool()

◆ readBytes()

◆ removeNotifyAudioChange()

◆ setAudioInfo()

◆ setAutoUpdate()

◆ setBandDB()

◆ setBandGain()

◆ setOutput()

◆ setStream()

◆ write() [1/2]

◆ write() [2/2]