librosa.display.specshow

librosa.display.specshow(data, sr=22050, hop_length=512, x_axis=None, y_axis=None, n_xticks=5, n_yticks=5, fmin=None, fmax=None, bins_per_octave=12, tmin=16, tmax=240, freq_fmt='Hz', time_fmt=None, **kwargs)[source]

Display a spectrogram/chromagram/cqt/etc.

Functions as a drop-in replacement for matplotlib.pyplot.imshow, but with useful defaults.

Parameters:

data : np.ndarray [shape=(d, n)]

Matrix to display (e.g., spectrogram)

sr : number > 0 [scalar]

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

hop_length : int > 0 [scalar]

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

x_axis : None or str

y_axis : None or str

Range for the x- and y-axes.

Valid types are:

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

Frequency types:

  • ‘linear’ : frequency range is determined by the FFT window and sampling rate.
  • ‘log’ : the image is displayed on a vertical 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.
  • ‘chroma’ : pitches are determined by the chroma filters.
  • ‘tonnetz’ : axes are labeled by Tonnetz dimensions

Time types:

  • ‘time’ : markers are shown as milliseconds, seconds, minutes, or hours
  • ‘lag’ : like time, but past the half-way point counts as negative values.
  • ‘frames’ : markers are shown as frame counts.
  • ‘tempo’ : markers are shown as beats-per-minute

n_xticks : int > 0 [scalar]

If x_axis is drawn, the number of ticks to show

n_yticks : int > 0 [scalar]

If y_axis is drawn, the number of ticks to show

fmin : float > 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’).

fmax : float > 0 [scalar] or None

Used for setting the Mel frequency scales

bins_per_octave : int > 0 [scalar]

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

tmin : float > 0 [scalar]

tmax : float > 0 [scalar]

Minimum and maximum tempi displayed when _axis=’tempo’, as measured in beats per minute.

freq_fmt : None or str

Formatting for frequency axes. ‘Hz’, by default.

See frequency_ticks.

time_fmt : None or str

Formatting for time axes. None (automatic) by default.

See time_ticks.

kwargs : additional keyword arguments

Arguments passed through to matplotlib.pyplot.imshow.

Returns:

image : matplotlib.image.AxesImage

As returned from matplotlib.pyplot.imshow.

See also

cmap
Automatic colormap detection
time_ticks
time-formatted tick marks
frequency_ticks
frequency-formatted tick marks

matplotlib.pyplot.imshow

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.logamplitude(np.abs(librosa.stft(y))**2, ref_power=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.logamplitude(librosa.cqt(y, sr=sr)**2, ref_power=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)
>>> oenv = librosa.onset.onset_strength(y=y, sr=sr)
>>> tempo = librosa.beat.estimate_tempo(oenv, sr=sr)
>>> Tgram = librosa.feature.tempogram(y=y, sr=sr)
>>> librosa.display.specshow(Tgram[:100], x_axis='time', y_axis='tempo',
...                          tmin=tempo/4, tmax=tempo*2, n_yticks=4)
>>> plt.colorbar()
>>> plt.title('Tempogram')
>>> plt.tight_layout()

(Source code)

../_images/librosa-display-specshow-1.png