自定义音频采集和渲染

adjustCustomAudioPlayoutVolume:volume:

调节本地播放的自定义音频轨道的音量。

Objective-C

- (int)adjustCustomAudioPlayoutVolume:(NSInteger)trackId volume:(NSInteger)volume NS_SWIFT_NAME(adjustCustomAudioPlayoutVolume(_:volume:));

如果你想更改本地播放的音频音量，需要再次调用该方法。

信息

请确保在调用该方法前已调用 createCustomAudioTrack:config: 创建自定义音频轨道。

参数

trackId

音频轨道 ID。请设置为 createCustomAudioTrack:config: 返回的自定义音频轨道 ID。

volume

音频源的音量。取值范围为 0 到 100。

• 0：静音。
• 100：原始音量。

返回值

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

所属接口类

• AgoraRtcEngineKit

adjustCustomAudioPublishVolume:volume:

调节远端播放的自定义音频轨道的音量。

Objective-C

- (int)adjustCustomAudioPublishVolume:(NSInteger)trackId volume:(NSInteger)volume NS_SWIFT_NAME(adjustCustomAudioPublishVolume(_:volume:));

如果你想更改远端播放的音频音量，需要再次调用此方法。

信息

请确保在调用此方法前已调用 createCustomAudioTrack:config: 方法创建自定义音频轨道。

参数

trackId

音频轨道 ID。请设置为 createCustomAudioTrack:config: 方法返回的自定义音频轨道 ID。

volume

音频源的音量。取值范围为 0 到 100。

• 0：静音。
• 100：原始音量。

返回值

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

所属接口类

• AgoraRtcEngineKit

createCustomAudioTrack:config:

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

Objective-C

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

要发布自定义音频源，请按照以下步骤操作：

1. 调用该方法创建一个自定义音频轨道并获取音频轨道 ID。
2. 调用 joinChannelByToken 加入频道。在 AgoraRtcChannelMediaOptions 中，将 publishCustomAudioTrackId 设置为你想要发布的音频轨道 ID，并将 publishCustomAudioTrack 设置为 YES。
3. 调用 pushExternalAudioFrameRawData，并将 trackId 设置为第 2 步中设置的音频轨道 ID，即可在频道中发布相应的自定义音频源。

信息

请在加入频道前调用此方法。

参数

trackType

自定义音频轨道的类型，详见 AgoraAudioTrackType。

• 如果该参数设置为 AgoraAudioTrackTypeDirect，你必须在调用 joinChannelByToken 加入频道时，将 AgoraRtcChannelMediaOptions 中的 publishMicrophoneTrack 设置为 NO，否则加入频道会失败并返回错误码 -2。

config

自定义音频轨道的配置，详见 AgoraAudioTrackConfig。

返回值

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

所属接口类

• AgoraRtcEngineKit

destroyCustomAudioTrack:

销毁指定的音频轨道。

Objective-C

- (int)destroyCustomAudioTrack:(NSInteger)trackId;

参数

trackId

调用 createCustomAudioTrack:config: 时返回的自定义音频轨道 ID。

返回值

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

所属接口类

• AgoraRtcEngineKit

enableCustomAudioLocalPlayback:enabled:

设置是否启用外部音频源的本地播放。

Objective-C

- (int)enableCustomAudioLocalPlayback:(NSInteger)trackId enabled:(BOOL)enabled NS_SWIFT_NAME(enableCustomAudioLocalPlayback(_:enabled:));

调用该方法启用外部音频源的本地播放后，如需停止本地播放，可再次调用该方法并将 enabled 设置为 NO。你可以调用 adjustCustomAudioPlayoutVolume:volume: 方法调整自定义音频轨道的本地播放音量。

信息

请确保在调用该方法前已通过 createCustomAudioTrack:config: 方法创建自定义音频轨道。

参数

trackId

音频轨道 ID。该参数需设置为 createCustomAudioTrack:config: 方法返回的自定义音频轨道 ID。

enabled

是否播放外部音频源：

• YES：播放外部音频源。
• NO：（默认）不播放外部音频源。

返回值

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

所属接口类

• AgoraRtcEngineKit

pullPlaybackAudioFrameRawData:lengthInByte:

拉取远端音频数据。

Objective-C

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

调用该方法成功后，你可以拉取解码并混音后的远端音频数据用于播放。调用该方法前，请先调用 enableExternalAudioSink:sampleRate:channels:（enabled: YES）以开启并设置外部音频渲染。

信息

pullPlaybackAudioFrameRawData:lengthInByte: 方法和 onPlaybackAudioFrame: 回调都可用于获取远端混音后的音频数据。调用 enableExternalAudioSink:sampleRate:channels: 开启外部音频渲染后，将无法再通过 onPlaybackAudioFrame: 回调获取数据。请根据实际业务需求选择使用该方法或 onPlaybackAudioFrame: 回调。两者的具体区别如下：

• 调用 pullPlaybackAudioFrameRawData:lengthInByte: 方法后，你会自动从 SDK 拉取音频数据。通过设置音频数据参数，SDK 会调整帧缓冲区以帮助你处理延迟，有效避免音频播放卡顿。
• 注册 onPlaybackAudioFrame: 回调后，SDK 会通过回调将音频数据发送给你。若处理音频帧存在延迟，可能会导致音频卡顿。

该方法仅用于获取远端混音后的音频数据。如需获取采集、播放等其他音频处理阶段的数据，可通过调用 setAudioFrameDelegate: 注册相应的回调。

调用时机

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

参数

data

输出参数，要拉取的远端音频数据。数据类型为 byte[]。

lengthInByte

数据长度（字节）。该参数的值与音频时长，以及在 enableExternalAudioSink:sampleRate:channels: 中设置的 sampleRate 和 channels 参数有关。lengthInByte = sampleRate / 1000 × 2 × channels × 音频时长（毫秒）。

返回值

• YES：调用成功。
• NO：调用失败。

所属接口类

• AgoraRtcEngineKit

pullPlaybackAudioFrameSampleBufferByLengthInByte:

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

Objective-C

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

调用该方法后，你可以拉取解码并混音后的音频数据用于播放。

参数

lengthInByte

数据长度（字节）。该参数的值与你设置的音频时长、sampleRate 和 channels 参数有关。lengthInByte = sampleRate / 1000 × 2 × channels × 音频时长（毫秒）。

返回值

方法调用成功，返回 CMSampleBufferRef 对象；失败时返回 nil。

所属接口类

• AgoraRtcEngineKit

pushExternalAudioFrameRawData:samples:sampleRate:channels:trackId:timestamp:

将外部音频帧推送到 SDK。

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:));

你可以调用该方法通过音频轨道向 SDK 推送外部音频帧。 调用该方法前，请先完成以下操作：

1. 调用 createCustomAudioTrack 创建自定义音频轨道，并获取音频轨道 ID。
2. 调用 joinChannelByToken 加入频道。在 AgoraRtcChannelMediaOptions 中，将 publishCustomAudioTrackId 设置为要发布的音频轨道 ID，并将 publishCustomAudioTrack 设置为 YES。

参数

data

外部音频数据。

samples

采样点数量。

sampleRate

外部音频源的采样率（Hz），可设置为 8000、16000、32000、44100 或 48000。

channels

外部音频源的声道数，可设置为 1（单声道）或 2（立体声）。

trackId

音频轨道 ID，需设置为调用 createCustomAudioTrack 返回的自定义音频轨道 ID。

timestamp

外部音频帧的时间戳（毫秒）。该参数为必填项，可用于还原采集音频帧的顺序，或在涉及视频的场景中（包括使用自定义视频源的场景）实现音视频同步。

返回值

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

所属接口类

• AgoraRtcEngineKit

pushExternalAudioFrameSampleBuffer:

推送外部 CMSampleBuffer 音频帧。

Objective-C

- (int)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer NS_SWIFT_NAME(pushExternalAudioFrameSampleBuffer(_:)) __deprecated_msg("use pushExternalAudioFrameSampleBuffer:sampleRate:channels:trackId: instead.");

废弃

该方法已废弃，请改用 pushExternalAudioFrameSampleBuffer:sampleRate:channels:trackId:。

参数

sampleBuffer

音频帧的 sample buffer，类型为 CMSampleBufferRef。详见 CMSampleBufferRef。

返回值

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

所属接口类

• AgoraRtcEngineKit

pushExternalAudioFrameSampleBuffer:sampleRate:channels:trackId:

通过自定义音频轨道将外部 CMSampleBuffer 音频帧推送到频道中。

Objective-C

- (int)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer
                               sampleRate:(NSInteger)sampleRate
                                 channels:(NSInteger)channels
                                  trackId:(NSInteger)trackId NS_SWIFT_NAME(pushExternalAudioFrameSampleBuffer(_:sampleRate:channels:trackId:));

在调用该方法推送外部音频数据之前，你需要完成以下操作：

1. 调用 createCustomAudioTrack 创建自定义音频轨道，并获取音频轨道 ID。
2. 调用 joinChannelByToken 加入频道。在 AgoraRtcChannelMediaOptions 中，将 publishCustomAudioTrackId 设置为你要发布的音频轨道 ID，并将 publishCustomAudioTrack 设置为 YES。

参数

sampleBuffer

采样缓冲区。详见 CMSampleBufferRef。

sampleRate

外部音频源的采样率（Hz），可设置为 8000、16000、32000、44100 或 48000。

channels

外部音频源的声道数，可设置为 1（单声道）或 2（立体声）。

trackId

音频轨道 ID。你需要将该参数设置为 createCustomAudioTrack 返回的自定义音频轨道 ID。

返回值

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

所属接口类

• AgoraRtcEngineKit

enableExternalAudioSink:sampleRate:channels:

设置外部音频渲染。

Objective-C

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

启用外部音频渲染后，你可以调用 pullPlaybackAudioFrameRawData:lengthInByte: 方法拉取远端音频帧，应用程序可以处理远端音频，并使用期望的音效进行播放。

信息

启用外部音频渲染后，应用程序将无法从 onPlaybackAudioFrame: 回调中获取任何音频数据。

适用场景

适用于需要使用外部音频数据进行播放的场景。

调用时机

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

参数

enabled

是否启用外部音频渲染：

• YES：启用外部音频渲染。
• NO：（默认）不启用外部音频渲染。

sampleRate

外部音频渲染的采样率（Hz），可设置为 16000、32000、44100 或 48000。

channels

外部音频渲染的声道数：

• 1：单声道。
• 2：双声道。

所属接口类

• AgoraRtcEngineKit

setExternalAudioSource:sampleRate:channels:

设置外部音频源。

Objective-C

- (int)setExternalAudioSource:(BOOL)enabled
                   sampleRate:(NSInteger)sampleRate
                     channels:(NSInteger)channels NS_SWIFT_NAME(setExternalAudioSource(_:sampleRate:channels:)) __deprecated_msg("use createCustomAudioTrack:config: instead.");

废弃

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

在调用 joinChannelByToken 和 startPreview 之前调用该方法。

参数

enabled

• YES：启用外部音频源。
• NO：（默认）禁用外部音频源。

sampleRate

外部音频源的采样率（Hz），可设置为 8000、16000、32000、44100 或 48000。

channels

外部音频源的声道数：

• 1：单声道。
• 2：立体声。

返回值

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

所属接口类

• AgoraRtcEngineKit

setExternalAudioSource:sampleRate:channels:localPlayback:publish:

设置外部音频源参数。

Objective-C

- (int)setExternalAudioSource:(BOOL)enabled
                   sampleRate:(NSInteger)sampleRate
                     channels:(NSInteger)channels
                localPlayback:(BOOL)localPlayback
                      publish:(BOOL)publish NS_SWIFT_NAME(setExternalAudioSource(_:sampleRate:channels:localPlayback:publish:)) __deprecated_msg("use createCustomAudioTrack:config: instead.");

废弃

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

调用时机

请你在加入频道前调用该方法。

参数

enabled

是否启用外部音频源：

• YES：启用外部音频源。
• NO：（默认）不启用外部音频源。

sampleRate

外部音频源的采样率（Hz），可设置为 8000、16000、32000、44100 或 48000。

channels

外部音频源的声道数，可设置为 1（单声道）或 2（立体声）。

localPlayback

是否播放外部音频源：

• YES：播放外部音频源。
• NO：（默认）不播放外部音频源。

publish

是否向远端用户发布音频：

• YES：（默认）发布音频到远端用户。
• NO：不发布音频到远端用户。

返回值

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

所属接口类

• AgoraRtcEngineKit