Agora Objective-C API Overview Document

声网通过全球部署的虚拟网络,提供可以灵活搭配的 API 组合,为移动端到移动端以及移动端到 Web 端提供质量可靠的实时音视频通信。

在调用 API 过程中,SDK 可能会返回错误码和警告码,详见错误码和警告码

icon 自 v2.3.3 开始,Objective-C API Reference for iOS/macOS 可以在 Dash 下载,详见 FAQ

核心方法

方法 功能
sharedEngineWithAppId 创建 AgoraRtcEngineKit 实例
sharedEngineWithConfig 创建 AgoraRtcEngineKit 实例并指定访问区域
destroy 销毁 AgoraRtcEngineKit 实例
setChannelProfile 设置频道场景
setClientRole1 设置直播场景下的用户角色
setClientRole2 设置直播场景下的用户角色和级别
joinChannelByToken1 加入频道
joinChannelByToken2 加入频道并设置发布或订阅状态
switchChannelByToken1 快速切换直播频道
switchChannelByToken2 快速切换直播频道并设置订阅状态
leaveChannel 离开频道
renewToken 更新 Token
getConnectionState 获取网络连接状态

核心事件

事件 描述
didJoinChannel 已加入频道
didRejoinChannel 已重新加入频道
didLeaveChannelWithStats 已离开频道
didClientRoleChanged 直播场景下用户角色切换成功回调
didClientRoleChangeFailed 直播场景下切换用户角色失败回调
didJoinedOfUid 远端用户已加入频道
didOfflineOfUid 远端用户已离开频道
connectionChangedToState 网络连接状态已改变
networkTypeChangedToType 本地网络类型发生改变
rtcEngineConnectionDidLost 网络连接中断且 SDK 无法在 10 秒内连接服务器
tokenPrivilegeWillExpire Token 服务即将过期
rtcEngineRequestToken Token 已过期

音频管理

方法 功能
enableAudio 启用音频模块
disableAudio 关闭音频模块
setAudioProfile 设置音频编码配置
adjustRecordingSignalVolume 调节麦克风采集信号音量
adjustLoopbackRecordingSignalVolume 调节声卡采集信号音量(仅适用于 macOS)
adjustUserPlaybackSignalVolume 调节本地播放的指定远端用户的信号音量
adjustPlaybackSignalVolume 调节本地播放的所有远端用户的信号音量
enableLocalAudio 开关本地音频采集
muteLocalAudioStream 取消或恢复发布本地音频流
muteRemoteAudioStream 取消或恢复订阅指定远端用户的音频流
muteAllRemoteAudioStreams 取消或恢复订阅所有远端用户的音频流

视频管理

方法 功能
enableVideo 启用视频模块
disableVideo 关闭视频模块
setVideoEncoderConfiguration 设置视频编码配置
setupLocalVideo 初始化本地用户视图
setupRemoteVideo 初始化远端用户视图
setLocalRenderMode 更新本地视图显示模式
setRemoteRenderMode 更新远端视图显示模式
startPreview 开启视频预览
stopPreview 停止视频预览
enableLocalVideo 开关本地视频采集
muteLocalVideoStream 取消或恢复发布本地视频流
muteRemoteVideoStream 取消或恢复订阅指定远端用户的视频流
muteAllRemoteVideoStreams 取消或恢复订阅所有远端用户的视频流

本地媒体事件

事件 描述
localAudioStateChange 本地音频状态发生改变
localVideoStateChange 本地视频状态发生改变
firstLocalAudioFramePublished 已发布本地音频首帧回调
firstLocalVideoFramePublished 已发布本地视频首帧回调
firstLocalVideoFrameWithSize 已显示本地视频首帧
didAudioPublishStateChange 音频发布状态改变回调
didVideoPublishStateChange 视频发布状态改变回调

远端媒体事件

事件 描述
remoteAudioStateChangedOfUid 远端音频流状态发生改变
remoteVideoStateChangedOfUid 远端用户视频流状态发生改变
firstRemoteVideoFrameOfUid 已显示远端视频首帧
firstRemoteVideoDecodedOfUid 已完成远端视频首帧解码回调
didAudioSubscribeStateChange 音频订阅状态发生改变回调
didVideoSubscribeStateChange 视频订阅状态发生改变回调
didAudioMuted 远端用户音频静音回调
didVideoMuted 远端用户取消或恢复发布视频流回调
didVideoEnabled 远端用户启用/关闭视频回调
didLocalVideoEnabled 远端用户启用/关闭本地视频回调

数据统计事件

加入频道后,SDK 每隔 2 秒自动触发本组回调。 我们为这些回调提供了详细的功能描述、实现方法文档,详情请参考《通话中质量监测》。

事件 描述
remoteAudioStats 报告通话中远端音频流的统计信息
reportRtcStats 报告 Rtc Engine 统计信息
networkQuality 报告网络上下行质量
localAudioStats 通话中本地音频流的统计信息回调
localVideoStats 报告本地视频统计信息
remoteVideoStats 报告远端视频统计信息

视频前处理及后处理

方法 功能
setBeautyEffectOptions 设置美颜效果选项
enableVirtualBackground 开启/关闭虚拟背景
enableRemoteSuperResolution 开启/关闭远端视频超分辨率(beta 功能)
setVideoDenoiserOptions 设置视频降噪功能
setLowlightEnhanceOptions 设置暗光增强功能
setColorEnhanceOptions 设置色彩增强功能
事件 描述
virtualBackgroundSourceEnabled 报告虚拟背景是否成功开启
superResolutionEnabledOfUid 报告超分辨率功能是否成功开启(beta 功能)

多频道管理

我们为该组 API 提供了详细的场景描述、实现方法及开发注意事项文档,详情请参考《加入多频道》。

API 功能
createRtcChannel 创建并获取一个 AgoraRtcChannel 对象。通过创建多个对象,用户可以同时加入多个频道
AgoraRtcChannel 该类提供在指定频道内实现实时音视频功能的方法
AgoraRtcChannelDelegate 该类提供监听指定频道事件和数据的回调

屏幕共享

我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档,详情请参考《屏幕共享》。

方法 功能
getScreenCaptureSourcesWithThumbSize 获取可共享的屏幕和窗口对象列表(仅支持 macOS)
startScreenCaptureByDisplayId 通过屏幕 ID 共享屏幕(仅支持 macOS)
startScreenCaptureByWindowId 通过窗口 ID 共享窗口(仅支持 macOS)
startScreenCapture 开始屏幕共享(仅支持 iOS)
setScreenCaptureContentHint 设置屏幕共享内容类型(仅支持 macOS)
updateScreenCaptureParameters 更新屏幕共享的参数配置(仅支持 macOS)
updateScreenCapture 更新屏幕共享配置(仅支持 iOS)
updateScreenCaptureRegion 更新屏幕共享区域(仅支持 macOS)
stopScreenCapture 停止屏幕共享

音乐文件播放及混音

方法 功能
startAudioMixing 开始播放音乐文件
stopAudioMixing 停止播放音乐文件
pauseAudioMixing 暂停播放音乐文件
resumeAudioMixing 恢复播放音乐文件
adjustAudioMixingVolume 调节音乐文件播放音量
adjustAudioMixingPlayoutVolume 调节音乐文件的本地播放音量
adjustAudioMixingPublishVolume 调节音乐文件的远端播放音量
setAudioMixingPitch 调整本地播放的音乐文件的音调
getAudioMixingPlayoutVolume 获取音乐文件的本地播放音量
getAudioMixingPublishVolume 获取音乐文件的远端播放音量
getAudioMixingCurrentPosition 获取音乐文件播放进度
setAudioMixingPosition 设置音乐文件的播放位置
getAudioTrackCount 获取当前音乐文件的音轨数量(仅适用于 iOS)
selectAudioTrack 指定当前音乐文件的播放音轨(仅适用于 iOS)
setAudioMixingPlaybackSpeed 设置当前音乐文件的播放速度
setAudioMixingDualMonoMode 设置当前音乐文件的声道模式
事件 描述
localAudioMixingStateDidChanged 本地音乐文件播放状态改变
rtcEngineRemoteAudioMixingDidStart 远端音乐文件播放已开始
rtcEngineRemoteAudioMixingDidFinish 远端音乐文件播放已结束

音效文件播放管理

方法 功能
getEffectsVolume 获取音效文件播放音量
setEffectsVolume 设置音效文件播放音量
setVolumeOfEffect 实时调整音效文件播放音量
playEffect 播放指定音效文件
stopEffect 停止播放指定音效文件
stopAllEffects 停止播放所有音效文件
preloadEffect 将指定音效文件预加载至内存
unloadEffect 从内存释放某个预加载的音效文件
pauseEffect 暂停音效文件播放
pauseAllEffects 暂停所有音效文件播放
resumeEffect 恢复播放指定音效文件
resumeAllEffects 恢复播放所有音效文件
getEffectCurrentPosition 获取指定音效文件的播放进度
setEffectPosition 设置指定音效文件的播放位置
事件 描述
rtcEngineDidAudioEffectFinish 本地音效文件播放已结束

音频文件信息

方法 功能
getAudioFileInfo 获取指定音频文件信息
getEffectDuration 获取指定音频文件信息
事件 描述
didRequestAudioFileInfo 音频文件信息回调

虚拟节拍器

本组方法仅适用于 iOS,不适用于 macOS。

方法 功能
startRhythmPlayer 开启虚拟节拍器
configRhythmPlayer 配置虚拟节拍器
stopRhythmPlayer 关闭虚拟节拍器

人声效果

方法 功能
setLocalVoicePitch 设置本地语音音调
enableLocalVoicePitchCallback 开启本地语音音调回调
setLocalVoiceEqualizationOfBandFrequency 设置本地语音音效均衡
setLocalVoiceReverbOfType 设置本地音效混响
setVoiceBeautifierPreset 设置 SDK 预设的美声效果
setVoiceBeautifierParameters 设置 SDK 预设美声效果的参数
setAudioEffectPreset 设置 SDK 预设的人声音效
setAudioEffectParameters 设置 SDK 预设人声音效的参数
setVoiceConversionPreset 设置 SDK 预设的变声效果
事件 描述
reportLocalVoicePitchFrequency 报告本地用户的语音音调

听声辨位

方法 功能
enableSoundPositionIndication 开启/关闭远端用户的语音立体声
setRemoteVoicePosition 设置远端用户的语音位置

旁路推流

本组方法仅适用于直播场景。

方法 功能
startRtmpStreamWithoutTranscoding 开始非转码推流
startRtmpStreamWithTranscoding 开始 CDN 直播推流并设置转码属性
updateRtmpTranscoding 更新转码属性
stopRtmpStream 结束 CDN 直播推流
事件 描述
rtmpStreamingChangedToState RTMP/RTMPS 推流状态发生改变
rtmpStreamingEventWithUrl RTMP/RTMPS 推流事件回调
rtcEngineTranscodingUpdated 旁路推流设置已被更新

跨频道媒体流转发

方法 功能
startChannelMediaRelay 开始跨频道媒体流转发
updateChannelMediaRelay 更新媒体流转发的频道
stopChannelMediaRelay 停止跨频道媒体流转发
pauseAllChannelMediaRelay 暂停向所有目标频道转发媒体流
resumeAllChannelMediaRelay 恢复向所有目标频道转发媒体流
事件 描述
channelMediaRelayStateDidChange 跨频道媒体流转发状态发生改变
didReceiveChannelMediaRelayEvent 跨频道媒体流转发事件

音量提示

方法 功能
enableAudioVolumeIndication 启用用户音量提示
事件 描述
reportAudioVolumeIndicationOfSpeakers 用户音量提示回调
activeSpeaker 监测到远端最活跃用户回调

人脸检测

本组方法仅适用于 iOS,不适用于 macOS。

方法 功能
enableFaceDetection 开启/关闭本地人脸检测
事件 描述
facePositionDidChangeWidth 报告本地人脸检测结果

音频播放路由

方法 功能
setDefaultAudioRouteToSpeakerphone 设置默认的音频路由(仅适用于 iOS)
setEnableSpeakerphone 开启/关闭扬声器播放(仅适用于 iOS)
isSpeakerphoneEnabled 查询扬声器启用状态(仅适用于 iOS)
事件 描述
didAudioRouteChanged 音频路由已改变

耳返控制

本组方法仅适用于 iOS,不适用于 macOS。

方法 功能
enableInEarMonitoring 开启耳返功能
setInEarMonitoringVolume 设置耳返音量

视频双流模式

方法 功能
enableDualStreamMode 开关视频双流模式
setRemoteVideoStream 设置订阅的视频流类型
setRemoteDefaultVideoStreamType 设置默认订阅的视频流类型

音视频流回退

我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档,详情请参考《视频流回退》。

方法 功能
setRemoteUserPriority 设置远端用户流的优先级
setLocalPublishFallbackOption 设置弱网条件下发布的音视频流回退选项
setRemoteSubscribeFallbackOption 设置弱网条件下订阅的音视频流回退选项
事件 描述
didLocalPublishFallbackToAudioOnly 本地发布流已回退为音频流或恢复为音视频流
didRemoteSubscribeFallbackToAudioOnly 远端订阅流已回退为音频流或恢复为音视频流

通话前网络测试

我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档,详情请参考《通话前检测》。

方法 功能
startEchoTestWithInterval 开始音频通话回路测试
startEchoTestWithConfig 开始音视频通话回路测试
stopEchoTest 停止通话回路测试
enableLastmileTest 启用网络测试
disableLastmileTest 关闭网络测试
startLastmileProbeTest 开始通话前网络质量探测
stopLastmileProbeTest 停止通话前网络质量探测
事件 描述
lastmileQuality 报告本地用户的网络质量
lastmileProbeTestResult 报告通话前网络上下行 last mile 质量

自定义视频模块

方法 功能
setVideoSource 设置自定义视频源
setLocalVideoRenderer 设置本地自定义视频渲染器
setRemoteVideoRenderer 设置远端自定义视频渲染器
videoSource 获取当前视频源
localVideoRenderer 获取本地视频渲染器
remoteVideoRendererOfUserId 获取远端视频渲染器

音频自采集(仅适用于 Push 模式)

方法 功能
enableExternalAudioSourceWithSampleRate 开启外部音频采集
disableExternalAudioSource 关闭外部音频采集
pushExternalAudioFrameRawData 推送外部原始音频帧到指定位置
pushExternalAudioFrameSampleBuffer 推送外部 CMSampleBuffer 音频帧到指定位置
setExternalAudioSourceVolume 设置指定位置的外部音频帧音量

音频自渲染

方法 功能
enableExternalAudioSink 开启外部音频渲染
disableExternalAudioSink 关闭外部音频渲染
pullPlaybackAudioFrameRawData 拉取 RawData 格式的远端音频数据
pullPlaybackAudioFrameSampleBufferByLengthInByte 拉取 SampleBuffer 格式的远端音频数据

视频自采集(仅适用于 Push 模式)

方法 功能
setExternalVideoSource 配置外部视频源
pushExternalVideoFrame 推送外部视频帧

原始音频数据

方法 功能
setAudioDataFrame 注册原始音频数据协议
getObservedAudioFramePosition 设置音频观测位置
getMixedAudioParams 设置 onMixedAudioFrame 回调数据的格式
getRecordAudioParams 设置 onRecordAudioFrame 回调数据的格式
getPlaybackAudioParams 设置 onPlaybackAudioFrame 回调数据的格式
setRecordingAudioFrameParametersWithSampleRate 设置采集的音频格式
setPlaybackAudioFrameParametersWithSampleRate 设置播放的音频格式
setMixedAudioFrameParametersWithSampleRate 设置采集和播放的音频混音后的数据格式
事件 描述
onRecordAudioFrame 获取采集的本地用户的音频
onPlaybackAudioFrame 获取播放的所有远端用户的音频
onMixedAudioFrame 获取本地和所有远端用户混音后的音频
onPlaybackAudioFrameBeforeMixing 获取混音前单个远端用户的音频

原始视频数据

本组方法仅适用于 iOS,不适用于 macOS。如需在 macOS 上实现原始视频数据,使用 C++ 的原始视频数据 API。

方法 功能
setVideoDataFrame 注册原始视频数据协议
getVideoFormatPreference 设置 SDK 输出的原始视频数据格式
getRotationApplied 设置是否旋转 SDK 输出的原始视频数据
getMirrorApplied 设置是否镜像 SDK 输出的原始视频数据
getObservedFramePosition 设置视频观测位置
事件 描述
onCaptureVideoFrame 获取本地采集的视频数据
onPreEncodeVideoFrame 获取本地编码前的视频数据
onRenderVideoFrame 获取接收到的远端视频数据

本地视频编码数据

本组方法仅适用于 iOS,不适用于 macOS。

方法 功能
setVideoEncodedFrame 注册本地视频编码数据协议
事件 描述
onVideoEncodedFrame 获取本地视频编码数据

媒体附属信息

请不要在 AgoraRtcEngineDelegate 中实现 metadataMaxSizereadyToSendMetadataAtTimestampreceiveMetadata 回调

方法 功能
setMediaMetadataDataSource 设置媒体附属信息的 Data source
setMediaMetadataDelegate 设置媒体附属信息的 Delegate
事件 描述
metadataMaxSize 请求媒体附属信息的最大数据大小
readyToSendMetadataAtTimestamp 发送端已准备好发送媒体附属信息
receiveMetadata 接收端已收到媒体附属信息

直播视频水印

本组方法仅适用于直播场景。

方法 功能
addVideoWatermark 添加本地视频水印
clearVideoWatermarks 删除已添加的视频水印

视频截图

方法 功能
takeSnapshot 获取视频截图
事件 描述
snapshotTaken 视频截图结果回调

视频截图上传

方法 描述
enableContentInspect 开启/关闭视频截图上传

加密

方法 功能
enableEncryption 开启或关闭内置加密

音频录制

方法 功能
startAudioRecordingWithConfig 开始客户端录音
stopAudioRecording 停止客户端录音

音视频录制

方法 功能
sharedMediaRecorderWithRtcEngine 创建 AgoraMediaRecorder 实例
destroy 销毁 AgoraMediaRecorder 实例
enableMainQueueDispatch 分发/不分发回调至主队列
startRecording 开启本地音视频流录制
stopRecording 停止本地音视频流录制
事件 描述
stateDidChanged 录制状态发生改变回调
informationDidUpdated 录制信息更新回调

摄像头控制

本组方法仅适用于 iOS,不适用于 macOS。

方法 功能
switchCamera 切换前置/后置摄像头
isCameraZoomSupported 检测设备是否支持摄像头缩放功能
isCameraTorchSupported 检查设备是否支持打开闪光灯
isCameraFocusPositionInPreviewSupported 检测设备是否支持手动对焦功能
isCameraExposurePositionSupported 检测设备是否支持手动曝光功能
isCameraAutoFocusFaceModeSupported 检测设备是否支持人脸对焦功能
setCameraZoomFactor 设置摄像头缩放比例
setCameraFocusPositionInPreview 设置手动对焦位置,并触发对焦
setCameraExposurePosition 设置手动曝光位置
setCameraTorchOn 设置是否打开闪光灯
setCameraAutoFocusFaceModeEnabled 设置是否开启人脸自动对焦
事件 描述
cameraFocusDidChangedToRect 摄像头对焦区域已改变
cameraExposureDidChangedToRect 摄像头曝光区域已改变

设备管理

方法 功能
monitorDeviceChange 监控设备改变(仅适用于 macOS)
enumerateDevices 获取系统中所有的音视频设备(仅适用于 macOS)
getDeviceInfo 获取当前设备名称(仅适用于 macOS)
setDevice 指定设备(仅适用于 macOS)
getDeviceVolume 获取设备音量(仅适用于 macOS)
setDeviceVolume 设置设备音量(仅适用于 macOS)
startRecordingDeviceTest 启动音频采集设备测试(仅适用于 macOS)
stopRecordingDeviceTest 停止麦克风测试(仅适用于 macOS)
startPlaybackDeviceTest 启动音频播放设备测试(仅适用于 macOS)
stopPlaybackDeviceTest 停止播放设备测试(仅适用于 macOS)
startCaptureDeviceTest 启动视频采集设备测试(仅适用于 macOS)
stopCaptureDeviceTest 停止视频采集设备测试(仅适用于 macOS)
startAudioDeviceLoopbackTest 开始音频设备回路测试(仅适用于 macOS)
stopAudioDeviceLoopbackTest 停止音频设备回路测试(仅适用于 macOS)
getDefaultAudioDevice 获取系统默认的音频设备(仅适用于 macOS)
followSystemPlaybackDevice 设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备(仅适用于 macOS)
followSystemRecordingDevice 设置 SDK 使用的音频采集设备跟随系统默认的音频采集设备(仅适用于 macOS)
事件 描述
stateChanged 设备状态改变(仅适用于 macOS)
reportAudioDeviceTestVolume 音频设备测试回调(仅适用于 macOS)

流消息

方法 功能
createDataStream 创建数据流
sendStreamMessage 发送数据流
事件 描述
receiveStreamMessageFromUid 接收到对方数据流消息
didOccurStreamMessageErrorFromUid 接收对方数据流消息发生错误

Wi-Fi 加速

方法 功能
enableWirelessAccelerate 开启或关闭 Wi-Fi 加速功能
事件 描述
wlAccMessage 报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议
wlAccStats 报告 Wi-Fi 加速效果

代理

方法 描述
setCloudProxy 设置声网云代理服务
setLocalAccessPoint 设置本地代理
事件 描述
didProxyConnected 代理连接状态回调

其他音频控制

方法 功能
enableLoopbackRecording 开启声卡采集(仅 macOS)
setAudioSessionOperationRestriction 设置 SDK 对 Audio Session 的操作权限(仅 iOS)

其他视频控制

方法 功能
setCameraCapturerConfiguration 设置摄像头采集配置

其他方法

方法 功能
setAVSyncSource 设置发流端音画同步
enableDeepLearningDenoise 开启/关闭 AI 降噪模式
sendCustomReportMessage 自定义数据上报
getCallId 获取通话 ID
rate 给通话评分
complain 投诉通话质量
enableMainQueueDispatch 分发/不分发回调至主队列
getSdkVersion 查询 SDK 版本号
getErrorDescription 获取警告或错误描述
getNativeHandle 获取 SDK 引擎的 C++ 句柄
delegate 设置/获取回调事件

其他事件

事件 事件
didOccurWarning 发生警告
didOccurError 发生错误
didApiCallExecute API 方法已执行