Causal SuperFlux onset detector with lock-free readout. More...

#include <OnsetDetector.h>

Public Types
enum class	Method { SpectralFlux , ComplexDomain , SuperFlux }
	Onset-detection function family. Default SuperFlux. More...

Public Member Functions
void	prepare (const AudioSpec &spec, int fftSize=2048, int hop=0)
	Allocates all state and configures the STFT front-end.

void	setMethod (Method m) noexcept
	Selects the ODF family. Lock-free.

void	setThreshold (T deltaAboveMean) noexcept
	Sets the adaptive peak-pick delta (margin above the moving mean). Non-finite values are ignored; negative values are clamped to 0.

void	setAdaptiveWhitening (bool on) noexcept
	Enables Stowell-Plumbley adaptive whitening (default off).

void	processBlock (AudioBufferView< const T > in) noexcept
	Feeds a mono block; reads channel 0 only. Const, never mutated.

void	pushSamples (std::span< const T > samples) noexcept
	Feeds a mono stream of samples. Lock-free, allocation-free.

bool	onsetDetected () const noexcept
	True if an onset was reported during the most recent call.

T	getOnsetStrength () const noexcept
	Onset strength (ODF value) of the most recent reported onset.

int64_t	getLastOnsetSample () const noexcept
	Reference sample index (frame centre) of the most recent onset. The latch fires exactly getLatencySamples() samples after this index.

int	getLatencySamples () const noexcept
	The single causal reporting latency, L = fftSize + hop (samples).

int	getFftSize () const noexcept

int	getHopSize () const noexcept

int	getNumBands () const noexcept

std::vector< int64_t >	detectOffline (AudioBufferView< const T > whole)
	Offline detection over a whole mono buffer (channel 0).

void	reset () noexcept
	Clears all streaming state. Not concurrent with pushSamples().

Detailed Description

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

Causal SuperFlux onset detector with lock-free readout.

Role: analysis readout. It consumes const audio (AudioBufferView<const T> or a raw span) and never mutates it. All heap use happens in prepare(); the audio path (processBlock/pushSamples) allocates nothing, takes no lock and throws nothing.

Template Parameters

T	Sample type (float or double).

Definition at line 94 of file OnsetDetector.h.

Member Enumeration Documentation

◆ Method

template<FloatType T>

enum class dspark::OnsetDetector::Method

strong

Onset-detection function family. Default SuperFlux.

Enumerator
SpectralFlux
ComplexDomain
SuperFlux

Definition at line 98 of file OnsetDetector.h.

Member Function Documentation

◆ detectOffline()

template<FloatType T>

std::vector< int64_t > dspark::OnsetDetector< T >::detectOffline ( AudioBufferView< const T > whole )

inline

Offline detection over a whole mono buffer (channel 0).

Runs the same ODF with the symmetric (post_max/post_avg > 0) picker for slightly higher F, and returns onset sample positions (frame-centre references, ascending). Allocates – not an audio-thread call. Resets the streaming state on entry.

Definition at line 332 of file OnsetDetector.h.

◆ getFftSize()

template<FloatType T>

int dspark::OnsetDetector< T >::getFftSize ( ) const

inlinenoexcept

Definition at line 318 of file OnsetDetector.h.

◆ getHopSize()

template<FloatType T>

int dspark::OnsetDetector< T >::getHopSize ( ) const

inlinenoexcept

Definition at line 319 of file OnsetDetector.h.

◆ getLastOnsetSample()

template<FloatType T>

int64_t dspark::OnsetDetector< T >::getLastOnsetSample ( ) const

inlinenoexcept

Reference sample index (frame centre) of the most recent onset. The latch fires exactly getLatencySamples() samples after this index.

Definition at line 307 of file OnsetDetector.h.

◆ getLatencySamples()

template<FloatType T>

int dspark::OnsetDetector< T >::getLatencySamples ( ) const

inlinenoexcept

The single causal reporting latency, L = fftSize + hop (samples).

Definition at line 313 of file OnsetDetector.h.

◆ getNumBands()

template<FloatType T>

int dspark::OnsetDetector< T >::getNumBands ( ) const

inlinenoexcept

Definition at line 320 of file OnsetDetector.h.

◆ getOnsetStrength()

template<FloatType T>

T dspark::OnsetDetector< T >::getOnsetStrength ( ) const

inlinenoexcept

Onset strength (ODF value) of the most recent reported onset.

Definition at line 298 of file OnsetDetector.h.

◆ onsetDetected()

template<FloatType T>

bool dspark::OnsetDetector< T >::onsetDetected ( ) const

inlinenoexcept

True if an onset was reported during the most recent call.

Definition at line 292 of file OnsetDetector.h.

◆ prepare()

template<FloatType T>

void dspark::OnsetDetector< T >::prepare	(	const AudioSpec &	spec,
		int	fftSize = `2048`,
		int	hop = `0`
	)

inline

Allocates all state and configures the STFT front-end.

Not real-time safe (allocates). Any previous stream state is cleared. An invalid spec (non-finite or non-positive sample rate) is ignored, preserving the previous configuration.

Parameters

spec	Audio environment (only sampleRate is used; the detector is mono – feed channel 0, or mix down before pushing).
fftSize	Analysis frame size; rounded up to a power of two in [64, 1<<16]. Default 2048.
hop	Hop in samples; hop <= 0 selects round(fs/200) (~5 ms). Clamped to [1, fftSize].

Definition at line 116 of file OnsetDetector.h.

◆ processBlock()

template<FloatType T>

void dspark::OnsetDetector< T >::processBlock ( AudioBufferView< const T > in )

inlinenoexcept

Feeds a mono block; reads channel 0 only. Const, never mutated.

Lock-free and allocation-free. Safe no-op before prepare().

Definition at line 234 of file OnsetDetector.h.

◆ pushSamples()

template<FloatType T>

void dspark::OnsetDetector< T >::pushSamples ( std::span< const T > samples )

inlinenoexcept

Feeds a mono stream of samples. Lock-free, allocation-free.

Onsets fire at the fixed reporting latency L = fftSize + hop after their reference sample; onsetDetected() latches per processing call (see the file header). Safe no-op before prepare().

Definition at line 248 of file OnsetDetector.h.

◆ reset()

template<FloatType T>

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

inlinenoexcept

Clears all streaming state. Not concurrent with pushSamples().

Definition at line 402 of file OnsetDetector.h.

◆ setAdaptiveWhitening()

template<FloatType T>

void dspark::OnsetDetector< T >::setAdaptiveWhitening ( bool on )

inlinenoexcept

Enables Stowell-Plumbley adaptive whitening (default off).

Definition at line 222 of file OnsetDetector.h.

◆ setMethod()

template<FloatType T>

void dspark::OnsetDetector< T >::setMethod ( Method m )

inlinenoexcept

Selects the ODF family. Lock-free.

Definition at line 209 of file OnsetDetector.h.

◆ setThreshold()

template<FloatType T>

void dspark::OnsetDetector< T >::setThreshold ( T deltaAboveMean )

inlinenoexcept

Sets the adaptive peak-pick delta (margin above the moving mean). Non-finite values are ignored; negative values are clamped to 0.

Definition at line 215 of file OnsetDetector.h.

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

Analysis/OnsetDetector.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Method

Member Function Documentation

◆ detectOffline()

◆ getFftSize()

◆ getHopSize()

◆ getLastOnsetSample()

◆ getLatencySamples()

◆ getNumBands()

◆ getOnsetStrength()

◆ onsetDetected()

◆ prepare()

◆ processBlock()

◆ pushSamples()

◆ reset()

◆ setAdaptiveWhitening()

◆ setMethod()

◆ setThreshold()