AgoraRtcEngineKit 类
Inherits from | NSObject |
---|---|
Declared in | AgoraRtcEngineKit.h |
概览
提供所有可供 App 调用的方法
声网通过全球部署的虚拟网络专为 WebRTC 以及移动端到移动端的 App 进行过优化。可以为全世界的音视频通信提供质量保证的体验(QoE)。
AgoraRtcEngineKit 是 Agora SDK 的入口类。它为 App 提供了快速搭建音视频通信的 API。
核心方法
+ sharedEngineWithAppId:delegate:
创建 AgoraRtcEngineKit 实例
+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString *_Nonnull)appId delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate
参数
appId |
Agora 为 app 开发者签发的 App ID,详见获取 App ID。使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 AgoraRtcEngineKit。如需更换 App ID,必须先调用 destroy 销毁当前 AgoraRtcEngineKit,并在 |
---|---|
delegate |
返回
- 方法调用成功,返回一个 AgoraRtcEngineKit 对象。
方法调用失败,返回错误码。
-1
(AgoraErrorCodeFailed
): 一般性的错误(未明确归类)-2
(AgoraErrorCodeInvalidArgument
): 未提供AgoraRtcEngineDelegate
对象-7
(AgoraErrorCodeNotInitialized
): SDK 尚未初始化-101
(AgoraErrorCodeInvalidAppId
):不是有效的 App ID。
详情
AgoraRtcEngineKit 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。
Note
- 请确保在调用其他 API 前先调用该方法创建并初始化 AgoraRtcEngineKit。
- 调用该方法和 sharedEngineWithConfig 均能创建 AgoraRtcEngineKit 实例。该方法与
sharedEngineWithConfig
的区别在于,sharedEngineWithConfig
支持在创建 AgoraRtcEngineKit 实例时指定访问区域。 - 目前 Agora RTC Native SDK 只支持每个 app 创建一个 AgoraRtcEngineKit 实例。
Declared In
AgoraRtcEngineKit.h
+ sharedEngineWithConfig:delegate:
创建 AgoraRtcEngineKit 实例
+ (instancetype _Nonnull)sharedEngineWithConfig:(AgoraRtcEngineConfig *_Nonnull)config delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate
参数
config |
AgoraRtcEngineKit 实例的配置,详见 AgoraRtcEngineConfig 。 |
---|---|
delegate |
返回
- 方法调用成功,返回一个 AgoraRtcEngineKit 对象。
方法调用失败,返回错误码。
-1
(AgoraErrorCodeFailed
): 一般性的错误(未明确归类)-2
(AgoraErrorCodeInvalidArgument
): 未提供AgoraRtcEngineDelegate
对象-7
(AgoraErrorCodeNotInitialized
): SDK 尚未初始化-101
(AgoraErrorCodeInvalidAppId
):不是有效的 App ID。
详情
AgoraRtcEngineKit 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。
Note
- 请确保在调用其他 API 前先调用该方法创建并初始化 AgoraRtcEngineKit。
- 调用该方法和 sharedEngineWithAppId 均能创建 AgoraRtcEngineKit 实例。该方法与
sharedEngineWithAppId
的区别在于,该方法支持在创建 AgoraRtcEngineKit 实例时指定访问区域。 - 目前 Agora RTC Native SDK 只支持每个 app 创建一个 AgoraRtcEngineKit 实例。
Declared In
AgoraRtcEngineKit.h
+ destroy
销毁 AgoraRtcEngineKit
实例
+ (void)destroy
详情
该方法释放 Agora SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信,不需要时则将资源释放出来用于其他操作,该方法适用于此类情况。调用 destroy
方法后,你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能,你必须重新调用
sharedEngineWithAppId 方法创建一个新的 AgoraRtcEngineKit
实例。
Note:
- 该方法为同步调用,需要等待
AgoraRtcEngineKit
实例资源释放后才能执行其他操作,所以我们建议在子线程中调用该方法,避免主线程阻塞。此外,我们不建议 在 SDK 的回调中调用destroy
,否则由于 SDK 要等待回调返回才能回收相关的对象资源,会造成死锁。 - 如需在销毁后再次创建
AgoraRtcEngineKit 实例,需要等待
destroy` 方法执行结束后再创建实例。
Declared In
AgoraRtcEngineKit.h
– setChannelProfile:
该方法用于设置 AgoraRtcEngineKit 频道的使用场景。
- (int)setChannelProfile:(AgoraChannelProfile)profile
参数
profile |
频道使用场景。详见 AgoraChannelProfile。 |
---|
返回
0
(AgoraErrorCodeNoError
): 方法调用成功<
0
: 方法调用失败-2
(AgoraErrorCodeInvalidArgument
): 参数无效-7
(AgoraErrorCodeNotInitialized
): SDK 尚未初始化
详情
AgoraRtcEngineKit 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。
Note:
- 为保证实时音视频质量,我们建议相同频道内的用户使用同一种频道场景。
- 该方法必须在加入频道前调用,进入频道后无法再设置频道场景。
- 不同的频道场景下,SDK 的默认音频路由和默认视频编码码率是不同的,详见 setDefaultAudioRouteToSpeakerphone 和 setVideoEncoderConfiguration 中的说明。
Declared In
AgoraRtcEngineKit.h
– setClientRole:
设置直播场景下的用户角色。
- (int)setClientRole:(AgoraClientRole)role
参数
role |
直播场景里的用户角色,详见 AgoraClientRole。 |
---|
返回
- 0(
AgoraErrorCodeNoError
): 方法调用成功。 < 0: 方法调用失败。
- -1(
AgoraErrorCodeFailed
): 一般性的错误(未明确归类)。 - -2(
AgoraErrorCodeInvalidArgument
): 参数无效。 - -7(
AgoraErrorCodeNotInitialized
): SDK 尚未初始化。 -5 (
AgoraErrorCodeRefused
): 调用被拒绝。在多频道场景中, 如果你已在一个频道中进行如下设置,则用户在另一个频道内切换角色为主播时会返回该错误码:- 调用带
options
参数的 joinChannelByToken, 并使用默认设置publishLocalAudio = YES
或publishLocalVideo = YES
。 - 调用
setClientRole
,并设置用户角色为主播。 - 调用
muteLocalAudioStream(NO)
或muteLocalVideoStream(NO)
。
- 调用带
- -1(
详情
调用 setChannelProfile(AgoraChannelProfileLiveBroadcasting)
后,SDK 会默认设置用户角色为观众,你可以调用 setClientRole
设置用户角色为主播。
该方法在加入频道前后均可调用。如果你在加入频道后调用该方法切换用户角色,调用成功后,SDK 会自动进行如下操作:
- 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
- 本地触发 didClientRoleChanged。
- 远端触发 didJoinedOfUid 或 didOfflineOfUid(AgoraUserOfflineReasonBecomeAudience)。
Note: 该方法仅适用于直播场景。
Declared In
AgoraRtcEngineKit.h
– setClientRole:options:
设置直播场景下的用户角色。
- (int)setClientRole:(AgoraClientRole)role options:(AgoraClientRoleOptions *_Nullable)options
参数
role |
直播场景中的用户角色,详见 AgoraClientRole。 |
---|---|
options |
用户具体设置,包含用户级别,详见 AgoraClientRoleOptions。 |
返回
- 0(
AgoraErrorCodeNoError
): 方法调用成功。 < 0: 方法调用失败。
- -1(
AgoraErrorCodeFailed
): 一般性的错误(未明确归类)。 - -2(
AgoraErrorCodeInvalidArgument
): 参数无效。 - -7(
AgoraErrorCodeNotInitialized
): SDK 尚未初始化。 -5 (
AgoraErrorCodeRefused
): 调用被拒绝。在多频道场景中, 如果你已在一个频道中进行如下设置,则用户在另一个频道内切换角色为主播时会返回该错误码:- 调用带
options
参数的 joinChannelByToken, 并使用默认设置publishLocalAudio = YES
或publishLocalVideo = YES
。 - 调用
setClientRole
,并设置用户角色为主播。 - 调用
muteLocalAudioStream(NO)
或muteLocalVideoStream(NO)
。
- 调用带
- -1(
Availability
v3.2.0
调用 setChannelProfile(AgoraChannelProfileLiveBroadcasting)
后,SDK 会默认设置用户角色为观众,你可以调用 setClientRole
设置用户角色为主播。
该方法在加入频道前后均可调用。如果你在加入频道后调用该方法切换用户角色,调用成功后,SDK 会自动进行如下操作:
- 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
- 本地触发 didClientRoleChanged。
- 远端触发 didJoinedOfUid 或 didOfflineOfUid(AgoraUserOfflineReasonBecomeAudience)。
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
参数
token |
在你服务器上生成的 Token。详见使用 Token 鉴权。 |
---|---|
channelId |
标识通话频道的字符串,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
|
info |
(非必选项) 开发者需加入的任何附加信息。一般可设置为空字符串,或频道相关信息。该信息不会传递给频道内的其他用户。 |
uid |
用户 ID,32 位无符号整数。建议设置范围:1到 (232-1),并保证唯一性。如果不填或设为 0,SDK 会自动分配一个,并在 joinSuccessBlock 回调方法中返回,App 层必须记住该返回值并维护,SDK 不对该返回值进行维护。 |
joinSuccessBlock |
成功加入频道回调。joinSuccessBlock 优先级高于 didJoinChannel,2 个同时存在时,didJoinChannel 会被忽略。 需要有 didJoinChannel 回调时,请将 joinSuccessBlock 设置为 nil 。 |
返回
0
(AgoraErrorCodeNoError
): 方法调用成功<
0
: 方法调用失败-2
(AgoraErrorCodeInvalidArgument
): 参数无效。-3
(AgoraErrorCodeNotReady
): SDK 初始化失败,请尝试重新初始化 SDK。-5
(AgoraErrorCodeRefused
):调用被拒绝。可能有如下两个原因:- 已经创建了一个同名的
AgoraRtcChannel
频道。 - 已经通过
AgoraRtcChannel
加入了一个频道,并在该AgoraRtcChannel
频道中发布了音视频流。由于通过AgoraRtcEngineKit
加入频道会默认发布音视频流,而 SDK 不支持同时在两个频道发布音视频流,因此会报错。
- 已经创建了一个同名的
-7
(AgoraErrorCodeNotInitialized
): SDK 尚未初始化,就调用其 API。请确认在调用 API 之前已创建AgoraRtcEngineKit
并完成初始化。
详情
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 App 是不能互通的。如果已在通话中,用户必须调用 leaveChannel 退出当前通话,才能进入下一个频道。SDK 在通话中使用 iOS 系统的 AVAudioSession 共享对象进行采集和播放, App 对该对象的操作可能会影响 SDK 的音频相关功能。
调用该 API 后会触发 joinSuccessBlock 或 didJoinChannel 回调。block 比 delegate 优先级高,如果两种回调都实现了,只有 block 会触发。
我们建议你将 joinSuccessBlock 设置为 nil,使用 delegate 回调。
加入频道后,本地会触发 didJoinChannel 回调;通信场景下的用户和直播场景下的主播加入频道后,远端会触发 didJoinedOfUid 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute
方法实现。
在网络状况不理想的情况下,客户端可能会与 Agora 的服务器失去连接;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
参数
token |
在 app 服务端生成的用于鉴权的 Token。详见服务端生成 Token。 |
---|---|
channelId |
标识通话的频道名称,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
|
info |
(非必选项) 开发者需加入的任何附加信息。一般可设置为空字符串,或频道相关信息。该信息不会传递给频道内的其他用户。 |
uid |
(非必选项)用户 ID,32 位无符号整数。建议设置范围:1 到 (232-1),并保证唯一性。如果不指定(即设为 0),SDK 会自动分配一个,并在
Note: 频道内每个用户的 UID 必须是唯一的。如果想要从不同的设备同时接入同一个频道,请确保每个设备上使用的 UID 是不同的。 |
options |
频道媒体设置选项:AgoraRtcChannelMediaOptions 。 |
返回
0
(AgoraErrorCodeNoError
): 方法调用成功。<
0
: 方法调用失败。-2
(AgoraErrorCodeInvalidArgument
): 参数无效。-3
(AgoraErrorCodeNotReady
): SDK 初始化失败,请尝试重新初始化 SDK。-5
(AgoraErrorCodeRefused
): 调用被拒绝。可能有如下两个原因:- 已经创建了一个同名的
AgoraRtcChannel
频道。 - 已经通过
AgoraRtcChannel
加入了一个频道,并在该AgoraRtcChannel
频道中发布了音视频流。由于通过AgoraRtcEngineKit
加入频道会默认发布音视频流,而 SDK 不支持同时在两个频道发布音视频流,因此会报错。
- 已经创建了一个同名的
-7
(AgoraErrorCodeNotInitialized
): SDK 尚未初始化,就调用其 API。请确认在调用 API 之前已创建AgoraRtcEngineKit
并完成初始化。
Availability
v3.3.0
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。使用不同 App ID 的 App 是不能互通的。
如果已在通话中,用户必须调用 leaveChannel 退出当前通话,才能进入下一个频道。
成功调用该方法加入频道后,本地会触发 didJoinChannel 回调; 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 didJoinedOfUid 回调。
在网络状况不理想的情况下,客户端可能会与 Agora 的服务器失去连接;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
参数
userAccount |
用户 User Account。该参数为必需,最大不超过 255 字节,不可为
|
---|---|
token |
在你服务器上生成的 Token。详见使用 Token 鉴权。 |
channelId |
标识通话频道的字符串,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
|
joinSuccessBlock |
成功加入频道回调。joinSuccessBlock 优先级高于 didJoinChannel,2 个同时存在时,didJoinChannel 会被忽略。 需要有 didJoinChannel 回调时,请将 joinSuccessBlock 设置为 nil 。 |
返回
- 0: 方法调用成功
< 0: 方法调用失败
- AgoraErrorCodeInvalidToken(110):不是有效的 Token。请更换有效的 Token 重新加入频道。建议你进行如下检查:
- 检查生成 Token 的 uid 与
joinChannelByUserAccount
方法中的 uid 是否一致 - 检查 Token 的格式是否有效
- 检查 Token 与 App ID 是否匹配
- 检查生成 Token 的 uid 与
- AgoraErrorCodeInvalidToken(110):不是有效的 Token。请更换有效的 Token 重新加入频道。建议你进行如下检查:
详情
该方法允许本地用户使用 User Account 加入频道。成功加入频道后,会触发以下回调:
- 本地:didRegisteredLocalUser 和 didJoinChannel 回调
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会依次触发 didJoinedOfUid 和 didUpdatedUserInfo 回调
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute
方法实现。
Note
- 请确保在使用 String 型用户名前阅读如何使用 String 型用户 ID,了解使用限制及实现方法。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Agora 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
参数
userAccount |
用户 User Account。该参数为必需,最大不超过 255 字节,不可为
|
---|---|
token |
在 app 服务端生成的用于鉴权的 Token。详见服务端生成 Token。 |
channelId |
标识频道的频道名,最大不超过 64 字节。以下为支持的字符集范围(共 89 个字符):
|
options |
频道媒体设置选项:AgoraRtcChannelMediaOptions 。 |
返回
- 0: 方法调用成功。
< 0: 方法调用失败。
AgoraErrorCodeInvalidArgument
(-2)AgoraErrorCodeNotReady
(-3)AgoraErrorCodeRefused
(-5)AgoraErrorCodeSDKNotInitialized
(-7)
Availability
v3.3.0
该方法允许本地用户使用 User Account 加入频道。
成功加入频道后,会触发以下回调:
- 本地: didRegisteredLocalUser 和 didJoinChannel 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会依次触发 didJoinedOfUid 和 didUpdatedUserInfo 回调。
Note
- 请确保在使用 String 型用户名前阅读如何使用 String 型用户 ID,了解使用限制及实现方法。
- 相比 joinChannelByUserAccount1,
该方法加了
options
参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流, 因此会产生用量并影响计费。如果想取消订阅,可以通过设置options
参数或相应的mute
方法实现。 - 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Agora Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
Declared In
AgoraRtcEngineKit.h
– registerLocalUserAccount:appId:
注册本地用户 User Account
- (int)registerLocalUserAccount:(NSString *_Nonnull)userAccount appId:(NSString *_Nonnull)appId
参数
userAccount |
用户 User Account。该参数为必填,最大不超过 255 字节,不可填
|
---|---|
appId |
你的项目在 Agora 控制台注册的 App ID |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法为本地用户注册一个 User Account。注册成功后,该 User Account 即可标识该本地用户的身份,用户可以使用它加入频道。成功注册 User Account 后,本地会触发 didRegisteredLocalUser 回调,告知本地用户的 UID 和 User Account。
该方法为可选。如果你希望用户使用 User Account 加入频道,可以选用以下两种方式:
- 先调用 registerLocalUserAccount 方法注册 User Account,再调用 joinChannelByUserAccount 方法加入频道
- 直接调用 joinChannelByUserAccount 方法加入频道
两种方式的区别在于,提前调用 registerLocalUserAccount,可以缩短使用 joinChannelByUserAccount 进入频道的时间。
Note:
- userAccount 不能为空,否则该方法不生效。
- 请确保在该方法中设置的 userAccount 在频道中的唯一性。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Agora Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
Declared In
AgoraRtcEngineKit.h
– getUserInfoByUserAccount:withError:
通过 User Account 获取用户信息
- (AgoraUserInfo *_Nullable)getUserInfoByUserAccount:(NSString *_Nonnull)userAccount withError:(AgoraErrorCode *_Nullable)error
参数
userAccount |
用户 User Account。该参数为必填。 |
---|---|
error |
AgoraErrorCode 的指针,可以为空。 |
返回
一个包含了用户 User Account 和 UID 的 AgoraUserInfo 对象
详情
远端用户加入频道后,SDK 会获取到该用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的映射表,并在本地触发 didUpdatedUserInfo 回调。
收到这个回调后,你可以调用该方法,通过传入 User Account 获取包含了指定用户 UID 的 AgoraUserInfo 对象。
Declared In
AgoraRtcEngineKit.h
– getUserInfoByUid:withError:
通过 UID 获取用户信息
- (AgoraUserInfo *_Nullable)getUserInfoByUid:(NSUInteger)uid withError:(AgoraErrorCode *_Nullable)error
参数
uid |
用户 UID。该参数为必填 |
---|---|
error |
AgoraErrorCode 的指针,可以为空。 |
返回
一个包含了用户 User Account 和 UID 的 AgoraUserInfo 对象
详情
远端用户加入频道后,SDK 会获取到该用户的 UID 和 User Account,然后缓存一个包含了用户 UID 和 User Account 的映射表,并在本地触发 didUpdatedUserInfo 回调。
收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 AgoraUserInfo 对象。
Declared In
AgoraRtcEngineKit.h
– switchChannelByToken:channelId:joinSuccess:
快速切换直播频道。
- (int)switchChannelByToken:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId joinSuccess:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))joinSuccessBlock
参数
token |
在你服务器上生成的 Token。详见使用 Token 鉴权。 |
---|---|
channelId |
标识频道的频道名,最大不超过 64 字节。以下为支持的字符集范围(共 89 个字符):
|
joinSuccessBlock |
成功加入频道回调。 |
返回
0
(AgoraErrorCodeNoError
): 方法调用成功<
0
: 方法调用失败-1
(AgoraErrorCodeFailed
): 一般性的错误(未明确归类)-2
(AgoraErrorCodeInvalidArgument
): 参数无效-5
(AgoraErrorCodeRefused
): 调用被拒绝。可能因为用户角色不是观众-7
(AgoraErrorCodeNotInitialized
): SDK 尚未初始化-102
(AgoraErrorCodeInvalidChannelId
):频道名无效。请更换有效的频道名-113
(AgoraErrorCodeNotInChannel
):用户不在频道内
详情
当直播频道中的观众想从一个频道切换到另一个频道时,可以调用该方法,实现快速切换。
成功调用该方切换频道后,本地会先收到离开原频道的回调 didLeaveChannelWithStats,再收到成功加入新频道的回调 didJoinChannel。
用户成功切换频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute
方法实现。
Note: 该方法仅适用直播频道中的观众用户。
Declared In
AgoraRtcEngineKit.h
– switchChannelByToken:channelId:options:
快速切换直播频道,并设置是否自动订阅目标频道的音频流或视频流。
- (int)switchChannelByToken:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId options:(AgoraRtcChannelMediaOptions *_Nonnull)options
参数
token |
在 app 服务端生成的用于鉴权的 Token。详见服务端生成 Token。 |
---|---|
channelId |
标识频道的频道名,最大不超过 64 字节。以下为支持的字符集范围(共 89 个字符):
|
options |
频道媒体设置选项:AgoraRtcChannelMediaOptions 。 |
返回
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
参数
leaveChannelBlock |
成功离开频道的回调,提供通话相关的统计信息,详见 AgoraChannelStats |
---|
返回
0
(AgoraErrorCodeNoError
): 方法调用成功<
0
: 方法调用失败-1
(AgoraErrorCodeFailed
): 一般性的错误(未明确归类)-2
(AgoraErrorCodeInvalidArgument
): 参数无效-7
(AgoraErrorCodeNotInitialized
): SDK 尚未初始化
详情
离开频道,即挂断或退出通话。
当调用 joinChannelByToken 方法后,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。 不管当前是否在通话中,都可以调用本方法,没有副作用。该方法会把会话相关的所有资源释放掉。该方法是异步操作,调用返回时并没有真正退出频道。
成功调用该方法离开频道后,本地会触发 didLeaveChannelWithStats 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 didOfflineOfUid(AgoraUserOfflineReasonBecomeAudience) 回调。
Note:
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 didLeaveChannelWithStats 回调。
- 如果你在旁路推流时调用本方法, SDK 将自动调用 removePublishStreamUrl 方法。
- 在调用本方法时,iOS 默认情况下 SDK 会停用 audio session,可能会对其他应用程序造成影响。如果想改变这种默认行为,可以通过setAudioSessionOperationRestriction 方法设置
AgoraAudioSessionOperationRestrictionDeactivateSession
,这样在 leaveChannel 时,SDK 不会停用 audio session。
Declared In
AgoraRtcEngineKit.h
– renewToken:
更新 Token
- (int)renewToken:(NSString *_Nonnull)token
参数
token |
新的 Token |
---|
返回
0
(AgoraErrorCodeNoError
): 方法调用成功<
0
: 方法调用失败-1
(AgoraErrorCodeFailed
): 一般性的错误(未明确归类)-2
(AgoraErrorCodeInvalidArgument
): 参数无效-7
(AgoraErrorCodeNotInitialized
): SDK 尚未初始化
详情
该方法用于更新 Token。如果启用了 Token 机制,过一段时间后使用的 Token 会失效。当以下任意一种情况发生时:
- tokenPrivilegeWillExpire 回调。
- connectionChangedToState 回调的
reason
参数报告 AgoraConnectionChangedTokenExpired(9)。
App 应重新获取 Token,然后调用该 API 更新 Token,否则 SDK 无法和服务器建立连接。
Declared In
AgoraRtcEngineKit.h
– getConnectionState
获取当前网络连接状态
- (AgoraConnectionStateType)getConnectionState
返回
当前的网络连接状态,详见 AgoraConnectionStateType。
详情
该方法在加入频道前后都能调用。
Declared In
AgoraRtcEngineKit.h
– startChannelMediaRelay:
开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
- (int)startChannelMediaRelay:(AgoraChannelMediaRelayConfiguration *_Nonnull)config
参数
config |
跨频道媒体流转发参数配置: AgoraChannelMediaRelayConfiguration 类。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
成功调用该方法后,SDK 会触发 channelMediaRelayStateDidChange 和 didReceiveChannelMediaRelayEvent 回调,并在回调中报告当前的跨频道媒体流转发状态和事件。
- 如果
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
参数
config |
跨频道媒体流转发参数配置: AgoraChannelMediaRelayConfiguration 类。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
成功调用该方法后,SDK 会触发 didReceiveChannelMediaRelayEvent 回调,并在回调中报告状态码 AgoraChannelMediaRelayEventUpdateDestinationChannel(7)。
Note
- 请在 startChannelMediaRelay 方法后调用该方法,更新媒体流转发的频道。
- 跨频道媒体流转发最多支持 4 个目标频道。如果直播间里已经有 4 个频道了,你可以在调用该方法之前,调用 AgoraChannelMediaRelayConfiguration 中的
removeDestinationInfoForChannelName
方法移除不需要的频道。
Declared In
AgoraRtcEngineKit.h
– stopChannelMediaRelay
停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。
- (int)stopChannelMediaRelay
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
成功调用该方法后,SDK 会触发 channelMediaRelayStateDidChange 回调。如果报告 AgoraChannelMediaRelayStateIdle(0) 和 AgoraChannelMediaRelayErrorNone(0),则表示已停止转发媒体流。
Note: 如果该方法调用不成功,SDK 会触发 channelMediaRelayStateDidChange 回调,并报告错误码 AgoraChannelMediaRelayErrorServerNoResponse(2) 或 AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8)。你可以调用 leaveChannel 方法离开频道,跨频道媒体流转发会自动停止。
Declared In
AgoraRtcEngineKit.h
– setCloudProxy:
设置 Agora 云代理服务。
- (int)setCloudProxy:(AgoraCloudProxyType)proxyType
参数
proxyType |
云代理类型,详见 AgoraCloudProxyType 。该参数为必填参数,如果你不赋值,SDK 会报错。 |
---|
返回
- 0: 方法调用成功。
< 0: 方法调用失败。
-2(AgoraErrorCodeInvalidArgument)
: 传入的参数无效。-7(AgoraErrorCodeNotInitialized)
: SDK 尚未初始化。
Availability
v3.3.0
当用户防火墙限制 IP 和端口号时,你需要参考《使用云代理》开放相应 IP 和端口号,然后调用该方法开启云代理,并将 proxyType
参数设置为
AgoraUdpProxy(1)
,即 UDP 协议的云代理。
成功连接云代理后,SDK 会触发 connectionChangedToState(AgoraConnectionStateConnecting, AgoraConnectionChangedSettingProxyServer) 回调。
如果你想关闭已设置的云代理,请调用 setCloudProxy(AgoraNoneProxy)
。如果你想更改已设置的云代理类型,请先调用 setCloudProxy(AgoraNoneProxy)
,
再调用 setCloudProxy
并传入你期望的 proxyType
值。
Note
- Agora 推荐你在频道外调用该方法。
- 使用 UDP 协议的云代理时,推流到 CDN 和跨频道媒体流转发功能不可用。
Declared In
AgoraRtcEngineKit.h
音频核心方法
– enableAudio
启用音频模块
- (int)enableAudio
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
本方法可以启用音频模块。(音频模块默认为开启状态)
Note:
该方法设置的是音频模块为开启状态,在频道内和频道外均可调用,且在 leaveChannel 后仍然有效。
该方法开启整个音频模块,响应速度较慢,因此 Agora 建议使用如下方法来控制音频模块:
- enableLocalAudio:是否启动麦克风采集并创建本地音频流
- muteLocalAudioStream:是否发布本地音频流
- muteRemoteAudioStream:是否接收并播放远端音频流
- muteAllRemoteAudioStreams:是否接收并播放所有远端音频流
Declared In
AgoraRtcEngineKit.h
– disableAudio
关闭音频模块
- (int)disableAudio
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
Note:
该方法设置的是音频模块为禁用状态,在频道内和频道外均可调用,且在 leaveChannel 后仍然有效。
该方法关闭整个音频模块,响应速度较慢,因此 Agora 建议使用如下方法来控制音频模块:
- enableLocalAudio:是否启动麦克风采集并创建本地音频流
- muteLocalAudioStream:是否发布本地音频流
- muteRemoteAudioStream:是否接收并播放远端音频流
- muteAllRemoteAudioStreams:是否接收并播放所有远端音频流
Declared In
AgoraRtcEngineKit.h
– setAudioProfile:scenario:
设置音频编码配置
- (int)setAudioProfile:(AgoraAudioProfile)profile scenario:(AgoraAudioScenario)scenario
参数
profile |
设置采样率,码率,编码模式和声道数: AgoraAudioProfile。 |
---|---|
scenario |
设置音频应用场景,详细定义见 AgoraAudioScenario。不同的音频场景下,设备的音量类型不同。详见 如何区分媒体音量和通话音量。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
Note:
- 该方法需要在 joinChannelByToken 之前设置好,joinChannelByToken 之后设置不生效
- 通信场景下,该方法设置
profile
生效,设置scenario
不生效 - 通信和直播场景下,音质(码率)会有网络自适应的调整,通过该方法设置的是一个最高码率
- 在有高音质需求的场景(例如音乐教学场景)中,建议将
profile
设置为AgoraAudioProfileMusicHighQuality(4)
,scenario
设置为AgoraAudioScenarioGameStreaming(3)
Declared In
AgoraRtcEngineKit.h
– adjustRecordingSignalVolume:
调节麦克风采集信号音量
- (int)adjustRecordingSignalVolume:(NSInteger)volume
参数
volume |
麦克风采集信号音量。取值范围为 [0,100]。默认值为 100,表示原始音量。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法在加入频道前后都能调用。
Declared In
AgoraRtcEngineKit.h
– adjustLoopbackRecordingSignalVolume:
调节声卡采集信号音量
- (int)adjustLoopbackRecordingSignalVolume:(NSInteger)volume
参数
volume |
声卡采集信号音量。取值范围为 [0,100]。默认值为 100,表示原始音量。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
Note: 该方法仅适用于 macOS。
Declared In
AgoraRtcEngineKit.h
– adjustPlaybackSignalVolume:
调节本地播放的所有远端用户的信号音量
- (int)adjustPlaybackSignalVolume:(NSInteger)volume
参数
volume |
播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法在加入频道前后都能调用。
Note
- 该方法调节的是本地播放的所有远端用户混音后的音量。
- 从 v2.3.2 开始,静音本地音频需同时调用
adjustPlaybackSignalVolume
和 adjustAudioMixingPlayoutVolume 方法,并将volume
参数设置为 0。
Declared In
AgoraRtcEngineKit.h
– enableAudioVolumeIndication:smooth:report_vad:
启用用户音量提示
- (int)enableAudioVolumeIndication:(NSInteger)interval smooth:(NSInteger)smooth report_vad:(BOOL)report_vad
参数
interval |
指定音量提示的时间间隔:
|
---|---|
smooth |
指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3,数字越大,波动越灵敏;数字越小,波动越平滑。 |
report_vad |
|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。启用该方法后,只要频道内有发流用户,SDK 会在加入频道后按设置的时间间隔触发 reportAudioVolumeIndicationOfSpeakers 回调。
该方法在加入频道前后都能调用。
Declared In
AgoraRtcEngineKit.h
– enableLocalAudio:
开关本地音频采集
- (int)enableLocalAudio:(BOOL)enabled
参数
enabled |
|
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
当 App 加入频道时,它的语音功能默认是开启的。该方法可以关闭或重新开启本地语音功能,即停止或重新开始本地音频采集。该方法在加入频道前后都能调用。
该方法不影响接收远端音频流,enableLocalAudio(NO)
适用于只听不发的用户场景。
语音功能关闭或重新开启后,会收到 localAudioStateChange 回调并报告 AgoraAudioLocalStateStopped(0)
或 AgoraAudioLocalStateRecording(1)
。
Note:
该方法与 muteLocalAudioStream 的区别在于:
- enableLocalAudio:开启或关闭本地语音采集及处理。使用
enableLocalAudio
关闭或开启本地采集后,本地听远端播放会有短暂中断。 - muteLocalAudioStream:停止或继续发送本地音频流。
Declared In
AgoraRtcEngineKit.h
– muteLocalAudioStream:
取消或恢复发布本地音频流。
- (int)muteLocalAudioStream:(BOOL)mute
参数
mute |
是否取消发布本地音频流:
|
---|
返回
- 0: 方法调用成功。
< 0: 方法调用失败。
-5
(AgoraErrorCodeRefused
): 调用被拒绝。
详情
自 v3.4.5 起,该方法仅设置用户在 AgoraRtcEngineKit
频道中的音频发布状态。
成功调用该方法后,远端会触发 didAudioMuted 回调。
同一时间,本地的音视频流只能发布到一个频道。如果你创建了多个频道,请确保你只在一个频道中调用
muteLocalAudioStream(NO)
,否则方法会调用失败并返回 -5 (AgoraErrorCodeRefused)
。
Note:
- 该方法不会改变音频采集设备的使用状态。
- 该方法的调用是否生效受 joinChannelByToken 和 setClientRole 方法的影响,详见《设置发布状态》。
Declared In
AgoraRtcEngineKit.h
– muteRemoteAudioStream:mute:
取消或恢复订阅指定远端用户的音频流。
- (int)muteRemoteAudioStream:(NSUInteger)uid mute:(BOOL)mute
参数
uid |
指定用户的用户 ID。 |
---|---|
mute |
是否取消订阅指定远端用户的音频流。
|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
Note
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见《设置订阅状态》。
Declared In
AgoraRtcEngineKit.h
– muteAllRemoteAudioStreams:
取消或恢复订阅所有远端用户的音频流。
- (int)muteAllRemoteAudioStreams:(BOOL)mute
参数
mute |
是否取消订阅所有远端用户的音频流。
|
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流, 包括在调用该方法后加入频道的用户的音频流。
Note
- 该方法需要在加入频道后调用。
- 自 v3.3.0 起,该方法包含了
setDefaultMuteAllRemoteAudioStreams
的功能。Agora 建议不要一起调用
muteAllRemoteAudioStreams
和setDefaultMuteAllRemoteAudioStreams
,否则设置可能会不生效。详见《设置订阅状态》。
Declared In
AgoraRtcEngineKit.h
– adjustUserPlaybackSignalVolume:volume:
调节本地播放的指定远端用户的信号音量。
- (int)adjustUserPlaybackSignalVolume:(NSUInteger)uid volume:(int)volume
参数
uid |
远端用户 ID,需和远端用户加入频道时用的 uid 一致。 |
---|---|
volume |
播放音量,取值范围为 [0,100]。
|
详情
加入频道后,你可以多次调用该方法调节不同远端用户在本地播放的音量,或对某个远端用户在本地播放的音量调节多次。
Note
- 该方法要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
- 该方法每次只能调整一位远端用户在本地播放的音量。若需调整多位远端用户在本地播放的音量,则需多次调用该方法。
Declared In
AgoraRtcEngineKit.h
视频核心方法
– enableVideo
启用视频模块
- (int)enableVideo
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法用于打开视频模式。可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启视频模式,在通话中调用则由音频模式切换为视频模式。调用 disableVideo 方法可关闭视频模式。
成功调用该方法后,远端会触发 didVideoEnabled(YES) 回调。
Note:
- 该方法设置的是内部引擎为启用状态,在 leaveChannel 后仍然有效。
该方法重置整个引擎,响应速度较慢,因此 Agora 建议使用如下方法来控制视频模块:
- enableLocalVideo:是否启动摄像头采集并创建本地视频流
- muteLocalVideoStream:是否发布本地视频流
- muteRemoteVideoStream:是否接收并播放远端视频流
- muteAllRemoteVideoStreams:是否接收并播放所有远端视频流
Declared In
AgoraRtcEngineKit.h
– disableVideo
关闭视频模块
- (int)disableVideo
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法用于关闭视频。可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启纯音频模式,在通话中调用则由视频模式切换为纯音频模式。调用 enableVideo 方法可开启视频模式。
成功调用该方法后,远端会触发 didVideoEnabled(NO) 回调。
Note:
该方法设置的是内部引擎为禁用状态,在 leaveChannel 后仍然有效。
该方法重置整个引擎,响应速度较慢,因此 Agora 建议使用如下方法来控制视频模块:
- enableLocalVideo:是否启动摄像头采集并创建本地视频流
- muteLocalVideoStream:是否发布本地视频流
- muteRemoteVideoStream:是否接收并播放远端视频流
- muteAllRemoteVideoStreams:是否接收并播放所有远端视频流
Declared In
AgoraRtcEngineKit.h
– setVideoEncoderConfiguration:
设置视频编码配置
- (int)setVideoEncoderConfiguration:(AgoraVideoEncoderConfiguration *_Nonnull)config
参数
config |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法设置视频编码配置。每个配置对应一套视频参数,如分辨率、帧率、码率、视频方向等。 所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时,会取最接近最大值的那个值。
如果加入频道后不需要重新设置视频编码配置,Agora 建议在 enableVideo 之前调用该方法,可以加快首帧出图时间。
该方法在加入频道前后都能调用。
Note:
在 v2.3.0 版本中,如下接口已废弃,Agora 不再推荐使用:
Declared In
AgoraRtcEngineKit.h
– setupLocalVideo:
初始化本地视图。
- (int)setupLocalVideo:(AgoraRtcVideoCanvas *_Nullable)local
参数
local |
通过 AgoraRtcVideoCanvas 设置本地视频显示属性。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法初始化本地视图并设置本地用户视频显示信息,只影响本地用户看到的视频画面,不影响本地发布视频。调用该方法绑定本地视频流的显示视窗(view
),并设置本地用户视图的渲染模式和镜像模式。在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入频道。退出频道后,绑定仍然有效,如果需要解除绑定,可以指定空 (nil
) view 调用本方法。
该方法在加入频道前后都能调用。
Note
如果你希望在通话中更新本地用户视图的渲染或镜像模式,请使用 setLocalRenderMode 方法。
Declared In
AgoraRtcEngineKit.h
– setupRemoteVideo:
初始化远端用户视图。
- (int)setupRemoteVideo:(AgoraRtcVideoCanvas *_Nonnull)remote
参数
remote |
通过 AgoraRtcVideoCanvas 设置远端视频显示属性。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。调用该接口时需要指定远端用户的 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
参数
renderMode |
本地视图的渲染模式,详见 AgoraVideoRenderMode |
---|---|
mirrorMode |
本地视图的镜像模式,详见 AgoraVideoMirrorMode Note 如果你使用前置摄像头,默认启动本地用户视图镜像模式;如果你使用后置摄像头,默认关闭本地视图镜像模式。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
自从 v3.0.0
初始化本地用户视图后,你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面,不影响本地发布视频。
Note
- 请在调用 setupLocalVideo 方法初始化本地视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新本地用户视图的显示模式。
Declared In
AgoraRtcEngineKit.h
– setRemoteRenderMode:renderMode:mirrorMode:
更新远端视图显示模式。
- (int)setRemoteRenderMode:(NSUInteger)uid renderMode:(AgoraVideoRenderMode)renderMode mirrorMode:(AgoraVideoMirrorMode)mirrorMode
参数
uid |
远端用户 ID。 |
---|---|
renderMode |
远端用户视图的渲染模式,详见 AgoraVideoRenderMode 。 |
mirrorMode |
远端用户视图的镜像模式,详见 AgoraVideoMirrorMode 。 Note 默认关闭远端用户的镜像模式。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
自从 v3.0.0
初始化远端用户视图后,你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。
Note
- 请在调用 setupRemoteVideo 方法初始化远端视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
Declared In
AgoraRtcEngineKit.h
– startPreview
开启视频预览
- (int)startPreview
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法用于在进入频道前启动本地视频预览。本地预览默认开启镜像功能。
调用该 API 前,必须
- 调用 setupLocalVideo 设置预览窗口及属性
- 调用 enableVideo 开启视频功能
启用了本地视频预览后,如果调用 leaveChannel 退出频道,本地预览依然处于启动状态,如需要关闭本地预览,需要调用 stopPreview 。
Declared In
AgoraRtcEngineKit.h
– stopPreview
停止本地视频预览
- (int)stopPreview
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
Note: 请在开启预览后且加入频道前调用该方法。
Declared In
AgoraRtcEngineKit.h
– enableLocalVideo:
开关本地视频采集
- (int)enableLocalVideo:(BOOL)enabled
参数
enabled |
是否启用本地视频:
|
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
调用 enableVideo 后,本地视频即默认开启。你可以调用 enableLocalVideo(NO) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 enableLocalVideo(YES)。
成功禁用或启用本地视频采集后,远端会触发 remoteVideoStateChangedOfUid 回调。
该方法在加入频道前后都能调用。
Note:
该方法设置的是内部引擎为启用/禁用状态,在 leaveChannel 后仍然有效。
Declared In
AgoraRtcEngineKit.h
– muteLocalVideoStream:
取消或恢复发布本地视频流。
- (int)muteLocalVideoStream:(BOOL)mute
参数
mute |
是否取消发布本地视频流:
|
---|
返回
- 0: 方法调用成功。
< 0: 方法调用失败。
-5
(AgoraErrorCodeRefused
): 调用被拒绝。
详情
自 v3.4.5 起,该方法仅设置用户在 AgoraRtcEngineKit
频道中的视频发布状态。
成功调用该方法后,远端会触发 didVideoMuted 回调。
同一时间,本地的音视频流只能发布到一个频道。如果你创建了多个频道,请确保你只在一个频道中调用
muteLocalVideoStream(NO)
,否则方法会调用失败并返回 -5 (AgoraErrorCodeRefused)
。
Note:
- 该方法不会改变视频采集设备的使用状态。
- 该方法的调用是否生效受 joinChannelByToken 和 setClientRole 方法的影响,详见《设置发布状态》。
Declared In
AgoraRtcEngineKit.h
– muteAllRemoteVideoStreams:
取消或恢复订阅所有远端用户的视频流。
- (int)muteAllRemoteVideoStreams:(BOOL)mute
参数
mute |
是否取消订阅所有远端用户的视频流。
|
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流, 包括在调用该方法后加入频道的用户的视频流。
Note
- 该方法需要在加入频道后调用。
- 自 v3.3.0 起,该方法包含了
setDefaultMuteAllRemoteVideoStreams
的功能。Agora 建议不要一起调用
muteAllRemoteVideoStreams
和setDefaultMuteAllRemoteVideoStreams
,否则设置可能会不生效。详见《设置订阅状态》。
Declared In
AgoraRtcEngineKit.h
– muteRemoteVideoStream:mute:
取消或恢复订阅指定远端用户的视频流。
- (int)muteRemoteVideoStream:(NSUInteger)uid mute:(BOOL)mute
参数
uid |
指定用户的用户 ID。 |
---|---|
mute |
是否取消订阅指定远端用户的视频流。
|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
Note
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见《设置订阅状态》。
Declared In
AgoraRtcEngineKit.h
视频前处理及后处理
– setBeautyEffectOptions:options:
设置美颜效果选项。
- (int)setBeautyEffectOptions:(BOOL)enable options:(AgoraBeautyOptions *_Nullable)options
参数
enable |
是否开启美颜功能:
|
---|---|
options |
美颜选项,详见 AgoraBeautyOptions |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Declared In
AgoraRtcEngineKit.h
– enableVirtualBackground:backData:
开启/关闭虚拟背景。(beta 功能)
- (int)enableVirtualBackground:(BOOL)enable backData:(AgoraVirtualBackgroundSource *_Nullable)backData
参数
enable |
设置是否开启虚拟背景:
|
---|---|
backData |
自定义的背景图。详见 AgoraVirtualBackgroundSource 。 Note:为将自定义背景图的分辨率与 SDK 的视频采集分辨率适配, SDK 会在保证自定义背景图内容不变形的前提下,对自定义背景图进行缩放和裁剪。 |
返回
- 0: 方法调用成功。
- < 0: 方法调用失败。
Availability
自 v3.4.5 起支持 macOS 平台,自 v3.5.0 起支持 iOS 平台。
开启虚拟背景功能后,你可以使用自定义的背景图替代本地用户原来的背景图。替换后, 频道内所有用户都能看到自定义的背景图。你可以从 virtualBackgroundSourceEnabled 回调了解虚拟背景是否成功开启和相应的出错原因。
Note:
- 调用该方法前,请确保你已经将
AgoraVideoSegmentationExtension.framework
(macOS) 或AgoraVideoSegmentationExtension.xcframework
(iOS)动态库集成到项目文件中。 - 请在 enableVideo 后调用该方法。
该功能对设备性能要求较高,Agora 推荐你在如下设备上使用:
- macOS:CPU 为 i5 及更好的设备
iOS:搭载 A9 及以上芯片的如下设备:
- iPhone 6S 及以上
- iPad Air 第三代及以上
- iPad 第五代及以上
- iPad Pro 第一代及以上
- iPad mini 第五代及以上
Agora 建议你在满足如下条件的场景中使用该功能:
- 使用高清摄像设备、摄像环境光照均匀。
- 摄像画面中,物件较少,用户的人像为半身人像且基本无遮挡,背景色较单一且与用户着装颜色不同。
Declared In
AgoraRtcEngineKit.h
人脸检测
– enableFaceDetection:
开启/关闭本地人脸检测。
- (int)enableFaceDetection:(bool)enable
参数
enable |
是否开启人脸检测:
|
---|
返回
- 0: 方法调用成功。
- < 0: 方法调用失败。
详情
自从: v3.0.1.
开启本地人脸检测后,SDK 会触发 facePositionDidChangeWidth 回调向你报告人脸检测的信息:
- 摄像头采集的画面大小
- 人脸在画面中的位置
- 人脸距设备屏幕的距离
Note
- 该方法在加入频道前后都能调用。
- 该方法仅使用于 iOS 平台。
Declared In
AgoraRtcEngineKit.h
音频播放路由
– setDefaultAudioRouteToSpeakerphone:
设置默认的音频路由。
- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker
参数
defaultToSpeaker |
设置默认的音频路由:
|
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
如果 SDK 默认的音频路由(见《设置音频路由》)无法满足你的需求, 你可以调用该方法切换默认的音频路由。成功切换音频路由后,SDK 会触发 didAudioRouteChanged 回调提示音频路由已更改。
Note
- 该方法仅适用于 iOS 平台。
- 该方法需要在 joinChannelByToken 前调用。如需在加入频道后切换音频路由,请调用 setEnableSpeakerphone。
- 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备,则该方法的设置无效, 音频只会通过外接设备播放。当有多个外接设备时,音频会通过最后一个接入的设备播放。
Declared In
AgoraRtcEngineKit.h
– setEnableSpeakerphone:
开启/关闭扬声器播放。
- (int)setEnableSpeakerphone:(BOOL)enableSpeaker
参数
enableSpeaker |
设置是否开启扬声器播放:
|
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
如果 SDK 默认的音频路由(见《设置音频路由》)或
setDefaultAudioRouteToSpeakerphone
的设置无法满足你的需求,你可以调用 setEnableSpeakerphone
切换当前的音频路由。
成功切换音频路由后,SDK 会触发
didAudioRouteChanged
回调提示音频路由已更改。
该方法只设置用户在当前频道内使用的音频路由,不会影响 SDK 默认的音频路由。 如果用户离开当前频道并加入新的频道,则用户还是会使用 SDK 默认的音频路由。
Note
- 该方法仅适用于 iOS 平台。
- 该方法需要在 joinChannelByToken 后调用。
- 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备,则该方法的设置无效, 音频只会通过外接设备播放。当有多个外接设备时,音频会通过最后一个接入的设备播放。
Declared In
AgoraRtcEngineKit.h
– isSpeakerphoneEnabled
查询扬声器启用状态
- (BOOL)isSpeakerphoneEnabled
返回
- YES: 扬声器已开启,语音会输出到扬声器
- NO: 扬声器未开启,语音会输出到非扬声器(听筒、耳机等)
详情
该方法仅适用于 iOS。 该方法在加入频道前后都能调用。
Declared In
AgoraRtcEngineKit.h
耳返设置
– enableInEarMonitoring:
开启耳返功能
- (int)enableInEarMonitoring:(BOOL)enabled
参数
enabled |
|
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法在加入频道前后都能调用。
Note
- 该方法仅适用于 iOS 平台。
- 用户必须使用有线耳机才能听到耳返效果。
Declared In
AgoraRtcEngineKit.h
– setInEarMonitoringVolume:
设置耳返音量
- (int)setInEarMonitoringVolume:(NSInteger)volume
参数
volume |
设置耳返音量,取值范围在 [0,100]。默认值为 100 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法在加入频道前后都能调用。
Note
- 该方法仅适用于 iOS 平台。
- 用户必须使用有线耳机才能听到耳返效果。
Declared In
AgoraRtcEngineKit.h
设置人声效果
– setLocalVoicePitch:
设置本地语音音调
- (int)setLocalVoicePitch:(double)pitch
参数
pitch |
语音频率。可以在 [0.5,2.0] 范围内设置。取值越小,则音调越低。默认值为 1.0,表示不需要修改音调。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法改变本地说话人声音的音调。该方法在加入频道前后都能调用。
Declared In
AgoraRtcEngineKit.h
– setLocalVoiceEqualizationOfBandFrequency:withGain:
设置本地语音音效均衡
- (int)setLocalVoiceEqualizationOfBandFrequency:(AgoraAudioEqualizationBandFrequency)bandFrequency withGain:(NSInteger)gain
参数
bandFrequency |
频谱子带索引,取值范围是 [0,9],分别代表 10 个 频带,对应的中心频率是 [31,62,125,250,500,1k,2k,4k,8k,16k] Hz,详见 AgoraAudioEqualizationBandFrequency 。 |
---|---|
gain |
每个 band 的增益,单位是 dB,每一个值的范围是 [-15,15],默认值为 0。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法在加入频道前后都能调用。
Declared In
AgoraRtcEngineKit.h
– setLocalVoiceReverbOfType:withValue:
设置本地音效混响
- (int)setLocalVoiceReverbOfType:(AgoraAudioReverbType)reverbType withValue:(NSInteger)value
参数
reverbType |
混响音效类型,详见 AgoraAudioReverbType |
---|---|
value |
设置混响音效的效果数值,各混响音效对应的取值范围请参考 AgoraAudioReverbType |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Declared In
AgoraRtcEngineKit.h
– setVoiceBeautifierPreset:
设置 SDK 预设的美声效果。
- (int)setVoiceBeautifierPreset:(AgoraVoiceBeautifierPreset)preset
参数
preset |
预设的美声效果选项:AgoraVoiceBeautifierPreset。 |
---|
返回
- 0: 方法调用成功。
- < 0: 方法调用失败。
Availability
v3.2.0
调用该方法可以为本地发流用户设置 SDK 预设的人声美化效果。设置美声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的美声效果, 各美声效果的适用场景可参考《设置人声效果》。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario
设为
AgoraAudioScenarioGameStreaming(3)
,并将 profile
设为 AgoraAudioProfileMusicHighQuality(4)
或 AgoraAudioProfileMusicHighQualityStereo(5)
。
Note
- 该方法在加入频道前后都能调用。
- 请勿将
setAudioProfile
的profile
参数设置为AgoraAudioProfileSpeechStandard(1)
,否则该方法不生效。 - 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
调用该方法后,Agora 不推荐调用以下方法,否则该方法设置的效果会被覆盖:
Declared In
AgoraRtcEngineKit.h
– setVoiceBeautifierParameters:param1:param2:
设置 SDK 预设美声效果的参数。
- (int)setVoiceBeautifierParameters:(AgoraVoiceBeautifierPreset)preset param1:(int)param1 param2:(int)param2
参数
preset |
SDK 预设的音效:
|
---|---|
param1 |
歌声的性别特征:
|
param2 |
歌声的混响效果:
|
返回
- 0: 方法调用成功。
- < 0: 方法调用失败。
Availability
v3.3.0
调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。设置后,频道内所有用户都能听到该效果。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile
的 scenario
设为 AgoraAudioScenarioGameStreaming(3)
,并将 profile
设为 AgoraAudioProfileMusicHighQuality(4)
或
AgoraAudioProfileMusicHighQualityStereo(5)
。
Note
- 该方法在加入频道前后都能调用。
- 请勿将
setAudioProfile
的profile
参数设置为AgoraAudioProfileSpeechStandard(1)
,否则该方法不生效。 - 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
调用该方法后,Agora 不推荐调用以下方法,否则该方法设置的效果会被覆盖:
Declared In
AgoraRtcEngineKit.h
– setAudioEffectPreset:
设置 SDK 预设的人声音效。
- (int)setAudioEffectPreset:(AgoraAudioEffectPreset)preset
参数
preset |
预设的音效选项:AgoraAudioEffectPreset。 |
---|
返回
- 0: 方法调用成功。
- < 0: 方法调用失败。
Availability
v3.2.0
调用该方法可以为本地发流用户设置 SDK 预设的人声音效,且不会改变原声的性别特征。设置音效后,频道内所有用户都能听到该效果。
根据不同的场景,你可以为用户设置不同的音效,各音效的适用场景可参考《设置人声效果》。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario
设为 AgoraAudioScenarioGameStreaming(3)
。
Note:
- 该方法在加入频道前后都能调用。
- 请勿将
setAudioProfile
的profile
参数设置为AgoraAudioProfileSpeechStandard(1)
,否则该方法不生效。 - 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 如果调用该方法并设置除
AgoraRoomAcoustics3DVoice
或AgoraPitchCorrection
外的枚举,请勿再调用 setAudioEffectParameters,否则该方法设置的效果会被覆盖。 调用该方法后,Agora 不推荐调用以下方法,否则该方法设置的效果会被覆盖:
Declared In
AgoraRtcEngineKit.h
– setVoiceConversionPreset:
设置 SDK 预设的变声效果。
- (int)setVoiceConversionPreset:(AgoraVoiceConversionPreset)preset
参数
preset |
预设的变声效果选项:AgoraVoiceConversionPreset。 |
---|
返回
- 0: 方法调用成功。
- < 0: 方法调用失败。
Availability
v3.3.1
调用该方法可以为本地发流用户设置 SDK 预设的变声效果。设置变声效果后,频道内所有用户都能听到该效果。 根据不同的场景,你可以为用户设置不同的变声效果,各变声效果的适用场景可参考《设置人声效果》。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile
的 profile
设为 AgoraAudioProfileMusicHighQuality(4)
或 AgoraAudioProfileMusicHighQualityStereo(5)
,并将
scenario
设为 AgoraAudioScenarioGameStreaming(3)
。
Note:
- 该方法在加入频道前后都能调用。
- 请勿将
setAudioProfile
的profile
参数设置为AgoraAudioProfileSpeechStandard(1)
,否则该方法不生效。 - 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
调用该方法后,Agora 不推荐调用以下方法,否则该方法设置的效果会被覆盖:
Declared In
AgoraRtcEngineKit.h
– setAudioEffectParameters:param1:param2:
设置 SDK 预设人声音效的参数。
- (int)setAudioEffectParameters:(AgoraAudioEffectPreset)preset param1:(int)param1 param2:(int)param2
参数
preset |
SDK 预设的音效:
|
---|---|
param1 |
|
param2 |
|
返回
- 0: 方法调用成功。
- < 0: 方法调用失败。
Availability
v3.2.0
调用该方法可以对本地发流用户进行如下设置:
- 3D 人声音效:设置 3D 人声音效的环绕周期。
- 电音音效:设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效,Agora 推荐你将基础调式和主音音高配置选项与应用的 UI 元素绑定。
设置后,频道内所有用户都能听到该效果。
Note:
- 该方法在加入频道前后都能调用。
- 为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile 的
scenario
设为AgoraAudioScenarioGameStreaming(3)
。 - 请勿将
setAudioProfile
的profile
参数设置为AgoraAudioProfileSpeechStandard(1)
,否则该方法不生效。 - 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
调用该方法后,Agora 不推荐调用以下方法,否则该方法设置的效果会被覆盖:
Declared In
AgoraRtcEngineKit.h
听声辨位
– enableSoundPositionIndication:
开启/关闭远端用户的语音立体声。
- (int)enableSoundPositionIndication:(BOOL)enabled
参数
enabled |
是否开启远端用户语音立体声:
- |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
如果想调用 setRemoteVoicePosition 实现听声辨位的功能,请确保在加入频道前调用本方法开启远端用户的语音立体声。
Declared In
AgoraRtcEngineKit.h
– setRemoteVoicePosition:pan:gain:
设置远端用户的语音位置
- (int)setRemoteVoicePosition:(NSUInteger)uid pan:(double)pan gain:(double)gain
参数
uid |
远端用户的 ID |
---|---|
pan |
设置远端用户声音的空间位置,取值范围为 [-1.0,1.0]:
|
gain |
设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
设置远端用户声音的空间位置和音量,方便本地用户听声辨位。
通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。
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
参数
filePath |
音乐文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如: |
---|---|
loopback |
是否只在本地播放音乐文件:
|
replace |
是否用音乐文件替换麦克风采集的音频:
|
cycle |
音乐文件的播放次数。
|
startPos |
音乐文件的播放位置,单位为毫秒。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Availability
v3.4.0
该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后,本地会触发
localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying, AgoraAudioMixingReasonStartedByUser)
回调。
播放结束后,本地会触发 localAudioMixingStateDidChanged(AgoraAudioMixingStateStopped, AgoraAudioMixingReasonAllLoopsCompleted)
回调。
Note:
- 为避免阻塞,自 v3.4.5 起,该方法由同步调用改为异步调用。
- 如需多次调用
startAudioMixing
,请确保调用间隔大于 500 ms。 - 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL,则 SDK 会报告
AgoraWarningCodeAudioMixingOpenError(701)
。
Declared In
AgoraRtcEngineKit.h
– stopAudioMixing
停止播放音乐文件
- (int)stopAudioMixing
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
请在频道内调用该方法。
Declared In
AgoraRtcEngineKit.h
– pauseAudioMixing
暂停播放音乐文件
- (int)pauseAudioMixing
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
请在频道内调用该方法。
Declared In
AgoraRtcEngineKit.h
– resumeAudioMixing
恢复播放音乐文件
- (int)resumeAudioMixing
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
请在频道内调用该方法。
Declared In
AgoraRtcEngineKit.h
– adjustAudioMixingVolume:
调节音乐文件的播放音量
- (int)adjustAudioMixingVolume:(NSInteger)volume
参数
volume |
音乐文件播放音量范围为 0~100。默认 100 为原始文件音量 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法调节混音的音乐文件在本地和远端播放的音量大小。该方法需要在 startAudioMixing 后调用。
Note:
- 调用该方法不影响调用 playEffect 播放音效文件的音量。
- 你需要在调用 startAudioMixing 并收到
localAudioMixingStateDidChanged(
AgoraAudioMixingStatePlaying
) 回调后调用该方法。
Declared In
AgoraRtcEngineKit.h
– adjustAudioMixingPlayoutVolume:
调节音乐文件在本地播放的音量
- (int)adjustAudioMixingPlayoutVolume:(NSInteger)volume
参数
volume |
音乐文件播放音量范围为 0~100。默认 100 为原始文件音量 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法调节混音的音乐文件在本地播放的音量大小。该方法需要在 startAudioMixing 后调用。
Declared In
AgoraRtcEngineKit.h
– adjustAudioMixingPublishVolume:
调节音乐文件在远端播放的音量
- (int)adjustAudioMixingPublishVolume:(NSInteger)volume
参数
volume |
音乐文件播放音量范围为 0~100。默认 100 为原始文件音量 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法调节混音的音乐文件在远端播放的音量大小。该方法需要在 startAudioMixing 后调用。
Declared In
AgoraRtcEngineKit.h
– getAudioMixingPlayoutVolume
获取音乐文件的本地播放音量
- (int)getAudioMixingPlayoutVolume
返回
- 方法调用成功则返回音量值,范围为 [0,100]
- <0:方法调用失败
详情
该方法获取混音的音乐文件本地播放音量,方便排查音量相关问题。
Note: 你需要在调用 startAudioMixing 并收到
localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying
) 回调后调用该方法。
Declared In
AgoraRtcEngineKit.h
– getAudioMixingPublishVolume
获取音乐文件的远端播放音量
- (int)getAudioMixingPublishVolume
返回
- 方法调用成功则返回音量值,范围为 [0,100]
- <0:方法调用失败
详情
该方法获取混音的音乐文件远端播放音量,方便排查音量相关问题。
Note: 你需要在调用 startAudioMixing 并收到
localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying
) 回调后调用该方法。
Declared In
AgoraRtcEngineKit.h
– getAudioMixingDuration
获取音乐文件时长
- (int)getAudioMixingDuration
返回
- 方法调用成功返回音乐文件时长
- < 0: 方法调用失败
详情
该方法获取音乐文件时长,单位为毫秒。请在 startAudioMixing 后调用该方法。
Declared In
AgoraRtcEngineKit.h
– getAudioMixingCurrentPosition
获取音乐文件播放进度,单位为毫秒。
- (int)getAudioMixingCurrentPosition
返回
- 方法调用成功返回音乐文件播放进度
- < 0: 方法调用失败
详情
Note:
- 你需要在调用 startAudioMixing 并收到
localAudioMixingStateDidChanged(
AgoraAudioMixingStatePlaying
) 回调后调用该方法。 - 如需多次调用
getAudioMixingCurrentPosition
,请确保调用间隔大于 500 ms。
Declared In
AgoraRtcEngineKit.h
– setAudioMixingPosition:
设置音频文件的播放位置
- (int)setAudioMixingPosition:(NSInteger)pos
参数
pos |
整数。进度条位置,单位为毫秒。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法可以设置音频文件的播放位置,这样你可以根据实际情况播放文件,而不是非得从头到尾播放一个文件。该方法需要在 startAudioMixing 后调用。
Declared In
AgoraRtcEngineKit.h
– setAudioMixingPitch:
调整本地播放的音乐文件的音调。
- (int)setAudioMixingPitch:(NSInteger)pitch
参数
pitch |
按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12],每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。 |
---|
返回
- 0: 方法调用成功。
- < 0: 方法调用失败。
Declared In
AgoraRtcEngineKit.h
音效文件播放管理
– getEffectsVolume
获取音效文件播放音量,范围为 [0.0,100.0]。
- (double)getEffectsVolume
返回
- 方法调用成功返回音效的音量值
- < 0: 方法调用失败
详情
该方法需要在 playEffect 后调用。
Declared In
AgoraRtcEngineKit.h
– setEffectsVolume:
设置音效文件播放音量
- (int)setEffectsVolume:(double)volume
参数
volume |
取值范围为 [0.0,100.0]。 100.0 为默认值 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法需要在 playEffect 后调用。
Declared In
AgoraRtcEngineKit.h
– setVolumeOfEffect:withVolume:
实时调整音效文件播放音量,范围为 [0.0,100.0]。
- (int)setVolumeOfEffect:(int)soundId withVolume:(double)volume
参数
soundId |
自行设定的音效 ID,需保证唯一性。 |
---|---|
volume |
取值范围为 [0.0,100.0]。100.0 为默认值 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法需要在 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
参数
soundId |
音效的 ID。每个音效的 ID 具有唯一性。如果你已通过 preloadEffect 将音效加载至内存,
请确保该参数与 |
---|---|
filePath |
音效文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如: |
loopCount |
音效循环播放的次数。
|
pitch |
音效的音调,取值范围为 [0.5,2.0]。默认值为 |
pan |
音效的空间位置。取值范围为 [-1.0,1.0],例如:
|
gain |
音效的音量。取值范围为 [0.0,100.0]。默认值为 |
publish |
是否将音效发布至远端:
|
startPos |
音效文件的播放位置,单位为毫秒。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
你可以多次调用该方法,传入不同的 soundId
和 filePath
,同时播放多个音效文件。为获得最佳用户体验,Agora 推荐同时播放的音效文件不超过 3 个。
音效文件播放结束后,SDK 会触发 rtcEngineDidAudioEffectFinish 回调。
Note: 该方法需要在加入频道后调用。
Declared In
AgoraRtcEngineKit.h
– stopEffect:
停止播放指定音效文件
- (int)stopEffect:(int)soundId
参数
soundId |
自行设定的音效 ID,需保证唯一性。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Declared In
AgoraRtcEngineKit.h
– preloadEffect:filePath:
将指定音效文件预加载至内存
- (int)preloadEffect:(int)soundId filePath:(NSString *_Nullable)filePath
参数
soundId |
自行设定的音效 ID,需保证唯一性。 |
---|---|
filePath |
音效文件的绝对路径 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
为保证通信畅通,请注意控制预加载音效文件的大小,并在 joinChannelByToken 前就使用该方法完成音效预加载。
音效文件支持以下音频格式: mp3,aac,m4a,3gp,wav
Note: 该方法不支持在线音效文件。
Declared In
AgoraRtcEngineKit.h
– unloadEffect:
从内存释放某个预加载的音效文件
- (int)unloadEffect:(int)soundId
参数
soundId |
自行设定的音效 ID,需保证唯一性。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Declared In
AgoraRtcEngineKit.h
– pauseEffect:
暂停音效文件播放
- (int)pauseEffect:(int)soundId
参数
soundId |
自行设定的音效 ID,需保证唯一性。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Declared In
AgoraRtcEngineKit.h
– pauseAllEffects
暂停所有音效文件播放
- (int)pauseAllEffects
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Declared In
AgoraRtcEngineKit.h
– resumeEffect:
恢复播放指定音效文件
- (int)resumeEffect:(int)soundId
参数
soundId |
自行设定的音效 ID,需保证唯一性。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Declared In
AgoraRtcEngineKit.h
– resumeAllEffects
恢复播放所有音效文件
- (int)resumeAllEffects
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Declared In
AgoraRtcEngineKit.h
– getEffectCurrentPosition:
获取指定音效文件的播放进度。
- (int)getEffectCurrentPosition:(int)soundId
参数
soundId |
音效 ID。请确保与 |
---|
返回
- ≥ 0: 方法调用成功,返回指定音效文件的播放进度(毫秒)。
< 0: 方法调用失败。
-22(AgoraErrorCodeResourceLimited)
: 无法找到音效文件。请填写正确的soundId
。
Availability
v3.4.0
详情
Note: 该方法需要在 playEffect 后调用。
Declared In
AgoraRtcEngineKit.h
– setEffectPosition:pos:
设置指定音效文件的播放位置。
- (int)setEffectPosition:(int)soundId pos:(NSInteger)pos
参数
soundId |
音效 ID。请确保与 |
---|---|
pos |
音效文件的播放位置,单位为毫秒。 |
返回
- 0: 方法调用成功。
< 0: 方法调用失败。
-22(AgoraErrorCodeResourceLimited)
: 无法找到音效文件。请填写正确的soundId
。
Availability
v3.4.0
成功设置后,本地音效文件会在指定位置开始播放。
详情
Note: 该方法需要在 playEffect 后调用。
Declared In
AgoraRtcEngineKit.h
– getEffectDuration:
获取指定音效文件总时长。
- (int)getEffectDuration:(NSString *)filePath
参数
filePath |
本地音效文件的绝对路径,需精确到文件名及格式。例如: |
---|
返回
- ≥ 0: 方法调用成功,返回指定音效文件时长(毫秒)。
< 0: 方法调用失败。
-22(AgoraErrorCodeResourceLimited)
: 无法找到音效文件。请填写正确的filePath
。
Availability
v3.4.0
详情
Note: 该方法需要在加入频道后调用。
Declared In
AgoraRtcEngineKit.h
虚拟节拍器
– startRhythmPlayer:sound2:config:
开启虚拟节拍器。
- (int)startRhythmPlayer:(NSString *_Nonnull)sound1 sound2:(NSString *_Nonnull)sound2 config:(AgoraRtcRhythmPlayerConfig *_Nonnull)config
参数
sound1 |
强拍文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如: |
---|---|
sound2 |
弱拍文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如: |
config |
节拍器配置。详见 AgoraRtcRhythmPlayerConfig。 |
返回
- 0: 方法调用成功。
< 0: 方法调用失败。
-22(AgoraErrorCodeResourceLimited)
: 无法找到音频文件。请填写正确的sound1
和sound2
。
Availability
v3.4.0
在音乐教学、体育教学等场景中,老师通常需要使用节拍器,让学生跟着正确的节拍练习。节拍由强拍和弱拍组成,每小节的第一拍称为强拍,其余称为弱拍。 你需要在该方法中设置强拍和弱拍的文件路径、每小节的拍数、节拍速度以及是否将节拍器的声音发送至远端。
详情
Note: 开启虚拟节拍器后,SDK 会从头开始播放指定的音频文件,并根据你设置的 beatsPerMinute 控制每个文件的播放时长。
例如,将 beatsPerMinute
设为 60
,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。
Declared In
AgoraRtcEngineKit.h
– stopRhythmPlayer
关闭虚拟节拍器。
- (int)stopRhythmPlayer
返回
- 0: 方法调用成功。
- < 0: 方法调用失败。
Declared In
AgoraRtcEngineKit.h
– configRhythmPlayer:
配置虚拟节拍器。
- (int)configRhythmPlayer:(AgoraRtcRhythmPlayerConfig *_Nonnull)config
参数
config |
节拍器配置。详见 AgoraRtcRhythmPlayerConfig。 |
---|
返回
- 0: 方法调用成功。
- < 0: 方法调用失败。
详情
Note: 重新配置虚拟节拍器后,SDK 会从头开始播放指定的音效文件,并根据你设置的 beatsPerMinute 控制每个文件的播放时长。
例如,将 beatsPerMinute
设为 60
,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。
Declared In
AgoraRtcEngineKit.h
音频录制
– startAudioRecordingWithConfig:
开始客户端录音。
- (int)startAudioRecordingWithConfig:(AgoraAudioRecordingConfiguration *_Nonnull)config
参数
config |
录音配置。详见 AgoraAudioRecordingConfiguration。 |
---|
返回
- 0: 方法调用成功。
< 0: 方法调用失败。
-160(
AgoraErrorCodeAlreadyInRecording
): 客户端正在录音。如需开始新的录音,请先调用 stopAudioRecording 停止当前录音,再调用startAudioRecordingWithConfig
。
Availability
v3.4.0
Agora SDK 支持通话过程中在客户端进行录音。调用该方法后,你可以录制频道内用户的音频,并得到一个录音文件。录音文件格式可以为:
- WAV: 音质保真度较高,文件较大。例如,采样率为 32000 Hz,录音时长为 10 分钟的文件大小约为 73 M。
- AAC: 音质保真度较低,文件较小。例如,采样率为 32000 Hz,录音音质为
AgoraAudioRecordingQualityMedium
,录音时长为 10 分钟的文件大小约为 2 M。
一旦用户离开频道,录音会自动停止。
详情
Note: 该方法需要在加入频道后调用。
Declared In
AgoraRtcEngineKit.h
– stopAudioRecording
停止客户端录音。
- (int)stopAudioRecording
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Declared In
AgoraRtcEngineKit.h
开启声卡采集
– enableLoopbackRecording:deviceName:
开启声卡采集
- (int)enableLoopbackRecording:(BOOL)enabled deviceName:(NSString *_Nullable)deviceName
参数
enabled |
|
---|---|
deviceName |
声卡的设备名。默认设为 nil,即使用当前声卡采集。如果用户使用虚拟声卡,如 “Soundflower”,可以将虚拟声卡名称 “Soundflower” 作为参数,SDK 会找到对应的虚拟声卡设备,并开始采集。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法仅适用于 macOS。该方法在加入频道前后都能调用。
启用声卡采集功能后,声卡播放的音频会被合到本地音频流中,从而可以发送到远端。
Note:
macOS 系统默认声卡不支持采集功能,如需开启此功能需要 App 自己启用一个虚拟声卡,并将该虚拟声卡的名字作为 deviceName 传入 SDK。 Agora 测试并推荐 soundflower 作为虚拟声卡。
Declared In
AgoraRtcEngineKit.h
音频其他方法
– setAudioSessionOperationRestriction:
设置 SDK 对 Audio Session 的操作权限。
- (void)setAudioSessionOperationRestriction:(AgoraAudioSessionOperationRestriction)restriction
参数
restriction |
SDK 对 Audio Session 的操作权限,详见 AgoraAudioSessionOperationRestriction。该参数为 Bit Mask,每个 Bit 对应一个权限。 |
---|
详情
在默认情况下,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
参数
enabled |
是否开启 AI 降噪模式:
|
---|
返回
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -
157
(AgoraErrorCodeModuleNotFound
): 未集成 AI 降噪库。
- -
详情
SDK 默认开启传统降噪模式,以消除大部分平稳噪声。如果你还需要消除非平稳噪声,Agora 推荐你按如下步骤开启 AI 降噪模式:
确保已集成如下库:
- iOS:
AgoraAIDenoiseExtension.xcframework
- macOS:
AgoraAIDenoiseExtension.framework
- iOS:
- 调用
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
库,所以 Agora 推荐在加入频道前调用该方法。 - 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
Declared In
AgoraRtcEngineKit.h
网络相关测试
– startEchoTestWithInterval:successBlock:
开始语音通话回路测试
- (int)startEchoTestWithInterval:(NSInteger)interval successBlock:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))successBlock
参数
interval |
返回语音通话回路测试结果的时间间隔,取值范围为 [2,10],单位为秒,默认值为 10 秒。 |
---|---|
successBlock |
成功开始语音通话测试回调。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,声音会在设置的时间间隔后回放出来。如果用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。
Note:
- 请在加入频道前调用该方法。
- 调用该方法后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
- 直播场景下,该方法仅能由用户角色为主播的用户调用。
Declared In
AgoraRtcEngineKit.h
– stopEchoTest
停止语音通话回路测试
- (int)stopEchoTest
返回
- 0: 方法调用成功
- < 0: 方法调用失败。如 -5(AgoraErrorCodeRefused):不能停止测试,可能语音通话测试没有成功启动。
Declared In
AgoraRtcEngineKit.h
– enableLastmileTest
启动网络测试
- (int)enableLastmileTest
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法启用网络连接质量测试,用于检测用户网络接入质量。默认该功能为关闭状态。
该方法主要用于以下场景:
- 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
启用该方法会消耗一定的网络流量,影响通话质量,因此我们建议不要和 startLastmileProbeTest 同时使用。
在收到 lastmileQuality 回调后须调用 disableLastmileTest 停止测试,再加入频道或切换用户角色。
Note:
- 调用该方法后,在收到 lastmileQuality 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此回调无法执行。
- 直播场景下,主播在加入频道后请勿调用该方法。
- 加入频道前调用该方法检测网络质量后,SDK 会占用一路视频的带宽,码率与 setVideoEncoderConfiguration 中设置的码率相同。加入频道后,无论是否调用了
disableLastmileTest
,SDK 均会自动停止带宽占用。
Declared In
AgoraRtcEngineKit.h
– disableLastmileTest
关闭网络测试
- (int)disableLastmileTest
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Declared In
AgoraRtcEngineKit.h
– startLastmileProbeTest:
开始通话前网络质量探测
- (int)startLastmileProbeTest:(AgoraLastmileProbeConfig *_Nullable)config
参数
config |
Last mile 网络探测配置,详见 AgoraLastmileProbeConfig |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。
启用该方法后,SDK 会依次返回如下 2 个回调:
- lastmileQuality,视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- lastmileProbeResult,视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。
该方法主要用于以下两种场景:
- 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
Note:
- 该方法会消耗一定的网络流量,影响通话质量,因此我们建议不要和 enableLastmileTest 同时使用。
- 调用该方法后,在收到 lastmileQuality 和 lastmileProbeResult 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
- 直播场景下,如果本地用户为主播,请勿在加入频道后调用该方法。
Declared In
AgoraRtcEngineKit.h
– stopLastmileProbeTest
停止通话前网络质量探测
- (int)stopLastmileProbeTest
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
停止通话前网络质量探测。
Declared In
AgoraRtcEngineKit.h
自定义视频模块
– setVideoSource:
设置自定义视频源
- (void)setVideoSource:(id<AgoraVideoSourceProtocol> _Nullable)videoSource
参数
videoSource |
自定义的视频源,详见 AgoraVideoSourceProtocol |
---|
详情
该方法设置视频源。实时通讯过程中,Agora SDK 通常会启动默认的视频输入设备,即内置的摄像头,进行视频推流。当需要自定义视频设备时,App 可以先通过 AgoraVideoSourceProtocol 自定义视频源,然后调用该方法将自定义的视频源加入到 SDK 中。
该方法在加入频道前后都能调用。
Declared In
AgoraRtcEngineKit.h
– setLocalVideoRenderer:
本地自定义视频渲染器
- (void)setLocalVideoRenderer:(id<AgoraVideoSinkProtocol> _Nullable)videoRenderer
参数
videoRenderer |
自定义的视频渲染器,详见 AgoraVideoSinkProtocol |
---|
详情
该方法设置本地视频渲染器。实时通讯过程中,Agora SDK 通常会启动默认的视频渲染器进行视频渲染。当需要自定义视频渲染设备时,App 可以先通过 AgoraVideoSinkProtocol 自定义渲染器,然后调用该方法将视频渲染器加入到 SDK 中。
该方法在加入频道前后都能调用。
Declared In
AgoraRtcEngineKit.h
– setRemoteVideoRenderer:forUserId:
远端自定义视频渲染器
- (void)setRemoteVideoRenderer:(id<AgoraVideoSinkProtocol> _Nullable)videoRenderer forUserId:(NSUInteger)userId
参数
videoRenderer |
自定义的视频渲染器,详见 AgoraVideoSinkProtocol |
---|---|
userId |
远端用户的 uid |
详情
实时音视频互动过程中,Agora SDK 通常会启动默认的视频渲染器进行视频渲染。当需要自定义视频渲染设备时,App 可以先通过 AgoraVideoSinkProtocol 自定义渲染器,然后调用该方法将视频渲染器加入到 SDK 中。
该方法在加入频道前后都能调用。如果在加入频道前调用,需要自行维护远端用户的 uid
。
Declared In
AgoraRtcEngineKit.h
– videoSource
获取当前视频源
- (id<AgoraVideoSourceProtocol> _Nullable)videoSource
Declared In
AgoraRtcEngineKit.h
– localVideoRenderer
获取本地视频渲染器
- (id<AgoraVideoSinkProtocol> _Nullable)localVideoRenderer
Declared In
AgoraRtcEngineKit.h
– remoteVideoRendererOfUserId:
获取远端视频渲染器
- (id<AgoraVideoSinkProtocol> _Nullable)remoteVideoRendererOfUserId:(NSUInteger)userId
参数
userId |
远端用户的 uid |
---|
详情
该方法获取远端视频渲染器。
Declared In
AgoraRtcEngineKit.h
– setVideoDataFrame:
注册原始视频数据协议。
- (void)setVideoDataFrame:(id<AgoraVideoDataFrameProtocol> _Nullable)videoData
参数
videoData |
原始视频数据。详见 AgoraVideoDataFrameProtocol 。 传空表示取消注册原始视频数据观测器。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Availability
v3.4.5
成功注册原始视频数据协议后,SDK 会在捕捉到每个视频帧时,触发你在 AgoraVideoDataFrameProtocol 中实现的回调。
Note:
- 该方法仅适用于 iOS 平台。
- 该方法需要在加入频道前调用。
- 通过协议获取的视频宽高可能会因网络情况变差和用户自行调整分辨率而变化。
Declared In
AgoraRtcEngineKit.h
– setVideoEncodedFrame:
注册本地视频编码数据协议。
- (void)setVideoEncodedFrame:(id<AgoraVideoEncodedFrameProtocol> _Nullable)videoEncode
参数
videoEncode |
本地视频编码数据。详见 AgoraVideoEncodedFrameProtocol 。 传空表示取消注册本地视频编码数据观测器。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Availability
v3.4.5
成功注册本地视频编码数据协议后,SDK 会在捕捉到每个视频帧时,触发你在 AgoraVideoEncodedFrameProtocol 中实现的回调。
Note:
- 该方法仅适用于 iOS 平台。
- 该方法需要在加入频道前调用。
- 通过协议获取的视频宽高可能会因网络情况变差和用户自行调整分辨率而变化。
Declared In
AgoraRtcEngineKit.h
音频自渲染
– enableExternalAudioSink:channels:
开启外部音频渲染。
- (void)enableExternalAudioSink:(NSUInteger)sampleRate channels:(NSUInteger)channels
参数
sampleRate |
外部音频渲染的采样率 (Hz),可设置为 16000,32000,44100 或 48000。 |
---|---|
channels |
外部音频渲染的声道数,可设置为 1 或 2:
|
详情
该方法适用于需要自行渲染音频的场景。开启外部音频渲染后,你可以通过调用 pullPlaybackAudioFrameRawData / pullPlaybackAudioFrameSampleBufferByLengthInByte 方法拉取远端音频数据App 可以对拉取到的原始音频数据进行处理后再渲染,获取想要的音频效果。
该方法需要在加入频道前调用。
Note: 开启外部音频渲染后,App 会无法从 onPlaybackAudioFrame
回调中获得数据。
Declared In
AgoraRtcEngineKit.h
– disableExternalAudioSink
关闭外部音频渲染。
- (void)disableExternalAudioSink
Declared In
AgoraRtcEngineKit.h
– pullPlaybackAudioFrameRawData:lengthInByte:
拉取 RawData 格式的远端音频数据。
- (BOOL)pullPlaybackAudioFrameRawData:(void *_Nonnull)data lengthInByte:(NSUInteger)lengthInByte
参数
data |
需要拉取的音频数据,格式为 byte[]。 |
---|---|
lengthInByte |
待拉取音频数据的字节数,单位为 byte。该参数的取值与音频数据的时长、你在 enableExternalAudioSink 中设置的 |
返回
- YES: 方法调用成功。
- NO: 方法调用失败。
详情
使用该方法前,你需要调用 enableExternalAudioSink 方法通知 app 开启并设置外部渲染。
调用该方法后,app 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。
Note
- 该方法需要在加入频道后调用。调用该方法后,App 会无法从
onPlaybackAudioFrame
回调中获得数据。 - 该方法和
onPlaybackAudioFrame
回调相比,区别在于:onPlaybackAudioFrame
:SDK 通过该回调将音频数据传输给 app。如果 app 处理延时,可能会导致音频播放抖动。pullPlaybackAudioFrameRawData
:app 主动拉取音频数据。通过设置音频帧的数据和字节数,SDK 可以调整缓存,帮助 app 处理延时,从而有效避免音频播放抖动。
Declared In
AgoraRtcEngineKit.h
– pullPlaybackAudioFrameSampleBufferByLengthInByte:
拉取 SampleBuffer 格式的远端音频数据。
- (CMSampleBufferRef _Nullable)pullPlaybackAudioFrameSampleBufferByLengthInByte:(NSUInteger)lengthInByte
参数
lengthInByte |
待拉取音频数据的字节数,单位为 byte。该参数的取值与音频数据的时长、你在 enableExternalAudioSink 中设置的 |
---|
返回
- YES: 方法调用成功。
- NO: 方法调用失败。
详情
调用该方法前,你需要调用 enableExternalAudioSink 方法通知 app 开启并设置外部渲染。
调用该方法后,app 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。
Note
- 该方法需要在加入频道后调用。调用该方法后,app 会无法从
onPlaybackAudioFrame
回调中获得数据。 该方法和
onPlaybackAudioFrame
方法相比,区别在于:onPlaybackAudioFrame
:SDK 通过该回调将音频数据传输给 app。如果 app 处理延时,可能会导致音频播放抖动;pullPlaybackAudioFrameSampleBufferByLengthInByte
:app 主动拉取音频数据。通过设置音频帧的数据和字节数,SDK 可以调整缓存,帮助 app 处理延时,从而有效避免音频播放抖动。
Declared In
AgoraRtcEngineKit.h
音频自采集 (仅适用于 push 模式)
– enableExternalAudioSourceWithSampleRate:channelsPerFrame:
开启外部音频采集
- (void)enableExternalAudioSourceWithSampleRate:(NSUInteger)sampleRate channelsPerFrame:(NSUInteger)channelsPerFrame
参数
sampleRate |
外部音频源的采样率 (Hz),可设置为 8000,16000,32000,44100 或 48000 |
---|---|
channelsPerFrame |
外部音频源的通道数,可设置为 1 或 2:
|
详情
该方法必须在 joinChannelByToken 和 startPreview 前调用。
Declared In
AgoraRtcEngineKit.h
– disableExternalAudioSource
关闭外部音频采集
- (void)disableExternalAudioSource
Declared In
AgoraRtcEngineKit.h
– pushExternalAudioFrameRawData:samples:timestamp:
推送外部音频帧
- (BOOL)pushExternalAudioFrameRawData:(void *_Nonnull)data samples:(NSUInteger)samples timestamp:(NSTimeInterval)timestamp
参数
data |
外部音频数据 |
---|---|
samples |
音频帧的样本数量 |
timestamp |
外部音频帧的时间戳(毫秒)。该参数为必填。你可以使用该时间戳还原音频帧顺序;在有视频的场景中(包含使用外部视频源的场景),该参数可以帮助实现音视频同步。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
Declared In
AgoraRtcEngineKit.h
– pushExternalAudioFrameSampleBuffer:
推送外部 CMSampleBuffer 音频帧
- (BOOL)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer
参数
sampleBuffer |
采样缓冲区 |
---|
返回
- YES: 方法调用成功
- NO: 方法调用失败
Declared In
AgoraRtcEngineKit.h
视频自采集 (仅适用于 push 模式)
– setExternalVideoSource:useTexture:pushMode:
配置外部视频源
- (void)setExternalVideoSource:(BOOL)enable useTexture:(BOOL)useTexture pushMode:(BOOL)pushMode
参数
enable |
是否使用外部视频源:
|
---|---|
useTexture |
是否使用 Texture 作为输入:
|
pushMode |
是否外部视频源需要调用 pushExternalVideoFrame 将视频帧主动推送给 Agora SDK:
|
详情
Note: 该方法需要在加入频道前调用。
Declared In
AgoraRtcEngineKit.h
– pushExternalVideoFrame:
推送外部视频帧
- (BOOL)pushExternalVideoFrame:(AgoraVideoFrame *_Nonnull)frame
参数
frame |
该视频帧包含待 Agora SDK 编码的视频数据,详见 AgoraVideoFrame |
---|
返回
- YES: 该帧推送成功
- NO: 该帧推送不成功
详情
该方法主动将视频帧数据用 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
参数
sampleRate |
指定 |
---|---|
channel |
指定
|
mode |
|
samplesPerCall |
指定 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法设置 onRecordAudioFrame 回调数据的格式,详情请参考原始音频数据
该方法需要在加入频道前调用。
Note
SDK 会通过该方法的 samplesPerCall
、sampleRate
和 channel
参数计算出采样间隔,计算公式为采样间隔 = 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
参数
sampleRate |
指定 |
---|---|
channel |
指定
|
mode |
|
samplesPerCall |
指定 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法设置 onPlaybackAudioFrame
回调数据的格式,详情请参考原始音视频数据
该方法需要在加入频道前调用。
Note
SDK 会通过该方法的 samplesPerCall
、sampleRate
和 channel
参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall
/(sampleRate
* channel
)。请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发 onPlaybackAudioFrame
回调。
Declared In
AgoraRtcEngineKit.h
– setMixedAudioFrameParametersWithSampleRate:samplesPerCall:
设置采集和播放的音频混音后的数据格式
- (int)setMixedAudioFrameParametersWithSampleRate:(NSInteger)sampleRate samplesPerCall:(NSInteger)samplesPerCall
参数
sampleRate |
指定 |
---|---|
samplesPerCall |
指定 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法设置 onMixedAudioFrame
回调数据的格式,详情请参考原始音视频数据
该方法需要在加入频道前调用。
Note
SDK 会通过该方法的 samplesPerCall
、sampleRate
和 channel
参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall
/(sampleRate
* channel
)。请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发 onMixedAudioFrame
回调。
Declared In
AgoraRtcEngineKit.h
– setAudioDataFrame:
注册原始音频数据协议。
- (BOOL)setAudioDataFrame:(id<AgoraAudioDataFrameProtocol> _Nullable)delegate
参数
delegate |
音频帧 delegate,详见 AgoraAudioDataFrameProtocol 。 |
---|
返回
- YES: 方法调用成功。
- NO: 方法调用失败。
Availability
v3.4.5
当需要 SDK 通过回调提供原始音频数据时,需要使用该方法注册原始音频数据协议。 你需要在该方法中实现 AgoraAudioDataFrameProtocol 。
Note
- 该方法仅适用于 iOS 平台。
- 该方法需要在加入频道前调用。
- 如果你想注销原始音频数据协议,请将
delegate
参数设为nil
。我们建议在收到 didLeaveChannelWithStats 后调用setAudioDataFrame(nil)
。
Declared In
AgoraRtcEngineKit.h
直播视频水印
– addVideoWatermark:options:
添加本地视频水印。
- (int)addVideoWatermark:(NSURL *_Nonnull)url options:(WatermarkOptions *_Nonnull)options
参数
url |
待添加的水印图片的本地路径。本方法支持从本地路径添加水印图片。如果待添加的水印图片位于工程文件中,则需要把图片在 Xcode 属性中将图像的 Type 由 PNG Image 修改为 Data, 否则 SDK 无法识别图片。 |
---|---|
options |
待添加的水印图片的设置选项,详见 WatermarkOptions 。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的观众、旁路直播观众和采集设备都能看到或采集到该水印图片。Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
水印坐标和 setVideoEncoderConfiguration 方法中的设置有依赖关系:
- 如果视频编码方向/orientationMode 固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
- 如果视频编码方向/orientationMode 固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
- 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸,否则超出部分将被裁剪。
Note
- 你需要在调用 enableVideo 方法之后再调用本方法。
- 如果你只是在旁路直播(推流到CDN)中添加水印,你可以使用本方法或 setLiveTranscoding 方法设置水印。
- 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
- 如果你已经使用 startPreview 方法开启本地视频预览,那么本方法的 visibleInPreview 可设置水印在预览时是否可见。
- 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,Agora 建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
Declared In
AgoraRtcEngineKit.h
直播音视频流回退
– setRemoteUserPriority:type:
设置远端用户流的优先级
- (int)setRemoteUserPriority:(NSUInteger)uid type:(AgoraUserPriority)userPriority
参数
uid |
远端用户的 ID |
---|---|
userPriority |
远端用户的优先级,详见 AgoraUserPriority。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
如果将某个用户的优先级设为高,那么发给这个用户的音视频流的优先级就会高于其他用户。
弱网下 SDK 会优先保证高优先级用户收到的流的质量。
该方法需要在加入频道前调用。
Note:
目前仅支持将一名远端用户设为高优先级。
Declared In
AgoraRtcEngineKit.h
– setLocalPublishFallbackOption:
设置弱网条件下发布的音视频流回退选项
- (int)setLocalPublishFallbackOption:(AgoraStreamFallbackOptions)option
参数
option |
发布音视频流的回退选项,默认为不开启回退。详见 AgoraStreamFallbackOptions |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
网络不理想的环境下,发送音视频的质量都会下降。启用本地发布音视频流回退之后,SDK 会在上行弱网且音视频质量严重受影响时,自动关断视频流,从而保证或提高音频质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。 当本地发送的音视频流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发 本地发送的音视频流已回退为音频流 回调。
该方法需要在加入频道前调用。
Note:
旁路推流场景下,设置本地发布音视频流回退为仅音频流可能会导致远端的 CDN 用户听到音频的时间有所延迟。因此在有旁路推流的场景下,Agora 建议不要设置回退。
Declared In
AgoraRtcEngineKit.h
– setRemoteSubscribeFallbackOption:
设置弱网条件下订阅的音视频流回退选项
- (int)setRemoteSubscribeFallbackOption:(AgoraStreamFallbackOptions)option
参数
option |
订阅音视频流的回退选项,默认为弱网时回退到视频小流,详见 AgoraStreamFallbackOptions |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
网络不理想的环境下,订阅音视频的质量都会下降。使用该接口开启订阅音视频流的回退选项后,SDK 会在下行弱网且音视频质量严重受影响时,将视频流切换为小流,或关断视频流,从而保证或提高通信质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。当远端订阅流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发远端订阅流已回退为音频流回调。
该方法需要在加入频道前调用。
Declared In
AgoraRtcEngineKit.h
视频双流模式
– enableDualStreamMode:
开关视频双流模式
- (int)enableDualStreamMode:(BOOL)enabled
参数
enabled |
指定双流或者单流模式:
|
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
使用该方法设置单流(默认)或者双流模式。发送端开启双流模式后,接收端可以选择接收大流还是小流。 其中,大流指高分辨率、高码率的视频流,小流指低分辨率、低码率的视频流。
该方法在加入频道前后都能调用。
Declared In
AgoraRtcEngineKit.h
– setRemoteVideoStream:type:
设置订阅的视频流类型
- (int)setRemoteVideoStream:(NSUInteger)uid type:(AgoraVideoStreamType)streamType
参数
uid |
用户 ID |
---|---|
streamType |
设置视频流大小,AgoraVideoStreamType |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode(NO) 关闭双流模式,接收端可以选择接收大流还是小流。其中,大流可以接收高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需节约带宽和计算资源,则可以调用该方法动态调整对应远端视频流的大小。SDK 会根据该方法中的设置,切换大小流。
视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
调用本方法的执行结果将在 didApiCallExecute 中返回。
Note: 该方法在加入频道前后都能调用。如果既调用了 setRemoteVideoStream
,也调用了 setRemoteDefaultVideoStreamType,则 SDK 以 setRemoteVideoStream
中的设置为准。
Declared In
AgoraRtcEngineKit.h
– setRemoteDefaultVideoStreamType:
设置默认订阅的视频流类型
- (int)setRemoteDefaultVideoStreamType:(AgoraVideoStreamType)streamType
参数
streamType |
设置默认接收的视频流类型,详见 AgoraVideoStreamType 。 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法设置远端视频默认为大流或小流。
Note: 该方法在加入频道前后都能调用。如果既调用了 setRemoteDefaultVideoStreamType
,也调用了 setRemoteVideoStream,则 SDK 以 setRemoteVideoStream
中的设置为准。
Declared In
AgoraRtcEngineKit.h
加密
– enableEncryption:encryptionConfig:
开启或关闭内置加密。
- (int)enableEncryption:(bool)enabled encryptionConfig:(AgoraEncryptionConfig *)config
参数
enabled |
是否开启内置加密:
|
---|---|
config |
配置内置加密模式和密钥。详见 AgoraEncryptionConfig 。 |
返回
- 0: 方法调用成功
< 0: 方法调用失败
- -2 (
AgoraErrorCodeInvalidArgument
): 调用了无效的参数。需重新指定参数。 - -7 (
AgoraErrorCodeNotInitialized
): SDK 尚未初始化。需在调用 API 之前已创建AgoraRtcEngineKit
对象并完成初始化。 - -4 (
AgoraErrorCodeNotSupported
): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
- -2 (
Availability
v3.1.0
在安全要求较高的场景下,Agora 建议你在加入频道前,调用 enableEncryption
方法开启内置加密。
用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
自 v3.4.5 起,Agora 推荐使用 AgoraEncryptionModeAES128GCM2
或
AgoraEncryptionModeAES256GCM2
加密模式。这两种模式支持设置盐,安全性更高。
设置方法详见《媒体流加密》。
详情
Warning: 同一频道内所有用户必须使用相同的加密模式、密钥和盐,否则用户之间无法互通。
Note:
- 如果开启了内置加密,则不能使用 RTMP/RTMPS 推流功能。
- 为加强安全性,Agora 建议每次启用媒体流加密时都更换新的密钥和盐。
Declared In
AgoraRtcEngineKit.h
直播输入在线媒体流
– addInjectStreamUrl:config:
输入在线媒体流 URL
- (int)addInjectStreamUrl:(NSString *_Nonnull)url config:(AgoraLiveInjectStreamConfig *_Nonnull)config
参数
url |
添加到直播中的视频流 URL 地址, 支持 RTMP, HLS, HTTP-FLV 协议传输。
|
---|---|
config |
输入的视频流设置,详见 AgoraLiveInjectStreamConfig 。 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
AgoraErrorCodeInvalidArgument
(-2):输入的 URL 为空。请重新调用该方法,并确认输入的媒体流的 URL 是有效的。AgoraErrorCodeNotInitialized
(-7):引擎没有初始化。请确认调用该方法前已创建 RtcEngine 对象并完成初始化。AgoraErrorCodeNotSupported
(-4):频道非直播场景。请调用 setChannelProfile 并将频道设置为直播场景再调用该方法。AgoraErrorCodeNotReady
(-3):用户没有加入频道。
详情
该方法通过在服务端拉取视频流并发送到频道中,将正在播放的视频输入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。
调用该方法后,SDK 会在本地触发 streamInjectedStatusOfUrl 回调,报告输入在线媒体流的状态。
成功输入媒体流后,该音视频流会出现在频道中,频道内所有用户都会收到 didJoinedOfUid 回调,其中 uid 为 666。
Warning: 客户端输入在线媒体流功能即将停服。如果你尚未集成该功能,Agora 建议你不要使用。详见《部分服务下架计划》。
Note:
- 该方法需要在加入频道后调用。
- 频道内同一时间只允许输入一个在线媒体流。
- 请确保已开通旁路推流的功能,详见前提条件。
- 该方法适用于 Native SDK v2.4.1 及之后的版本。
Declared In
AgoraRtcEngineKit.h
– removeInjectStreamUrl:
删除输入的在线媒体流
- (int)removeInjectStreamUrl:(NSString *_Nonnull)url
参数
url |
已输入、待删除的在线媒体流 URL 地址 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
成功删除后会触发 didOfflineOfUid 回调,UID 为 666。
Warning: 客户端输入在线媒体流功能即将停服。如果你尚未集成该功能,Agora 建议你不要使用。详见《部分服务下架计划》。
Declared In
AgoraRtcEngineKit.h
CDN 旁路推流
– addPublishStreamUrl:transcodingEnabled:
增加旁路推流地址
- (int)addPublishStreamUrl:(NSString *_Nonnull)url transcodingEnabled:(BOOL)transcodingEnabled
参数
url |
CDN 推流地址,格式为 RTMP。该字符串长度不能超过 1024 字节。URL 不支持中文等特殊字符。 |
---|---|
transcodingEnabled |
|
返回
- 0: 方法调用成功
< 0: 方法调用失败
- AgoraErrorCodeInvalidArgument(-2):参数无效,一般是 URL 为空或是长度为 0 的的字符串
- AgoraErrorCodeNotInitialized(-7):推流时未初始化引擎
详情
该方法用于添加旁路推流地址,调用该方法后,你可以向 CDN 推送 RTMP 或 RTMPS 协议的媒体流。SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告增加旁路推流地址的状态。
Note:
- 该方法仅适用于直播场景。
- 请确保在成功加入频道后再调用该接口。
- 请确保已开通旁路推流的功能,详见前提条件。
- 该方法每次只能增加一路旁路推流地址。若需推送多路流,则需多次调用该方法。
- Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。
Declared In
AgoraRtcEngineKit.h
– removePublishStreamUrl:
删除旁路推流地址
- (int)removePublishStreamUrl:(NSString *_Nonnull)url
参数
url |
待删除的推流地址,格式为 RTMP。该字符串长度不能超过 1024 字节 |
---|
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法用于删除旁路推流过程中已经设置的 RTMP/RTMPS 推流地址。调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告删除旁路推流地址的状态。
Note:
- 该方法仅适用于直播场景。
- 该方法每次只能删除一路旁路推流地址。若需删除多路流,则需多次调用该方法。
- URL 不支持中文等特殊字符。
Declared In
AgoraRtcEngineKit.h
– setLiveTranscoding:
设置直播转码
- (int)setLiveTranscoding:(AgoraLiveTranscoding *_Nullable)transcoding
参数
transcoding |
一个 AgoraLiveTranscoding 的对象,详细设置见 AgoraLiveTranscoding 。 |
---|
返回
- 0: 方法调用成功;
- < 0: 方法调用失败。
详情
该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码设置后本地会触发 rtcEngineTranscodingUpdated 回调。
Note:
- 该方法需要在加入频道后调用。
- 该方法仅适用于直播场景。
- 请确保已开通 CDN 旁路推流的功能,详见前提条件。
- 首次调用该方法更新转码设置时,不会触发
rtcEngineTranscodingUpdated
回调。 - Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。
Declared In
AgoraRtcEngineKit.h
数据流
– createDataStream:config:
创建数据流。
- (int)createDataStream:(NSInteger *_Nonnull)streamId config:(AgoraDataStreamConfig *_Nonnull)config
参数
streamId |
数据流 ID。 |
---|---|
config |
数据流设置:AgoraDataStreamConfig 。 |
返回
- 创建数据流成功则返回数据流 ID。
- < 0: 创建数据流失败。
Availability
v3.3.0
该方法用于创建数据流。每个用户在每个频道内最多只能创建 5 个数据流。
该方法不支持数据可靠,接收方会丢弃超出发送时间 5 秒后的数据包。
Declared In
AgoraRtcEngineKit.h
– sendStreamMessage:data:
发送数据流
- (int)sendStreamMessage:(NSInteger)streamId data:(NSData *_Nonnull)data
参数
streamId |
数据流 ID, |
---|---|
data |
需要发送的消息 |
返回
- 0: 方法调用成功
- < 0: 方法调用失败
详情
该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制:频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。 每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 receiveStreamMessageFromUid 回调,远端用户可以在该回调中获取接收到的流消息;若调用失败,远端会触发 didOccurStreamMessageErrorFromUid 回调。
Note:
- 该方法仅适用于通信场景以及直播场景下的主播用户,如果直播场景下的观众调用此方法可能会造成观众变主播。
- 请确保在调用该方法前,已调用 createDataStream 创建了数据通道。
Declared In
AgoraRtcEngineKit.h
其他视频控制
– setCameraCapturerConfiguration:
设置摄像头采集配置
- (int)setCameraCapturerConfiguration:(AgoraCameraCapturerConfigu