MDFEchoCancellation< Allocator > Class Template Reference

Acoustic echo canceller using MDF algorithm. More...

#include <MDFEchoCancellation.h>

Inheritance diagram for MDFEchoCancellation< Allocator >:

Public Member Functions
	MDFEchoCancellation (int filterLength, AudioFFTBase &fftDriver, const Allocator &alloc=Allocator())
	MDFEchoCancellation (int filterLength, int nbMic, int nbSpeakers, AudioFFTBase &fftDriver, const Allocator &alloc=Allocator())
	~MDFEchoCancellation ()
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
virtual bool	begin ()
void	cancel (const echo_int16_t *rec, const echo_int16_t *play, echo_int16_t *out)
void	capture (const echo_int16_t *rec, echo_int16_t *out)
virtual void	clearNotifyAudioChange ()
	Deletes all change notify subscriptions.
int	control (int request, void *ptr)
virtual void	end ()
virtual void	flush () override
int	getFilterLength ()
int	getFrameSize ()
void	getImpulseResponse (echo_int32_t *response)
int	getImpulseResponseSize ()
int	getMicChannels ()
int	getSamplingRate ()
int	getSpeakerChannels ()
EchoState *	getState ()
bool	isNotifyActive ()
	Checks if the automatic AudioInfo update is active.
virtual	operator bool ()
void	playback (const echo_int16_t *play)
virtual 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.
void	reset ()
virtual void	setAudioInfo (AudioInfo newInfo) override
	Defines the input AudioInfo.
void	setFFTDriver (AudioFFTBase &fftDriver)
void	setFilterLength (int len)
void	setMicChannels (int num)
void	setNotifyActive (bool flag)
	Deactivate/Reactivate automatic AudioInfo updates: (default is active)
void	setSamplingRate (int rate)
void	setSpeakerChannels (int num)
void	setWriteBufferSize (int size)
virtual 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
template<typename T >
T *	echoAlloc (size_t count)
	Allocate memory for array of type T using custom allocator.
void	echoCancellationImpl (EchoState *st, const echo_int16_t *in, const echo_int16_t *far_end, echo_int16_t *out)
	Core echo cancellation implementation.
void	echoFatal (const char *str)
template<typename T >
void	echoFree (T *ptr, size_t count=0)
	Deallocate memory using custom allocator.
EchoState *	echoStateInitMc (int frame_size, int filter_length, int nb_mic, int nb_speakers)
	Initialize multi-channel echo canceller state.
void	echoWarning (const char *str)
void	ensureInitialized ()
	Ensure echo canceller is initialized (lazy initialization)
void	filterDcNotch16 (const echo_int16_t *in, echo_word16_t radius, echo_word16_t *out, int len, echo_mem_t *mem, int stride)
	Apply DC notch filter to remove DC offset.
void	mdfAdjustProp (const echo_word32_t *W, int N, int M, int P, echo_word16_t *prop)
	Adjust proportional adaptation weights.
echo_word32_t	mdfInnerProd (const echo_word16_t *x, const echo_word16_t *y, int len)
	Compute inner product of two vectors.
virtual int	not_supported (int out, const char *msg="")
void	notifyAudioChange (AudioInfo info)
void	powerSpectrum (const echo_word16_t *X, echo_word32_t *ps, int N)
	Compute power spectrum from FFT output.
void	powerSpectrumAccum (const echo_word16_t *X, echo_word32_t *ps, int N)
	Accumulate power spectrum from FFT output.
void	refillReadBuffer ()
void	spectralMulAccum (const echo_word16_t *X, const echo_word32_t *Y, echo_word16_t *acc, int N, int M)
	Accumulate spectral multiplication across multiple frames.
float	spxCos (float x)
	Compute cosine function.
float	spxExp (float x)
	Compute exponential function.
echo_int16_t	spxIlog2 (echo_uint32_t x)
float	spxSqrt (float x)
void	weightedSpectralMulConj (const echo_float_t *w, const echo_float_t p, const echo_word16_t *X, const echo_word16_t *Y, echo_word32_t *prod, int N)
	Compute weighted spectral multiplication with conjugate.

Protected Attributes
int	_timeout = 10
Allocator	allocator
AudioFFTBase *	fft_driver
int	filter_length
AudioInfo	info
bool	initialized = false
bool	is_notify_active = true
int	nb_mic
int	nb_speakers
Vector< AudioInfoSupport * >	notify_vector
EchoState *	state = nullptr
RingBuffer< uint8_t >	tmp_in {0}
RingBuffer< uint8_t >	tmp_out {0}
int	write_buffer_size = MAX_SINGLE_CHARS

Detailed Description

template<typename Allocator = std::allocator<uint8_t>>
class audio_tools::MDFEchoCancellation< Allocator >

Acoustic echo canceller using MDF algorithm.

High-performance echo cancellation implementation based on the Multi-Delay block Frequency adaptive filter (MDF) algorithm. Supports both single and multi-channel configurations with customizable memory allocation.

The echo canceller operates by:

• Learning the echo path between loudspeakers and microphones
• Adaptively filtering the playback signal to predict the echo
• Subtracting the predicted echo from the captured microphone signal

Features:

• Header-only C++ implementation
• Custom allocator support for embedded systems
• Fixed-point and floating-point arithmetic modes
• Two-path filter for improved double-talk handling
• Multi-channel support (multiple microphones and speakers)

Template Parameters

Allocator

Custom allocator type for memory management (defaults to std::allocator<uint8_t>)

Note

This implementation requires an external FFT driver implementing the AudioFFTBase interface from AudioFFT.h

Example usage:

FFTDriverImpl fftDriver;
EchoCanceller<> echo(frameSize, filterLength, fftDriver);
echo.setSamplingRate(16000);
echo.cancellation(micData, speakerData, outputData);

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

Reimplemented from Stream.

Reimplemented in AudioKitStream, AudioFFTBase, I2SCodecStream, TfLiteAudioStream, A2DPStream, HLSStreamT< URLStream >, ICYStreamT< T >, BufferedTaskStream, UDPStream, Equalizer3Bands, Equalizer3BandsPerChannel, I2SStream, TimedStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, BufferedStream, ConverterStream< T >, InputMerge< T >, FrequencyDetectorAutoCorrelation, FrequencyDetectorZeroCrossing, Pipeline::ModifyingStreamAdapter, and VolumeStream.

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()

virtual bool begin ( )

inlinevirtualinherited

Reimplemented in AudioOutputWithCallback, SPDIFOutput, VS1053Stream, WM8960Stream, AdaptiveResamplingStream, ESPNowStream, Equalizer3BandsPerChannel, TimerCallbackAudioStream, FrequencyDetectorAutoCorrelation, GoertzelStream, AudioFFTBase, HLSStreamT< URLStream >, AnalogAudioArduino, AnalogAudioStream, MemoryStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, AudioInputMonitor, FormatConverterStream, QueueStream< T >, QueueStream< uint8_t >, DynamicMemoryStream, and Pipeline.

clearNotifyAudioChange()

virtual void clearNotifyAudioChange ( )

inlinevirtualinherited

Deletes all change notify subscriptions.

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

end()

virtual void end ( )

inlinevirtualinherited

Reimplemented in FaustStream< DSP >, I2SCodecStream, VS1053Stream, WM8960Stream, AdaptiveResamplingStream, ESPNowStream, I2SStream, TimerCallbackAudioStream, GoertzelStream, AudioFFTBase, AudioKitStream, HLSStreamT< URLStream >, HttpRequest, ICYStreamT< T >, AnalogAudioStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, InputMixer< T >, InputMerge< T >, QueueStream< T >, QueueStream< uint8_t >, and Pipeline.

flush()

virtual void flush ( )

inlineoverridevirtualinherited

Reimplemented from Print.

Reimplemented in ResampleStream, BufferedTaskStream, and BufferedStream.

operator bool()

virtual operator bool ( )

inlinevirtualinherited

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

readBytes()

virtual size_t readBytes ( uint8_t *  data, size_t  len  )

inlineoverridevirtualinherited

Implements BaseStream.

Reimplemented in LMSEchoCancellationStream< T >, MDFEchoCancellationStream< Allocator >, MozziStream, FaustStream< DSP >, AudioFFTBase, AudioKitStream, I2SCodecStream, TfLiteAudioStream, A2DPStream, AdaptiveResamplingStream, HLSStreamT< URLStream >, ICYStreamT< T >, BufferedTaskStream, AnalogAudioArduino, AudioEffectStreamT< T >, Equalizer3Bands, Equalizer3BandsPerChannel, I2SStream, TimedStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, BufferedStream, MeasuringStream, ProgressStream, InputMixer< T >, InputMerge< T >, AudioInputMonitor, FrequencyDetectorAutoCorrelation, FrequencyDetectorZeroCrossing, GoertzelStream, VolumeStream, and AnalogDriverESP32V2::IO16Bit.

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

write() [1/2]

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

inlineoverridevirtualinherited

Implements BaseStream.

Reimplemented in LMSEchoCancellationStream< T >, MDFEchoCancellationStream< Allocator >, I2SCodecStream, MozziStream, SPDIFOutput, I2SStream, FaustStream< DSP >, AudioFFTBase, TfLiteAudioStream, VS1053Stream, A2DPStream, AdaptiveResamplingStream, BufferedTaskStream, AnalogAudioStream, AudioEffectStreamT< T >, Equalizer3Bands, Equalizer3BandsPerChannel, TimedStream, BufferedStream, MeasuringStream, ProgressStream, AudioInputMonitor, FrequencyDetectorAutoCorrelation, FrequencyDetectorZeroCrossing, GoertzelStream, ResampleStreamT< TInterpolator >, VolumeStream, TfLiteAudioStreamBase, and AnalogDriverESP32V2::IO16Bit.

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/STT/MDFEchoCancellation.h