Caution

You're reading the documentation for a development version. For the latest released version, please have a look at 0.10.2.

librosa.onset.onset_detect

librosa.onset.onset_detect(*, y=None, sr=22050, onset_envelope=None, hop_length=512, backtrack=False, energy=None, units='frames', normalize=True, sparse=True, **kwargs)

Locate note onset events by picking peaks in an onset strength envelope.

The peak_pick parameters were chosen by large-scale hyper-parameter optimization over the dataset provided by [1].

[1]

https://github.com/CPJKU/onset_db

Parameters:

ynp.ndarray [shape=(…, n)]

audio time-series. Multi-channel is supported.

srnumber > 0 [scalar]

sampling rate of y

onset_envelopenp.ndarray [shape=(…, m)]

(optional) pre-computed onset strength envelope

hop_lengthint > 0 [scalar]

hop length (in samples)

units{‘frames’, ‘samples’, ‘time’}

The units to encode detected onset events in. By default, ‘frames’ are used.

backtrackbool

If True, detected onset events are backtracked to the nearest preceding minimum of energy.

This is primarily useful when using onsets as slice points for segmentation.

Note

backtracking is only supported if sparse=True.

energynp.ndarray [shape=(m,)] (optional)

An energy function to use for backtracking detected onset events. If none is provided, then onset_envelope is used.

normalizebool

If True (default), normalize the onset envelope to have minimum of 0 and maximum of 1 prior to detection. This is helpful for standardizing the parameters of librosa.util.peak_pick.

Otherwise, the onset envelope is left unnormalized.

sparsebool

If True (default), detections are returned as an array of frames, samples, or time indices (as specified by units=).

If False, detections are encoded as a dense boolean array where onsets[n] is True if there’s an onset at frame index n.

Note

multi-channel input is only supported if sparse=False.

**kwargsadditional keyword arguments

Additional parameters for peak picking.

See librosa.util.peak_pick for details.

Returns:

onsetsnp.ndarray [shape=(n_onsets,) or onset_envelope.shape]

estimated positions of detected onsets, in whichever units are specified. By default, frame indices.

If sparse=False, onsets[…, n] indicates an onset detection at frame index n.

Note

If no onset strength could be detected, onset_detect returns an empty array (sparse=True) or all-False array (sparse=False).

Raises:

ParameterError

if neither y nor onsets are provided

or if units is not one of ‘frames’, ‘samples’, or ‘time’

See also

onset_strength

compute onset strength per-frame

onset_backtrack

backtracking onset events

librosa.util.peak_pick

pick peaks from a time series

Examples

Get onset times from a signal

>>> y, sr = librosa.load(librosa.ex('trumpet'))
>>> librosa.onset.onset_detect(y=y, sr=sr, units='time')
array([0.07 , 0.232, 0.395, 0.604, 0.743, 0.929, 1.045, 1.115,
       1.416, 1.672, 1.881, 2.043, 2.206, 2.368, 2.554, 3.019])

Or use a pre-computed onset envelope

>>> o_env = librosa.onset.onset_strength(y=y, sr=sr)
>>> times = librosa.times_like(o_env, sr=sr)
>>> onset_frames = librosa.onset.onset_detect(onset_envelope=o_env, sr=sr)

>>> import matplotlib.pyplot as plt
>>> D = np.abs(librosa.stft(y))
>>> fig, ax = plt.subplots(nrows=2, sharex=True)
>>> librosa.display.specshow(librosa.amplitude_to_db(D, ref=np.max),
...                          x_axis='time', y_axis='log', ax=ax[0], sr=sr)
>>> ax[0].set(title='Power spectrogram')
>>> ax[0].label_outer()
>>> ax[1].plot(times, o_env, label='Onset strength')
>>> ax[1].vlines(times[onset_frames], 0, o_env.max(), color='r', alpha=0.9,
...            linestyle='--', label='Onsets')
>>> ax[1].legend()