acousticProminenceRatio

Quantify tonality by comparing critical bands

Since R2023b

Syntax

``[pr,prFreq] = acousticProminenceRatio(audioIn,fs)``
``[pr,prFreq,isProminent] = acousticProminenceRatio(audioIn,fs)``
``[pr,prFreq,isProminent,timestamps] = acousticProminenceRatio(audioIn,fs,TimeVarying=true)``
``[___] = acousticProminenceRatio(___,Name=Value)``
``acousticProminenceRatio(___)``

Description

example

````[pr,prFreq] = acousticProminenceRatio(audioIn,fs)` returns the prominence ratios of frequencies in the audio signal to quantify their tonality according to ECMA-418-1 [1].```

example

````[pr,prFreq,isProminent] = acousticProminenceRatio(audioIn,fs)` also returns a logical vector specifying which frequencies are prominent tones according to ECMA-418-1.```

example

````[pr,prFreq,isProminent,timestamps] = acousticProminenceRatio(audioIn,fs,TimeVarying=true)` measures the prominence ratios in a time-varying signal. This syntax also returns a vector of timestamps for each time segment in the input signal.```

example

````[___] = acousticProminenceRatio(___,Name=Value)` specifies options using one or more name-value arguments. For example, `acousticProminenceRatio(x,fs,FFTLength=2048)` computes the prominence ratios with an FFT length of 2048.```

example

````acousticProminenceRatio(___)` with no output arguments plots the prominence ratios of the frequencies in the signal.```

Examples

collapse all

Read in an audio signal containing the sound from a turbine.

`[x,fs] = audioread("Turbine-16-44p1-mono-22secs.wav");`

Listen to the first three seconds of the audio signal.

`sound(x(1:fs*3),fs)`

Use `acousticProminenceRatio` to compute the prominence ratios and measure the tonality of frequencies in the stationary signal.

`[pr,prFreq] = acousticProminenceRatio(x,fs);`

Call `acousticProminenceRatio` with no output arguments to plot the prominence ratios and the magnitude spectrum.

`acousticProminenceRatio(x,fs)`

Read in an audio signal containing a train whistle and listen to it.

```[x,fs] = audioread("TrainWhistle-16-44p1-mono-9secs.wav"); sound(x,fs)```

Call `acousticProminenceRatio` with `TimeVarying` set to `true` to measure the tonality in the time-varying signal.

`[pr,prFreq,isProminent,timestamps] = acousticProminenceRatio(x,fs,TimeVarying=true);`

Call `acousticProminenceRatio` with no output arguments to plot the time-varying prominence ratios.

`acousticProminenceRatio(x,fs,TimeVarying=true)`

Read in an audio signal containing the sound from a turbine.

`[x,fs] = audioread("Turbine-16-44p1-mono-22secs.wav");`

Use `acousticProminenceRatio` to measure the tonality of frequencies in the signal. Specify the third output argument to get a logical vector indicating which frequencies are prominent tones.

`[pr,prFreq,isProminent] = acousticProminenceRatio(x,fs);`

Use `isProminent` to get the frequencies of the prominent tones.

`prominentTones = prFreq(isProminent);`

Read in an audio signal containing the sound from a turbine.

`[x,fs] = audioread("Turbine-16-44p1-mono-22secs.wav");`

Specify custom parameters for the spectral analysis performed by `acousticProminenceRatio`.

```nfft = 2048; window = hamming(nfft,"periodic"); overlap = round(0.75*numel(window)); freqRange = [100 16000];```

Call `acousticProminenceRatio` with the custom parameters and see the resulting plot.

```acousticProminenceRatio(x,fs,FFTLength=nfft,Window=window, ... OverlapLength=overlap,FrequencyRange=freqRange)```

Read in an audio signal containing the sound from a turbine.

`[x,fs] = audioread("Turbine-16-44p1-mono-22secs.wav");`

Compute the magnitude spectrum of the stationary signal and convert it to dB.

```nfft = 16384; [pxx,f] = pwelch(x,hann(nfft,"periodic"),nfft/2,nfft,fs); pxxDB = 10*log10(pxx);```

Use `acousticProminenceRatio` to measure tonality in the magnitude spectrum.

`acousticProminenceRatio(pxxDB,f)`

Read in an audio signal containing a train whistle.

`[x,fs] = audioread("TrainWhistle-16-44p1-mono-9secs.wav");`

Compute the spectrogram of the time-varying signal and convert it to dB.

```nfft = 16384; h = hann(nfft,"periodic"); [~,fs,~,psd] = spectrogram(x,h,nfft/2,nfft,fs); psdDB = 10*log10(psd);```

Use `acousticProminenceRatio` to measure tonality in the spectrogram.

`acousticProminenceRatio(psdDB,fs,TimeVarying=true)`

Input Arguments

collapse all

Audio input, specified as a column vector or matrix. The audio input can be a time-domain or frequency-domain signal.

• If `fs` is a scalar, `audioIn` must be a column vector, which `acousticProminenceRatio` interprets as a single-channel time-domain signal.

• If `fs` is a vector and `TimeVarying` is `false` or unspecified, `audioIn` must be a column vector, which `acousticProminenceRatio` interprets as a magnitude spectrum in dB.

• If `fs` is a vector and `TimeVarying` is `true`, `audioIn` must be a matrix, which `acousticProminenceRatio` interprets as a magnitude spectrogram in dB. Each column in the spectrogram is a spectrum corresponding to a time segment.

Data Types: `single` | `double`

Sample rate or frequency vector in Hz, specified as a positive scalar or vector.

• If `fs` is a scalar, it is the sample rate of the time-domain input signal `audioIn`. To cover the frequency range specified in the ECMA-418-1 [1] standard, the sample rate should be at least 32 kHz.

• If `fs` is a vector, it contains the frequencies corresponding to each row in the frequency-domain input signal `audioIn`.

Data Types: `single` | `double`

Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Example: ```acousticProminenceRatio(x,fs,FrequencyRange=[500 2000])```

Time-varying input signal, specified as `true` or `false`. If `TimeVarying` is `true`, `acousticProminenceRatio` measures tones in each time segment of the time-varying signal.

• If the input is a time-domain signal, the `Window` and `OverlapLength` determine the time segments of the time-varying signal.

• If the input is a frequency-domain signal, each column in the magnitude spectrogram corresponds to a time segment.

Data Types: `logical`

FFT length, specified as a positive integer greater than or equal to the length of `Window`.

This argument does not apply if the input is a frequency-domain signal.

Data Types: `single` | `double`

Analysis window, specified as a vector.

This argument does not apply if the input is a frequency-domain signal.

Data Types: `single` | `double`

Overlap length, specified as a positive integer less than the length of `Window`. This argument specifies the number of overlapping samples between adjacent windows.

This argument does not apply if the input is a frequency-domain signal.

Data Types: `single` | `double`

Frequency range in Hz over which to compute prominence ratios, specified as a two-element row vector. The function computes the prominence ratio for all of the frequency bins within the frequency range.

Data Types: `single` | `double`

Output Arguments

collapse all

Prominence ratios of frequencies in the input signal, returned as a vector of length M, where M is the number of frequency bins within the `FrequencyRange`. The `FFTLength` and `FrequencyRange` determine M.

The ECMA-418-1 [1] standard defines the prominence ratio metric to measure tonality in an audio signal.

If `TimeVarying` is `true`, `acousticProminenceRatio` returns `pr` as an M-by-N matrix with the prominence ratios for each of the N time segments in the time-varying signal.

Frequencies in Hz corresponding to the prominence ratio values in `pr`, returned as a vector with the same number of rows as `pr`.

Prominent tones according to the ECMA-418-1 standard, returned as a logical vector with a value corresponding to each prominence ratio in `pr` indicating whether it represents a prominent tone.

If `TimeVarying` is `true`, `acousticProminenceRatio` returns `isProminent` as a matrix that is of the same size as `pr`.

Timestamps of each time segment in the input signal in seconds, returned as a vector.

This output argument applies only if you set `TimeVarying` to `true`.

References

[1] ECMA-418-1. "Psychoacoustic metrics for ITT equipment — Part 1 (prominent discrete tones)." Ecma International. https://ecma-international.org/publications-and-standards/standards/ecma-418/.

Version History

Introduced in R2023b