实时音视频
  • iOS : Objective-C
  • Android
  • macOS
  • Windows
  • HarmonyOS
  • Linux
  • Web
  • 小程序
  • Flutter
  • Electron
  • Unity3D
  • uni-app
  • React Native
  • Cocos Creator
  • 产品简介
  • 下载
  • 体验 App
  • 快速开始
    • 跑通示例源码
    • 集成 SDK
    • 实现视频通话
    • 实时音视频 SDK 与实时语音 SDK 差异
    • 场景化音视频配置
  • 基础功能
  • 进阶功能
  • 最佳实践
  • 常见错误码
  • 服务端 API
  • 客户端 API
  • 常见问题

音频频谱与音量变化

更新时间:2022-10-27 16:49

1 功能简介

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

    主要应用场景,在推拉流过程中,判断麦上的用户谁在说话,并做 UI 展示,例如:

  • 音频频谱:即数字音频信号在各频点的能量值。

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

2 示例源码下载

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

相关源码请查看 “/ZegoExpressExample/Examples/AdvancedAudioProcessing/SoundLevel” 目录下的文件。

3 前提条件

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

4 使用步骤

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

  • 接口原型

    • 本地采集的声浪回调接口:

      /// 本地采集音频声浪回调
      ///
      /// @param soundLevel 本地采集的声浪值,取值范围为 0.0 ~ 100.0
      - (void)onCapturedSoundLevelUpdate:(NSNumber *)soundLevel;
      
      /// 本地采集音频声浪回调
      ///
      /// @note 想要触发这个回调,必须调用 [startSoundLevelMonitor] 函数启动声浪监控器。
      /// @note 回调通知周期为调用 [startSoundLevelMonitor] 时设置的参数值。
      ///
      /// @param soundLevelInfo 本地采集的声浪值,取值范围为 0.0 ~ 100.0        
      - (void)onCapturedSoundLevelInfoUpdate:(ZegoSoundLevelInfo *)soundLevelInfo;
    • 远端音频声浪回调接口:

      /// 远端音频声浪回调
      ///
      /// @param soundLevels 远端的声浪键值对,key 为流 ID,value 为对应的流的声浪值,value 取值范围为 0.0 ~ 100.0
      - (void)onRemoteSoundLevelUpdate:(NSDictionary<NSString *, NSNumber *> *)soundLevels;
      
      /// 远端拉流音频声浪回调
      ///
      /// @note 想要触发这个回调,必须调用 [startSoundLevelMonitor] 函数启动声浪监控器,且处于正在拉流的状态。
      /// @note 回调通知周期为调用 [startSoundLevelMonitor] 时设置的参数值。
      ///
      /// @param soundLevelInfos 远端的声浪键值对,key 为流 ID,value 为对应的流的声浪值,value 取值范围为 0.0 ~ 100.0
      - (void)onRemoteSoundLevelInfoUpdate:(NSDictionary<NSString *, ZegoSoundLevelInfo *> *)soundLevelInfos;
      
    • 本地采集的音频频谱回调接口:

      /// 本地采集音频频谱回调
      ///
      /// @param audioSpectrum 本地采集的音频频谱值数组,频谱值范围为 [0-2^30]
      - (void)onCapturedAudioSpectrumUpdate:(NSArray<NSNumber *> *)audioSpectrum;
      -
    • 远端拉流音频频谱回调接口:

      /// 远端拉流音频频谱回调
      ///
      /// @param audioSpectrums 远端音频频谱键值对,key 是流 ID,value 为对应的流的音频频谱值数组,频谱值范围为 [0-2^30]
      - (void)onRemoteAudioSpectrumUpdate:(NSDictionary<NSString *, NSArray<NSNumber *> *> *)audioSpectrums;
  • 调用示例

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

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

    以下示例将演示如何从回调方法中获取到声浪/音频频谱的数据并传递给 UI。具体上下文请参考示例源码中 “/ZegoExpressExample-iOS-OC/Topics/SoundLevel” 目录下的文件。

    // Sound level callback for local stream
    - (void)onCapturedSoundLevelUpdate:(NSNumber *)soundLevel {
        ZGSoundLevelTableViewCell *cell = [self.tableView cellForRowAtIndexPath:[NSIndexPath indexPathForRow:0 inSection:0]];
        cell.soundLevel = soundLevel;
    }
    
    // Sound level callback for local stream
    - (void)onCapturedSoundLevelInfoUpdate:(ZegoSoundLevelInfo *)soundLevelInfo {
        ZGSoundLevelTableViewCell *cell = [self.tableView cellForRowAtIndexPath:[NSIndexPath indexPathForRow:0 inSection:0]];
        cell.soundLevelInfo = soundLevelInfo;
    }
    
    // Sound level callback for remote streams, key is stream ID, value is the sound level data corresponding to stream ID
    - (void)onRemoteSoundLevelUpdate:(NSDictionary<NSString *,NSNumber *> *)soundLevels {
        NSInteger rowCount = [self.tableView numberOfRowsInSection:1];
        for (NSInteger row = 0; row < rowCount; row++) {
            ZGSoundLevelTableViewCell *cell = [self.tableView cellForRowAtIndexPath:[NSIndexPath indexPathForRow:row inSection:1]];
            if ([soundLevels objectForKey:cell.streamID]) {
                cell.soundLevel = soundLevels[cell.streamID];
            }
        }
    }
    
    // Sound level callback for remote streams, key is stream ID, value is the sound level data corresponding to stream ID
    - (void)onRemoteSoundLevelInfoUpdate:(NSDictionary<NSString *, ZegoSoundLevelInfo *> *)soundLevelInfos {
        NSInteger rowCount = [self.tableView numberOfRowsInSection:1];
        for (NSInteger row = 0; row < rowCount; row++) {
            ZGSoundLevelTableViewCell *cell = [self.tableView cellForRowAtIndexPath:[NSIndexPath indexPathForRow:row inSection:1]];
            if ([soundLevelInfos objectForKey:cell.streamID]) {
                cell. soundLevelInfos = soundLevelInfos[cell.streamID];
            }
        }
    }
    
    // Audio frequency spectrum callback for local stream
    - (void)onCapturedAudioSpectrumUpdate:(NSArray<NSNumber *> *)audioSpectrum {
        ZGSoundLevelTableViewCell *cell = [self.tableView cellForRowAtIndexPath:[NSIndexPath indexPathForRow:0 inSection:0]];
        cell.spectrumList = audioSpectrum;
    }
    
    // Audio frequency spectrum callback for remote streams, key is stream ID, value is the spectrum data corresponding to stream ID
    - (void)onRemoteAudioSpectrumUpdate:(NSDictionary<NSString *,NSArray<NSNumber *> *> *)audioSpectrums {
        NSInteger rowCount = [self.tableView numberOfRowsInSection:1];
        for (NSInteger row = 0; row < rowCount; row++) {
            ZGSoundLevelTableViewCell *cell = [self.tableView cellForRowAtIndexPath:[NSIndexPath indexPathForRow:row inSection:1]];
            if ([audioSpectrums objectForKey:cell.streamID]) {
                cell.spectrumList = audioSpectrums[cell.streamID];
            }
        }
    }

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

可分别针对音频频谱或声浪,调用启动监听对应回调的接口。

  • 启动声浪的监听:

    /// 启动声浪监控
    ///
    - (void)startSoundLevelMonitor;
    
    /// 启动声浪监控,支持开启进阶功能
    ///
    /// @note 启动监控后可通过 [onCapturedSoundLevelUpdate] 回调接收本地采集音频声浪回调,以及 [onRemoteSoundLevelUpdate] 回调接收远端拉流音频声浪回调。
    /// @note 开发者可在进入房间之前,调用 [startPreview] 与此函数,并与 [onCapturedSoundLevelUpdate] 结合来判断音频设备是否正常工作。
    /// @note [onCapturedSoundLevelUpdate] 与 [onRemoteSoundLevelUpdate] 回调通知周期为参数设置的值。
    ///
    /// @param config 启动声浪监控的配置
    - (void)startSoundLevelMonitorWithConfig:(ZegoSoundLevelConfig *)config;

    在调用上述接口之后,onCapturedSoundLevelUpdate 回调方法会立刻触发,未推流且未预览时回调值为 0;onRemoteSoundLevelUpdate 需要在调用 startPlayingStream 开始拉流接口之后,才会有回调。

  • 启动频谱的监听:

    /// 启动音频频谱监控
    ///
    - (void)startAudioSpectrumMonitor;

    在调用上述接口之后,onCapturedAudioSpectrumUpdate 回调方法会立刻触发,未推流且未预览时回调值为 0;onRemoteAudioSpectrumUpdate 需要在调用 startPlayingStream 开始拉流接口之后,才会有回调。

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

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

5 API 参考列表

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

6 常见问题

  1. 开启了声浪和频谱的监控开关之后,为什么没有收到相关回调?

    本地采集的回调会立刻触发,未推流时的回调值为 0;远端拉流的回调在拉流startPlayingStream 成功之后才会触发。

相关文档