音频频谱与音量变化

更新时间：2022-07-19 19:53

1 功能简介

音量变化：指某条流的音量大小，下文简称为“声浪”。

主要应用场景，在推拉流过程中，判断麦上的用户谁在说话，并做 UI 展示，例如：
音频频谱：即数字音频信号在各频点的能量值。

主要应用场景，在主播 K 歌场景中，已经推流或拉流的前提下，让主播或观众看到音调与音量变化的动画，例如：

2 示例源码下载

相关源码请查看 “/ZegoExpressExample/AdvancedAudioProcessing/src/main/java/im/zego/advancedaudioprocessing/soundlevelandspectrum” 目录下的文件。

3 前提条件

在实现音频频谱与声浪功能之前，请确保：

已在项目中集成 ZEGO Express SDK，实现基本的实时音视频功能，详情请参考快速开始 - 集成和快速开始 - 实现视频通话。
已在 ZEGO 控制台创建项目，并申请有效的 AppID 和 AppSign，详情请参考控制台 - 项目管理中的“项目信息”。

4 使用步骤

4.1 监听声浪与音频频谱的回调接口

接口原型

本地采集的声浪回调接口：

/**
 * 本地采集音频声浪回调
 *
 * 回调通知周期为 100 ms。
 * @param soundLevel 本地采集的声浪值，取值范围为 0.0 ~ 100.0
 */
public void onCapturedSoundLevelUpdate(double soundLevel){

}

远端音频声浪回调接口：

/**
 * 远端拉流音频声浪回调
 *
 * 回调通知周期为 100 ms。
 * @param soundLevels 远端的声浪键值对，key 为流 ID，value 为对应的流的声浪值，value 取值范围为 0.0 ~ 100.0
 */
public void onRemoteSoundLevelUpdate(HashMap<String, Double> soundLevels){

}

本地采集的音频频谱回调接口：

/**
 * 本地采集音频频谱回调
 *
 * 回调通知周期为 100 ms。
 * @param audioSpectrum 本地采集的音频频谱值数组，频谱值范围为 [0-2^30]
 */
public void onCapturedAudioSpectrumUpdate(float[] audioSpectrum){

}

远端拉流音频频谱回调接口：

/**
 * 远端拉流音频频谱回调
 *
 * 回调通知周期为 100 ms。
 * @param audioSpectrums 远端音频频谱键值对，key 是流 ID，value 为对应的流的音频频谱值数组，频谱值范围为 [0-2^30]
 */
public void onRemoteAudioSpectrumUpdate(HashMap<String, float[]> audioSpectrums){

}

调用示例

远端拉流声浪和远端音频频谱的回调给的是 HashMap，“key” 是当前房间内正在推流的其他用户的流 ID，“value” 是对应这条流的声浪/音频频谱数据。

可先通过 onRoomStreamUpdate 回调方法获取到当前房间内存在的流列表并保存起来，然后通过保存的流列表来索引 HashMap 取得每条流对应的声浪/音频频谱数据。

以下示例将演示如何从回调方法中获取到声浪/音频频谱的数据并传递给 UI，具体渲染到 UI 上的逻辑请参考声浪和频谱模块相关的代码。

class MyEventHandler extends IZegoEventHandler
{
    @override
    public void onCapturedSoundLevelUpdate(double soundLevel) {
        // 开发者可以在这里进行获取本地声浪数据之后渲染到具体的 UI 控件上
    }    
    @override
    public void onRemoteSoundLevelUpdate(HashMap<String, Double> soundLevels) {
        // 开发者可以在这里进行获取远端声浪数据之后渲染到具体的 UI 控件上
    }
    @override
    public void onCapturedAudioSpectrumUpdate(double[] audioSpectrum) {
        // 开发者可以在这里进行获取本地音频频谱数据之后渲染到具体的 UI 控件上
    }
    @override
    public void onRemoteAudioSpectrumUpdate(HashMap<String, double[]> audioSpectrums) {
        // 开发者可以在这里进行获取远端音频频谱数据之后渲染到具体的 UI 控件上
    }
}

4.2 启动监听音频频谱与声浪的回调的开关

可分别针对音频频谱或声浪，调用启动监听对应回调的开关。

启动声浪的监听：
```
// mSDKEnging 为 ZegoExpressEngine 的实例
mSDKEnging.startSoundLevelMonitor();
```
在调用上述接口之后，onCapturedSoundLevelUpdate 会立刻触发，未推流且未预览时回调值为 0；onRemoteSoundLevelUpdate 需要在拉流 startPlayingStream 之后，才会回调。
启动频谱的监听：
```
// mSDKEnging 为 ZegoExpressEngine 的实例
mSDKEnging.startAudioSpectrumMonitor();
```
在调用上述接口之后，onCapturedAudioSpectrumUpdate 会立刻触发，未推流且未预览时回调值为 0；onRemoteAudioSpectrumUpdate 需要在拉流 startPlayingStream 之后，才会回调。

4.3 停止监听音频频谱与声浪的回调的开关

可分别针对音频频谱或声浪，调用停止监听对应回调的开关。

停止声浪的监听：
```
// mSDKEnging 为 ZegoExpressEngine 的实例
mSDKEnging.stopSoundLevelMonitor();
```
在调用上述接口之后，onCapturedSoundLevelUpdate 与 onRemoteSoundLevelUpdate 不再回调。
停止频谱的监听：
```
// mSDKEnging 为 ZegoExpressEngine 的实例
mSDKEnging.stopAudioSpectrumMonitor();
```
在调用上述接口之后，onCapturedAudioSpectrumUpdate 与 onRemoteAudioSpectrumUpdate 不再回调。

5 API 参考列表

方法	描述
startSoundLevelMonitor	启动声浪监控
stopSoundLevelMonitor	停止声浪监控
startAudioSpectrumMonitor	启动音频频谱监控
stopAudioSpectrumMonitor	停止音频频谱监控
onCapturedSoundLevelUpdate	本地采集音频声浪回调
onRemoteSoundLevelUpdate	远端音频声浪回调接口
onCapturedAudioSpectrumUpdate	本地采集频谱回调
onRemoteAudioSpectrumUpdate	远端音频频谱回调接口