Main Content

loudnessMeter

Standard-compliant loudness measurements

Description

The loudnessMeter System object™ computes the loudness, loudness range, and true-peak of an audio signal in accordance with EBU R 128 and ITU-R BS.1770-4 standards.

To implement loudness metering:

  1. Create the loudnessMeter object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Description

loudMtr = loudnessMeter creates a System object, loudMtr, that performs loudness metering independently across each input channel.

loudMtr = loudnessMeter(Name,Value) sets each property Name to the specified Value. Unspecified properties have default values.

Example: loudMtr = loudnessMeter('ChannelWeights',[1.2, 0.8],'SampleRate',12000) creates a System object, loudMtr, with channel weights of 1.2 and 0.8, and a sample rate of 12 kHz.

Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Linear weighting applied to each input channel, specified as a row vector of nonnegative values. The number of elements in the row vector must be equal to or greater than the number of input channels. Excess values in the vector are ignored.

The default channel weights follow the ITU-R BS.1170-4 standard. To use the default channel weights, specify the input signal channels as a matrix in this order: [Left, Right, Center, Left surround, Right surround].

As a best practice, specify the ChannelWeights property in order: [Left, Right, Center, Left surround, Right surround].

Tunable: Yes

Data Types: single | double

Use relative scale for loudness measurements, specified as a logical scalar.

  • false –– The loudness measurements are absolute and returned in loudness units full scale (LUFS).

  • true –– The loudness measurements are relative to the TargetLoudness value and returned in loudness units (LU).

Tunable: No

Data Types: logical

Target loudness level for relative scale in LUFS, specified as a real scalar.

For example, if the TargetLoudness is –23 LUFS, then a loudness value of –23 LUFS is reported as 0 LU.

Tunable: Yes

Dependencies

To enable this property, set UseRelativeScale to true.

Data Types: single | double

Input sample rate in Hz, specified as a positive scalar.

Tunable: Yes

Data Types: single | double

Usage

Description

example

[momentary,shortTerm,integrated,range,peak] = loudMtr(audioIn) returns measurement values for momentary and short-term loudness of the input to your loudness meter, and the true-peak value of the current input frame, audioIn. It also returns the integrated loudness and loudness range of the input to your loudness meter since the last time reset was called.

Input Arguments

expand all

Audio input to the loudness meter, specified as a matrix. The columns of the matrix are treated as independent audio channels.

Note

If you use the default ChannelWeights of the loudnessMeter, as a best practice, specify the input channels in this order: [Left, Right, Center, Left surround, Right surround].

Data Types: single | double

Output Arguments

expand all

Momentary loudness in loudness units relative to full scale (LUFS), returned as a column vector with the same number of rows as audioIn.

By default, loudness measurements are returned in LUFS. If you set the UseRelativeScale property to true, loudness measurements are returned in loudness units (LU).

Data Types: single | double

Short-term loudness in loudness units relative to full scale (LUFS), returned as a column vector with the same number of rows as audioIn.

By default, loudness measurements are returned in LUFS. If you set the UseRelativeScale property to true, loudness measurements are returned in loudness units (LU).

Data Types: single | double

Integrated loudness in loudness units relative to full scale (LUFS), returned as a column vector with the same number of rows as audioIn.

By default, loudness measurements are returned in LUFS. If you set the UseRelativeScale property to true, loudness measurements are returned in loudness units (LU).

Data Types: single | double

Loudness range in loudness units (LU), returned as a column vector with the same number of rows as audioIn.

Data Types: single | double

True-peak loudness in dB-TP, returned as a column vector with the same number of rows as audioIn.

Data Types: single | double

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

expand all

visualizeOpen 'EBU Mode' meter display
cloneCreate duplicate System object
isLockedDetermine if System object is in use
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object
stepRun System object algorithm

Examples

collapse all

Create a dsp.AudioFileReader System object™ to read in an audio file. Create a loudnesMeter System object. Use the sample rate of the audio file as the sample rate of the loudnessMeter.

fileReader = dsp.AudioFileReader('RockDrums-44p1-stereo-11secs.mp3');
loudMtr = loudnessMeter('SampleRate',fileReader.SampleRate);

Read in the audio file in an audio stream loop. Use the loudness meter to determine the momentary, short-term, and integrated loudness of the audio signal. Cache the loudness measurements for analysis.

momentary = [];
shortTerm = [];
integrated = [];

while ~isDone(fileReader)
    x = fileReader();
    [m,s,i] = loudMtr(x);
    momentary = [momentary;m];
    shortTerm = [shortTerm;s];
    integrated = [integrated;i];
end

release(fileReader)

Plot the momentary, short-term, and integrated loudness of the audio signal.

t = linspace(0,11,length(momentary));
plot(t,[momentary,shortTerm,integrated])
title('Loudness Measurements')
legend('Momentary','Short-term','Integrated')
xlabel('Time (seconds)')
ylabel('LUFS')

Create an audio file reader and an audio device writer.

fileReader = dsp.AudioFileReader('FunkyDrums-44p1-stereo-25secs.mp3', ...
    'SamplesPerFrame',1024);
fs = fileReader.SampleRate;
deviceWriter = audioDeviceWriter('SampleRate',fs);

Create a time scope to visualize your audio stream loop.

timeScope = timescope('NumInputPorts',2, ...
    'SampleRate',fs, ...
    'TimeSpanOverrunAction','Scroll', ...
    'LayoutDimensions',[2,1], ...
    'TimeSpanSource','Property','TimeSpan',5, ...
    'BufferLength',5*fs);

% Top subplot of scope
timeScope.Title = 'Momentary Loudness';
timeScope.YLabel = 'LUFS';
timeScope.YLimits = [-40, 0];

% Bottom subplot of scope
timeScope.ActiveDisplay = 2;
timeScope.Title = 'Loudness Range';
timeScope.YLabel = 'LU';
timeScope.YLimits = [-1, 2];

Create a loudness meter. Use the sample rate of your input file as the sample rate of your loudness meter. Call visualize to open an 'EBU-mode' visualization for your loudness meter.

loudMtr = loudnessMeter('SampleRate',fs);
visualize(loudMtr)

In an audio stream loop:

  • Read in your audio file.

  • Compute the momentary loudness and loudness range.

  • Visualize the momentary loudness and loudness range on your time scope.

  • Play the audio signal.

The 'EBU-mode' loudness meter visualization updates automatically while it is open. As a best practice, release your file reader and device writer once the loop is completed.

while ~isDone(fileReader)
    audioIn = fileReader();
    [momentaryLoudness,~,~,LRA] = loudMtr(audioIn);
    timeScope(momentaryLoudness,LRA);
    deviceWriter(audioIn);
end

release(fileReader)
release(deviceWriter)

Create an audio file reader to read in an audio file. Create an audio device writer to write the audio file to your audio device. Use the sample rate of your file reader as the sample rate of your device writer.

fileReader = dsp.AudioFileReader('Counting-16-44p1-mono-15secs.wav',...
    'SamplesPerFrame',1024);
fs = fileReader.SampleRate;
deviceWriter = audioDeviceWriter('SampleRate',fs);

Create a loudness meter with the target loudness set to the default -23 LUFS. Open the 'EBU-mode' loudness meter visualization.

loudMtr = loudnessMeter('UseRelativeScale',true);
visualize(loudMtr)

Create a time scope to visualize your audio signal and its measured relative momentary and short-term loudness.

scope = timescope( ...
    'NumInputPorts',3, ...
    'SampleRate',fs, ...
    'TimeSpanOverrunAction','Scroll', ...
    'TimeSpanSource','Property','TimeSpan',5, ...
    'BufferLength',5*fs, ...
    'Title','Audio Signal, Momentary Loudness, and Short-Term Loudness', ...
    'ChannelNames',{'Audio signal','Momentary loudness','Short-term loudness'}, ...
    'YLimits',[-16,16], ...
    'YLabel','Amplitude / LU', ...
    'ShowLegend',true);

In an audio stream loop, listen to and visualize the audio signal.

while ~isDone(fileReader)
    x = fileReader();
    [momentary,shortTerm] = loudMtr(x);
    scope(x,momentary,shortTerm)
    deviceWriter(x);
end

release(deviceWriter)
release(fileReader)

Algorithms

expand all

The loudnessMeter System object calculates the momentary loudness, short-term loudness, integrated loudness, loudness range (LRA), and true-peak value of an audio signal. You can specify any number of channels and nondefault channel weights used for loudness measurements. The loudnessMeter algorithm is described for the general case of n channels with default channel weights.

References

[1] International Telecommunication Union; Radiocommunication Sector. Algorithms to Measure Audio Programme Loudness and True-Peak Audio Level. ITU-R BS.1770-4. 2015.

[2] European Broadcasting Union. Loudness Normalisation and Permitted Maximum Level of Audio Signals. EBU R 128. 2014.

[3] European Broadcasting Union. Loudness Metering: 'EBU Mode' Metering to Supplement EBU R 128 Loudness Normalization. EBU R 128 Tech 3341. 2014.

[4] European Broadcasting Union. Loudness Range: A Measure to Supplement EBU R 128 Loudness Normalization. EBU R 128 Tech 3342. 2016.

Extended Capabilities

Version History

Introduced in R2016b