audioLevelMeter

Measure digital audio peak level

Since R2023a

Description

The audioLevelMeter System object™ measures the digital peak level of an audio signal. You can use audioLevelMeter to identify and prevent audio clipping during recording and playback.

To measure the peak level:

1. Create the audioLevelMeter 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

lvlMeter = audioLevelMeter

lvlMeter = audioLevelMeter(Name=Value)

Description

lvlMeter = audioLevelMeter creates an audio level meter System object with default property values.

lvlMeter = audioLevelMeter(Name=Value) sets Properties using one or more name-value arguments.

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.

Method — Measurement method

"sample-peak" (default) | "true-peak"

Measurement method to compute the peak levels, specified as "sample-peak" or "true-peak". The true-peak measurement method follows the ITU-R BS.1770-4 standards [2]. For more information about these methods, see Algorithms.

Data Types: char | string

WindowLength — Window length

1024 (default) | positive integer

Window length, specified as a positive integer. The window length defines the size of the nonoverlapping frames in the input signal over which the object computes each peak level.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

DecayRate — Decay rate of peak values (dB/s)

11.76 (default) | nonnegative scalar

Decay rate of the peak values in dB/s, specified as a nonnegative scalar. For more information about the decay, see Decay.

A decay rate of Inf means the object does not apply the decay.

Tunable: Yes

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Units — Output units

"dBFS" | "dBTP"

This property is read-only.

Output units of the measured peak values, returned as "dBFS" or "dBTP". The units are "dBFS" if you set Method to "sample-peak", and "dBTP" if you set Method to "true-peak".

Data Types: string

SampleRate — Sample rate of input signal (Hz)

44100 (default) | finite positive scalar

Sample rate of input signal in Hz, specified as a finite positive scalar.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Usage

Syntax

peakLevel = lvlMeter(audioIn)

Description

peakLevel = lvlMeter(audioIn) computes the peak levels over nonoverlapping frames in the input signal.

Input Arguments

audioIn — Audio input signal

column vector | matrix

Audio input signal, specified as a column vector or matrix. If the input is a matrix, the object treats the columns as independent channels

Output Arguments

peakLevel — Peak level

matrix

Peak level of each frame in the input signal, returned as an L-by-C matrix, where C is the number of channels and L is determined by the WindowLength property and the length of audioIn.

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 audioLevelMeter

visualize	Visualize audio levels in audio meter display
clone	Create duplicate System object
isLocked	Determine if System object is in use

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Examples

Measure Sample-Peak Level of Audio Signal

Create a dsp.AudioFileReader to stream an audio file for processing. Create an audioDeviceWriter to play the audio as you stream it.

reader = dsp.AudioFileReader("FunkyDrums-44p1-stereo-25secs.mp3");
player = audioDeviceWriter(SampleRate=reader.SampleRate);

Create an audioLevelMeter object. Specify the SampleRate and WindowLength to match the file reader object.

lvlMeter = audioLevelMeter(SampleRate=reader.SampleRate, ...
    WindowLength=reader.SamplesPerFrame);

Create a timescope object to plot both the audio signal and the measured peak level.

scope = timescope(SampleRate=reader.SampleRate,LayoutDimensions=[2,1], ...
    TimeSpanSource="property",TimeSpan=5);
scope.Title = "Audio Waveform";
scope.YLabel = "Amplitude";
scope.YLimits = [-1.25, 1.25];

scope.ActiveDisplay = 2;
scope.Title = "Peak Level";
scope.YLabel = lvlMeter.Units;
scope.YLimits = [-40, 6];
scope.ChannelNames = ["Channel 1", "Channel 2", "Channel 1", "Channel 2"];

In a streaming loop:

1. Read in a frame of audio data.

2. Compute the sample-peak level of the frame.

3. Plot the signal and the peak level.

4. Play the audio with the device writer.

while ~isDone(reader)
    audioIn = reader();
    peakLevel = lvlMeter(audioIn);
    peakLevelHold = peakLevel.*ones(size(audioIn));
    scope(audioIn,peakLevelHold);
    player(audioIn);
end

Measure True-Peak Level of Audio Signal

Create a dsp.AudioFileReader to stream an audio file for processing. Create an audioDeviceWriter to play the audio as you stream it.

reader = dsp.AudioFileReader("FunkyDrums-44p1-stereo-25secs.mp3");
player = audioDeviceWriter(SampleRate=reader.SampleRate);

Create an audioLevelMeter object. Set the Method property to "true-peak" to use the true-peak measurement method according to the ITU-R BS.1770-4 standards. Specify the SampleRate and WindowLength to match the file reader object.

lvlMeter = audioLevelMeter(Method="true-peak",SampleRate=reader.SampleRate, ...
    WindowLength=reader.SamplesPerFrame);

Create a timescope object to plot both the audio signal and the measured peak level.

scope = timescope(SampleRate=reader.SampleRate,LayoutDimensions=[2,1], ...
    TimeSpanSource="property",TimeSpan=5);
scope.Title = "Audio Waveform";
scope.YLabel = "Amplitude";
scope.YLimits = [-1.25, 1.25];

scope.ActiveDisplay = 2;
scope.Title = "Peak Level";
scope.YLabel = lvlMeter.Units;
scope.YLimits = [-40, 6];
scope.ChannelNames = ["Channel 1", "Channel 2", "Channel 1", "Channel 2"];

In a streaming loop:

1. Read in a frame of audio data.

2. Compute the true-peak level of the frame.

3. Plot the signal and the peak level.

4. Play the audio with the device writer.

while ~isDone(reader)
    audioIn = reader();
    peakLevel = lvlMeter(audioIn);
    peakLevelHold = peakLevel.*ones(size(audioIn));
    scope(audioIn,peakLevelHold);
    player(audioIn);
end

Visualize Audio Peak Levels

Create an audioLevelMeter object and call visualize to open an audio meter display.

lvlMeter = audioLevelMeter;
visualize(lvlMeter)

Create an audio file reader and a device writer to stream audio from a file and play it on your device.

reader = dsp.AudioFileReader("FunkyDrums-44p1-stereo-25secs.mp3");
player = audioDeviceWriter(SampleRate=reader.SampleRate);

In an audio stream loop, read the audio from the file and play it to your device. The audio meter visualization updates at each call.

while ~isDone(reader)
    audioIn = reader();
    lvlMeter(audioIn);
    player(audioIn);
end

Algorithms

Sample-Peak Measurement

The sample-peak level of an audio frame is simply the maximum of the sample values converted to decibels.

max(20*log10(abs(audioFrame)))

True-Peak Measurement

Use the true-peak level to accurately measure peaks that can occur between samples in the reconstructed analog version of the digital audio signal.

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.

Decay

For both measurement methods, the audioLevelMeter object applies a linear decay to the peak level in the dB scale to prevent a steep dropoff. It applies the delay before it takes the maximum peak level from each frame.

The default decay rate of 11.76 dB/s satisfies the IEC TR 60268-18:1995 standard [1], which specifies 1.7 (+/- 0.3) seconds for the return time of a 20-dB fall in the peak value.

References

[1] IEC TR 60268-18:1995. "Sound system equipment - Part 18: Peak programme level meters - Digital audio peak level meter." International Electrotechnical Commission.

[2] ITU-R BS.1770-4. "Algorithms to measure audio programme loudness and true-peak audio level." International Telecommunication Union, Radiocommunication Sector.

Version History

Introduced in R2023a