Caution

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

librosa.display.specshow

librosa.display.specshow(data, x_coords=None, y_coords=None, x_axis=None, y_axis=None, sr=22050, hop_length=512, fmin=None, fmax=None, tuning=0.0, bins_per_octave=12, ax=None, **kwargs)

Display a spectrogram/chromagram/cqt/etc.

Parameters

datanp.ndarray [shape=(d, n)]

Matrix to display (e.g., spectrogram)

srnumber > 0 [scalar]

Sample rate used to determine time scale in x-axis.

hop_lengthint > 0 [scalar]

Hop length, also used to determine time scale in x-axis

x_axisNone or str

y_axisNone or str

Range for the x- and y-axes.

Valid types are:

• None, ‘none’, or ‘off’ : no axis decoration is displayed.

Frequency types:

• ‘linear’, ‘fft’, ‘hz’ : frequency range is determined by the FFT window and sampling rate.

• ‘log’ : the spectrum is displayed on a log scale.

• ‘mel’ : frequencies are determined by the mel scale.

• ‘cqt_hz’ : frequencies are determined by the CQT scale.

• ‘cqt_note’ : pitches are determined by the CQT scale.

All frequency types are plotted in units of Hz.

Categorical types:

• ‘chroma’ : pitches are determined by the chroma filters. Pitch classes are arranged at integer locations (0-11).

• ‘tonnetz’ : axes are labeled by Tonnetz dimensions (0-5)

• ‘frames’ : markers are shown as frame counts.

Time types:

• ‘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.

Rhythm:

• ‘tempo’markers are shown as beats-per-minute (BPM)

  using a logarithmic scale. This is useful for visualizing the outputs of feature.tempogram.

• ‘fourier_tempo’same as ‘tempo’, but used when

  tempograms are calculated in the Frequency domain using feature.fourier_tempogram.

x_coordsnp.ndarray [shape=data.shape[1]+1]

y_coordsnp.ndarray [shape=data.shape[0]+1]

Optional positioning coordinates of the input data. These can be use to explicitly set the location of each element data[i, j], e.g., for displaying beat-synchronous features in natural time coordinates.

If not provided, they are inferred from x_axis and y_axis.

fminfloat > 0 [scalar] or None

Frequency of the lowest spectrogram bin. Used for Mel and CQT scales.

If y_axis is cqt_hz or cqt_note and fmin is not given, it is set by default to note_to_hz(‘C1’).

fmaxfloat > 0 [scalar] or None

Used for setting the Mel frequency scales

tuningfloat

Tuning deviation from A440, in fractions of a bin.

This is used for CQT frequency scales, so that fmin is adjusted to fmin * 2**(tuning / bins_per_octave).

bins_per_octaveint > 0 [scalar]

Number of bins per octave. Used for CQT frequency scale.

axmatplotlib.axes.Axes or None

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

kwargsadditional keyword arguments

Arguments passed through to matplotlib.pyplot.pcolormesh.

By default, the following options are set:

• rasterized=True

• shading=’flat’

• edgecolors=’None’

Returns

axes

The axis handle for the figure.

See also

cmap

Automatic colormap detection

matplotlib.pyplot.pcolormesh

Examples

Visualize an STFT power spectrum

>>> import matplotlib.pyplot as plt
>>> y, sr = librosa.load(librosa.util.example_audio_file())
>>> plt.figure(figsize=(12, 8))

>>> D = librosa.amplitude_to_db(np.abs(librosa.stft(y)), ref=np.max)
>>> plt.subplot(4, 2, 1)
>>> librosa.display.specshow(D, y_axis='linear')
>>> plt.colorbar(format='%+2.0f dB')
>>> plt.title('Linear-frequency power spectrogram')

Or on a logarithmic scale

>>> plt.subplot(4, 2, 2)
>>> librosa.display.specshow(D, y_axis='log')
>>> plt.colorbar(format='%+2.0f dB')
>>> plt.title('Log-frequency power spectrogram')

Or use a CQT scale

>>> CQT = librosa.amplitude_to_db(np.abs(librosa.cqt(y, sr=sr)), ref=np.max)
>>> plt.subplot(4, 2, 3)
>>> librosa.display.specshow(CQT, y_axis='cqt_note')
>>> plt.colorbar(format='%+2.0f dB')
>>> plt.title('Constant-Q power spectrogram (note)')

>>> plt.subplot(4, 2, 4)
>>> librosa.display.specshow(CQT, y_axis='cqt_hz')
>>> plt.colorbar(format='%+2.0f dB')
>>> plt.title('Constant-Q power spectrogram (Hz)')

Draw a chromagram with pitch classes

>>> C = librosa.feature.chroma_cqt(y=y, sr=sr)
>>> plt.subplot(4, 2, 5)
>>> librosa.display.specshow(C, y_axis='chroma')
>>> plt.colorbar()
>>> plt.title('Chromagram')

Force a grayscale colormap (white -> black)

>>> plt.subplot(4, 2, 6)
>>> librosa.display.specshow(D, cmap='gray_r', y_axis='linear')
>>> plt.colorbar(format='%+2.0f dB')
>>> plt.title('Linear power spectrogram (grayscale)')

Draw time markers automatically

>>> plt.subplot(4, 2, 7)
>>> librosa.display.specshow(D, x_axis='time', y_axis='log')
>>> plt.colorbar(format='%+2.0f dB')
>>> plt.title('Log power spectrogram')

Draw a tempogram with BPM markers

>>> plt.subplot(4, 2, 8)
>>> Tgram = librosa.feature.tempogram(y=y, sr=sr)
>>> librosa.display.specshow(Tgram, x_axis='time', y_axis='tempo')
>>> plt.colorbar()
>>> plt.title('Tempogram')
>>> plt.tight_layout()
>>> plt.show()

Draw beat-synchronous chroma in natural time

>>> plt.figure()
>>> tempo, beat_f = librosa.beat.beat_track(y=y, sr=sr, trim=False)
>>> beat_f = librosa.util.fix_frames(beat_f, x_max=C.shape[1])
>>> Csync = librosa.util.sync(C, beat_f, aggregate=np.median)
>>> beat_t = librosa.frames_to_time(beat_f, sr=sr)
>>> ax1 = plt.subplot(2,1,1)
>>> librosa.display.specshow(C, y_axis='chroma', x_axis='time')
>>> plt.title('Chroma (linear time)')
>>> ax2 = plt.subplot(2,1,2, sharex=ax1)
>>> librosa.display.specshow(Csync, y_axis='chroma', x_axis='time',
...                          x_coords=beat_t)
>>> plt.title('Chroma (beat time)')
>>> plt.tight_layout()
>>> plt.show()