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

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

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

 visualize Open 'EBU Mode' meter display
 clone Create duplicate System object isLocked Determine if System object is in use release Release resources and allow changes to System object property values and input characteristics reset Reset internal states of System object step Run System object algorithm

## Examples

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

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 = [];

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

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.

'SamplesPerFrame',1024);
deviceWriter = audioDeviceWriter('SampleRate',fs);

Create a time scope to visualize your audio stream loop.

timeScope = dsp.TimeScope('NumInputPorts',2, ...
'SampleRate',fs, ...
'TimeSpanOverrunAction','Scroll', ...
'LayoutDimensions',[2,1], ...
'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:

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

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

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.

'SamplesPerFrame',1024);
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 = dsp.TimeScope( ...
'NumInputPorts',3, ...
'SampleRate',fs, ...
'TimeSpanOverrunAction','Scroll', ...
'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.

[momentary,shortTerm] = loudMtr(x);
scope(x,momentary,shortTerm)
deviceWriter(x);
end

release(deviceWriter)

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