# spectralFlatness

Spectral flatness for audio signals and auditory spectrograms

## Syntax

## Description

specifies options using one or more `flatness`

= spectralFlatness(`x`

,`f`

,`Name,Value`

)`Name,Value`

pair arguments.

`[`

returns the spectral arithmetic mean and spectral geometric mean.`flatness`

,`arithmeticMean`

,`geometricMean`

] = spectralFlatness(___)

## Examples

### Spectral Flatness of Time-Domain Audio

Read in an audio file, calculate the flatness using default parameters, and then plot the results.

[audioIn,fs] = audioread('Counting-16-44p1-mono-15secs.wav'); flatness = spectralFlatness(audioIn,fs); t = linspace(0,size(audioIn,1)/fs,size(flatness,1)); plot(t,flatness) xlabel('Time (s)') ylabel('Flatness')

### Spectral Flatness of Frequency-Domain Audio Data

Read in an audio file and then calculate the mel spectrogram using the `melSpectrogram`

function.

```
[audioIn,fs] = audioread('Counting-16-44p1-mono-15secs.wav');
[s,cf,t] = melSpectrogram(audioIn,fs);
```

Calculate the flatness of the mel spectrogram over time. Plot the results.

flatness = spectralFlatness(s,cf); plot(t,flatness) xlabel('Time (s)') ylabel('Flatness')

### Specify Nondefault Parameters

Read in an audio file.

`[audioIn,fs] = audioread('Counting-16-44p1-mono-15secs.wav');`

Calculate the flatness of the power spectrum over time. Calculate the flatness for 50 ms Hamming windows of data with 25 ms overlap. Use the range from 62.5 Hz to `fs`

/2 for the flatness calculation. Plot the results.

flatness = spectralFlatness(audioIn,fs, ... 'Window',hamming(round(0.05*fs)), ... 'OverlapLength',round(0.025*fs), ... 'Range',[62.5,fs/2]); t = linspace(0,size(audioIn,1)/fs,size(flatness,1)); plot(t,flatness) xlabel('Time (s)') ylabel('Flatness')

### Calculate Spectral Flatness of Streaming Audio

Create a `dsp.AudioFileReader`

object to read in audio data frame-by-frame. Create a `dsp.SignalSink`

to log the spectral flatness calculation.

```
fileReader = dsp.AudioFileReader('Counting-16-44p1-mono-15secs.wav');
logger = dsp.SignalSink;
```

In an audio stream loop:

Read in a frame of audio data.

Calculate the spectral flatness for the frame of audio.

Log the spectral flatness for later plotting.

To calculate the spectral flatness for only a given input frame, specify a window with the same number of samples as the input, and set the overlap length to zero. Plot the logged data.

win = hamming(fileReader.SamplesPerFrame); while ~isDone(fileReader) audioIn = fileReader(); flatness = spectralFlatness(audioIn,fileReader.SampleRate, ... 'Window',win, ... 'OverlapLength',0); logger(flatness) end plot(logger.Buffer) ylabel('Flatness')

Use `dsp.AsyncBuffer`

if

The input to your audio stream loop has a variable samples-per-frame.

The input to your audio stream loop has an inconsistent samples-per-frame with the analysis window of

`spectralFlatness`

.You want to calculate the spectral flatness for overlapped data.

Create a `dsp.AsyncBuffer`

object, reset the logger, and release the file reader.

buff = dsp.AsyncBuffer; reset(logger) release(fileReader)

Specify that the spectral flatness is calculated for 50 ms frames with a 25 ms overlap.

fs = fileReader.SampleRate; samplesPerFrame = round(fs*0.05); samplesOverlap = round(fs*0.025); samplesPerHop = samplesPerFrame - samplesOverlap; win = hamming(samplesPerFrame); while ~isDone(fileReader) audioIn = fileReader(); write(buff,audioIn); while buff.NumUnreadSamples >= samplesPerHop audioBuffered = read(buff,samplesPerFrame,samplesOverlap); flatness = spectralFlatness(audioBuffered,fs, ... 'Window',win, ... 'OverlapLength',0); logger(flatness) end end release(fileReader)

Plot the logged data.

```
plot(logger.Buffer)
ylabel('Flatness')
```

## Input Arguments

`x`

— Input signal

column vector | matrix | 3-D array

Input signal, specified as a vector, matrix, or 3-D array. How the function
interprets `x`

depends on the shape of `f`

.

**Data Types: **`single`

| `double`

`f`

— Sample rate or frequency vector (Hz)

scalar | vector

Sample rate or frequency vector in Hz, specified as a scalar or vector,
respectively. How the function interprets `x`

depends on the shape
of `f`

:

If

`f`

is a scalar,`x`

is interpreted as a time-domain signal, and`f`

is interpreted as the sample rate. In this case,`x`

must be a real vector or matrix. If`x`

is specified as a matrix, the columns are interpreted as individual channels.If

`f`

is a vector,`x`

is interpreted as a frequency-domain signal, and`f`

is interpreted as the frequencies, in Hz, corresponding to the rows of`x`

. In this case,`x`

must be a real*L*-by-*M*-by-*N*array, where*L*is the number of spectral values at given frequencies of`f`

,*M*is the number of individual spectra, and*N*is the number of channels.The number of rows of

`x`

,*L*, must be equal to the number of elements of`f`

.

**Data Types: **`single`

| `double`

### Name-Value Arguments

Specify optional
comma-separated pairs of `Name,Value`

arguments. `Name`

is
the argument name and `Value`

is the corresponding value.
`Name`

must appear inside quotes. You can specify several name and value
pair arguments in any order as
`Name1,Value1,...,NameN,ValueN`

.

**Example:**

`'Window',hamming(256)`

**Note**

The following name-value pair arguments apply if `x`

is a
time-domain signal. If `x`

is a frequency-domain signal, name-value
pair arguments are ignored.

`Window`

— Window applied in time domain

`rectwin(round(``f`

*0.03))

(default) | vector

`f`

*0.03))Window applied in the time domain, specified as the comma-separated pair
consisting of `'Window'`

and a real vector. The number of elements in
the vector must be in the range [1,
`size(`

]. The number of elements in the
vector must also be greater than `x`

,1)`OverlapLength`

.

**Data Types: **`single`

| `double`

`OverlapLength`

— Number of samples overlapped between adjacent windows

`round(``f`

*0.02)

(default) | non-negative scalar

`f`

*0.02)Number of samples overlapped between adjacent windows, specified as the
comma-separated pair consisting of `'OverlapLength'`

and an integer
in the range [0, `size(`

).`Window`

,1)

**Data Types: **`single`

| `double`

`FFTLength`

— Number of bins in DFT

`numel(``Window`

)

(default) | positive scalar integer

`Window`

)Number of bins used to calculate the DFT of windowed input samples, specified as
the comma-separated pair consisting of `'FFTLength'`

and a positive
scalar integer. If unspecified, `FFTLength`

defaults to the number
of elements in the `Window`

.

**Data Types: **`single`

| `double`

`Range`

— Frequency range (Hz)

`[0,``f`

/2]

(default) | two-element row vector

`f`

/2]Frequency range in Hz, specified as the comma-separated pair consisting of
`'Range'`

and a two-element row vector of increasing real values in
the range [0, `f`

/2].

**Data Types: **`single`

| `double`

`SpectrumType`

— Spectrum type

`'power'`

(default) | `'magnitude'`

Spectrum type, specified as the comma-separated pair consisting of
`'SpectrumType'`

and `'power'`

or
`'magnitude'`

:

`'power'`

–– The spectral flatness is calculated for the one-sided power spectrum.`'magnitude'`

–– The spectral flatness is calculated for the one-sided magnitude spectrum.

**Data Types: **`char`

| `string`

## Output Arguments

`flatness`

— Spectral flatness

scalar | vector | matrix

Spectral flatness, returned as a scalar, vector, or matrix. Each row of
`flatness`

corresponds to the spectral flatness of a window of
`x`

. Each column of `flatness`

corresponds to an
independent channel.

`arithmeticMean`

— Spectral arithmetic mean

scalar | vector | matrix

Spectral arithmetic mean, returned as a scalar, vector, or matrix. Each row of
`arithmeticMean`

corresponds to the arithmetic mean of the spectrum
of a window of `x`

. Each column of
`arithmeticMean`

corresponds to an independent channel.

`geometricMean`

— Spectral geometric mean

scalar | vector | matrix

Spectral geometric mean, returned as a scalar, vector, or matrix. Each row of
`geometricMean`

corresponds to the geometric mean of the spectrum
of a window of `x`

. Each column of `geometricMean`

corresponds to an independent channel.

## Algorithms

The spectral flatness is calculated as described in [1]:

$$\text{flatness}=\frac{{\left({\displaystyle \prod _{k={b}_{1}}^{{b}_{2}}{s}_{k}}\right)}^{\frac{1}{{b}_{2}-{b}_{1}}}}{\frac{1}{{b}_{2}-{b}_{1}}{\displaystyle \sum _{k={b}_{1}}^{{b}_{2}}{s}_{k}}}$$

where

*s*is the spectral value at bin_{k}*k*.*b*_{1}and*b*_{2}are the band edges, in bins, over which to calculate the spectral spread.

## References

[1] Johnston, J.d. "Transform Coding
of Audio Signals Using Perceptual Noise Criteria." *IEEE Journal on Selected Areas
in Communications*. Vol. 6, Number 2, 1988, pp. 314–323.

## Extended Capabilities

### C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

### GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

**Introduced in R2019a**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

# Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)