Caution

You're reading an old version of this documentation. If you want up-to-date information, 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, **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, must be monophonic

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.

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.

**kwargsadditional keyword arguments

Additional parameters for peak picking.

See librosa.util.peak_pick for details.

Returns:

onsetsnp.ndarray [shape=(n_onsets,)]

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

Note

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

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