自定义音频采集和渲染

声网默认的音频模块可以满足在 App 中使用基本音频功能的需求。声网 SDK 支持使用自定义的音频源和自定义的音频渲染模块为你的 App 添加特殊的音频功能。

技术原理

实时音频传输过程中，声网 SDK 通常会开启默认的音频模块。在以下场景中，你可能会发现默认的音频模块无法满足开发需求，需要自定义音频采集或自定义音频渲染。例如：

• App 中已有自己的音频模块。
• 需要使用前处理库处理采集到的音频。
• 某些音频采集设备被系统独占。为避免与其他业务产生冲突，需要灵活的设备管理策略。

使用自定义音频源管理音频帧的采集、处理和播放时，需要使用声网 SDK 外部方法。

音频数据传输

下图展示在自定义音频采集、音频渲染时，音频数据的传输过程。

自定义音频采集

• 你需要使用 SDK 外部方法自行实现采集模块。
• 调用 pushExternalAudioFrameSampleBuffer 或 pushExternalAudioFrameRawData，将采集到的音频帧发送给 SDK。

自定义音频渲染

• 你需要使用 SDK 外部方法自行实现渲染模块。
• 调用 pullPlaybackAudioFrame 获取远端用户发送的音频数据。

前提条件

在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见实现音视频互动。

实现方法

自定义音频采集

本节介绍如何实现自定义音频采集。

参考以下调用时序图，在你的 App 中实现自定义音频采集：

API 调用步骤

参考如下步骤，在你的项目中实现自定义音频采集功能：

1. 创建自定义音频轨道

   初始化 AgoraRtcEngineKit 后，调用 createCustomAudioTrack 创建自定义音频轨道并获得音频轨道 ID。

   Swift

   let audioTrack = AgoraAudioTrackConfig()
   audioTrack.enableLocalPlayback = true
   trackId = agoraKit.createCustomAudioTrack(.mixable, config: audioTrack)

2. 加入频道并发布自定义音频轨道

   调用 joinChannelByToken[2/4] 加入频道，在 AgoraRtcChannelMediaOptions 中，将 publishCustomAudioTrackId 参数设置为步骤 1 中获得的音频轨道 ID，并将 publishCustomAudioTrack 设置为 YES，即可在频道中发布指定的自定义音频轨道。

   注意

   如需调用 enableCustomAudioLocalPlayback 在本地播放外部音频源，或调用 adjustCustomAudioPlayoutVolume 调节自定义音频采集轨道在本地播放的音量，请将 AgoraRtcChannelMediaOptions 中的 enableAudioRecordingOrPlayout 设置为 YES。

   Swift

   let option = AgoraRtcChannelMediaOptions()
   // 音频自采集场景下，不发布麦克风采集的音频
   option.publishMicrophoneTrack = false;
   // 发布自采集音频流
   option.publishCustomAudioTrack = true
   // 设置自定义音频轨道 ID
   option.publishCustomAudioTrackId = Int(trackId)
   option.clientRoleType = GlobalSettings.shared.getUserRole()
   NetworkManager.shared.generateToken(channelName: channelName, success: { token in
       // 加入频道
       let result = self.agoraKit.joinChannel(byToken: token, channelId: channelName, uid: 0, mediaOptions: option)
       if result != 0 {
           self.showAlert(title: "Error", message: "joinChannel call failed: \(result), please check your params")
       }
   })

3. 实现自采集模块

   声网提供了 CustomPcmAudioSource.swift 示例项目，演示从本地文件读取 PCM 格式的音频数据。在实际项目中，你需要结合业务创建自定义音频采集模块。

4. 通过自定义音频轨道推送音频数据到 SDK

   调用 pushExternalAudioFrameRawData 将采集到的音频帧通过自定义音频轨道推送至 SDK。其中，trackId 要与步骤 2 加入频道时指定的音频轨道 ID 一致，sampleRate、channels 和 samples 用于设置外部音频帧的采样率、声道数和采样数。

   信息

   • 为确保音视频同步，声网建议你调用getCurrentMonotonicTimeInMs 获取当前的 Monotonic Time，将 timestamp（时间戳）设置为系统 Monotonic Time。
   • 如果需要推送 CMSampleBuffer 格式的音频帧，请改用 pushExternalAudioFrameSampleBuffer。
   Swift

   extension CustomAudioSource: AgoraPcmSourcePushDelegate {
       func onAudioFrame(data: UnsafeMutablePointer<UInt8>) {
           agoraKit.pushExternalAudioFrameRawData(data,
                                                  samples: samples,
                                                  sampleRate: Int(sampleRate),
                                                  channels: Int(audioChannel),
                                                  trackId: Int(trackId),
                                                  timestamp: 0)
       }
   }

5. 销毁自定义音频轨道

   如果你需要停止发布自定义采集的音频，调用 destroyCustomAudioTrack 销毁自定义音频轨道。

   Swift

   agoraKit.destroyCustomAudioTrack(Int(trackId))

自定义音频渲染

本节介绍如何实现自定义音频渲染。

开始前，请确保你的项目中已实现原始音频数据的采集和处理。详见原始音频数据。

参考如下步骤，在你的项目中调用原始音频数据 API 实现自定义音频渲染：

1. 从 onRecordAudioFrame，onPlaybackAudioFrame，onMixedAudioFrame 或 onPlaybackAudioFrameBeforeMixing 获取待播放的音频数据。
2. 自行渲染并播放音频数据。

参考信息

示例项目

声网提供了开源的音频自采集和音频自渲染的示例项目供你参考，你可以前往下载或查看其中的源代码。

CustomPcmAudioSource

CustomPcmAudioSource

CustomAudioRender

CustomAudioRender

API 参考

• createCustomAudioTrack
• destroyCustomAudioTrack
• pushExternalAudioFrameRawData
• pushExternalAudioFrameSampleBuffer [2/2]
• enableExternalAudioSink
• pullPlaybackAudioFrameRawData