Agora Objective-C API Reference for iOS/macOS

AgoraRtcEngineKit 类

Inherits from NSObject
Declared in AgoraRtcEngineKit.h

概览

提供所有可供 App 调用的方法

声网通过全球部署的虚拟网络专为 WebRTC 以及移动端到移动端的 App 进行过优化。可以为全世界的音视频通信提供质量保证的体验(QoE)。

AgoraRtcEngineKit 是 Agora SDK 的入口类。它为 App 提供了快速搭建音视频通信的 API。

核心方法

+ sharedEngineWithAppId:delegate:

初始化一个 AgoraRtcEngineKit 对象

+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString *_Nonnull)appId delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate

参数

appId

Agora 为 App 开发者签发的 App ID。每个项目都应该有一个独一无二的 App ID。如果你的开发包里没有 App ID,请从声网申请一个新的 App ID。在你调用 joinChannelByToken:channelId:info:uid:joinSuccess: 加入声网的全球网络实现一对一或一对多直播通信时需要:

  • 用 App ID 标示你的项目和所属组织
  • 用一个独一无二的频道名称
delegate

AgoraRtcEngineDelegate

返回

一个 AgoraRtcEngineKit 实例对象。

详情

该方法初始化一个 AgoraRtcEngineKit 单例。使用 AgoraRtcEngineKit,必须先调用该接口进行初始化。

Note: 请确保在调用其他 API 前先调用该方法创建并初始化 AgoraRtcEngineKit。

Warning: 必须使用同一个 App ID 才能进行通话。

Warning: 一个 AgoraRtcEngineKit 实例对象只能使用一个 App ID。如需更换 App ID,必须先调用 destroy 销毁当前实例,再调用本方法重新创建实例。

Declared In

AgoraRtcEngineKit.h

+ destroy

销毁 RtcEngine 实例

+ (void)destroy

详情

该方法用于释放 Agora SDK 使用的所有对象资源。帮助偶尔使用音视频通话的 App 在无需通话时释放资源。一旦 App 调用了 destroy 接口销毁创建的 AgoraRtcEngineKit 实例,将无法调用 SDK 内的任何方法也不再会有任何回调产生。如需重启通话,请调用初始化方法 sharedEngineWithAppId:delegate: 创建一个新的 AgoraRtcEngineKit 实例。

Note:

  • 该方法需要在子线程中操作
  • 该方法为同步调用。 App 不得在 SDK 生成的回调中调用该方法,不然 SDK 只能等候该回调返回才能重新获取相应的对象资源造成死锁。

Declared In

AgoraRtcEngineKit.h

– setChannelProfile:

设置频道模式

- (int)setChannelProfile:(AgoraChannelProfile)profile

参数

profile

频道模式。详见 AgoraChannelProfile

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

Agora SDK 需知道应用程序的使用场景(例如通信模式或直播模式), 从而使用不同的优化手段。

目前 Agora Native SDK 支持以下几种模式:

  • 通信模式 (默认)
  • 直播模式
  • 游戏语音模式 (仅适用于 Agora Gaming SDK)

Note:

  • 相同频道内的所有用户必须使用相同的频道模式。
  • 如果想要切换模式,则需要先调用 destroy 销毁当前引擎,然后在 sharedEngineWithAppId 方法重新创建引擎,再调用该方法切换频道模式。
  • 该方法必须在加入频道前调用和进行设置,进入频道后无法再设置。
  • 目前通信模式下不支持自采集的 Texture 编码,只支持原始音视频数据。

Declared In

AgoraRtcEngineKit.h

– setClientRole:

设置用户角色

- (int)setClientRole:(AgoraClientRole)role

参数

role

直播场景里的用户角色

  • AgoraClientRoleBroadcaster = 1; 主播
  • AgoraClientRoleAudience = 2; 观众(默认)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅适用于直播模式。

在加入频道前,用户需要通过本方法设置观众(默认)或主播模式。在加入频道后,用户可以通过本方法切换用户模式。

如果你在加入频道后调用该方法切换用户角色,调用成功后,本地会触发 didClientRoleChanged 回调;远端会触发 didJoinedOfUiddidOfflineOfUid(AgoraUserOfflineReasonBecomeAudience) 回调。

Declared In

AgoraRtcEngineKit.h

– joinChannelByToken:channelId:info:uid:joinSuccess:

加入频道

- (int)joinChannelByToken:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId info:(NSString *_Nullable)info uid:(NSUInteger)uid joinSuccess:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))joinSuccessBlock

参数

token

动态密钥

  • 安全要求不高: 将值设为 nil
  • 安全要求高: 将值设置为 Token。如果你已经启用了 App Certificate,请务必使用 Token。
  • 请务必确保用于生成 Token 的 App ID 和 sharedEngineWithappId 方法初始化引擎时用的是同一个 App ID。
channelId

标识通话频道的字符串,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):

  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”
info

(非必选项) 开发者需加入的任何附加信息。一般可设置为空字符串,或频道相关信息。该信息不会传递给频道内的其他用户。

uid

用户 ID,32 位无符号整数。建议设置范围:1到 (232-1),并保证唯一性。如果不填或设为 0,SDK 会自动分配一个,并在 joinSuccessBlock 回调方法中返回,App 层必须记住该返回值并维护,SDK 不对该返回值进行维护。

joinSuccessBlock

成功加入频道回调。joinSuccessBlock 优先级高于 didJoinChannel,2 个同时存在时,didJoinChannel 会被忽略。 需要有 didJoinChannel 回调时,请将 joinSuccessBlock 设置为 nil 。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 App 是不能互通的。如果已在通话中,用户必须调用 leaveChannel 退出当前通话,才能进入下一个频道。SDK 在通话中使用 iOS 系统的 AVAudioSession 共享对象进行录音和播放, App 对该对象的操作可能会影响 SDK 的音频相关功能。

调用该 API 后会触发 joinSuccessBlock 或 didJoinChannel 回调。block 比 delegate 优先级高,如果两种回调都实现了,只有 block 会触发。

我们建议你将 joinSuccessBlock 设置为 nil,使用 delegate 回调。

加入频道后,本地会触发 didJoinChannel 回调;通信模式下的用户和直播模式下的主播加入频道后,远端会触发 didJoinedOfUid 回调。

在网络状况不理想的情况下,客户端可能会与 Agora 的服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 didRejoinChannel 回调。

Note:

  • 频道内每个用户的 UID 必须是唯一的。如果将 UID 设为 0,系统将自动分配一个 UID。如果想要从不同的设备同时接入同一个频道,请确保每个设备上使用的 UID 是不同的。
  • 在加入频道时,SDK 调用 setCategory(AVAudioSessionCategoryPlayAndRecord) 将 AVAudioSession 设置到 PlayAndRecord 模式, App 不应将其设置到其他模式。设置该模式时,正在播放的声音会被打断(比如正在播放的响铃声)。

Declared In

AgoraRtcEngineKit.h

– joinChannelByUserAccount:token:channelId:joinSuccess:

使用 User Account 加入频道

- (int)joinChannelByUserAccount:(NSString *_Nonnull)userAccount token:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId joinSuccess:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))joinSuccessBlock

参数

userAccount

用户 User Account。该参数为必需,最大不超过 255 字节,不可为 null。请确保加入频道的 User Account 的唯一性。 以下为支持的字符集范围(共 89 个字符):

  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ {”, “}”, “|”, “~”, “,”
token

在你的服务器端生成的用于鉴权的 Token:

  • 安全要求不高:你可以使用 Dashboard 生成的临时 Token,详见获取临时 Token
  • 安全要求高:将值设为你的服务端生成的正式 Token,详见获取正式 Token
channelId

标识通话频道的字符串,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):

  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”
joinSuccessBlock

成功加入频道回调。joinSuccessBlock 优先级高于 didJoinChannel,2 个同时存在时,didJoinChannel 会被忽略。 需要有 didJoinChannel 回调时,请将 joinSuccessBlock 设置为 nil 。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法允许本地用户使用 User Account 加入频道。成功加入频道后,会触发以下回调:

Note: 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Agora Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。

Declared In

AgoraRtcEngineKit.h

– registerLocalUserAccount:appId:

注册本地用户 User Account

- (int)registerLocalUserAccount:(NSString *_Nonnull)userAccount appId:(NSString *_Nonnull)appId

参数

userAccount

用户 User Account。该参数为必填,最大不超过 255 字节,不可填 null。请确保注册的 User Account 的唯一性。 以下为支持的字符集范围(共 89 个字符):

  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ {”, “}”, “|”, “~”, “,”.
appId

你的项目在 Agora Dashboard 注册的 App ID

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法为本地用户注册一个 User Account。注册成功后,该 User Account 即可标识该本地用户的身份,用户可以使用它加入频道。成功注册 User Account 后,本地会触发 didRegisteredLocalUser 回调,告知本地用户的 UID 和 User Account。

该方法为可选。如果你希望用户使用 User Account 加入频道,可以选用以下两种方式:

两种方式的区别在于,提前调用 registerLocalUserAccount,可以缩短使用 joinChannelByUserAccount 进入频道的时间。

Note:

  • userAccount 不能为空,否则该方法不生效。
  • 请确保在该方法中设置的 userAccount 在频道中的唯一性。
  • 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Agora Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。

Declared In

AgoraRtcEngineKit.h

– getUserInfoByUserAccount:withError:

通过 User Account 获取用户信息

- (AgoraUserInfo *_Nullable)getUserInfoByUserAccount:(NSString *_Nonnull)userAccount withError:(AgoraErrorCode *_Nullable)error

参数

userAccount

用户 User Account。该参数为必填。

error

AgoraErrorCode 的指针,可以为空。

返回

一个包含了用户 User Account 和 UID 的 AgoraUserInfo 对象

详情

远端用户加入频道后,SDK 会获取到该用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的映射表,并在本地触发 didUpdatedUserInfo 回调。

收到这个回调后,你可以调用该方法,通过传入 User Account 获取包含了指定用户 UID 的 AgoraUserInfo 对象。

Declared In

AgoraRtcEngineKit.h

– getUserInfoByUid:withError:

通过 UID 获取用户信息

- (AgoraUserInfo *_Nullable)getUserInfoByUid:(NSUInteger)uid withError:(AgoraErrorCode *_Nullable)error

参数

uid

用户 UID。该参数为必填

error

AgoraErrorCode 的指针,可以为空。

返回

一个包含了用户 User Account 和 UID 的 AgoraUserInfo 对象

详情

远端用户加入频道后,SDK 会获取到该用户的 UID 和 User Account,然后缓存一个包含了用户 UID 和 User Account 的映射表,并在本地触发 didUpdatedUserInfo 回调。

收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 AgoraUserInfo 对象。

Declared In

AgoraRtcEngineKit.h

– switchChannelByToken:channelId:joinSuccess:

快速切换直播频道。

- (int)switchChannelByToken:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId joinSuccess:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))joinSuccessBlock

参数

token

在服务器端生成的用于鉴权的 Token:

  • 安全要求不高:你可以使用 Dashboard 生成的临时 Token,详见 获取临时 Token
  • 安全要求高:将值设为你的服务端生成的正式 Token,详见 获取正式 Token
channelId

标识频道的频道名,最大不超过 64 字节。以下为支持的字符集范围(共 89 个字符):

  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • “!",”#“,”$“,”%“,”&“,”(“,”)“,”+“,”-“,”:“,”;“,”<“,”=“,”.“,”>“,”?“,”@“,”[“,”]“,”^“,”_“,” {“, ”}“,”|“,”~“,”,"
joinSuccessBlock

成功加入频道回调。joinSuccessBlock 优先级高于 didJoinChannel,2 个同时存在时,didJoinChannel 会被忽略。 需要有 didJoinChannel 回调时,请将 joinSuccessBlock 设置为 nil 。

返回

  • 0:方法调用成功
  • < 0:方法调用失败

详情

当直播频道中的观众想从一个频道切换到另一个频道时,可以调用该方法,实现快速切换。

成功调用该方切换频道后,本地会先收到离开原频道的回调 didLeaveChannelWithStats,再收到成功加入新频道的回调 didJoinChannel

Note: 该方法仅适用直播频道中的观众用户。

Declared In

AgoraRtcEngineKit.h

– leaveChannel:

离开频道

- (int)leaveChannel:(void ( ^ _Nullable ) ( AgoraChannelStats *_Nonnull stat ))leaveChannelBlock

参数

leaveChannelBlock

成功离开频道的回调,提供通话相关的统计信息,详见 AgoraChannelStats

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

离开频道,即挂断或退出通话。

当调用 joinChannelByToken 方法后,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。 不管当前是否在通话中,都可以调用本方法,没有副作用。该方法会把会话相关的所有资源释放掉。该方法是异步操作,调用返回时并没有真正退出频道。

成功调用该方法离开频道后,本地会触发 didLeaveChannelWithStats 回调;通信模式下的用户和直播模式下的主播离开频道后,远端会触发 didOfflineOfUid(AgoraUserOfflineReasonBecomeAudience) 回调。

Note:

  • 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 didLeaveChannelWithStats 回调。
  • 如果你在旁路推流时调用本方法, SDK 将自动调用 removePublishStreamUrl 方法。
  • 在调用本方法时,iOS 默认情况下 SDK 会停用 audio session,可能会对其他应用程序造成影响。如果想改变这种默认行为,可以通过setAudioSessionOperationRestriction 方法设置 AgoraAudioSessionOperationRestrictionDeactivateSession,这样在 leaveChannel 时,SDK 不会停用 audio session。

Declared In

AgoraRtcEngineKit.h

– renewToken:

更新 Token

- (int)renewToken:(NSString *_Nonnull)token

参数

token

新的 Token

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法用于更新 Token。如果启用了 Token 机制,过一段时间后使用的 Token 会失效。当以下任意一种情况发生时:

App 应重新获取 Token,然后调用该 API 更新 Token,否则 SDK 无法和服务器建立连接。

Declared In

AgoraRtcEngineKit.h

– enableWebSdkInteroperability:

打开与 Web SDK 的互通

- (int)enableWebSdkInteroperability:(BOOL)enabled

参数

enabled

是否已打开与 Agora Web SDK 的互通:

  • YES: 打开互通
  • NO: 关闭互通(默认)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅适用于直播模式。通信模式默认与 Web SDK 互通,无需调用该方法。

Declared In

AgoraRtcEngineKit.h

– getConnectionState

获取当前网络连接状态

- (AgoraConnectionStateType)getConnectionState

返回

当前的网络连接状态,详见 AgoraConnectionStateType

Declared In

AgoraRtcEngineKit.h

– startChannelMediaRelay:

开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。

- (int)startChannelMediaRelay:(AgoraChannelMediaRelayConfiguration *_Nonnull)config

参数

config

跨频道媒体流转发参数配置: AgoraChannelMediaRelayConfiguration 类。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

成功调用该方法后,SDK 会触发 channelMediaRelayStateDidChangedidReceiveChannelMediaRelayEvent 回调,并在回调中报告当前的跨频道媒体流转发状态和事件。

  • 如果 channelMediaRelayStateDidChange 回调报告 AgoraChannelMediaRelayStateRunning(2) 和 AgoraChannelMediaRelayStateIdle(0),且 didReceiveChannelMediaRelayEvent 回调报告 AgoraChannelMediaRelayEventSentToDestinationChannel(4),则表示 SDK 开始在源频道和目标频道之间转发媒体流。
  • 如果 channelMediaRelayStateDidChange 回调报告 AgoraChannelMediaRelayStateFailure(3),则表示跨频道媒体流转发出现异常。

Note

  • 请在成功加入频道后调用该方法。
  • 该方法仅对直播模式下的主播有效。
  • 成功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。

Declared In

AgoraRtcEngineKit.h

– updateChannelMediaRelay:

更新媒体流转发的频道。成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。 * * 成功调用该方法后,SDK 会触发 channelMediaRelayStateDidChange 回调,并在回调中报告状态码 AgoraChannelMediaRelayEventUpdateDestinationChannel(7)。

- (int)updateChannelMediaRelay:(AgoraChannelMediaRelayConfiguration *_Nonnull)config

参数

config

跨频道媒体流转发参数配置: AgoraChannelMediaRelayConfiguration 类。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

Note

  • 请在 startChannelMediaRelay 方法后调用该方法,更新媒体流转发的频道。
  • 跨频道媒体流转发最多支持 4 个目标频道。如果直播间里已经有 4 个频道了,你可以在调用该方法之前,调用 AgoraChannelMediaRelayConfiguration 中的 removeDestinationInfoForChannelName 方法移除不需要的频道。

Declared In

AgoraRtcEngineKit.h

– stopChannelMediaRelay

停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。

- (int)stopChannelMediaRelay

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

成功调用该方法后,SDK 会触发 channelMediaRelayStateDidChange 回调。如果报告 AgoraChannelMediaRelayStateIdle(0) 和 AgoraChannelMediaRelayErrorNone(0),则表示已停止转发媒体流。

Note: 如果该方法调用不成功,SDK 会触发 channelMediaRelayStateDidChange 回调,并报告状态码 AgoraChannelMediaRelayErrorServerNoResponse(2) 或 AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8)。你可以调用 leaveChannel 方法离开频道,跨频道媒体流转发会自动停止。

Declared In

AgoraRtcEngineKit.h

音频核心方法

– enableAudio

启用音频模块

- (int)enableAudio

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

本方法可以启用音频模块。(音频模块默认为开启状态)

Note:

  • 该方法设置的是内部引擎为开启状态,在频道内和频道外均可调用,且在 leaveChannel 后仍然有效。

  • 该方法重置整个引擎,响应速度较慢,因此 Agora 建议使用如下方法来控制音频模块:

Declared In

AgoraRtcEngineKit.h

– disableAudio

关闭音频模块

- (int)disableAudio

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

Note:

  • 该方法设置的是内部引擎为禁用状态,在频道内和频道外均可调用,且在 leaveChannel 后仍然有效。

  • 该方法重置整个引擎,响应速度较慢,因此 Agora 建议使用如下方法来控制音频模块:

Declared In

AgoraRtcEngineKit.h

– setAudioProfile:scenario:

设置音频编码配置

- (int)setAudioProfile:(AgoraAudioProfile)profile scenario:(AgoraAudioScenario)scenario

参数

profile

AgoraAudioProfile

scenario

设置音频应用场景,详细定义见 AgoraAudioScenario。不同的音频场景下,设备的系统音量是不同的。详见 如何区分媒体音量和通话音量

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

Note:

  • 该方法需要在 joinChannelByToken 之前设置好,joinChannelByToken 之后设置不生效
  • 通信模式下,该方法设置 profile 生效,设置 scenario 不生效
  • 通信和直播模式下,音质(码率)会有网络自适应的调整,通过该方法设置的是一个最高码率
  • 音乐教学场景下,建议将 profile 设置为 AgoraAudioProfileMusicHighQuality(4),scenario 设置为 AgoraAudioScenarioGameStreaming(3)

Declared In

AgoraRtcEngineKit.h

– adjustRecordingSignalVolume:

调节录音音量

- (int)adjustRecordingSignalVolume:(NSInteger)volume

参数

volume

录音音量可在 0~400 范围内进行调节:

  • 0: 静音
  • 100: 原始音量
  • 400: 最大可为原始音量的 4 倍(自带溢出保护)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– adjustPlaybackSignalVolume:

调节播放人声的音量。

- (int)adjustPlaybackSignalVolume:(NSInteger)volume

参数

volume

播放人声的音量可在 0~400 范围内进行调节:

  • 0: 静音
  • 100: 原始音量
  • 400: 最大可为原始音量的 4 倍(自带溢出保护)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– enableAudioVolumeIndication:smooth:

启用说话者音量提示

- (int)enableAudioVolumeIndication:(NSInteger)interval smooth:(NSInteger)smooth

参数

interval

指定音量提示的时间间隔:

  • <= 0: 禁用音量提示功能
  • > 0: 提示间隔,单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒。启用该方法后,无论频道内是否有人说话,都会在 reportAudioVolumeIndicationOfSpeakersaudioVolumeIndicationBlock 回调中按设置的时间间隔返回音量提示。
smooth

指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3,数字越大,波动越灵敏;数字越小,波动越平滑。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法允许 SDK 定期向 App 反馈当前谁在说话以及说话者的音量。

Declared In

AgoraRtcEngineKit.h

– enableLocalAudio:

开关本地音频采集

- (int)enableLocalAudio:(BOOL)enabled

参数

enabled
  • YES: 重新开启本地语音功能,即开启本地语音采集(默认)
  • NO: 关闭本地语音功能,即停止本地语音采集或处理

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

当 App 加入频道时,它的语音功能默认是开启的。该方法可以关闭或重新开启本地语音功能,即停止或重新开始本地音频采集。

该方法不影响接收或播放远端音频流,enableLocalAudio(NO) 适用于只听不发的用户场景。

语音功能关闭或重新开启后,会收到回调 didMicrophoneEnabled

该方法需要在 joinChannelByToken 之后调用才能生效。

该方法与 muteLocalAudioStream 的区别在于:

Declared In

AgoraRtcEngineKit.h

– muteLocalAudioStream:

开关本地音频发送

- (int)muteLocalAudioStream:(BOOL)mute

参数

mute
  • YES: 停止发送本地音频流
  • NO: (默认)继续发送本地音频流

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法用于允许/禁止往网络发送本地音频流。成功调用该方法后,远端会触发 didAudioMuted 回调。

Note:

该方法不影响录音状态,并没有禁用麦克风。

Declared In

AgoraRtcEngineKit.h

– muteRemoteAudioStream:mute:

停止/恢复接收指定用户的音频流

- (int)muteRemoteAudioStream:(NSUInteger)uid mute:(BOOL)mute

参数

uid

指定用户的用户 ID

mute
  • YES: 停止接收指定音频流
  • NO: 继续接收指定音频流(默认)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

Note:

如果之前有调用过 muteAllRemoteAudioStreams(YES) 对所有远端音频进行静音,在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams(NO) 。 muteAllRemoteAudioStreams 是全局控制,muteRemoteAudioStream 是精细控制。

Declared In

AgoraRtcEngineKit.h

– muteAllRemoteAudioStreams:

停止/恢复接收所有远端音频流

- (int)muteAllRemoteAudioStreams:(BOOL)mute

参数

mute
  • YES: 停止接收所有远端音频流
  • NO: 继续接收所有远端音频流(默认)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– setDefaultMuteAllRemoteAudioStreams:

设置是否默认接收音频流

- (int)setDefaultMuteAllRemoteAudioStreams:(BOOL)mute

参数

mute
  • YES: 默认停止接收所有远端音频流
  • NO: 默认继续接收所有远端音频流(默认)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法在加入频道前后都可调用。如果加入频道后调用该方法,会收不到后面加入频道的用户的音频流。

Declared In

AgoraRtcEngineKit.h

视频核心方法

– enableVideo

启用视频模块

- (int)enableVideo

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法用于打开视频模式。可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启视频模式,在通话中调用则由音频模式切换为视频模式。调用 disableVideo 方法可关闭视频模式。

成功调用该方法后,远端会触发 didVideoEnabled(YES) 回调。

Note:

Declared In

AgoraRtcEngineKit.h

– disableVideo

关闭视频模块

- (int)disableVideo

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法用于关闭视频。可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启纯音频模式,在通话中调用则由视频模式切换为纯音频模式。调用 enableVideo 方法可开启视频模式。

成功调用该方法后,远端会触发 didVideoEnabled(NO) 回调。

Note:

Declared In

AgoraRtcEngineKit.h

– setVideoEncoderConfiguration:

设置视频编码配置

- (int)setVideoEncoderConfiguration:(AgoraVideoEncoderConfiguration *_Nonnull)config

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法设置视频编码配置。每个配置对应一套视频参数,如分辨率、帧率、码率、视频方向等。 所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时,会取最接近最大值的那个值。

如果加入频道后不需要重新设置视频编码配置,Agora 建议在 enableVideo 之前调用该方法,可以加快首帧出图时间。

Note:

在 v2.3.0 版本中,如下接口已废弃,Agora 不再推荐使用:

Declared In

AgoraRtcEngineKit.h

– setupLocalVideo:

设置本地视图

- (int)setupLocalVideo:(AgoraRtcVideoCanvas *_Nullable)local

参数

local

通过 AgoraRtcVideoCanvas 设置本地视频显示属性。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法设置本地视频显示信息。 App 通过调用此接口绑定本地视频流的显示视图(view),并设置视频显示模式。 在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入频道。退出频道后,绑定仍然有效,如果需要解除绑定,可以指定空(NIL)View 调用本方法。

Declared In

AgoraRtcEngineKit.h

– setupRemoteVideo:

设置远端用户视图

- (int)setupRemoteVideo:(AgoraRtcVideoCanvas *_Nonnull)remote

参数

remote

通过 AgoraRtcVideoCanvas 设置远端视频显示属性:

  • view 视频显示视窗
  • renderMode: 视频显示模式
    • AgoraVideoRenderModeHidden (1):优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
    • AgoraVideoRenderModeFit (2):优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
  • uid: 用户 ID,指定要显示视窗的远端用户。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法绑定远端用户和显示视图,即设定 uid 指定的用户用哪个视图显示。调用该接口时需要指定远端用户的 uid,一般可以在进频道前提前设置好。

如果 App 不能事先知道对方的 uid,可以在 APP 收到 didJoinedOfUid 事件时设置。如果启用了视频录制功能,视频录制服务会做为一个哑客户端加入频道,因此其他客户端也会收到它的 didJoinedOfUid 事件,App 不应给它绑定视图(因为它不会发送视频流),如果 App 不能识别哑客户端,可以在 firstRemoteVideoDecodedOfUid 事件时再绑定视图。解除某个用户的绑定视图可以把 view 设置为空。退出频道后,SDK 会把远端用户的绑定关系清除掉。

Declared In

AgoraRtcEngineKit.h

– setLocalRenderMode:

设置本地视图显示模式

- (int)setLocalRenderMode:(AgoraVideoRenderMode)mode

参数

mode

本地视图显示模式,详见 AgoraVideoRenderMode

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。

Declared In

AgoraRtcEngineKit.h

– setRemoteRenderMode:mode:

设置远端视图显示模式

- (int)setRemoteRenderMode:(NSUInteger)uid mode:(AgoraVideoRenderMode)mode

参数

uid

远端用户 UID

mode

AgoraVideoRenderMode 视图显示模式

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法设置远端视图显示模式。 App 可以多次调用此方法更改显示模式。

Declared In

AgoraRtcEngineKit.h

– startPreview

开启视频预览

- (int)startPreview

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法用于在进入频道前启动本地视频预览。本地预览默认开启镜像功能。

调用该 API 前,必须

启用了本地视频预览后,如果调用 leaveChannel 退出频道,本地预览依然处于启动状态,如需要关闭本地预览,需要调用 stopPreview

Declared In

AgoraRtcEngineKit.h

– stopPreview

停止本地视频预览

- (int)stopPreview

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– enableLocalVideo:

开关本地视频采集

- (int)enableLocalVideo:(BOOL)enabled

参数

enabled

是否启用本地视频:

  • YES: 开启本地视频采集和渲染(默认)
  • NO: 关闭使用本地摄像头设备。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为 NO 时,该方法不需要本地有摄像头。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法禁用/启用本地视频功能。enableLocalVideo(NO) 适用于只看不发的视频场景。

请在 enableVideo 后调用本方法,否则本方法可能无法正常使用。

调用 enableVideo 后,本地视频默认开启。使用该方法可以开启或关闭本地视频采集,且不影响接收远端视频。

成功调用该方法后,远端会触发 didLocalVideoEnabled 回调。

Note:

该方法设置的是内部引擎为启用/禁用状态,在 leaveChannel 后仍然有效。

Declared In

AgoraRtcEngineKit.h

– muteLocalVideoStream:

开关本地视频发送

- (int)muteLocalVideoStream:(BOOL)mute

参数

mute
  • YES: 不发送本地视频流
  • NO: 发送本地视频流(默认)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

调用该方法时,SDK 不再发送本地视频流,但摄像头仍然处于工作状态。相比于 enableLocalVideo 用于控制本地视频流发送的方法,该方法响应速度更快。

该方法不影响本地视频流获取,没有禁用摄像头。

成功调用该方法后,远端会触发 didVideoMuted 回调。

Declared In

AgoraRtcEngineKit.h

– muteAllRemoteVideoStreams:

停止/恢复接收所有视频流

- (int)muteAllRemoteVideoStreams:(BOOL)mute

参数

mute
  • YES: 停止接收所有视频流
  • NO: 允许接收所有视频流(默认)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法用于禁止/允许接收所有人的视频流。

Declared In

AgoraRtcEngineKit.h

– muteRemoteVideoStream:mute:

停止/恢复接收指定视频流

- (int)muteRemoteVideoStream:(NSUInteger)uid mute:(BOOL)mute

参数

uid

远端用户ID

mute
  • YES: 停止接收指定用户的视频流
  • NO: 允许接收指定用户的视频流(默认)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

Note:

如果之前有调用过 muteAllRemoteVideoStreams (YES) 暂停接收所有远端视频,在调用本 API 之前请确保你已调用 muteAllRemoteVideoStreams (NO)。 muteAllRemoteVideoStreams 是全局控制,muteRemoteVideoStream 是精细控制。

Declared In

AgoraRtcEngineKit.h

– setDefaultMuteAllRemoteVideoStreams:

设置是否默认接收视频流

- (int)setDefaultMuteAllRemoteVideoStreams:(BOOL)mute

参数

mute
  • YES: 默认不接收
  • NO: 默认接收

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

视频前处理及后处理

– setBeautyEffectOptions:options:

设置美颜效果选项 (仅支持 iOS)

- (int)setBeautyEffectOptions:(BOOL)enable options:(AgoraBeautyOptions *_Nullable)options

参数

enable

是否开启美颜功能:

  • YES:开启
  • NO:(默认)关闭
options

美颜选项,详见 AgoraBeautyOptions

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

开启本地美颜功能,并设置美颜效果选项。

Declared In

AgoraRtcEngineKit.h

音频播放路由

– setDefaultAudioRouteToSpeakerphone:

设置默认的语音路由

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker

参数

defaultToSpeaker
  • YES: 从扬声器出声
  • NO: 从听筒出声

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法设置接收到的语音从听筒或扬声器出声。如果用户不调用本方法,语音默认从听筒出声。

Note:

  • 该方法仅适用于 iOS。
  • 该方法只在纯音频模式下工作,在有视频的模式下不工作。
  • 该方法需要在 joinChannelByToken 前设置,否则不生效。

各频道模式下默认的语音路由:

Declared In

AgoraRtcEngineKit.h

– setEnableSpeakerphone:

启用/关闭扬声器播放

- (int)setEnableSpeakerphone:(BOOL)enableSpeaker

参数

enableSpeaker
  • YES: 切换到外放。
  • NO: 切换到听筒。如果设备连接了耳机,则语音路由走耳机。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法设置是否将语音路由到扬声器(外放)。调用该方法后,SDK 将返回 didAudioRouteChanged 回调提示状态已更改。

Note:

  • 该方法仅适用于 iOS。
  • 请确保在调用此方法前已调用过 joinChannelByToken 方法。
  • SDK 会调用 setCategory(AVAudioSessionCategoryPlayAndRecord) 并配置耳麦或者外放,所以调用该方法后所有声音的路由都会按照该方法设置。

Declared In

AgoraRtcEngineKit.h

– isSpeakerphoneEnabled

查询扬声器启用状态

- (BOOL)isSpeakerphoneEnabled

返回

  • YES: 扬声器已开启,语音会输出到扬声器
  • NO: 扬声器未开启,语音会输出到非扬声器(听筒、耳机等)

详情

该方法仅适用于 iOS。

Declared In

AgoraRtcEngineKit.h

耳返设置

– enableInEarMonitoring:

开启耳返功能

- (int)enableInEarMonitoring:(BOOL)enabled

参数

enabled
  • YES: 开启耳返功能
  • (默认)NO: 关闭耳返功能

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅适用于 iOS 平台。

Declared In

AgoraRtcEngineKit.h

– setInEarMonitoringVolume:

设置耳返音量

- (int)setInEarMonitoringVolume:(NSInteger)volume

参数

volume

设置耳返音量,取值范围在 [0,100]。默认值为 100

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅适用于 iOS 平台。

Declared In

AgoraRtcEngineKit.h

语音音效设置

– setLocalVoicePitch:

设置本地语音音调

- (int)setLocalVoicePitch:(double)pitch

参数

pitch

语音频率。可以在 [0.5,2.0] 范围内设置。取值越小,则音调越低。默认值为 1.0,表示不需要修改音调。

返回

  • 0: 方法调用成功
  • -1: 方法调用失败

详情

该方法改变本地说话人声音的音调。

Declared In

AgoraRtcEngineKit.h

– setLocalVoiceEqualizationOfBandFrequency:withGain:

设置本地语音音效均衡

- (int)setLocalVoiceEqualizationOfBandFrequency:(AgoraAudioEqualizationBandFrequency)bandFrequency withGain:(NSInteger)gain

参数

bandFrequency

频谱子带索引,取值范围是 [0,9],分别代表 10 个 频带,对应的中心频率是 [31,62,125,250,500,1k,2k,4k,8k,16k] Hz,详见 AgoraAudioEqualizationBandFrequency

gain

每个 band 的增益,单位是 dB,每一个值的范围是 [-15,15],默认值为 0。

返回

  • 0: 方法调用成功
  • -1: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– setLocalVoiceReverbOfType:withValue:

设置本地音效混响

- (int)setLocalVoiceReverbOfType:(AgoraAudioReverbType)reverbType withValue:(NSInteger)value

参数

reverbType

混响音效类型,详见 AgoraAudioReverbType

value

设置混响音效的效果数值,各混响音效对应的取值范围请参考 AgoraAudioReverbType

返回

  • 0: 方法调用成功
  • -1: 方法调用失败

详情

Agora SDK 在 v2.4.0 版本中提供一个使用更为简便的接口 setLocalVoiceReverbPreset,通过一系列内置参数的调整,直接实现流行、R&B、摇滚、嘻哈等预置的混响效果。

Declared In

AgoraRtcEngineKit.h

– setLocalVoiceChanger:

设置本地语音变声

- (int)setLocalVoiceChanger:(AgoraAudioVoiceChanger)voiceChanger

参数

voiceChanger

预设本地语音变声效果选项,详见 AgoraAudioVoiceChanger

返回

  • 0: 方法调用成功
  • -1: 方法调用失败

详情

设置本地语音的变声效果选项。

Note:

该方法不能与 setLocalVoiceReverbPreset 方法同时使用,否则先调的方法会不生效。

Declared In

AgoraRtcEngineKit.h

– setLocalVoiceReverbPreset:

设置本地语音混响

- (int)setLocalVoiceReverbPreset:(AgoraAudioReverbPreset)reverbPreset

参数

reverbPreset

预设的本地语音混响效果选项,详见 AgoraAudioReverbPreset

返回

  • 0: 方法调用成功
  • -1: 方法调用失败

详情

设置预置的本地语音的混响效果选项。

Note:

Declared In

AgoraRtcEngineKit.h

– enableSoundPositionIndication:

开启/关闭远端用户的语音立体声。

- (int)enableSoundPositionIndication:(BOOL)enabled

参数

enabled

是否开启远端用户语音立体声: - YES:开启 - NO:关闭

返回

  • 0: 方法调用成功
  • -1: 方法调用失败

详情

如果想调用 setRemoteVoicePosition 实现听声辨位的功能,请确保在加入频道前调用本方法开启远端用户的语音立体声。

Declared In

AgoraRtcEngineKit.h

– setRemoteVoicePosition:pan:gain:

设置远端用户的语音位置

- (int)setRemoteVoicePosition:(NSUInteger)uid pan:(double)pan gain:(double)gain

参数

uid

远端用户的 ID

pan

设置远端用户声音的空间位置,取值范围为 [-1.0,1.0]:

  • (默认)0.0:声音出现在正前方
  • -1.0:声音出现在左边
  • 1.0:声音出现在右边
gain

设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低。

返回

  • 0: 方法调用成功
  • -1: 方法调用失败

详情

设置远端用户声音的空间位置和音量,方便本地用户听声辨位。

通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。

Note:

  • 使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声
  • 为获得最佳听觉体验,我们建议:

    • 在 iOS 使用该方法时佩戴耳机
    • 在 macOS 使用该方法时使用立体声外放

Declared In

AgoraRtcEngineKit.h

音乐文件播放及混音设置

– startAudioMixing:loopback:replace:cycle:

开始播放音乐文件

- (int)startAudioMixing:(NSString *_Nonnull)filePath loopback:(BOOL)loopback replace:(BOOL)replace cycle:(NSInteger)cycle

参数

filePath

指定需要混音的音频文件名和文件路径名。支持以下音频格式: mp3,aac,m4a,3gp,wav

loopback
  • YES: 只有本地可以听到混音或替换后的音频流
  • NO: 本地和对方都可以听到混音或替换后的音频流
replace
  • YES: 只推送设置的本地音频文件或者线上音频文件,不传输麦克风收录的音频。
  • NO: 音频文件内容将会和麦克风采集的音频流进行混音
cycle

指定音频文件循环播放的次数:

  • 正整数: 循环的次数
  • -1:无限循环

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

指定本地或在线音频文件来和麦克风采集的音频流进行混音或替换。替换是指用指定的音频文件替换麦克风采集到的音频流。该方法可以选择是否让对方听到本地播放的音频,并指定循环播放的次数。

成功调用该方法后,本地会触发 localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying) 回调。播放结束后,会收到 localAudioMixingStateDidChanged(AgoraAudioMixingStateStopped) 回调。

Note:

  • 使用本方法前请确保你的 iOS 设备版本不低于 8.0。
  • 请在频道内调用该方法,如果在频道外调用该方法可能会出现问题。
  • 如果播放的是在线音乐文件,请确保重复调用该 API 的间隔超过 100 ms,否则 SDK 会返回 AudioFileOpenTooFrequent(702)警告码,表示音乐文件打开过于频繁。
  • 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 AgoraWarningCodeAudioMixingOpenError = 701

Declared In

AgoraRtcEngineKit.h

– stopAudioMixing

停止播放音乐文件

- (int)stopAudioMixing

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

请在频道内调用该方法。

Declared In

AgoraRtcEngineKit.h

– pauseAudioMixing

暂停播放音乐文件

- (int)pauseAudioMixing

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

请在频道内调用该方法。

Declared In

AgoraRtcEngineKit.h

– resumeAudioMixing

恢复播放音乐文件

- (int)resumeAudioMixing

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

请在频道内调用该方法。

Declared In

AgoraRtcEngineKit.h

– adjustAudioMixingVolume:

调节音乐文件的播放音量

- (int)adjustAudioMixingVolume:(NSInteger)volume

参数

volume

音乐文件播放音量范围为 0~100。默认 100 为原始文件音量

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法调节混音的音乐文件在本地和远端播放的音量大小。请在频道内调用该方法。

Declared In

AgoraRtcEngineKit.h

– adjustAudioMixingPlayoutVolume:

调节音乐文件在本地播放的音量

- (int)adjustAudioMixingPlayoutVolume:(NSInteger)volume

参数

volume

音乐文件播放音量范围为 0~100。默认 100 为原始文件音量

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法调节混音的音乐文件在本地播放的音量大小。请在频道内调用该方法。

Declared In

AgoraRtcEngineKit.h

– adjustAudioMixingPublishVolume:

调节音乐文件在远端播放的音量

- (int)adjustAudioMixingPublishVolume:(NSInteger)volume

参数

volume

音乐文件播放音量范围为 0~100。默认 100 为原始文件音量

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法调节混音的音乐文件在远端播放的音量大小。请在频道内调用该方法。

Declared In

AgoraRtcEngineKit.h

– getAudioMixingPlayoutVolume

获取音乐文件的本地播放音量

- (int)getAudioMixingPlayoutVolume

返回

  • 方法调用成功则返回音量值,范围为 [0,100]
  • <0:方法调用失败

详情

该方法获取混音的音乐文件本地播放音量,方便排查音量相关问题。

Declared In

AgoraRtcEngineKit.h

– getAudioMixingPublishVolume

获取音乐文件的远端播放音量

- (int)getAudioMixingPublishVolume

返回

  • 方法调用成功则返回音量值,范围为 [0,100]
  • <0:方法调用失败

详情

该方法获取混音的音乐文件远端播放音量,方便排查音量相关问题。

Declared In

AgoraRtcEngineKit.h

– getAudioMixingDuration

获取音乐文件时长

- (int)getAudioMixingDuration

返回

  • 方法调用成功返回音乐文件时长
  • < 0: 方法调用失败

详情

该方法获取音乐文件时长,单位为毫秒。请在频道内调用该方法。如果返回值 < 0,表明调用失败。

Declared In

AgoraRtcEngineKit.h

– getAudioMixingCurrentPosition

获取音乐文件播放进度,单位为毫秒。

- (int)getAudioMixingCurrentPosition

返回

  • 方法调用成功返回音乐文件播放进度
  • < 0: 方法调用失败

详情

请在频道内调用该方法。

Declared In

AgoraRtcEngineKit.h

– setAudioMixingPosition:

设置音频文件的播放位置

- (int)setAudioMixingPosition:(NSInteger)pos

参数

pos

整数。进度条位置,单位为毫秒。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法可以设置音频文件的播放位置,这样你可以根据实际情况播放文件,而不是非得从头到尾播放一个文件。

Declared In

AgoraRtcEngineKit.h

音效文件播放管理

– getEffectsVolume

获取音效文件播放音量,范围为 [0.0,100.0]。

- (double)getEffectsVolume

返回

  • 方法调用成功返回音效的音量值
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– setEffectsVolume:

设置音效文件播放音量

- (int)setEffectsVolume:(double)volume

参数

volume

取值范围为 [0.0,100.0]。 100.0 为默认值

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– setVolumeOfEffect:withVolume:

实时调整音效文件播放音量,范围为 [0.0,100.0]。

- (int)setVolumeOfEffect:(int)soundId withVolume:(double)volume

参数

soundId

自行设定的音效 ID,需保证唯一性。

volume

取值范围为 [0.0,100.0]。100.0 为默认值

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– playEffect:filePath:loopCount:pitch:pan:gain:publish:

播放指定音效文件

- (int)playEffect:(int)soundId filePath:(NSString *_Nullable)filePath loopCount:(int)loopCount pitch:(double)pitch pan:(double)pan gain:(double)gain publish:(BOOL)publish

参数

soundId

自行设定的音效 ID,需保证唯一性。 如果你已通过 preloadEffect 将音效加载至内存,确保这里设置的 soundId 与 preloadEffect 设置的 soundId 相同。

filePath

要播放的音效文件的绝对路径或 URL 地址

loopCount

设置音效文件循环播放的次数:

  • 0: 播放音效文件一次
  • 1: 循环播放音效文件两次
  • -1: 无限循环播放音效文件,直至调用 stopEffectstopAllEffects 后停止
pitch

设置音效的音调 取值范围为 [0.5,2]。默认值为 1.0,表示不需要修改音调。取值越小,则音调越低

pan

设置音效的空间位置。取值范围为 [-1.0,1.0]:

  • 0.0: 音效出现在正前方
  • 1.0: 音效出现在右边
  • -1.0: 音效出现在左边
gain

设置音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0。取值越小,则音效的音量越低。

publish

设置是否将音效传到远端

  • YES: 音效文件在本地播放的同时,会发布到 Agora 云上,因此远端用户也能听到该音效
  • NO: 音效文件不会发布到 Agora 云上,因此只能在本地听到该音效

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法可以播放指定的本地或在线音效文件来给应用增加音效,比如游戏中特定操作的音效。

你可以在该方法中设置音效文件的播放次数、音调、音效的空间位置和增益,以及远端用户是否能听到该音效。 你可以多次调用该方法,通过传入不同的音效文件的 soundID 和 filePath,同时播放多个音效文件,实现音效叠加。为获得最佳用户体验,我们建议同时播放的音效文件不要超过 3 个。‘

调用该方法播放音效结束后,会触发 rtcEngineDidAudioEffectFinish 回调。

Note: macOS 上不支持同时播放多个在线音效文件。

Declared In

AgoraRtcEngineKit.h

– stopEffect:

停止播放指定音效文件

- (int)stopEffect:(int)soundId

参数

soundId

自行设定的音效 ID,需保证唯一性。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– stopAllEffects

停止播放所有音效文件

- (int)stopAllEffects

Declared In

AgoraRtcEngineKit.h

– preloadEffect:filePath:

将指定音效文件预加载至内存

- (int)preloadEffect:(int)soundId filePath:(NSString *_Nullable)filePath

参数

soundId

自行设定的音效 ID,需保证唯一性。

filePath

音效文件的绝对路径

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

为保证通信畅通,请注意控制预加载音效文件的大小,并在 joinChannel 前就使用该方法完成音效预加载。

音效文件支持以下音频格式: mp3,aac,m4a,3gp,wav

Note: 该方法不支持在线音效文件。

Declared In

AgoraRtcEngineKit.h

– unloadEffect:

从内存释放某个预加载的音效文件

- (int)unloadEffect:(int)soundId

参数

soundId

自行设定的音效 ID,需保证唯一性。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– pauseEffect:

暂停音效文件播放

- (int)pauseEffect:(int)soundId

参数

soundId

自行设定的音效 ID,需保证唯一性。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– pauseAllEffects

暂停所有音效文件播放

- (int)pauseAllEffects

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– resumeEffect:

恢复播放指定音效文件

- (int)resumeEffect:(int)soundId

参数

soundId

自行设定的音效 ID,需保证唯一性。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– resumeAllEffects

恢复播放所有音效文件

- (int)resumeAllEffects

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

音频录制

– startAudioRecording:quality:

开始客户端录音

- (int)startAudioRecording:(NSString *_Nonnull)filePath quality:(AgoraAudioRecordingQuality)quality

参数

filePath

Full 录音文件的本地保存路径,需精确到文件名及格式,例如:/dir1/dir2/dir3/audio.aac。文件名字符串应为 UTF-8 格式。

quality

AgoraAudioRecordingQuality

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

Agora SDK 支持通话过程中在客户端进行录音。该方法录制频道内所有用户的音频,并生成一个包含所有用户声音的录音文件,录音文件格式可以为:

  • .wav: 文件大,音质保真度高
  • .aac: 文件小,有一定的音质保真度损失

请确保 App 里指定的目录存在且可写。该接口需在 joinChannelByToken 之后调用。如果调用 leaveChannel 时还在录音,录音会自动停止。

Declared In

AgoraRtcEngineKit.h

– stopAudioRecording

停止客户端录音

- (int)stopAudioRecording

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

停止录音。

Note:

该接口需要在 leaveChannel 之前调用,不然会在调用 leaveChannel 时自动停止。

Declared In

AgoraRtcEngineKit.h

开启声卡采集

– enableLoopbackRecording:deviceName:

开启声卡采集

- (int)enableLoopbackRecording:(BOOL)enabled deviceName:(NSString *_Nullable)deviceName

参数

enabled
  • YES: 开启声卡采集
  • NO: 关闭声卡采集(默认)
deviceName

声卡的设备名。默认设为 nil,即使用当前声卡采集。如果用户使用虚拟声卡,如 “Soundflower”,可以将虚拟声卡名称 “Soundflower” 作为参数,SDK 会找到对应的虚拟声卡设备,并开始采集。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅适用于 macOS。

启用声卡采集功能后,声卡播放的声音会被合到本地音频流中,从而可以发送到远端。

Note:

macOS 系统默认声卡不支持采集功能,如需开启此功能需要 App 自己启用一个虚拟声卡,并将该虚拟声卡的名字作为 deviceName 传入 SDK。 Agora 测试并推荐 soundflower 作为虚拟声卡。

Declared In

AgoraRtcEngineKit.h

音频其他方法

– setAudioSessionOperationRestriction:

设置 SDK 对 Audio Session 的控制权限

- (void)setAudioSessionOperationRestriction:(AgoraAudioSessionOperationRestriction)restriction

参数

restriction

Agora SDK 对 Audio Session 的控制权限,详见 AgoraAudioSessionOperationRestriction。该 restriction 为 Bit Mask,每个 Bit 对应一个权限。

详情

该方法仅适用于 iOS 平台。

该方法限制 Agora SDK 对 Audio Session 的操作权限。在默认情况下,SDK 和 App 对 Audio Session 都有控制权,但某些场景下,App 会希望限制 Agora SDK 对 Audio Session 的控制权限,而使用其他应用或第三方组件对 Audio Session 进行操控。调用该方法可以实现该功能。

该接口可以在任意时候调用,可以在任意时候通过该方法把控制权交还给 SDK。

Note:

一旦调用该方法限制了 Agora SDK 对 Audio Session 的控制权限, SDK 将无法对 Audio Session 进行相关设置,而需要用户自己或第三方组件进行维护。

Declared In

AgoraRtcEngineKit.h

网络相关测试

– startEchoTest:

开始语音通话回路测试

- (int)startEchoTest:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))successBlock

参数

successBlock

成功开始语音通话测试回调。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败。如 ERR_REFUSED (-5):无法启动测试,可能没有成功初始化

详情

DEPRECATED 自 v2.4 起废弃

该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。 在测试过程中,用户先说一段话,在 10 秒后,声音会回放出来。如果 10 秒后用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。

Note:

  • 调用 startEchoTest 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,或者调用 joinChannelByToken 进行通话。
  • 直播模式下,只有主播用户才能调用该方法。如果用户由通信模式切换到直播模式,请务必调用 setClientRole 方法将用户角色设置为主播后再调用该方法。

Declared In

AgoraRtcEngineKit.h

– startEchoTestWithInterval:successBlock:

开始语音通话回路测试

- (int)startEchoTestWithInterval:(NSInteger)interval successBlock:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))successBlock

参数

interval

返回语音通话回路测试结果的时间间隔,取值范围为 [2,10],单位为秒,默认值为 10 秒。

successBlock

成功开始语音通话测试回调。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,声音会在设置的时间间隔后回放出来。如果用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。

Note:

  • 请在加入频道前调用该方法。
  • 调用该方法后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
  • 直播模式下,该方法仅能由用户角色为主播的用户调用。

Declared In

AgoraRtcEngineKit.h

– stopEchoTest

停止语音通话回路测试

- (int)stopEchoTest

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败。如 ERR_REFUSED (-5):不能停止测试,可能语音通话测试没有成功启动。

Declared In

AgoraRtcEngineKit.h

– enableLastmileTest

启动网络测试

- (int)enableLastmileTest

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法启用网络连接质量测试,用于检测用户网络接入质量。默认该功能为关闭状态。

该方法主要用于以下场景:

  • 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
  • 直播模式下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。

启用该方法会消耗一定的网络流量,影响通话质量,因此我们建议不要和 startLastmileProbeTest 同时使用。

在收到 lastmileQuality 回调后须调用 disableLastmileTest 停止测试,再加入频道或切换用户角色。

Note:

  • 调用该方法后,在收到 lastmileQuality 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此回调无法执行。
  • 直播模式下,主播在加入频道后请勿调用该方法。

Declared In

AgoraRtcEngineKit.h

– disableLastmileTest

关闭网络测试

- (int)disableLastmileTest

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– startLastmileProbeTest:

开始通话前网络质量探测

- (int)startLastmileProbeTest:(AgoraLastmileProbeConfig *_Nullable)config

参数

config

Last mile 网络探测配置,详见 AgoraLastmileProbeConfig

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。

启用该方法后,SDK 会依次返回如下 2 个回调:

  • lastmileQuality,视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
  • lastmileProbeResult,视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。

该方法主要用于以下两种场景:

  • 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
  • 直播模式下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。

Note:

  • 该方法会消耗一定的网络流量,影响通话质量,因此我们建议不要和 enableLastmileTest 同时使用。
  • 调用该方法后,在收到 lastmileQualitylastmileProbeResult 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
  • 直播模式下,如果本地用户为主播,请勿在加入频道后调用该方法。

Declared In

AgoraRtcEngineKit.h

– stopLastmileProbeTest

停止通话前网络质量探测

- (int)stopLastmileProbeTest

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

停止通话前网络质量探测。

Declared In

AgoraRtcEngineKit.h

自定义视频模块

– setVideoSource:

设置自定义视频源

- (void)setVideoSource:(id<AgoraVideoSourceProtocol> _Nullable)videoSource

参数

videoSource

自定义的视频源,详见 AgoraVideoSourceProtocol

详情

该方法设置视频源。实时通讯过程中,Agora SDK 通常会启动默认的视频输入设备,即内置的摄像头,进行视频推流。当需要自定义视频设备时,App 可以先通过 AgoraVideoSourceProtocol 自定义视频源,然后调用该方法将自定义的视频源加入到 SDK 中。

Declared In

AgoraRtcEngineKit.h

– setLocalVideoRenderer:

本地自定义视频渲染器

- (void)setLocalVideoRenderer:(id<AgoraVideoSinkProtocol> _Nullable)videoRenderer

参数

videoRenderer

自定义的视频渲染器,详见 AgoraVideoSinkProtocol

详情

该方法设置本地视频渲染器。实时通讯过程中,Agora SDK 通常会启动默认的视频渲染器进行视频渲染。当需要自定义视频渲染设备时,App 可以先通过 AgoraVideoSinkProtocol 自定义渲染器,然后调用该方法将视频渲染器加入到 SDK 中。

Declared In

AgoraRtcEngineKit.h

– setRemoteVideoRenderer:forUserId:

远端自定义视频渲染器

- (void)setRemoteVideoRenderer:(id<AgoraVideoSinkProtocol> _Nullable)videoRenderer forUserId:(NSUInteger)userId

参数

videoRenderer

自定义的视频渲染器,详见 AgoraVideoSinkProtocol

userId

远端用户的 uid

详情

该方法设置远端视频渲染器。实时通讯过程中,Agora SDK 通常会启动默认的视频渲染器进行视频渲染。当需要自定义视频渲染设备时,App 可以先通过 AgoraVideoSinkProtocol 自定义渲染器,然后调用该方法将视频渲染器加入到 SDK 中。

Declared In

AgoraRtcEngineKit.h

– videoSource

获取当前视频源

- (id<AgoraVideoSourceProtocol> _Nullable)videoSource

Declared In

AgoraRtcEngineKit.h

– localVideoRenderer

获取本地视频渲染器

- (id<AgoraVideoSinkProtocol> _Nullable)localVideoRenderer

Declared In

AgoraRtcEngineKit.h

– remoteVideoRendererOfUserId:

获取远端视频渲染器

- (id<AgoraVideoSinkProtocol> _Nullable)remoteVideoRendererOfUserId:(NSUInteger)userId

参数

userId

远端用户的 uid

详情

该方法获取远端视频渲染器。

Declared In

AgoraRtcEngineKit.h

– enableExternalAudioSink:channels:

开启外部音频渲染。

- (void)enableExternalAudioSink:(NSUInteger)sampleRate channels:(NSUInteger)channels

参数

sampleRate

外部音频渲染的采样率 (Hz),可设置为 8000,16000,32000,44100 或 48000。

channels

外部音频渲染的声道数,可设置为 1 或 2:

  • 1:单声道
  • 2:双声道

详情

该方法适用于需要自行渲染音频的场景。开启外部音频渲染后,你可以通过调用 pullPlaybackAudioFrameRawData / pullPlaybackAudioFrameSampleBufferByLengthInByte 方法拉取远端音频数据App 可以对拉取到的原始音频数据进行处理后再渲染,获取想要的音频效果。

Note: 开启外部音频渲染后,App 会无法从 onPlaybackAudioFrame 回调中获得数据。

Declared In

AgoraRtcEngineKit.h

– disableExternalAudioSink

关闭外部音频渲染。

- (void)disableExternalAudioSink

Declared In

AgoraRtcEngineKit.h

– pullPlaybackAudioFrameRawData:lengthInByte:

拉取 RawData 格式的远端音频数据。

- (BOOL)pullPlaybackAudioFrameRawData:(void *_Nonnull)data lengthInByte:(NSUInteger)lengthInByte

参数

data

需要拉取的音频数据,格式为 byte[]。

lengthInByte

待拉取音频数据的字节数,单位为 byte。该参数的取值与你在 enableExternalAudioSink 中设置的 sampleRate 值相关。计算公式为: lengthInByte = sampleRate / 100 * 2 * 声道数 * 时间(毫秒)。

返回

  • YES: 方法调用成功。
  • NO: 方法调用失败。

详情

使用该方法前,你需要调用 enableExternalAudioSink 方法通知 App 开启并设置外部渲染。

调用该方法后,App 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。

Note

  • 调用该方法后,App 会无法从 onPlaybackAudioFrame 回调中获得数据。
  • 该方法和 onPlaybackAudioFrame 回调相比,区别在于:
    • onPlaybackAudioFrame:SDK 每 10 毫秒通过该回调将音频数据传输给 App。如果 App 处理延时,可能会导致音频播放抖动。
    • pullPlaybackAudioFrameRawData:App 主动拉取音频数据。通过设置音频帧的数据和字节数,SDK 可以调整缓存,帮助 App 处理延时,从而有效避免音频播放抖动。

Declared In

AgoraRtcEngineKit.h

– pullPlaybackAudioFrameSampleBufferByLengthInByte:

拉取 SampleBuffer 格式的远端音频数据。

- (CMSampleBufferRef _Nullable)pullPlaybackAudioFrameSampleBufferByLengthInByte:(NSUInteger)lengthInByte

参数

lengthInByte

待拉取音频数据的字节数,单位为 byte。

该参数的取值与你在 enableExternalAudioSink 中设置的 sampleRate 值相关。计算公式为: lengthInByte = sampleRate / 100 * 2 * 声道数 * 时间(毫秒),且该参数应能被 sampleRate 值整除。

返回

  • YES: 方法调用成功。
  • NO: 方法调用失败。

详情

调用该方法前,你需要调用 enableExternalAudioSink 方法通知 App 开启并设置外部渲染。

调用该方法后,App 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。

Note

  • 调用该方法后,App 会无法从 onPlaybackAudioFrame 回调中获得数据。
  • 该方法和 onPlaybackAudioFrame 方法相比,区别在于:

    • onPlaybackAudioFrame:SDK 每 10 毫秒通过该回调将音频数据传输给 App。如果 App 处理延时,可能会导致音频播放抖动;
    • pullPlaybackAudioFrameSampleBufferByLengthInByte:App 主动拉取音频数据。通过设置音频帧的数据和字节数,SDK 可以调整缓存,帮助 App 处理延时,从而有效避免音频播放抖动。

Declared In

AgoraRtcEngineKit.h

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

– enableExternalAudioSourceWithSampleRate:channelsPerFrame:

开启外部音频采集

- (void)enableExternalAudioSourceWithSampleRate:(NSUInteger)sampleRate channelsPerFrame:(NSUInteger)channelsPerFrame

参数

sampleRate

外部音频源的采样率,可设置为 8000,16000,32000,44100 或 48000

channelsPerFrame

外部音频源的通道数(最多支持两个声道)

详情

该方法必须在加入频道前调用。

Declared In

AgoraRtcEngineKit.h

– disableExternalAudioSource

关闭外部音频采集

- (void)disableExternalAudioSource

Declared In

AgoraRtcEngineKit.h

– pushExternalAudioFrameRawData:samples:timestamp:

推送外部音频帧

- (BOOL)pushExternalAudioFrameRawData:(void *_Nonnull)data samples:(NSUInteger)samples timestamp:(NSTimeInterval)timestamp

参数

data

外部音频数据

samples

音频帧的样本数量

timestamp

外部音频帧的时间戳。该参数为必填。你可以使用该时间戳还原音频帧顺序;在有视频的场景中(包含使用外部视频源的场景),该参数可以帮助实现音视频同步。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– pushExternalAudioFrameSampleBuffer:

推送外部 CMSampleBuffer 音频帧

- (BOOL)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer

参数

sampleBuffer

采样缓冲区

返回

  • YES: 方法调用成功
  • NO: 方法调用失败

Declared In

AgoraRtcEngineKit.h

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

– setExternalVideoSource:useTexture:pushMode:

配置外部视频源

- (void)setExternalVideoSource:(BOOL)enable useTexture:(BOOL)useTexture pushMode:(BOOL)pushMode

参数

enable

是否使用外部视频源:

  • YES: 使用外部视频源
  • NO: 不使用外部视频源(默认)
useTexture

是否使用 Texture 作为输入:

  • YES: 使用 Texture 作为输入
  • NO: 不使用 Texture 作为输入
pushMode

是否外部视频源需要调用 pushExternalVideoFrame 将视频帧主动推送给 Agora SDK:

  • YES: 使用推送 (push) 模式
  • NO: 使用拉 (pull) 模式(暂不支持)

详情

Note:

如果使用了外部视频源,请在调用 enableVideostartPreview 之前调用此 API。

Declared In

AgoraRtcEngineKit.h

– pushExternalVideoFrame:

推送外部视频帧

- (BOOL)pushExternalVideoFrame:(AgoraVideoFrame *_Nonnull)frame

参数

frame

该视频帧包含待 Agora SDK 编码的视频数据,详见 AgoraVideoFrame

返回

  • YES: 该帧推送成功
  • NO: 该帧推送不成功

详情

该方法主动将视频帧数据用 AgoraVideoFrame 类封装后传递给 SDK。请确保在你调用本方法前已调用 setExternalVideoSource,并将参数 pushMode 设为 YES,不然调用本方法后会一直报错。

Note:

在通信模式下,该方法不支持 Texture 格式的视频帧,只支持非 Texture 格式视频帧。

Declared In

AgoraRtcEngineKit.h

原始音频数据处理

– setRecordingAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:

设置录制的声音格式

- (int)setRecordingAudioFrameParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel mode:(AgoraAudioRawFrameOperationMode)mode samplesPerCall:(NSInteger)samplesPerCall

参数

sampleRate

指定 onRecordAudioFrame 中返回数据的采样率,可设置为 8000,16000,32000,44100 或 48000

channel

指定 onRecordAudioFrame 中返回数据的声道数,可设置为 1 或 2:

  • 1:单声道
  • 2:双声道
mode

onRecordAudioFrame 的使用模式,详见 AgoraAudioRawFrameOperationMode

samplesPerCall

指定 onRecordAudioFrame 中返回数据的采样点数,如转码推流应用中通常为 1024。samplesPerCall = (int)(samplesPerSec × sampleInterval × numChannels),其中 sampleInterval ≥ 0.01,单位为秒。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法设置 onRecordAudioFrame 回调数据的格式,详情请参考修改原始音频数据

Declared In

AgoraRtcEngineKit.h

– setPlaybackAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:

设置播放的声音格式

- (int)setPlaybackAudioFrameParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel mode:(AgoraAudioRawFrameOperationMode)mode samplesPerCall:(NSInteger)samplesPerCall

参数

sampleRate

指定 onPlaybackAudioFrame 中返回数据的采样率,可设置为 8000,16000,32000,44100 或 48000

channel

指定 onPlaybackAudioFrame 中返回数据的声道数,可设置为 1 或 2:

  • 1:单声道
  • 2:双声道
mode

onPlaybackAudioFrame 的使用模式,详见 AgoraAudioRawFrameOperationMode

samplesPerCall

指定 onPlaybackAudioFrame 中返回数据的采样点数,如转码推流应用中通常为 1024。samplesPerCall = (int)(samplesPerSec × sampleInterval × numChannels),其中 sampleInterval ≥ 0.01,单位为秒。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法设置 onPlaybackAudioFrame 回调数据的格式,详情请参考修改原始音视频数据

Declared In

AgoraRtcEngineKit.h

– setMixedAudioFrameParametersWithSampleRate:samplesPerCall:

设置录制和播放声音混音后的数据格式

- (int)setMixedAudioFrameParametersWithSampleRate:(NSInteger)sampleRate samplesPerCall:(NSInteger)samplesPerCall

参数

sampleRate

指定 onMixedAudioFrame 中返回数据的采样率,可设置为 8000,16000,32000,44100 或 48000

samplesPerCall

指定 onMixedAudioFrame 中返回数据的采样点数,如转码推流应用中通常为 1024。samplesPerCall = (int)(samplesPerSec × sampleInterval × numChannels),其中 sampleInterval ≥ 0.01,单位为秒。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法设置 onMixedAudioFrame 回调数据的格式,详情请参考修改原始音视频数据

Declared In

AgoraRtcEngineKit.h

直播视频水印

– addVideoWatermark:

添加本地视频水印

- (int)addVideoWatermark:(AgoraImage *_Nonnull)watermark

参数

watermark

待添加在本地直播推流中的水印图片,详见 AgoraImage

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的观众,旁路推流观众,甚至录制设备都能看到或采集到该水印图片。 如果你仅仅希望在旁路推流推流中添加水印,请参考设置直播转码 setLiveTranscoding 中描述的用法。

Note:

  • 在本地直播和旁路推流中,URL 的定义不同。本地直播中,URL 指本地直播视频上水印图片的本地绝对路径;旁路推流中,URL 指旁路推流视频上水印图片的地址
  • 水印图片的源文件格式必须是 PNG。如果待添加的 PNG 图片的尺寸与你该方法中设置的尺寸不一致,SDK 会对 PNG 图片进行裁剪,以与设置相符
  • Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印
  • 如果你在 setVideoEncoderConfiguration 方法中将 orientationMode 设置为 Adaptive 模式,则如果视频帧在播放端发生旋转,水印也会以其左上角为坐标原点,跟着视频帧旋转。

Declared In

AgoraRtcEngineKit.h

– clearVideoWatermarks

删除已添加的视频水印

- (int)clearVideoWatermarks

Declared In

AgoraRtcEngineKit.h

直播音视频流回退

– setRemoteUserPriority:type:

设置远端用户流的优先级

- (int)setRemoteUserPriority:(NSUInteger)uid type:(AgoraUserPriority)userPriority

参数

uid

远端用户的 ID

userPriority

远端用户的优先级,详见 AgoraUserPriority

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

如果将某个用户的优先级设为高,那么发给这个用户的音视频流的优先级就会高于其他用户。

该方法可以与 setRemoteSubscribeFallbackOption 搭配使用。如果开启了订阅流回退选项,弱网下 SDK 会优先保证高优先级用户收到的流的质量。

Note:

目前仅支持将一名远端用户设为高优先级。

Declared In

AgoraRtcEngineKit.h

– setLocalPublishFallbackOption:

设置弱网条件下发布的音视频流回退选项

- (int)setLocalPublishFallbackOption:(AgoraStreamFallbackOptions)option

参数

option

发布音视频流的回退选项,默认为不开启回退。详见 AgoraStreamFallbackOptions

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

网络不理想的环境下,发送音视频的质量都会下降。启用本地发布音视频流回退之后,SDK 会在上行弱网且音视频质量严重受影响时,自动关断视频流,从而保证或提高音频质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。 当本地发送的音视频流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发 本地发送的音视频流已回退为音频流 回调。

Note:

旁路推流场景下,设置本地发布音视频流回退为仅音频流可能会导致远端的 CDN 用户听到声音的时间有所延迟。因此在有旁路推流的场景下,Agora 建议不要设置回退。

Declared In

AgoraRtcEngineKit.h

– setRemoteSubscribeFallbackOption:

设置弱网条件下订阅的音视频流回退选项

- (int)setRemoteSubscribeFallbackOption:(AgoraStreamFallbackOptions)option

参数

option

订阅音视频流的回退选项,默认为弱网时回退到视频小流,详见 AgoraStreamFallbackOptions

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

网络不理想的环境下,订阅音视频的质量都会下降。使用该接口开启订阅音视频流的回退选项后,SDK 会在下行弱网且音视频质量严重受影响时,将视频流切换为小流,或关断视频流,从而保证或提高通信质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。当远端订阅流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发 远端订阅流已回退为音频流 回调。

Declared In

AgoraRtcEngineKit.h

视频双流模式

– enableDualStreamMode:

开关视频双流模式

- (int)enableDualStreamMode:(BOOL)enabled

参数

enabled

指定双流或者单流模式:

  • YES: 双流模式
  • NO: 单流模式(默认)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

使用该方法设置单流(默认)或者双流模式。发送端开启双流模式后,接收端可以选择接收大流还是小流。 其中,大流指高分辨率、高码率的视频流,小流指低分辨率、低码率的视频流。

Declared In

AgoraRtcEngineKit.h

– setRemoteVideoStream:type:

设置订阅的视频流类型

- (int)setRemoteVideoStream:(NSUInteger)uid type:(AgoraVideoStreamType)streamType

参数

uid

用户 ID

streamType

设置视频流大小,AgoraVideoStreamType

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

如果发送端选择发送视频双流(大流或小流),接收端可以选择接收大流还是小流。其中大流可以理解为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。该方法可以根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。

本方法调用状态将在 didApiCallExecute 中返回。

Agora SDK 默认收到视频大流。如需使用视频小流,调用本方法进行切换。

  • 如果发送端用户已调用 enableDualStreamMode 启用了双流模式,SDK 默认接收大流。如需接收小流,可调用本方法进行切换。
  • 如果发送端用户未启用双流模式,SDK 默认接收大流。

视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。

Declared In

AgoraRtcEngineKit.h

– setRemoteDefaultVideoStreamType:

设置默认订阅的视频流类型

- (int)setRemoteDefaultVideoStreamType:(AgoraVideoStreamType)streamType

参数

streamType

设置默认接收的视频流类型,详见 AgoraVideoStreamType

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法设置远端视频默认为大流或小流。

Declared In

AgoraRtcEngineKit.h

加密

– setEncryptionSecret:

启用内置加密,并设置数据加密密码

- (int)setEncryptionSecret:(NSString *_Nullable)secret

参数

secret

加密密码

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

在加入频道之前, App 需调用 setEncryptionSecret() 指定 secret 来启用内置的加密功能,同一频道内的所有用户应设置相同的 secret。 当用户离开频道时,该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空,则无法激活加密功能。

Note:

  • 请不要在旁路推流时调用此方法。
  • 为保证最佳传输效果,请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。

Declared In

AgoraRtcEngineKit.h

– setEncryptionMode:

设置内置的加密方案

- (int)setEncryptionMode:(NSString *_Nullable)encryptionMode

参数

encryptionMode

加密方式,有三种选择:

  • “aes-128-xts":(默认)128 位 AES 加密,XTS 模式。
  • “aes-256-xts":256 位 AES 加密,XTS 模式。
  • “aes-128-ecb":128 位 AES 加密,ECB 模式。

设置为空字符串时,使用默认加密方式 “aes-128-xts”。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

Agora Native SDK 支持内置加密功能,默认使用 AES-128-XTS 加密方式。如需使用其他加密方式,可以调用该 API 设置。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别,请参考 AES 加密算法的相关资料。

在调用本方法前,请先调用 setEncryptionSecret 启用内置加密功能。

Note:

请不要在旁路推流时调用此方法。

Declared In

AgoraRtcEngineKit.h

直播导入在线媒体流

– addInjectStreamUrl:config:

导入在线媒体流 URL

- (int)addInjectStreamUrl:(NSString *_Nonnull)url config:(AgoraLiveInjectStreamConfig *_Nonnull)config

参数

url

添加到直播中的视频流 URL 地址, 支持 RTMP, HLS, FLV 协议传输。

  • 支持的 FLV 音频编码格式:AAC。
  • 支持的 FLV 视频编码格式:H264 (AVC)。
config

导入的视频流设置,详见 AgoraLiveInjectStreamConfig

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败
    • AgoraErrorCodeInvalidArgument(2):输入的 URL 为空。请重新调用该方法,并确认输入的媒体流的 URL 是有效的。
    • AgoraErrorCodeNotInitialized(7):引擎没有初始化。请确认调用该方法前已创建 RtcEngine 对象并完成初始化。
    • AgoraErrorCodeNotSupported(4):频道非直播模式。请调用 setChannelProfile 并将频道设置为直播模式再调用该方法。
    • AgoraErrorCodeNotReady(3):用户没有加入频道。

详情

该方法通过在服务端拉取视频流并发送到频道中,将正在播放的视频导入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。

调用该方法后,SDK 会在本地触发 streamInjectedStatusOfUrl 回调,报告导入在线媒体流的状态。

成功导入媒体流后,该音视频流会出现在频道中,频道内所有用户都会收到 didJoinedOfUid 回调,其中 uid 为 666。

Note:

  • 请确保已联系 support@agora.io 开通旁路直播推流功能。
  • 该方法适用于 Native SDK v2.4.1 及之后的版本。

Declared In

AgoraRtcEngineKit.h

– removeInjectStreamUrl:

删除导入的在线媒体流

- (int)removeInjectStreamUrl:(NSString *_Nonnull)url

参数

url

已导入、待删除的在线媒体流 URL 地址

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

成功删除后会触发 didOfflineOfUid 回调,UID 为 666。

Declared In

AgoraRtcEngineKit.h

CDN 旁路推流

– addPublishStreamUrl:transcodingEnabled:

增加旁路推流地址

- (int)addPublishStreamUrl:(NSString *_Nonnull)url transcodingEnabled:(BOOL)transcodingEnabled

参数

url

CDN 推流地址,格式为 RTMP。该字符串长度不能超过 1024 字节。

transcodingEnabled
  • YES: 转码(转码是指在旁路推流时对音视频流做一些转码处理后再推送到其他 RTMP 服务器,常见的适用场景是对多主播进行混流、合图)
  • NO: 不转码

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

    • AgoraErrorCodeInvalidArgument(2):参数无效,一般是 URL 为空或是长度为 0 的的字符串
    • AgoraErrorCodeNotInitialized(7):推流时未初始化引擎

详情

该方法用于添加旁路推流地址,调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告增加旁路推流地址的状态。

Note:

  • 该方法仅适用于直播模式。
  • 请确保在成功加入频道后再调用该接口。
  • 该方法每次只能增加一路旁路推流地址。若需推送多路流,则需多次调用该方法。
  • URL 不支持中文等特殊字符。

Declared In

AgoraRtcEngineKit.h

– removePublishStreamUrl:

删除旁路推流地址

- (int)removePublishStreamUrl:(NSString *_Nonnull)url

参数

url

待删除的推流地址,格式为 RTMP。该字符串长度不能超过 1024 字节

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法用于删除旁路推流过程中已经设置的 RTMP 推流地址。调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告删除旁路推流地址的状态。

Note:

  • 该方法仅适用于直播模式。
  • 该方法每次只能删除一路旁路推流地址。若需删除多路流,则需多次调用该方法。
  • URL 不支持中文等特殊字符。

Declared In

AgoraRtcEngineKit.h

– setLiveTranscoding:

设置直播转码

- (int)setLiveTranscoding:(AgoraLiveTranscoding *_Nullable)transcoding

参数

transcoding

一个 AgoraLiveTranscoding 的对象,详细设置见 AgoraLiveTranscoding

详情

该方法用于旁路推流的视图布局及音频设置等。

Note: 该方法仅适用于直播模式。

Declared In

AgoraRtcEngineKit.h

数据流

– createDataStream:reliable:ordered:

创建数据流

- (int)createDataStream:(NSInteger *_Nonnull)streamId reliable:(BOOL)reliable ordered:(BOOL)ordered

参数

streamId

数据流 ID

reliable
  • YES: 接收方 5 秒内会收到发送方所发送的数据,否则会收到 didOccurStreamMessageError 回调获得相应报错信息。
  • NO: 接收方不保证收到,就算数据丢失也不会报错。
ordered
  • YES: 接收方 5 秒内会按照发送方发送的顺序收到数据包。
  • NO: 接收方不保证按照发送方发送的顺序收到数据包

返回

  • 0: 创建数据流成功
  • < 0: 创建数据流失败

详情

该方法用于创建数据流。AgoraRtcEngineKit 生命周期内,每个用户最多只能创建 5 个数据流。频道内数据通道最多允许数据延迟 5 秒,若超过 5 秒接收方尚未收到数据流,则数据通道会向 App 报错。 目前 Agora Native SDK 支持 99% 可靠和 100% 有序的数据传输。

Note:

请将 reliableordered 同时设置为 YES 或 NO,暂不支持交叉设置。

Declared In

AgoraRtcEngineKit.h

– sendStreamMessage:data:

发送数据流

- (int)sendStreamMessage:(NSInteger)streamId data:(NSData *_Nonnull)data

参数

streamId

数据流 ID,createDataStream 的返回值。

data

需要发送的消息

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制:频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。 每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。

成功调用该方法后,远端会触发 receiveStreamMessageFromUid 回调,远端用户可以在该回调中获取接收到的流消息;若调用失败,远端会触发 didOccurStreamMessageErrorFromUid 回调。

Note:

该方法仅适用于通信模式以及直播模式下的主播用户,如果直播模式下的观众调用此方法可能会造成观众变主播。

Declared In

AgoraRtcEngineKit.h

其他视频控制

– setLocalVideoMirrorMode:

设置本地视频镜像模式

- (int)setLocalVideoMirrorMode:(AgoraVideoMirrorMode)mode

参数

mode

视频镜像模式,详见 AgoraVideoMirrorMode

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法设置本地视频镜像模式,须在开启本地预览前设置。如果在开启预览后设置,需要重新开启预览才能生效。

Declared In

AgoraRtcEngineKit.h

– setCameraCapturerConfiguration:

设置摄像头采集偏好

- (int)setCameraCapturerConfiguration:(AgoraCameraCapturerConfiguration *_Nullable)configuration

参数

configuration

摄像头采集偏好,详见 AgoraCameraCapturerConfiguration

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

一般的视频通话或直播中,默认由 SDK 自动控制摄像头的输出参数。在如下特殊场景中,默认的参数通常无法满足需求,或可能引起设备性能问题,我们推荐调用该方法设置摄像头的采集偏好:

  • 使用原始音视频数据自采集接口时,如果 SDK 输出的分辨率和帧率高于 setVideoEncoderConfiguration 中指定的参数,在后续处理视频帧的时候,比如美颜功能时,会需要更高的 CPU 及内存,容易导致性能问题。在这种情况下,我们推荐将摄像头采集偏好设置为 AgoraCameraCaptureOutputPreferencePerformance(1),避免性能问题。
  • 如果没有本地预览功能或者对预览质量没有要求,我们推荐将采集偏好设置为 AgoraCameraCaptureOutputPreferencePerformance(1),以优化 CPU 和内存的资源分配。
  • 如果用户希望本地预览视频比实际编码发送的视频清晰,可以将采集偏好设置为 AgoraCameraCaptureOutputPreferencePreview(2)。

Note:

请在启动摄像头之前调用该方法,如 joinChannelByTokenenableVideo 或者 enableLocalVideo 之前。

Declared In

AgoraRtcEngineKit.h

摄像头控制

– switchCamera

切换前置/后置摄像头

- (int)switchCamera

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

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

Declared In

AgoraRtcEngineKit.h

– isCameraZoomSupported

检测设备是否支持摄像头缩放功能

- (BOOL)isCameraZoomSupported

返回

  • YES: 设备支持摄像头缩放功能
  • NO: 设备不支持摄像头缩放功能

详情

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

Declared In

AgoraRtcEngineKit.h

– isCameraTorchSupported

检测设备是否支持闪光灯常开

- (BOOL)isCameraTorchSupported

返回

  • YES: 设备支持闪光灯常开
  • NO: 设备不支持闪光灯常开

详情

Note:

  • 本方法仅适用于 iOS 平台,不适用于 macOS。
  • 一般情况下,App 默认开启前置摄像头,因此如果你的前置摄像头不支持闪光灯常开,直接使用该方法会返回 NO。如果需要检查后置摄像头是否支持闪光灯常开,需要先使用 switchCamera 切换摄像头,再使用该方法。

Declared In

AgoraRtcEngineKit.h

– isCameraFocusPositionInPreviewSupported

检测设备是否支持手动对焦功能

- (BOOL)isCameraFocusPositionInPreviewSupported

返回

  • YES: 设备支持手动对焦功能
  • NO: 设备不支持手动对焦功能

详情

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

Declared In

AgoraRtcEngineKit.h

– isCameraExposurePositionSupported

检测设备是否支持手动曝光功能

- (BOOL)isCameraExposurePositionSupported

返回

  • YES: 设备支持手动曝光功能
  • NO: 设备不支持手动曝光功能

详情

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

Declared In

AgoraRtcEngineKit.h

– isCameraAutoFocusFaceModeSupported

检测设备是否支持人脸对焦功能

- (BOOL)isCameraAutoFocusFaceModeSupported

返回

  • YES: 设备支持人脸对焦功能
  • NO: 设备不支持人脸对焦功能

详情

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

Declared In

AgoraRtcEngineKit.h

– setCameraZoomFactor:

设置摄像头缩放比例

- (CGFloat)setCameraZoomFactor:(CGFloat)zoomFactor

参数

zoomFactor

摄像头缩放比例,有效范围是 1.0 到设备支持的最大缩放比例。

返回

设置成功返回设置的 factor 值,设置失败返回 < 0

详情

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

Declared In

AgoraRtcEngineKit.h

– setCameraFocusPositionInPreview:

设置手动对焦位置,并触发对焦

- (BOOL)setCameraFocusPositionInPreview:(CGPoint)position

参数

position

触摸点相对于视图的坐标

返回

  • YES: 方法调用成功
  • NO: 方法调用失败

详情

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

成功调用该方法后,本地会触发 cameraFocusDidChangedToRect 回调。

Declared In

AgoraRtcEngineKit.h

– setCameraExposurePosition:

设置摄像头曝光位置

- (BOOL)setCameraExposurePosition:(CGPoint)positionInView

参数

positionInView

触摸点相对于视图的横坐标和纵坐标

返回

  • YES: 方法调用成功
  • NO: 方法调用失败

详情

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

成功调用该方法后,本地会触发 cameraExposureDidChangedToRect 回调。

Declared In

AgoraRtcEngineKit.h

– setCameraTorchOn:

设置是否打开闪光灯

- (BOOL)setCameraTorchOn:(BOOL)isOn

参数

isOn
  • YES: 打开
  • NO: 关闭

返回

  • YES: 方法调用成功
  • NO: 方法调用失败

详情

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

Declared In

AgoraRtcEngineKit.h

– setCameraAutoFocusFaceModeEnabled:

设置是否开启人脸对焦功能

- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable

参数

enable
  • YES: 开启
  • (默认)NO: 关闭

返回

  • YES: 方法调用成功
  • NO: 方法调用失败

详情

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

Declared In

AgoraRtcEngineKit.h

屏幕共享

– startScreenCaptureByDisplayId:rectangle:parameters:

通过屏幕 ID 共享屏幕(仅支持 macOS )

- (int)startScreenCaptureByDisplayId:(NSUInteger)displayId rectangle:(CGRect)rectangle parameters:(AgoraScreenCaptureParameters *_Nonnull)captureParams

参数

displayId

待共享的屏幕 ID。通过该参数指定你要共享的那个屏幕。关于如何获取屏幕 ID,请参考进行屏幕共享

rectangle

(可选)待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。由如下参数组成:

  • x:左上角的横向偏移
  • y:左上角的纵向偏移
  • width:待共享区域的宽
  • height:待共享区域的高

如果设置的共享区域超出了屏幕的边界,则只共享屏幕内的内容;如果宽或高设为 0,则共享整个屏幕。

captureParams

屏幕共享的编码参数配置,详见 AgoraScreenCaptureParameters

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

    • ERR_INVALID_STATE:屏幕共享状态无效。可能有屏幕正在共享中,请先调用 stopScreenCapture 停止共享。
    • ERR_INVALID_ARGUMENT:传入的参数无效。

详情

共享一个屏幕或该屏幕的部分区域。你需要在该方法中指定想要共享的屏幕 ID。

Declared In

AgoraRtcEngineKit.h

– startScreenCaptureByWindowId:rectangle:parameters:

通过窗口 ID 共享窗口(仅支持 macOS )

- (int)startScreenCaptureByWindowId:(NSUInteger)windowId rectangle:(CGRect)rectangle parameters:(AgoraScreenCaptureParameters *_Nonnull)captureParams

参数

windowId

待共享的窗口 ID。通过该参数指定你要共享的那个窗口。关于如何获取窗口 ID,请参考进行屏幕共享

rectangle

(可选)待共享区域相对于整个窗口的位置。如不填,则表示共享整个窗口。由如下参数组成:

  • x:左上角的横向偏移
  • y:左上角的纵向偏移
  • width:待共享区域的宽
  • height:待共享区域的高

如果设置的共享区域超出了窗口的边界,则只共享窗口内的内容;如果宽或高设为 0,则共享整个窗口。

captureParams

屏幕共享的编码参数配置,详见 AgoraScreenCaptureParameters

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

    • ERR_INVALID_STATE:屏幕共享状态无效。可能有屏幕正在共享中,请先调用 stopScreenCapture 停止共享。
    • ERR_INVALID_ARGUMENT:传入的参数无效。

详情

共享一个窗口或该窗口的部分区域。你需要在该方法中指定想要共享的窗口 ID。

Declared In

AgoraRtcEngineKit.h

– setScreenCaptureContentHint:

设置屏幕共享内容类型(仅支持 macOS )

- (int)setScreenCaptureContentHint:(AgoraVideoContentHint)contentHint

参数

contentHint

屏幕共享的内容类型,详见 AgoraVideoContentHint

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

Agora SDK 会根据不同的内容类型,使用不同的算法对共享效果进行优化。如果不调用该方法,SDK 会将屏幕共享的内容默认为 AgoraVideoContentHintNone,即无指定的内容类型。

Declared In

AgoraRtcEngineKit.h

– updateScreenCaptureParameters:

更新屏幕共享的编码参数配置(仅支持 macOS )

- (int)updateScreenCaptureParameters:(AgoraScreenCaptureParameters *_Nonnull)captureParams

参数

captureParams

屏幕共享的编码参数配置,详见 AgoraScreenCaptureParameters

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

    • ERR_NOT_READY:当前没有共享的屏幕

Declared In

AgoraRtcEngineKit.h

– updateScreenCaptureRegion:

更新屏幕共享区域 (仅支持 macOS )

- (int)updateScreenCaptureRegion:(CGRect)rect

参数

rect

待共享区域相对于整个屏幕或窗口的位置。如不填,则表示共享整个屏幕或窗口。由如下参数组成:

  • x:左上角的横向偏移
  • y:左上角的纵向偏移
  • width:待共享区域的宽
  • height:待共享区域的高

如果设置的共享区域超出了屏幕或窗口的边界,则只共享屏幕或窗口内的内容;如果宽或高设为 0,则共享整个屏幕或窗口。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

    • ERR_NOT_READY:当前没有共享的屏幕

Declared In

AgoraRtcEngineKit.h

– stopScreenCapture

停止屏幕共享(仅支持 macOS )

- (int)stopScreenCapture

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

音视频设备管理 (macOS)

– monitorDeviceChange:

监控设备改变

- (void)monitorDeviceChange:(BOOL)enabled

参数

enabled
  • YES: 开启监控
  • NO: 关闭监控

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

该方法用来启动设备插拔检测,这里设备指的是音视频外接设备,比如外接摄像头等。

Declared In

AgoraRtcEngineKit.h

– enumerateDevices:

获取系统中所有的音视频设备

- (NSArray<AgoraRtcDeviceInfo*> *_Nullable)enumerateDevices:(AgoraMediaDeviceType)type

参数

type

要枚举的设备类型,详见 AgoraMediaDeviceType

返回

调用成功时,返回 AgoraRtcDeviceInfo NSArray 对象,包含所有的音视频设备。

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

该方法返回一个 NSArray 对象,包含系统中所有的音视频设备。应用程序可以通过 AgoraRtcDeviceInfo array 对象枚举设备。

Note:

不要在主线程调用该方法。

Declared In

AgoraRtcEngineKit.h

– getDeviceInfo:

获取当前设备名称

- (AgoraRtcDeviceInfo *_Nullable)getDeviceInfo:(AgoraMediaDeviceType)type

参数

type

设备的类型,包括录音、外发和媒体采集设备,详见 AgoraMediaDeviceType

返回

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

该方法通过 type 获取当前录音、外放或视频采集设备名称。

Declared In

AgoraRtcEngineKit.h

– setDevice:deviceId:

指定设备

- (int)setDevice:(AgoraMediaDeviceType)type deviceId:(NSString *_Nonnull)deviceId

参数

type

设备的类型,包括录音、外放和视频采集设备,详见 AgoraMediaDeviceType

deviceId

设备的 Device ID,可通过 enumerateDevices获取。插拔设备不会影响 deviceId 。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

该方法通过 deviceId 参数指定播放、录音或视频采集设备。

Declared In

AgoraRtcEngineKit.h

– getDeviceVolume:

获取设备音量

- (int)getDeviceVolume:(AgoraMediaDeviceType)type

参数

type

设备的类型,包括录音、外放和视频采集设备,详见 AgoraMediaDeviceType

返回

  • 调用成功,返回设备的音量
  • < 0: 方法调用失败

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

该方法获取当前设备的音量。

Declared In

AgoraRtcEngineKit.h

– setDeviceVolume:volume:

设置设备音量

- (int)setDeviceVolume:(AgoraMediaDeviceType)type volume:(int)volume

参数

type

设备的类型,包括录音、外放和视频采集设备,详见 AgoraMediaDeviceType

volume

设置的音量

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

设置录音或外放的音量。

Declared In

AgoraRtcEngineKit.h

– startRecordingDeviceTest:

启动麦克风测试

- (int)startRecordingDeviceTest:(int)indicationInterval

参数

indicationInterval

报告麦克风音量的时间间隔(毫秒)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

该方法测试麦克风是否能正常工作。启动测试后,SDK 通过 reportAudioVolumeIndicationOfSpeakers 回调方法向应用程序上报音量信息。

Declared In

AgoraRtcEngineKit.h

– stopRecordingDeviceTest

停止麦克风测试

- (int)stopRecordingDeviceTest

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

该方法停止麦克风测试。调用 startRecordingDeviceTest 后,必须调用该方法停止测试。

Declared In

AgoraRtcEngineKit.h

– startPlaybackDeviceTest:

启动播放设备测试

- (int)startPlaybackDeviceTest:(NSString *_Nonnull)audioFileName

参数

audioFileName

指定音频文件的绝对路径,路径字符串使用UTF-8编码格式:

  • 支持的文件格式: wav,mp3,m4a,aac
  • 支持的文件采样率: 8000,16000,32000,44100,48000

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

该方法测试播放设备是否能正常工作。SDK 播放指定的音频文件,测试者如果能听到声音,说明播放设备能正常工作。

Declared In

AgoraRtcEngineKit.h

– stopPlaybackDeviceTest

停止播放设备测试

- (int)stopPlaybackDeviceTest

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

该方法停止播放设备测试。调用 startPlaybackDeviceTest 后,必须调用该方法停止测试。

Declared In

AgoraRtcEngineKit.h

– startCaptureDeviceTest:

启动视频采集设备测试

- (int)startCaptureDeviceTest:(NSView *_Nonnull)view

参数

view

输入参数,用于显示图像的窗口

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

用于测试当前视频采集设备是否工作正常,使用前需保证已调用过 enableVideo ,且传入参数的 view 窗口有效。

Declared In

AgoraRtcEngineKit.h

– stopCaptureDeviceTest

停止视频采集设备测试

- (int)stopCaptureDeviceTest

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

停止视频采集设备测试,如果之前调用了 startCaptureDeviceTest,必须通过该方法停止测试。

Declared In

AgoraRtcEngineKit.h

– startAudioDeviceLoopbackTest:

开始音频设备回路测试

- (int)startAudioDeviceLoopbackTest:(int)indicationInterval

参数

indicationInterval

SDK 返回 reportAudioVolumeIndicationOfSpeakers 回调的时间间隔,单位为毫秒。建议设置为大于 200 毫秒,最小不得少于 10 毫秒。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

该方法测试麦克风和播放设备是否能正常工作。一旦测试开始,麦克风会采集本地讲话声音,然后使用扬声器播放出来,同时 SDK 会通过 reportAudioVolumeIndicationOfSpeakers 回调向应用程序上报音量信息。

Note:

该方法仅在本地进行音频设备测试,不涉及网络连接。

Declared In

AgoraRtcEngineKit.h

– stopAudioDeviceLoopbackTest

停止音频设备回路测试

- (int)stopAudioDeviceLoopbackTest

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

该方法仅支持 macOS 平台,不支持 iOS 平台。

在调用 startAudioDeviceLoopbackTest 后,必须调用该方法停止音频设备回路测试。

Declared In

AgoraRtcEngineKit.h

媒体附属信息

– setMediaMetadataDataSource:withType:

设置媒体附属信息的 Data source

- (BOOL)setMediaMetadataDataSource:(id<AgoraMediaMetadataDataSource> _Nullable)metadataDataSource withType:(AgoraMetadataType)type

参数

metadataDataSource

AgoraMediaMetadataDataSource 协议。

type

附属信息的数据类型,详见 AgoraMetadataType。目前仅支持视频类的附属信息。

返回

  • YES: 方法调用成功
  • NO: 方法调用失败

详情

设置媒体附属信息的 Data source。你需要在该方法中实现一个 AgoraMediaMetadataDataSource 协议,并指定附属信息的数据类型。成功调用该方法后,SDK 会触发 metadataMaxSize 回调。

该接口可以与 setMediaMetadataDelegate 接口搭配使用,在直播场景中实现发送商品链接、分发优惠券、发送答题等功能,构建更为丰富的直播互动方式。

Note: 请在调用 joinChannelByToken 加入频道前调用该方法

Note: 该方法仅适用于直播模式

Declared In

AgoraRtcEngineKit.h

– setMediaMetadataDelegate:withType:

设置媒体附属信息的 Delegate

- (BOOL)setMediaMetadataDelegate:(id<AgoraMediaMetadataDelegate> _Nullable)metadataDelegate withType:(AgoraMetadataType)type

参数

metadataDelegate

AgoraMediaMetadataDelegate 协议。

type

附属信息的数据类型,详见 AgoraMetadataType。目前仅支持视频类的附属信息。

返回

  • YES: 方法调用成功
  • NO: 方法调用失败

详情

设置媒体附属信息的 Delegate。你需要在该方法中实现一个 AgoraMediaMetadataDelegate 协议,并指定附属信息的数据类型。

Note: 请在调用 joinChannelByToken 加入频道前调用该方法

Note: 该方法仅适用于直播模式

Declared In

AgoraRtcEngineKit.h

其他方法

– getCallId

获取通话 ID

- (NSString *_Nullable)getCallId

返回

当前通话 ID

详情

客户端在每次 joinChannelByToken 后会生成一个对应的 CallId,标识该客户端的此次通话。有些方法如 ratecomplain需要在通话结束后调用,向 SDK 提交反馈,这些方法必须指定 CallId 参数。使用这些反馈方法,需要在通话过程中调用 getCallId 方法获取 CallId,在通话结束后在反馈方法中作为参数传入。

Declared In

AgoraRtcEngineKit.h

– rate:rating:description:

给通话评分

- (int)rate:(NSString *_Nonnull)callId rating:(NSInteger)rating description:(NSString *_Nullable)description

参数

callId

通话 getCallId 函数获取的通话 ID。

rating

给通话的评分,最低 1 分,最高 5 分,如设置超过这个范围,SDK 会返回 AgoraErrorCodeInvalidArgument(-2) 错误。

description

(非必选项) 给通话的描述,可选,长度应小于 800 字节。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败
    • AgoraErrorCodeInvalidArgument (-2):传入的参数无效,例如 callId 无效
    • AgoraErrorCodeNotReady (-3):SDK 不在正确的状态,可能是因为没有成功初始化

详情

该方法能够让用户为通话评分,一般在通话结束后调用。

Declared In

AgoraRtcEngineKit.h

– complain:description:

投诉通话质量

- (int)complain:(NSString *_Nonnull)callId description:(NSString *_Nullable)description

参数

callId

通过 getCallId 函数获取的通话 ID

description

(非必选项) 给通话的描述,可选,长度应小于 800 字节

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败
    • ERR_INVALID_ARGUMENT (-2):传入的参数无效,例如 callId 无效
    • ERR_NOT_READY (-3):SDK 不在正确的状态,可能是因为没有成功初始化

详情

该方法让用户就通话质量进行投诉。一般在通话结束后调用。

Declared In

AgoraRtcEngineKit.h

– enableMainQueueDispatch:

分发/不分发回调至主队列

- (int)enableMainQueueDispatch:(BOOL)enabled

参数

enabled
  • YES: 分发回调方法到主队列
  • NO: 不分发回调方法到主队列

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

如果不分发回调方法到主队列, App 应将 UI 操作分发到主队列。

Declared In

AgoraRtcEngineKit.h

+ getSdkVersion

查询 SDK 版本号

+ (NSString *_Nonnull)getSdkVersion

返回

当前的 SDK 版本号,格式为字符串,如 2.3.0

详情

该方法返回当前 SDK 版本号。

Declared In

AgoraRtcEngineKit.h

– setLogFile:

设置日志文件

- (int)setLogFile:(NSString *_Nonnull)filePath

参数

filePath

日志文件的完整路径。该日志文件为 UTF-8 编码。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。 App 必须保证指定的目录存在而且可写。

Note:

  • 日志文件的默认地址如下
    • iOS:App Sandbox/Library/caches/agorasdk.log
    • macOS
      • 开启沙盒:App Sandbox/Library/Logs/agorasdk.log,例如 /Users/<username>/Library/Containers/<App Bundle Identifier>/Data/Library/Logs/agorasdk.log
      • 关闭沙盒:~/Library/Logs/agorasdk.log
  • 如需调用本方法,请在调用 sharedEngineWithAppId 方法初始化 AgoraRtcEngineKit 对象后立即调用,否则可能造成输出日志不完整。

Declared In

AgoraRtcEngineKit.h

– setLogFileSize:

设置日志文件大小

- (int)setLogFileSize:(NSUInteger)fileSizeInKBytes

参数

fileSizeInKBytes

指定 SDK 输出日志文件的内存大小,单位为 KB。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败,有可能是因为传入的参数无效

详情

设置 SDK 输出的日志文件大小,单位为 KB。

Agora SDK 设有 2 个日志文件,每个文件大小为 512 KB。如果你将 fileSizeInKByte 设置为 1024 KB, SDK 会最多输出 2 MB 的日志文件。如果日志文件大小超出设置值,新的日志会覆盖之前的日志。

Declared In

AgoraRtcEngineKit.h

– setLogFilter:

设置日志输出等级

- (int)setLogFilter:(NSUInteger)filter

参数

filter

AgoraLogFilter

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

Declared In

AgoraRtcEngineKit.h

– getNativeHandle

获取 Native SDK Engine Handle

- (void *_Nullable)getNativeHandle

详情

该方法获取 native SDK engine 的 C++ handle,用于包括注册音视频帧观测器在内的特殊场景。

Declared In

AgoraRtcEngineKit.h

  delegate

设置/获取 AgoraRtcEngineDelegate

@property (nonatomic, weak) id<AgoraRtcEngineDelegate> _Nullable delegate

详情

Agora Native SDK 通过指定的 delegate 通知 App 引擎运行时的事件。Delegate 中定义的所有方法都是可选实现的。

Declared In

AgoraRtcEngineKit.h

定制方法 (Technical Preview)

– setParameters:

通过 JSON 配置 SDK 提供技术预览或特别定制功能

- (int)setParameters:(NSString *_Nonnull)options

参数

options

JSON 格式的 SDK 选项

详情

JSON 选项默认不公开。声网工程师正在努力寻求以标准化方式公开 JSON 选项。

Declared In

AgoraRtcEngineKit.h

– getParameter:args:

获取 Agora SDK 可供自定义的参数

- (NSString *_Nullable)getParameter:(NSString *_Nonnull)parameter args:(NSString *_Nullable)args

详情

该方法未公开,请联系声网支持 support@agora.io 获取详情。

Declared In

AgoraRtcEngineKit.h

已废弃方法

– setVideoQualityParameters:

设置视频质量偏好选项

- (int)setVideoQualityParameters:(BOOL)preferFrameRateOverImageQuality

参数

preferFrameRateOverImageQuality

画质和流畅度里,是否优先保障流畅度:

  • YES: 画质和流畅度里,优先保证流畅度
  • NO: 画质和流畅度里,优先保证画质(默认)

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

DEPRECATED 自 v2.4 起废弃

该方法仅适用于直播模式。在网络条件不好或者设备性能不足影响到直播体验的情况下,可以使用该方法设置是否要优先保障流畅度。

Declared In

AgoraRtcEngineKit.h

+ sharedEngineWithAppId:error:

初始化 AgoraRtcEngineKit

+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString *_Nonnull)AppId error:(void ( ^ _Nullable ) ( AgoraErrorCode errorCode ))errorBlock

参数

AppId

Agora 为应用程序开发者签发的 App ID

errorBlock

AgoraErrorCode

详情

DEPRECATED 从 v2.3 起废弃

推荐使用

Declared In

AgoraRtcEngineKit.h

– pauseAudio

关闭音频

- (int)pauseAudio

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

DEPRECATED 从 v2.3 起废弃

推荐使用

Declared In

AgoraRtcEngineKit.h

– resumeAudio

打开音频

- (int)resumeAudio

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

DEPRECATED 从 v2.3 起废弃

推荐使用

Declared In

AgoraRtcEngineKit.h

– setHighQualityAudioParametersWithFullband:stereo:fullBitrate:

设置音频高音质选项

- (int)setHighQualityAudioParametersWithFullband:(BOOL)fullband stereo:(BOOL)stereo fullBitrate:(BOOL)fullBitrate

参数

fullband

是否开启 Full-band codec(采样率 48 kHz),不支持 v1.7.4 以下版本。

  • YES: 开启
  • NO: 关闭
stereo

是否开启 stereo codec,不支持 v1.7.4 以下版本。

  • YES: 开启
  • NO: 关闭
fullBitrate

是否开启高码率模式。建议仅在语音模式开启。

  • YES: 开启
  • NO: 关闭

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

DEPRECATED 从 v2.3 起废弃

该方法设置音频高音质选项。请在加入频道前调用本方法并一次性设置好三个模式。切勿在加入频道后再次调用本方法。

推荐使用

Declared In

AgoraRtcEngineKit.h

– setSpeakerphoneVolume:

设置扬声器音量

- (int)setSpeakerphoneVolume:(NSUInteger)volume

参数

volume

扬声器音量,0 (音量最低) 到 255 (音量最高) 的整数。

返回

  • 0: 设置成功
  • < 0: 设置失败

详情

DEPRECATED 从 v2.3 起废弃

该方法仅支持 macOS 平台,不支持 iOS 平台。

推荐使用

Declared In

AgoraRtcEngineKit.h

– startScreenCapture:withCaptureFreq:bitRate:andRect:

开始屏幕共享

- (int)startScreenCapture:(NSUInteger)windowId withCaptureFreq:(NSInteger)captureFreq bitRate:(NSInteger)bitRate andRect:(CGRect)rect

参数

windowId

用于指定共享窗口:

  • 共享整个屏幕:将 windowId 设为 0,且将 rect 设为 nil
  • 共享指定窗口:将 windowId 设为非 0,每个窗口对应一个非 0 的 windowId
  • 共享指定区域:将 windowId 设为 0,且将 rect 设为非 nil 。在这个情况下,你可以共享指定区域,例如你可以拖动鼠标选中要共享的区域,但这个逻辑需要自己实现。这里的 共享指定区域 指的是共享整个屏幕里的某个区域。目前暂不支持共享指定窗口里的指定区域。
captureFreq

共享屏幕的帧率,必须设置,范围是 1 到 15 fps。

bitRate

共享屏幕的码率

rect

指定共享屏幕的区域。只有将 windowsId 设为 0 时,该参数才有效。当你将 rect 设置为 nil 时,共享整个屏幕。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

DEPRECATED 从 v2.4 起废弃

该方法仅支持 macOS 平台,不支持 iOS 平台。

Declared In

AgoraRtcEngineKit.h

– setVideoProfile:swapWidthAndHeight:

设置本地视频属性

- (int)setVideoProfile:(AgoraVideoProfile)profile swapWidthAndHeight:(BOOL)swapWidthAndHeight

参数

profile

视频属性,详见 AgoraVideoProfile

swapWidthAndHeight

SDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高:

  • YES: 交换宽和高
  • NO: (默认)不交换宽和高

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

DEPRECATED 从 v2.3 起废弃

该方法设置视频编码属性(Profile)。每个属性对应一套视频参数,如分辨率、帧率、码率等。 当设备的摄像头不支持指定的分辨率时,SDK 会自动选择一个合适的摄像头分辨率,但是编码分辨率仍然用本方法指定的。

Note:

  • 应在调用 enableVideo 后设置视频属性。
  • 应在调用 joinChannelByToken/startPreview前设置视频属性。
  • 如果加入频道后不需要重新设置视频编码属性,Agora 建议在 enableVideo 之前调用该方法,可以加快首帧出图时间。

Declared In

AgoraRtcEngineKit.h

– setVideoResolution:andFrameRate:bitrate:

手动设置视频的宽、高、帧率和码率

- (int)setVideoResolution:(CGSize)size andFrameRate:(NSInteger)frameRate bitrate:(NSInteger)bitrate

参数

size

想要设置的视频尺寸,最高不超过 1280 × 720。

frameRate

想要设置的视频帧率,最高值不超过 30. 如 5、 10、 15、 24、 30 等。

bitrate

你想要设置的视频码率,需要根据想要设置的视频的宽、高和帧率,并结合 AgoraVideoEncoderConfiguration 中的码率参考表,手动推算出合适值。宽和高固定的情况下,码率随帧率的变化而变化:

  • 若选取的帧率为 5 fps,则推算码率为上表推荐码率除以 2
  • 若选取的帧率为 15 fps,则推算码率为上表推荐码率
  • 若选取的帧率为 30 fps,则推算码率为上表码率乘以 1.5
  • 若选取其余帧率,等比例推算即可

假设分辨率为 320 × 240,根据上表,帧率为 15 fps 时推荐码率为 200,则:

  • 若帧率为 5 FPS,则推算码率为 200 除以 2,即 100
  • 若帧率为 30 FPS,则推算码率为 200 乘以 1.5,即 300
  • 若设置的码率超过合理范围, SDK 将自动将其调整到合理区间。

详情

DEPRECATED 从 v2.3 起废弃

如果加入频道后不需要重新设置视频编码属性,Agora 建议在 enableVideo 之前调用该方法,可以加快首帧出图时间。

Declared In

AgoraRtcEngineKit.h

– getDeviceId:

获取当前设备名称

- (NSString *_Nullable)getDeviceId:(AgoraMediaDeviceType)type

参数

type

设备的类型,包括录音、外发和媒体采集设备,详见 AgoraMediaDeviceType

返回

  • 调用成功时,返回设备的 Device ID
  • 调用失败时,返回 nil

详情

DEPRECATED 从 v2.3 起废弃

该方法仅支持 macOS 平台,不支持 iOS 平台。

该方法通过 type 获取当前录音、外放或视频采集设备名称。

推荐使用

Declared In

AgoraRtcEngineKit.h

– playEffect:filePath:loopCount:pitch:pan:gain:

播放指定音效文件

- (int)playEffect:(int)soundId filePath:(NSString *_Nullable)filePath loopCount:(int)loopCount pitch:(double)pitch pan:(double)pan gain:(double)gain

参数

soundId

自行设定的音效 ID,需保证唯一性。

Note:

如果你已通过 preloadEffect 将音效加载至内存,确保这里设置的 soundId 与 preloadEffect 设置的 soundId 相同。

filePath

音效文件的绝对路径

loopCount

设置音效文件循环播放的次数:

  • 0: 播放音效文件一次
  • 1: 循环播放音效文件两次
  • -1: 无限循环播放音效文件,直至调用 stopEffectstopAllEffects 后停止
pitch

设置音效的音调 取值范围为 [0.5,2]。默认值为 1.0,表示不需要修改音调。取值越小,则音调越低

pan

设置音效的空间位置。取值范围为 [-1.0,1.0]:

  • 0.0: 音效出现在正前方
  • 1.0: 音效出现在右边
  • -1.0: 音效出现在左边
gain

设置音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0。取值越小,则音效的音量越低。

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

DEPRECATED 从 v2.3 起废弃

推荐使用

Declared In

AgoraRtcEngineKit.h

+ getMediaEngineVersion

获取媒体引擎版本号

+ (NSString *_Nonnull)getMediaEngineVersion

返回

媒体引擎版本号

详情

DEPRECATED 从 v2.3 起废弃

推荐使用

Declared In

AgoraRtcEngineKit.h

已废弃回调

– audioVolumeIndicationBlock:

提示谁在说话及其音量

- (void)audioVolumeIndicationBlock:(void ( ^ _Nullable ) ( NSArray *_Nonnull speakers , NSInteger totalVolume ))audioVolumeIndicationBlock

参数

audioVolumeIndicationBlock

回调中包含:

  • speakers: 以数组的形式返回每个说话者的用户 ID 和音量信息。

    • uid: 说话者的用户 ID。如果返回的 uid 为 0,则为本地用户。
    • volume:说话者的音量(0~255)
  • totalVolume: (混音后的)总音量(0~255)

详情

DEPRECATED 从 v1.1 起废弃

默认禁用。可通过 enableAudioVolumeIndication 方法开启;开启后,无论频道内是否有人说话,都会按方法中设置的时间间隔返回提示音量。

Declared In

AgoraRtcEngineKit.h

– firstLocalVideoFrameBlock:

本地首帧视频显示回调

- (void)firstLocalVideoFrameBlock:(void ( ^ _Nullable ) ( NSInteger width , NSInteger height , NSInteger elapsed ))firstLocalVideoFrameBlock

参数

firstLocalVideoFrameBlock

回调中包含:

  • width: 视频流宽(像素)
  • height: 视频流高(像素)
  • elapsed: 加入频道开始到该回调触发过去的时间(ms)

详情

DEPRECATED 从 v1.1 起废弃

提示第一帧本地视频画面已经显示在屏幕上。

Declared In

AgoraRtcEngineKit.h

– firstRemoteVideoDecodedBlock:

远端首帧视频显示回调

- (void)firstRemoteVideoDecodedBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger width , NSInteger height , NSInteger elapsed ))firstRemoteVideoDecodedBlock

参数

firstRemoteVideoDecodedBlock

回调中包含:

  • uid: 用户 ID,指定是哪个用户的视频流
  • width: 视频流宽(像素)
  • height: 视频流高(像素)
  • elapsed: 加入频道开始到该回调触发过去的时间(ms)

详情

DEPRECATED 从 v1.1 起废弃

Declared In

AgoraRtcEngineKit.h

– firstRemoteVideoFrameBlock:

远端首帧视频接收解码回调

- (void)firstRemoteVideoFrameBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger width , NSInteger height , NSInteger elapsed ))firstRemoteVideoFrameBlock

参数

firstRemoteVideoFrameBlock

回调中包含:

  • uid: 用户 ID,指定是哪个用户的视频流
  • width: 视频流宽(像素)
  • height: 视频流高(像素)
  • elapsed: 加入频道开始到该回调触发过去的时间(ms)

详情

DEPRECATED 从 v1.1 起废弃

提示已收到第一帧远端视频流并解码。

Declared In

AgoraRtcEngineKit.h

– userJoinedBlock:

用户加入回调

- (void)userJoinedBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger elapsed ))userJoinedBlock

参数

userJoinedBlock

回调中包含:

  • uid: 用户 ID。如果 joinChannelByToken 中指定了 uid,则此处返回该 ID;否则使用 Agora 服务器自动分配的 ID 。
  • elapsed: 加入频道开始到该回调触发过去的时间(ms)

详情

DEPRECATED 从 v1.1 起废弃

提示有用户加入了频道。如果该客户端加入频道时已经有人在频道中,SDK 也会向应用程序上报这些已在频道中的用户。

推荐使用

Declared In

AgoraRtcEngineKit.h

– userOfflineBlock:

用户离线回调

- (void)userOfflineBlock:(void ( ^ _Nullable ) ( NSUInteger uid ))userOfflineBlock

参数

userOfflineBlock

回调中包含 uid: 用户 ID

详情

DEPRECATED 从 v1.1 起废弃

提示有用户离开了频道(或掉线)。SDK 判断用户离开频道(或掉线)的依据是超时:在一定时间内(15 秒)没有收到对方的任何数据包,判定为对方掉线。在网络较差的情况下,可能会有误报。建议可靠的掉线检测应该由信令来做。

推荐使用

Declared In

AgoraRtcEngineKit.h

– userMuteAudioBlock:

用户音频静音回调

- (void)userMuteAudioBlock:(void ( ^ _Nullable ) ( NSUInteger uid , BOOL muted ))userMuteAudioBlock

参数

userMuteAudioBlock

回调中包含:

  • uid: 用户 ID
  • muted: 用户是否静音
    • YES: 静音
    • NO: 取消静音

详情

DEPRECATED 从 v1.1 起废弃

提示有用户将通话静音/取消静音。

推荐使用

Declared In

AgoraRtcEngineKit.h

– userMuteVideoBlock:

用户停止/重新发送视频回调

- (void)userMuteVideoBlock:(void ( ^ _Nullable ) ( NSUInteger uid , BOOL muted ))userMuteVideoBlock

参数

userMuteVideoBlock

回调中包含:

  • uid: 用户 ID
  • muted: 用户暂停/恢复发送视频流
    • YES: 该用户已暂停发送其视频流
    • NO: 该用户已恢复发送其视频流

详情

DEPRECATED 从 v1.1 起废弃

推荐使用

Declared In

AgoraRtcEngineKit.h

– localVideoStatBlock:

本地视频统计回调

- (void)localVideoStatBlock:(void ( ^ _Nullable ) ( NSInteger sentBitrate , NSInteger sentFrameRate ))localVideoStatBlock

参数

localVideoStatBlock

回调中包含:

  • sentBitrate: (上次统计后)发送的码率 (Kbps)
  • sentFrameRate: (上次统计后)发送的帧率 (fps)

详情

DEPRECATED 从 v1.1 起废弃

报告更新本地视频统计信息,该回调方法每两秒触发一次。

推荐使用

Declared In

AgoraRtcEngineKit.h

– remoteVideoStatBlock:

远端视频统计回调

- (void)remoteVideoStatBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger delay , NSInteger receivedBitrate , NSInteger receivedFrameRate ))remoteVideoStatBlock

参数

remoteVideoStatBlock

回调中包含:

  • uid: 用户 ID,指定远端视频来自哪个用户
  • delay: 延迟 (ms)
  • receivedBitrate: 上次统计后)接收到的码率 (Kbps)
  • receivedFrameRate: (上次统计后)接收的帧率 (fps)

详情

DEPRECATED 从 v1.1 起废弃

报告更新远端视频统计信息,该回调方法每两秒触发一次。

推荐使用

Declared In

AgoraRtcEngineKit.h

– cameraReadyBlock:

摄像头启用回调

- (void)cameraReadyBlock:(void ( ^ _Nullable ) ( void ))cameraReadyBlock

详情

DEPRECATED 从 v1.1 起废弃

提示已成功打开摄像头,可以开始捕获视频。

Declared In

AgoraRtcEngineKit.h

– connectionLostBlock:

网络连接丢失回调

- (void)connectionLostBlock:(void ( ^ _Nullable ) ( void ))connectionLostBlock

详情

DEPRECATED 从 v1.1 起废弃

该回调方法表示 SDK 与服务器失去了网络连接。

Declared In

AgoraRtcEngineKit.h

– rejoinChannelSuccessBlock:

重新加入频道回调

- (void)rejoinChannelSuccessBlock:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))rejoinChannelSuccessBlock

参数

rejoinChannelSuccessBlock

回调中包含:

  • channel: 频道名
  • uid: 用户 ID
  • elapsed: 加入延迟(ms)

详情

DEPRECATED 从 v1.1 起废弃

有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法,提示有用户重新加入了频道,且频道 ID 和用户 ID 均已分配。

推荐使用

Declared In

AgoraRtcEngineKit.h

– rtcStatsBlock:

Rtc Engine 统计数据回调

- (void)rtcStatsBlock:(void ( ^ _Nullable ) ( AgoraChannelStats *_Nonnull stat ))rtcStatsBlock

参数

rtcStatsBlock

回调中包含 stat, 详见 AgoraChannelStats

详情

DEPRECATED 从 v1.1 起废弃

该回调定期上报 Rtc Engine 的运行时的状态,每两秒触发一次。

推荐使用

Declared In

AgoraRtcEngineKit.h

– leaveChannelBlock:

离开频道回调

- (void)leaveChannelBlock:(void ( ^ _Nullable ) ( AgoraChannelStats *_Nonnull stat ))leaveChannelBlock

参数

leaveChannelBlock

回调中包含 stat, 详见 AgoraChannelStats

详情

DEPRECATED 从 v1.1 起废弃

显示用户离开了频道,提供会话数据信息,包括通话时长和 tx/rx 字节数。

Declared In

AgoraRtcEngineKit.h

– audioQualityBlock:

语音质量回调

- (void)audioQualityBlock:(void ( ^ _Nullable ) ( NSUInteger uid , AgoraNetworkQuality quality , NSUInteger delay , NSUInteger lost ))audioQualityBlock

参数

audioQualityBlock

回调中包含:

  • uid: 用户 ID 。每次回调上报一个用户当前的语音质量(不包含自己),不同用户在不同的回调中上报。
  • quality: 网络质量,详见 AgoraNetworkQuality
  • delay: 延迟(ms)
  • lost: 丢包率(百分比)

详情

DEPRECATED 从 v1.1 起废弃

在通话中,该回调方法每两秒触发一次,报告当前通话的(嘴到耳)音频质量。

推荐使用

Declared In

AgoraRtcEngineKit.h

– networkQualityBlock:

频道内网络质量报告回调

- (void)networkQualityBlock:(void ( ^ _Nullable ) ( NSUInteger uid , AgoraNetworkQuality txQuality , AgoraNetworkQuality rxQuality ))networkQualityBlock

参数

networkQualityBlock

回调中包含:

  • uid: 用户 ID。表示该回调报告的是持有该ID的用户的网络质量 。当 uid 为 0 时,返回的是本地用户的网络质量
  • txQuality: 该用户的上行网络质量,详见 AgoraNetworkQuality
  • rxQuality: 该用户的下行网络质量,详见 AgoraNetworkQuality

详情

DEPRECATED 从 v1.1 起废弃

该回调每 2 秒触发,向 App 报告频道内所有用户当前的上行、下行网络质量。

推荐使用

Declared In

AgoraRtcEngineKit.h

– lastmileQualityBlock:

本地用户网络质量回调

- (void)lastmileQualityBlock:(void ( ^ _Nullable ) ( AgoraNetworkQuality quality ))lastmileQualityBlock

参数

lastmileQualityBlock

回调中包含 quality: 网络质量的评分,详见 AgoraNetworkQuality

详情

DEPRECATED 从 v1.1 起废弃

报告本地用户的网络质量。该回调方法每两秒触发一次。

推荐使用

Declared In

AgoraRtcEngineKit.h

– mediaEngineEventBlock:

Media engine 事件回调

- (void)mediaEngineEventBlock:(void ( ^ _Nullable ) ( NSInteger code ))mediaEngineEventBlock

详情

DEPRECATED 从 v1.1 起废弃

Declared In

AgoraRtcEngineKit.h

X
本篇文章对你是否有帮助?