Trait AudioOnsetDetection 

pub trait AudioOnsetDetection: AudioTransforms
where
    Self::Sample: StandardSample,
{
    // Required methods
    fn detect_onsets(
        &self,
        config: &OnsetDetectionConfig,
    ) -> AudioSampleResult<Vec<f64>>;
    fn onset_detection_function(
        &self,
        config: &OnsetDetectionConfig,
    ) -> AudioSampleResult<(NonEmptyVec<f64>, NonEmptyVec<f64>)>;
    fn detect_onsets_spectral_flux(
        &self,
        config: &SpectralFluxConfig,
    ) -> AudioSampleResult<Vec<f64>>;
    fn spectral_flux(
        &self,
        config: &CqtParams,
        window_size: NonZeroUsize,
        hop_size: NonZeroUsize,
        method: SpectralFluxMethod,
    ) -> AudioSampleResult<(NonEmptyVec<f64>, NonEmptyVec<f64>)>;
    fn complex_onset_detection(
        &self,
        onset_config: &ComplexOnsetConfig,
    ) -> AudioSampleResult<Vec<f64>>;
    fn onset_detection_function_complex(
        &self,
        onset_config: &ComplexOnsetConfig,
    ) -> AudioSampleResult<NonEmptyVec<f64>>;
    fn magnitude_difference_matrix(
        &self,
        config: &ComplexOnsetConfig,
    ) -> AudioSampleResult<Array2<f64>>;
    fn phase_deviation_matrix(
        &self,
        config: &ComplexOnsetConfig,
    ) -> AudioSampleResult<Array2<f64>>;
}

Onset detection and spectral analysis operations.

Purpose

Locates the moments where a new musical event begins — note attacks, drum hits, chord changes — and exposes the intermediate spectral representations that drive the detection.

Intended Usage

Use detect_onsets or detect_onsets_spectral_flux when you need a list of onset timestamps. Use onset_detection_function or spectral_flux when you need the raw activation curve for downstream analysis (e.g. beat induction or custom peak-picking). complex_onset_detection and its helpers provide a phase-sensitive alternative useful for polyphonic or sustained content.

Invariants

All returned time vectors are sorted in ascending order and expressed in seconds relative to the start of the signal. The detection-function and timestamp vectors returned by tuple methods always have the same length.

Required Methods

fn detect_onsets( &self, config: &OnsetDetectionConfig, ) -> AudioSampleResult<Vec<f64>>

Detects onset times in the audio signal using spectral flux.

Computes an onset detection function from the signal and applies peak-picking to find the frames where new events begin. The exact pipeline is controlled by config.

Arguments

• config – Onset detection parameters: STFT settings, flux method, peak-picking thresholds, and minimum inter-onset interval.

Returns

A Vec<f64> of onset times in seconds, sorted ascending. Returns an empty Vec if no onsets are found.

Errors

Returns crate::AudioSampleError::Parameter if config fields are invalid. Returns crate::AudioSampleError::Processing if the STFT computation fails.

fn onset_detection_function( &self, config: &OnsetDetectionConfig, ) -> AudioSampleResult<(NonEmptyVec<f64>, NonEmptyVec<f64>)>

Computes the onset detection function and its time axis.

Returns the raw activation curve before peak-picking, together with the corresponding frame timestamps. Useful when you want to inspect the ODF, apply custom thresholding, or feed it into a beat tracker.

Arguments

• config – Onset detection parameters controlling the spectral analysis and flux computation.

Returns

A (odf_values, timestamps) tuple:

• odf_values – One activation value per analysis frame.
• timestamps – Corresponding frame centre times in seconds. Both vectors have the same length.

Errors

Returns crate::AudioSampleError::Parameter if config fields are invalid. Returns crate::AudioSampleError::Processing if the STFT computation fails.

fn detect_onsets_spectral_flux( &self, config: &SpectralFluxConfig, ) -> AudioSampleResult<Vec<f64>>

Detects onset times using the spectral-flux method.

An alternative entry point that accepts a SpectralFluxConfig directly, exposing finer control over the CQT analysis and flux accumulation than the higher-level detect_onsets.

Arguments

• config – Spectral flux parameters: CQT settings, flux method, and peak-picking thresholds.

Returns

A Vec<f64> of onset times in seconds, sorted ascending.

Errors

Returns crate::AudioSampleError::Parameter if config fields are invalid. Returns crate::AudioSampleError::Processing if the CQT computation fails.

fn spectral_flux( &self, config: &CqtParams, window_size: NonZeroUsize, hop_size: NonZeroUsize, method: SpectralFluxMethod, ) -> AudioSampleResult<(NonEmptyVec<f64>, NonEmptyVec<f64>)>

Computes the spectral flux curve and its time axis.

Returns the per-frame positive spectral change using the specified CQT parameters and flux method, together with the corresponding timestamps. The raw flux curve can be used as an onset strength signal for beat tracking or visualisation.

Arguments

• config – CQT analysis parameters (bins per octave, frequency range, etc.).
• window_size – Analysis window length in samples.
• hop_size – Number of samples to advance between successive windows.
• method – Spectral flux variant to compute (e.g. positive flux, complex flux, or Wiener entropy).

Returns

A (flux_values, timestamps) tuple, both of equal length.

Errors

Returns crate::AudioSampleError::Parameter if window_size or hop_size are inconsistent with the signal length. Returns crate::AudioSampleError::Processing if the CQT computation fails.

fn complex_onset_detection( &self, onset_config: &ComplexOnsetConfig, ) -> AudioSampleResult<Vec<f64>>

Detects onset times using the complex-domain onset detection function.

Combines magnitude difference and phase deviation into a single activation curve that is sensitive to both amplitude changes and phase discontinuities. This makes it more robust than spectral-flux alone for sustained or polyphonic content.

Arguments

• onset_config – Complex onset detection parameters: STFT settings and peak-picking thresholds.

Returns

A Vec<f64> of onset times in seconds, sorted ascending.

Errors

Returns crate::AudioSampleError::Parameter if onset_config fields are invalid. Returns crate::AudioSampleError::Processing if the STFT computation fails.

fn onset_detection_function_complex( &self, onset_config: &ComplexOnsetConfig, ) -> AudioSampleResult<NonEmptyVec<f64>>

Computes the complex-domain onset detection function curve.

Returns the raw per-frame activation values before peak-picking. Each value combines the magnitude difference and unwrapped phase deviation for that frame.

Arguments

• onset_config – Complex onset detection parameters.

Returns

A NonEmptyVec<f64> with one value per analysis frame, in chronological order.

Errors

Returns crate::AudioSampleError::Parameter if onset_config is invalid. Returns crate::AudioSampleError::Processing if the STFT computation fails.

fn magnitude_difference_matrix( &self, config: &ComplexOnsetConfig, ) -> AudioSampleResult<Array2<f64>>

Computes the frame-by-frame magnitude difference matrix.

Each entry [i, j] is the absolute difference in spectral magnitude between consecutive STFT frames at frequency bin j and frame i. This is an intermediate building block of the complex ODF.

Arguments

• config – Complex onset detection parameters controlling the STFT analysis window.

Returns

An Array2<f64> with shape [frames, frequency_bins].

Errors

Returns crate::AudioSampleError::Processing if the STFT computation fails.

fn phase_deviation_matrix( &self, config: &ComplexOnsetConfig, ) -> AudioSampleResult<Array2<f64>>

Computes the frame-by-frame phase deviation matrix.

Each entry [i, j] is the second-order phase difference (phase deviation from a constant-frequency prediction) at frequency bin j and frame i. This is an intermediate building block of the complex ODF.

Arguments

• config – Complex onset detection parameters controlling the STFT analysis window.

Returns

An Array2<f64> with shape [frames, frequency_bins].

Errors

Returns crate::AudioSampleError::Processing if the STFT computation fails.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<T> AudioOnsetDetection for AudioSamples<'_, T>

where T: StandardSample, Self: AudioTypeConversion<Sample = T>,