Single-frequency magnitude detector using the Goertzel algorithm. More...

#include <Goertzel.h>

Public Member Functions
void	prepare (double sampleRate, double targetFreqHz, int blockSize) noexcept
	Prepares the detector for a specific frequency.

void	processBlock (const T *data, int numSamples) noexcept
	Processes a block of audio samples, updating the internal state.

bool	pushSample (T sample) noexcept
	Feeds a single sample into the running Goertzel computation.

void	forceCompute () noexcept
	Manually forces the computation of the result before N samples are reached.

bool	checkNewResultAvailable () noexcept
	Checks if a new result has been computed.

T	getMagnitude () const noexcept
	Returns the magnitude at the target frequency (linear scale).

T	getPower () const noexcept
	Returns the power at the target frequency.

T	getMagnitudeDb () const noexcept
	Returns the magnitude in decibels.

T	getPhase () const noexcept
	Returns the phase angle at the target frequency.

double	getTargetFrequency () const noexcept
	Returns the currently configured target frequency.

double	getSampleRate () const noexcept
	Returns the configured sample rate in Hz.

int	getBlockSize () const noexcept
	Returns the configured analysis block size in samples.

void	reset () noexcept
	Resets the internal IIR state and counters to zero.

Detailed Description

template<FloatType T>
class dspark::Goertzel< T >

Single-frequency magnitude detector using the Goertzel algorithm.

Designed for continuous streaming or block-based real-time analysis. State is unified: you can mix processBlock and pushSample safely. Before prepare() the detector is inert and reports zero magnitude.

Template Parameters

T	Sample type (float or double). Requires dspark::FloatType concept.

Definition at line 63 of file Goertzel.h.

Member Function Documentation

◆ checkNewResultAvailable()

template<FloatType T>

bool dspark::Goertzel< T >::checkNewResultAvailable ( )

inlinenoexcept

Checks if a new result has been computed.

Calling this will return true only once after an analysis block completes, resetting the flag internally.

Returns: True if new data is available.

Definition at line 207 of file Goertzel.h.

◆ forceCompute()

template<FloatType T>

void dspark::Goertzel< T >::forceCompute ( )

inlinenoexcept

Manually forces the computation of the result before N samples are reached.

Warning: Evaluating before reaching the configured blockSize will result in inaccurate magnitude and phase due to incomplete integration and incorrect scaling.

Definition at line 189 of file Goertzel.h.

◆ getBlockSize()

template<FloatType T>

int dspark::Goertzel< T >::getBlockSize ( ) const

inlinenoexcept

Returns the configured analysis block size in samples.

Definition at line 269 of file Goertzel.h.

◆ getMagnitude()

template<FloatType T>

T dspark::Goertzel< T >::getMagnitude ( ) const

inlinenoexcept

Returns the magnitude at the target frequency (linear scale).

Returns: Magnitude (Amplitude of the detected frequency).

Definition at line 221 of file Goertzel.h.

◆ getMagnitudeDb()

template<FloatType T>

T dspark::Goertzel< T >::getMagnitudeDb ( ) const

inlinenoexcept

Returns the magnitude in decibels.

Returns: Magnitude in dB, floored at -100 dB for zero/silence (dspark::gainToDecibels floor).

Definition at line 240 of file Goertzel.h.

◆ getPhase()

template<FloatType T>

T dspark::Goertzel< T >::getPhase ( ) const

inlinenoexcept

Returns the phase angle at the target frequency.

The phase is referenced to the analysis block boundary: it is reproducible between blocks when the target frequency is an exact multiple of sampleRate/blockSize (bin-exact tones).

Returns: Phase in radians in the range [-pi, pi].

Definition at line 254 of file Goertzel.h.

◆ getPower()

template<FloatType T>

T dspark::Goertzel< T >::getPower ( ) const

inlinenoexcept

Returns the power at the target frequency.

Returns: Power (Magnitude squared).

Definition at line 230 of file Goertzel.h.

◆ getSampleRate()

template<FloatType T>

double dspark::Goertzel< T >::getSampleRate ( ) const

inlinenoexcept

Returns the configured sample rate in Hz.

Definition at line 266 of file Goertzel.h.

◆ getTargetFrequency()

template<FloatType T>

double dspark::Goertzel< T >::getTargetFrequency ( ) const

inlinenoexcept

Returns the currently configured target frequency.

Returns: Frequency in Hz.

Definition at line 263 of file Goertzel.h.

◆ prepare()

template<FloatType T>

void dspark::Goertzel< T >::prepare	(	double	sampleRate,
		double	targetFreqHz,
		int	blockSize
	)

inlinenoexcept

Prepares the detector for a specific frequency.

Release-safe: a non-finite or non-positive sample rate, a non-finite target frequency or a non-positive block size are ignored (no-op keeping the previous configuration); the target frequency is clamped to [0, sampleRate/2].

Parameters

sampleRate	Sample rate in Hz. Must be > 0.
targetFreqHz	The frequency to detect, in [0, sampleRate/2].
blockSize	Number of samples per analysis window. Must be > 0. There is deliberately no default: the useful quantity is the bin width fs/blockSize, so the count that meets a requirement at one sample rate does not meet it at another (see the selectivity note in the file header). With float precision, very long windows (hundreds of thousands of samples) accumulate rounding error in the resonator; prefer double for extreme block sizes. At exact DC and Nyquist the recursion sits on a double pole and its state grows O(N^2), so float precision degrades much sooner there: use double (or a short window) when measuring those two edge frequencies.

Definition at line 89 of file Goertzel.h.

◆ processBlock()

template<FloatType T>

void dspark::Goertzel< T >::processBlock	(	const T *	data,
		int	numSamples
	)

inlinenoexcept

Processes a block of audio samples, updating the internal state.

This method accumulates samples. To know if a full analysis block has been completed, check checkNewResultAvailable() after processing.

Parameters

data	Pointer to the audio samples.
numSamples	Number of samples in the buffer.

Definition at line 131 of file Goertzel.h.

◆ pushSample()

template<FloatType T>

bool dspark::Goertzel< T >::pushSample ( T sample )

inlinenoexcept

Feeds a single sample into the running Goertzel computation.

Parameters

sample Input audio sample.

Returns: True if a new magnitude calculation was just completed (N samples reached).

Definition at line 166 of file Goertzel.h.

◆ reset()

template<FloatType T>

void dspark::Goertzel< T >::reset ( )

inlinenoexcept

Resets the internal IIR state and counters to zero.

Retains configured sample rate, frequency, and block size.

Definition at line 276 of file Goertzel.h.

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

Goertzel.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ checkNewResultAvailable()

◆ forceCompute()

◆ getBlockSize()

◆ getMagnitude()

◆ getMagnitudeDb()

◆ getPhase()

◆ getPower()

◆ getSampleRate()

◆ getTargetFrequency()

◆ prepare()

◆ processBlock()

◆ pushSample()

◆ reset()