# spectralSpread

Spectral spread for audio signals and auditory spectrograms

## Syntax

## Description

specifies options using one or more `spread`

= spectralSpread(`x`

,`f`

,`Name,Value`

)`Name,Value`

pair arguments.

## Examples

### Spectral Spread of Time-Domain Audio

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

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

### Spectral Spread of Frequency-Domain Audio Data

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

function. Calculate the spread of the mel spectrums over time. Plot the results.

[audioIn,fs] = audioread('Counting-16-44p1-mono-15secs.wav'); [s,cf,t] = melSpectrogram(audioIn,fs); spread = spectralSpread(s,cf); plot(t,spread) xlabel('Time (s)') ylabel('Spread (Hz)')

### Specify Nondefault Parameters

Read in an audio file.

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

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

/2 for the spread calculation. Plot the results.

spread = spectralSpread(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(spread,1)); plot(t,spread) xlabel('Time (s)') ylabel('Spread (Hz)')

### Calculate Spectral Spread of Streaming Audio

Create a `dsp.AudioFileReader`

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

to log the spectral spread 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 spread for the frame of audio.

Log the spectral spread for later plotting.

To calculate the spectral spread 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(); spread = spectralSpread(audioIn,fileReader.SampleRate, ... 'Window',win, ... 'OverlapLength',0); logger(spread) end plot(logger.Buffer) ylabel('Spread (Hz)')

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

`spectralSpread`

.You want to calculate the spectral spread 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 spread 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); spread = spectralSpread(audioBuffered,fs, ... 'Window',win, ... 'OverlapLength',0); logger(spread) end end release(fileReader)

Plot the logged data.

```
plot(logger.Buffer)
ylabel('Spread (Hz)')
```

## 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 spread is calculated for the one-sided power spectrum.`'magnitude'`

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

**Data Types: **`char`

| `string`

## Output Arguments

`centroid`

— Spectral centroid (Hz)

scalar | vector | matrix

Spectral centroid in Hz, returned as a scalar, vector, or matrix. Each row of
`centroid`

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

. Each column of `centroid`

corresponds to an
independent channel.

## Algorithms

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

$$\text{spread}=\sqrt{\frac{{\displaystyle \sum _{k={b}_{1}}^{{b}_{2}}{\left({f}_{k}-{\mu}_{1}\right)}^{2}{s}_{k}}}{{\displaystyle \sum _{k={b}_{1}}^{{b}_{2}}{s}_{k}}}}$$

where

*f*is the frequency in Hz corresponding to bin_{k}*k*.*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.*μ*_{1}is the spectral centroid, calculated as described by the`spectralCentroid`

function.

## References

[1] Peeters, G. "A Large Set of Audio Features for Sound Description (Similarity and Classification) in the CUIDADO Project." Technical Report; IRCAM: Paris, France, 2004.

## 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)