自定义音频采集和渲染

createCustomAudioTrack

创建一个自定义音频采集轨道。

Objective-C

- (int)createCustomAudioTrack:(AgoraAudioTrackType)trackType
                       config:(AgoraAudioTrackConfig* _Nonnull)config;

自从

v4.2.0

如需在频道中发布多路自定义采集音频，可参考以下步骤：

• 调用该方法创建音频轨道并获得音频轨道 ID。

• 在每个频道的 AgoraRtcChannelMediaOptions 中，将 publishCustomAudioTrackId 参数设置为你想要发布的音频轨道 ID，并将 publishCustomAudioTrack 设置为 YES。

• 调用 pushExternalAudioFrameRawData 将 trackId 指定为步骤 2 中指定的音频轨道 ID，即可实现在多个频道中发布对应的自定义音频源。

参数

参数名	描述
trackType	自定义音频轨道类型。详见 AgoraAudioTrackType。 注意： 如指定 AgoraAudioTrackTypeDirect，则必须在调用 joinChannelByToken [2/4] 加入频道时，将 AgoraRtcChannelMediaOptions 中的 publishMicrophoneTrack 设为 NO，否则加入频道失败并返回错误码 -2.
config	自定义音频轨道配置。详见 AgoraAudioTrackConfig。

返回值

• 方法调用成功，返回音频轨道 ID 作为该音频轨道的唯一标识。

• 方法调用失败，返回负值。

所属接口类

• AgoraRtcEngineKit

destroyCustomAudioTrack

销毁指定的音频轨道。

Objective-C

- (int)destroyCustomAudioTrack:(NSInteger)trackId;

自从

v4.2.0

参数

参数名	描述
trackId	调用 createCustomAudioTrack 方法返回的自定义音频轨道 ID。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setExternalAudioSource [1/2]

设置外部音频采集参数。

Objective-C

- (int)setExternalAudioSource:(BOOL)enabled
                   sampleRate:(NSInteger)sampleRate
                     channels:(NSInteger)channels;

弃用

该方法已废弃，请改用 createCustomAudioTrack。

请在 joinChannelByToken [1/4] 和 startPreview [1/2] 前调用该方法。

参数

参数名	描述
enabled	YES: 开启使用外部音频源的功能。 NO: （默认）关闭使用外部音频源的功能。
sampleRate	外部音频源的采样率 (Hz)，可设置为 8000，16000，32000，44100 或 48000。
channels	外部音频源的通道数，可设置为 1 或 2: 1: 单声道 2: 双声道

返回值

• 0：方法调用成功。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setExternalAudioSource [2/2]

设置外部音频采集参数。

Objective-C

- (int)setExternalAudioSource:(BOOL)enabled
                   sampleRate:(NSInteger)sampleRate
                     channels:(NSInteger)channels
                localPlayback:(BOOL)localPlayback
                      publish:(BOOL)publish;

弃用

该方法已废弃，请改用 createCustomAudioTrack。

注意： 请在加入频道前调用该方法。

参数

参数名	描述
enabled	是否开启使用外部音频源的功能： YES：开启外部音频源。 NO：（默认）关闭外部音频源。
sampleRate	外部音频源的采样率 (Hz)，可设置为 8000，16000，32000，44100 或 48000。
channels	外部音频源的声道数，可设置为 1（单声道）或 2（双声道）。
localPlayback	是否在本地播放外部音频源： YES：在本地播放。 NO：（默认）不在本地播放。
publish	是否将音频发布到远端： YES：（默认）发布到远端。 NO：不发布到远端。

返回值

• 0：方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

pullPlaybackAudioFrameRawData

拉取远端音频数据。

Objective-C

- (BOOL)pullPlaybackAudioFrameRawData:(void * _Nonnull)data
                              lengthInByte:(NSUInteger)lengthInByte;

使用该方法前，你需要调用 enableExternalAudioSink 通知 app 开启并设置外部渲染。

调用该方法后，app 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。

注意：

• 该方法仅支持拉取自采集的数据。如果你需要拉取 SDK 采集的数据，请不要调用该方法。

• 该方法需要在加入频道后调用。

• 开启外部音频渲染后，app 将无法从 onPlaybackAudioFrame 回调中获得数据。

• 该方法和 onPlaybackAudioFrame 回调相比，区别在于：

  • SDK 通过 onPlaybackAudioFrame 回调将音频数据传输给 app。如果 app 处理延时，可能会导致音频播放抖动。

  • 调用该方法后 app 会主动拉取音频数据。通过设置音频数据，SDK 可以调整缓存，帮助 app 处理延时，从而有效避免音频播放抖动。

参数

参数名	描述
data	待拉取的远端音频数据，数据类型为 byte[]。
lengthInByte	音频数据长度，单位为字节。该参数的值由音频数据时长、enableExternalAudioSink 的 sampleRate 和 channels 参数确定。lengthInByte = sampleRate/1000 × 2 × channels × 音频数据时长 (ms)。

返回值

• YES：方法调用成功。

• NO：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

pullPlaybackAudioFrameSampleBufferByLengthInByte

拉取 SampleBuffer 格式的远端音频数据。

Objective-C

- (CMSampleBufferRef _Nullable)pullPlaybackAudioFrameSampleBufferByLengthInByte:(NSUInteger)lengthInByte;

使用该方法前，你需要调用 enableExternalAudioSink 通知 app 开启并设置外部渲染。

调用该方法后，app 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。

注意：

• 该方法仅支持拉取自采集的数据。如果你需要拉取 SDK 采集的数据，请不要调用该方法。

• 该方法需要在加入频道后调用。

• 开启外部音频渲染后，app 将无法从 onPlaybackAudioFrame 回调中获得数据。

• 该方法和 onPlaybackAudioFrame 回调相比，区别在于：

  • SDK 通过 onPlaybackAudioFrame 回调将音频数据传输给 app。如果 app 处理延时，可能会导致音频播放抖动。

  • 调用该方法后 app 会主动拉取音频数据。通过设置音频数据，SDK 可以调整缓存，帮助 app 处理延时，从而有效避免音频播放抖动。

参数

参数名	描述
lengthInByte	音频数据长度，单位为字节。该参数的值由音频数据时长、enableExternalAudioSink 的 sampleRate 和 channels 参数确定。lengthInByte = sampleRate/1000 × 2 × channels × 音频数据时长 (ms)。

返回值

• YES：方法调用成功。

• NO：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

pushExternalAudioFrameRawData

推送外部音频数据。

Objective-C

- (int)pushExternalAudioFrameRawData:(void* _Nonnull)data
                             samples:(NSInteger)samples
                          sampleRate:(NSInteger)sampleRate
                            channels:(NSInteger)channels
                            trackId:(NSInteger)trackId
                           timestamp:(NSTimeInterval)timestamp NS_SWIFT_NAME(pushExternalAudioFrameRawData(_:samples:sampleRate:channels:trackId:timestamp:));

注意：
调用该方法前，请将 AgoraRtcChannelMediaOptions 中的 publishCustomAudioTrackId 参数设置为你想要发布的音频轨道 ID，并将 publishCustomAudioTrack 设为 YES。

参数

参数名	描述
data	外部音频数据。
samples	外部音频帧采样数。
timestamp	外部音频帧的时间戳（毫秒）。该参数为必填。你可以使用该时间戳还原音频帧顺序；在有视频的场景中（包含使用外部视频源的场景），该参数可以帮助实现音视频同步。
sampleRate	外部音频渲染的采样率 (Hz)，可设置为 8000，16000，32000，44100 或 48000。
channels	外部音频渲染的声道数: 1: 单声道 2: 双声道
trackId	音频轨道 ID。将该参数设置为 createCustomAudioTrack 方法中返回的自定义音频轨道 ID。

返回值

• 0：方法调用成功。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

pushExternalAudioFrameSampleBuffer

推送外部 CMSampleBuffer 音频帧。

Objective-C

- (int)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer;

参数

参数名	描述
sampleBuffer	采样缓冲区。

返回值

• 0：方法调用成功。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

enableExternalAudioSink

设置外部音频渲染。

Objective-C

- (void)enableExternalAudioSink:(BOOL)enabled
                     sampleRate:(NSUInteger)sampleRate
                       channels:(NSUInteger)channels;

该方法适用于需要自行渲染音频的场景。开启外部音频渲染后，你可以调用 pullPlaybackAudioFrameRawData 拉取远端音频数据。App 可以对拉取到的原始音频数据进行处理后再渲染，获取想要的音频效果。

参数

参数名	描述
enabled	设置是否开启外部音频渲染： YES：开启外部音频渲染。 NO：（默认）关闭外部音频渲染。
sampleRate	外部音频渲染的采样率 (Hz)，可设置为 16000，32000，44100 或 48000。
channels	外部音频渲染的声道数: 1: 单声道 2: 双声道

返回值

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit