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(*, y=None, sr=22050, onset_envelope=None, hop_length=512, backtrack=False, energy=None, units='frames', normalize=True, sparse=True, **kwargs)[source]

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].

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.


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.


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.


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.


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.


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

**kwargsadditional keyword arguments

Additional parameters for peak picking.

See librosa.util.peak_pick for details.

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.


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


if neither y nor onsets are provided

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

See also


compute onset strength per-frame


backtracking onset events


pick peaks from a time series


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])
>>> 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()