Real-time FFT spectrum analyser with per-bin smoothing and peak hold. More...

#include <SpectrumAnalyzer.h>

Public Types
enum class	WindowType { Hann , Hamming , Blackman , BlackmanHarris , FlatTop , Rectangular }
	Available window types for the FFT analysis. More...

Public Member Functions
void	prepare (double sampleRate, int fftSize=2048, WindowType windowType=WindowType::Hann)
	Prepares the analyser and allocates all necessary buffers.

void	reset () noexcept
	Resets all internal buffers and state to zero/floor values.

void	setSmoothing (T factor) noexcept
	Sets the per-frame magnitude smoothing factor.

void	setPeakDecay (T decayDbPerSecond) noexcept
	Sets the peak-hold decay rate.

void	setPeakHoldEnabled (bool enabled) noexcept
	Enables or disables peak-hold tracking.

void	setFloorDb (T floorDb) noexcept
	Sets the readout floor in decibels.

T	getSmoothing () const noexcept
	Returns the per-frame magnitude smoothing factor.

T	getPeakDecay () const noexcept
	Returns the peak-hold decay rate in dB per second.

bool	isPeakHoldEnabled () const noexcept
	Returns true if peak-hold tracking is enabled.

T	getFloorDb () const noexcept
	Returns the readout floor in decibels.

WindowType	getWindowType () const noexcept
	Returns the window type in use (set at prepare time).

void	pushSamples (const T *samples, int numSamples) noexcept
	Pushes audio samples into the analyser's internal ring buffer.

const T *	getMagnitudesDb () const noexcept
	Returns the current magnitude spectrum in decibels.

const T *	getPeakHoldDb () const noexcept
	Returns the peak-hold spectrum in decibels.

bool	isNewDataReady () noexcept
	Consumes and returns the new data flag. True if updated since last call.

int	getNumBins () const noexcept
	Number of spectrum bins (fftSize/2 + 1); 0 before prepare().

int	getFFTSize () const noexcept
	FFT size in samples; 0 before prepare().

T	binToFrequency (int bin) const noexcept
	Centre frequency of the given bin in Hz (0 before prepare()).

Detailed Description

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

Real-time FFT spectrum analyser with per-bin smoothing and peak hold.

The magnitude smoothing is a per-frame exponential (one analysis frame per hop = fftSize/2 samples), so its settling TIME depends on fftSize and the sample rate: frameRate = 2 * sampleRate / fftSize. The peak-hold decay is specified in dB/second and is rate-invariant.

Template Parameters

T	Sample type (float or double).

Definition at line 75 of file SpectrumAnalyzer.h.

Member Enumeration Documentation

◆ WindowType

template<FloatType T>

enum class dspark::SpectrumAnalyzer::WindowType

strong

Available window types for the FFT analysis.

Enumerator
Hann	Default. Good general-purpose choice.
Hamming	Slightly better side lobe rejection.
Blackman	High dynamic range.
BlackmanHarris	Highest side lobe rejection.
FlatTop	Amplitude-accurate measurement.
Rectangular	No windowing (transient analysis).

Definition at line 79 of file SpectrumAnalyzer.h.

Member Function Documentation

◆ binToFrequency()

template<FloatType T>

T dspark::SpectrumAnalyzer< T >::binToFrequency ( int bin ) const

inlinenoexcept

Centre frequency of the given bin in Hz (0 before prepare()).

Definition at line 293 of file SpectrumAnalyzer.h.

◆ getFFTSize()

template<FloatType T>

int dspark::SpectrumAnalyzer< T >::getFFTSize ( ) const

inlinenoexcept

FFT size in samples; 0 before prepare().

Definition at line 290 of file SpectrumAnalyzer.h.

◆ getFloorDb()

template<FloatType T>

T dspark::SpectrumAnalyzer< T >::getFloorDb ( ) const

inlinenoexcept

Returns the readout floor in decibels.

Definition at line 228 of file SpectrumAnalyzer.h.

◆ getMagnitudesDb()

template<FloatType T>

const T * dspark::SpectrumAnalyzer< T >::getMagnitudesDb ( ) const

inlinenoexcept

Returns the current magnitude spectrum in decibels.

Returns: Pointer to an array of size getNumBins() (0 before prepare()).

Definition at line 264 of file SpectrumAnalyzer.h.

◆ getNumBins()

template<FloatType T>

int dspark::SpectrumAnalyzer< T >::getNumBins ( ) const

inlinenoexcept

Number of spectrum bins (fftSize/2 + 1); 0 before prepare().

Definition at line 287 of file SpectrumAnalyzer.h.

◆ getPeakDecay()

template<FloatType T>

T dspark::SpectrumAnalyzer< T >::getPeakDecay ( ) const

inlinenoexcept

Returns the peak-hold decay rate in dB per second.

Definition at line 222 of file SpectrumAnalyzer.h.

◆ getPeakHoldDb()

template<FloatType T>

const T * dspark::SpectrumAnalyzer< T >::getPeakHoldDb ( ) const

inlinenoexcept

Returns the peak-hold spectrum in decibels.

Returns: Pointer to an array of size getNumBins() (0 before prepare()).

Definition at line 274 of file SpectrumAnalyzer.h.

◆ getSmoothing()

template<FloatType T>

T dspark::SpectrumAnalyzer< T >::getSmoothing ( ) const

inlinenoexcept

Returns the per-frame magnitude smoothing factor.

Definition at line 219 of file SpectrumAnalyzer.h.

◆ getWindowType()

template<FloatType T>

WindowType dspark::SpectrumAnalyzer< T >::getWindowType ( ) const

inlinenoexcept

Returns the window type in use (set at prepare time).

Definition at line 231 of file SpectrumAnalyzer.h.

◆ isNewDataReady()

template<FloatType T>

bool dspark::SpectrumAnalyzer< T >::isNewDataReady ( )

inlinenoexcept

Consumes and returns the new data flag. True if updated since last call.

Definition at line 281 of file SpectrumAnalyzer.h.

◆ isPeakHoldEnabled()

template<FloatType T>

bool dspark::SpectrumAnalyzer< T >::isPeakHoldEnabled ( ) const

inlinenoexcept

Returns true if peak-hold tracking is enabled.

Definition at line 225 of file SpectrumAnalyzer.h.

◆ prepare()

template<FloatType T>

void dspark::SpectrumAnalyzer< T >::prepare	(	double	sampleRate,
		int	fftSize = `2048`,
		WindowType	windowType = `WindowType::Hann`
	)

inline

Prepares the analyser and allocates all necessary buffers.

Release-safe: a non-finite or non-positive sample rate is ignored (conservative no-op); fftSize is clamped to [256, 16384] and rounded UP to the next power of two; an out-of-range window enum falls back to Hann. May allocate (setup thread only). If an allocation throws, the analyser is left unprepared (pushSamples becomes a no-op) rather than half-configured.

Parameters

sampleRate	Sample rate in Hz.
fftSize	FFT size (power of two, 256 to 16384).
windowType	Window function to use (default: Hann).

Definition at line 103 of file SpectrumAnalyzer.h.

◆ pushSamples()

template<FloatType T>

void dspark::SpectrumAnalyzer< T >::pushSamples	(	const T *	samples,
		int	numSamples
	)

inlinenoexcept

Pushes audio samples into the analyser's internal ring buffer.

Computes the FFT synchronously when the internal hop size (50% overlap) is met. No-op before prepare() or with a null/empty input.

Parameters

samples	Pointer to the continuous audio data.
numSamples	Number of samples to process.

Definition at line 242 of file SpectrumAnalyzer.h.

◆ reset()

template<FloatType T>

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

inlinenoexcept

Resets all internal buffers and state to zero/floor values.

Definition at line 160 of file SpectrumAnalyzer.h.

◆ setFloorDb()

template<FloatType T>

void dspark::SpectrumAnalyzer< T >::setFloorDb ( T floorDb )

inlinenoexcept

Sets the readout floor in decibels.

Parameters

floorDb Values below this floor are clamped to it (non-finite values are ignored).

Definition at line 212 of file SpectrumAnalyzer.h.

◆ setPeakDecay()

template<FloatType T>

void dspark::SpectrumAnalyzer< T >::setPeakDecay ( T decayDbPerSecond )

inlinenoexcept

Sets the peak-hold decay rate.

Parameters

decayDbPerSecond Decay in dB per second (floored at 0; non-finite values are ignored).

Definition at line 195 of file SpectrumAnalyzer.h.

◆ setPeakHoldEnabled()

template<FloatType T>

void dspark::SpectrumAnalyzer< T >::setPeakHoldEnabled ( bool enabled )

inlinenoexcept

Enables or disables peak-hold tracking.

Definition at line 202 of file SpectrumAnalyzer.h.

◆ setSmoothing()

template<FloatType T>

void dspark::SpectrumAnalyzer< T >::setSmoothing ( T factor )

inlinenoexcept

Sets the per-frame magnitude smoothing factor.

Parameters

factor 0 = no smoothing, 0.99 = heaviest. Applied once per analysis frame (hop), so the settling time scales with fftSize / sampleRate. Non-finite values are ignored.

Definition at line 184 of file SpectrumAnalyzer.h.

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

Analysis/SpectrumAnalyzer.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ WindowType

Member Function Documentation

◆ binToFrequency()

◆ getFFTSize()

◆ getFloorDb()

◆ getMagnitudesDb()

◆ getNumBins()

◆ getPeakDecay()

◆ getPeakHoldDb()

◆ getSmoothing()

◆ getWindowType()

◆ isNewDataReady()

◆ isPeakHoldEnabled()

◆ prepare()

◆ pushSamples()

◆ reset()

◆ setFloorDb()

◆ setPeakDecay()

◆ setPeakHoldEnabled()

◆ setSmoothing()