自定义音频采集和渲染
adjustCustomAudioPlayoutVolume
调节自定义音频采集轨道在本地播放的音量。
- (int)adjustCustomAudioPlayoutVolume:(NSInteger)trackId volume:(NSInteger)volume NS_SWIFT_NAME(adjustCustomAudioPlayoutVolume(_:volume:));
详情
调用该方法设置音频在本地播放的音量后,如果你想重新调整音量,你可以再次调用该方法。
参数
- trackId
- 音频轨道 ID。将该参数设置为调用 createCustomAudioTrack 方法返回的自定义音频轨道 ID。
- volume
- 自定义采集音频的播放音量,取值范围为 [0,100]。0 表示静音,100 表示原始音量。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
adjustCustomAudioPublishVolume
调节自定义音频采集轨道在远端播放的音量。
- (int)adjustCustomAudioPublishVolume:(NSInteger)trackId volume:(NSInteger)volume NS_SWIFT_NAME(adjustCustomAudioPublishVolume(_:volume:));
详情
调用该方法设置音频在远端播放的音量后,如果你想重新调整音量,你可以再次调用该方法。
参数
- trackId
- 音频轨道 ID。将该参数设置为调用 createCustomAudioTrack 方法返回的自定义音频轨道 ID。
- volume
- 自定义采集音频的播放音量,取值范围为 [0,100]。0 表示静音,100 表示原始音量。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
createCustomAudioTrack
创建一个自定义音频采集轨道。
- (int)createCustomAudioTrack:(AgoraAudioTrackType)trackType
config:(AgoraAudioTrackConfig* _Nonnull)config;
详情
- 调用该方法创建音频轨道并获得音频轨道 ID。
- 调用 joinChannelByToken [2/4] 加入频道时,将 AgoraRtcChannelMediaOptions 中的 publishCustomAudioTrackId 设置为你想要发布的音频轨道 ID,并将 publishCustomAudioTrack 设置为
YES
。 - 调用 pushExternalAudioFrameRawData 将 trackId 指定为步骤 2 中指定的音频轨道 ID,即可实现在频道内发布对应的自定义音频源。
参数
- trackType
- 自定义音频轨道类型。详见 AgoraAudioTrackType。注意如指定 AgoraAudioTrackTypeDirect,则必须在调用 joinChannelByToken [2/4] 加入频道时,将 AgoraRtcChannelMediaOptions 中的
publishMicrophoneTrack
设为NO
,否则加入频道失败并返回错误码 -2. - config
- 自定义音频轨道配置。详见 AgoraAudioTrackConfig。
返回值
- 方法调用成功,返回音频轨道 ID 作为该音频轨道的唯一标识。
- 方法调用失败,返回负值。
destroyCustomAudioTrack
销毁指定的音频轨道。
- (int)destroyCustomAudioTrack:(NSInteger)trackId;
详情
参数
- trackId
- 调用 createCustomAudioTrack 方法返回的自定义音频轨道 ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
enableCustomAudioLocalPlayback
设置是否在本地播放外部音频源。
- (int)enableCustomAudioLocalPlayback:(NSInteger)trackId enabled:(BOOL)enabled NS_SWIFT_NAME(enableCustomAudioLocalPlayback(_:enabled:));
详情
调用该方法设置在本地播放外部采集的音频源后,如需停止本地播放,可以再次调用该方法并设置 enabled 为 NO
。
你可以调用 adjustCustomAudioPlayoutVolume 调节自定义音频采集轨道在本地播放的音量。
参数
- trackId
- 音频轨道 ID。将该参数设置为调用 createCustomAudioTrack 方法返回的自定义音频轨道 ID。
- enabled
- 是否在本地播放外部音频源:
YES
:在本地播放。NO
:(默认)不在本地播放。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setExternalAudioSource [1/2]
设置外部音频采集参数。
- (int)setExternalAudioSource:(BOOL)enabled
sampleRate:(NSInteger)sampleRate
channels:(NSInteger)channels;
详情
请在 joinChannelByToken [1/4] 和 startPreview [1/2] 前调用该方法。
参数
- enabled
YES
: 开启使用外部音频源的功能。NO
: (默认)关闭使用外部音频源的功能。
- sampleRate
- 外部音频源的采样率 (Hz),可设置为 8000,16000,32000,44100 或 48000。
- channels
- 外部音频源的通道数,可设置为 1 或 2:
- 1: 单声道
- 2: 双声道
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
setExternalAudioSource [2/2]
设置外部音频采集参数。
- (int)setExternalAudioSource:(BOOL)enabled
sampleRate:(NSInteger)sampleRate
channels:(NSInteger)channels
localPlayback:(BOOL)localPlayback
publish:(BOOL)publish;
详情
参数
- enabled
- 是否开启使用外部音频源的功能:
YES
:开启外部音频源。NO
:(默认)关闭外部音频源。
- sampleRate
- 外部音频源的采样率 (Hz),可设置为
8000
,16000
,32000
,44100
或48000
。 - channels
- 外部音频源的声道数,可设置为
1
(单声道)或2
(双声道)。 - localPlayback
- 是否在本地播放外部音频源:
YES
:在本地播放。NO
:(默认)不在本地播放。
- publish
- 是否将音频发布到远端:
YES
:(默认)发布到远端。NO
:不发布到远端。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
pullPlaybackAudioFrameRawData
拉取远端音频数据。
- (BOOL)pullPlaybackAudioFrameRawData:(void * _Nonnull)data
lengthInByte:(NSUInteger)lengthInByte;
详情
使用该方法前,你需要调用 enableExternalAudioSink(enabled: YES)
通知 App 开启并设置外部渲染。
调用该方法后,App 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。
- 该方法需要在加入频道后调用。
- 该方法和 onPlaybackAudioFrame 回调均可用于获取远端混音后的音频数据。需要注意的是:在调用 enableExternalAudioSink 开启外部音频渲染后,App 将无法从 onPlaybackAudioFrame 回调中获得数据,因此,请根据实际的业务需求在该方法和 onPlaybackAudioFrame 回调之间进行选择。二者的处理机制不同,具体区别如下:
- 调用该方法后 App 会主动拉取音频数据。通过设置音频数据,SDK 可以调整缓存,帮助 App 处理延时,从而有效避免音频播放抖动。
- SDK 通过 onPlaybackAudioFrame 回调将音频数据传输给 App。如果 App 处理延时,可能会导致音频播放抖动。
- 该方法仅用于拉取远端混音后的音频数据,如需获取采集、播放等不同音频处理阶段的音频数据,可以通过调用 setAudioFrameDelegate 注册相应的回调。
参数
- data
- 待拉取的远端音频数据,数据类型为
byte[]
。 - lengthInByte
- 音频数据长度,单位为字节。该参数的值由音频数据时长、enableExternalAudioSink 的
sampleRate
和channels
参数确定。lengthInByte
=sampleRate
/1000 × 2 ×channels
× 音频数据时长 (ms)。
返回值
YES
:方法调用成功。NO
:方法调用失败。详见错误码了解详情和解决建议。
pullPlaybackAudioFrameSampleBufferByLengthInByte
拉取 SampleBuffer 格式的远端音频数据。
- (CMSampleBufferRef _Nullable)pullPlaybackAudioFrameSampleBufferByLengthInByte:(NSUInteger)lengthInByte;
详情
使用该方法前,你需要调用 enableExternalAudioSink(enabled: YES)
通知 App 开启并设置外部渲染。
调用该方法后,App 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。
- 该方法需要在加入频道后调用。
- 该方法和 onPlaybackAudioFrame 回调均可用于获取远端混音后的音频数据。需要注意的是:在调用 enableExternalAudioSink 开启外部音频渲染后,App 将无法从 onPlaybackAudioFrame 回调中获得数据,因此,请根据实际的业务需求在该方法和 onPlaybackAudioFrame 回调之间进行选择。二者的处理机制不同,具体区别如下:
- 调用该方法后 App 会主动拉取音频数据。通过设置音频数据,SDK 可以调整缓存,帮助 App 处理延时,从而有效避免音频播放抖动。
- SDK 通过 onPlaybackAudioFrame 回调将音频数据传输给 App。如果 App 处理延时,可能会导致音频播放抖动。
- 该方法仅用于拉取远端混音后的音频数据,如需获取采集、播放等不同音频处理阶段的音频数据,可以通过调用 setAudioFrameDelegate 注册相应的回调。
参数
- lengthInByte
- 音频数据长度,单位为字节。该参数的值由音频数据时长、enableExternalAudioSink 的
sampleRate
和channels
参数确定。lengthInByte
=sampleRate
/1000 × 2 ×channels
× 音频数据时长 (ms)。
返回值
YES
:方法调用成功。NO
:方法调用失败。详见错误码了解详情和解决建议。
pushExternalAudioFrameRawData
推送外部音频数据。
- (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:));
详情
- 调用 createCustomAudioTrack 创建音频轨道并获得音频轨道 ID。
- 调用 joinChannelByToken [2/4] 加入频道时,将 AgoraRtcChannelMediaOptions 中的 publishCustomAudioTrackId 设置为你想要发布的音频轨道 ID,并将 publishCustomAudioTrack 设置为
YES
。
参数
- data
- 外部音频数据。
- samples
- 外部音频帧采样数。
- timestamp
- 外部音频帧的时间戳(毫秒)。该参数为必填。你可以使用该时间戳还原音频帧顺序;在有视频的场景中(包含使用外部视频源的场景),该参数可以帮助实现音视频同步。
- sampleRate
- 外部音频渲染的采样率 (Hz),可设置为 8000,16000,32000,44100 或 48000。
- channels
- 外部音频渲染的声道数:
- 1: 单声道
- 2: 双声道
- trackId
- 音频轨道 ID。将该参数设置为 createCustomAudioTrack 方法中返回的自定义音频轨道 ID。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
pushExternalAudioFrameSampleBuffer [1/2]
推送外部 CMSampleBuffer 音频帧。
- (int)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer;
详情
参数
- sampleBuffer
- 采样缓冲区。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
pushExternalAudioFrameSampleBuffer [2/2]
将外部 CMSampleBuffer 音频帧通过自定义音频轨道推送到频道中。
- (int)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer
sampleRate:(NSInteger)sampleRate
channels:(NSInteger)channels
trackId:(NSInteger)trackId NS_SWIFT_NAME(pushExternalAudioFrameSampleBuffer(_:sampleRate:channels:trackId:));
详情
- 调用 createCustomAudioTrack 创建音频轨道并获得音频轨道 ID。
- 调用 joinChannelByToken [2/4] 加入频道时,将 AgoraRtcChannelMediaOptions 中的 publishCustomAudioTrackId 设置为你想要发布的音频轨道 ID,并将 publishCustomAudioTrack 设置为
YES
。
参数
- sampleBuffer
- 采样缓冲区。
- sampleRate
- 外部音频渲染的采样率 (Hz),可设置为 8000,16000,32000,44100 或 48000。
- channels
- 外部音频渲染的声道数:
- 1: 单声道
- 2: 双声道
- trackId
- 音频轨道 ID。将该参数设置为 createCustomAudioTrack 方法中返回的自定义音频轨道 ID。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
enableExternalAudioSink
设置外部音频渲染。
- (void)enableExternalAudioSink:(BOOL)enabled
sampleRate:(NSUInteger)sampleRate
channels:(NSUInteger)channels;
详情
该方法适用于需要自行渲染音频的场景。开启外部音频渲染后,你可以调用 pullPlaybackAudioFrameRawData 拉取远端音频数据。App 可以对拉取到的原始音频数据进行处理后再渲染,获取想要的音频效果。
参数
- enabled
- 设置是否开启外部音频渲染:
YES
:开启外部音频渲染。NO
:(默认)关闭外部音频渲染。
- sampleRate
外部音频渲染的采样率 (Hz),可设置为 16000,32000,44100 或 48000。
- channels
- 外部音频渲染的声道数:
- 1: 单声道
- 2: 双声道