音频处理
介绍跟音频处理相关的方法和回调。
adjustAudioMixingPlayoutVolume
调节音乐文件在本地播放的音量。
- (int)adjustAudioMixingPlayoutVolume:(NSInteger)volume;
详情
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
参数
- volume
- 音乐文件音量。取值范围为 [0,100],100 (默认值)为原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingPublishVolume
调节音乐文件远端播放音量。
- (int)adjustAudioMixingPublishVolume:(NSInteger)volume;
详情
该方法调节混音音乐文件在远端的播放音量大小。
你需要在调用 startAudioMixing [2/2] 并收到 audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
参数
- volume
- 音乐文件音量。取值范围为 [0,100],100 (默认值)为原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingVolume
调节音乐文件的播放音量。
- (int)adjustAudioMixingVolume:(NSInteger)volume;
详情
该方法调节混音音乐文件在本端和远端的播放音量大小。
- 该方法需要在 startAudioMixing [2/2] 后调用。
- 调用该方法不影响调用 playEffect [3/3] 播放音效文件的音量。
参数
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
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:方法调用失败。
adjustPlaybackSignalVolume
调节本地播放的所有远端用户信号音量。
- (int)adjustPlaybackSignalVolume:(NSInteger)volume;
详情
- 该方法调节的是本地播放的所有远端用户混音后的音量。
- 该方法在加入频道前后都能调用。
参数
- volume
-
音量,取值范围为 [0,400]。
- 0: 静音。注: 如果你只需将音频信号静音,声网建议你使用 muteRecordingSignal。
- 100: (默认)原始音量。
- 400: 原始音量的 4 倍,自带溢出保护。
- 0: 静音。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustRecordingSignalVolume
调节音频采集信号音量。
- (int)adjustRecordingSignalVolume:(NSInteger)volume;
详情
该方法在加入频道前后都能调用。
参数
- volume
-
音量,取值范围为 [0,400]。
- 0: 静音。注: 如果你只需将音频信号静音,声网建议你使用 muteRecordingSignal。
- 100: (默认)原始音量。
- 400: 原始音量的 4 倍,自带溢出保护。
- 0: 静音。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustUserPlaybackSignalVolume
调节本地播放的指定远端用户信号音量。
- (int)adjustUserPlaybackSignalVolume:(NSUInteger)uid volume:(int)volume;
详情
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
- 该方法需要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
- uid
- 远端用户 ID。
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
configRhythmPlayer
配置虚拟节拍器。
- (int)configRhythmPlayer:(AgoraRhythmPlayerConfig * _Nullable)config;
详情
调用 startRhythmPlayer 后,你可以调用该方法重新配置虚拟节拍器。
成功调用该方法后,SDK 会在本地触发 didRhythmPlayerStateChanged 回调,报告虚拟节拍器的状态。
- 开启虚拟节拍器后,SDK 会从头开始播放指定的音频文件,并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如,将 beatsPerMinute 设为
60
,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。 - 虚拟节拍器的声音默认会发布至远端,如果你不希望远端用户听到虚拟节拍器的声音,你可以将 AgoraRtcChannelMediaOptions 中的 publishRhythmPlayerTrack 设为
NO
。
参数
- config
- 节拍器配置。详见 AgoraRhythmPlayerConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
createCustomAudioTrack
创建一个自定义音频采集轨道。
- (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 作为该音频轨道的唯一标识。
- 方法调用失败,返回负值。
destroyCustomAudioTrack
销毁指定的音频轨道。
- (int)destroyCustomAudioTrack:(NSInteger)trackId;
详情
- 自从
- v4.2.0
参数
- trackId
- 调用 createCustomAudioTrack 方法返回的自定义音频轨道 ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
disableAudio
关闭音频模块。
- (int)disableAudio;
详情
- 该方法设置内部引擎为禁用状态,在频道内和频道外均可调用。离开频道后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制音频模块:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
disableAudioSpectrumMonitor
关闭音频频谱监测。
- (int)disableAudioSpectrumMonitor;
详情
调用 enableAudioSpectrumMonitor 后,如果你想关闭音频频谱监测,请调用该方法。
该方法在加入频道前后均可调用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableAudio
启用音频模块。
- (int)enableAudio;
详情
启用音频模块(默认为开启状态)。
- 该方法设置音频模块为启用状态,在频道内和频道外均可调用。在离开频道后仍然有效。
- 调用该方法会重置整个引擎,响应时间较慢。你可以根据实际需求用以下方法来独立控制音频模块的某一项功能:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
- 在频道内调用该方法时,会重置 enableLocalAudio、muteRemoteAudioStream 和 muteAllRemoteAudioStreams 的设置,需谨慎使用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableAudioSpectrumMonitor
开启音频频谱监测。
- (int)enableAudioSpectrumMonitor:(int)intervalInMS;
详情
如果你想获取本地或远端用户的音频频谱数据,请注册音频频谱观测器并开启音频频谱监测。
该方法在加入频道前后均可调用。
参数
- intervalInMS
-
SDK 触发 onLocalAudioSpectrum 和 onRemoteAudioSpectrum 回调的时间间隔(毫秒)。 默认值为 100 毫秒。取值不得少于 10 毫秒,否则该方法会调用失败。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2: 参数设置错误。
enableAudioVolumeIndication
启用用户音量提示。
- (int)enableAudioVolumeIndication:(NSInteger)interval smooth:(NSInteger)smooth reportVad:(BOOL)reportVad;
详情
该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。启用该方法后,只要频道内有发流用户,SDK 会在加入频道后按设置的时间间隔触发 reportAudioVolumeIndicationOfSpeakers 回调。
参数
- interval
- 指定音量提示的时间间隔:
- ≤ 0: 禁用音量提示功能。
- > 0: 返回音量提示的间隔,单位为毫秒,最小取值为 50。
- smooth
- 平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
- reportVad
-
YES
:开启本地人声检测功能。开启后,reportAudioVolumeIndicationOfSpeakers 回调的 vad 参数会报告是否在本地检测到人声。NO
:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,reportAudioVolumeIndicationOfSpeakers 回调的 vad 参数不会报告是否在本地检测到人声。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableInEarMonitoring [1/2]
开启耳返功能。
- (int)enableInEarMonitoring:(BOOL)enabled;
详情
该方法打开或关闭耳返功能。
- 用户必须使用耳机(有线和蓝牙均可)才能听到耳返效果。
- 该方法在加入频道前后都能调用。
参数
- enabled
- 开启/关闭耳返功能:
YES
: 开启耳返功能。NO
: (默认)关闭耳返功能。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- - 8: 请确保当前的音频路由为蓝牙或耳机。
enableInEarMonitoring [2/2]
开启耳返功能。
- (int)enableInEarMonitoring:(BOOL)enabled includeAudioFilters:(AgoraEarMonitoringFilterType)includeAudioFilters;
详情
该方法打开或关闭耳返功能。
- 用户必须使用耳机(有线和蓝牙均可)才能听到耳返效果。
- 该方法在加入频道前后都能调用。
参数
- enabled
- 开启/关闭耳返功能:
YES
: 开启耳返功能。NO
: (默认)关闭耳返功能。
- includeAudioFilters
- 耳返 audio filter 类型。详见 AgoraEarMonitoringFilterType。
返回值
- >0: 方法调用成功。
- < 0: 方法调用失败。
- - 8: 请确保当前的音频路由为蓝牙或耳机。
enableLocalAudio
开关本地音频采集。
- (int)enableLocalAudio:(BOOL)enabled;
详情
当用户加入频道时,音频功能默认是开启的。该方法可以关闭或重新开启本地音频功能,即停止或重新开始本地音频采集。
该方法不影响接收远端音频流,enableLocalAudio(NO)
适用于只听不发的用户场景。
- 该方法与 muteLocalAudioStream 的区别在于:
- enableLocalAudio: 开启或关闭本地音频采集及处理。使用 enableLocalAudio 关闭或开启本地采集后,本地听远端播放会有短暂中断。
- muteLocalAudioStream: 停止或继续发送本地音频流。
- 该方法在加入频道前后均可调用。在加入频道前调用只能设置设备状态,在加入频道后才会立即生效。
参数
- enabled
-
YES
: 重新开启本地音频功能,即开启本地音频采集(默认);NO
: 关闭本地音频功能,即停止本地音频采集。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
getAudioMixingCurrentPosition
获取音乐文件的播放进度。
- (int)getAudioMixingCurrentPosition;
详情
该方法获取当前音乐文件播放进度,单位为毫秒。
- 你需要在调用 startAudioMixing [2/2] 并收到
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。 - 如需多次调用 getAudioMixingCurrentPosition,请确保调用间隔大于 500 ms。
返回值
- ≥ 0: 方法调用成功,返回当前音乐文件播放进度(ms)。0 表示当前音乐文件未开始播放。
- < 0: 方法调用失败。
getAudioMixingDuration
获取音乐文件总时长。
- (int)getAudioMixingDuration;
详情
该方法获取音乐文件总时长,单位为毫秒。
你需要在调用 startAudioMixing [2/2] 并收到 audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
返回值
- ≥ 0: 方法调用成功返回音乐文件时长。
- < 0: 方法调用失败。
getAudioMixingPlayoutVolume
获取音乐文件的本地播放音量。
- (int)getAudioMixingPlayoutVolume;
详情
该方法获取混音的音乐文件本地播放音量,方便排查音量相关问题。
你需要在调用 startAudioMixing [2/2] 并收到 audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
返回值
- ≥ 0: 方法调用成功则返回音量值,范围为 [0,100]。
- < 0: 方法调用失败。
getAudioMixingPublishVolume
获取音乐文件的远端播放音量。
- (int)getAudioMixingPublishVolume;
详情
该接口可以方便开发者排查音量相关问题。
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。返回值
- ≥ 0: 方法调用成功则返回音量值,范围为 [0,100]。
- < 0: 方法调用失败。
getAudioTrackCount
获取当前音乐文件的音轨索引。
- (int)getAudioTrackCount;
详情
- 你需要在调用 startAudioMixing [2/2] 并收到
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
返回值
- 方法调用成功时,返回当前音乐文件的音轨索引。
- < 0: 方法调用失败。
muteRecordingSignal
是否将录音信号静音。
-(int)muteRecordingSignal:(BOOL)muted;
参数
- muted
-
YES
: 静音。NO
:(默认)原始音量。
注: 如果你已经调用 adjustRecordingSignalVolume 调节了音量,则调用该方法并设置为YES
时,SDK 会记录当前音量并将其静音。如需恢复之前的音量,再次调用该方法并设置为NO
即可。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
pauseAudioMixing
暂停播放音乐文件。
- (int)pauseAudioMixing;
详情
请在加入频道后调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
pullPlaybackAudioFrameRawData
拉取远端音频数据。
- (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
:方法调用失败。
pullPlaybackAudioFrameSampleBufferByLengthInByte
拉取 SampleBuffer 格式的远端音频数据。
- (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
:方法调用失败。
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:));
详情
调用该方法前,请将 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
推送外部 CMSampleBuffer 音频帧。
- (int)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer;
参数
- sampleBuffer
- 采样缓冲区。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
resumeAudioMixing
恢复播放音乐文件。
- (int)resumeAudioMixing;
详情
该方法恢复混音,继续播放音乐文件。请在频道内调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
selectAudioTrack
指定当前音乐文件的播放音轨。
- (int)selectAudioTrack:(NSInteger)index;
详情
获取音乐文件的音轨数量后,你可以调用该方法指定任一音轨进行播放。例如,如果一个多音轨文件的不同音轨存放了不同语言的歌曲,则你可以调用该方法设置音乐文件的播放语言。
- 该方法支持的音频文件格式见 https://docs.agora.io/cn/faq/audio_format。
- 你需要在调用 startAudioMixing [2/2] 并收到
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
参数
- index
- 指定的播放音轨。取值范围为 [0, getAudioTrackCount()]。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAdvancedAudioOptions
设置音频的高级选项。
- (int)setAdvancedAudioOptions:(AgoraAdvancedAudioOptions * _Nonnull)options;
详情
如果你对音频处理有进阶需求,例如需要采集和发送立体声,可以调用该方法设置音频的高级选项。
参数
- options
- 音频的高级选项。详见 AgoraAdvancedAudioOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAINSMode
设置是否开启 AI 降噪功能并设置降噪模式。
- (int)setAINSMode:(BOOL)enabled mode:(AUDIO_AINS_MODE)mode NS_SWIFT_NAME(setAINSMode(_:mode:));
详情
- 自从
- v4.2.0
- 电视机噪声
- 空调噪声
- 工厂机器噪声等
- 雷声
- 爆炸声
- 破裂声等
适用场景
在语音连麦、在线教育、在线会议等场景中,如果周围环境比较嘈杂,AI 降噪功能可以在保证语音质量的前提下,识别并降低周围的稳态噪声和非稳态噪声,提高语音质量和体验。
参数
- enabled
- 是否开启 AI 降噪功能:
YES
:开启 AI 降噪功能。NO
:(默认)关闭 AI 降噪功能。
- mode
-
降噪模式,详见 AUDIO_AINS_MODE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioMixingDualMonoMode
设置当前音频文件的声道模式。
- (int)setAudioMixingDualMonoMode:(AgoraAudioMixingDualMonoMode)mode;
详情
在双声道音频文件中,左声道和右声道可以存储不同的音频数据。根据实际需要,你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如,在 KTV 场景中,音频文件的左声道存储了伴奏,右声道存储了原唱的歌声。如果你只需听伴奏,调用该方法设置音频文件的声道模式为左声道模式;如果你需要同时听伴奏和原唱,调用该方法设置声道模式为混合模式。
- 你需要在调用 startAudioMixing [2/2] 并收到
audioMixingStateChanged (AgoraAudioMixingStateTypePlaying)
回调后调用该方法。 - 该方法仅适用于双声道的音频文件。
参数
- mode
- 声道模式。详见 AgoraAudioMixingDualMonoMode。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingPitch
调整本地播放的音乐文件的音调。
- (int)setAudioMixingPitch:(NSInteger)pitch;
详情
本地人声和播放的音乐文件混音时,调用该方法可以仅调节音乐文件的音调。
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。参数
- pitch
- 按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12],每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingPosition
设置音乐文件的播放位置。
- (int)setAudioMixingPosition:(NSInteger)pos;
详情
该方法可以设置音频文件的播放位置,这样你可以根据实际情况播放文件,而非从头到尾播放整个文件。
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。参数
- pos
- 整数。进度条位置,单位为毫秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioProfile [1/2]
设置音频编码属性和音频场景。
- (int)setAudioProfile:(AgoraAudioProfile)profile scenario:(AgoraAudioScenario)scenario;
详情
- 弃用:
- 此方法已废弃,如需设置音频编码属性,请改用 setAudioProfile [2/2];如需设置音频场景,请改用 setAudioScenario。
- 该方法在加入频道前后均可调用。
- 在有高音质需求的场景(例如音乐教学场景)中,建议将 profile 设置为
AgoraAudioProfileMusicHighQuality(4)
,scenario 设置为AgoraAudioScenarioGameStreaming(3)
。
参数
- profile
-
音频编码属性,包含采样率、码率、编码模式和声道数。详见 AgoraAudioProfile。
- scenario
- 音频场景。详见 AgoraAudioScenario 。不同的音频场景下,设备的音量类型是不同的。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioProfile [2/2]
设置音频编码属性。
- (int)setAudioProfile:(AgoraAudioProfile)profile;
详情
- 该方法在加入频道前后均可调用。
- 在有高音质需求的场景(例如音乐教学场景)中,建议将
profile
设置为AgoraAudioProfileMusicHighQuality (4)
。 - 如果你想设置音频应用场景,可以直接调用 setAudioScenario 方法进行设置,也可以调用 sharedEngineWithConfig 并设置 AgoraRtcEngineConfig 结构体中的 audioScenario。
参数
- profile
-
音频编码属性,包含采样率、码率、编码模式和声道数。详见 AgoraAudioProfile。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioScenario
设置音频场景。
- (int)setAudioScenario:(AgoraAudioScenario)scenario;
详情
参数
- scenario
- 音频场景,详见 AgoraAudioScenario。不同的音频场景下,设备的音量类型是不同的。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioSessionOperationRestriction
设置 SDK 对 Audio Session 的操作权限。
- (void)setAudioSessionOperationRestriction:(AgoraAudioSessionOperationRestriction)restriction NS_SWIFT_NAME(setAudioSessionOperationRestriction(_:));
详情
默认情况下,SDK 和 app 对 Audio Session 都有操作权限。如果你只需使用 app 对 Audio Session 进行操作,你可以调用该方法限制 SDK 对 Audio Session 的操作权限。
该方法在加入频道前后都能调用。一旦调用该方法限制了 SDK 对 Audio Session 的操作权限,该限制会在 SDK 需要更改 Audio Session 时生效。
- 该方法不会限制 app 对 Audio Session 的操作权限。
参数
- restriction
- SDK 对 Audio Session 的操作权限,详见 AgoraAudioSessionOperationRestriction。该参数为 Bit Mask,每个 Bit 对应一个权限。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败。
setDefaultAudioRouteToSpeakerphone
设置默认的音频路由。
- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker;
详情
- 该方法需要在加入频道前调用。如需在加入频道后切换音频路由,请调用 setEnableSpeakerphone。
手机设备一般有两个音频路由,一个是位于顶部的听筒,播放声音偏小;一个是位于底部的扬声器,播放声音偏大。设置默认的音频路由,就是在没有外接设备的前提下,设置系统使用听筒还是扬声器播放音频。
- 语音通话:听筒
- 语音直播:扬声器
- 视频通话:扬声器
- 视频直播:扬声器
调用该 API 可以改变上述默认音频路由。成功改变音频路由后,SDK 会触发 didAudioRouteChanged 回调。
当手机插入外接设备,如蓝牙设备或耳机时,系统的音频路由会发生改变。详细的路由变化规律请参考 音频路由。
参数
- defaultToSpeaker
- 是否使用扬声器作为默认的音频路由:
YES
: 设置默认音频路由为扬声器。NO
: 设置默认音频路由为听筒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEarMonitoringAudioFrameParametersWithSampleRate
设置耳返的音频数据格式。
- (int)setEarMonitoringAudioFrameParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel mode:(AgoraAudioRawFrameOperationMode)mode samplesPerCall:(NSInteger)samplesPerCall;
详情
该方法用于设置 onEarMonitoringAudioFrame 回调的耳返音频数据格式。
- 调用该方法前,你需要先调用 enableInEarMonitoring [2/2],将 includeAudioFilters 设置为 AgoraEarMonitoringFilterBuiltInAudioFilters 或 AgoraEarMonitoringFilterNoiseSuppression。
- SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。SDK 会根据该采样间隔触发 onEarMonitoringAudioFrame 回调。
参数
- sampleRate
- onEarMonitoringAudioFrame 中报告音频的采样率 (Hz),可设置为 8000、 16000、 32000、44100 或 48000。
- channel
-
onEarMonitoringAudioFrame 中报告音频的声道数,可设置为 1 或 2:
- 1: 单声道。
- 2: 双声道。
- mode
-
音频帧的使用模式,详见 AgoraAudioRawFrameOperationMode。
- samplesPerCall
- onEarMonitoringAudioFrame 中报告的音频的采样点数,如旁路推流应用中通常为 1024。
返回值
- 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: 双声道
返回值
- < 0: 方法调用失败
setExternalAudioSource [1/2]
设置外部音频采集参数。
- (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:方法调用失败。
setExternalAudioSource [2/2]
设置外部音频采集参数。
- (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: 方法调用失败。
setInEarMonitoringVolume
设置耳返音量。
- (int)setInEarMonitoringVolume:(NSInteger)volume;
详情
- 用户必须使用有线耳机才能听到耳返效果。
- 该方法在加入频道前后都能调用。
参数
- volume
- 设置耳返音量,取值范围在 [0,100]。默认值为 100。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioMixing [1/2]
开始播放音乐文件。
- (int)startAudioMixing:(NSString * _Nonnull)filePath loopback:(BOOL)loopback cycle:(NSInteger)cycle NS_SWIFT_NAME(startAudioMixing(_:loopback:cycle:));
详情
- 弃用:
- 请改用 startAudioMixing [2/2]。
该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后,本地会触发 audioMixingStateChanged (AgoraAudioMixingStateTypePlaying) 回调。播放结束后,本地会触发 audioMixingStateChanged (AgoraAudioMixingStateTypeStopped) 回调。
- 该方法在加入频道前后均可调用。如需多次调用 startAudioMixing [1/2],请确保调用间隔大于 500 ms。
- 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL,则 SDK 会报告警告码 701。
参数
- filePath
-
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见支持的媒体格式。 - loopback
-
是否只在本地播放音乐文件:
YES
: 只在本地播放音乐文件,只有本地用户能听到音乐。NO
: 将本地播放的音乐文件发布至远端,本地用户和远端用户都能听到音乐。
- cycle
-
音乐文件的播放次数。
- ≥ 0: 播放次数。例如,0 表示不播放;1 表示播放 1 次。
- -1: 无限循环播放。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioMixing [2/2]
开始播放音乐文件。
- (int)startAudioMixing:(NSString* _Nonnull)filePath loopback:(BOOL)loopback cycle:(NSInteger)cycle startPos:(NSInteger)startPos;
详情
该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后,本地会触发 audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调。播放结束后,本地会触发 audioMixingStateChanged(AgoraAudioMixingStateTypeStopped)
回调。
- 该方法在加入频道前后均可调用。如需多次调用 startAudioMixing [2/2],请确保调用间隔大于 500 ms。
- 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL,则 SDK 会报告警告码 701。
- 该方法支持的音频文件格式见 RTC SDK 支持播放哪些格式的音频文件。
参数
- filePath
- 文件路径:
- iOS 或 macOS: 音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。
- iOS 或 macOS: 音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
- loopback
-
是否只在本地播放音乐文件:
YES
: 只在本地播放音乐文件,只有本地用户能听到音乐。NO
: 将本地播放的音乐文件发布至远端,本地用户和远端用户都能听到音乐。
- cycle
-
音乐文件的播放次数。
- ≥ 0: 播放次数。例如,0 表示不播放;1 表示播放 1 次。
- -1: 无限循环播放。
- startPos
- 音乐文件的播放位置,单位为毫秒。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败
- -1: 一般性的错误(未明确归类)。
- -2: 设置了无效的参数。
- -3:SDK 尚未准备好:
- 请检查是否已开启音频模块。
- 请检查程序集完整性。
- AgoraRtcEngineKit 初始化失败。请重新初始化 AgoraRtcEngineKit。
startAudioRecording [1/2]
开始客户端录音。
- (int)startAudioRecording:(NSString * _Nonnull)filePath quality:(AgoraAudioRecordingQuality)quality;
详情
.wav
: 文件大,音质保真度高;.aac
: 文件小,有一定的音质保真度损失。
请确保 App 里指定的目录存在且可写。该接口需在 joinChannelByToken [2/4] 之后调用。如果调用 leaveChannel [2/2] 时还在录音,录音会自动停止。
参数
- filePath
- 录音文件在本地保存的绝对路径,需精确到文件名及格式。例如:
/var/mobile/Containers/Data/audio.mp4
。注意:请确保你指定的路径存在并且可写。
- quality
- 录音质量。详见 AgoraAudioRecordingQuality 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioRecording [2/2]
开始客户端录音并进行录音配置。
- (int)startAudioRecordingWithConfig:(AgoraAudioRecordingConfiguration * _Nonnull)config;
详情
- WAV: 音质保真度较高,文件较大。例如,采样率为 32000 Hz,录音时长为 10 分钟的文件大小约为 73 M。
- AAC: 音质保真度较低,文件较小。例如,采样率为 32000 Hz,录音音质为 AgoraAudioRecordingQualityMedium,录音时长为 10 分钟的文件大小约为 2 M。
用户离开频道后,录音会自动停止。
参数
- config
- 录音配置。详见 AgoraAudioRecordingConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startRhythmPlayer
开启虚拟节拍器。
- (int)startRhythmPlayer:(NSString * _Nonnull)sound1 sound2:(NSString * _Nonnull)sound2 config:(AgoraRhythmPlayerConfig * _Nullable)config;
详情
在音乐教学、体育教学等场景中,老师通常需要使用节拍器,让学生跟着正确的节拍练习。节拍由强拍和弱拍组成,每小节的第一拍称为强拍,其余称为弱拍。
你需要在该方法中设置强拍和弱拍的文件路径、每小节的拍数、节拍速度以及是否将节拍器的声音发送至远端。
成功调用该方法后,SDK 会在本地触发 didRhythmPlayerStateChanged 回调,报告虚拟节拍器的状态。
- 开启虚拟节拍器后,SDK 会从头开始播放指定的音频文件,并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如,将 beatsPerMinute 设为
60
,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。 - 虚拟节拍器的声音默认会发布至远端,如果你不希望远端用户听到虚拟节拍器的声音,你可以将 AgoraRtcChannelMediaOptions 中的 publishRhythmPlayerTrack 设为
NO
。
参数
- sound1
- 强拍文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。支持的音频文件格式见 RTC SDK 支持播放哪些格式的音频文件。 - sound2
- 弱拍文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。支持的音频文件格式见 RTC SDK 支持播放哪些格式的音频文件。 - config
- 节拍器配置。详见 AgoraRhythmPlayerConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -22: 无法找到音频文件。请填写正确的 sound1 和 sound2。
stopAudioMixing
停止播放音乐文件。
- (int)stopAudioMixing;
详情
该方法停止播放音乐文件。请在频道内调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopAudioRecording
停止客户端录音。
- (int)stopAudioRecording;
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopRhythmPlayer
关闭虚拟节拍器。
- (int)stopRhythmPlayer;
详情
调用 startRhythmPlayer 后,你可以调用该方法关闭虚拟节拍器。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
activeSpeaker
监测到远端最活跃用户回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine activeSpeaker:(NSUInteger)speakerUid;
成功调用 enableAudioVolumeIndication 后,SDK 会持续监测音量最大的远端用户,并统计该用户被判断为音量最大者的次数。当前时间段内,该次数累积最多的远端用户为最活跃的用户。
- 如果远端最活跃用户一直是同一位用户,则 SDK 不会再次触发 activeSpeaker 回调。
- 如果远端最活跃用户有变化,则 SDK 会再次触发该回调并报告新的远端最活跃用户的 uid。
参数
- engine
- AgoraRtcEngineKit 对象。
- speakerUid
- 远端最活跃用户的 ID。
rtcEngineLocalAudioMixingDidFinish
本地音乐文件播放已结束回调。
- (void)rtcEngineLocalAudioMixingDidFinish:(AgoraRtcEngineKit * _Nonnull)engine;
- 弃用:
- 请改用 audioMixingStateChanged。
当调用 startAudioMixing [2/2] 播放本地音乐文件结束后,会触发该回调。如果调用 startAudioMixing [2/2] 失败,会返回错误码 WARN_AUDIO_MIXING_OPEN_ERROR。
参数
- engine
- AgoraRtcEngineKit 对象。
audioMixingPositionChanged
音乐文件播放进度回调。
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine audioMixingPositionChanged:(NSInteger)position NS_SWIFT_NAME(rtcEngine(_:audioMixingPositionChanged:));
详情
- 自从
- v4.2.0
当你调用 startAudioMixing [2/2] 方法播放音乐文件后,SDK 会每隔一秒触发一次该回调,报告音乐文件当前的播放进度。
参数
- position
- 音乐文件当前的播放进度,单位为 ms。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
audioMixingStateChanged
音乐文件的播放状态已改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine audioMixingStateChanged:(AgoraAudioMixingStateType)state reasonCode:(AgoraAudioMixingReasonCode)reasonCode;
该回调在音乐文件播放状态发生改变时触发,并报告当前的播放状态和错误码。
参数
- state
- 音乐文件播放状态。详见 AgoraAudioMixingStateType。
- reasonCode
- 错误码。详见 AgoraAudioMixingReasonCode。
didAudioPublishStateChange
音频发布状态改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didAudioPublishStateChange:(NSString * _Nonnull)channelId oldState:(AgoraStreamPublishState)oldState newState:(AgoraStreamPublishState)newState elapseSinceLastState:(int)elapseSinceLastState;
参数
- engine
- AgoraRtcEngineKit 对象。
- channelId
- 频道名。
- oldState
- 之前的发布状态,详见 AgoraStreamPublishState。
- newState
- 当前的发布状态,详见 AgoraStreamPublishState。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
audioQualityOfUid
远端声音质量回调。
- (void)audioQualityBlock:(void (^_Nullable)(NSUInteger uid, AgoraNetworkQuality quality, NSUInteger delay, NSUInteger lost))audioQualityBlock
- 弃用:
- 请改用 remoteAudioStats。
该回调描述远端用户在通话中的音频质量,针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播,该回调每 2 秒会被触发多次。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 用户 ID,指定是谁发的音频流。
- quality
- 语音质量。详见 AgoraNetworkQuality。
- delay
- 音频包从发送端到接收端的延迟(毫秒),包括声音采样前处理、网络传输、网络抖动缓冲引起的延迟。
- lost
- 音频包从发送端到接收端的丢包率 (%)。
didAudioRouteChanged
音频路由已发生变化回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didAudioRouteChanged:(AgoraAudioOutputRouting)routing;
参数
- engine
- AgoraRtcEngineKit 对象。
- routing
-
当前的音频路由。详见 AgoraAudioOutputRouting。
reportAudioVolumeIndicationOfSpeakers
用户音量提示回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine reportAudioVolumeIndicationOfSpeakers:(NSArray<AgoraRtcAudioVolumeInfo *> * _Nonnull)speakers totalVolume:(NSInteger)totalVolume;
该回调默认禁用,你可以通过 enableAudioVolumeIndication 开启。 开启后,只要频道内有发流用户,SDK 会在加入频道后按 enableAudioVolumeIndication 中设置的时间间隔触发 reportAudioVolumeIndicationOfSpeakers 回调。每次会触发两个 reportAudioVolumeIndicationOfSpeakers 回调,一个报告本地发流用户的音量相关信息,另一个报告瞬时音量最高的远端用户(最多 3 位)的音量相关信息。
在收到该回调后如需更新 UI 界面,请将确保将执行的线程转至 UI 线程中。
启用该功能后,如果有用户将自己静音(调用了 muteLocalAudioStream),SDK 会继续报告本地用户的音量提示回调。
瞬时音量最高的远端用户静音后 20 秒,远端的音量提示回调中将不再包含该用户;如果远端所有用户都将自己静音,20 秒后 SDK 停止报告远端用户的音量提示回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- speakers
- 用户音量信息,详见 AgoraRtcAudioVolumeInfo 数组。如果 speakers 为空,则表示远端用户不发流或没有远端用户。
- totalVolume
-
混音后的总音量,取值范围为 [0,255]。
- 在本地用户的回调中,totalVolume 为本地发流用户的音量。
- 在远端用户的回调中,totalVolume 为瞬时音量最高的远端用户(最多 3 位)混音后的总音量。 如果用户调用了 startAudioMixing [2/2],则 totalVolume 为音乐文件和用户声音的总音量。
firstLocalAudioFramePublished
已发布本地音频首帧回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstLocalAudioFramePublished:(NSInteger)elapsed;
- 开启本地音频的情况下,调用 joinChannelByToken [2/4] 成功加入频道后。
- 调用
muteLocalAudioStream(
,再调用YES
)muteLocalAudioStream(
后。NO
) - 调用 disableAudio,再调用 enableAudio 后。
- 调用 pushExternalAudioFrameRawData 成功向 SDK 推送音频帧后。
参数
- engine
- AgoraRtcEngineKit 对象。
- elapsed
- 从调用 joinChannelByToken [2/4] 方法到触发该回调的时间间隔(毫秒)。
firstRemoteAudioFrameDecodedOfUid
已解码远端音频首帧的回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine firstRemoteAudioFrameDecodedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed;
- 弃用:
- 请改用 remoteAudioStateChangedOfUid 。
- 远端用户首次上线后发送音频。
- 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包,可能有如下原因:
- 远端用户离开频道
- 远端用户掉线
- 远端用户调用 muteLocalAudioStream 方法停止发送音频流
- 远端用户调用 disableAudio 方法关闭音频
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 远端用户 ID。
- elapsed
- 从本地用户调用 joinChannelByToken [2/4] 直至该回调触发的延迟,单位为毫秒。
firstRemoteAudioFrameOfUid
已接收远端音频首帧回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine firstRemoteAudioFrameOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:firstRemoteAudioFrameOfUid:elapsed:));
- 弃用:
- 请改用 remoteAudioStateChangedOfUid 。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 发送音频帧的远端用户的用户 ID。
- elapsed
- 从本地用户调用 joinChannelByToken [2/4] 直至该回调触发的延迟,单位为毫秒。
localAudioStateChanged
本地音频状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine localAudioStateChanged:(AgoraAudioLocalState)state error:(AgoraAudioLocalError)error;
本地音频的状态发生改变时(包括本地麦克风采集状态和音频编码状态),SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时,该回调可以帮助你了解当前音频的状态以及出现故障的原因,方便你排查问题。
参数
- engine
- AgoraRtcEngineKit 对象。
- state
- 当前的本地音频状态。详见 AgoraAudioLocalState。
- error
- 本地音频出错原因。详见 AgoraAudioLocalError。
localAudioStats
通话中本地音频流的统计信息回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine localAudioStats:(AgoraRtcLocalAudioStats * _Nonnull)stats;
SDK 每 2 秒触发该回调一次。
参数
- engine
- AgoraRtcEngineKit 对象。
- stats
- 本地音频统计数据。详见 AgoraRtcLocalAudioStats。
remoteAudioStateChangedOfUid
远端音频流状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine remoteAudioStateChangedOfUid:(NSUInteger)uid state:(AgoraAudioRemoteState)state reason:(AgoraAudioRemoteReason)reason elapsed:(NSInteger)elapsed;
远端用户(通信场景)或主播(直播场景)的音频状态发生改变时,SDK 会触发该回调向本地用户报告当前的远端音频流状态。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 发生音频状态改变的远端用户 ID。
- state
- 远端音频流状态,详见 AgoraAudioRemoteState。
- reason
- 远端音频流状态改变的具体原因,详见 AgoraAudioRemoteReason。
- elapsed
- 从本地用户调用 joinChannelByToken [2/4] 方法到发生本事件经历的时间,单位为毫秒。
remoteAudioStats
通话中远端音频流的统计信息回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine remoteAudioStats:(AgoraRtcRemoteAudioStats * _Nonnull)stats;
该回调针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流,该回调每 2 秒会被触发多次。
参数
- engine
- AgoraRtcEngineKit 对象。
- stats
- 接收到的远端音频统计数据,详见 AgoraRtcRemoteAudioStats。
audioTransportStatsOfUid
通话中远端音频流传输的统计信息回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine audioTransportStatsOfUid:(NSUInteger)uid delay:(NSUInteger)delay lost:(NSUInteger)lost rxKBitRate:(NSUInteger)rxKBitRate;
- 弃用:
- 请改用 remoteAudioStats。
该回调描述远端用户通话中端到端的网络统计信息,通过音频包计算,用客观的数据,如丢包、 网络延迟等,展示当前网络状态。通话中,当用户收到远端用户/主播发送的音频数据包后 ,会每 2 秒触发一次该回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 用户 ID,指定是哪个用户/主播的音频包。
- delay
- 音频包从发送端到接收端的延时(毫秒)。
- lost
- 音频包从发送端到接收端的丢包率 (%)。
- rxKBitrate
- 远端音频包的接收码率(Kbps)。
didLocalVideoTranscoderErrorWithStream
本地合图发生错误回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLocalVideoTranscoderErrorWithStream:(AgoraTranscodingVideoStream * _Nonnull )stream errorCode:(AgoraVideoTranscoderError)errorCode NS_SWIFT_NAME(rtcEngine(_:didLocalVideoTranscoderErrorWithStream:errorCode:));
详情
- 自从
- v4.2.0
当你调用 startLocalVideoTranscoder 或 updateLocalTranscoderConfiguration 失败时,SDK 会触发该回调,报告合图失败的原因。
参数
- stream
- 合图失败的视频流。详见 AgoraTranscodingVideoStream。
- errorCode
- 本地合图出错原因。详见 AgoraVideoTranscoderError。
remoteVideoStateChangedOfUid
远端视频状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine remoteVideoStateChangedOfUid:(NSUInteger)uid state:(AgoraVideoRemoteState)state reason:(AgoraVideoRemoteReason)reason elapsed:(NSInteger)elapsed;
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 发生视频状态改变的远端用户 ID。
- state
-
远端视频流状态,详见 AgoraVideoRemoteState。
- reason
-
远端视频流状态改变的具体原因,详见 AgoraVideoRemoteReason。
- elapsed
- 从本地用户调用 joinChannelByToken [2/4] 方法到发生本事件经历的时间,单位为毫秒。
didRhythmPlayerStateChanged
虚拟节拍器状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didRhythmPlayerStateChanged:(AgoraRhythmPlayerState)state errorCode:(AgoraRhythmPlayerError)errorCode NS_SWIFT_NAME(rtcEngine(_:didRhythmPlayerStateChanged:errorCode:));
虚拟节拍器状态发生改变时,SDK 会触发该回调报告当前的虚拟节拍器状态。在虚拟节拍器出现故障时,该回调可以帮助你了解当前虚拟节拍的状态以及出现故障的原因,方便你排查问题。
参数
- state
- 当前的虚拟节拍器状态,详见 AgoraRhythmPlayerState。
- errorCode
- 虚拟节拍器发生错误的错误码和错误信息,详见 AgoraRhythmPlayerError。
didAudioMuted
远端用户(通信场景)/主播(直播场景)停止或恢复发送音频流回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didAudioMuted:(BOOL)muted byUid:(NSUInteger)uid;
该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。
参数
- uid
- 用户 ID。
- muted
- 该用户是否静音:
YES
: 该用户已将音频静音。NO
: 该用户取消了音频静音。