Volume Change and Audio Spectrum

2026-03-05

Feature Overview

Warning

This document is not applicable to the Web platform.

Concept	Description	Application Scenarios	Scenario Diagram
Volume Change	Refers to the volume level of a stream, hereafter referred to as "Sound Level".	During stream publishing and playing, determine which user on the microphone is speaking and display it in the UI.
Audio Spectrum	Refers to the energy value of digital audio signals at various frequency points.	In karaoke scenarios, after publishing or playing streams, allow the host or audience to see animations of pitch and volume changes.

Example Source Code Download

Please refer to Download Example Source Code to get the source code.

For related source code, please view files in the "lib/topics/AudioAdvanced/soundlevel_spectrum" directory.

Prerequisites

Before implementing Sound Level and Audio Spectrum features, ensure that:

You have integrated ZEGO Express SDK into your project and implemented basic real-time audio/video functionality. For details, please refer to Quick Start - Integration and Quick Start - Implementation.
You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to ZEGOCLOUD Console - Project Information.

Usage Steps for Non-Mixing Scenarios

1 Listen for Sound Level and Audio Spectrum Callback Interfaces

Interface Prototypes

Local captured sound level callback interface onCapturedSoundLevelUpdate :

class ZegoExpressEngine {

...

/**
 * Local captured audio sound level callback
 *
 * Callback notification period is 100 ms.
 * @param soundLevel Local captured sound level value, ranging from 0.0 to 100.0
 */
static void Function(double soundLevel)? onCapturedSoundLevelUpdate;

...

}

class ZegoExpressEngine {

...

/**
 * Local captured audio sound level callback
 *
 * Callback notification period is 100 ms.
 * @param soundLevel Local captured sound level value, ranging from 0.0 to 100.0
 */
static void Function(double soundLevel)? onCapturedSoundLevelUpdate;

...

}

Remote audio sound level callback interface onRemoteSoundLevelUpdate :

class ZegoExpressEngine {

...

/**
 * Remote played stream audio sound level callback
 *
 * Callback notification period is 100 ms.
 * @param soundLevels Key-value pairs of remote sound levels, key is stream ID, value is the corresponding stream's sound level value, value ranges from 0.0 to 100.0
 */
static void Function(Map<String, double> soundLevels)? onRemoteSoundLevelUpdate;

...

}

class ZegoExpressEngine {

...

/**
 * Remote played stream audio sound level callback
 *
 * Callback notification period is 100 ms.
 * @param soundLevels Key-value pairs of remote sound levels, key is stream ID, value is the corresponding stream's sound level value, value ranges from 0.0 to 100.0
 */
static void Function(Map<String, double> soundLevels)? onRemoteSoundLevelUpdate;

...

}

Local captured audio spectrum callback interface onCapturedAudioSpectrumUpdate :

class ZegoExpressEngine {

...

/**
 * Local captured audio spectrum callback
 *
 * Callback notification period is 100 ms.
 * @param audioSpectrum Array of local captured audio spectrum values, spectrum values range from [0-2^30]
 */
static void Function(List<double> audioSpectrum)? onCapturedAudioSpectrumUpdate;

...

}

class ZegoExpressEngine {

...

/**
 * Local captured audio spectrum callback
 *
 * Callback notification period is 100 ms.
 * @param audioSpectrum Array of local captured audio spectrum values, spectrum values range from [0-2^30]
 */
static void Function(List<double> audioSpectrum)? onCapturedAudioSpectrumUpdate;

...

}

Remote played stream audio spectrum callback interface onRemoteAudioSpectrumUpdate :

class ZegoExpressEngine {

...

/**
 * Remote played stream audio spectrum callback
 *
 * Callback notification period is 100 ms.
 * @param audioSpectrums Key-value pairs of remote audio spectrums, key is stream ID, value is the corresponding stream's audio spectrum value array, spectrum values range from [0-2^30]
 */
static void Function(Map<String, List<double>> audioSpectrums)? onRemoteAudioSpectrumUpdate;

...

}

class ZegoExpressEngine {

...

/**
 * Remote played stream audio spectrum callback
 *
 * Callback notification period is 100 ms.
 * @param audioSpectrums Key-value pairs of remote audio spectrums, key is stream ID, value is the corresponding stream's audio spectrum value array, spectrum values range from [0-2^30]
 */
static void Function(Map<String, List<double>> audioSpectrums)? onRemoteAudioSpectrumUpdate;

...

}

Usage Examples

The callbacks for remote played stream sound levels and remote audio spectrums provide a Map, where key is the stream ID of other users currently publishing in the room, and value is the sound level/audio spectrum data corresponding to that stream.

You can first use the onRoomStreamUpdate callback method to get the list of existing streams in the current room and save it, then use the saved stream list to index the Map to obtain the sound level/audio spectrum data for each stream.

The following example demonstrates how to get sound level/audio spectrum data from callback methods and pass it to the UI. For specific context, please refer to files in the "lib/topics/AudioAdvanced/soundlevel_spectrum" directory in the example source code.

ZegoExpressEngine.onCapturedSoundLevelUpdate = (double soundLevel) {
        // Developers can render the local sound level data to specific UI controls here
}
ZegoExpressEngine.onRemoteSoundLevelUpdate = (Map<String, double> soundLevels) {
        // Developers can render the remote sound level data to specific UI controls here
}
ZegoExpressEngine.onCapturedAudioSpectrumUpdate = (List<double> audioSpectrum) {
        // Developers can render the local audio spectrum data to specific UI controls here
}
ZegoExpressEngine.onRemoteAudioSpectrumUpdate = (Map<String, List<double>> audioSpectrums) {
        // Developers can render the remote audio spectrum data to specific UI controls here
}

ZegoExpressEngine.onCapturedSoundLevelUpdate = (double soundLevel) {
        // Developers can render the local sound level data to specific UI controls here
}
ZegoExpressEngine.onRemoteSoundLevelUpdate = (Map<String, double> soundLevels) {
        // Developers can render the remote sound level data to specific UI controls here
}
ZegoExpressEngine.onCapturedAudioSpectrumUpdate = (List<double> audioSpectrum) {
        // Developers can render the local audio spectrum data to specific UI controls here
}
ZegoExpressEngine.onRemoteAudioSpectrumUpdate = (Map<String, List<double>> audioSpectrums) {
        // Developers can render the remote audio spectrum data to specific UI controls here
}

2 Start Monitoring Sound Level and Audio Spectrum Callbacks

You can separately enable monitoring for sound level and audio spectrum callbacks.

Call startSoundLevelMonitor to start sound level monitoring:

// Start sound level monitoring
ZegoExpressEngine.instance.startSoundLevelMonitor();

// Start sound level monitoring
ZegoExpressEngine.instance.startSoundLevelMonitor();

When calling the startSoundLevelMonitor interface, you can set the millisecond parameter to adjust the sound level callback interval.

// millisecond: Sound level monitoring period in milliseconds, range [100, 3000]. Default is 100 ms.
ZegoExpressEngine.instance.startSoundLevelMonitor({millisecond: 100});

// millisecond: Sound level monitoring period in milliseconds, range [100, 3000]. Default is 100 ms.
ZegoExpressEngine.instance.startSoundLevelMonitor({millisecond: 100});

After calling the above interface, onCapturedSoundLevelUpdate will trigger immediately, with a callback value of 0 when not publishing and not previewing; onRemoteSoundLevelUpdate will only callback after starting to play streams with startPlayingStream .

Call startAudioSpectrumMonitor to start audio spectrum monitoring:
```
// Start audio spectrum monitoring
ZegoExpressEngine.instance.startAudioSpectrumMonitor();
```
```
// Start audio spectrum monitoring
ZegoExpressEngine.instance.startAudioSpectrumMonitor();
```
After calling the above interface, onCapturedAudioSpectrumUpdate will trigger immediately, with a callback value of 0 when not publishing and not previewing; onRemoteAudioSpectrumUpdate will only callback after starting to play streams with startPlayingStream .

3 Stop Monitoring Audio Spectrum and Sound Level Callbacks

You can separately disable monitoring for sound level or audio spectrum callbacks.

Call stopSoundLevelMonitor to stop sound level monitoring:
```
// Stop sound level monitoring
ZegoExpressEngine.instance.stopSoundLevelMonitor();
```
```
// Stop sound level monitoring
ZegoExpressEngine.instance.stopSoundLevelMonitor();
```
After calling the above interface, onCapturedSoundLevelUpdate and onRemoteSoundLevelUpdate will no longer callback.
Call stopAudioSpectrumMonitor to stop audio spectrum monitoring:
```
// Stop audio spectrum monitoring
ZegoExpressEngine.instance.stopAudioSpectrumMonitor();
```
```
// Stop audio spectrum monitoring
ZegoExpressEngine.instance.stopAudioSpectrumMonitor();
```
After calling the above interface, onCapturedAudioSpectrumUpdate and onRemoteAudioSpectrumUpdate will no longer callback.

Usage Steps for Mixing Scenarios

Mixing refers to the feature of mixing multiple streams into one stream. When customers need to display sound level information of each stream before mixing, they can use the mixing sound level feature. Since the output of mixing is a single stream, using the sound level information of the mixed output stream cannot meet the need to display sound levels of each input stream. At this time, during mixing, the sound level information of input streams needs to be carried in the stream information, and then when playing the mixed output stream, the sound level information of each input stream can be parsed from the stream information.
When parsing the sound level information of each input stream from the stream information, we get the values corresponding to the sound levels of each input stream, which is a dictionary. The key in the dictionary is the stream identifier, and value is the sound level value. However, due to the size limit of stream information, key cannot use stream ID and can only use a numeric ID (soundLevelID) to identify the stream.
In manual mixing configuration, developers need to maintain the association between numeric IDs (soundLevelID) and stream IDs. In callbacks, developers will get numeric IDs (soundLevelID) and corresponding sound level information.
In room auto-mixing, the mixing server and SDK automatically handle the association between numeric IDs and stream IDs. In callbacks, developers get stream IDs corresponding to sound level information.

1 Listen for Mixing Sound Level Callback Interfaces

Interface Prototypes

Sound level update callback interface for each single stream in manual mixing onMixerSoundLevelUpdate:

class ZegoExpressEngine {

...

/**
 * Manual mixing audio spectrum callback
 *
 * Callback notification period is 100 ms.
 * @param soundLevels Key-value pairs of remote audio spectrums, key is soundLevelID, value is the corresponding stream's audio spectrum value array, spectrum values range from [0.0 ~ 100.0]
 */
static void Function(Map<int, double> soundLevels)? onMixerSoundLevelUpdate;

...

}

class ZegoExpressEngine {

...

/**
 * Manual mixing audio spectrum callback
 *
 * Callback notification period is 100 ms.
 * @param soundLevels Key-value pairs of remote audio spectrums, key is soundLevelID, value is the corresponding stream's audio spectrum value array, spectrum values range from [0.0 ~ 100.0]
 */
static void Function(Map<int, double> soundLevels)? onMixerSoundLevelUpdate;

...

}

Sound level update callback interface for each single stream in automatic mixing onAutoMixerSoundLevelUpdate:

class ZegoExpressEngine {

...

/**
 * Automatic mixing audio spectrum callback
 *
 * Callback notification period is 100 ms.
 * @param soundLevels Key-value pairs of remote audio spectrums, key is stream ID, value is the corresponding stream's audio spectrum value array, spectrum values range from [0.0 ~ 100.0]
 */
static void Function(Map<String, double> soundLevels)? onAutoMixerSoundLevelUpdate;

...

}

class ZegoExpressEngine {

...

/**
 * Automatic mixing audio spectrum callback
 *
 * Callback notification period is 100 ms.
 * @param soundLevels Key-value pairs of remote audio spectrums, key is stream ID, value is the corresponding stream's audio spectrum value array, spectrum values range from [0.0 ~ 100.0]
 */
static void Function(Map<String, double> soundLevels)? onAutoMixerSoundLevelUpdate;

...

}

2 Start Monitoring Sound Level Callbacks

When starting/updating mixing, you can enable sound level callback monitoring.

Manual Mixing Scenario

When calling the startMixerTask interface to initiate a manual mixing task, set the enableSoundLevel parameter to true to start sound level monitoring, and specify a unique soundLevelID for each input stream:

ZegoMixerTask task = ZegoMixerTask("task123");

// Enable mixing sound level
task.enableSoundLevel = true;

ZegoMixerInput input = ZegoMixerInput.defaultConfig();
// Assign a soundLevelID to the input stream
input.soundLevelID = 123;

// Other configurations

ZegoExpressEngine.instance.startMixerTask(task);

ZegoMixerTask task = ZegoMixerTask("task123");

// Enable mixing sound level
task.enableSoundLevel = true;

ZegoMixerInput input = ZegoMixerInput.defaultConfig();
// Assign a soundLevelID to the input stream
input.soundLevelID = 123;

// Other configurations

ZegoExpressEngine.instance.startMixerTask(task);

Automatic Mixing Scenario

When calling the startAutoMixerTask interface to initiate an automatic mixing task, set the enableSoundLevel parameter to true to start sound level monitoring:

var task = ZegoAutoMixerTask();
task.roomID = "room123";
task.taskID = "autotask123";

// Enable mixing sound level
task.enableSoundLevel = true;
// Other configurations

ZegoExpressEngine.instance.startAutoMixerTask(task);

var task = ZegoAutoMixerTask();
task.roomID = "room123";
task.taskID = "autotask123";

// Enable mixing sound level
task.enableSoundLevel = true;
// Other configurations

ZegoExpressEngine.instance.startAutoMixerTask(task);

3 Stop Monitoring Sound Level Callbacks

When updating a mixing task, you can disable sound level callback monitoring.