Agora Objective-C API Overview

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

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

频道管理

方法 功能
sharedEngineWithAppId 初始化引擎
destroy 销毁 RtcEngine 实例
setChannelProfile 设置频道场景
setClientRole 设置直播场景的用户角色
joinChannelByToken 加入频道
switchChannelByToken 快速切换直播频道
leaveChannel 离开频道
renewToken 更新 Token
getConnectionState 获取网络连接状态

频道事件

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

音频管理

方法 功能
enableAudio 启用音频模块
disableAudio 关闭音频模块
setAudioProfile 设置音频编码配置
adjustRecordingSignalVolume 调节录音音量
adjustUserPlaybackSignalVolume 调节本地播放的指定远端用户音量。
adjustPlaybackSignalVolume 调节本地播放的所有远端用户音量。
enableLocalAudio 开关本地音频采集
muteLocalAudioStream 开关本地音频发送
muteRemoteAudioStream 停止/恢复接收指定音频流
muteAllRemoteAudioStreams 停止/恢复接收所有音频流
setDefaultMuteAllRemoteAudioStreams 设置是否默认接收音频流

视频管理

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

本地媒体事件

事件 描述
localAudioStateChange 本地音频状态发生改变
localVideoStateChange 本地视频状态发生改变
firstLocalAudioFrame 已发送本地音频首帧
firstLocalVideoFrameWithSize 已显示本地视频首帧

远端媒体事件

事件 描述
remoteAudioStateChangedOfUid 远端音频流状态发生改变
remoteVideoStateChangedOfUid 远端用户视频流状态发生改变

数据统计事件

  • 加入频道后,SDK 每隔 2 秒自动触发本组回调。
  • 我们为这些回调提供了详细的功能描述、实现方法文档,详情请参考《通话中质量监测》。
事件 描述
remoteAudioStats 报告通话中远端音频流的统计信息
reportRtcStats 报告 Rtc Engine 统计信息
networkQuality 报告网络上下行质量
localAudioStats 通话中本地音频流的统计信息回调
localVideoStats 报告本地视频统计信息
remoteVideoStats 报告远端视频统计信息

视频前处理及后处理

方法 功能
setBeautyEffectOptions 设置美颜效果选项(仅 iOS)

多频道管理

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

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

屏幕共享

  • 我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档,详情请参考《屏幕共享》。
  • 本组方法仅适用于macOS,不适用于 iOS。
方法 功能
startScreenCaptureByDisplayId 通过屏幕 ID 共享屏幕
startScreenCaptureByWindowId 通过窗口 ID 共享窗口
setScreenCaptureContentHint 设置屏幕共享内容类型
updateScreenCaptureParameters 更新屏幕共享的编码参数配置
updateScreenCaptureRegion 更新屏幕共享区域
stopScreenCapture 停止屏幕共享

音乐文件播放及混音

方法 功能
startAudioMixing 开始播放音乐文件
stopAudioMixing 停止播放音乐文件
pauseAudioMixing 暂停播放音乐文件
resumeAudioMixing 恢复播放音乐文件
adjustAudioMixingVolume 调节音乐文件播放音量
adjustAudioMixingPlayoutVolume 调节音乐文件的本地播放音量
adjustAudioMixingPublishVolume 调节音乐文件的远端播放音量
getAudioMixingPlayoutVolume 获取音乐文件的本地播放音量
getAudioMixingPublishVolume 获取音乐文件的远端播放音量
getAudioMixingDuration 获取音乐文件播放时长
getAudioMixingCurrentPosition 获取音乐文件播放进度
setAudioMixingPosition 设置音乐文件的播放位置
事件 描述
localAudioMixingStateDidChanged 本地音乐文件播放状态改变
rtcEngineRemoteAudioMixingDidStart 远端音乐文件播放已开始
rtcEngineRemoteAudioMixingDidFinish 远端音乐文件播放已结束

音效文件播放管理

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

变声与混响

方法 功能
setLocalVoicePitch 设置本地语音音调
setLocalVoiceEqualizationOfBandFrequency 设置本地语音音效均衡
setLocalVoiceReverbOfType 设置本地音效混响
setLocalVoiceChanger 设置本地语音变声
setLocalVoiceReverbPreset 设置预设的本地语音混响效果

听声辨位

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

CDN 推流

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

方法 功能
setLiveTranscoding 设置直播转码
addPublishStreamUrl 增加旁路推流地址
removePublishStreamUrl 删除旁路推流地址
事件 描述
rtmpStreamingChangedToState RTMP 推流状态发生改变
rtcEngineTranscodingUpdated 旁路推流设置已被更新

跨频道媒体流转发

方法 功能
startChannelMediaRelay 开始跨频道媒体流转发
updateChannelMediaRelay 更新媒体流转发的频道
stopChannelMediaRelay 停止跨频道媒体流转发
事件 描述
channelMediaRelayStateDidChange 跨频道媒体流转发状态发生改变
didReceiveChannelMediaRelayEvent 跨频道媒体流转发事件

音量提示

方法 功能
enableAudioVolumeIndication 启用说话者音量提示
事件 描述
reportAudioVolumeIndicationOfSpeakers 提示频道内谁在说话以及说话者的音量
activeSpeaker 监测到活跃用户

音频播放路由

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

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

耳返控制

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

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

视频双流模式

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

音视频流回退

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

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

通话前网络测试

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

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

自定义视频模块

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

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

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

音频自渲染

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

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

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

原始音频数据

你可以使用 C++ 的原始音频数据接口实现相关功能,详见 C++ 原始音频数据

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

原始视频数据

你可以使用 C++ 的原始视频数据接口实现相关功能,详见 C++ 原始视频数据

媒体附属信息

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

直播视频水印

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

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

加密

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

音频录制

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

直播输入在线媒体流

  • 本组方法仅适用于直播场景。
  • 我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档,详情请参考《输入在线媒体流》。
方法 功能
addInjectStreamUrl 输入在线媒体流 URL
removeInjectStreamUrl 删除输入的在线媒体流
事件 描述
streamInjectedStatusOfUrl 输入在线媒体流状态

摄像头控制

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

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

设备管理

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

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

流消息

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

其他音频控制

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

其他视频控制

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

其他方法

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

其他事件

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

定制方法 (Technical Preview)

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