Documentation

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

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

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

Syntax

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

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

```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 = 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.

```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 = 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.

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

Get trial now