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

Syntax

loudMtr = loudnessMeter

loudMtr = loudnessMeter(Name,Value)

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

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.

ChannelWeights — Linear weighting applied to each input channel

[1, 1, 1, 1.41, 1.41] (default) | nonnegative row vector

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

UseRelativeScale — Use relative scale for loudness measurements

false (default) | true

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

TargetLoudness — Target loudness level for relative scale (LUFS)

-23 (default) | real scalar

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

SampleRate — Input sample rate (Hz)

44100 (default) | positive scalar

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

Tunable: Yes

Data Types: single | double

Usage

Syntax

[momentary,shortTerm,integrated,range,peak] = loudMtr(audioIn)

Description

[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

audioIn — Audio input to loudness meter

matrix

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

momentary — Momentary loudness (LUFS)

column vector

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

shortTerm — Short-term loudness (LUFS)

column vector

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 — Integrated loudness (LUFS)

column vector

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

range — Loudness range (LU)

column vector

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

Data Types: single | double

peak — True-peak loudness (dB-TP)

scalar

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)

Specific to loudnessMeter

visualize

Open 'EBU Mode' meter display

Common to All System Objects

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

Loudness of Audio Signal

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

Plot Momentary Loudness and Loudness Range of Audio Stream

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)

Relative Scale for Loudness Measurements

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

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.

Loudness Measurements

The input channels, x, pass through a K-weighted weightingFilter. The K-weighted filter shapes the frequency spectrum to reflect perceived loudness.

Momentary Loudness and Integrated Loudness

1. The K-weighted channels, y, are divided into 0.4-second segments with 0.3-second overlap. If the required number of samples have not been collected yet, the loudnessMeter System object returns the last computed values for momentary and integrated loudness. If enough samples have been collected, then the power (mean square) of each segment of the K-weighted channels is calculated:

   $$m{P}_i=\frac{1}{w}{\displaystyle \sum _{k=1}^w{y}_i^2[k]}$$

   • mP_i is the momentary power of the ith segment.

   • w is the segment length in samples.

2. The momentary loudness, mL, is computed in LUFS for each segment:

   $$m{L}_i=-0.691+10{\log }_{10}\left({\displaystyle \sum _{c=1}^n{G}_c\times m{P}_{\left(i,c\right)}}\right)$$

   • G_c is the weighting for channel c.

   mL is the momentary loudness returned by your loudnessMeter System object. It is also used internally to calculate the integrated loudness (steps 3–6).

3. The integrated loudness measurement considers the audio signal since the last reset of your loudness meter. To calculate integrated loudness, the momentary power is passed through a gating system. The gate system pauses the measurement during periods of low sound, such as stretches of silence in a movie.

   The momentary power segment is gated using the corresponding momentary loudness segment calculation:

   $$m{P}_i\to m{P}_j$$

   $$j=\left\{i|m{L}_i\ge -70\right\}$$

   mP_j is cached until your loudnessMeter is reset.

4. The momentary power subset, mP_j, passes through a relative threshold gate.

   

   1. The relative threshold, Γ, is computed:

      $$\Gamma =-0.691+10{\log }_{10}\left({\displaystyle \sum _{c=1}^n{G}_c}\times l_c\right)-10$$

      l_c is the mean momentary power of channel c:

      $$l_c=\frac{1}{\left|j\right|}{\displaystyle \sum _j^{}m{P}_{\left(j,c\right)}}$$

   2. The momentary power subset, mP_j, is gated using relative threshold Γ:

      $$m{P}_j\to m{P}_k$$

      $$k=\left\{j|m{P}_j\ge \Gamma \right\}$$

   The relative threshold is recomputed during each call to your loudnessMeter object. The cached values of mP_j are gated again depending on the updated value of Γ.

5. The momentary power segments are averaged:

   $$P=\frac{1}{\left|k\right|}{\displaystyle \sum _{k}m{P}_k}$$

6. The integrated loudness is computed in LUFS by passing the mean momentary power, P, through the Compute Loudness system:

   $$\text{Integrated}\text{Loudness}=-0.691+10{\log }_{10}\left({\displaystyle \sum _{c=1}^n{G}_c\times P_c}\right)$$

Short-Term Loudness and Loudness Range

1. The K-weighted channels, y, are divided into 3-second segments with 2.9-second overlap. If the required number of samples have not been collected yet, the loudnessMeter System object returns the last computed values for short-term loudness and loudness range. If enough samples have been collected, then the power (mean square) of each K-weighted channel is calculated:

   $$s{P}_i=\frac{1}{w}{\displaystyle \sum _{k=1}^w{y}_i^2[k]}$$

   • sP_i is the short-term power of the ith segment of a channel.

   • w is the segment length in samples.

2. The short-term loudness, sL, is computed in LUFS for each segment:

   $$s{L}_i=-0.691+10{\log }_{10}\left({\displaystyle \sum _{c=1}^n{G}_c\times s{P}_{\left(i,c\right)}}\right)$$

   • G_c is the weighting for channel c.

   sL is the short-term loudness returned by your loudnessMeter System object. It is also used internally to calculate the loudness range (steps 3–5).

3. The short-term loudness is gated using an absolute threshold:

   $$s{L}_i\to s{L}_j$$

   $$j=\left\{i|s{L}_i\ge -70\right\}$$

   sL_j is cached until your loudnessMeter is reset.

4. The short-term loudness subset, sL_j passes through a relative threshold gate.

   

   1. The gated short-term loudness is converted back to linear and then the mean is taken:

      $$s{P}_j=\frac{1}{\left|j\right|}{\displaystyle \sum _j{10}^{\left(\raisebox{1ex}{$s{L}_j$}\!\left/ \!\raisebox{-1ex}{$10$}\right.\right)}}$$

      The relative threshold, K, is computed:

      $$K=-20+10{\log }_{10}\left(s{P}_j\right)$$

   2. The short-term loudness subset, sL_j, is gated using the relative threshold:

      $$s{L}_j\to s{L}_k$$

      $$k=\left\{j|s{L}_j\ge K\right\}$$

   The relative threshold, K, is recomputed during each call to your loudnessMeter object. The cached values of sL_j are gated again depending on the updated value of K.

5. The short-term loudness subset, sL_k, is sorted. The loudness range is calculated as between the 10th and 95th percentiles of the distribution and is returned in loudness units (LU).

True-Peak

The true-peak measurement considers only the current input frame of a call to your loudness meter.

1. The signal is oversampled to at least 192 kHz. To optimize processing, the input sample rate determines the exact oversampling. The algorithm does not consider an input sample rate below 750 Hz.

   Input Sample Rate (kHz)	Upsample Factor
   [0.75, 1.5)	256
   [1.5, 3)	128
   [3, 6)	64
   [6,12)	32
   [12, 24)	16
   [24, 48)	8
   [48, 96)	4
   [96,192)	2
   [192, ∞)	Not required

2. The oversampled signal a passes through a lowpass filter with a half-polyphase length of 12 and stopband attenuation of 80 dB. The filter design uses designMultirateFIR.

3. The filtered signal b is rectified and converted to the dB TP scale:

   $$c=20\times {\log }_{10}\left(\left|b\right|\right)$$

4. The true-peak is determined as the maximum of the converted signal c.

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

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

System Objects in MATLAB Code Generation (MATLAB Coder)

Supports MATLAB Function block: No

Dynamic Memory Allocation must not be turned off.

Version History

Introduced in R2016b