多频道管理
介绍跟多频道相关的方法和回调。
RTC SDK 支持用户同时加入多个频道,可以同时在多个频道中接收和发布音视频流。
adjustUserPlaybackSignalVolumeEx
调节本地播放的指定远端用户信号音量。
- (int)adjustUserPlaybackSignalVolumeEx:(NSUInteger)uid volume:(NSInteger)volume connection:(AgoraRtcConnection* _Nonnull)connection;
详情
- 自从
- v4.1.0
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
- 该方法需要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
- uid
- 远端用户 ID。
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
addVideoWatermarkEx
添加本地视频水印。
- (int)addVideoWatermarkEx:(NSURL* _Nonnull)url options:(WatermarkOptions* _Nonnull)options connection:(AgoraRtcConnection * _Nonnull)connection;
详情
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户、旁路直播观众和采集设备都能看到或采集到该水印图片。当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
- 如果视频编码方向(AgoraVideoOutputOrientationMode)固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
- 如果视频编码方向(AgoraVideoOutputOrientationMode)固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
- 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfigurationEx 方法中设置的视频尺寸,否则超出部分将被裁剪。
- 你需要在调用 enableVideo 方法之后再调用本方法。
- 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
- 如果你已经使用 startPreview [2/2] 方法开启本地视频预览,那么本方法的
visibleInPreview
可设置水印在预览时是否可见。 - 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
- url
- 待添加的水印图片的本地路径。该方法支持从本地绝对/相对路径添加水印图片。
- options
- 待添加的水印图片的设置选项,详见 WatermarkOptions 。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
clearVideoWatermarkEx
删除已添加的视频水印。
- (int)clearVideoWatermarkEx:(AgoraRtcConnection * _Nonnull)connection;
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableAudioVolumeIndicationEx
启用用户音量提示。
- (int)enableAudioVolumeIndicationEx:(NSInteger)interval smooth:(NSInteger)smooth reportVad:(BOOL)reportVad connection:(AgoraRtcConnection* _Nonnull)connection NS_SWIFT_NAME(enableAudioVolumeIndicationEx(_:smooth:reportVad:connection:));
详情
该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。启用该方法后,只要频道内有发流用户,SDK 会在加入频道后按设置的时间间隔触发 reportAudioVolumeIndicationOfSpeakers 回调。
参数
- interval
- 指定音量提示的时间间隔:
- ≤ 0: 禁用音量提示功能。
- > 0: 返回音量提示的间隔,单位为毫秒,最小取值为 50。
- smooth
- 平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
- reportVad
-
YES
:开启本地人声检测功能。开启后,reportAudioVolumeIndicationOfSpeakers 回调的 vad 参数会报告是否在本地检测到人声。NO
:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,reportAudioVolumeIndicationOfSpeakers 回调的 vad 参数不会报告是否在本地检测到人声。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableDualStreamModeEx
在发送端开启或关闭双流模式。
- (int)enableDualStreamModeEx:(BOOL)enabled streamConfig:(AgoraSimulcastStreamConfig*)streamConfig connection:(AgoraRtcConnection* _Nonnull)connection;
详情
- 自从
- v4.0.1
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStream 选择接收视频大流或视频小流。
参数
- enabled
-
是否开启双流模式:
YES
: 开启双流模式。NO
: (默认) 关闭双流模式。
- streamConfig
-
视频小流的配置。详见 AgoraSimulcastStreamConfig。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
getConnectionStateEx
获取当前网络连接状态。
- (AgoraConnectionState)getConnectionStateEx:(AgoraRtcConnection * _Nonnull)connection;
详情
该方法在加入频道前后都能调用。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
当前网络连接状态。详见 AgoraConnectionState。
getUserInfoByUidEx
通过 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: 方法调用失败。
getUserInfoByUserAccountEx
通过 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 [1/2]
使用连接 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 鉴权。
注: 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 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 对象内部状态错误。可能的原因是:调用 startEchoTestWithConfig 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 connectionChangedToState 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelExByToken [2/2]
使用 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 鉴权。
注: 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 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 [1/2]
离开频道。
- (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock NS_SWIFT_NAME(leaveChannelEx(_:leaveChannelBlock:));
详情
离开频道,即挂断或退出通话。
调用 joinChannelExByToken [1/2] 加入频道后,必须调用本方法结束通话,才能开始下一次通话。
不管当前是否在通话中,都可以调用该方法。该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 didLeaveChannelWithStats 回调。
成功调用该方法离开频道后,本地会触发 didLeaveChannelWithStats 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 didOfflineOfUid 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 didLeaveChannelWithStats 回调。
- 调用 leaveChannel [1/2] 后会同时离开 joinChannelByToken [2/4] 和 joinChannelExByToken [1/2] 加入的频道。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
- leaveChannelBlock
-
成功离开频道的回调,提供通话相关的统计信息,详见 AgoraChannelStats。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
leaveChannelEx [2/2]
设置频道选项并离开频道。
- (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection options:(AgoraLeaveChannelOptions * _Nonnull)options leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock;
详情
离开频道,即挂断或退出通话。
调用 joinChannelExByToken [1/2] 加入频道后,必须调用本方法结束通话,才能开始下一次通话。
不管当前是否在通话中,都可以调用该方法。该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 didLeaveChannelWithStats 回调。
成功调用该方法离开频道后,本地会触发 didLeaveChannelWithStats 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 didOfflineOfUid 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 didLeaveChannelWithStats 回调。
- 调用 leaveChannel [2/2] 后会同时离开 joinChannelByToken [2/4] 和 joinChannelExByToken [1/2] 加入的频道。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
- options
-
- 自从
- v4.1.0
离开频道的选项,详见 AgoraLeaveChannelOptions。
注: 该参数仅支持设置 AgoraLeaveChannelOptions 中的 stopMicrophoneRecording 成员,设置其他成员均不生效。 - leaveChannelBlock
-
成功离开频道的回调,提供通话相关的统计信息,详见 AgoraChannelStats。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteAllRemoteAudioStreamsEx
取消或恢复订阅所有远端用户的音频流。
- (int)muteAllRemoteAudioStreamsEx:(BOOL)mute connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(muteAllRemoteAudioStreamsEx(_:connection:));
详情
成功调用该方法后,本地用户会取消或恢复订阅远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在加入频道后调用。
- 如果需要在加入频道前设置默认不订阅远端用户音频流,可以在调用 joinChannelByToken [2/4] 加入频道时设置 autoSubscribeAudio 为
NO
。 - 该方法的推荐设置详见设置订阅状态。
参数
- mute
-
是否取消订阅所有远端用户的音频流:
YES
: 取消订阅所有远端用户的音频流。NO
:(默认)订阅所有远端用户的音频流。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteAllRemoteVideoStreamsEx
取消或恢复订阅所有远端用户的视频流。
- (int)muteAllRemoteVideoStreamsEx:(BOOL)mute connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(muteAllRemoteVideoStreamsEx(_:connection:));
详情
- 自从
- v4.1.0
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流,包括在调用该方法后加入频道的用户的视频流。
参数
- mute
-
是否取消订阅所有远端用户的视频流。
YES
: 取消订阅所有用户的视频流。NO
:(默认)订阅所有用户的视频流。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteLocalAudioStreamEx
取消或恢复发布本地音频流。
- (int)muteLocalAudioStreamEx:(BOOL)mute connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(muteLocalAudioStreamEx(_:connection:));
详情
成功调用该方法后,远端会触发 didAudioMuted 回调和 remoteAudioStateChangedOfUid 回调。
参数
- mute
-
是否取消发布本地音频流。
YES
: 取消发布。NO
:(默认)发布。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteLocalVideoStreamEx
取消或恢复发布本地视频流。
- (int)muteLocalVideoStreamEx:(BOOL)mute connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(muteLocalVideoStreamEx(_:connection:));
详情
- 自从
- v4.1.0
成功调用该方法后,远端会触发 didVideoMuted 回调。
- 该方法不影响视频采集状态,没有禁用摄像头。
参数
- mute
-
是否取消发送本地视频流。
YES
: 取消发送本地视频流。NO
: (默认)发送本地视频流。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 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;
详情
该方法主动将视频帧数据用 AgoraOutputVideoFrame 类封装后传递给 SDK。请确保在你调用本方法前已调用 createCustomVideoTrack 获得视频轨道 ID。
参数
- frame
-
待推送的视频帧。详见 AgoraVideoFrame。
- videoTrackId
- 调用 createCustomVideoTrack 方法返回的视频轨道 ID。默认值为 0。
返回值
YES
:推送成功。NO
:推送失败。
resumeAllChannelMediaRelayEx
恢复向所有目标频道转发媒体流。
- (int)resumeAllChannelMediaRelayEx:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(resumeAllChannelMediaRelayEx(_:));
详情
调用 pauseAllChannelMediaRelayEx 方法后,如果你需要恢复向所有目标频道转发媒体流,可以调用该方法。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
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:方法调用失败
setRemoteVideoStreamEx
设置订阅的视频流类型。
- (int)setRemoteVideoStreamEx:(NSUInteger)uid type:(AgoraVideoStreamType)streamType connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(setRemoteVideoStreamEx(_:type:connection:));
详情
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamModeEx(NO)
关闭双流模式,接收端可以调用该方法选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
SDK 默认在发送端开启小流 auto 模式(不主动发送小流),接收端主播可以调用本方法在接收端发起小流申请,发送端收到申请后自动切换为小流模式。
参数
- uid
- 用户 ID。
- streamType
-
视频流类型: AgoraVideoStreamType。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVideoSubscriptionOptionsEx
设置远端视频流的订阅选项。
- (int)setRemoteVideoSubscriptionOptionsEx:(NSUInteger)uid options:(AgoraVideoSubscriptionOptions* _Nonnull)options connection:(AgoraRtcConnection* _Nonnull)connection NS_SWIFT_NAME(setRemoteVideoSubscriptionOptionsEx(_:options:connection:));
详情
当远端发送双流时,可调用此方法来设置远端视频流的订阅选项。
参数
- uid
- 远端用户 ID。
- options
- 视频流的订阅设置,详见 AgoraVideoSubscriptionOptions。
- 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: 方法调用失败
setSubscribeAudioBlocklistEx
设置音频订阅黑名单。
- (int)setSubscribeAudioBlocklistEx:(NSArray <NSNumber *> *_Nonnull)blocklist connection:(AgoraRtcConnection * _Nonnull)connection;
详情
你可以调用该方法指定不订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅黑名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeAudio 影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- blocklist
-
订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeAudioBlocklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeAudioAllowlistEx
设置音频订阅白名单。
- (int)setSubscribeAudioAllowlistEx:(NSArray <NSNumber *> *_Nonnull)allowlist connection:(AgoraRtcConnection * _Nonnull)connection;
详情
你可以调用该方法指定想要订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅白名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeAudio 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- allowlist
-
音频订阅白名单的用户 ID 列表。
如果你想指定订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeAudioAllowlist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoBlocklistEx
设置视频订阅黑名单。
- (int)setSubscribeVideoBlocklistEx:(NSArray <NSNumber *> *_Nonnull)blocklist connection:(AgoraRtcConnection * _Nonnull)connection;
详情
你可以调用该方法指定不订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅黑名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- blocklist
-
视频订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeVideoBlocklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoAllowlistEx
设置视频订阅白名单。
- (int)setSubscribeVideoAllowlistEx:(NSArray <NSNumber *> *_Nonnull)allowlist connection:(AgoraRtcConnection * _Nonnull)connection;
详情
你可以调用该方法指定想要订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅白名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
-
视频订阅白名单的用户 ID 列表。
如果你想指定仅订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeVideoAllowlist 方法更新音频订阅白名单的用户 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: 方法调用失败。
startChannelMediaRelayEx
开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
- (int)startChannelMediaRelayEx:(AgoraChannelMediaRelayConfiguration * _Nonnull)config connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(startChannelMediaRelayEx(_:connection:));
详情
- 弃用:
- 该方法已废弃。请改用 startOrUpdateChannelMediaRelayEx 。
- 如果 channelMediaRelayStateDidChange 回调报告 AgoraChannelMediaRelayStateRunning (2) 和 AgoraChannelMediaRelayErrorNone (0),且 didReceiveChannelMediaRelayEvent 回调报告 AgoraChannelMediaRelayEventSentToDestinationChannel (4), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 channelMediaRelayStateDidChange 回调报告 AgoraChannelMediaRelayStateFailure (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 成功调用该方法后,若你想再次调用该方法,必须先调用 StopChannelMediaRelayEx 方法退出当前的转发状态。
- 跨频道媒体流转发功能需要联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- config
- 跨频道媒体流转发参数配置。详见 AgoraChannelMediaRelayConfiguration。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0:方法调用成功
- < 0:方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: 方法调用被拒绝。可能因为 SDK 未初始化成功,或用户角色不是主播。
- -8:内部状态错误。可能因为用户角色不是主播。
startMediaRenderingTracingEx
开启视频帧渲染数据打点。
- (int)startMediaRenderingTracingEx:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(startMediaRenderingTracingEx(_:));
详情
- 自从
- v4.1.1
成功调用该方法后,SDK 会以调用该方法的时刻作为起点,并通过 videoRenderingTracingResultOfUid 回调报告视频帧渲染的相关信息。
- SDK 默认在成功加入频道的时刻起打点,自动开始跟踪视频频的渲染事件。你可以根据实际业务场景,在合适的时机调用该方法,进行自定义打点。
- 离开当前频道后,SDK 会自动重置该时间点为下一次成功加入频道的时刻。
适用场景
声网推荐你将该方法和 app 中的 UI 设置(按钮、滑动条等)结合使用,用于针对终端用户的体验改进。例如:在终端用户在点击 加入频道
按钮的时刻调用该方法进行打点,然后通过 videoRenderingTracingResultOfUid 回调获取视频帧渲染过程中的指标,从而针对指标进行专项优化。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startOrUpdateChannelMediaRelayEx
开始或更新跨频道媒体流转发。
- (int)startOrUpdateChannelMediaRelayEx:(AgoraChannelMediaRelayConfiguration * _Nonnull)config connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(startOrUpdateChannelMediaRelayEx(_:connection:));
详情
- 自从
- v4.2.0
首次成功调用该方法将开始跨频道转发媒体流。如需将流转发到多个目标频道,或退出当前的转发频道,可以再次调用该方法添加或移除转发的目标频道。该功能最多支持将媒体流转发至 6 个目标频道。
- 如果 channelMediaRelayStateDidChange 回调报告 AgoraChannelMediaRelayStateRunning (2) 和 AgoraChannelMediaRelayErrorNone (0), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 channelMediaRelayStateDidChange 回调报告 AgoraChannelMediaRelayStateFailure (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 跨频道媒体流转发功能需要联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- config
- 跨频道媒体流转发参数配置。详见 AgoraChannelMediaRelayConfiguration。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0:方法调用成功
- < 0:方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: 方法调用被拒绝。可能因为 SDK 未初始化成功,或用户角色不是主播。
- -8:内部状态错误。可能因为用户角色不是主播。
startRtmpStreamWithoutTranscodingEx
开始非转码推流。
- (int)startRtmpStreamWithoutTranscodingEx:(NSString* _Nonnull)url connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(startRtmpStreamWithoutTranscodingEx(_:connection:));
详情
- 自从
- v4.1.0
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
调用该方法,你可以向指定的旁路推流地址推送直播音视频流。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
- -19:该旁路推流 URL 已在使用中,请使用其他旁路推流 URL。
startRtmpStreamWithoutTranscodingEx
开始非转码推流。
- (int)startRtmpStreamWithoutTranscodingEx:(NSString* _Nonnull)url connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(startRtmpStreamWithoutTranscodingEx(_:connection:));
详情
- 自从
- v4.1.0
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
调用该方法,你可以向指定的旁路推流地址推送直播音视频流。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
- -19:该旁路推流 URL 已在使用中,请使用其他旁路推流 URL。
startRtmpStreamWithTranscodingEx
开始旁路推流并设置转码属性。
- (int)startRtmpStreamWithTranscodingEx:(NSString* _Nonnull)url transcoding:(AgoraLiveTranscoding* _Nullable)transcoding connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(startRtmpStreamWithTranscodingEx(_:transcoding:connection:));
详情
- 自从
- v4.1.0
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
调用该方法,你可以向指定的旁路推流地址推送直播音视频流并设置转码属性。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。
- 请确保已开通旁路推流服务。详见旁路推流中的前提条件。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStreamEx,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- transcoding
-
旁路推流的转码属性,详见 AgoraLiveTranscoding 类。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
- -19:该旁路推流 URL 已在使用中,请使用其他旁路推流 URL。
startRtmpStreamWithTranscodingEx
开始旁路推流并设置转码属性。
- (int)startRtmpStreamWithTranscodingEx:(NSString* _Nonnull)url transcoding:(AgoraLiveTranscoding* _Nullable)transcoding connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(startRtmpStreamWithTranscodingEx(_:transcoding:connection:));
详情
- 自从
- v4.1.0
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
调用该方法,你可以向指定的旁路推流地址推送直播音视频流并设置转码属性。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。
- 请确保已开通旁路推流服务。详见旁路推流中的前提条件。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStreamEx,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- transcoding
-
旁路推流的转码属性,详见 AgoraLiveTranscoding 类。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
- -19:该旁路推流 URL 已在使用中,请使用其他旁路推流 URL。
StopChannelMediaRelayEx
停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。
- (int)stopChannelMediaRelayEx:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(stopChannelMediaRelayEx(_:));
详情
成功调用该方法后,SDK 会触发 channelMediaRelayStateDidChange 回调。如果报告 AgoraChannelMediaRelayStateIdle (0) 和 AgoraChannelMediaRelayErrorNone (0),则表示已停止转发媒体流。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
stopRtmpStreamEx
结束旁路推流。
- (int)stopRtmpStreamEx:(NSString* _Nonnull)url connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(stopRtmpStreamEx(_:connection:));
详情
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
调用该方法,你可以结束指定的旁路推流地址上的直播。该方法每次只能结束一个推流地址上的直播,如果你需要结束多个推流地址的直播,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
takeSnapshotEx
获取视频截图。
- (NSInteger)takeSnapshotEx:(AgoraRtcConnection * _Nonnull)connection uid:(NSInteger)uid filePath:(NSString* _Nonnull)filePath;
详情
该方法用于对指定用户的视频流进行截图,生成一张 JPG 格式的图片,并保存至指定的路径。
该方法是异步操作,调用返回时 SDK 并没有真正获取截图。成功调用该方法后,SDK 会触发 snapshotTaken 回调报告截图是否成功和获取截图的详情。
- 该方法需要在调用 joinChannelExByToken [1/2] 后调用。
- 该方法用于本地视频截图时,是对 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 对象内部状态错误。可能的原因是用户不在频道中。建议通过 connectionChangedToState 回调判断用户是否在频道中。如果收到 AgoraConnectionStateDisconnected(1) 或 AgoraConnectionStateFailed(5),则表示用户不在频道中。你需要在调用该方法前调用 joinChannelByToken [2/4] 加入频道。
updateChannelMediaRelayEx
更新媒体流转发的频道。
- (int)updateChannelMediaRelayEx:(AgoraChannelMediaRelayConfiguration * _Nonnull)config connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(updateChannelMediaRelayEx(_:connection:));
详情
- 弃用:
- 该方法已废弃。请改用 startOrUpdateChannelMediaRelayEx。
成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。
成功调用该方法后,SDK 会触发 didReceiveChannelMediaRelayEvent 回调, 并在回调中报告状态码 AgoraChannelMediaRelayEventUpdateDestinationChannel (7)。
channelMediaRelayStateDidChange(AgoraChannelMediaRelayStateRunning, AgoraChannelMediaRelayErrorNone)
后调用该方法;否则,方法调用会失败。参数
- config
- 跨频道媒体流转发参数配置。详见 AgoraChannelMediaRelayConfiguration 。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0:方法调用成功
- < 0:方法调用失败
pauseAllChannelMediaRelayEx
暂停向所有目标频道转发媒体流。
- (int)pauseAllChannelMediaRelayEx:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(pauseAllChannelMediaRelayEx(_:));
详情
开始跨频道转发媒体流后,如果你需要暂停向所有频道转发媒体流,可以调用该方法;暂停后,如果要恢复跨频道媒体流转发,可以调用 resumeAllChannelMediaRelay 方法。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateRtmpTranscodingEx
更新旁路推流转码属性。
- (int)updateRtmpTranscodingEx:(AgoraLiveTranscoding* _Nullable)transcoding connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(updateRtmpTranscodingEx(_:connection:));
详情
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
开启转码推流后,你可以根据场景需求,动态更新转码属性。转码属性更新后,SDK 会触发 rtcEngineTranscodingUpdated 回调。
参数
- transcoding
-
旁路推流的转码属性,详见 AgoraLiveTranscoding 类。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。