Agora Objective-C API Overview

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

方法

AgoraRtcEngineKit 是 Agora SDK 的入口类，提供所有可供 App 调用的方法。

根据方法实现的功能，我们把所有方法分为以下几类。

核心方法

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播 。

方法 功能
sharedEngineWithAppId 初始化引擎
destroy 销毁 RtcEngine 实例
setChannelProfile 设置频道模式
setClientRole 设置直播场景的用户角色
joinChannelByToken 加入频道
leaveChannel 离开频道
renewToken 更新 Token
enableWebSdkInteroperability 直播场景下打开与 Web SDK 的互通
getConnectionState 获取网络连接状态

核心音频方法

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

方法 功能
enableAudio 启用音频模块
disableAudio 关闭音频模块
setAudioProfile 设置音频编码配置
adjustRecordingSignalVolume 调节录音音量
adjustPlaybackSignalVolume 调节播放音量
enableAudioVolumeIndication 启用说话者音量提示
enableLocalAudio 开关本地音频采集
muteLocalAudioStream 开关本地音频发送
muteRemoteAudioStream 接收/停止接收指定音频流
muteAllRemoteAudioStreams 接收/停止接收所有音频流
setDefaultMuteAllRemoteAudioStreams 设置是否默认接收音频流

核心视频方法

本组方法适用于声网如下产品： 视频通话和互动直播。

方法 功能
enableVideo 启用视频模块
disableVideo 关闭视频模块
setVideoEncoderConfiguration 设置视频编码配置
setupLocalVideo 设置本地视图
setupRemoteVideo 设置远端用户视图
setLocalRenderMode 设置本地视图显示模式
setRemoteRenderMode 设置远端视图显示模式
startPreview 开启视频预览
stopPreview 停止视频预览
enableLocalVideo 开关本地视频采集
muteLocalVideoStream 开关本地视频发送
muteRemoteVideoStream 接收/停止接收指定视频流
muteAllRemoteVideoStreams 接收/停止接收所有视频流
setDefaultMuteAllRemoteVideoStreams 设置是否默认接收视频流

音频播放路由

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

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

方法 功能
setDefaultAudioRouteToSpeakerphone 设置默认的音频播放路由
setEnableSpeakerphone 启用/关闭扬声器播放
isSpeakerphoneEnabled 查询扬声器启用状态

耳返设置

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

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

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

语音音效设置

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

方法 功能
setLocalVoicePitch 设置本地语音音调
setLocalVoiceEqualizationOfBandFrequency 设置本地语音音效均衡
setLocalVoiceReverbOfType 设置本地音效混响

音乐文件播放及混音设置

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

方法 功能
startAudioMixing 开始播放音乐文件
stopAudioMixing 停止播放音乐文件
pauseAudioMixing 暂停播放音乐文件
resumeAudioMixing 恢复播放音乐文件
adjustAudioMixingVolume 调节音乐文件播放音量
adjustAudioMixingPlayoutVolume 调节音乐文件的本地播放音量。
adjustAudioMixingPublishVolume 调节音乐文件的远端播放音量。
getAudioMixingDuration 获取音乐文件播放时长
getAudioMixingCurrentPosition 获取音乐文件播放进度
setAudioMixingPosition 设置音乐文件的播放位置

音效文件播放管理

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

方法 功能
getEffectsVolume 获取音效文件播放音量
setEffectsVolume 设置音效文件播放音量
setVolumeOfEffect 实时调整音效文件播放音量
playEffect 播放指定音效文件
stopEffect 停止播放指定音效文件
stopAllEffects 停止播放所有音效文件
preloadEffect 将指定音效文件预加载至内存
unloadEffect 从内存释放某个预加载的音效文件
pauseEffect 暂停音效文件播放
pauseAllEffects 暂停所有音效文件播放
resumeEffect 恢复播放指定音效文件
resumeAllEffects 恢复播放所有音效文件

音频录制

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

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

开启声卡采集

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

方法 功能
enableLoopbackRecording 开启声卡采集（仅适用于 macOS）

音频其他方法

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

方法 功能
setAudioSessionOperationRestriction 设置 SDK 对 Audio Session 的控制权限 （仅适用于 iOS）

网络相关测试

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

方法 功能
startEchoTest 开始语音通话回路测试
stopEchoTest 停止语音通话回路测试
enableLastmileTest 启用网络测试
disableLastmileTest 关闭网络测试

自定义视频模块

本组方法适用于声网如下产品： 视频通话和互动直播。

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

音频自采集（仅适用于 Push 模式）

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

方法 功能
enableExternalAudioSourceWithSampleRate 开启外部音频采集
disableExternalAudioSource 关闭外部音频采集
pushExternalAudioFrameRawData 推送外部原始音频帧
pushExternalAudioFrameSampleBuffer 推送外部 CMSampleBuffer 音频帧

音频自渲染

N/A

视频自采集（仅适用于 Push 模式）

本组方法适用于声网如下产品： 视频通话和互动直播。

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

原始音频数据处理

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

详见修改原始音视频数据。

方法 功能
setRecordingAudioFrameParametersWithSampleRate 设置录制的声音格式
setPlaybackAudioFrameParametersWithSampleRate 设置播放的声音格式
setMixedAudioFrameParametersWithSampleRate 设置录制和播放声音混音后的数据格式

原始视频数据处理

N/A

直播视频水印

本组方法仅适用于声网的互动直播产品。

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

直播音视频流回退

本组方法仅适用于声网的互动直播产品。

方法 功能
setLocalPublishFallbackOption 设置弱网条件下发布的音视频流回退选项
setRemoteSubscribeFallbackOption 设置弱网条件下订阅的音视频流回退选项

视频双流模式

本组方法适用于声网如下产品： 视频通话和互动直播。

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

加密

本组方法适用于声网如下产品： 语音通话、视频通话和互动直播。

方法 功能
setEncryptionSecret 启用内置加密，并设置数据加密密钥
setEncryptionMode 设置内置的加密方案

直播导入在线媒体流

本组方法仅适用于声网的互动直播产品。

方法 功能
addInjectStreamUrl 导入在线媒体流 URL
removeInjectStreamUrl 删除导入的在线媒体流

CDN 旁路推流

本组方法仅适用于声网的互动直播产品。

方法 功能
addPublishStreamUrl 增加旁路推流地址
removePublishStreamUrl 删除旁路推流地址
setLiveTranscoding 设置直播转码

数据流

本组方法适用于声网如下产品：语音通话、视频通话和互动直播。

方法 功能
createDataStream 创建数据流
sendStreamMessage 发送数据流

其他视频控制

本组方法适用于声网如下产品：视频通话和互动直播。

方法 功能
setVideoQualityParameters 设置视频质量偏好选项（仅适用于直播模式）
setLocalVideoMirrorMode 设置本地视频镜像模式

摄像头控制

本组方法适用于声网如下产品：视频通话和互动直播。

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

方法 功能
switchCamera 切换前置/后置摄像头
isCameraZoomSupported 检测设备是否支持摄像头缩放功能
isCameraTorchSupported 检测设备是否支持闪光灯常开
isCameraFocusPositionInPreviewSupported 检测设备是否支持手动对焦功能
isCameraExposurePositionSupported 检测设备是否支持手动曝光功能
isCameraAutoFocusFaceModeSupported 检测设备是否支持人脸对焦功能
setCameraZoomFactor 设置摄像头缩放比例
setCameraFocusPositionInPreview 设置手动对焦位置，并触发对焦
setCameraExposurePosition 设置手动曝光位置
setCameraTorchOn 设置是否打开闪光灯
setCameraAutoFocusFaceModeEnabled 设置是否开启人脸对焦功能

屏幕共享

本组方法适用于声网如下产品： 视频通话和互动直播。

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

方法 功能
startScreenCapture 开始屏幕共享
stopScreenCapture 停止屏幕共享
updateScreenCaptureRegion 更新屏幕共享区域

音视频设备管理

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

方法 功能
monitorDeviceChange 监控设备改变
enumerateDevices 获取系统中所有的音视频设备
getDeviceInfo 获取当前设备名称
setDevice 指定设备
getDeviceVolume 获取设备音量
setDeviceVolume 设置设备音量
startRecordingDeviceTest 启动麦克风测试
stopRecordingDeviceTest 停止麦克风测试
startPlaybackDeviceTest 启动播放设备测试
stopPlaybackDeviceTest 停止播放设备测试
startCaptureDeviceTest 启动视频采集设备测试
stopCaptureDeviceTest 停止视频采集设备测试

其他方法

本组方法适用于声网如下产品： 视频通话和互动直播。

方法 功能
getCallId 获取通话 ID
rate 给通话评分
complain 投诉通话质量
enableMainQueueDispatch 分发／不分发回调至主队列
getSdkVersion 查询 SDK 版本号
setLogFile 设置日志文件
setLogFilter 设置日志输出等级
getNativeHandle 获取 SDK 引擎的 C++ 句柄
delegate 设置/获取回调事件

定制方法 (Technical Preview)

方法 功能
setParameters 通过 JSON 配置 SDK 提供技术预览或特别定制功能
getParameter 获取 Agora SDK 可供自定义的参数

回调

AgoraRtcEngineDelegate 接口类采用 Delegate 方法向 App 发送回调通知。

核心事件回调

回调 事件
didOccurWarning 发生警告
didOccurError 发生错误
didApiCallExecute API 方法已执行
didJoinChannel 已加入频道
didRejoinChannel 已重新加入频道
didLeaveChannel 已离开频道
didClientRoleChanged 用户角色已切换
didJoinedOfUid 远端用户已加入频道
didOfflineOfUid 远端用户已离开频道
connectionChangedToState 网络连接状态已改变
rtcEngineConnectionDidLost 网络连接丢失
tokenPrivilegeWillExpire Token 服务即将过期
rtcEngineRequestToken Token 已过期

媒体事件回调

回调 事件
didMicrophoneEnabled 麦克风状态已改变
reportAudioVolumeIndicationOfSpeakers 提示频道内谁在说话以及说话者的音量
activeSpeaker 监测到活跃用户
firstLocalAudioFrame 已发送本地音频首帧
firstRemoteAudioFrameOfUid 已接收远端音频首帧
rtcEngineVideoDidStop 视频功能已停止
firstLocalVideoFrameWithSize 已发送本地视频首帧
firstRemoteVideoDecodedOfUid 已完成远端视频首帧解码
firstRemoteVideoFrameOfUid 已显示远端视频首帧
didAudioMuted 远端用户音频已静音/取消静音
didVideoMuted 远端用户暂停/重新发送视频流
didVideoEnabled 远端用户启用/关闭视频功能
didLocalVideoEnabled 远端用户启用/关闭本地视频
videoSizeChangedOfUid 本地或远端视频大小和旋转信息发生改变
remoteVideoStateChangedOfUid 远端用户视频流状态发生改变

音视频流回退事件回调

回调 事件
didLocalPublishFallbackToAudioOnly 本地发布流已回退为音频流或恢复为音视频流
didRemoteSubscribeFallbackToAudioOnly 远端订阅流已回退为音频流或恢复为音视频流

媒体设备事件回调

回调 事件
stateChanged 设备状态改变（仅适用于 macOS）
didAudioRouteChanged 语音路由已改变
rtcEngineCameraDidReady 摄像头启用
cameraFocusDidChangedToRect 摄像头对焦区域已改变（仅适用于 iOS）
cameraExposureDidChangedToRect 摄像头曝光区域已改变（仅适用于 iOS）

数据统计事件回调

回调 事件
remoteAudioStats 报告通话中远端音频流的统计信息
reportRtcStats 报告 Rtc Engine 统计信息
lastmileQuality 报告本地用户的网络质量
networkQuality 报告网络上下行质量
localVideoStats 报告本地视频统计信息
remoteVideoStats 报告远端视频统计信息
audioTransportStatsOfUid 报告远端音频传输统计信息
videoTransportStatsOfUid 报告远端视频传输统计信息

音频播放事件回调

回调 事件
rtcEngineLocalAudioMixingDidFinish 本地音乐文件播放已结束
rtcEngineRemoteAudioMixingDidStart 远端音乐文件播放已开始
rtcEngineRemoteAudioMixingDidFinish 远端音乐文件播放已结束
rtcEngineDidAudioEffectFinish 本地音效文件播放已结束

CDN 旁路推流事件回调

回调 事件
streamPublishedWithUrl 旁路推流已开启
streamUnpublishedWithUrl 旁路推流已停止
rtcEngineTranscodingUpdated 旁路推流设置已被更新

直播导入在线媒体流事件回调

回调 事件
streamInjectedStatusOfUrl 导入在线媒体流状态

数据流事件回调

回调 事件
receiveStreamMessageFromUid 接收到对方数据流消息
didOccurStreamMessageErrorFromUid 接收对方数据流消息发生错误

原始音频数据事件回调

N/A

原始视频数据事件回调

N/A

其他回调

回调 事件
rtcEngineMediaEngineDidLoaded 媒体引擎成功加载
rtcEngineMediaEngineDidStartCall 媒体引擎成功启动

已废弃回调

从 1.1 版本开始，Agora SDK 使用 Delegate 代替原有的 Block 回调。

原有的 Block 回调被标为废弃，目前仍然可以使用，但是 Agora 建议用相应的 Delegate 方法代替。

如果同一个回调 Block 和 Delegate 方法都有定义，则 SDK 只回调 Block 方法。

回调 事件
audioVolumeIndicationBlock 提示频道内谁在说话以及说话者的音量
firstLocalVideoFrameBlock 本地首帧视频已显示
firstRemoteVideoDecodedBlock 已收到第一帧远端视频流并解码
firstRemoteVideoFrameBlock 远端首帧视频已显示
userJoinedBlock 有用户加入了频道
userOfflineBlock 有用户离开了频道（或掉线）
userMuteAudioBlock 其他用户音频已静音/取消静音
userMuteVideoBlock 其他用户停止/恢复发送视频
localVideoStatBlock 报告本地视频统计信息
remoteVideoStatBlock 报告远端视频统计信息
cameraReadyBlock 摄像头已启用
connectionLostBlock 网络连接丢失
rejoinChannelSuccessBlock 有用户重新加入频道
rtcStatsBlock 报告 Rtc Engine 统计信息
leaveChannelBlock 已离开频道
audioQualityBlock 报告语音质量
networkQualityBlock 报告频道内网络质量
lastmileQualityBlock 报告本地用户网络质量
mediaEngineEventBlock Media engine 事件