Caution

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

librosa.display.waveshow

librosa.display.waveshow(y, *, sr=22050, max_points=11025, x_axis='time', offset=0.0, marker='', where='post', label=None, ax=None, **kwargs)

Visualize a waveform in the time domain.

This function constructs a plot which adaptively switches between a raw samples-based view of the signal (matplotlib.pyplot.step) and an amplitude-envelope view of the signal (matplotlib.pyplot.fill_between) depending on the time extent of the plot’s viewport.

More specifically, when the plot spans a time interval of less than max_points / sr (by default, 1/2 second), the samples-based view is used, and otherwise a downsampled amplitude envelope is used. This is done to limit the complexity of the visual elements to guarantee an efficient, visually interpretable plot.

When using interactive rendering (e.g., in a Jupyter notebook or IPython console), the plot will automatically update as the view-port is changed, either through widget controls or programmatic updates.

Note

When visualizing stereo waveforms, the amplitude envelope will be generated so that the upper limits derive from the left channel, and the lower limits derive from the right channel, which can produce a vertically asymmetric plot.

When zoomed in to the sample view, only the first channel will be shown. If you want to visualize both channels at the sample level, it is recommended to plot each signal independently.

Parameters

ynp.ndarray [shape=(n,) or (2,n)]

audio time series (mono or stereo)

srnumber > 0 [scalar]

sampling rate of y (samples per second)

max_pointspositive integer

Maximum number of samples to draw. When the plot covers a time extent smaller than max_points / sr (default: 1/2 second), samples are drawn.

If drawing raw samples would exceed max_points, then a downsampled amplitude envelope extracted from non-overlapping windows of y is visualized instead. The parameters of the amplitude envelope are defined so that the resulting plot cannot produce more than max_points frames.

x_axisstr or None

Display of the x-axis ticks and tick markers. Accepted values are:

• ‘time’markers are shown as milliseconds, seconds, minutes, or hours.

  Values are plotted in units of seconds.

• ‘s’ : markers are shown as seconds.

• ‘ms’ : markers are shown as milliseconds.

• ‘lag’ : like time, but past the halfway point counts as negative values.

• ‘lag_s’ : same as lag, but in seconds.

• ‘lag_ms’ : same as lag, but in milliseconds.

• None, ‘none’, or ‘off’: ticks and tick markers are hidden.

axmatplotlib.axes.Axes or None

Axes to plot on instead of the default plt.gca().

offsetfloat

Horizontal offset (in seconds) to start the waveform plot

markerstring

Marker symbol to use for sample values. (default: no markers)

See also: matplotlib.markers.

wherestring, {‘pre’, ‘mid’, ‘post’}

This setting determines how both waveform and envelope plots interpolate between observations.

See matplotlib.pyplot.step for details.

Default: ‘post’

labelstring [optional]

The label string applied to this plot. Note that the label

**kwargs

Additional keyword arguments to matplotlib.pyplot.fill_between and matplotlib.pyplot.step.

Note that only those arguments which are common to both functions will be supported.

Returns

librosa.display.AdaptiveWaveplot

An object of type librosa.display.AdaptiveWaveplot

See also

AdaptiveWaveplot

matplotlib.pyplot.step

matplotlib.pyplot.fill_between

matplotlib.markers

Examples

Plot a monophonic waveform with an envelope view

>>> import matplotlib.pyplot as plt
>>> y, sr = librosa.load(librosa.ex('choice'), duration=10)
>>> fig, ax = plt.subplots(nrows=3, sharex=True)
>>> librosa.display.waveshow(y, sr=sr, ax=ax[0])
>>> ax[0].set(title='Envelope view, mono')
>>> ax[0].label_outer()

Or a stereo waveform

>>> y, sr = librosa.load(librosa.ex('choice', hq=True), mono=False, duration=10)
>>> librosa.display.waveshow(y, sr=sr, ax=ax[1])
>>> ax[1].set(title='Envelope view, stereo')
>>> ax[1].label_outer()

Or harmonic and percussive components with transparency

>>> y, sr = librosa.load(librosa.ex('choice'), duration=10)
>>> y_harm, y_perc = librosa.effects.hpss(y)
>>> librosa.display.waveshow(y_harm, sr=sr, alpha=0.5, ax=ax[2], label='Harmonic')
>>> librosa.display.waveshow(y_perc, sr=sr, color='r', alpha=0.5, ax=ax[2], label='Percussive')
>>> ax[2].set(title='Multiple waveforms')
>>> ax[2].legend()

Zooming in on a plot to show raw sample values

>>> fig, (ax, ax2) = plt.subplots(nrows=2, sharex=True)
>>> ax.set(xlim=[6.0, 6.01], title='Sample view', ylim=[-0.2, 0.2])
>>> librosa.display.waveshow(y, sr=sr, ax=ax, marker='.', label='Full signal')
>>> librosa.display.waveshow(y_harm, sr=sr, alpha=0.5, ax=ax2, label='Harmonic')
>>> librosa.display.waveshow(y_perc, sr=sr, color='r', alpha=0.5, ax=ax2, label='Percussive')
>>> ax.label_outer()
>>> ax.legend()
>>> ax2.legend()