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:
Create the
loudnessMeter
object and set its properties.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(
sets
each property Name,Value
)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 theTargetLoudness
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
Description
[
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,
momentary
,shortTerm
,integrated
,range
,peak
] = loudMtr(audioIn
)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 |
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.
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:mPi is the momentary power of the ith segment.
w is the segment length in samples.
The momentary loudness, mL, is computed in LUFS for each segment:
Gc 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).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:
mPj is cached until your
loudnessMeter
is reset.The momentary power subset, mPj, passes through a relative threshold gate.
The relative threshold, Γ, is computed:
lc is the mean momentary power of channel c:
The momentary power subset, mPj, is gated using relative threshold Γ:
The relative threshold is recomputed during each call to your
loudnessMeter
object. The cached values of mPj are gated again depending on the updated value of Γ.The momentary power segments are averaged:
The integrated loudness is computed in LUFS by passing the mean momentary power, P, through the Compute Loudness system:
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:sPi is the short-term power of the ith segment of a channel.
w is the segment length in samples.
The short-term loudness, sL, is computed in LUFS for each segment:
Gc 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).The short-term loudness is gated using an absolute threshold:
sLj is cached until your
loudnessMeter
is reset.The short-term loudness subset, sLj passes through a relative threshold gate.
The gated short-term loudness is converted back to linear and then the mean is taken:
The relative threshold, K, is computed:
The short-term loudness subset, sLj, is gated using the relative threshold:
The relative threshold, K, is recomputed during each call to your
loudnessMeter
object. The cached values of sLj are gated again depending on the updated value of K.The short-term loudness subset, sLk, 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.
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 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
.The filtered signal b is rectified and converted to the dB TP scale:
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
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)