Main Content

acousticProminenceRatio

Quantify tonality by comparing critical bands

Since R2023b

    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)

    Figure contains 2 axes objects. Axes object 1 with title Prominence Ratio, xlabel Frequency (Hz), ylabel Prominence Ratio (dB) contains an object of type line. Axes object 2 with xlabel Frequency (Hz), ylabel Spectrum (dB) contains an object of type line.

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