AudioStream-based multi-frequency Goertzel detector for real-time audio analysis. More...

#include <GoerzelStream.h>

Inheritance diagram for GoertzelStream:

Public Member Functions
	GoertzelStream (AudioOutput &out)

	GoertzelStream (AudioStream &io)

	GoertzelStream (Print &out)

	GoertzelStream (Stream &io)

void	addFrequency (float freq)
	Add a frequency to the detection list.

void	addFrequency (float freq, void *ref)
	Add a frequency to the detection list with a custom reference pointer.

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 ()
	Initialize detectors for all frequencies.

bool	begin (GoertzelConfig config)
	Initialize with GoertzelConfig.

virtual void	clearNotifyAudioChange ()
	Deletes all change notify subscriptions.

GoertzelConfig	defaultConfig ()
	Returns a default GoertzelConfig instance with standard parameters.

void	end ()
	Stop the Goertzel detectors and clear resources.

virtual void	flush () override

const GoertzelConfig &	getConfig () const
	Get the current configuration.

GoertzelDetector &	getDetector (int no)
	Get detector for specific channel.

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

virtual	operator bool ()

size_t	readBytes (uint8_t *data, size_t len) override
	Read data from input stream and process it.

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	setAudioInfo (AudioInfo info) override
	Set audio format and initialize detector array.

void	setFrequencyDetectionCallback (void(callback)(float frequency, float magnitude, void ref))
	Set detection callback function for channel-aware frequency detection.

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

void	setOutput (AudioOutput &out)
	Defines/Changes the output target.

void	setOutput (Print &out)
	Defines/Changes the output target.

void	setReference (void *ref)
	Set reference pointer for callback context.

void	setStream (AudioStream &io)
	Defines/Changes the input & output.

void	setStream (Stream &in)
	Defines/Changes the input & output.

void	setWriteBufferSize (int size)

size_t	write (const uint8_t *data, size_t len) override
	Process audio data and pass it through.

virtual size_t	write (uint8_t ch) override

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

Protected Member Functions
void	checkDetection (GoertzelDetector &detector)
	Check if a detector has detected its frequency and invoke callback.

float	clip (float value)
	Clip audio values to prevent overflow.

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

void	notifyAudioChange (AudioInfo info)

void	processSamples (const uint8_t *data, size_t data_len)
	Generic sample processing method for both write and readBytes.

template<typename T >
void	processSamplesOfType (const uint8_t *data, size_t data_len, int channels)
	Template helper to process samples of a specific type.

void	refillReadBuffer ()

Protected Attributes
int	_timeout = 10

GoertzelConfig	default_config
	Current algorithm configuration.

Vector< GoertzelDetector >	detectors
	One detector per frequency in frequencies.

Vector< float >	frequencies
	List of frequencies to detect.

void(*	frequency_detection_callback )(float frequency, float magnitude, void *ref)
	User callback for detection events.

AudioInfo	info

bool	is_notify_active = true

Vector< AudioInfoSupport * >	notify_vector

Print *	p_print = nullptr
	Output stream for writing audio data.

Stream *	p_stream = nullptr
	Input stream for reading audio data.

void *	ref = this
	User-defined reference for callback context.

Vector< void * >	references
	List of frequencies to detect.

size_t	sample_no = 0
	Sample counter for channel selection.

RingBuffer< uint8_t >	tmp_in {0}

RingBuffer< uint8_t >	tmp_out {0}

int	write_buffer_size = MAX_SINGLE_CHARS

Detailed Description

AudioStream-based multi-frequency Goertzel detector for real-time audio analysis.

GoertzelStream enables efficient detection of one or more target frequencies in a continuous audio stream. It acts as a transparent filter: audio data flows through unchanged, while the class analyzes the signal for specified tones.

Key Features:

Detects multiple frequencies simultaneously (DTMF, tone detection, etc.)
Supports runtime addition of frequencies via addFrequency()
Works with various sample formats: 8/16/24/32-bit (see below)
Channel-aware: can analyze a specific channel in multi-channel audio
Callback system: notifies user when a frequency is detected above threshold
Non-intrusive: does not modify or block audio data
Configurable detection parameters (block size, threshold, volume, etc.)

Usage:

Configure the stream with GoertzelConfig or AudioInfo (sample rate, channels, etc.)
Add one or more target frequencies using addFrequency()
Optionally set a detection callback with setFrequencyDetectionCallback()
Use write() or readBytes() to process audio data; detection runs automatically

Supported sample formats:

8-bit: unsigned (0-255), internally converted to signed (-128 to 127)
16-bit: signed (-32768 to 32767)
24-bit: signed, packed format
32-bit: signed (-2^31 to 2^31-1)

Author: pschatzmann

Copyright: GPLv3

Member Function Documentation

◆ addFrequency() [1/2]

void addFrequency ( float freq )

inline

Add a frequency to the detection list.

Parameters

freq	Frequency in Hz to add to the detection list

◆ addFrequency() [2/2]

void addFrequency	(	float	freq,
		void *	ref
	)

inline

Add a frequency to the detection list with a custom reference pointer.

This method allows you to associate a user-defined reference (context pointer) with a specific frequency. The reference will be passed to the detection callback when this frequency is detected, enabling per-frequency context handling.

Parameters

freq	Frequency in Hz to add to the detection list
ref	Pointer to user-defined context object for this frequency

◆ 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() [1/2]

bool begin ( )

inlinevirtual

Initialize detectors for all frequencies.

Creates and configures individual Goertzel detectors for frequency. Each detector will independently for the target frequency.

Returns: true if at least one channel is configured, false otherwise

Reimplemented from BaseStream.

◆ begin() [2/2]

bool begin ( GoertzelConfig config )

inline

Initialize with GoertzelConfig.

Sets up the stream with specific Goertzel algorithm parameters. This method configures the audio format and detection parameters in one call.

Parameters

config Configuration object containing all parameters

Returns: true if initialization successful, false otherwise

◆ clearNotifyAudioChange()

virtual void clearNotifyAudioChange ( )

inlinevirtualinherited

Deletes all change notify subscriptions.

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

◆ clip()

float clip ( float value )

inlineprotected

Clip audio values to prevent overflow.

Ensures that normalized audio samples stay within the valid range of [-1.0, 1.0] to prevent algorithm instability.

Parameters

value Input audio sample value

Returns: Clipped value in range [-1.0, 1.0]

◆ defaultConfig()

GoertzelConfig defaultConfig ( )

inline

Returns a default GoertzelConfig instance with standard parameters.

This utility method provides a convenient way to obtain a default configuration for the Goertzel algorithm. The returned config can be customized before use.

Returns: GoertzelConfig with default values

◆ end()

void end ( )

inlinevirtual

Stop the Goertzel detectors and clear resources.

Reimplemented from BaseStream.

◆ flush()

virtual void flush ( )

inlineoverridevirtualinherited

Reimplemented from Print.

Reimplemented in ResampleStream, BufferedTaskStream, and BufferedStream.

◆ getConfig()

const GoertzelConfig & getConfig ( ) const

inline

Get the current configuration.

Returns a reference to the current Goertzel configuration, including audio format, detection parameters, and processing settings.

Returns: Reference to the current GoertzelConfig

◆ getDetector()

GoertzelDetector & getDetector ( int no )

inline

Get detector for specific channel.

Provides access to the GoertzelDetector instance for a given channel. This allows for direct inspection of detector state and results.

Parameters

no	Channel index (0-based)

Returns: Reference to the GoertzelDetector for the specified channel

◆ operator bool()

virtual operator bool ( )

inlinevirtualinherited

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

◆ processSamples()

void processSamples	(	const uint8_t *	data,
		size_t	data_len
	)

inlineprotected

Generic sample processing method for both write and readBytes.

This method serves as the central dispatcher for audio sample processing. It examines the configured sample format and routes the data to the appropriate type-specific processing method. This approach eliminates code duplication between write() and readBytes() methods.

Supported formats:

8-bit: Unsigned samples (0-255)
16-bit: Signed samples (-32768 to 32767)
24-bit: Signed samples in 3-byte packed format
32-bit: Signed samples (-2^31 to 2^31-1)

Parameters

data	Raw audio data buffer
data_len	Length of data buffer in bytes

◆ processSamplesOfType()

template<typename T >

void processSamplesOfType	(	const uint8_t *	data,
		size_t	data_len,
		int	channels
	)

inlineprotected

Template helper to process samples of a specific type.

Converts audio samples from their native format to normalized floats, applies volume scaling, and feeds them to the appropriate channel detectors. This method handles the format conversion and channel distribution automatically.

Template Parameters

T	Sample data type (uint8_t, int16_t, int24_t, int32_t)

Parameters

data	Raw audio data buffer
data_len	Length of data buffer in bytes
channels	Number of audio channels (for sample distribution)

◆ readBytes()

size_t readBytes	(	uint8_t *	data,
		size_t	len
	)

inlineoverridevirtual

Read data from input stream and process it.

Reads audio data from the input stream, processes it through the Goertzel detectors for frequency analysis, and returns the data to the caller. This allows for frequency detection in pull-mode audio processing.

Parameters

data	Output buffer to store read data
len	Maximum number of bytes to read

Returns: Number of bytes actually read

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

void setAudioInfo ( AudioInfo info )

inlineoverridevirtual

Set audio format and initialize detector array.

This method is called when the audio format changes. It updates the internal configuration and resizes the detector array to match the number of audio channels.

Parameters

info	Audio format information (sample rate, channels, bits per sample)

Reimplemented from AudioStream.

◆ setFrequencyDetectionCallback()

void setFrequencyDetectionCallback ( void(*)(float frequency, float magnitude, void *ref) callback )

inline

Set detection callback function for channel-aware frequency detection.

Registers a callback function that will be called when the target frequency is detected on any channel. The callback receives the channel number, detected frequency, magnitude, and a user reference pointer.

Parameters

callback Function to call when frequency is detected, includes channel info

◆ setReference()

void setReference ( void * ref )

inline

Set reference pointer for callback context.

Defines a reference to any object that should be available in the detection callback. This allows the callback to access application context or other objects.

Parameters

ref	Pointer to user-defined context object

◆ write() [1/2]

size_t write	(	const uint8_t *	data,
		size_t	len
	)

inlineoverridevirtual

Process audio data and pass it through.

This method receives audio data, processes it through the Goertzel detectors for frequency analysis, and then passes the unmodified data to the output stream. This allows for real-time frequency detection without affecting the audio flow.

Parameters

data	Input audio data buffer
len	Length of data in bytes

Returns: Number of bytes written to output stream

If there is no output stream, we just return the length

Reimplemented from AudioStream.

◆ write() [2/2]

virtual size_t write ( uint8_t ch )

inlineoverridevirtualinherited

Reimplemented in BufferedTaskStream, and BufferedStream.

Member Data Documentation

◆ frequency_detection_callback

void(* frequency_detection_callback) (float frequency, float magnitude, void *ref)

protected

Initial value:

=

nullptr

User callback for detection events.

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

src/AudioTools/CoreAudio/GoerzelStream.h

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ addFrequency() [1/2]

◆ addFrequency() [2/2]

◆ addNotifyAudioChange()

◆ audioInfo()

◆ audioInfoOut()

◆ available()

◆ availableForWrite()

◆ begin() [1/2]

◆ begin() [2/2]

◆ clearNotifyAudioChange()

◆ clip()

◆ defaultConfig()

◆ end()

◆ flush()

◆ getConfig()

◆ getDetector()

◆ operator bool()

◆ processSamples()

◆ processSamplesOfType()

◆ readBytes()

◆ removeNotifyAudioChange()

◆ setAudioInfo()

◆ setFrequencyDetectionCallback()

◆ setReference()

◆ write() [1/2]

◆ write() [2/2]

Member Data Documentation

◆ frequency_detection_callback