Caution

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

librosa.feature.spectral_flatness

librosa.feature.spectral_flatness(*, y=None, S=None, n_fft=2048, hop_length=512, win_length=None, window='hann', center=True, pad_mode='constant', amin=1e-10, power=2.0)[source]

Compute spectral flatness

Spectral flatness (or tonality coefficient) is a measure to quantify how much noise-like a sound is, as opposed to being tone-like [1]. A high spectral flatness (closer to 1.0) indicates the spectrum is similar to white noise. It is often converted to decibel.

Parameters:

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

audio time series. Multi-channel is supported.

Snp.ndarray [shape=(…, d, t)] or None

(optional) pre-computed spectrogram magnitude

n_fftint > 0 [scalar]

FFT window size

hop_lengthint > 0 [scalar]

hop length for STFT. See librosa.stft for details.

win_lengthint <= n_fft [scalar]

Each frame of audio is windowed by window(). The window will be of length win_length and then padded with zeros to match n_fft. If unspecified, defaults to win_length = n_fft.

windowstring, tuple, number, function, or np.ndarray [shape=(n_fft,)]

a window specification (string, tuple, or number); see scipy.signal.get_window
a window function, such as scipy.signal.windows.hann
a vector or array of length n_fft

centerboolean

If True, the signal y is padded so that frame t is centered at y[t * hop_length].
If False, then frame t begins at y[t * hop_length]

pad_modestring

If center=True, the padding mode to use at the edges of the signal. By default, STFT uses zero padding.

aminfloat > 0 [scalar]

minimum threshold for S (=added noise floor for numerical stability)

powerfloat > 0 [scalar]

Exponent for the magnitude spectrogram. e.g., 1 for energy, 2 for power, etc. Power spectrogram is usually used for computing spectral flatness.

Returns:

flatnessnp.ndarray [shape=(…, 1, t)]: spectral flatness for each frame. The returned value is in [0, 1] and often converted to dB scale.

Examples

From time-series input

>>> y, sr = librosa.load(librosa.ex('trumpet'))
>>> flatness = librosa.feature.spectral_flatness(y=y)
>>> flatness
array([[0.001, 0.   , ..., 0.218, 0.184]], dtype=float32)

From spectrogram input

>>> S, phase = librosa.magphase(librosa.stft(y))
>>> librosa.feature.spectral_flatness(S=S)
array([[0.001, 0.   , ..., 0.218, 0.184]], dtype=float32)

From power spectrogram input

>>> S, phase = librosa.magphase(librosa.stft(y))
>>> S_power = S ** 2
>>> librosa.feature.spectral_flatness(S=S_power, power=1.0)
array([[0.001, 0.   , ..., 0.218, 0.184]], dtype=float32)