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

[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].

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

[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.

[___] = 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.

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

Examples

Measure Tonality with Prominence Ratio

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)

Measure Tonality in a Time-Varying Signal

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)

Find Prominent Tones with Prominence Ratio

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

Specify Custom Parameters for Measuring Prominence Ratio

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)

Measure Tonality in Magnitude Spectrum

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)

Measure Tonality in Spectrogram

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

audioIn — Audio input

column vector | matrix

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

fs — Sample rate or frequency vector (Hz)

positive scalar | vector

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

TimeVarying — Time-varying input signal

false (default) | true

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

FFTLength — FFT length

min(size(audioIn,1),2^nextpow2(0.2*fs)) (default) | positive integer

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

Window — Analysis window

hann(FFTLength,"periodic") (default) | vector

Analysis window, specified as a vector.

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

Data Types: single | double

OverlapLength — Overlap length

round(numel(Window)/2) (default) | positive integer

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

FrequencyRange — Frequency range (Hz)

[89.1 11200] (default) | two-element row vector

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

pr — Prominence ratios

vector | matrix

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.

prFreq — Frequencies (Hz)

vector

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

isProminent — Prominent tones

vector | matrix

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 — Timestamps

vector

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/.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2023b