Visualize the sound level

Introduction

Sound level refers to the volume of a stream. ZEGOCLOUD’s SDKs provide the ability to capture the sound level of a stream in real time and output the captured sound level data to the app client through related callbacks. A typical use case of this feature is that you can visualize the sound level data on your app UI to indicate the current active speaker and their volume. The following picture shows an example of such use cases.

Prerequisites

Before you begin, make sure you complete the following:

• Create a project in ZEGOCLOUD Admin Console and get the AppID and AppSign of your project.

• Refer to the Quick Start doc to complete the SDK integration and basic function implementation.

Enable sound level callbacks

Call the startSoundLevelMonitor method to enable sound level callbacks when needed.

/**
 * Enable sound level callbacks
 */
ZegoExpressEngine.instance().startSoundLevelMonitor;

After the above step is completed:

• When you start previewing the local video (by calling the startPreview method) or publishing a local stream (by calling the startPublishingStream method), the SDK will trigger the capturedSoundLevelUpdate callback at an interval of 100ms to deliver the sound level data of the locally captured audio.

/**
    * The callback to deliver the sound level data of locally captured audio
    *
    * @param soundLevel: The sound level value of the locally captured audio, which is in the range [0.0, 100.0].
    */
capturedSoundLevelUpdate: (soundLevel: number) => void;

• When you start playing remote streams (by calling the startPlayingStream method), the SDK will trigger the remoteSoundLevelUpdate callback at an interval of 100ms to deliver the sound level data of the remote streams.

/**
    * The callback to deliver the sound level data of remote streams
    *
    * @param soundLevels: The sound level data (key-value pairs) of the remote streams, of which the key is a stream ID, and the value is the sound level value of the corresponding stream. Each sound level value is in the range [0.0, 100.0].
    */
remoteSoundLevelUpdate: (soundLevels: {[key: string]: number}) => void;

Obtain data from the callbacks

The SDK delivers the sound level data of the remote streams as key-value pairs in a map. In each key-value pair, the key is the stream ID of a remote stream published by another user in the same room, and the value is the sound level value of that stream.

You can first obtain and save the list of remote streams published by the other users in the current room through the roomStreamUpdate callback, and then use each stream ID in the list as an index to get the sound level value of that stream from the map.

The following examples show how to obtain the sound level data from the callbacks.

// Listen for the sound level callback for remote streams.
ZegoExpressEngine.instance().on('remoteSoundLevelUpdate', (soundLevels) => {
    // Use the stream ID as the key to get the sound level value from the map soundLevels.
    });

// Listen for the sound level callback for locally captured audio.
ZegoExpressEngine.instance().on('capturedSoundLevelUpdate', (soundLevel) => {
    // Get the sound level values from the parameter soundLevel.
    });

Disable sound level callbacks

Call the stopSoundLevelMonitor method to disable the sound level callbacks when needed.

/**
 * Disable sound level callbacks
 */
ZegoExpressEngine.instance().stopSoundLevelMonitor();

After the above step is completed, the SDK will stop triggering the callbacks capturedSoundLevelUpdate and remoteSoundLevelUpdate.

FAQ

1. Why I receive no sound level callback after I enable them?

   Even after you enable the sound level callbacks, the SDK will only trigger the callbacks when you start related streaming activities. For more details, see Section 3.2 above.