AgoraRtcEngineKit Class Reference

Inherits from NSObject
Declared in AgoraRtcEngineKit.h

Overview

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

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

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

核心方法

+ sharedEngineWithAppId:delegate:

创建 AgoraRtcEngineKit 实例

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

Parameters

appId

声网为 app 开发者签发的 App ID,详见获取 App ID。使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 AgoraRtcEngineKit。如需更换 App ID,必须先调用 destroy 销毁当前 AgoraRtcEngineKit,并在 destroy 成功返回后,再调用 sharedEngineWithAppId 重新创建 AgoraRtcEngineKit。

delegate

AgoraRtcEngineDelegate

Return Value

  • 方法调用成功,返回一个 AgoraRtcEngineKit 对象。
  • 方法调用失败,返回错误码。

    • -1(AgoraErrorCodeFailed): 一般性的错误(未明确归类)
    • -2(AgoraErrorCodeInvalidArgument): 未提供 AgoraRtcEngineDelegate 对象
    • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化
    • -101(AgoraErrorCodeInvalidAppId):不是有效的 App ID。

Discussion

AgoraRtcEngineKit 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。

Note

  • 请确保在调用其他 API 前先调用该方法创建并初始化 AgoraRtcEngineKit。
  • 调用该方法和 sharedEngineWithConfig 均能创建 AgoraRtcEngineKit 实例。该方法与 sharedEngineWithConfig 的区别在于,sharedEngineWithConfig 支持在创建 AgoraRtcEngineKit 实例时指定访问区域。
  • 目前声网 RTC Native SDK 只支持每个 app 创建一个 AgoraRtcEngineKit 实例。

Declared In

AgoraRtcEngineKit.h

+ sharedEngineWithConfig:delegate:

创建 AgoraRtcEngineKit 实例

+ (instancetype _Nonnull)sharedEngineWithConfig:(AgoraRtcEngineConfig *_Nonnull)config delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate

Parameters

config

AgoraRtcEngineKit 实例的配置,详见 AgoraRtcEngineConfig

delegate

AgoraRtcEngineDelegate.

Return Value

  • 方法调用成功,返回一个 AgoraRtcEngineKit 对象。
  • 方法调用失败,返回错误码。

    • -1(AgoraErrorCodeFailed): 一般性的错误(未明确归类)
    • -2(AgoraErrorCodeInvalidArgument): 未提供 AgoraRtcEngineDelegate 对象
    • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化
    • -101(AgoraErrorCodeInvalidAppId):不是有效的 App ID。

Discussion

AgoraRtcEngineKit 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。

Note

  • 请确保在调用其他 API 前先调用该方法创建并初始化 AgoraRtcEngineKit。
  • 调用该方法和 sharedEngineWithAppId 均能创建 AgoraRtcEngineKit 实例。该方法与 sharedEngineWithAppId 的区别在于,该方法支持在创建 AgoraRtcEngineKit 实例时指定访问区域。
  • 目前声网 RTC Native SDK 只支持每个 app 创建一个 AgoraRtcEngineKit 实例。

Declared In

AgoraRtcEngineKit.h

+ destroy

销毁 AgoraRtcEngineKit 实例

+ (void)destroy

Discussion

该方法释放 SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信,不需要时则将资源释放出来用于其他操作,该方法适用于此类情况。调用 destroy 方法后,你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能,你必须重新调用 sharedEngineWithAppId 方法创建一个新的 AgoraRtcEngineKit 实例。

Note:

  • 该方法为同步调用,需要等待 AgoraRtcEngineKit 实例资源释放后才能执行其他操作,所以我们建议在子线程中调用该方法,避免主线程阻塞。此外,我们不建议 在 SDK 的回调中调用 destroy,否则由于 SDK 要等待回调返回才能回收相关的对象资源,会造成死锁。
  • 如需在销毁后再次创建 AgoraRtcEngineKit 实例,需要等待destroy` 方法执行结束后再创建实例。

Declared In

AgoraRtcEngineKit.h

– setChannelProfile:

该方法用于设置 AgoraRtcEngineKit 频道的使用场景。

- (int)setChannelProfile:(AgoraChannelProfile)profile

Parameters

profile

频道使用场景。详见 AgoraChannelProfile

Return Value

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

    • -2(AgoraErrorCodeInvalidArgument): 参数无效
    • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化

Discussion

SDK 初始化后默认的频道场景为通信场景,AgoraRtcEngineKit 会针对不同的使用场景采用不同的优化策略, 如通信场景偏好流畅,直播场景偏好画质。

Note:

  • 为保证实时音视频质量,我们建议相同频道内的用户使用同一种频道场景。
  • 该方法必须在加入频道前调用,进入频道后无法再设置频道场景。
  • 不同的频道场景下,SDK 的默认音频路由和默认视频编码码率是不同的,详见 setDefaultAudioRouteToSpeakerphonesetVideoEncoderConfiguration 中的说明。

Declared In

AgoraRtcEngineKit.h

– setClientRole:

设置直播场景下的用户角色。

- (int)setClientRole:(AgoraClientRole)role

Parameters

role

直播场景里的用户角色,详见 AgoraClientRole

Return Value

  • 0(AgoraErrorCodeNoError): 方法调用成功。
  • < 0: 方法调用失败。

    • -1(AgoraErrorCodeFailed): 一般性的错误(未明确归类)。
    • -2(AgoraErrorCodeInvalidArgument): 参数无效。
    • -5 (AgoraErrorCodeRefused): 调用被拒绝。在多频道场景中, 如果你已在一个频道中进行如下设置,则用户在另一个频道内切换角色为主播时会返回该错误码:

      • 调用带 options 参数的 joinChannelByToken, 并使用默认设置 publishLocalAudio = YESpublishLocalVideo = YES
      • 调用 setClientRole,并设置用户角色为主播。
      • 调用 muteLocalAudioStream(NO)muteLocalVideoStream(NO)

      • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化。

Discussion

调用 setChannelProfile(AgoraChannelProfileLiveBroadcasting) 后,SDK 会默认设置用户角色为观众,你可以调用 setClientRole 设置用户角色为主播。

该方法在加入频道前后均可调用。如果你在加入频道后调用该方法切换用户角色,调用成功后,SDK 会自动进行如下操作:

Note: 该方法仅适用于直播场景。

Declared In

AgoraRtcEngineKit.h

– setClientRole:options:

设置直播场景下的用户角色。

- (int)setClientRole:(AgoraClientRole)role options:(AgoraClientRoleOptions *_Nullable)options

Parameters

role

直播场景中的用户角色,详见 AgoraClientRole

options

用户具体设置,包含用户级别,详见 AgoraClientRoleOptions

Return Value

  • 0(AgoraErrorCodeNoError): 方法调用成功。
  • < 0: 方法调用失败。

    • -1(AgoraErrorCodeFailed): 一般性的错误(未明确归类)。
    • -2(AgoraErrorCodeInvalidArgument): 参数无效。
    • -5 (AgoraErrorCodeRefused): 调用被拒绝。在多频道场景中, 如果你已在一个频道中进行如下设置,则用户在另一个频道内切换角色为主播时会返回该错误码:

      • 调用带 options 参数的 joinChannelByToken, 并使用默认设置 publishLocalAudio = YESpublishLocalVideo = YES
      • 调用 setClientRole,并设置用户角色为主播。
      • 调用 muteLocalAudioStream(NO)muteLocalVideoStream(NO)

      • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化。

Availability

v3.2.0

调用 setChannelProfile(AgoraChannelProfileLiveBroadcasting) 后,SDK 会默认设置用户角色为观众,你可以调用 setClientRole 设置用户角色为主播。

该方法在加入频道前后均可调用。如果你在加入频道后调用该方法切换用户角色,调用成功后,SDK 会自动进行如下操作:

Note

  • 该方法仅适用于直播场景。
  • 该方法与 setClientRole1 的区别在于,该方法还支持设置用户级别。

    • 用户角色 (role) 确定用户在 SDK 层的权限,包含是否可以发送流、是否可以接收流、是否可以推流到 CDN 等。
    • 用户级别 (level) 需要与角色结合使用,确定用户在其权限范围内,可以操作和享受到的服务级别。 例如对于观众,选择接收低延时还是超低延时的视频流。用户级别会影响计费

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

Parameters

token

在你服务器上生成的 Token。详见使用 Token 鉴权

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 。

Return Value

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

    • -2(AgoraErrorCodeInvalidArgument): 参数无效。
    • -3(AgoraErrorCodeNotReady): SDK 初始化失败,请尝试重新初始化 SDK。
    • -5(AgoraErrorCodeRefused):调用被拒绝。可能有如下两个原因:

      • 已经创建了一个同名的 AgoraRtcChannel 频道。
      • 已经通过 AgoraRtcChannel 加入了一个频道,并在该 AgoraRtcChannel 频道中发布了音视频流。由于通过 AgoraRtcEngineKit 加入频道会默认发布音视频流,而 SDK 不支持同时在两个频道发布音视频流,因此会报错。
    • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化,就调用其 API。请确认在调用 API 之前已创建 AgoraRtcEngineKit 并完成初始化。

    • -17(AgoraErrorCodeJoinChannelRejected)):加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 AgoraRtcEngineKit 频道,当已经加入 AgoraRtcEngineKit 频道的用户使用有效的频道名再次调用 AgoraRtcEngineKit 类中的加入频道方法时,会返回此错误码。

Discussion

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

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

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

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

用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– joinChannelByToken:channelId:info:uid:options:

加入频道并设置是否发布或自动订阅音频或视频流。

- (int)joinChannelByToken:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId info:(NSString *_Nullable)info uid:(NSUInteger)uid options:(AgoraRtcChannelMediaOptions *_Nonnull)options

Parameters

token

在 app 服务端生成的用于鉴权的 Token。详见服务端生成 Token

channelId

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

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

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

uid

(非必选项)用户 ID,32 位无符号整数。建议设置范围:1 到 (232-1),并保证唯一性。如果不指定(即设为 0),SDK 会自动分配一个,并在 didJoinChannel 回调方法中返回,App 需自行维护该返回值,SDK 不对该返回值进行维护。

Note: 频道内每个用户的 UID 必须是唯一的。如果想要从不同的设备同时接入同一个频道,请确保每个设备上使用的 UID 是不同的。

options

频道媒体设置选项:AgoraRtcChannelMediaOptions

Return Value

  • 0(AgoraErrorCodeNoError): 方法调用成功。
  • < 0: 方法调用失败。

    • -2(AgoraErrorCodeInvalidArgument): 参数无效。
    • -3(AgoraErrorCodeNotReady): SDK 初始化失败,请尝试重新初始化 SDK。
    • -5(AgoraErrorCodeRefused): 调用被拒绝。可能有如下两个原因:

      • 已经创建了一个同名的 AgoraRtcChannel 频道。
      • 已经通过 AgoraRtcChannel 加入了一个频道,并在该 AgoraRtcChannel 频道中发布了音视频流。由于通过 AgoraRtcEngineKit 加入频道会默认发布音视频流,而 SDK 不支持同时在两个频道发布音视频流,因此会报错。
    • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化,就调用其 API。请确认在调用 API 之前已创建 AgoraRtcEngineKit 并完成初始化。

    • -17(AgoraErrorCodeJoinChannelRejected):加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 AgoraRtcEngineKit 频道,当已经加入 AgoraRtcEngineKit 频道的用户使用有效的频道名再次调用 AgoraRtcEngineKit 类中的加入频道方法时,会返回此错误码。

Availability

v3.3.0

该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。使用不同 App ID 的 App 是不能互通的。

如果已在通话中,用户必须调用 leaveChannel 退出当前通话,才能进入下一个频道。

成功调用该方法加入频道后,本地会触发 didJoinChannel 回调; 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 didJoinedOfUid 回调。

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

Note

  • 相比于 joinChannelByToken1, 该方法加了 options 参数,用于配置用户加入频道时是否发布或自动订阅音视频流。默认情况下,用户发布本地音视频流并自动订阅频道内所有其他用户的音视频流。 订阅音视频流会产生用量并影响计费。如果想取消订阅,可以通过设置 options 参数或相应的 mute 方法实现。
  • 请确保用于生成 Token 的 App ID 与用 sharedEngineWithAppId 方法创建 AgoraRtcEngineKit 对象时的 App ID 一致。

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

Parameters

userAccount

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

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

在你服务器上生成的 Token。详见使用 Token 鉴权

channelId

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

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

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

Return Value

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

    • AgoraErrorCodeInvalidToken(110):不是有效的 Token。请更换有效的 Token 重新加入频道。建议你进行如下检查:

      • 检查生成 Token 的 uid 与 joinChannelByUserAccount 方法中的 uid 是否一致
      • 检查 Token 的格式是否有效
      • 检查 Token 与 App ID 是否匹配
    • -17(AgoraErrorCodeJoinChannelRejected):加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 AgoraRtcEngineKit 频道,当已经加入 AgoraRtcEngineKit 频道的用户使用有效的频道名再次调用 AgoraRtcEngineKit 类中的加入频道方法时,会返回此错误码。

Discussion

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

用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。

Note

  • 请确保在使用 String 型用户名前阅读如何使用 String 型用户 ID,了解使用限制及实现方法。
  • 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。

Declared In

AgoraRtcEngineKit.h

– joinChannelByUserAccount:token:channelId:options:

使用 User Account 加入频道,并设置是否自动订阅音频或视频流。

- (int)joinChannelByUserAccount:(NSString *_Nonnull)userAccount token:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId options:(AgoraRtcChannelMediaOptions *_Nonnull)options

Parameters

userAccount

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

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

在 app 服务端生成的用于鉴权的 Token。详见服务端生成 Token

channelId

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

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

频道媒体设置选项:AgoraRtcChannelMediaOptions

Return Value

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

    • AgoraErrorCodeInvalidArgument(-2)
    • AgoraErrorCodeNotReady(-3)
    • AgoraErrorCodeRefused(-5)
    • AgoraErrorCodeSDKNotInitialized(-7)
    • AgoraErrorCodeJoinChannelRejected(-17):加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 AgoraRtcEngineKit 频道,当已经加入 AgoraRtcEngineKit 频道的用户使用有效的频道名再次调用 AgoraRtcEngineKit 类中的加入频道方法时,会返回此错误码。

Availability

v3.3.0

该方法允许本地用户使用 User Account 加入频道。

成功加入频道后,会触发以下回调:

Note

  • 请确保在使用 String 型用户名前阅读如何使用 String 型用户 ID,了解使用限制及实现方法。
  • 相比 joinChannelByUserAccount1, 该方法加了 options 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流, 因此会产生用量并影响计费。如果想取消订阅,可以通过设置 options 参数或相应的 mute 方法实现。
  • 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。

Declared In

AgoraRtcEngineKit.h

– registerLocalUserAccount:appId:

注册本地用户 User Account

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

Parameters

userAccount

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

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

你的项目在声网控制台注册的 App ID

Return Value

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

Discussion

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

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

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– getUserInfoByUserAccount:withError:

通过 User Account 获取用户信息

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

Parameters

userAccount

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

error

AgoraErrorCode 的指针,可以为空。

Return Value

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

Discussion

远端用户加入频道后,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

Parameters

uid

用户 UID。该参数为必填

error

AgoraErrorCode 的指针,可以为空。

Return Value

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

Discussion

远端用户加入频道后,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

Parameters

token

在你服务器上生成的 Token。详见使用 Token 鉴权

channelId

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

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

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

Return Value

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

    • -1(AgoraErrorCodeFailed): 一般性的错误(未明确归类)
    • -2(AgoraErrorCodeInvalidArgument): 参数无效
    • -5(AgoraErrorCodeRefused): 调用被拒绝。可能因为用户角色不是观众
    • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化
    • -102(AgoraErrorCodeInvalidChannelId):频道名无效。请更换有效的频道名
    • -113(AgoraErrorCodeNotInChannel):用户不在频道内

Discussion

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

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

用户成功切换频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。

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

Declared In

AgoraRtcEngineKit.h

– switchChannelByToken:channelId:options:

快速切换直播频道,并设置是否自动订阅目标频道的音频流或视频流。

- (int)switchChannelByToken:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId options:(AgoraRtcChannelMediaOptions *_Nonnull)options

Parameters

token

在 app 服务端生成的用于鉴权的 Token。详见服务端生成 Token

channelId

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

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

频道媒体设置选项:AgoraRtcChannelMediaOptions

Return Value

  • 0(AgoraErrorCodeNoError): 方法调用成功。
  • < 0: 方法调用失败。

    • -1(AgoraErrorCodeFailed): 一般性的错误(未明确归类)。
    • -2(AgoraErrorCodeInvalidArgument): 参数无效。
    • -5(AgoraErrorCodeRefused): 调用被拒绝。可能因为用户角色不是观众。
    • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化。
    • -102(AgoraErrorCodeInvalidChannelId): 频道名无效。请更换有效的频道名。
    • -113(AgoraErrorCodeNotInChannel): 用户不在频道内。

Availability

v3.3.0

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

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

用户成功切换频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。

Note

  • 该方法仅适用直播频道中的观众用户。
  • 该方法和 switchChannelByToken1 的区别在于, 该方法加了 options 参数,用于配置终端用户在切换到新的频道时是否自动订阅频道内所有远端音视频流。 默认情况下,用户订阅新的频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅, 可以通过设置 options 参数或相应的 mute 方法实现。

Declared In

AgoraRtcEngineKit.h

– leaveChannel:

离开频道

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

Parameters

leaveChannelBlock

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

Return Value

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

    • -1(AgoraErrorCodeFailed): 一般性的错误(未明确归类)
    • -2(AgoraErrorCodeInvalidArgument): 参数无效
    • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化

Discussion

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

当调用 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

– setAVSyncSource:uid:

设置发流端音画同步。

- (int)setAVSyncSource:(NSString *_Nullable)channelId uid:(NSUInteger)uid

Parameters

channelId

标识音频发送端所在频道的频道名。

uid

音频发送端的用户 ID。

Return Value

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

Availability

v3.6.0

同一用户可能使用两个设备分别发送音频流和视频流,为保证接收端听到和看到的音频和视频的时间同步性,你可以在视频发送端调用该方法,并传入音频发送端的频道名、用户 ID。SDK 会以发送的音频流的时间戳为基准进行自动调节发送的视频流,以保证即使在两个发送端的上行网络情况不一致(如分别使用 Wi-Fi 和 4G 网络)的情况下,也能让接收到的音视频具有时间同步性。

Discussion

Note: 声网推荐你在加入频道前调用该方法。

Declared In

AgoraRtcEngineKit.h

– renewToken:

更新 Token

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

Parameters

token

新的 Token

Return Value

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

    • -1(AgoraErrorCodeFailed): 一般性的错误(未明确归类)
    • -2(AgoraErrorCodeInvalidArgument): 参数无效
    • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– getConnectionState

获取当前网络连接状态

- (AgoraConnectionStateType)getConnectionState

Return Value

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

Discussion

该方法在加入频道前后都能调用。

Declared In

AgoraRtcEngineKit.h

跨频道媒体流转发

– startChannelMediaRelay:

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

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

Parameters

config

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

Return Value

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

Discussion

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

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

Note

  • 请在成功加入频道后调用该方法。
  • 该方法仅对直播场景下的主播有效。
  • 成功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
  • 跨频道媒体流转发功能需要提交工单联系技术支持开通。
  • 该功能不支持 String 型 UID。

Declared In

AgoraRtcEngineKit.h

– updateChannelMediaRelay:

更新媒体流转发的频道。成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。

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

Parameters

config

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

Return Value

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

Discussion

成功调用该方法后,SDK 会触发 didReceiveChannelMediaRelayEvent 回调,并在回调中报告状态码 AgoraChannelMediaRelayEventUpdateDestinationChannel(7)。

Note

  • 请在成功调用 startChannelMediaRelay 方法并收到 channelMediaRelayStateDidChange (AgoraChannelMediaRelayStateRunning, AgoraChannelMediaRelayErrorNone) 后调用该方法;否则,方法调用会失败。
  • 跨频道媒体流转发最多支持 4 个目标频道。如果直播间里已经有 4 个频道了,你可以在调用该方法之前,调用 AgoraChannelMediaRelayConfiguration 中的 removeDestinationInfoForChannelName 方法移除不需要的频道。

Declared In

AgoraRtcEngineKit.h

– pauseAllChannelMediaRelay

暂停向所有目标频道转发媒体流。

- (int)pauseAllChannelMediaRelay

Return Value

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

Availability

v3.5.1

开始跨频道转发媒体流后,如果你需要暂停向所有频道转发媒体流,可以调用该方法;暂停后, 如果要恢复跨频道媒体流转发,可以调用 resumeAllChannelMediaRelay 方法。

成功调用该方法后,SDK 会触发 didReceiveChannelMediaRelayEvent 回调,并在回调中报告是否成功暂停媒体流转发。

Discussion

Note: 该方法需要在 startChannelMediaRelay 后调用。

Declared In

AgoraRtcEngineKit.h

– resumeAllChannelMediaRelay

恢复向所有目标频道转发媒体流。

- (int)resumeAllChannelMediaRelay

Return Value

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

Availability

v3.5.1

调用 pauseAllChannelMediaRelay 方法后,如果你需要恢复向所有目标频道转发媒体流,可以调用该方法。

成功调用该方法后,SDK 会触发 didReceiveChannelMediaRelayEvent 回调,并在回调中报告是否成功恢复媒体流转发。

Discussion

Note: 该方法需要在 pauseAllChannelMediaRelay 后调用。

Declared In

AgoraRtcEngineKit.h

– stopChannelMediaRelay

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

- (int)stopChannelMediaRelay

Return Value

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

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

网络代理

– setCloudProxy:

设置声网云代理服务。

- (int)setCloudProxy:(AgoraCloudProxyType)proxyType

Parameters

proxyType

云代理类型,详见 AgoraCloudProxyType 。该参数为必填参数,如果你不赋值,SDK 会报错。

Return Value

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

    • -2(AgoraErrorCodeInvalidArgument): 传入的参数无效。
    • -7(AgoraErrorCodeNotInitialized): SDK 尚未初始化。

Availability

v3.3.0

当用户的网络访问受到防火墙限制时,你需要将声网提供的 IP 和端口号添加到防火墙白名单,然后调用该方法开启云代理,并通过 proxyType 参数设置云代理类型。

成功连接云代理后,SDK 会触发 connectionChangedToState(AgoraConnectionStateConnecting, AgoraConnectionChangedSettingProxyServer) 回调。

自 v3.6.2 起,当用户调用该方法并成功加入频道后,SDK 会触发 didProxyConnected 回调,报告用户 ID、连接的代理类型和用户调用 joinChannelByToken 到 SDK 触发该回调的经过的时间等。

如果你想关闭已设置的云代理,请调用 setCloudProxy(AgoraNoneProxy)。如果你想更改已设置的云代理类型,请先调用 setCloudProxy(AgoraNoneProxy), 再调用 setCloudProxy 并传入你期望的 proxyType 值。

Note

  • 声网推荐你在频道外调用该方法。
  • 对 3.3.x 版 SDK,使用 Force UDP 云代理时,旁路推流和跨频道媒体流转发功能不可用。对 3.4.0 及之后版 SDK,如果用户处于内网防火墙环境下,使用 Force UDP 云代理时,旁路推流和跨频道媒体流转发功能不可用。
  • 使用 Force TCP 云代理时:
    • 调用 startAudioMixing 方法时无法播放 HTTP 协议的在线音频文件。
    • 旁路推流和跨频道媒体流转发功能会用 TCP 协议的云代理。

Declared In

AgoraRtcEngineKit.h

– setLocalAccessPoint:

设置本地代理。

- (int)setLocalAccessPoint:(AgoraLocalAccessPointConfiguration *_Nonnull)config

Parameters

config

Local Access Point 的配置。详见 AgoraLocalAccessPointConfiguration

Return Value

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

Availability

v3.7.1

成功部署声网混合云或声网私有化平台并在内网终端集成声网 Native SDK 后,你需要调用该方法指定 Local Access Point 来设置本地代理。成功设置本地代理后,SDK 会自动将日志上传到声网日志服务器。如果你需要将日志上传到指定的服务器,可以在通过 AgoraLocalAccessPointConfigurationAdvancedConfigInfo 设置。

Note:

  • 该方法仅在部署声网混合云或声网实时音视频私有化平台后生效。你可以联系 sales@agora.io 了解和部署声网混合云或声网私有化平台。
  • 该方法需要加入频道前调用。

Declared In

AgoraRtcEngineKit.h

音频核心方法

– enableAudio

启用音频模块

- (int)enableAudio

Return Value

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

Discussion

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

Note:

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

  • 该方法开启整个音频模块,响应速度较慢,因此声网建议使用如下方法来控制音频模块:

Declared In

AgoraRtcEngineKit.h

– disableAudio

关闭音频模块

- (int)disableAudio

Return Value

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

Discussion

Note:

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

  • 该方法关闭整个音频模块,响应速度较慢,因此声网建议使用如下方法来控制音频模块:

Declared In

AgoraRtcEngineKit.h

– setAudioProfile:scenario:

设置音频编码配置

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

Parameters

profile

设置采样率,码率,编码模式和声道数: AgoraAudioProfile

scenario

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

Return Value

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

Discussion

Note:

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

Declared In

AgoraRtcEngineKit.h

– adjustRecordingSignalVolume:

调节麦克风采集信号音量

- (int)adjustRecordingSignalVolume:(NSInteger)volume

Parameters

volume

麦克风采集信号音量。取值范围为 [0,400],其中:

  • 0: 静音
  • 100:(默认)原始音量
  • 400: 原始音量的 4 倍(自带溢出保护)

Return Value

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

Discussion

该方法在加入频道前后都能调用。

Declared In

AgoraRtcEngineKit.h

– adjustLoopbackRecordingSignalVolume:

调节声卡采集信号音量

- (int)adjustLoopbackRecordingSignalVolume:(NSInteger)volume

Parameters

volume

声卡采集信号音量。取值范围为 [0,100],其中:

  • 0: 静音
  • 100:(默认)原始音量

Return Value

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

Availability

v3.4.0

调用 enableLoopbackRecording 开启声卡采集后,你可以调用该方法调节声卡采集的信号音量。

Discussion

Note: 该方法仅适用于 macOS。

Declared In

AgoraRtcEngineKit.h

– adjustPlaybackSignalVolume:

调节本地播放的所有远端用户的信号音量

- (int)adjustPlaybackSignalVolume:(NSInteger)volume

Parameters

volume

播放音量。取值范围为 [0,400],其中:

  • 0: 静音
  • 100:(默认)原始音量
  • 400: 原始音量的 4 倍(自带溢出保护)

Return Value

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

Discussion

该方法在加入频道前后都能调用。

Note

  • 该方法调节的是本地播放的所有远端用户混音后的音量。
  • 从 v2.3.2 开始,静音本地音频需同时调用 adjustPlaybackSignalVolumeadjustAudioMixingPlayoutVolume 方法,并将 volume 参数设置为 0。

Declared In

AgoraRtcEngineKit.h

– enableAudioVolumeIndication:smooth:report_vad:

启用用户音量提示

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

Parameters

interval

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

  • ≤ 0: 禁用音量提示功能
  • 0: 提示间隔,单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒。

smooth

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

report_vad
  • YES:开启本地人声检测功能。开启后, reportAudioVolumeIndicationOfSpeakers 回调的 vad 参数会报告是否在本地检测到人声。
  • NO:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外, reportAudioVolumeIndicationOfSpeakers 回调的 vad 参数不会报告是否在本地检测到人声。

Return Value

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

Discussion

该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。启用该方法后,只要频道内有发流用户,SDK 会在加入频道后按设置的时间间隔触发 reportAudioVolumeIndicationOfSpeakers 回调。

该方法在加入频道前后都能调用。

Declared In

AgoraRtcEngineKit.h

– enableLocalVoicePitchCallback:

开启本地语音音调回调。

- (int)enableLocalVoicePitchCallback:(NSInteger)interval

Parameters

interval

设置 SDK 触发 reportLocalVoicePitchFrequency 回调的时间间隔:

  • ≤ 0: 关闭 reportLocalVoicePitchFrequency 回调。
  • > 0: SDK 触发 reportLocalVoicePitchFrequency 回调的时间间隔,单位为毫秒。取值需大于等于 10 毫秒,如果小于 10 毫秒,SDK 会自动调整为 10 毫秒。

Return Value

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

Availability

v3.7.0

该方法允许 SDK 定期向 app 报告本地用户的语音音调。开启本地音频采集并调用该方法后,SDK 会按设置的时间间隔触发 reportLocalVoicePitchFrequency 回调。

Discussion

Note: 该方法在加入频道前后均可调用。

Declared In

AgoraRtcEngineKit.h

– enableLocalAudio:

开关本地音频采集

- (int)enableLocalAudio:(BOOL)enabled

Parameters

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

Return Value

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

Discussion

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

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

语音功能关闭或重新开启后,会收到 localAudioStateChange 回调并报告 AgoraAudioLocalStateStopped(0)AgoraAudioLocalStateRecording(1)

Note:

  • 该方法在加入频道前后均可调用。在加入频道前调用只能设置设备状态,在加入频道后才会立即生效。
  • 该方法与 muteLocalAudioStream 的区别在于:

    • enableLocalAudio:开启或关闭本地语音采集及处理。使用 enableLocalAudio 关闭或开启本地采集后,本地听远端播放会有短暂中断。
    • muteLocalAudioStream:停止或继续发送本地音频流。

Declared In

AgoraRtcEngineKit.h

– muteLocalAudioStream:

取消或恢复发布本地音频流。

- (int)muteLocalAudioStream:(BOOL)mute

Parameters

mute

是否取消发布本地音频流:

  • YES: 取消发布。
  • NO: 发布。

Return Value

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

    • -5 (AgoraErrorCodeRefused): 调用被拒绝。

Discussion

自 v3.4.5 起,该方法仅设置用户在 AgoraRtcEngineKit 频道中的音频发布状态。

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

同一时间,本地的音视频流只能发布到一个频道。如果你创建了多个频道,请确保你只在一个频道中调用 muteLocalAudioStream(NO),否则方法会调用失败并返回 -5 (AgoraErrorCodeRefused)

Note

  • 该方法不会改变音频采集设备的使用状态。
  • 该方法的调用是否生效受 joinChannelByTokensetClientRole 方法的影响,详见《设置发布状态》。

Declared In

AgoraRtcEngineKit.h

– muteRemoteAudioStream:mute:

取消或恢复订阅指定远端用户的音频流。

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

Parameters

uid

指定用户的用户 ID。

mute

是否取消订阅指定远端用户的音频流。

  • YES: 取消订阅。
  • NO: (默认)订阅。

Return Value

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

Discussion

Note

  • 该方法需要在加入频道后调用。
  • 该方法的推荐设置详见《设置订阅状态》。

Declared In

AgoraRtcEngineKit.h

– muteAllRemoteAudioStreams:

取消或恢复订阅所有远端用户的音频流。

- (int)muteAllRemoteAudioStreams:(BOOL)mute

Parameters

mute

是否取消订阅所有远端用户的音频流。

  • YES: 取消订阅。
  • NO: (默认)订阅。

Return Value

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

Discussion

成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流, 包括在调用该方法后加入频道的用户的音频流。

Note

  • 该方法需要在加入频道后调用。
  • 自 v3.3.0 起,该方法包含了 setDefaultMuteAllRemoteAudioStreams 的功能。声网建议不要一起调用 muteAllRemoteAudioStreamssetDefaultMuteAllRemoteAudioStreams,否则设置可能会不生效。详见《设置订阅状态》。

Declared In

AgoraRtcEngineKit.h

– adjustUserPlaybackSignalVolume:volume:

调节本地播放的指定远端用户的信号音量。

- (int)adjustUserPlaybackSignalVolume:(NSUInteger)uid volume:(int)volume

Parameters

uid

远端用户 ID,需和远端用户加入频道时用的 uid 一致。

volume

播放音量。取值范围为 [0,100],其中:

  • 0: 静音
  • 100:(默认)原始音量

Return Value

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

Discussion

加入频道后,你可以多次调用该方法调节不同远端用户在本地播放的音量,或对某个远端用户在本地播放的音量调节多次。

Note

  • 该方法要在加入频道后调用。
  • 该方法调节的是本地播放的指定远端用户混音后的音量。
  • 该方法每次只能调整一位远端用户在本地播放的音量。若需调整多位远端用户在本地播放的音量,则需多次调用该方法。

Declared In

AgoraRtcEngineKit.h

视频核心方法

– enableVideo

启用视频模块

- (int)enableVideo

Return Value

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

Discussion

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

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

Note:

Declared In

AgoraRtcEngineKit.h

– disableVideo

关闭视频模块

- (int)disableVideo

Return Value

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

Discussion

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

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

Note:

Declared In

AgoraRtcEngineKit.h

– setVideoEncoderConfiguration:

设置视频编码配置

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

Parameters

config

AgoraVideoEncoderConfiguration

Return Value

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

Discussion

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

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

该方法在加入频道前后都能调用。

Note:

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

Declared In

AgoraRtcEngineKit.h

– setupLocalVideo:

初始化本地视图。

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

Parameters

local

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

Return Value

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

Discussion

该方法初始化本地视图并设置本地用户视频显示信息,只影响本地用户看到的视频画面,不影响本地发布视频。调用该方法绑定本地视频流的显示视窗(view),并设置本地用户视图的渲染模式和镜像模式。在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入频道。退出频道后,绑定仍然有效,如果需要解除绑定,可以指定空 (nil) view 调用本方法。

该方法在加入频道前后都能调用。

Note

如果你希望在通话中更新本地用户视图的渲染或镜像模式,请使用 setLocalRenderMode 方法。

Declared In

AgoraRtcEngineKit.h

– setupRemoteVideo:

初始化远端用户视图。

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

Parameters

remote

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

Return Value

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

Discussion

该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。调用该接口时需要指定远端用户的 uid,一般可以在进频道前提前设置好。

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

Note: 如果你希望在通话中更新远端用户视图的渲染或镜像模式,请使用 setRemoteRenderMode 方法。

Declared In

AgoraRtcEngineKit.h

– setLocalRenderMode:mirrorMode:

更新本地视图显示模式。

- (int)setLocalRenderMode:(AgoraVideoRenderMode)renderMode mirrorMode:(AgoraVideoMirrorMode)mirrorMode

Parameters

renderMode

本地视图的渲染模式,详见 AgoraVideoRenderMode

mirrorMode

本地视图的镜像模式,详见 AgoraVideoMirrorMode

Note 如果你使用前置摄像头,默认启动本地用户视图镜像模式;如果你使用后置摄像头,默认关闭本地视图镜像模式。

Return Value

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

Discussion

自从 v3.0.0

初始化本地用户视图后,你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面,不影响本地发布视频。

Note

  • 请在调用 setupLocalVideo 方法初始化本地视图后,调用该方法。
  • 你可以在通话中多次调用该方法,多次更新本地用户视图的显示模式。

Declared In

AgoraRtcEngineKit.h

– setRemoteRenderMode:renderMode:mirrorMode:

更新远端视图显示模式。

- (int)setRemoteRenderMode:(NSUInteger)uid renderMode:(AgoraVideoRenderMode)renderMode mirrorMode:(AgoraVideoMirrorMode)mirrorMode

Parameters

uid

远端用户 ID。

renderMode

远端用户视图的渲染模式,详见 AgoraVideoRenderMode

mirrorMode

远端用户视图的镜像模式,详见 AgoraVideoMirrorMode

Note

默认关闭远端用户的镜像模式。

Return Value

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

Discussion

自从 v3.0.0

初始化远端用户视图后,你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。

Note

  • 请在调用 setupRemoteVideo 方法初始化远端视图后,调用该方法。
  • 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。

Declared In

AgoraRtcEngineKit.h

– startPreview

开启视频预览

- (int)startPreview

Return Value

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

Discussion

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

调用该 API 前,必须

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

Declared In

AgoraRtcEngineKit.h

– stopPreview

停止本地视频预览

- (int)stopPreview

Return Value

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

Discussion

调用 startPreview 后,如果你想关闭本地视频预览, 请调用 stopPreview

Note: 请在加入频道前或离开频道后调用该方法。

Declared In

AgoraRtcEngineKit.h

– enableLocalVideo:

开关本地视频采集

- (int)enableLocalVideo:(BOOL)enabled

Parameters

enabled

是否启用本地视频:

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

Return Value

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

Discussion

该方法禁用或重新启用本地视频采集,不影响接收远端视频。

调用 enableVideo 后,本地视频即默认开启。你可以调用 enableLocalVideo(NO) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 enableLocalVideo(YES)

成功禁用或启用本地视频采集后,远端会触发 remoteVideoStateChangedOfUid 回调。

该方法在加入频道前后都能调用。

Note:

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

Declared In

AgoraRtcEngineKit.h

– muteLocalVideoStream:

取消或恢复发布本地视频流。

- (int)muteLocalVideoStream:(BOOL)mute

Parameters

mute

是否取消发布本地视频流:

  • YES: 取消发布。
  • NO: 发布。

Return Value

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

    • -5 (AgoraErrorCodeRefused): 调用被拒绝。

Discussion

自 v3.4.5 起,该方法仅设置用户在 AgoraRtcEngineKit 频道中的视频发布状态。

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

同一时间,本地的音视频流只能发布到一个频道。如果你创建了多个频道,请确保你只在一个频道中调用 muteLocalVideoStream(NO),否则方法会调用失败并返回 -5 (AgoraErrorCodeRefused)

Note

  • 该方法不会改变视频采集设备的使用状态。
  • 该方法的调用是否生效受 joinChannelByTokensetClientRole 方法的影响,详见《设置发布状态》。

Declared In

AgoraRtcEngineKit.h

– muteAllRemoteVideoStreams:

取消或恢复订阅所有远端用户的视频流。

- (int)muteAllRemoteVideoStreams:(BOOL)mute

Parameters

mute

是否取消订阅所有远端用户的视频流。

  • YES: 取消订阅。
  • NO: (默认)订阅。

Return Value

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

Discussion

成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流, 包括在调用该方法后加入频道的用户的视频流。

Note

  • 该方法需要在加入频道后调用。
  • 自 v3.3.0 起,该方法包含了 setDefaultMuteAllRemoteVideoStreams 的功能。声网建议不要一起调用 muteAllRemoteVideoStreamssetDefaultMuteAllRemoteVideoStreams,否则设置可能会不生效。详见《设置订阅状态》。

Declared In

AgoraRtcEngineKit.h

– muteRemoteVideoStream:mute:

取消或恢复订阅指定远端用户的视频流。

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

Parameters

uid

指定用户的用户 ID。

mute

是否取消订阅指定远端用户的视频流。

  • YES: 取消订阅。
  • NO: (默认)订阅。

Return Value

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

Discussion

Note

  • 该方法需要在加入频道后调用。
  • 该方法的推荐设置详见《设置订阅状态》。

Declared In

AgoraRtcEngineKit.h

视频前处理及后处理

– setBeautyEffectOptions:options:

设置美颜效果选项。

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

Parameters

enable

是否开启美颜功能:

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

美颜选项,详见 AgoraBeautyOptions

Return Value

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

Discussion

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

Note:

  • 请在调用 enableVideo 方法后,调用该方法。
  • 声网从 3.6.0 版起更新了基础美颜算法,能提升基础美颜效果并支持锐度调节功能。如果你想体验优化后的基础美颜效果或设置锐度,请在调用该方法前,将 AgoraVideoProcessExtension.xcframework 动态库集成到项目文件中。

Declared In

AgoraRtcEngineKit.h

– setLowlightEnhanceOptions:options:

设置暗光增强功能。

- (int)setLowlightEnhanceOptions:(BOOL)enable options:(AgoraLowlightEnhanceOptions *_Nullable)options

Parameters

enable

是否开启暗光增强功能:

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

暗光增强选项,用于设置暗光增强的效果。详见 AgoraLowLightEnhanceOptions

Return Value

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

Availability

v3.6.2

暗光增强功能可以在光线亮度偏低(如背光、阴天、暗场景)和亮度不均匀的环境下自适应调整视频画面的亮度值,恢复或凸显图像的细节信息,最终提升视频图像的整体视觉效果。

你可以调用该方法开启暗光增强功能并设置暗光增强的效果。

Note:

  • 调用该方法前,请确保已集成 AgoraVideoProcessExtension.xcframework 动态库。
  • 请在 enableVideo 后调用该方法。
  • 暗光增强对设备性能有一定要求。开启暗光增强后,如果设备出现严重发烫等问题,声网推荐你将暗光增强等级修改为消耗性能较少的等级或关闭暗光增强功能。

Declared In

AgoraRtcEngineKit.h

– setVideoDenoiserOptions:options:

设置视频降噪功能。

- (int)setVideoDenoiserOptions:(BOOL)enable options:(AgoraVideoDenoiserOptions *_Nullable)options

Parameters

enable

是否开启视频降噪功能:

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

视频降噪选项,用于设置视频降噪的效果。详见 AgoraVideoDenoiserOptions

Return Value

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

Availability

v3.6.2

采光不足的环境和低端视频采集设备会使视频图像含有明显的噪声,影响视频画质。在实时互动场景下,视频噪声还会在编码过程中占用码流资源并降低编码效率。

你可以调用该方法开启视频降噪功能并设置视频降噪的效果。

Note:

  • 调用该方法前,请确保已集成 AgoraVideoProcessExtension.xcframework 动态库。
  • 请在 enableVideo 后调用该方法。
  • 视频降噪对设备性能有一定要求。开启视频降噪后,如果设备出现严重发烫等问题,声网推荐你将视频降噪等级修改为消耗性能较少的等级或关闭视频降噪功能。

Declared In

AgoraRtcEngineKit.h

– setColorEnhanceOptions:options:

设置色彩增强功能。

- (int)setColorEnhanceOptions:(BOOL)enable options:(AgoraColorEnhanceOptions *_Nullable)options

Parameters

enable

是否开启色彩增强功能:

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

色彩增强选项,用于设置色彩增强的效果。详见 AgoraColorEnhanceOptions

Return Value

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

Availability

v3.6.2

摄像头采集到的视频画面可能存在色彩失真的现象。色彩增强功能可以通过智能调节饱和度和对比度等视频特性,提升视频色彩丰富度和色彩还原度,最终使视频画面更生动。

你可以调用该方法开启色彩增强功能并设置色彩增强的效果。

Note:

  • 调用该方法前,请确保已集成 AgoraVideoProcessExtension.xcframework 动态库。
  • 请在 enableVideo 后调用该方法。
  • 色彩增强对设备性能有一定要求。开启色彩增强后,如果设备出现严重发烫等问题,声网推荐你将色彩增强等级修改为消耗性能较少的等级或关闭色彩增强功能。

Declared In

AgoraRtcEngineKit.h

– enableVirtualBackground:backData:

开启/关闭虚拟背景。

- (int)enableVirtualBackground:(BOOL)enable backData:(AgoraVirtualBackgroundSource *_Nullable)backData

Parameters

enable

设置是否开启虚拟背景:

  • YES: 开启。
  • NO: 关闭。
backData

自定义的背景图。详见 AgoraVirtualBackgroundSource

Note:为将自定义背景图的分辨率与 SDK 的视频采集分辨率适配, SDK 会在保证自定义背景图内容不变形的前提下,对自定义背景图进行缩放和裁剪。

Return Value

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

Availability

自 v3.4.5 起支持 macOS 平台,自 v3.5.0 起支持 iOS 平台。

开启虚拟背景功能后,你可以使用自定义的背景图替代本地用户原来的背景图。替换后, 频道内所有用户都能看到自定义的背景图。你可以从 virtualBackgroundSourceEnabled 回调了解虚拟背景是否成功开启和相应的出错原因。

Note:

  • 调用该方法前,请确保你已经将 AgoraVideoSegmentationExtension.xcframework 动态库集成到项目中。
  • 请在 enableVideo 后调用该方法。
  • 对早于 3.6.1 版,虚拟背景功能不支持 Texture 格式视频和来自 Push 自采集的视频。
  • 该功能对设备性能要求较高,声网推荐你在如下设备上使用:

    • macOS:CPU 为 i5 及更好的设备
    • iOS:搭载 A9 及以上芯片的如下设备:

      • iPhone 6S 及以上
      • iPad Air 第三代及以上
      • iPad 第五代及以上
      • iPad Pro 第一代及以上
      • iPad mini 第五代及以上
  • 声网建议你在满足如下条件的场景中使用该功能:

    • 使用高清摄像设备、摄像环境光照均匀。
    • 摄像画面中,物件较少,用户的人像为半身人像且基本无遮挡,背景色较单一且与用户着装颜色不同。

Declared In

AgoraRtcEngineKit.h

– enableRemoteSuperResolution:mode:uid:

开启/关闭远端视频超分辨率。(beta 功能)

- (int)enableRemoteSuperResolution:(BOOL)enabled mode:(AgoraVideoSRMode)mode uid:(NSUInteger)uid

Parameters

enabled

是否对远端视频开启超级分辨率:

  • YES: 开启。
  • NO: 关闭。
mode

超分辨率的模式。详见 AgoraVideoSRMode

uid

远端用户 ID。该参数仅在 modeAgoraVideoSRModeManual(0) 时生效。

Return Value

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

    • -157(AgoraErrorCodeModuleNotFound): 尚未集成超分辨率动态库。

Availability

v3.7.1

该功能可以有效地提升用户看到的远端视频画面的分辨率,即对接收到的某个远端用户的视频宽和高均扩大为 2 倍像素。

调用该方法后,SDK 会触发 superResolutionEnabledOfUid 回调报告超分辨率是否成功开启。

Discussion

Note: 调用该方法前,请确保你已经将 AgoraSuperResolutionExtension.xcframework 动态库集成到项目中。

使用限制: 超分辨率功能会额外耗费系统资源。为平衡视觉体验和系统消耗,该功能有如下使用限制:

  • 只可以对一个远端用户开启超分辨率。
  • 远端用户视频的原始分辨率不能超过 640 × 360。
  • 该功能不支持在部分低端机型上开启。

Declared In

AgoraRtcEngineKit.h

人脸检测

– enableFaceDetection:

开启/关闭本地人脸检测。

- (int)enableFaceDetection:(bool)enable

Parameters

enable

是否开启人脸检测:

  • YES: 开启人脸检测
  • NO: (默认)关闭人脸检测

Return Value

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

Discussion

自从: v3.0.1.

开启本地人脸检测后,SDK 会触发 facePositionDidChangeWidth 回调向你报告人脸检测的信息:

  • 摄像头采集的画面大小
  • 人脸在 View 中的位置
  • 人脸距设备屏幕的距离

Note

  • 该方法在加入频道前后都能调用。
  • 该方法仅使用于 iOS 平台。

Declared In

AgoraRtcEngineKit.h

音频播放路由

– setDefaultAudioRouteToSpeakerphone:

设置默认的音频路由。

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker

Parameters

defaultToSpeaker

设置默认的音频路由:

  • YES: 默认的音频路由为扬声器。
  • NO: 默认的音频路由为听筒。

Return Value

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

Discussion

如果 SDK 默认的音频路由(见《设置音频路由》)无法满足你的需求, 你可以调用该方法切换默认的音频路由。成功切换音频路由后,SDK 会触发 didAudioRouteChanged 回调提示音频路由已更改。

Note

  • 该方法仅适用于 iOS 平台。
  • 该方法需要在 joinChannelByToken 前调用。如需在加入频道后切换音频路由,请调用 setEnableSpeakerphone
  • 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备,则该方法的设置无效, 音频只会通过外接设备播放。当有多个外接设备时,音频会通过最后一个接入的设备播放。

Declared In

AgoraRtcEngineKit.h

– setEnableSpeakerphone:

开启/关闭扬声器播放。

- (int)setEnableSpeakerphone:(BOOL)enableSpeaker

Parameters

enableSpeaker

设置是否开启扬声器播放:

  • YES: 开启。音频路由为扬声器。
  • NO: 关闭。音频路由为听筒。

Return Value

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

Discussion

如果 SDK 默认的音频路由(见《设置音频路由》)或 setDefaultAudioRouteToSpeakerphone 的设置无法满足你的需求,你可以调用 setEnableSpeakerphone 切换当前的音频路由。 成功切换音频路由后,SDK 会触发 didAudioRouteChanged 回调提示音频路由已更改。

该方法只设置用户在当前频道内使用的音频路由,不会影响 SDK 默认的音频路由。 如果用户离开当前频道并加入新的频道,则用户还是会使用 SDK 默认的音频路由。

Note

  • 该方法仅适用于 iOS 平台。
  • 该方法需要在 joinChannelByToken 后调用。
  • 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备,则该方法的设置无效, 音频只会通过外接设备播放。当有多个外接设备时,音频会通过最后一个接入的设备播放。

Declared In

AgoraRtcEngineKit.h

– isSpeakerphoneEnabled

查询扬声器启用状态

- (BOOL)isSpeakerphoneEnabled

Return Value

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

Discussion

该方法仅适用于 iOS。 该方法在加入频道前后都能调用。

Declared In

AgoraRtcEngineKit.h

耳返设置

– enableInEarMonitoring:

开启耳返功能

- (int)enableInEarMonitoring:(BOOL)enabled

Parameters

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

Return Value

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

Discussion

该方法在加入频道前后都能调用。

Note

  • 该方法仅适用于 iOS 平台。
  • 用户必须使用耳机(有线和蓝牙均可)才能听到耳返效果。

Declared In

AgoraRtcEngineKit.h

– setInEarMonitoringVolume:

设置耳返音量

- (int)setInEarMonitoringVolume:(NSInteger)volume

Parameters

volume

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

Return Value

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

Discussion

该方法在加入频道前后都能调用。

Note

  • 该方法仅适用于 iOS 平台。
  • 用户必须使用耳机(有线和蓝牙均可)才能听到耳返效果。

Declared In

AgoraRtcEngineKit.h

设置人声效果

– setLocalVoicePitch:

设置本地语音音调

- (int)setLocalVoicePitch:(double)pitch

Parameters

pitch

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

Return Value

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

Discussion

该方法改变本地说话人声音的音调。该方法在加入频道前后都能调用。

Declared In

AgoraRtcEngineKit.h

– setLocalVoiceEqualizationOfBandFrequency:withGain:

设置本地语音音效均衡

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

Parameters

bandFrequency

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

gain

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

Return Value

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

Discussion

该方法在加入频道前后都能调用。

Declared In

AgoraRtcEngineKit.h

– setLocalVoiceReverbOfType:withValue:

设置本地音效混响

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

Parameters

reverbType

混响音效类型,详见 AgoraAudioReverbType

value

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

Return Value

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

Discussion

SDK 在 v3.2.0 版本中提供一个使用更为简便的方法 setAudioEffectPreset,直接实现流行、R&B、KTV 等预置的混响效果。

该方法在加入频道前后都能调用。

Declared In

AgoraRtcEngineKit.h

– setVoiceBeautifierPreset:

设置 SDK 预设的美声效果。

- (int)setVoiceBeautifierPreset:(AgoraVoiceBeautifierPreset)preset

Parameters

preset

预设的美声效果选项:AgoraVoiceBeautifierPreset

Return Value

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

Availability

v3.2.0

调用该方法可以为本地发流用户设置 SDK 预设的人声美化效果。设置美声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的美声效果, 各美声效果的适用场景可参考《设置人声效果》。

为获取更好的人声效果,声网推荐你在调用该方法前将 setAudioProfilescenario 设为 AgoraAudioScenarioGameStreaming(3),并将 profile 设为 AgoraAudioProfileMusicHighQuality(4)AgoraAudioProfileMusicHighQualityStereo(5)

Note

Declared In

AgoraRtcEngineKit.h

– setVoiceBeautifierParameters:param1:param2:

设置 SDK 预设美声效果的参数。

- (int)setVoiceBeautifierParameters:(AgoraVoiceBeautifierPreset)preset param1:(int)param1 param2:(int)param2

Parameters

preset

SDK 预设的音效:

  • AgoraSingingBeautifier: 歌唱美声。
param1

歌声的性别特征:

  • 1: 男声。
  • 2: 女声。
param2

歌声的混响效果:

  • 1: 歌声在小房间的混响效果。
  • 2: 歌声在大房间的混响效果。
  • 3: 歌声在大厅的混响效果。

Return Value

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

Availability

v3.3.0

调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。设置后,频道内所有用户都能听到该效果。

为获取更好的人声效果,声网推荐你在调用该方法前将 setAudioProfilescenario 设为 AgoraAudioScenarioGameStreaming(3),并将 profile 设为 AgoraAudioProfileMusicHighQuality(4)AgoraAudioProfileMusicHighQualityStereo(5)

Note

Declared In

AgoraRtcEngineKit.h

– setAudioEffectPreset:

设置 SDK 预设的人声音效。

- (int)setAudioEffectPreset:(AgoraAudioEffectPreset)preset

Parameters

preset

预设的音效选项:AgoraAudioEffectPreset

Return Value

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

Availability

v3.2.0

调用该方法可以为本地发流用户设置 SDK 预设的人声音效,且不会改变原声的性别特征。设置音效后,频道内所有用户都能听到该效果。

根据不同的场景,你可以为用户设置不同的音效,各音效的适用场景可参考《设置人声效果》。

为获取更好的人声效果,声网推荐你在调用该方法前将 setAudioProfilescenario 设为 AgoraAudioScenarioGameStreaming(3)

Note:

Declared In

AgoraRtcEngineKit.h

– setVoiceConversionPreset:

设置 SDK 预设的变声效果。

- (int)setVoiceConversionPreset:(AgoraVoiceConversionPreset)preset

Parameters

preset

预设的变声效果选项:AgoraVoiceConversionPreset

Return Value

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

Availability

v3.3.1

调用该方法可以为本地发流用户设置 SDK 预设的变声效果。设置变声效果后,频道内所有用户都能听到该效果。 根据不同的场景,你可以为用户设置不同的变声效果,各变声效果的适用场景可参考《设置人声效果》。

为获取更好的人声效果,声网推荐你在调用该方法前将 setAudioProfileprofile 设为 AgoraAudioProfileMusicHighQuality(4)AgoraAudioProfileMusicHighQualityStereo(5),并将 scenario 设为 AgoraAudioScenarioGameStreaming(3)

Note:

Declared In

AgoraRtcEngineKit.h

– setAudioEffectParameters:param1:param2:

设置 SDK 预设人声音效的参数。

- (int)setAudioEffectParameters:(AgoraAudioEffectPreset)preset param1:(int)param1 param2:(int)param2

Parameters

preset

SDK 预设的音效:

  • 3D 人声音效:AgoraRoomAcoustics3DVoice

    • 你需要在使用该枚举前将 setAudioProfileprofile 参数设置为 AgoraAudioProfileMusicStandardStereo(3)AgoraAudioProfileMusicHighQualityStereo(5),否则该枚举设置无效。
    • 启用 3D 人声后,用户需要使用支持双声道的音频播放设备才能听到预期效果。
  • 电音音效:AgoraPitchCorrection。为获取更好的人声效果,声网建议你在使用该枚举前将 setAudioProfileprofile 参数设置为 AgoraAudioProfileMusicHighQuality(4)AgoraAudioProfileMusicHighQualityStereo(5)

param1
  • 如果 preset 设为 AgoraRoomAcoustics3DVoice,则 param1 表示 3D 人声音效的环绕周期。取值范围为 [1,60], 单位为秒。默认值为 10,表示人声会 10 秒环绕 360 度。
  • 如果 preset 设为 AgoraPitchCorrection,则 param1 表示电音音效的基础调式。可设为如下值:

    • 1:(默认)自然大调。
    • 2: 自然小调。
    • 3: 和风小调。
param2
  • 如果 preset 设为 AgoraRoomAcoustics3DVoice,你需要将 param2 设为 0
  • 如果 preset 设为 AgoraPitchCorrection,则 param2 表示电音音效的主音音高。可设为如下值:

    • 1: A 调
    • 2: A# 调
    • 3: B 调
    • 4:(默认)C 调
    • 5: C# 调
    • 6: D 调
    • 7: D# 调
    • 8: E 调
    • 9: F 调
    • 10: F# 调
    • 11: G 调
    • 12: G# 调

Return Value

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

Availability

v3.2.0

调用该方法可以对本地发流用户进行如下设置:

  • 3D 人声音效:设置 3D 人声音效的环绕周期。
  • 电音音效:设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效,声网推荐你将基础调式主音音高配置选项与应用的 UI 元素绑定。

设置后,频道内所有用户都能听到该效果。

Note:

Declared In

AgoraRtcEngineKit.h

听声辨位

– enableSoundPositionIndication:

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

- (int)enableSoundPositionIndication:(BOOL)enabled

Parameters

enabled

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

Return Value

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

Discussion

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

Declared In

AgoraRtcEngineKit.h

– setRemoteVoicePosition:pan:gain:

设置远端用户的语音位置

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

Parameters

uid

远端用户的 ID

pan

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

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

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

Return Value

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

Discussion

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

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

Note:

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

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

Declared In

AgoraRtcEngineKit.h

音乐文件播放及混音设置

– startAudioMixing:loopback:replace:cycle:startPos:

开始播放音乐文件。

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

Parameters

filePath

音乐文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如:/var/mobile/Containers/Data/audio.mp4

loopback

是否只在本地播放音乐文件:

  • YES: 只在本地播放音乐文件,只有本地用户能听到音乐。
  • NO: 将本地播放的音乐文件发布至远端,本地用户和远端用户都能听到音乐。
replace

是否用音乐文件替换麦克风采集的音频:

  • YES: 替换。用户只能听到音乐。
  • NO: 不替换。用户可以听到音乐和麦克风采集的音频。
cycle

音乐文件的播放次数。

  • 0: 播放次数。例如,0 表示不播放;1 表示播放 1 次。
  • -1:无限循环播放。
startPos

音乐文件的播放位置,单位为毫秒。

Return Value

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

Availability

v3.4.0

该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后,本地会触发 localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying, AgoraAudioMixingReasonStartedByUser) 回调。 播放结束后,本地会触发 localAudioMixingStateDidChanged(AgoraAudioMixingStateStopped, AgoraAudioMixingReasonAllLoopsCompleted) 回调。

Note:

  • 为避免阻塞,自 v3.4.5 起,该方法由同步调用改为异步调用。
  • 如需多次调用 startAudioMixing,请确保调用间隔大于 500 ms。
  • 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL,则 SDK 会报告 AgoraWarningCodeAudioMixingOpenError(701)
  • 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件

Declared In

AgoraRtcEngineKit.h

– setAudioMixingPlaybackSpeed:

设置当前音乐文件的播放速度。

- (int)setAudioMixingPlaybackSpeed:(int)speed

Parameters

speed

播放速度。推荐取值范围为 [50,400],其中:

  • 50: 0.5 倍速。
  • 100: 原始速度。
  • 400: 4 倍速。

Return Value

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

Availability

v3.5.1

Discussion

Note: 你需要在调用 startAudioMixing 并收到 localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying) 回调后调用该方法。

Declared In

AgoraRtcEngineKit.h

– stopAudioMixing

停止播放音乐文件

- (int)stopAudioMixing

Return Value

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

Discussion

请在频道内调用该方法。

Declared In

AgoraRtcEngineKit.h

– pauseAudioMixing

暂停播放音乐文件

- (int)pauseAudioMixing

Return Value

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

Discussion

请在频道内调用该方法。

Declared In

AgoraRtcEngineKit.h

– resumeAudioMixing

恢复播放音乐文件

- (int)resumeAudioMixing

Return Value

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

Discussion

请在频道内调用该方法。

Declared In

AgoraRtcEngineKit.h

– selectAudioTrack:

指定当前音乐文件的播放音轨。

- (int)selectAudioTrack:(NSInteger)index

Parameters

index

指定的播放音轨。取值范围为 [0, getAudioTrackCount())。

Return Value

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

Availability

v3.5.1

获取音乐文件的音轨数量后,你可以调用该方法指定任一音轨进行播放。例如, 如果一个多音轨文件的不同音轨存放了不同语言的歌曲,则你可以调用该方法设置音乐文件的播放语言。

Notes

Declared In

AgoraRtcEngineKit.h

– getAudioTrackCount

获取当前音乐文件的音轨数量。

- (int)getAudioTrackCount

Return Value

  • > 0: 方法调用成功,返回当前音乐文件的音轨数量。
  • < 0: 方法调用失败。

Availability

v3.5.1

Notes

Declared In

AgoraRtcEngineKit.h

– setAudioMixingDualMonoMode:

设置当前音乐文件的声道模式。

- (int)setAudioMixingDualMonoMode:(AgoraAudioMixingDualMonoMode)mode

Parameters

mode

声道模式。详见 AgoraAudioMixingDualMonoMode

Return Value

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

Availability

v3.5.1

在双声道音乐文件中,左声道和右声道可以存储不同的音频数据。根据实际需要, 你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如,在 KTV 场景中, 音乐文件的左声道存储了伴奏,右声道存储了原唱的歌声。如果你只需听伴奏, 调用该方法设置音乐文件的声道模式为左声道模式;如果你需要同时听伴奏和原唱, 调用该方法设置声道模式为混合模式。

Notes

Declared In

AgoraRtcEngineKit.h

– adjustAudioMixingVolume:

调节音乐文件的播放音量

- (int)adjustAudioMixingVolume:(NSInteger)volume

Parameters

volume

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

Return Value

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

Discussion

该方法调节混音的音乐文件在本地和远端播放的音量大小。该方法需要在 startAudioMixing 后调用。

Note:

Declared In

AgoraRtcEngineKit.h

– adjustAudioMixingPlayoutVolume:

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

- (int)adjustAudioMixingPlayoutVolume:(NSInteger)volume

Parameters

volume

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

Return Value

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

Discussion

该方法调节混音的音乐文件在本地播放的音量大小。该方法需要在 startAudioMixing 后调用。

Declared In

AgoraRtcEngineKit.h

– adjustAudioMixingPublishVolume:

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

- (int)adjustAudioMixingPublishVolume:(NSInteger)volume

Parameters

volume

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

Return Value

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

Discussion

该方法调节混音的音乐文件在远端播放的音量大小。该方法需要在 startAudioMixing 后调用。

Declared In

AgoraRtcEngineKit.h

– getAudioMixingPublishVolume

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

- (int)getAudioMixingPublishVolume

Return Value

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

Discussion

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

Note: 你需要在调用 startAudioMixing 并收到 localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying) 回调后调用该方法。

Declared In

AgoraRtcEngineKit.h

– getAudioMixingPlayoutVolume

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

- (int)getAudioMixingPlayoutVolume

Return Value

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

Discussion

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

Note: 你需要在调用 startAudioMixing 并收到 localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying) 回调后调用该方法。

Declared In

AgoraRtcEngineKit.h

– getAudioMixingCurrentPosition

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

- (int)getAudioMixingCurrentPosition

Return Value

  • ≥ 0: 方法调用成功,返回当前音乐文件播放进度(ms)。0 表示当前音乐文件未开始播放。
  • < 0: 方法调用失败

Discussion

Note

Declared In

AgoraRtcEngineKit.h

– setAudioMixingPosition:

设置音频文件的播放位置

- (int)setAudioMixingPosition:(NSInteger)pos

Parameters

pos

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

Return Value

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

Discussion

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

Declared In

AgoraRtcEngineKit.h

– setAudioMixingPitch:

调整本地播放的音乐文件的音调。

- (int)setAudioMixingPitch:(NSInteger)pitch

Parameters

pitch

按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12],每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。

Return Value

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

Discussion

自从: v3.0.1.

本地人声和播放的音乐文件混音时,调用该方法可以仅调节音乐文件的音调。

Note: 该方法需在 startAudioMixing 后调用。

Declared In

AgoraRtcEngineKit.h

音效文件播放管理

– getEffectsVolume

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

- (double)getEffectsVolume

Return Value

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

Discussion

该方法需要在 playEffect 后调用。

Declared In

AgoraRtcEngineKit.h

– setEffectsVolume:

设置音效文件播放音量

- (int)setEffectsVolume:(double)volume

Parameters

volume

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

Return Value

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

Discussion

该方法需要在 playEffect 后调用。

Declared In

AgoraRtcEngineKit.h

– setVolumeOfEffect:withVolume:

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

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

Parameters

soundId

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

volume

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

Return Value

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

Discussion

该方法需要在 playEffect 后调用。

Declared In

AgoraRtcEngineKit.h

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

播放指定的本地或在线音效文件。

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

Parameters

soundId

音效的 ID。每个音效的 ID 具有唯一性。如果你已通过 preloadEffect 将音效加载至内存, 请确保该参数与 preloadEffect 中设置的 soundId 相同。

filePath

音效文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如:/var/mobile/Containers/Data/audio.mp4。 如果你已通过 preloadEffect 将音效加载至内存,请确保该参数与 preloadEffect 中设置的 filePath 相同。

loopCount

音效循环播放的次数。

  • 0: 循环播放次数。例如,1 表示循环播放 1 次,即总计播放 2 次。
  • -1: 无限循环播放。
pitch

音效的音调,取值范围为 [0.5,2.0]。默认值为 1.0,表示原始音调。取值越小,则音调越低。

pan

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

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

音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0,表示原始音量。取值越小,则音量越低。

publish

是否将音效发布至远端:

  • YES: 发布。本地用户和远端用户都能听到音效。
  • NO: 不发布。只有本地用户能听到音效。
startPos

音效文件的播放位置,单位为毫秒。

Return Value

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

Discussion

你可以多次调用该方法,传入不同的 soundIdfilePath,同时播放多个音效文件。为获得最佳用户体验,声网推荐同时播放的音效文件不超过 3 个。

音效文件播放结束后,SDK 会触发 rtcEngineDidAudioEffectFinish 回调。

Note

  • 该方法需要在加入频道后调用。
  • 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件
  • 如果你需要通过 playEffect 播放在线音效文件,声网建议你将在线音效文件缓存到本地设备,调用 preloadEffect 将音效加载至内存,确保这里设置的 soundId 与 preloadEffect 将缓存的音效文件预加载到内存中,再调用 playEffect 播放音效。否则,可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。

Declared In

AgoraRtcEngineKit.h

– stopEffect:

停止播放指定音效文件

- (int)stopEffect:(int)soundId

Parameters

soundId

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

Return Value

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

Declared In

AgoraRtcEngineKit.h

– stopAllEffects

停止播放所有音效文件

- (int)stopAllEffects

Declared In

AgoraRtcEngineKit.h

– preloadEffect:filePath:

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

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

Parameters

soundId

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

filePath

音效文件的绝对路径

Return Value

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

Discussion

Note

Declared In

AgoraRtcEngineKit.h

– unloadEffect:

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

- (int)unloadEffect:(int)soundId

Parameters

soundId

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

Return Value

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

Declared In

AgoraRtcEngineKit.h

– pauseEffect:

暂停音效文件播放

- (int)pauseEffect:(int)soundId

Parameters

soundId

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

Return Value

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

Declared In

AgoraRtcEngineKit.h

– pauseAllEffects

暂停所有音效文件播放

- (int)pauseAllEffects

Return Value

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

Declared In

AgoraRtcEngineKit.h

– resumeEffect:

恢复播放指定音效文件

- (int)resumeEffect:(int)soundId

Parameters

soundId

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

Return Value

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

Declared In

AgoraRtcEngineKit.h

– resumeAllEffects

恢复播放所有音效文件

- (int)resumeAllEffects

Return Value

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

Declared In

AgoraRtcEngineKit.h

– getEffectCurrentPosition:

获取指定音效文件的播放进度。

- (int)getEffectCurrentPosition:(int)soundId

Parameters

soundId

音效 ID。请确保与 playEffect 中设置的 soundId 一致。

Return Value

  • ≥ 0: 方法调用成功,返回指定音效文件的播放进度(毫秒)。
  • < 0: 方法调用失败。

    • -22(AgoraErrorCodeResourceLimited): 无法找到音效文件。请填写正确的 soundId

Availability

v3.4.0

Discussion

Note: 该方法需要在 playEffect 后调用。

Declared In

AgoraRtcEngineKit.h

– setEffectPosition:pos:

设置指定音效文件的播放位置。

- (int)setEffectPosition:(int)soundId pos:(NSInteger)pos

Parameters

soundId

音效 ID。请确保与 playEffect 中设置的 soundId 一致。

pos

音效文件的播放位置,单位为毫秒。

Return Value

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

    • -22(AgoraErrorCodeResourceLimited): 无法找到音效文件。请填写正确的 soundId

Availability

v3.4.0

成功设置后,本地音效文件会在指定位置开始播放。

Discussion

Note: 该方法需要在 playEffect 后调用。

Declared In

AgoraRtcEngineKit.h

– getEffectDuration:

获取指定音频文件信息。

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

Parameters

filePath

音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如:/var/mobile/Containers/Data/audio.mp4

Return Value

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

Availability

v3.4.0

成功调用该方法后,SDK 会触发 didRequestAudioFileInfo 回调,报告指定音频文件的时长等信息。你可以多次调用该方法,获取多个音频文件的信息。

Note

  • 该方法需要在加入频道后调用。
  • 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件
  • 自 v3.7.0 起,getEffectDuration 的行为从“获取指定音效文件总时长”变更为“获取音频文件信息”。

Declared In

AgoraRtcEngineKit.h

虚拟节拍器

– startRhythmPlayer:sound2:config:

开启虚拟节拍器(仅 iOS)

- (int)startRhythmPlayer:(NSString *_Nonnull)sound1 sound2:(NSString *_Nonnull)sound2 config:(AgoraRtcRhythmPlayerConfig *_Nonnull)config

Parameters

sound1

强拍文件的绝对路径,需精确到文件名及后缀。例如:/var/mobile/Containers/Data/audio.mp4

sound2

弱拍文件的绝对路径,需精确到文件名及后缀。例如:/var/mobile/Containers/Data/audio.mp4

config

节拍器配置。详见 AgoraRtcRhythmPlayerConfig

Return Value

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

    • -22(AgoraErrorCodeResourceLimited): 无法找到音频文件。请填写正确的 sound1sound2

Availability

v3.4.0

在音乐教学、体育教学等场景中,老师通常需要使用节拍器,让学生跟着正确的节拍练习。节拍由强拍和弱拍组成,每小节的第一拍称为强拍,其余称为弱拍。 你需要在该方法中设置强拍和弱拍的文件路径、每小节的拍数、节拍速度以及是否将节拍器的声音发送至远端。

Note

  • 开启虚拟节拍器后,SDK 会从头开始播放指定的音频文件,并根据你设置的 beatsPerMinute 控制每个文件的播放时长。 例如,将 beatsPerMinute 设为 60,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。
  • 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件

Declared In

AgoraRtcEngineKit.h

– stopRhythmPlayer

关闭虚拟节拍器(仅 iOS)

- (int)stopRhythmPlayer

Return Value

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

Availability

v3.4.0

调用 startRhythmPlayer 后,你可以调用该方法关闭虚拟节拍器。

Declared In

AgoraRtcEngineKit.h

– configRhythmPlayer:

配置虚拟节拍器(仅 iOS)

- (int)configRhythmPlayer:(AgoraRtcRhythmPlayerConfig *_Nonnull)config

Parameters

config

节拍器配置。详见 AgoraRtcRhythmPlayerConfig

Return Value

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

Availability

v3.4.0

调用 startRhythmPlayer 后,你可以调用该方法重新配置虚拟节拍器。

Discussion

Note: 重新配置虚拟节拍器后,SDK 会从头开始播放指定的音效文件,并根据你设置的 beatsPerMinute 控制每个文件的播放时长。 例如,将 beatsPerMinute 设为 60,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。

Declared In

AgoraRtcEngineKit.h

音频录制

– startAudioRecordingWithConfig:

开始客户端录音。

- (int)startAudioRecordingWithConfig:(AgoraAudioRecordingConfiguration *_Nonnull)config

Parameters

config

录音配置。详见 AgoraAudioRecordingConfiguration

Return Value

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

    -160(AgoraErrorCodeAlreadyInRecording): 客户端正在录音。如需开始新的录音,请先调用 stopAudioRecording 停止当前录音,再调用 startAudioRecordingWithConfig

Availability

v3.4.0

SDK 支持通话过程中在客户端进行录音。调用该方法后,你可以录制频道内用户的音频,并得到一个录音文件。录音文件格式可以为:

  • WAV: 音质保真度较高,文件较大。例如,采样率为 32000 Hz,录音时长为 10 分钟的文件大小约为 73 M。
  • AAC: 音质保真度较低,文件较小。例如,采样率为 32000 Hz,录音音质为 AgoraAudioRecordingQualityMedium,录音时长为 10 分钟的文件大小约为 2 M。

一旦用户离开频道,录音会自动停止。

Discussion

Note: 该方法需要在加入频道后调用。

Declared In

AgoraRtcEngineKit.h

– stopAudioRecording

停止客户端录音。

- (int)stopAudioRecording

Return Value

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

Declared In

AgoraRtcEngineKit.h

开启声卡采集

– enableLoopbackRecording:deviceName:

开启声卡采集(仅 macOS)

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

Parameters

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

deviceName: 声卡的设备名。默认为空,代表使用当前声卡采集。如果你使用虚拟声卡,如 AgoraALD(Agora Audio Loopback Device),你可以将该参数设置为声卡的名称("AgoraALD")。

Return Value

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

Discussion

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

Note:

  • 该方法在加入频道后调用。
  • macOS 系统默认声卡不支持采集功能,如果你需要使用该功能,请启用一个虚拟声卡,并将该虚拟声卡的名字传入 deviceName 参数。声网推荐你启用 AgoraALD (Agora Audio Loopback Device) 并向该参数传入 "AgoraALD"

Declared In

AgoraRtcEngineKit.h

音频其他方法

– setAudioSessionOperationRestriction:

设置 SDK 对 Audio Session 的操作权限。

- (void)setAudioSessionOperationRestriction:(AgoraAudioSessionOperationRestriction)restriction

Parameters

restriction

SDK 对 Audio Session 的操作权限,详见 AgoraAudioSessionOperationRestriction。该参数为 Bit Mask,每个 Bit 对应一个权限。

Discussion

在默认情况下,SDK 和 app 对 Audio Session 都有操作权限。如果你只需使用 app 对 Audio Session 进行操作,你可以调用该方法限制 SDK 对 Audio Session 的操作权限。

该方法在加入频道前后都能调用。一旦调用该方法限制了 SDK 对 Audio Session 的操作权限,该限制会在 SDK 需要更改 Audio Session 时生效。

Note:

  • 该方法仅适用于 iOS 平台。
  • 该方法不会限制 app 对 Audio Session 的操作权限。

Declared In

AgoraRtcEngineKit.h

– enableDeepLearningDenoise:

开启或关闭 AI 降噪模式。

- (int)enableDeepLearningDenoise:(BOOL)enabled

Parameters

enabled

是否开启 AI 降噪模式:

  • YES: 开启。
  • NO: 关闭。

Return Value

  • 0: 方法调用成功。
  • < 0: 方法调用失败。
    • -157(AgoraErrorCodeModuleNotFound): 未集成 AI 降噪库。

Discussion

SDK 默认开启传统降噪模式,以消除大部分平稳噪声。如果你还需要消除非平稳噪声,声网推荐你按如下步骤开启 AI 降噪模式:

  1. 确保已集成 AgoraAIDenoiseExtension.xcframework 库:

  2. 调用 enableDeepLearningDenoise(YES)

AI 降噪模式对设备性能有要求。只有在设备性能良好的情况下,SDK 才会成功开启 AI 降噪模式。支持在如下设备及其之后的型号中开启 AI 降噪模式:

  • iPhone 6S
  • MacBook Pro 2015
  • iPad Pro 第二代
  • iPad mini 第五代
  • iPad Air 第三代

成功开启 AI 降噪模式后,如果 SDK 检测到当前设备的性能不足,SDK 会自动关闭 AI 降噪模式,并开启传统降噪模式。

在频道内,如果你调用了 enableDeepLearningDenoise(NO) 或 SDK 自动关闭了 AI 降噪模式,当你需要重新开启 AI 降噪模式时, 你需要先调用 leaveChannel,再调用 enableDeepLearningDenoise(YES)

Note

  • 该方法需要动态加载 AgoraAIDenoiseExtension 库,所以声网推荐在加入频道前调用该方法。
  • 该方法对人声的处理效果最佳,声网不推荐调用该方法处理含音乐的音频数据。

Declared In

AgoraRtcEngineKit.h

网络相关测试

– startEchoTestWithInterval:successBlock:

开始语音通话回路测试

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

Parameters

interval

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

successBlock

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

Return Value

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

Discussion

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– startEchoTestWithConfig:

开始音视频通话回路测试。

- (int)startEchoTestWithConfig:(AgoraEchoTestConfiguration *_Nonnull)config

Parameters

config

音视频通话回路测试的配置。详见 AgoraEchoTestConfiguration

Return Value

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

Availability

v3.5.2

加入频道前,为测试用户本地发流、收流是否正常,你可以调用该方法进行音视频通话回路测试,即测试系统的音视频设备和用户的上下行网络是否正常。

开始测试后,用户需发出声音或面对摄像头,音频或视频会在约 2 秒后播放出来。如果音频播放正常,则表示系统音频设备和用户上下行网络均正常;如果视频播放正常,则表示系统视频设备和用户上下行网络均正常。

Note:

  • 请在加入频道前调用该方法。
  • 调用该方法后,必须调用 stopEchoTest 结束测试,否则该用户无法进行下一次音视频通话回路测试,也无法加入频道。
  • 直播场景下,该方法仅能由主播调用。

Declared In

AgoraRtcEngineKit.h

– stopEchoTest

停止通话回路测试。

- (int)stopEchoTest

Return Value

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

Discussion

调用 startEchoTestWithIntervalstartEchoTestWithConfig 后,如果你想停止通话回路测试,请调用本方法。

Declared In

AgoraRtcEngineKit.h

– enableLastmileTest

启动网络测试

- (int)enableLastmileTest

Return Value

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

Discussion

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

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

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

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

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

Note:

  • 调用该方法后,在收到 lastmileQuality 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此回调无法执行。
  • 直播场景下,主播在加入频道后请勿调用该方法。
  • 加入频道前调用该方法检测网络质量后,SDK 会占用一路视频的带宽,码率与 setVideoEncoderConfiguration 中设置的码率相同。加入频道后,无论是否调用了 disableLastmileTest,SDK 均会自动停止带宽占用。

Declared In

AgoraRtcEngineKit.h

– disableLastmileTest

关闭网络测试

- (int)disableLastmileTest

Return Value

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

Declared In

AgoraRtcEngineKit.h

– startLastmileProbeTest:

开始通话前网络质量探测

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

Parameters

config

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

Return Value

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

Discussion

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

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

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

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

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– stopLastmileProbeTest

停止通话前网络质量探测

- (int)stopLastmileProbeTest

Return Value

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

Discussion

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

Declared In

AgoraRtcEngineKit.h

自定义视频模块

– setVideoSource:

设置自定义视频源

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

Parameters

videoSource

自定义的视频源,详见 AgoraVideoSourceProtocol

Discussion

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

该方法在加入频道前后都能调用。

Declared In

AgoraRtcEngineKit.h

– setLocalVideoRenderer:

本地自定义视频渲染器

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

Parameters

videoRenderer

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

Discussion

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

该方法在加入频道前后都能调用。

Declared In

AgoraRtcEngineKit.h

– setRemoteVideoRenderer:forUserId:

远端自定义视频渲染器

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

Parameters

videoRenderer

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

userId

远端用户的 uid

Discussion

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

该方法在加入频道前后都能调用。如果在加入频道前调用,需要自行维护远端用户的 uid

Declared In

AgoraRtcEngineKit.h

– videoSource

获取当前视频源

- (id<AgoraVideoSourceProtocol> _Nullable)videoSource

Declared In

AgoraRtcEngineKit.h

– localVideoRenderer

获取本地视频渲染器

- (id<AgoraVideoSinkProtocol> _Nullable)localVideoRenderer

Return Value

AgoraVideoSinkProtocol

Declared In

AgoraRtcEngineKit.h

– remoteVideoRendererOfUserId:

获取远端视频渲染器

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

Parameters

userId

远端用户的 uid

Return Value

AgoraVideoSinkProtocol

Discussion

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

Declared In

AgoraRtcEngineKit.h

– setVideoDataFrame:

注册原始视频数据协议。

- (void)setVideoDataFrame:(id<AgoraVideoDataFrameProtocol> _Nullable)videoData

Parameters

videoData

原始视频数据。详见 AgoraVideoDataFrameProtocol 。 传空表示取消注册原始视频数据观测器。

Return Value

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

Availability

v3.4.5

成功注册原始视频数据协议后,SDK 会在捕捉到每个视频帧时,触发你在 AgoraVideoDataFrameProtocol 中实现的回调。

Note:

  • 该方法仅适用于 iOS 平台。
  • 该方法需要在加入频道前调用。
  • 通过协议获取的视频宽高可能会因网络情况变差和用户自行调整分辨率而变化。
  • 使用 3.0.1 或之后版本的 SDK 时,请注意如下:
    • SDK 不再保证 AgoraVideoDataFrameProtocol 中的回调函数在同一个线程中报告。SDK 只会保证这些回调的顺序性。
    • 如果你使用 OpenGL 对视频原始数据进行美颜处理,为适应多线程场景,你需要在 AgoraVideoDataFrameProtocol 中的回调函数中主动切换 OpenGL 的上下文,否则美颜可能失效。

Declared In

AgoraRtcEngineKit.h

– setVideoEncodedFrame:

注册本地视频编码数据协议。

- (void)setVideoEncodedFrame:(id<AgoraVideoEncodedFrameProtocol> _Nullable)videoEncode

Parameters

videoEncode

本地视频编码数据。详见 AgoraVideoEncodedFrameProtocol 。 传空表示取消注册本地视频编码数据观测器。

Return Value

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

Availability

v3.4.5

成功注册本地视频编码数据协议后,SDK 会在捕捉到每个视频帧时,触发你在 AgoraVideoEncodedFrameProtocol 中实现的回调。

Note:

  • 该方法仅适用于 iOS 平台。
  • 该方法需要在加入频道前调用。
  • 通过协议获取的视频宽高可能会因网络情况变差和用户自行调整分辨率而变化。

Declared In

AgoraRtcEngineKit.h

音频自渲染

– enableExternalAudioSink:channels:

开启外部音频渲染。

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

Parameters

sampleRate

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

channels

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

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

Discussion

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

该方法需要在加入频道前调用。

Note: 使用早于 3.5.0 版的 SDK 时,设置 Pull 方式的音频自渲染后,你将无法收到 onPlaybackAudioFrame 回调。

Declared In

AgoraRtcEngineKit.h

– disableExternalAudioSink

关闭外部音频渲染。

- (void)disableExternalAudioSink

Declared In

AgoraRtcEngineKit.h

– pullPlaybackAudioFrameRawData:lengthInByte:

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

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

Parameters

data

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

lengthInByte

待拉取音频数据的字节数,单位为 byte。该参数的取值与音频数据的时长、你在 enableExternalAudioSink 中设置的 sampleRatechannels 参数相关。声网建议音频数据的时长至少为 10 毫秒。计算公式为:lengthInByte = sampleRate / 1000 × 2 × channels × 音频数据时长(毫秒)。

Return Value

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

Discussion

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

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

Note

  • 该方法需要在加入频道后调用。
  • 使用早于 3.5.0 版的 SDK 时,设置 Pull 方式的音频自渲染后,你将无法收到 onPlaybackAudioFrame 回调。
  • 该方法和 onPlaybackAudioFrame 回调相比,区别在于:
    • onPlaybackAudioFrame:SDK 通过该回调将音频数据传输给 app。如果 app 处理延时,可能会导致音频播放抖动。
    • pullPlaybackAudioFrameRawData:app 主动拉取音频数据。通过设置音频帧的数据和字节数,SDK 可以调整缓存,帮助 app 处理延时,从而有效避免音频播放抖动。

Declared In

AgoraRtcEngineKit.h

– pullPlaybackAudioFrameSampleBufferByLengthInByte:

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

- (CMSampleBufferRef _Nullable)pullPlaybackAudioFrameSampleBufferByLengthInByte:(NSUInteger)lengthInByte

Parameters

lengthInByte

待拉取音频数据的字节数,单位为 byte。该参数的取值与音频数据的时长、你在 enableExternalAudioSink 中设置的 sampleRatechannels 参数相关,且该参数应能被 sampleRate 值整除。声网建议音频数据的时长至少为 10 毫秒。计算公式为:lengthInByte = sampleRate / 1000 × 2 × channels × 音频数据时长(毫秒)。

Return Value

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

Discussion

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

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

Note

  • 该方法需要在加入频道后调用。
  • 使用早于 3.5.0 版的 SDK 时,设置 Pull 方式的音频自渲染后,你将无法收到 onPlaybackAudioFrame 回调。
  • 该方法和 onPlaybackAudioFrame 方法相比,区别在于:

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

Declared In

AgoraRtcEngineKit.h

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

– enableExternalAudioSourceWithSampleRate:channelsPerFrame:

开启外部音频采集

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

Parameters

sampleRate

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

channelsPerFrame

外部音频源的通道数,可设置为 1 或 2: 

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

Discussion

该方法必须在 joinChannelByTokenstartPreview 前调用。

Declared In

AgoraRtcEngineKit.h

– disableExternalAudioSource

关闭外部音频采集

- (void)disableExternalAudioSource

Declared In

AgoraRtcEngineKit.h

– setExternalAudioSourceVolume:volume:

设置指定位置的外部音频帧音量。

- (void)setExternalAudioSourceVolume:(AgoraAudioExternalSourcePos)sourcePos volume:(NSUInteger)volume

Parameters

sourcePos

外部音频帧的推送位置。详见 AgoraAudioExternalSourcePos

volume

外部音频帧的音量。取值范围为 [0,100]。默认值为 100,表示原始音量。

Availability

v3.5.1

你可以多次调用该方法,设置不同位置的外部音频帧音量。 音量设置对被推送到指定位置的所有外部音频帧都有效。

Discussion

Note: 该方法需要在加入频道后调用。

Declared In

AgoraRtcEngineKit.h

– pushExternalAudioFrameRawData:frame:

推送外部原始音频帧到指定位置。

- (int)pushExternalAudioFrameRawData:(AgoraAudioExternalSourcePos)sourcePos frame:(AgoraAudioFrame *_Nonnull)frame

Parameters

sourcePos

外部音频帧的推送位置。详见 AgoraAudioExternalSourcePos

frame

外部音频帧。详见 AgoraAudioFrame。音频帧长度范围为 [10,60],单位为 ms。

Return Value

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

    • -2 (AgoraErrorCodeInvalidArgument): 无效参数。
    • -12 (AgoraErrorCodeTooOften): 调用频率太高,导致内部缓冲区溢出。 建议在 30 - 50 ms 后重新调用该方法。

Availability

v3.5.1

根据实际需求,你可以将外部音频帧推送到音频采集后、编码前或本地播放前的位置。你可以多次调用该方法, 将一个音频帧推送到多个位置或者将多个音频帧推送到不同位置。例如,在 KTV 场景中, 你可以将歌声推送到音频采集后的位置,让歌声经过 SDK 音频模块的处理,从而获取优质的音频体验; 将伴奏推送到音频编码前的位置,让伴奏不受 SDK 音频模块的影响。

Discussion

Note: 该方法需要在加入频道后调用。

Declared In

AgoraRtcEngineKit.h

– pushExternalAudioFrameSampleBuffer:sampleBuffer:

推送外部 CMSampleBufferRef 音频帧到指定位置。

- (int)pushExternalAudioFrameSampleBuffer:(AgoraAudioExternalSourcePos)sourcePos sampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer

Parameters

sourcePos

外部音频帧的推送位置。详见 AgoraAudioExternalSourcePos

sampleBuffer

采样缓冲区。音频帧长度范围为 [10,60],单位为 ms。

Return Value

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

    • -2 (AgoraErrorCodeInvalidArgument): 无效参数。
    • -12 (AgoraErrorCodeTooOften): 调用频率太高,导致内部缓冲区溢出。 建议在 30 - 50 ms 后重新调用该方法。

Availability

v3.5.1

根据实际需求,你可以将外部音频帧推送到音频采集后、编码前或本地播放前的位置。你可以多次调用该方法, 将一个音频帧推送到多个位置或者将多个音频帧推送到不同位置。例如,在 KTV 场景中, 你可以将歌声推送到音频采集后的位置,让歌声经过 SDK 音频模块的处理,从而获取优质的音频体验; 将伴奏推送到音频编码前的位置,让伴奏不受 SDK 音频模块的影响。

Discussion

Note: 该方法需要在加入频道后调用。

Declared In

AgoraRtcEngineKit.h

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

– setExternalVideoSource:useTexture:pushMode:

配置外部视频源

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

Parameters

enable

是否使用外部视频源:

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

是否使用 Texture 作为输入:

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

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

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

Discussion

Note: 该方法需要在加入频道前调用。

Declared In

AgoraRtcEngineKit.h

– pushExternalVideoFrame:

推送外部视频帧

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

Parameters

frame

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

Return Value

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

Discussion

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

Note: SDK 目前不支持 alpha 通道。传入的 alpha 值将被丢弃。

Declared In

AgoraRtcEngineKit.h

原始音频数据处理

– setRecordingAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:

设置采集的音频格式

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

Parameters

sampleRate

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

channel

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

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

onRecordAudioFrame 的使用模式,详见 AgoraAudioRawFrameOperationMode

samplesPerCall

指定 onRecordAudioFrame 中返回数据的采样点数,如 RTMP/RTMPS 推流应用中通常为 1024。

Return Value

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

Discussion

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

该方法需要在加入频道前调用。

Note

SDK 会通过该方法的 samplesPerCallsampleRatechannel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate * channel)。请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发 onRecordAudioFrame 回调。

Declared In

AgoraRtcEngineKit.h

– setPlaybackAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:

设置播放的音频格式

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

Parameters

sampleRate

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

channel

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

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

onPlaybackAudioFrame 的使用模式,详见 AgoraAudioRawFrameOperationMode

samplesPerCall

指定 onPlaybackAudioFrame 中返回数据的采样点数,如 RTMP/RTMPS 推流应用中通常为 1024。

Return Value

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

Discussion

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

该方法需要在加入频道前调用。

Note

SDK 会通过该方法的 samplesPerCallsampleRatechannel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate * channel)。请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发 onPlaybackAudioFrame 回调。

Declared In

AgoraRtcEngineKit.h

– setMixedAudioFrameParametersWithSampleRate:samplesPerCall:

设置采集和播放的音频混音后的数据格式

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

Parameters

sampleRate

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

samplesPerCall

指定 onMixedAudioFrame 中返回数据的采样点数,如 RTMP/RTMPS 推流应用中通常为 1024。

Return Value

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

Discussion

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

该方法需要在加入频道前调用。

Note

SDK 会通过该方法的 samplesPerCallsampleRatechannel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate * channel)。请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发 onMixedAudioFrame 回调。

Declared In

AgoraRtcEngineKit.h

– setAudioDataFrame:

注册原始音频数据协议。

- (BOOL)setAudioDataFrame:(id<AgoraAudioDataFrameProtocol> _Nullable)delegate

Parameters

delegate

音频帧 delegate,详见 AgoraAudioDataFrameProtocol

Return Value

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

Availability

v3.4.5

当需要 SDK 通过回调提供原始音频数据时,需要使用该方法注册原始音频数据协议。 你需要在该方法中实现 AgoraAudioDataFrameProtocol

Note

  • 该方法需要在加入频道前调用。
  • 如果你想注销原始音频数据协议,请将 delegate 参数设为 nil。我们建议在收到 didLeaveChannelWithStats 后调用 setAudioDataFrame(nil)

Declared In

AgoraRtcEngineKit.h

直播视频水印

– addVideoWatermark:options:

添加本地视频水印。

- (int)addVideoWatermark:(NSURL *_Nonnull)url options:(WatermarkOptions *_Nonnull)options

Parameters

url

待添加的水印图片的本地路径。本方法支持从本地路径添加水印图片。如果待添加的水印图片位于工程文件中,则需要把图片在 Xcode 属性中将图像的 Type 由 PNG Image 修改为 Data, 否则 SDK 无法识别图片。

options

待添加的水印图片的设置选项,详见 WatermarkOptions

Return Value

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

Discussion

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的观众、旁路直播观众和采集设备都能看到或采集到该水印图片。声网当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。

水印坐标setVideoEncoderConfiguration 方法中的设置有依赖关系:

  • 如果视频编码方向/orientationMode 固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
  • 如果视频编码方向/orientationMode 固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
  • 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸,否则超出部分将被裁剪。

Note

  • 你需要在调用 enableVideo 方法之后再调用本方法。
  • 如果你只是在旁路直播(推流到CDN)中添加水印,你可以使用本方法或 setLiveTranscoding 方法设置水印。
  • 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
  • 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
  • 如果你已经使用 startPreview 方法开启本地视频预览,那么本方法的 visibleInPreview 可设置水印在预览时是否可见。
  • 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,声网建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。

Declared In

AgoraRtcEngineKit.h

– clearVideoWatermarks

删除已添加的视频水印

- (int)clearVideoWatermarks

Declared In

AgoraRtcEngineKit.h

直播音视频流回退

– setRemoteUserPriority:type:

设置远端用户流的优先级

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

Parameters

uid

远端用户的 ID

userPriority

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

Return Value

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

Discussion

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

弱网下 SDK 会优先保证高优先级用户收到的流的质量。

该方法需要在加入频道前调用。

Note:

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

Declared In

AgoraRtcEngineKit.h

– setLocalPublishFallbackOption:

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

- (int)setLocalPublishFallbackOption:(AgoraStreamFallbackOptions)option

Parameters

option

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

Return Value

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

Discussion

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

该方法需要在加入频道前调用。

Note:

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

Declared In

AgoraRtcEngineKit.h

– setRemoteSubscribeFallbackOption:

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

- (int)setRemoteSubscribeFallbackOption:(AgoraStreamFallbackOptions)option

Parameters

option

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

Return Value

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

Discussion

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

该方法需要在加入频道前调用。

Declared In

AgoraRtcEngineKit.h

视频双流模式

– enableDualStreamMode:

开关视频双流模式

- (int)enableDualStreamMode:(BOOL)enabled

Parameters

enabled

指定双流或者单流模式:

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

Return Value

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

Discussion

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

该方法在加入频道前后都能调用。

Declared In

AgoraRtcEngineKit.h

– setRemoteVideoStream:type:

设置订阅的视频流类型

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

Parameters

uid

用户 ID

streamType

设置视频流大小,AgoraVideoStreamType

Return Value

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

Discussion

在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode(NO) 关闭双流模式,接收端可以选择接收大流还是小流。其中,大流可以接收高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。

正常情况下,用户默认接收大流。如需节约带宽和计算资源,则可以调用该方法动态调整对应远端视频流的大小。SDK 会根据该方法中的设置,切换大小流。

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

调用本方法的执行结果将在 didApiCallExecute 中返回。

Note: 该方法在加入频道前后都能调用。如果既调用了 setRemoteVideoStream,也调用了 setRemoteDefaultVideoStreamType,则 SDK 以 setRemoteVideoStream 中的设置为准。

Declared In

AgoraRtcEngineKit.h

– enableWirelessAccelerate:

开启或关闭 Wi-Fi 加速功能。

- (int)enableWirelessAccelerate:(BOOL)enabled

Parameters

enabled

设置是否开启 Wi-Fi 加速功能:

  • YES: 开启。
  • NO: 关闭。

Return Value

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

Availability

v3.6.2

当 SDK 发现集成加速插件的 Wi-Fi 路由器后,该功能才会生效,使路由器合理分配 Wi-Fi 频谱资源,以降低丢包率和时延,从而减少音视频卡顿。

当路由器提供加速服务后,SDK 会周期性触发 wlAccStats 回调,报告 Wi-Fi 连接优化数据,并在 Wi-Fi 连接质量不佳时触发 wlAccMessage 回调,报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

Note:

  • Wi-Fi 加速功能默认开启,但必须与集成加速插件的路由器配合使用才能生效,详见哪些 Wi-Fi 路由器可支持加速功能。如果 Wi-Fi 路由器不支持加速功能,系统性能不会受损。
  • 加速功能生效后,路由器的 app 会显示加速效果和被加速 app 的名称。如果你不想在路由器的 app 中展示被加速 app 的名称,请调用 enableWirelessAccelerate(NO) 关闭加速功能。
  • 请在加入频道前或离开频道后调用该方法。
  • 声网提供的 Wi-Fi 加速功能除应用于音视频流,还可以应用于其他第三方业务流,如私有信令、课件、RTMP 协议等。如有需要,请联系 sales@agora.io

Declared In

AgoraRtcEngineKit.h

– setRemoteDefaultVideoStreamType:

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

- (int)setRemoteDefaultVideoStreamType:(AgoraVideoStreamType)streamType

Parameters

streamType

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

Return Value

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

Discussion

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

Note

  • 该方法只能在加入频道前调用。声网不支持你在加入频道后修改默认订阅的视频流类型。
  • 如果你既调用了该方法,也调用了 setRemoteVideoStream,则 SDK 以 setRemoteVideoStream 中的设置为准。

Declared In

AgoraRtcEngineKit.h

加密

– enableEncryption:encryptionConfig:

开启或关闭内置加密。

- (int)enableEncryption:(bool)enabled encryptionConfig:(AgoraEncryptionConfig *_Nonnull)config

Parameters

enabled

是否开启内置加密:

  • YES: 开启
  • NO: 关闭
config

配置内置加密模式和密钥。详见 AgoraEncryptionConfig

Return Value

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

    • -2 (AgoraErrorCodeInvalidArgument): 调用了无效的参数。需重新指定参数。
    • -7 (AgoraErrorCodeNotInitialized): SDK 尚未初始化。需在调用 API 之前已创建 AgoraRtcEngineKit 对象并完成初始化。
    • -4 (AgoraErrorCodeNotSupported): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。

Availability

v3.1.0

在安全要求较高的场景下,声网建议你在加入频道前,调用 enableEncryption 方法开启内置加密。

用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。

自 v3.4.5 起,声网推荐使用 AgoraEncryptionModeAES128GCM2AgoraEncryptionModeAES256GCM2 加密模式。这两种模式支持设置盐,安全性更高。 设置方法详见《媒体流加密》。

Discussion

Warning: 同一频道内所有用户必须使用相同的加密模式、密钥和盐,否则用户之间无法互通。

Note:

  • 如果开启了内置加密,则不能使用 RTMP/RTMPS 推流功能。
  • 为加强安全性,声网建议每次启用媒体流加密时都更换新的密钥和盐。

Declared In

AgoraRtcEngineKit.h

CDN 旁路推流

– addPublishStreamUrl:transcodingEnabled:

增加旁路推流地址

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

Parameters

url

CDN 推流地址,格式为 RTMP 或 RTMPS。该字符串长度不能超过 1024 字节。URL 不支持中文等特殊字符。

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

Return Value

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

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

Discussion

Deprecated 该方法自 3.6.0 版废弃,替代方案请参考发版说明

该方法用于添加旁路推流地址,调用该方法后,你可以向 CDN 推送 RTMP 或 RTMPS 协议的媒体流。SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告增加旁路推流地址的状态。

Note:

  • 该方法仅适用于直播场景。
  • 请确保在成功加入频道后再调用该接口。
  • 请确保已开通旁路推流的功能,详见前提条件
  • 该方法每次只能增加一路旁路推流地址。若需推送多路流,则需多次调用该方法。
  • 声网目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

Declared In

AgoraRtcEngineKit.h

– removePublishStreamUrl:

删除旁路推流地址

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

Parameters

url

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

Return Value

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

Discussion

Deprecated 该方法自 3.6.0 版废弃,替代方案请参考发版说明

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– setLiveTranscoding:

设置直播转码

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

Parameters

transcoding

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

Return Value

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

Discussion

Deprecated 该方法自 3.6.0 版废弃,替代方案请参考发版说明

该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码设置后本地会触发 rtcEngineTranscodingUpdated 回调。

Note:

  • 该方法需要在加入频道后调用。
  • 该方法仅适用于直播场景。
  • 请确保已开通 CDN 旁路推流的功能,详见前提条件
  • 首次调用该方法更新转码设置时,不会触发 rtcEngineTranscodingUpdated 回调。

Declared In

AgoraRtcEngineKit.h

– startRtmpStreamWithoutTranscoding:

开始非转码推流。

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

Parameters

url

CDN 推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。

Return Value

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

    • AgoraErrorCodeInvalidArgument(-2): url 为空或为长度为 0 的字符串。
    • AgoraErrorCodeNotInitialized(-7): 调用该方法前,未初始化 SDK。

Availability

v3.6.0

调用该方法,你可以向指定的 CDN 推流地址推送直播音视频流。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址推流,则需多次调用该方法。

调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。

Note:

  • 请确保已开通 CDN 推流服务,详见进阶功能《旁路推流》中的前提条件。
  • 请在加入频道后调用该方法。
  • 只有直播场景下的主播才能调用该方法。
  • 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。

Declared In

AgoraRtcEngineKit.h

– startRtmpStreamWithTranscoding:transcoding:

开始 CDN 直播推流并设置转码属性。

- (int)startRtmpStreamWithTranscoding:(NSString *_Nonnull)url transcoding:(AgoraLiveTranscoding *_Nullable)transcoding

Parameters

url

CDN 推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。

transcoding

CDN 直播推流的转码属性,详见 AgoraLiveTranscoding 类。

Return Value

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

    • AgoraErrorCodeInvalidArgument(-2): url 为空或为长度为 0 的字符串。
    • AgoraErrorCodeNotInitialized(-7): 调用该方法前,未初始化 SDK。

Availability

v3.6.0

调用该方法,你可以向指定的 CDN 推流地址推送直播音视频流并设置转码属性。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。

调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。

Note:

  • 请确保已开通 CDN 推流服务,详见进阶功能《旁路推流》中的前提条件。
  • 请在加入频道后调用该方法。
  • 只有直播场景下的主播才能调用该方法。
  • 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。

Declared In

AgoraRtcEngineKit.h

– updateRtmpTranscoding:

更新转码属性。

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

Parameters

transcoding

CDN 直播推流的转码属性,详见 LiveTranscoding 类。

Return Value

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

Availability

v3.6.0

开启转码推流后,你可以根据场景需求,动态更新转码属性。转码属性更新后,SDK 会触发 rtcEngineTranscodingUpdated 回调。

Declared In

AgoraRtcEngineKit.h

– stopRtmpStream:

结束 CDN 直播推流。

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

Parameters

url

CDN 推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。

Return Value

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

Availability

v3.6.0

调用该方法,你可以结束指定的 CDN 推流地址上的直播。该方法每次只能结束一个推流地址上的直播,如果你需要结束多个推流地址的直播,则需多次调用该方法。

调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。

Declared In

AgoraRtcEngineKit.h

数据流

– createDataStream:config:

创建数据流。

- (int)createDataStream:(NSInteger *_Nonnull)streamId config:(AgoraDataStreamConfig *_Nonnull)config

Parameters

streamId

(输出参数)数据流 ID。

config

数据流设置:AgoraDataStreamConfig

Return Value

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

Availability

v3.3.0

该方法用于创建数据流。每个用户在每个频道内最多只能创建 5 个数据流。

该方法不支持数据可靠,接收方会丢弃超出发送时间 5 秒后的数据包。

Discussion

Note: 创建数据流后,如果你离开频道,SDK 会销毁数据流。

Declared In

AgoraRtcEngineKit.h

– sendStreamMessage:data:

发送数据流

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

Parameters

streamId

数据流 ID,createDataStream 的返回值。

data

需要发送的消息

Return Value

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

Discussion

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

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

Note:

  • 该方法仅适用于通信场景以及直播场景下的主播用户,如果直播场景下的观众调用此方法可能会造成观众变主播。
  • 请确保在调用该方法前,已调用 createDataStream 创建了数据通道。

Declared In

AgoraRtcEngineKit.h

其他视频控制

– setCameraCapturerConfiguration:

设置摄像头采集配置

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

Parameters

configuration

摄像头采集配置,详见 AgoraCameraCapturerConfiguration

Return Value

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

Discussion

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

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

Note:

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

Declared In

AgoraRtcEngineKit.h

摄像头控制

– switchCamera

切换前置/后置摄像头

- (int)switchCamera

Return Value

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

Discussion

Note

  • 本方法仅适用于 iOS 平台,不适用于 macOS。
  • 该方法需要在相机启动(如通过调用 startPreviewjoinChannelByToken 实现)后调用。

Declared In

AgoraRtcEngineKit.h

– isCameraZoomSupported

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

- (BOOL)isCameraZoomSupported

Return Value

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

Discussion

Note

  • 本方法仅适用于 iOS 平台,不适用于 macOS。
  • 该方法需要在相机启动(如通过调用 startPreviewjoinChannelByToken 实现)后调用。

Declared In

AgoraRtcEngineKit.h

– isCameraTorchSupported

检查设备是否支持打开闪光灯

- (BOOL)isCameraTorchSupported

Return Value

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

Discussion

SDK 默认使用前置摄像头,因此如果你直接调用 isCameraTorchSupported, 你可以从返回值中了解使用前置摄像头时是否支持打开闪光灯。 如果你想检查使用后置摄像头时设备是否支持打开闪光灯,请先调用 switchCamera 切换 SDK 使用的摄像头为后置摄像头,再调用 isCameraTorchSupported

Note

  • 该方法需在摄像头启动后调用。
  • 本方法仅适用于 iOS 平台,不适用于 macOS。
  • 在系统版本 15 的 iPad 上,即使 isCameraTorchSupported 返回 YES,也可能因系统问题导致你无法通过 setCameraTorchOn 成功开启闪光灯。

Declared In

AgoraRtcEngineKit.h

– isCameraFocusPositionInPreviewSupported

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

- (BOOL)isCameraFocusPositionInPreviewSupported

Return Value

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

Discussion

Note

  • 本方法仅适用于 iOS 平台,不适用于 macOS。
  • 该方法需要在相机启动(如通过调用 startPreviewjoinChannelByToken 实现)后调用。

Declared In

AgoraRtcEngineKit.h

– isCameraExposurePositionSupported

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

- (BOOL)isCameraExposurePositionSupported

Return Value

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

Discussion

Note

  • 本方法仅适用于 iOS 平台,不适用于 macOS。
  • 该方法需要在相机启动(如通过调用 startPreviewjoinChannelByToken 实现)后调用。

Declared In

AgoraRtcEngineKit.h

– isCameraAutoFocusFaceModeSupported

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

- (BOOL)isCameraAutoFocusFaceModeSupported

Return Value

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

Discussion

Note

  • 本方法仅适用于 iOS 平台,不适用于 macOS。
  • 该方法需要在相机启动(如通过调用 startPreviewjoinChannelByToken 实现)后调用。

Declared In

AgoraRtcEngineKit.h

– setCameraZoomFactor:

设置摄像头缩放比例

- (CGFloat)setCameraZoomFactor:(CGFloat)zoomFactor

Parameters

zoomFactor

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

Return Value

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

Discussion

Note

  • 本方法仅适用于 iOS 平台,不适用于 macOS。
  • 该方法需要在相机启动(如通过调用 startPreviewjoinChannelByToken 实现)后调用。

Declared In

AgoraRtcEngineKit.h

– setCameraFocusPositionInPreview:

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

- (BOOL)setCameraFocusPositionInPreview:(CGPoint)position

Parameters

position

触摸点相对于视图的坐标

Return Value

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

Discussion

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

Note

  • 本方法仅适用于 iOS 平台,不适用于 macOS。
  • 该方法需要在相机启动(如通过调用 startPreviewjoinChannelByToken 实现)后调用。

Declared In

AgoraRtcEngineKit.h

– setCameraExposurePosition:

设置摄像头曝光位置

- (BOOL)setCameraExposurePosition:(CGPoint)positionInView

Parameters

positionInView

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

Return Value

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

Discussion

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

Note

  • 本方法仅适用于 iOS 平台,不适用于 macOS。
  • 该方法需要在相机启动(如通过调用 startPreviewjoinChannelByToken 实现)后调用。

Declared In

AgoraRtcEngineKit.h

– setCameraTorchOn:

设置是否打开闪光灯

- (BOOL)setCameraTorchOn:(BOOL)isOn

Parameters

isOn

是否打开闪光灯:

  • YES: 打开
  • NO: 关闭

Return Value

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

Discussion

Note

  • 该方法需在摄像头启动后调用。
  • 本方法仅适用于 iOS 平台,不适用于 macOS。
  • 在系统版本 15 的 iPad 上,即使 isCameraTorchSupported 返回 YES,也可能因系统问题导致你无法通过 setCameraTorchOn 成功开启闪光灯。

Declared In

AgoraRtcEngineKit.h

– setCameraAutoFocusFaceModeEnabled:

设置是否开启人脸自动对焦

- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable

Parameters

enable

是否开启人脸自动对焦:

  • YES: 开启人脸自动对焦。
  • NO: 关闭人脸自动对焦。

Return Value

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

Discussion

对 3.5.0 之前版本,SDK 默认关闭人脸自动对焦。对 3.5.0 和之后版本,SDK 默认开启人脸自动对焦。如需自行设置人脸自动对焦,请调用该方法。

Note

  • 该方法仅适用于 iOS,不适用于 macOS。
  • 该方法需在摄像头启动后调用。

Declared In

AgoraRtcEngineKit.h

屏幕共享

– startScreenCaptureByDisplayId:rectangle:parameters:

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

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

Parameters

displayId

指定待共享的屏幕 ID。开发者需要通过该参数指定你要共享的那个屏幕。 关于如何获取屏幕 ID,请参考基础功能《共享屏幕》或从 getScreenCaptureSourcesWithThumbSize 返回的 sourceId 获取。

rectangle

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

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

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

captureParams

屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。 详见 AgoraScreenCaptureParameters 中的说明。

Return Value

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

    • -2(AgoraErrorCodeInvalidArgument):传入的参数无效。

Discussion

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

Note: 该方法需要在加入频道后调用。

Declared In

AgoraRtcEngineKit.h

– startScreenCaptureByWindowId:rectangle:parameters:

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

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

Parameters

windowId

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

rectangle

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

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

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

captureParams

屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。 详见 AgoraScreenCaptureParameters 中的说明。

Return Value

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

    • -2(AgoraErrorCodeInvalidArgument):传入的参数无效。

Discussion

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

Note: 该方法需要在加入频道后调用。

Declared In

AgoraRtcEngineKit.h

– setScreenCaptureContentHint:

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

- (int)setScreenCaptureContentHint:(AgoraVideoContentHint)contentHint

Parameters

contentHint

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

Return Value

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

Discussion

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

该方法在开始屏幕共享前后都能调用。

Declared In

AgoraRtcEngineKit.h

– updateScreenCaptureParameters:

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

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

Parameters

captureParams

屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。 详见 AgoraScreenCaptureParameters 中的说明。

Return Value

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

    • -2(AgoraErrorCodeInvalidArgument):传入的参数无效。

Discussion

Note: 请在开启屏幕共享或窗口共享后调用该方法。

Declared In

AgoraRtcEngineKit.h

– updateScreenCaptureRegion:

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

- (int)updateScreenCaptureRegion:(CGRect)rect

Parameters

rect

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

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

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

Return Value

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

    • -2(AgoraErrorCodeInvalidArgument):传入的参数无效。

Discussion

Note: 请在开启屏幕共享或窗口共享后调用该方法。

Declared In

AgoraRtcEngineKit.h

– getScreenCaptureSourcesWithThumbSize:iconSize:includeScreen:

获取可共享的屏幕和窗口对象列表。

- (NSArray<AgoraScreenCaptureSourceInfo*> *_Nullable)getScreenCaptureSourcesWithThumbSize:(NSSize)thumbSize iconSize:(NSSize)iconSize includeScreen:(BOOL)includeScreen

Parameters

thumbSize

屏幕或窗口的缩略图的目标尺寸(宽高单位为像素)。 SDK 会在保证原图不变形的前提下,缩放原图,使图片最长边和目标尺寸的最长边的长度一致。例如,原图宽高为 400 × 300,thumbSize 为 100 x 100,缩略图实际尺寸为 100 × 75。 如果目标尺寸大于原图尺寸,缩略图即为原图,SDK 不进行缩放操作。

iconSize

程序所对应的图标的目标尺寸(宽高单位为像素)。SDK 会在保证原图不变形的前提下,缩放原图,使图片最长边和目标尺寸的最长边的长度一致。 例如,原图宽高为 400 × 300,iconSize 为 100 × 100,图标实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸,图标即为原图,SDK 不进行缩放操作。

includeScreen

除了窗口信息外,SDK 是否还返回屏幕信息:

  • YES: 是。SDK 返回屏幕和窗口信息。
  • NO: 否。SDK 仅返回窗口信息。

Availability

v3.5.2

屏幕共享或窗口共享前,你可以调用该方法获取可共享的屏幕和窗口的对象数组列表,方便用户通过列表中的缩略图选择共享某个显示器的屏幕或某个窗口。 列表中包含窗口 ID 和屏幕 ID 等重要信息,你可以获取到 ID 后再调用 startScreenCaptureByWindowIdstartScreenCaptureByDisplayId 开启共享。

Discussion

Note: 该方法仅适用于 macOS。

Declared In

AgoraRtcEngineKit.h

– stopScreenCapture

停止屏幕共享

- (int)stopScreenCapture

Return Value

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

Declared In

AgoraRtcEngineKit.h

– startScreenCapture:

开始屏幕共享(仅支持 iOS)。

- (int)startScreenCapture:(AgoraScreenCaptureParameters2 *_Nonnull)parameters

Parameters

parameters

屏幕共享的配置。详见 AgoraScreenCaptureParameters2

Return Value

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

Availability

v3.7.0

屏幕共享 Extension 进程开启、结束、异常退出时,SDK 会相应地触发 localVideoStateChange 回调并分别报告 AgoraLocalVideoStreamErrorExtensionCaptureStarted(13)AgoraLocalVideoStreamErrorExtensionCaptureStoped(14)AgoraLocalVideoStreamErrorExtensionCaptureDisconnected(15)

Note:

  • 请在加入频道后调用该方法。
  • 屏幕共享仅适用于 iOS 12.0 及以上。
  • 屏幕共享流的计费以 AgoraScreenCaptureParameters2 中 dimensions 的值为准:当你未传值时,以 1280 × 720 计费;当你传值时,以你传入的值计费。详细的计费规则请参考实时音视频计费
  • 如果你使用音频自采集而非 SDK 采集音频,为避免应用退后台后屏幕共享停止,声网建议你对应用添加保活处理逻辑。
  • 该功能对设备性能要求较高,声网推荐你在 iPhone X 及之后机型上使用。

Declared In

AgoraRtcEngineKit.h

– updateScreenCapture:

更新屏幕共享配置(仅支持 iOS)。

- (int)updateScreenCapture:(AgoraScreenCaptureParameters2 *_Nonnull)parameters

Parameters

parameters

屏幕共享的配置。详见 AgoraScreenCaptureParameters2

Return Value

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

Availability

v3.7.0

Discussion

Note: 请在 startScreenCapture 后调用该方法。

Declared In

AgoraRtcEngineKit.h

音视频设备管理 (macOS)

– monitorDeviceChange:

监控设备改变

- (void)monitorDeviceChange:(BOOL)enabled

Parameters

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

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– enumerateDevices:

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

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

Parameters

type

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

Return Value

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

Discussion

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

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– getDeviceInfo:

获取当前设备名称

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

Parameters

type

设备的类型,包括音、视频采集或播放设备,详见 AgoraMediaDeviceType

Return Value

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– setDevice:deviceId:

指定设备

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

Parameters

type

设备的类型,包括音、视频采集或播放设备,详见 AgoraMediaDeviceType

deviceId

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

Return Value

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

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– getDefaultAudioDevice:

获取系统默认的音频设备。

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

Parameters

type

设备的类型,详见 AgoraMediaDeviceType

Return Value

Availability

v3.6.0

Discussion

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

Declared In

AgoraRtcEngineKit.h

– getDeviceVolume:

获取设备音量

- (int)getDeviceVolume:(AgoraMediaDeviceType)type

Parameters

type

设备的类型,包括音、视频采集或播放设备,详见 AgoraMediaDeviceType

Return Value

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

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– setDeviceVolume:volume:

设置设备音量

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

Parameters

type

设备的类型,包括音、视频采集或播放设备,详见 AgoraMediaDeviceType

volume

设置的音量

Return Value

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

Discussion

设置音、视频采集或播放设备的音量。

Note

  • 该方法需要在加入频道后调用。
  • 该方法仅支持 macOS 平台,不支持 iOS 平台。

Declared In

AgoraRtcEngineKit.h

– followSystemPlaybackDevice:

设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。

- (int)followSystemPlaybackDevice:(BOOL)enable

Parameters

enable

是否跟随系统默认的音频播放设备:

  • YES: 跟随。当系统默认音频播放设备发生改变时,SDK 立即切换音频播放设备。
  • NO: 不跟随。只有当 SDK 使用的音频播放设备被移除后,SDK 才切换至系统默认的音频播放设备。

Return Value

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

Availability

v3.6.0

Discussion

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

Declared In

AgoraRtcEngineKit.h

– followSystemRecordingDevice:

设置 SDK 使用的音频采集设备跟随系统默认的音频采集设备。

- (int)followSystemRecordingDevice:(BOOL)enable

Parameters

enable

是否跟随系统默认的音频采集设备:

  • YES: 跟随。当系统默认的音频采集设备改变时,SDK 立即切换音频采集设备。
  • NO: 不跟随。只有当 SDK 使用的音频采集设备被移除后,SDK 才切换至系统默认的音频采集设备。

Return Value

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

Availability

v3.6.0

Discussion

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

Declared In

AgoraRtcEngineKit.h

– startRecordingDeviceTest:

启动音频采集设备测试

- (int)startRecordingDeviceTest:(int)indicationInterval

Parameters

indicationInterval

SDK 触发 reportAudioVolumeIndicationOfSpeakersreportAudioDeviceTestVolume 回调的时间间隔,单位为毫秒。建议设置到大于 200 毫秒。不得少于 10 毫秒,否则会收不到音量回调。

Return Value

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

Discussion

该方法测试音频采集设备是否能正常工作。

自 v3.6.2 起,该方法在加入频道前后均可调用,并按设置的时间间隔触发如下回调,报告采集设备的音量信息:

  • 在加入频道前调用该方法,SDK 触发 reportAudioVolumeIndicationOfSpeakersreportAudioDeviceTestVolume 回调,其中:

    • reportAudioVolumeIndicationOfSpeakers 报告 uid = 0volume

    • reportAudioDeviceTestVolume 报告 volumeType = AgoraAudioDeviceTestRecordingVolume(0)volume

    这两个回调报告的音量信息相同,声网推荐使用 reportAudioDeviceTestVolume

  • 在加入频道后调用该方法,SDK 触发 reportAudioDeviceTestVolume 回调,报告 volumeType = AgoraAudioDeviceTestRecordingVolume(0)volume

Note

  • 加入频道后调用该方法前,请确保音频采集设备处于开启状态,即 enableLocalAudio(YES)。否则,方法调用会失败,SDK 触发 didOccurError 回调,报告 AgoraErrorCodeAdmStartRecording(1012) 错误码。
  • 该方法仅支持 macOS 平台,不支持 iOS 平台。
  • 加入频道后调用该方法,测试的是 SDK 正在使用的音频采集设备。
  • 调用该方法后,必须调 stopRecordingDeviceTest 方法停止测试。

Declared In

AgoraRtcEngineKit.h

– stopRecordingDeviceTest

停止麦克风测试

- (int)stopRecordingDeviceTest

Return Value

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

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– startPlaybackDeviceTest:

启动音频播放设备测试

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

Parameters

audioFileName

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

Return Value

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

Discussion

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

自 v3.6.2 起,该方法在加入频道前后均可调用,并每隔 100 ms 触发一次如下回调,报告播放设备的音量信息:

  • 在加入频道前调用该方法,触发 reportAudioVolumeIndicationOfSpeakersreportAudioDeviceTestVolume 回调,其中:

    • reportAudioVolumeIndicationOfSpeakers 报告 uid = 1volume

    • reportAudioDeviceTestVolume 报告 volumeType = AgoraAudioDeviceTestPlaybackVolume(1)volume

    这两个回调报告的音量信息相同,声网推荐使用 reportAudioDeviceTestVolume

  • 在加入频道后调用该方法,SDK 触发 reportAudioDeviceTestVolume,报告 volumeType = AgoraAudioDeviceTestPlaybackVolume(1)volume

Note

  • 加入频道后调用该方法,测试的是 SDK 正在使用的音频播放设备。
  • 该方法仅支持 macOS 平台,不支持 iOS 平台。
  • 调用该方法后,必须调 stopPlaybackDeviceTest 方法停止测试。

Declared In

AgoraRtcEngineKit.h

– stopPlaybackDeviceTest

停止播放设备测试

- (int)stopPlaybackDeviceTest

Return Value

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

Discussion

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

Note

  • 该方法需要在加入频道前调用。
  • 该方法仅支持 macOS 平台,不支持 iOS 平台。

Declared In

AgoraRtcEngineKit.h

– startCaptureDeviceTest:

启动视频采集设备测试

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

Parameters

view

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

Return Value

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

Discussion

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

Note

  • 该方法需要在加入频道前调用。
  • 该方法仅支持 macOS 平台,不支持 iOS 平台。

Declared In

AgoraRtcEngineKit.h

– stopCaptureDeviceTest

停止视频采集设备测试

- (int)stopCaptureDeviceTest

Return Value

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

Discussion

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

Note

  • 该方法需要在加入频道前调用。
  • 该方法仅支持 macOS 平台,不支持 iOS 平台。

Declared In

AgoraRtcEngineKit.h

– startAudioDeviceLoopbackTest:

开始音频设备回路测试

- (int)startAudioDeviceLoopbackTest:(int)indicationInterval

Parameters

indicationInterval

SDK 触发 reportAudioVolumeIndicationOfSpeakersreportAudioDeviceTestVolume 回调的时间间隔,单位为毫秒。建议设置到大于 200 毫秒。不得少于 10 毫秒,否则会收不到音量回调。

Return Value

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

Discussion

该方法测试音频采集和播放设备是否能正常工作。一旦测试开始,音频采集设备会采集本地音频,然后通过音频播放设备播放。

自 v3.6.2 起,该方法在加入频道前后均可调用,并按设置的时间间隔触发如下回调,分别报告采集设备和播放设备的音量信息:

  • 在加入频道前调用该方法,触发 reportAudioVolumeIndicationOfSpeakersreportAudioDeviceTestVolume 回调,每个回调触发两次,其中:

    • reportAudioVolumeIndicationOfSpeakers 分别报告 uid = 0volume,以及 uid = 1volume

    • reportAudioDeviceTestVolume 分别报告 volumeType = AgoraAudioDeviceTestRecordingVolume(0)volume,以及 volumeType = AgoraAudioDeviceTestPlaybackVolume(1)volume

    reportAudioVolumeIndicationOfSpeakersreportAudioDeviceTestVolume 回调报告的音量信息相同,声网推荐使用 reportAudioDeviceTestVolume

  • 在加入频道后调用该方法,SDK 触发两个 reportAudioDeviceTestVolume 回调,分别报告 volumeType = AgoraAudioDeviceTestRecordingVolume(0)volume,以及 volumeType = AgoraAudioDeviceTestPlaybackVolume(1)volume

Note:

  • 该方法仅在本地进行音频设备测试,不涉及网络连接。
  • 该方法仅支持 macOS 平台,不支持 iOS 平台。
  • 加入频道后调用该方法前,请确保音频采集设备处于开启状态,即 enableLocalAudio(YES)。否则,方法调用会失败,SDK 触发 didOccurError 回调,报告 AgoraErrorCodeAdmStartRecording(1012) 错误码。
  • 调用该方法后,必须调 stopAudioDeviceLoopbackTest 方法停止测试。
  • 加入频道后调用该方法,测试的是 SDK 正在使用的音频采集和播放设备。

Declared In

AgoraRtcEngineKit.h

– stopAudioDeviceLoopbackTest

停止音频设备回路测试

- (int)stopAudioDeviceLoopbackTest

Return Value

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

Discussion

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

Note

  • 该方法需要在加入频道前调用。
  • 该方法仅支持 macOS 平台,不支持 iOS 平台。

Declared In

AgoraRtcEngineKit.h

媒体附属信息

– setMediaMetadataDataSource:withType:

设置媒体附属信息的 Data source

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

Parameters

metadataDataSource

AgoraMediaMetadataDataSource 协议。

type

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

Return Value

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

Discussion

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

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

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

Declared In

AgoraRtcEngineKit.h

– setMediaMetadataDelegate:withType:

设置媒体附属信息的 Delegate

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

Parameters

metadataDelegate

AgoraMediaMetadataDelegate 协议。

type

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

Return Value

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

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

其他方法

– getAudioFileInfo:

获取指定音频文件信息。

- (int)getAudioFileInfo:(NSString *_Nullable)filePath

Parameters

filePath

音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如:/var/mobile/Containers/Data/audio.mp4

Return Value

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

Availability

v3.5.1

成功调用该方法后,SDK 会触发 didRequestAudioFileInfo 回调,报告指定音频文件的时长等信息。你可以多次调用该方法,获取多个音频文件的信息。

Note

Declared In

AgoraRtcEngineKit.h

– getCallId

获取通话 ID

- (NSString *_Nullable)getCallId

Return Value

当前通话 ID

Discussion

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

Note: 该方法需要在加入频道后调用。

Declared In

AgoraRtcEngineKit.h

– rate:rating:description:

给通话评分

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

Parameters

callId

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

rating

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

description

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

Return Value

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

Discussion

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

Note: 该方法需要在离开频道后调用。

Declared In

AgoraRtcEngineKit.h

– complain:description:

投诉通话质量

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

Parameters

callId

通过 getCallId 函数获取的通话 ID

description

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

Return Value

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

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

Discussion

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

Note: 该方法需要在离开频道后调用。

Declared In

AgoraRtcEngineKit.h

– enableMainQueueDispatch:

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

- (int)enableMainQueueDispatch:(BOOL)enabled

Parameters

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

Return Value

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

Discussion

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

Declared In

AgoraRtcEngineKit.h

+ getSdkVersion

查询 SDK 版本号

+ (NSString *_Nonnull)getSdkVersion

Return Value

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

Discussion

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

Note: 该方法在加入频道前后都能调用。

Declared In

AgoraRtcEngineKit.h

+ getErrorDescription:

获取警告或错误描述。

+ (NSString *_Nullable)getErrorDescription:(NSInteger)code

Parameters

code

didOccurWarningdidOccurError 提供的警告码或错误码。

Return Value

AgoraWarningCodeAgoraErrorCode

Declared In

AgoraRtcEngineKit.h

– sendCustomReportMessage:category:event:label:value:

声网提供自定义数据上报和分析服务。

- (int)sendCustomReportMessage:(NSString *_Nonnull)id category:(NSString *_Nonnull)category event:(NSString *_Nonnull)event label:(NSString *_Nonnull)label value:(NSInteger)value

Parameters

id

预留

category

预留

event

预留

label

预留

value

预留

Availability

v3.1.0

该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据,每条自定义数据不能超过 256 字节,每个字符串不能超过 100 字节。如需试用该服务, 请联系 sales@agora.io 开通并商定自定义数据格式。

Declared In

AgoraRtcEngineKit.h

– getNativeHandle

获取 Native SDK Engine Handle

- (void *_Nullable)getNativeHandle

Discussion

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

Declared In

AgoraRtcEngineKit.h

  delegate

设置/获取 AgoraRtcEngineDelegate

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

Discussion

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

Declared In

AgoraRtcEngineKit.h

– takeSnapshot:uid:filePath:

获取视频截图。

- (NSInteger)takeSnapshot:(NSString *_Nonnull)channel uid:(NSInteger)uid filePath:(NSString *_Nonnull)filePath

Parameters

channel

频道名。

uid

用户 ID。如果要对本地用户的视频截图,uid 设为 0。

filePath

截图的本地保存路径,需精确到文件名及格式, 例如:/App Sandbox/Library/Caches/example.jpg(iOS)或 ~/Library/Logs/example.jpg(macOS)。请确保目录存在且可写。

Return Value

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

Availability

v3.5.2

该方法用于对指定用户的视频流进行截图,生成一张 JPG 格式的图片,并保存至指定的路径。

该方法是异步操作,调用返回时 SDK 并没有真正获取截图。成功调用该方法后,SDK 会触发 snapshotTaken 回调报告截图是否成功和获取截图的详情。

相比 enableContentInspect 方法,本方法是即时截图,截图会保存在你指定的本地路径。

Note:

  • 该方法需要在加入频道后调用。
  • 如果用户的视频经过前处理,例如,添加了水印或美颜,生成的截图会包含前处理效果。

Declared In

AgoraRtcEngineKit.h

– enableContentInspect:config:

开启/关闭视频截图上传。

- (int)enableContentInspect:(BOOL)enabled config:(AgoraContentInspectConfig *_Nonnull)config

Parameters

enabled

设置是否开启视频截图上传:

  • YES: 开启。
  • NO: 关闭。
config

视频截图上传配置。详见 AgoraContentInspectConfig

Return Value

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

Availability

v3.6.2

开启视频截图上传后,SDK 会根据你在 AgoraContentInspectConfig 中设置的视频截图上传模块类型和频率对本地用户发送的视频进行截图、上传。截图完成后,声网服务器会以 HTTPS 请求的形式通知你的服务器,并将所有截图发送至你指定的第三方云存储。

相比 takeSnapshot 方法,本方法可以按照你设置的截图频率进行周期性截图,并将截图发送至你指定的第三方云存储。

Note: 调用该方法前,请确保满足以下要求:

  • 提交工单开通声网视频截图上传服务。

  • 已将 AgoraCIExtension.xcframework 动态库集成到项目中。

Declared In

AgoraRtcEngineKit.h

已废弃方法

– pushExternalAudioFrameRawData:samples:timestamp:

推送外部音频帧

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

Parameters

data

外部音频数据

samples

音频帧的样本数量

timestamp

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

Return Value

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

Discussion

Deprecated 该方法自 v3.5.1 起废弃,请改用 pushExternalAudioFrameRawData 2。

Declared In

AgoraRtcEngineKit.h

– pushExternalAudioFrameSampleBuffer:

推送外部 CMSampleBuffer 音频帧

- (BOOL)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer

Parameters

sampleBuffer

采样缓冲区

Return Value

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

Discussion

Deprecated 该方法自 v3.5.1 起废弃,请改用 pushExternalAudioFrameSampleBuffer 2。

Declared In

AgoraRtcEngineKit.h

– getAudioMixingDuration

获取当前音乐文件时长

- (int)getAudioMixingDuration

Return Value

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

Discussion

Deprecated 该方法自 v3.5.1 起废弃,请改用 getAudioFileInfo

Note: 该方法需在 startAudioMixing 后调用。

Declared In

AgoraRtcEngineKit.h

– enableRemoteSuperResolution:enabled:

开启/关闭远端视频超分辨率。(beta 功能)

- (int)enableRemoteSuperResolution:(NSUInteger)uid enabled:(BOOL)enabled

Parameters

uid

远端用户 ID。

enabled

是否对远端视频开启超级分辨率:

  • YES: 开启。
  • NO: 关闭。

Return Value

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

    • -157(AgoraErrorCodeModuleNotFound): 未集成超分辨率动态库。

Availability

v3.5.1

该功能可以有效地提升本地用户看到的远端视频画面的分辨率。远端用户视频的原始分辨率为 a × b, 开启该功能后,本地设备会以 2a × 2b 的分辨率显示该远端视频。

调用该方法后,SDK 会触发 superResolutionEnabledOfUid 回调报告超分辨率是否成功开启。

Warning

超分辨率功能会额外耗费系统资源。为平衡视觉体验和系统消耗,只可以对一个远端用户开启超分辨率, 并且远端用户视频的原始分辨率不能超过 640 × 480。

Note

  • 该方法仅适用于 iOS 平台。
  • 调用该方法前,请确保你已经将 AgoraSuperResolutionExtension.xcframework 动态库集成到项目中。
  • 该方法对用户设备具有一定要求,声网推荐你使用如下或更好的 iOS 设备(系统版本 12 或之后):

    • iPhone XR
    • iPhone XS
    • iPhone XS Max
    • iPhone 11
    • iPhone 11 Pro
    • iPhone 11 Pro Max
    • iPhone 12
    • iPhone 12 mini
    • iPhone 12 Pro
    • iPhone 12 Pro Max
    • iPhone 12 SE(第二代)
    • iPad Pro 11-inch(第三代)
    • iPad Pro 12.9-inch(第三代)
    • iPad Air(第三代)
    • iPad Air(第四代)

Discussion

Deprecated: 该方法自 v3.7.1 废弃,请改用 enableRemoteSuperResolution 方法。

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

Parameters

soundId

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

filePath

音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如:/var/mobile/Containers/Data/audio.mp4

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: 音效文件在本地播放的同时,会发布到声网云上,因此远端用户也能听到该音效
  • NO: 音效文件不会发布到声网云上,因此只能在本地听到该音效

Return Value

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

Discussion

Deprecated 自 v3.4.0 废弃。请改用 playEffect

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

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

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

Note

  • 该方法需要在加入频道后调用。
  • 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件
  • 如果你需要通过 playEffect 播放在线音效文件,声网建议你将在线音效文件缓存到本地设备,调用 preloadEffect 将音效加载至内存,确保这里设置的 soundId 与 preloadEffect 将缓存的音效文件预加载到内存中,再调用 playEffect 播放音效。否则,可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。

Declared In

AgoraRtcEngineKit.h

– startAudioRecording:sampleRate:quality:

开始客户端录音。

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

Parameters

filePath

录音文件在本地保存的绝对路径,由用户自行指定,需精确到文件名及格式,例如:/var/mobile/Containers/Data/audio.aac。

sampleRate

录音采样率(Hz),可以设为以下值:

  • 16000
  • 32000(默认)
  • 44100
  • 48000
quality

录音音质。详见 AgoraAudioRecordingQuality

Return Value

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

Discussion

Deprecated 自 v3.4.0 废弃。请改用 startAudioRecordingWithConfig

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

  • .wav: 文件大,音质保真度较高。
  • .aac: 文件小,音质保真度较低。

Note

  • 请确保你在该方法中指定的路径存在并且可写。
  • 该接口需在 joinChannelByToken 之后调用。如果调用 leaveChannel 时还在录音,录音会自动停止。
  • 为保证录音效果,当 sampleRate 设为 44100 Hz 或 48000 Hz 时,建议将 quality 设为 AgoraAudioRecordingQualityMedium 或 AgoraAudioRecordingQualityHigh 。

Declared In

AgoraRtcEngineKit.h

– startAudioMixing:loopback:replace:cycle:

开始播放音乐文件

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

Parameters

filePath

音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如:/var/mobile/Containers/Data/audio.mp4

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

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

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

Return Value

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

Discussion

Deprecated 自 v3.4.0 废弃,请改用 startAudioMixing2。

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

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

Note:

  • 为避免阻塞,自 v3.4.5 起,该方法由同步调用改为异步调用。
  • 如果播放的是在线音乐文件,请确保重复调用该 API 的间隔超过 100 ms,否则 SDK 会返回 AudioFileOpenTooFrequent(702)警告码,表示音乐文件打开过于频繁。
  • 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 AgoraWarningCodeAudioMixingOpenError = 701
  • 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件

Declared In

AgoraRtcEngineKit.h

– setDefaultMuteAllRemoteVideoStreams:

默认取消或恢复订阅远端用户的视频流。

- (int)setDefaultMuteAllRemoteVideoStreams:(BOOL)mute

Parameters

mute

是否默认取消订阅远端用户的视频流:

  • YES: 默认取消订阅。
  • NO: (默认)默认订阅。

Return Value

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

Discussion

Deprecated 该方法自 v3.3.0 起废弃。

该方法需要在加入频道后调用。调用成功后,本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。

Note

取消订阅视频流后,如果需要恢复订阅频道内的远端用户,可以进行如下操作:

  • 如果需要恢复订阅单个用户的视频流,调用 muteRemoteVideoStream(NO), 并指定你想要订阅的远端用户 ID。
  • 如果想恢复订阅多个用户的音频流,则需要多次调用 muteRemoteVideoStream(NO)

Declared In

AgoraRtcEngineKit.h

– setDefaultMuteAllRemoteAudioStreams:

默认取消或恢复订阅远端用户的音频流。

- (int)setDefaultMuteAllRemoteAudioStreams:(BOOL)mute

Parameters

mute

是否默认取消订阅远端用户的音频流:

  • YES: 默认取消订阅。
  • NO: (默认)默认订阅。

Return Value

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

Discussion

Deprecated 该方法自 v3.3.0 起废弃。

该方法需要在加入频道后调用。调用成功后,本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。

Note

取消订阅音频流后,如果需要恢复订阅频道内的远端用户,可以进行如下操作:

  • 如果需要恢复订阅单个用户的音频流,调用 muteRemoteAudioStream(NO), 并指定你想要订阅的远端用户 ID。
  • 如果想恢复订阅多个用户的音频流,则需要多次调用 muteRemoteAudioStream(NO)

Declared In

AgoraRtcEngineKit.h

– setLogFile:

设置日志文件

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

Parameters

filePath

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

Return Value

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

Discussion

Deprecated 该方法从 v3.3.0 起废弃,请改用 sharedEngineWithConfig 中的 LogConfig 参数设置日志文件路径。

默认情况下,SDK 会生成 agorasdk.logagorasdk_1.logagorasdk_2.logagorasdk_3.logagorasdk_4.log 这 5 个日志文件。 每个文件的默认大小为 1024 KB。日志文件为 UTF-8 编码。最新的日志永远写在 agorasdk.log 中。agorasdk.log 写满后,SDK 会从 1-4 中删除修改时间最早的一个文件, 然后将 agorasdk.log 重命名为该文件,并建立新的 agorasdk.log 写入最新的日志。

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
      • 关闭沙盒:/Users/<username>/Library/Caches/<App Bundle Identifier>/Logs/agorasdk.log
  • 如需调用本方法,请在调用 sharedEngineWithAppId 方法初始化 AgoraRtcEngineKit 对象后立即调用,否则可能造成输出日志不完整。

Declared In

AgoraRtcEngineKit.h

– setLogFilter:

设置日志输出等级

- (int)setLogFilter:(NSUInteger)filter

Parameters

filter

AgoraLogFilter

Return Value

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

Discussion

Deprecated 该方法从 v3.3.0 起废弃,请改用 sharedEngineWithConfig 中的 LogConfig 参数设置日志输出等级。

设置 SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 OffCriticalErrorWarningInfoDebug。选择一个级别,你就可以看到在该级别之前所有级别的日志信息。

例如,你选择 Warning 级别,就可以看到在 CriticalErrorWarning 级别上的所有日志信息。

Declared In

AgoraRtcEngineKit.h

– setLogFileSize:

设置 SDK 输出的单个日志文件大小。

- (int)setLogFileSize:(NSUInteger)fileSizeInKBytes

Parameters

fileSizeInKBytes

单个日志文件的大小,单位为 KB。默认值为 1024 KB。如果你将 fileSizeInKByte 设为 1024 KB,SDK 会最多输出 5 MB 的日志文件。如果你将 fileSizeInKByte 设为 小于 1024 KB,单个日志文件最大仍为 1024 KB。

Return Value

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

Discussion

Deprecated 该方法从 v3.3.0 起废弃,请改用 sharedEngineWithConfig 中的 LogConfig 参数设置单个日志文件大小。

默认情况下,SDK 会生成 agorasdk.logagorasdk_1.logagorasdk_2.logagorasdk_3.logagorasdk_4.log 这 5 个日志文件。每个文件的默认大小为 1024 KB。日志文件为 UTF-8 编码。 最新的日志永远写在 agorasdk.log 中。agorasdk.log 写满后,SDK 会从 1-4 中删除修改时间最早的一个文件,然后将 agorasdk.log 重命名为该文件,并建立新的 agorasdk.log 写入最新的日志。

Note: 如果想要设置日志文件的大小,则需要在 setLogFile 前调用该方法,否则日志会被清空。

Declared In

AgoraRtcEngineKit.h

– createDataStream:reliable:ordered:

创建数据流

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

Parameters

streamId

(输出参数)数据流 ID

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

Return Value

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

Discussion

Deprecated 该方法从 v3.3.0 起废弃,请改用 createDataStream2。

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

Note:

  • 该方法需要在加入频道后调用。
  • 请将 reliableordered 同时设置为 YES 或 NO,暂不支持交叉设置。
  • 创建数据流后,如果你离开频道,SDK 会销毁数据流。

Declared In

AgoraRtcEngineKit.h

– setLocalVoiceChanger:

设置本地语音变声、美音或语聊美声效果。

- (int)setLocalVoiceChanger:(AgoraAudioVoiceChanger)voiceChanger

Parameters

voiceChanger

本地语音的变声、美音或语聊美声效果选项,默认值为 AgoraAudioVoiceChangerOff,即原声。详见 AgoraAudioVoiceChanger

Note:

设置语聊美声效果时,声网推荐使用 AgoraAudioGeneralBeautyVoiceMaleMagnetic 处理男声,使用 AgoraAudioGeneralBeautyVoiceFemaleFreshAgoraAudioGeneralBeautyVoiceFemaleVitality 处理女声,否则音频可能会产生失真。

Return Value

  • 0: 方法调用成功。
  • < 0: 方法调用失败。请检查输入的枚举值是否正确。

Discussion

Deprecated 自 v3.2.0 起废弃,请改用以下方法:

通信场景下的用户或直播场景下的主播均可调用该方法为本地语音设置以下效果。成功设置以后,频道内的所有用户均可听到声音效果。

  • 变声效果:枚举值以 AgoraAudioVoiceChanger 为前缀。效果包括老男孩、小男孩、小女孩、猪八戒、空灵和绿巨人,通常用于语聊场景。
  • 美音效果:枚举值以 AgoraAudioVoiceBeauty 为前缀。效果包括浑厚、低沉、圆润、假音、饱满、清澈、高亢、嘹亮和空旷,通常用于语聊和唱歌场景。
  • 语聊美声效果:枚举值以 AgoraAudioGeneralBeautyVoice 为前缀。效果包括磁性(男)、清新(女)和活力(女),通常用于语聊场景。该功能主要细化了男声和女声各自的特点。

Note:

  • 为达到更好的声音效果,声网推荐在调用该方法前将 setAudioProfileprofile 参数设置为 AgoraAudioProfileMusicHighQuality(4)AgoraAudioProfileMusicHighQualityStereo(5)
  • 该方法对人声的处理效果最佳,声网不推荐调用该方法处理含人声和音乐的音频数据。
  • 该方法不能与 setLocalVoiceReverbPreset 方法一同使用,否则先调的方法会不生效。更多注意事项,详见《设置人声效果》。

Declared In

AgoraRtcEngineKit.h

– setLocalVoiceReverbPreset:

设置本地语音混响(含虚拟立体声效果)。

- (int)setLocalVoiceReverbPreset:(AgoraAudioReverbPreset)reverbPreset

Parameters

reverbPreset

本地语音混响选项,默认值为 AgoraAudioReverbPresetOff,即原声。详见 AgoraAudioReverbPreset

Note:

为达到更好的混响效果,声网推荐使用以 AgoraAudioReverbPresetFx 为前缀的枚举值。

Return Value

  • 0: 方法调用成功。
  • < 0: 方法调用失败。请检查输入的枚举值是否正确。

Discussion

Deprecated 自 v3.2.0 起废弃,请改用 setAudioEffectPresetsetVoiceBeautifierPreset

通信场景下的用户或直播场景下的主播均可调用该方法设置本地语音混响。成功设置以后,频道内的所有用户均可听到声音效果。

Note:

  • 该方法在频道内外均可调用。
  • 当使用以 AgoraAudioReverbPresetFx 为前缀的枚举值时,请确保在调用该方法前将 setAudioProfileprofile 参数设置为 AgoraAudioProfileMusicHighQuality(4)AgoraAudioProfileMusicHighQualityStereo(5),否则该方法设置无效。
  • 当使用 AgoraAudioReverbPresetVirtualStereo 时,声网推荐在调用该方法前将 setAudioProfileprofile 参数设置为 AgoraAudioProfileMusicHighQualityStereo(5)
  • 该方法对人声的处理效果最佳,声网不推荐调用该方法处理含人声和音乐的音频数据。
  • 该方法不能与 setLocalVoiceChanger 方法一同使用,否则先调的方法会不生效。更多注意事项,详见《设置人声效果》。

Declared In

AgoraRtcEngineKit.h

– setEncryptionSecret:

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

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

Parameters

secret

加密密码

Return Value

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

Discussion

Deprecated 自 v3.1.0 起废弃,请改用 enableEncryption

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– setEncryptionMode:

设置内置的加密方案

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

Parameters

encryptionMode

加密方式,有三种选择:

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

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

Return Value

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

Discussion

Deprecated 自 v3.1.0 起废弃,请改用 enableEncryption

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

Note:

  • 在调用本方法前,请先调用 setEncryptionSecret 启用内置加密功能。
  • 请不要在旁路推流时调用此方法。

Declared In

AgoraRtcEngineKit.h

– setLocalRenderMode:

设置本地视图显示模式

- (int)setLocalRenderMode:(AgoraVideoRenderMode)mode

Parameters

mode

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

Return Value

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

Discussion

Deprecated 自 v3.0.0 起废弃,请改用新的 setLocalRenderMode 方法。

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

Declared In

AgoraRtcEngineKit.h

– setRemoteRenderMode:mode:

设置远端视图显示模式

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

Parameters

uid

远端用户 UID

mode

AgoraVideoRenderMode 视图显示模式

Return Value

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

Discussion

Deprecated 自 v3.0.0 起废弃,请改用新的 setRemoteRenderMode 方法。

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

Declared In

AgoraRtcEngineKit.h

– setLocalVideoMirrorMode:

设置本地视频镜像模式

- (int)setLocalVideoMirrorMode:(AgoraVideoMirrorMode)mode

Parameters

mode

视频镜像模式,详见 AgoraVideoMirrorMode

Return Value

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

Discussion

Deprecated 自 v3.0.0 起废弃,请改用 setupLocalVideosetLocalRenderMode 方法。

Warning: 请在调用 setupLocalVideo 方法初始化本地视图后,调用该方法。

Declared In

AgoraRtcEngineKit.h

– enableWebSdkInteroperability:

打开与 Web SDK 的互通

- (int)enableWebSdkInteroperability:(BOOL)enabled

Parameters

enabled

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

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

Return Value

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

Discussion

Deprecated 自 v3.0.0 起废弃。自 v3.0.0 起,SDK 自动开启与 Web SDK 的互通,无需调用该方法开启。

  • 该方法仅适用于直播场景。通信场景默认与 Web SDK 互通,无需调用该方法。
  • 如果有用户通过 Web SDK 加入频道,请确保调用该方法,否则 Web 端用户看 Native 端的画面会是黑屏。

Declared In

AgoraRtcEngineKit.h

– addVideoWatermark:

添加本地视频水印

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

Parameters

watermark

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

Return Value

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

Discussion

Deprecated 自 v2.9.1 起废弃。请改用新的 addVideoWatermark 回调。

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– startEchoTest:

开始语音通话回路测试

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

Parameters

successBlock

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

Return Value

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

Discussion

Deprecated 自 v2.4 起废弃

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– startAudioRecording:quality:

开始客户端录音

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

Parameters

filePath

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

quality

AgoraAudioRecordingQuality

Return Value

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

Discussion

Deprecated 该方法从 v2.9.1 起废弃,其默认录音采样率为 32 kHz,不可修改。请改用新的 startAudioRecordingWithConfig 方法。

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

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

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

Declared In

AgoraRtcEngineKit.h

– setVideoQualityParameters:

设置视频质量偏好选项

- (int)setVideoQualityParameters:(BOOL)preferFrameRateOverImageQuality

Parameters

preferFrameRateOverImageQuality

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

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

Return Value

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

Discussion

Deprecated 自 v2.4 起废弃

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

Declared In

AgoraRtcEngineKit.h

+ sharedEngineWithAppId:error:

初始化 AgoraRtcEngineKit

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

Parameters

AppId

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

errorBlock

AgoraErrorCode

Discussion

Deprecated 从 v2.3 起废弃

Declared In

AgoraRtcEngineKit.h

– pauseAudio

关闭音频

- (int)pauseAudio

Return Value

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

Discussion

Deprecated 从 v2.3 起废弃

See Also

Declared In

AgoraRtcEngineKit.h

– resumeAudio

打开音频

- (int)resumeAudio

Return Value

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

Discussion

Deprecated 从 v2.3 起废弃

See Also

Declared In

AgoraRtcEngineKit.h

– setHighQualityAudioParametersWithFullband:stereo:fullBitrate:

设置音频高音质选项

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

Parameters

fullband

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

  • YES: 开启
  • NO: 关闭
stereo

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

  • YES: 开启
  • NO: 关闭
fullBitrate

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

  • YES: 开启
  • NO: 关闭

Return Value

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

Discussion

Deprecated 从 v2.3 起废弃

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

See Also

Declared In

AgoraRtcEngineKit.h

– setSpeakerphoneVolume:

设置扬声器音量

- (int)setSpeakerphoneVolume:(NSUInteger)volume

Parameters

volume

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

Return Value

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

Discussion

Deprecated 从 v2.3 起废弃

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

See Also

Declared In

AgoraRtcEngineKit.h

– startScreenCapture:withCaptureFreq:bitRate:andRect:

开始屏幕共享

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

Parameters

windowId

用于指定共享窗口:

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

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

bitRate

共享屏幕的码率

rect

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

Return Value

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

Discussion

Deprecated 从 v2.4 起废弃

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

Declared In

AgoraRtcEngineKit.h

– setVideoProfile:swapWidthAndHeight:

设置本地视频属性

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

Parameters

profile

视频属性,详见 AgoraVideoProfile

swapWidthAndHeight

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

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

Return Value

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

Discussion

Deprecated 从 v2.3 起废弃

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

该方法在加入频道前后都能调用。

Note:

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

Declared In

AgoraRtcEngineKit.h

– setVideoResolution:andFrameRate:bitrate:

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

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

Parameters

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 将自动将其调整到合理区间。

Discussion

Deprecated 从 v2.3 起废弃

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

Declared In

AgoraRtcEngineKit.h

– getDeviceId:

获取当前设备名称

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

Parameters

type

设备的类型,包括音、视频采集或播放设备,详见 AgoraMediaDeviceType

Return Value

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

Discussion

Deprecated 从 v2.3 起废弃

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

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

See Also

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

Parameters

soundId

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

Note:

  • 如果你已通过 preloadEffect 将音效加载至内存,确保这里设置的 soundId 与 preloadEffect 设置的 soundId 相同。
  • 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件
  • 如果你需要通过 playEffect 播放在线音效文件,声网建议你将在线音效文件缓存到本地设备,调用 preloadEffect 将缓存的音效文件预加载到内存中,再调用 playEffect 播放音效。否则,可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。
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。取值越小,则音效的音量越低。

Return Value

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

Discussion

Deprecated 从 v2.3 起废弃

See Also

Declared In

AgoraRtcEngineKit.h

+ getMediaEngineVersion

获取媒体引擎版本号

+ (NSString *_Nonnull)getMediaEngineVersion

Return Value

媒体引擎版本号

Discussion

Deprecated 从 v2.3 起废弃

See Also

Declared In

AgoraRtcEngineKit.h

已废弃回调

– audioVolumeIndicationBlock:

提示谁在说话及其音量

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

Parameters

audioVolumeIndicationBlock

回调中包含:

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

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

Discussion

Deprecated 从 v1.1 起废弃

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

Declared In

AgoraRtcEngineKit.h

– firstLocalVideoFrameBlock:

本地首帧视频显示回调

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

Parameters

firstLocalVideoFrameBlock

回调中包含:

  • width: 本地渲染视频的宽 (px)
  • height: 本地渲染视频的高 (px)
  • elapsed: 加入频道开始到该回调触发过去的时间(ms)

Discussion

Deprecated 从 v1.1 起废弃

本地视频首帧显示在本地视图上时,SDK 会触发此回调。

Declared In

AgoraRtcEngineKit.h

– firstRemoteVideoDecodedBlock:

远端首帧视频显示回调

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

Parameters

firstRemoteVideoDecodedBlock

回调中包含:

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

Discussion

Deprecated 从 v1.1 起废弃

Declared In

AgoraRtcEngineKit.h

– firstRemoteVideoFrameBlock:

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

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

Parameters

firstRemoteVideoFrameBlock

回调中包含:

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

Discussion

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

Declared In

AgoraRtcEngineKit.h

– userJoinedBlock:

用户加入回调

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

Parameters

userJoinedBlock

回调中包含:

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

Discussion

Deprecated 从 v1.1 起废弃

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

See Also

Declared In

AgoraRtcEngineKit.h

– userOfflineBlock:

用户离线回调

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

Parameters

userOfflineBlock

回调中包含 uid: 用户 ID

Discussion

Deprecated 从 v1.1 起废弃

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

See Also

Declared In

AgoraRtcEngineKit.h

– userMuteAudioBlock:

用户音频静音回调

- (void)userMuteAudioBlock:(void ( ^ _Nullable ) ( NSUInteger uid , BOOL muted ))userMuteAudioBlock

Parameters

userMuteAudioBlock

回调中包含:

  • uid: 用户 ID
  • muted: 用户是否静音
    • YES: 静音
    • NO: 取消静音

Discussion

Deprecated 从 v1.1 起废弃

提示有用户将通话静音/取消静音。

See Also

Declared In

AgoraRtcEngineKit.h

– userMuteVideoBlock:

用户停止/重新发送视频回调

- (void)userMuteVideoBlock:(void ( ^ _Nullable ) ( NSUInteger uid , BOOL muted ))userMuteVideoBlock

Parameters

userMuteVideoBlock

回调中包含:

  • uid: 用户 ID
  • muted: 用户暂停/恢复发送视频流
    • YES: 该用户已暂停发送其视频流
    • NO: 该用户已恢复发送其视频流

Discussion

Deprecated 从 v1.1 起废弃

See Also

Declared In

AgoraRtcEngineKit.h

– localVideoStatBlock:

本地视频统计回调

- (void)localVideoStatBlock:(void ( ^ _Nullable ) ( NSInteger sentBitrate , NSInteger sentFrameRate ))localVideoStatBlock

Parameters

localVideoStatBlock

回调中包含:

  • sentBitrate: (上次统计后)发送的码率 (Kbps)
  • sentFrameRate: (上次统计后)发送的帧率 (fps)

Discussion

Deprecated 从 v1.1 起废弃

报告更新本地视频统计信息,该回调方法每两秒触发一次。

See Also

Declared In

AgoraRtcEngineKit.h

– remoteVideoStatBlock:

远端视频统计回调

- (void)remoteVideoStatBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger delay , NSInteger receivedBitrate , NSInteger receivedFrameRate ))remoteVideoStatBlock

Parameters

remoteVideoStatBlock

回调中包含:

  • uid: 用户 ID,指定远端视频来自哪个用户
  • delay: 延迟 (ms)
  • receivedBitrate: 上次统计后)接收到的码率 (Kbps)
  • receivedFrameRate: (上次统计后)接收的帧率 (fps)

Discussion

Deprecated 从 v1.1 起废弃

报告更新远端视频统计信息,该回调方法每两秒触发一次。

See Also

Declared In

AgoraRtcEngineKit.h

– remoteAudioStatBlock:

远端音频统计回调

- (void)remoteAudioStatBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger quality , NSInteger networkTransportDelay , NSInteger jitterBufferDelay , NSInteger audioLossRate , NSInteger numChannels , NSInteger receivedSampleRate , NSInteger receivedBitrate , NSInteger totalFrozenTime , NSInteger frozenRate , NSInteger totalActiveTime , NSInteger publishDuration , NSInteger qoeQuality , NSInteger qualityChangedReason ))remoteAudioStatBlock

Parameters

remoteAudioStatBlock

回调中包含:

  • uid: 用户 ID,指定远端音频来自哪个用户。
  • quality: 用户接收到的音频的质量。
  • networkTransportDelay: 音频发送端到接收端的网络延迟。
  • jitterBufferDelay: 接收端到网络抖动缓冲端的网络延迟。
  • audioLossRate: 统计周期内,实际接收到的远端音频流的丢帧率。

Discussion

Deprecated 从 v1.1 起废弃。

报告更新远端音频统计信息,该回调方法每两秒触发一次。

See Also

Declared In

AgoraRtcEngineKit.h

– cameraReadyBlock:

摄像头启用回调

- (void)cameraReadyBlock:(void ( ^ _Nullable ) ( void ))cameraReadyBlock

Discussion

Deprecated 从 v1.1 起废弃

提示已成功打开摄像头,可以开始捕获视频。

Declared In

AgoraRtcEngineKit.h

– connectionLostBlock:

网络连接丢失回调

- (void)connectionLostBlock:(void ( ^ _Nullable ) ( void ))connectionLostBlock

Discussion

Deprecated 从 v1.1 起废弃

该回调方法表示 SDK 与服务器失去了网络连接。

Declared In

AgoraRtcEngineKit.h

– rejoinChannelSuccessBlock:

重新加入频道回调

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

Parameters

rejoinChannelSuccessBlock

回调中包含:

  • channel: 频道名
  • uid: 用户 ID
  • elapsed: 加入延迟(ms)

Discussion

Deprecated 从 v1.1 起废弃

有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法,提示有用户重新加入了频道,且频道 ID 和用户 ID 均已分配。

See Also

Declared In

AgoraRtcEngineKit.h

– rtcStatsBlock:

Rtc Engine 统计数据回调

- (void)rtcStatsBlock:(void ( ^ _Nullable ) ( AgoraChannelStats *_Nonnull stat ))rtcStatsBlock

Parameters

rtcStatsBlock

回调中包含 stat, 详见 AgoraChannelStats

Discussion

Deprecated 从 v1.1 起废弃

该回调定期上报 Rtc Engine 的运行时的状态,每两秒触发一次。

See Also

Declared In

AgoraRtcEngineKit.h

– leaveChannelBlock:

离开频道回调

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

Parameters

leaveChannelBlock

回调中包含 stat, 详见 AgoraChannelStats

Discussion

Deprecated 从 v1.1 起废弃

显示用户离开了频道,提供会话数据信息,包括通话时长和 tx/rx 字节数。

Declared In

AgoraRtcEngineKit.h

– audioQualityBlock:

语音质量回调

- (void)audioQualityBlock:(void ( ^ _Nullable ) ( NSUInteger uid , AgoraNetworkQuality quality , NSUInteger delay , NSUInteger lost ))audioQualityBlock

Parameters

audioQualityBlock

回调中包含:

  • uid: 用户 ID 。每次回调上报一个用户当前的语音质量(不包含自己),不同用户在不同的回调中上报。
  • quality: 网络质量,详见 AgoraNetworkQuality
  • delay: 延迟(ms)
  • lost: 丢包率(百分比)

Discussion

Deprecated 从 v1.1 起废弃

在通话中,该回调方法每两秒触发一次,报告当前通话的(嘴到耳)音频质量。

Declared In

AgoraRtcEngineKit.h

– networkQualityBlock:

频道内网络质量报告回调

- (void)networkQualityBlock:(void ( ^ _Nullable ) ( NSUInteger uid , AgoraNetworkQuality txQuality , AgoraNetworkQuality rxQuality ))networkQualityBlock

Parameters

networkQualityBlock

回调中包含:

  • uid: 用户 ID。表示该回调报告的是持有该ID的用户的网络质量 。当 uid 为 0 时,返回的是本地用户的网络质量
  • txQuality: 该用户的上行网络质量,详见 AgoraNetworkQuality
  • rxQuality: 该用户的下行网络质量,详见 AgoraNetworkQuality

Discussion

Deprecated 从 v1.1 起废弃

该回调每 2 秒触发,向 App 报告频道内所有用户当前的上行、下行网络质量。

See Also

Declared In

AgoraRtcEngineKit.h

– lastmileQualityBlock:

本地用户网络质量回调

- (void)lastmileQualityBlock:(void ( ^ _Nullable ) ( AgoraNetworkQuality quality ))lastmileQualityBlock

Parameters

lastmileQualityBlock

回调中包含 quality: 网络质量的评分,详见 AgoraNetworkQuality

Discussion

Deprecated 从 v1.1 起废弃

报告本地用户的网络质量。该回调方法每两秒触发一次。

See Also

Declared In

AgoraRtcEngineKit.h

– mediaEngineEventBlock:

Media engine 事件回调

- (void)mediaEngineEventBlock:(void ( ^ _Nullable ) ( NSInteger code ))mediaEngineEventBlock

Discussion

Deprecated 从 v1.1 起废弃

Declared In

AgoraRtcEngineKit.h

Extension Methods

– createRtcChannel:

创建并获取一个 AgoraRtcChannel 对象

- (AgoraRtcChannel *_Nullable)createRtcChannel:(NSString *_Nonnull)channelId

Parameters

channelId

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

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

Note

  • 该参数没有默认值,请确保对参数设值。
  • 请勿将该参数设为空字符 “",否则 SDK 会返回 AgoraErrorCodeRefused(-5) 错误码。

Return Value

  • 方法调用成功,返回 AgoraRtcChannel 对象
  • 方法调用失败,返回一个空指针 nil
  • 如果将 channelId 设为空字符 “",返回错误码 AgoraErrorCodeRefused(-5)

Discussion

你可以多次调用该方法,创建多个 AgoraRtcChannel 对象,再调用各 AgoraRtcChannel 对象中的 joinChannelByToken 方法,实现同时加入多个频道。

加入多个频道后,你可以同时订阅各个频道的音、视频流;但是同一时间只能在一个频道发布一路音、视频流。

Declared In

AgoraRtcChannel.h