Main Content

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

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

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.

For more information on changing property values, see System Design in MATLAB Using System Objects.

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

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

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

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

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

Description

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

example

Input Arguments

expand all

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

expand all

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)

expand all

visualizeVisualize audio levels in audio meter display
cloneCreate duplicate System object
isLockedDetermine if System object is in use
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

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

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

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

lvlMeter = audioLevelMeter;
visualize(lvlMeter)

Figure Audio Meter contains an object of type uiaudiometer.

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

Figure Audio Meter contains an object of type uiaudiometer.

Algorithms

expand all

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