文档中心
超低延迟直播
音频能力
音频频谱与音量变化

音量变化与音频频谱

更新时间：2024-01-31 17:18

功能简介

概念	描述	应用场景	场景图
音量变化	指某条流的音量大小，下文简称为“声浪”。	在推拉流过程中，判断麦上的用户谁在说话，并做 UI 展示。
音频频谱	指数字音频信号在各频点的能量值。	在主播 K 歌场景中，已经推流或拉流的前提下，让主播或观众看到音调与音量变化的动画。

示例源码下载

请参考下载示例源码获取源码。

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

前提条件

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

已在 ZEGO 控制台创建项目，并申请有效的 AppID 和 AppSign，详情请参考控制台 - 项目信息。
已在项目中集成 ZEGO Express SDK，并实现了基本的音视频推拉流功能，详情请参考快速开始 - 集成和快速开始 - 实现流程。

非混流场景使用步骤

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

接口原型

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

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

}

远端音频声浪回调接口 onRemoteSoundLevelUpdate：

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

}

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

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

}

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

/**
 * 远端拉流音频频谱回调
 *
 * 回调通知周期为 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 控件上
    }
}

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

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

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

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

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

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

混流场景使用步骤

混流，是将多路流混合成一路流的功能。当客户需要展示混流前各条流的声浪信息时，即可使用混流声浪的功能。由于混流的输出是单流，使用混流输出流的声浪信息是无法满足展示各条输入流声浪的需求。此时需要在混流时，在流信息里携带输入流的声浪信息，然后在拉取混流输出流时，从流信息里解析出各条输入流的声浪信息。
当从流信息里解析出各条输入流的声浪信息时，我们获得的是各条输入流对应声浪的值，就是一个字典。字典里面的 key 是流的标识符，value 是声浪值。但是由于流信息的大小限制，key 不能使用流 ID，只能用一个数字 ID（soundLevelID）来标识流。
在手动混流配置中，需要开发者维护数字 ID（soundLevelID）和流 ID 的关联关系。在回调中，开发者会得到数字 ID（soundLevelID）和对应声浪信息。
在房间自动混流中，混流服务端和 SDK 会自动处理数字 ID 和流 ID 的关联。在回调中，开发者得到的是流 ID 对应声浪信息。

1 监听混流声浪的回调接口

接口原型

手动混流中每条单流的声浪更新回调接口 onMixerSoundLevelUpdate：

/**
 * 混流中每条单流的声浪更新回调
 *
 * 回调通知周期为 100 ms。
 * @param soundLevel 混流中每条单流的声浪键值对，key 为每条单流的 soundLevelID，value 为对应的单流的声浪值。取值范围：value 的取值范围为 0.0 ~ 100.0。
 */
public void onMixerSoundLevelUpdate(HashMap<Integer, Float> soundLevels){

}

自动混流中每条单流的声浪更新回调接口 onAutoMixerSoundLevelUpdate：

/**
 * 自动混流中每条单流的声浪更新回调
 *
 * 回调通知周期为 100 ms。
 * @param soundLevels 混流中每条单流的声浪键值对，key 为每条单流的 streamID，value 为对应的单流的声浪值，value 的取值范围为 0.0 ~ 100.0
 */
public void onAutoMixerSoundLevelUpdate(HashMap<String, Float> soundLevels){

}

2 启动监听声浪回调的开关

在开始/更新混流时，可启动监听声浪回调的开关。

手动混流场景

调用 startMixerTask 接口发起一个手动混流任务时，设置 soundLevel 参数为 True 可启动声浪的监听，并为每条输入流指定设置唯一的 soundLevelID：

ZegoMixerTask task = new ZegoMixerTask();
task.taskID = "task123";
// 开启混流声浪
task.soundLevel = true;

ZegoMixerInput input = new ZegoMixerInput();
// 给输入流分配一个 soundLevelID
input.soundLevelID = 123;

// 其他配置

mSDKEnging.startMixerTask(task, null);

自动混流场景

调用 startAutoMixerTask 接口发起一个自动混流任务时，设置 enableSoundLevel 参数为 True 可启动声浪的监听：

ZegoAutoMixerTask task = new ZegoAutoMixerTask();
task.taskID = "autotask123";
// 开启混流声浪
task.enableSoundLevel = true;
// 其他配置

mSDKEnging.startAutoMixerTask(task, null);

3 停止监听声浪回调的开关

在更新混流任务时，可设置停止监听声浪回调的开关。