AgoraRtcEngineKit(Ex)
提供多频道方法的接口类。
继承自 AgoraRtcEngineKit。
addVideoWatermarkEx
添加本地视频水印。
- (int)addVideoWatermarkEx:(NSURL* _Nonnull)url options:(WatermarkOptions* _Nonnull)options connection:(AgoraRtcConnection * _Nonnull)connection;
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户、旁路直播观众和采集设备都能看到或采集到该水印图片。 Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
- 如果视频编码方向(AgoraVideoOutputOrientationMode)固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
- 如果视频编码方向(AgoraVideoOutputOrientationMode)固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
- 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfigurationEx 方法中设置的视频尺寸,否则超出部分将被裁剪。
- 你需要在调用 enableVideo 方法之后再调用本方法。
- 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
- 如果你已经使用 startPreview 方法开启本地视频预览,那么本方法的
visibleInPreview
可设置水印在预览时是否可见。 - 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,Agora 建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
- url
- 待添加的水印图片的本地路径。该方法支持从本地绝对/相对路径添加水印图片。
- options
- 待添加的水印图片的设置选项,详见 WatermarkOptions 。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
clearVideoWatermarkEx
删除已添加的视频水印。
- (int)clearVideoWatermarkEx:(AgoraRtcConnection * _Nonnull)connection;
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableDualStreamModeEx
在发送端开启或关闭双流模式。
- (int)enableDualStreamModeEx:(BOOL)enabled streamConfig:(AgoraSimulcastStreamConfig*)streamConfig connection:(AgoraRtcConnection* _Nonnull)connection;
- 自从
- v4.0.1
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStream 选择接收视频大流或视频小流。
- 该方法适用于发送端发送的所有类型的流,包括且不限于来自摄像头采集的视频流、屏幕共享流、自定义采集的视频流。
- 如果需要在多频道场景下开启视频双流,可以调用 enableDualStreamModeEx 方法。
- 该方法可以在加入频道前后调用。
参数
- enabled
-
是否开启双流模式:
YES
: 开启双流模式。NO
: (默认) 关闭双流模式。
- streamConfig
-
视频小流的配置。详见 AgoraSimulcastStreamConfig。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
getConnectionStateEx
获取当前网络连接状态。
- (AgoraConnectionState)getConnectionStateEx:(AgoraRtcConnection * _Nonnull)connection;
该方法在加入频道前后都能调用。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
当前网络连接状态。详见 AgoraConnectionState。
getUserInfoWithUserId
通过 UID 获取用户信息。
- (int)getUserInfoWithUserId:(NSUInteger)uid userInfo:(AgoraUserInfo *_Nullable* _Nullable)userInfo channelId:(NSString* _Nonnull)channelId localUserAccount:(NSString* _Nonnull)localUserAccount;
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 didUserInfoUpdatedWithUserId 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 AgoraUserInfo 对象。
参数
- uid
- 用户 ID。
- userInfo
- 标识用户信息的 AgoraUserInfo 对象。
- 输入值:一个 AgoraUserInfo 对象。
- 输出值:一个包含了用户 User Account 和 UID 的 AgoraUserInfo 对象。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- localUserAccount
- 本地用户的 User Account。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getUserInfoWithUserAccount
通过 User Account 获取用户信息。
- (int)getUserInfoWithUserAccount:(NSString * _Nonnull)userAccount userInfo:(AgoraUserInfo *_Nullable* _Nullable)userInfo channelId:(NSString* _Nonnull)channelId localUserAccount:(NSString* _Nonnull)localUserAccount;
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 didUserInfoUpdatedWithUserId 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 AgoraUserInfo 对象。
参数
- userAccount
- 用户 User Account。
- userInfo
- 标识用户信息的 AgoraUserInfo 对象。
- 输入值:一个 AgoraUserInfo 对象。
- 输出值:一个包含了用户 User Account 和 UID 的 AgoraUserInfo 对象。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- localUserAccount
- 本地用户的 User Account。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
joinChannelExByToken
使用连接 ID 加入频道。
- (int)joinChannelExByToken:(NSString* _Nullable)token connection:(AgoraRtcConnection * _Nonnull)connection delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate mediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions joinSuccess:(void(^ _Nullable)(NSString* _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
调用该方法,你可以同时加入多个频道。
- 如果你已经在一个频道内,你不能用相同的用户 UID 再次加入该频道。
- 如果你想在不同的设备上加入相同的频道,请确保你在不同设备上使用的用户 UID 都不同。
- 请确保生成 Token 时传入的 app ID 和创建 AgoraRtcEngineKit 实例时传入的 app ID 一致。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
- connection
- Connection 信息。详见 AgoraRtcConnection。
- mediaOptions
- 频道媒体设置选项。详见 AgoraRtcChannelMediaOptions。
- delegate
- AgoraRtcEngineKit(Ex) 的回调类,详见 AgoraRtcEngineDelegate。
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,AgoraRtcChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是:调用 startEchoTestWithInterval 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。Agora 推荐通过 connectionChangedToState 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelExByToken
使用 User Account 加入频道,并设置是否自动订阅音频或视频流。
- (int)joinChannelExByToken:(NSString* _Nullable)token channelId:(NSString* _Nonnull)channelId userAccount:(NSString* _Nonnull)userAccount delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate mediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions joinSuccess:(void(^ _Nullable)(NSString* _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
- 本地:didLocalUserRegisteredWithUserId、didJoinChannel 和 connectionChangedToState 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 didJoinedOfUid 和 didUserInfoUpdatedWithUserId 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- userAccount
-
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 nil。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- mediaOptions
- 频道媒体设置选项。详见 AgoraRtcChannelMediaOptions。
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
leaveChannelEx
离开频道。
- (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock;
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
- leaveChannelBlock
-
成功离开频道的回调,提供通话相关的统计信息,详见 AgoraChannelStats 。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteRemoteAudioStreamEx
停止/恢复接收指定的音频流。
- (int)muteRemoteAudioStreamEx:(NSUInteger)uid mute:(BOOL)mute connection:(AgoraRtcConnection * _Nonnull)connection;
参数
- uid
- 指定用户的 ID。
- mute
-
是否停止接收指定音频流:
YES
: 停止接收指定音频流。NO
:(默认)继续接收指定音频流。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteVideoStreamEx
停止/恢复接收指定的视频流。
- (int)muteRemoteVideoStreamEx:(NSUInteger)uid mute:(BOOL)mute connection:(AgoraRtcConnection * _Nonnull)connection;
该方法停止/恢复接收某一个指定远端用户的视频流。在加入频道前或后都可以调用。该方法的设置在离开频道后失效。
参数
- uid
-
远端用户的 ID。
- mute
-
是否停止接收某个远端用户的视频:
YES
: 停止接收。NO
: (默认)恢复接收。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pushExternalVideoFrame
推送外部原始视频帧到 SDK。
- (BOOL)pushExternalVideoFrame:(AgoraVideoFrame * _Nonnull)frame videoTrackId:(NSUInteger)videoTrackId;
调用 setExternalVideoSource 方法,设置 enabled 参数为 YES
、encodedFrame 参数为 NO
后,你可以调用本方法将未编码的外部视频帧推送到 SDK。
参数
- frame
-
待推送的视频帧。详见 AgoraVideoFrame。
- videoTrackId
- 调用 createCustomVideoTrack 方法返回的视频轨道 ID。默认值为 0。
返回值
YES
:推送成功。NO
:推送失败。
sendCustomReportMessageEx
自定义数据上报和分析服务。
- (int)sendCustomReportMessageEx:(NSString * _Nullable)messageId category:(NSString * _Nullable)category event:(NSString * _Nullable)event label:(NSString * _Nullable)label value:(NSInteger)value connection:(AgoraRtcConnection * _Nonnull)connection;
声网提供自定义数据上报和分析服务。该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据,每条自定义数据不能超过 256 字节,每个字符串不能超过 100 字节。如需试用该服务,请联系 sales@agora.io 开通并商定自定义数据格式。
setDualStreamModeEx
在发送端设置双流模式。
- (int)setDualStreamModeEx:(AgoraSimulcastStreamMode)mode streamConfig:(AgoraSimulcastStreamConfig*)streamConfig connection:(AgoraRtcConnection* _Nonnull)connection;
- 自从
- v4.0.1
SDK 默认在发送端开启小流 auto 模式,效果等同于调用该方法并将 mode 设置为 AgoraAutoSimulcastStream。如果你想修改此行为,可以调用该方法并修改 mode 为 AgoraDisableSimulcastStream(始终不发送小流)或 AgoraEnableSimulcastStream(始终发送小流)。
- 调用该方法并设置 mode 为 AgoraDisableSimulcastStream 时,跟
enableDualStreamModeEx(NO)
的效果相同。 - 调用该方法并设置 mode 为 AgoraEnableSimulcastStream 时,跟
enableDualStreamModeEx(YES)
的效果相同。 - 两种方法均可在加入频道前后调用,若同时使用,则以后调用的方法中的设置为准。
参数
- mode
- 发送视频流的模式。详见 AgoraSimulcastStreamMode。
- streamConfig
-
视频小流的配置。详见 AgoraSimulcastStreamConfig。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteRenderModeEx
设置远端视图显示模式。
- (int)setRemoteRenderModeEx:(NSUInteger)uid mode:(AgoraVideoRenderMode)mode mirror:(AgoraVideoMirrorMode)mirror connection:(AgoraRtcConnection * _Nonnull)connection;
- 请在调用 setupRemoteVideo 方法初始化远端视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
- uid
- 远端用户 ID。
- renderMode
-
远端视图显示模式,详见 AgoraVideoRenderMode。
- mirrorMode
-
远端用户视图的镜像模式,详见 AgoraVideoMirrorMode。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRemoteVoicePositionEx
设置远端用户声音的 2D 位置,即水平面位置。
- (int)setRemoteVoicePosition:(NSUInteger)uid pan:(double)pan gain:(double)gain connection:(AgoraRtcConnection * _Nonnull)connection;
设置远端用户声音的空间位置和音量,方便本地用户听声辨位。
通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。
- 为获得最佳听觉体验,我们建议用户佩戴有线耳机。
- 该方法需要在加入频道后调用。
参数
- uid
- 远端用户的 ID。
- pan
- 设置远端用户声音的空间位置,取值范围为 [-1.0,1.0]:
- -1.0: 声音出现在左边。
- (默认)0.0: 声音出现在正前方。
- 1.0: 声音出现在右边。
- gain
- 设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setSubscribeAudioBlacklistEx
设置音频订阅黑名单。
- (int)setSubscribeAudioBlacklistEx:(NSArray <NSNumber *> *_Nonnull)blacklist connection:(AgoraRtcConnection * _Nonnull)connection;
你可以调用该方法指定不订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅黑名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeAudio 影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- blacklist
-
订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeAudioBlacklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeAudioWhitelistEx
设置音频订阅白名单。
- (int)setSubscribeAudioWhitelistEx:(NSArray <NSNumber *> *_Nonnull)whitelist connection:(AgoraRtcConnection * _Nonnull)connection;
你可以调用该方法指定想要订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅白名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeAudio 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- whitelist
-
音频订阅白名单的用户 ID 列表。
如果你想指定订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeAudioWhitelist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoBlacklistEx
设置视频订阅黑名单。
- (int)setSubscribeVideoBlacklistEx:(NSArray <NSNumber *> *_Nonnull)blacklist connection:(AgoraRtcConnection * _Nonnull)connection;
你可以调用该方法指定不订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅黑名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- blacklist
-
视频订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeVideoBlacklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoWhitelistEx
设置视频订阅白名单。
- (int)setSubscribeVideoWhitelistEx:(NSArray <NSNumber *> *_Nonnull)whitelist connection:(AgoraRtcConnection * _Nonnull)connection;
你可以调用该方法指定想要订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅白名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
-
视频订阅白名单的用户 ID 列表。
如果你想指定仅订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeVideoWhitelist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setupRemoteVideoEx
初始化远端用户视图。
- (int)setupRemoteVideoEx:(AgoraRtcVideoCanvas* _Nonnull)remote connection:(AgoraRtcConnection * _Nonnull)connection;
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。
调用该方法时需要在 AgoraRtcVideoCanvas 中指定远端视频的用户 ID,一般可以在进频道前提前设置好。
如果无法在加入频道前得到远端用户的 uid,可以在收到 didJoinedOfUid 回调时调用该方法。如果启用了视频录制功能,视频录制服务会做为一个哑客户端加入频道,因此其他客户端也会收到它的 onUserJoined
事件, App 不应给它绑定视图(因为它不会发送视频流)。
如需解除某个远端用户的绑定视图,可以调用该方法并将 view 设置为空。
离开频道后,SDK 会清除远端用户视图的绑定关系。
如果你希望在通话中更新远端用户视图的渲染或镜像模式,请使用 setRemoteRenderModeEx 方法。
参数
- remote
-
视频画布信息。详见 AgoraRtcVideoCanvas。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setVideoEncoderConfigurationEx
设置本地视频编码属性。
- (int)setVideoEncoderConfigurationEx:(AgoraVideoEncoderConfiguration* _Nonnull)config connection:(AgoraRtcConnection * _Nonnull)connection;
每一种视频编码属性对应一系列视频相关参数设置,包含分辨率、帧率和码率。
该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好,视频引擎便不能使用该 config 渲染本地视频, 它会自动降低到一个合适的视频参数设置。
参数
- config
- 视频编码参数配置。详见 AgoraVideoEncoderConfiguration。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
takeSnapshotEx
获取视频截图。
- (NSInteger)takeSnapshotEx:(AgoraRtcConnection * _Nonnull)connection uid:(NSInteger)uid filePath:(NSString* _Nonnull)filePath;
该方法用于对指定用户的视频流进行截图,生成一张 JPG 格式的图片,并保存至指定的路径。
该方法是异步操作,调用返回时 SDK 并没有真正获取截图。成功调用该方法后,SDK 会触发 snapshotTaken 回调报告截图是否成功和获取截图的详情。
- 该方法需要在调用 joinChannelExByToken 后调用。
- 该方法对 AgoraRtcChannelMediaOptions 中指定发布的视频流进行截图。
- 如果用户的视频经过前处理,例如,添加了水印或美颜,生成的截图会包含前处理效果。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
- uid
- 用户 ID。如果要对本地用户的视频截图,则设为 0。
- filePath
-
截图的本地保存路径,需精确到文件名及格式, 例如:
- iOS:
/App Sandbox/Library/Caches/example.jpg
- iOS:
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateChannelExWithMediaOptions
加入频道后更新频道媒体选项 。
- (int)updateChannelExWithMediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions connection:(AgoraRtcConnection * _Nonnull)connection;
参数
- options
- 频道媒体选项,详见 AgoraRtcChannelMediaOptions。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:AgoraRtcChannelMediaOptions 结构体成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是用户不在频道中。Agora 推荐通过 connectionChangedToState 回调判断用户是否在频道中。如果收到 AgoraConnectionStateDisconnected(1) 或 AgoraConnectionStateFailed(5),则表示用户不在频道中。你需要在调用该方法前调用 joinChannelByToken [2/4] 加入频道。