You're reading an old version of this documentation. If you want up-to-date information, please have a look at 0.10.1.


librosa.onset.onset_detect(y=None, sr=22050, onset_envelope=None, hop_length=512, backtrack=False, energy=None, units='frames', normalize=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

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.

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.

kwargsadditional keyword arguments

Additional parameters for peak picking.

See librosa.util.peak_pick for details.

onsetsnp.ndarray [shape=(n_onsets,)]

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


If no onset strength could be detected, onset_detect returns an empty list.


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