多频道管理
介绍跟多频道相关的方法和回调。
RTC SDK 支持用户同时加入多个频道,可以同时在多个频道中接收和发布音视频流。
addVideoWatermarkEx
添加本地视频水印。
abstract addVideoWatermarkEx( watermarkUrl: string, options: WatermarkOptions, connection: RtcConnection ): number;
详情
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户、旁路直播观众和采集设备都能看到或采集到该水印图片。当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
- 如果视频编码方向(OrientationMode)固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
- 如果视频编码方向(OrientationMode)固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
- 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfigurationEx 方法中设置的视频尺寸,否则超出部分将被裁剪。
- 你需要在调用 enableVideo 方法之后再调用本方法。
- 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
- 如果你已经使用 startPreview 方法开启本地视频预览,那么本方法的
visibleInPreview
可设置水印在预览时是否可见。 - 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
- watermarkUrl
- 待添加的水印图片的本地路径。该方法支持从本地绝对/相对路径添加水印图片。
- options
- 待添加的水印图片的设置选项,详见 WatermarkOptions 。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustUserPlaybackSignalVolumeEx
调节本地播放的指定远端用户信号音量。
abstract adjustUserPlaybackSignalVolumeEx( uid: number, volume: number, connection: RtcConnection ): number;
详情
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
- 该方法需要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
- uid
- 远端用户 ID。
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
clearVideoWatermarkEx
删除已添加的视频水印。
abstract clearVideoWatermarkEx(connection: RtcConnection): number;
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
createDataStreamEx
创建数据流。
abstract createDataStreamEx( config: DataStreamConfig, connection: RtcConnection ): number;
详情
创建数据流。每个用户在每个频道中最多只能创建 5 个数据流。
相比 createDataStreamEx,本方法不支持数据可靠。接收方会丢弃超出发送时间 5 秒后的数据包。
参数
- config
- 数据流设置。详见 DataStreamConfig。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 创建的数据流的 ID:方法调用成功。
- < 0:方法调用失败。
enableAudioVolumeIndicationEx
启用用户音量提示。
abstract enableAudioVolumeIndicationEx( interval: number, smooth: number, reportVad: boolean, connection: RtcConnection ): number;
详情
该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。启用该方法后,只要频道内有发流用户,SDK 会在加入频道后按设置的时间间隔触发 onAudioVolumeIndication 回调。
参数
- interval
- 指定音量提示的时间间隔:
- ≤ 0: 禁用音量提示功能。
- > 0: 返回音量提示的间隔,单位为毫秒,最小取值为 50。
- smooth
- 平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
- reportVad
-
true
:开启本地人声检测功能。开启后,onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。false
:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableDualStreamModeEx
在发送端开启或关闭双流模式。
abstract enableDualStreamModeEx( enabled: boolean, streamConfig: SimulcastStreamConfig, connection: RtcConnection ): number;
详情
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStreamType 选择接收视频大流或视频小流。
参数
- enabled
-
是否开启双流模式:
true
: 开启双流模式。false
: (默认) 关闭双流模式。
- streamConfig
-
视频小流的配置。详见 SimulcastStreamConfig。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
getConnectionStateEx
获取当前网络连接状态。
abstract getConnectionStateEx(connection: RtcConnection): ConnectionStateType;
详情
该方法在加入频道前后都能调用。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
当前网络连接状态。详见 ConnectionStateType。
joinChannelEx
使用连接 ID 加入频道。
abstract joinChannelEx( token: string, connection: RtcConnection, options: ChannelMediaOptions ): number;
详情
调用该方法,你可以同时加入多个频道。
- 如果你已经在一个频道内,你不能用相同的用户 UID 再次加入该频道。
- 如果你想在不同的设备上加入相同的频道,请确保你在不同设备上使用的用户 UID 都不同。
- 请确保生成 Token 时传入的 app ID 和创建 IRtcEngine 实例时传入的 app ID 一致。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
- connection
- Connection 信息。详见 RtcConnection。
- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,ChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:IRtcEngine 对象初始化失败。你需要重新初始化 IRtcEngine 对象。
- -7:IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
- -8:IRtcEngine 对象内部状态错误。可能的原因是:调用 startEchoTest 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 onConnectionStateChanged 回调判断用户是否在频道中。除收到 ConnectionStateDisconnected(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelWithUserAccountEx
使用 User Account 加入频道,并设置是否自动订阅音频或视频流。
abstract joinChannelWithUserAccountEx( token: string, channelId: string, userAccount: string, options: ChannelMediaOptions ): number;
详情
- 本地:onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 onUserJoined 和 onUserInfoUpdated 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 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 字节,不可填 NULL。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
leaveChannelEx
设置频道选项并离开频道。
abstract leaveChannelEx( connection: RtcConnection, options?: LeaveChannelOptions ): number;
详情
离开频道,即挂断或退出通话。
调用 joinChannelEx 加入频道后,必须调用本方法结束通话,才能开始下一次通话。
不管当前是否在通话中,都可以调用该方法。该方法会把会话相关的所有资源释放掉。
调用该方法返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 onLeaveChannel 回调。
成功调用该方法离开频道后,本地会触发 onLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserOffline 回调。
- 如果你调用了本方法后立即调用 release 方法,SDK 将无法触发 onLeaveChannel 回调。
- 调用 leaveChannel 后会同时离开 joinChannel 和 joinChannelEx 加入的频道。
参数
- connection
- Connection 信息。详见 RtcConnection。
- options
-
离开频道的选项,详见 LeaveChannelOptions。
注: 该参数仅支持设置 LeaveChannelOptions 中的 stopMicrophoneRecording 成员,设置其他成员均不生效。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteAllRemoteAudioStreamsEx
取消或恢复订阅所有远端用户的音频流。
abstract muteAllRemoteAudioStreamsEx( mute: boolean, connection: RtcConnection ): number;
详情
成功调用该方法后,本地用户会取消或恢复订阅远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在加入频道后调用。
- 如果需要在加入频道前设置默认不订阅远端用户音频流,可以在调用 joinChannel 加入频道时设置 autoSubscribeAudio 为
false
。
参数
- mute
-
是否取消订阅所有远端用户的音频流:
true
: 取消订阅所有远端用户的音频流。false
:(默认)订阅所有远端用户的音频流。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteAllRemoteVideoStreamsEx
取消或恢复订阅所有远端用户的视频流。
abstract muteAllRemoteVideoStreamsEx( mute: boolean, connection: RtcConnection ): number;
详情
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流,包括在调用该方法后加入频道的用户的视频流。
参数
- mute
-
是否取消订阅所有远端用户的视频流。
true
: 取消订阅所有用户的视频流。false
:(默认)订阅所有用户的视频流。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteLocalAudioStreamEx
取消或恢复发布本地音频流。
abstract muteLocalAudioStreamEx( mute: boolean, connection: RtcConnection ): number;
详情
成功调用该方法后,远端会触发 onUserMuteAudio 回调和 onRemoteAudioStateChanged 回调。
参数
- mute
-
是否取消发布本地音频流。
true
: 取消发布。false
:(默认)发布。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteLocalVideoStreamEx
取消或恢复发布本地视频流。
abstract muteLocalVideoStreamEx( mute: boolean, connection: RtcConnection ): number;
详情
成功调用该方法后,远端会触发 onUserMuteVideo 回调。
- 该方法不影响视频采集状态,没有禁用摄像头。
参数
- mute
-
是否取消发送本地视频流。
true
: 取消发送本地视频流。false
: (默认)发送本地视频流。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteAudioStreamEx
停止/恢复接收指定的音频流。
abstract muteRemoteAudioStreamEx( uid: number, mute: boolean, connection: RtcConnection ): number;
详情
该方法停止/恢复接收某一个指定远端用户的音频流。在加入频道前或后都可以调用。该方法的设置在离开频道后失效。参数
- uid
- 指定用户的 ID。
- mute
-
是否停止接收指定音频流:
true
: 停止接收指定音频流。false
:(默认)继续接收指定音频流。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteVideoStreamEx
停止/恢复接收指定的视频流。
abstract muteRemoteVideoStreamEx( uid: number, mute: boolean, connection: RtcConnection ): number;
详情
该方法停止/恢复接收某一个指定远端用户的视频流。在加入频道前或后都可以调用。该方法的设置在离开频道后失效。
参数
- uid
-
远端用户的 ID。
- mute
-
是否停止接收某个远端用户的视频:
true
: 停止接收。false
: (默认)恢复接收。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pauseAllChannelMediaRelayEx
暂停向所有目标频道转发媒体流。
abstract pauseAllChannelMediaRelayEx(connection: RtcConnection): number;
详情
开始跨频道转发媒体流后,如果你需要暂停向所有频道转发媒体流,可以调用该方法;暂停后,如果要恢复跨频道媒体流转发,可以调用 resumeAllChannelMediaRelay 方法。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
resumeAllChannelMediaRelayEx
恢复向所有目标频道转发媒体流。
abstract resumeAllChannelMediaRelayEx(connection: RtcConnection): number;
详情
调用 pauseAllChannelMediaRelayEx 方法后,如果你需要恢复向所有目标频道转发媒体流,可以调用该方法。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
sendCustomReportMessageEx
自定义数据上报和分析服务。
abstract sendCustomReportMessageEx( id: string, category: string, event: string, label: string, value: number, connection: RtcConnection ): number;
详情
声网提供自定义数据上报和分析服务。该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据,每条自定义数据不能超过 256 字节,每个字符串不能超过 100 字节。如需试用该服务,请联系 sales@agora.io 开通并商定自定义数据格式。
sendStreamMessageEx
发送数据流。
abstract sendStreamMessageEx( streamId: number, data: Uint8Array, length: number, connection: RtcConnection ): number;
详情
调用 createDataStreamEx 后,你可以调用本方法向频道内所有用户发送数据流消息。
- 频道内每秒最多能发送 60 个包,且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 30 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 onStreamMessage 回调,远端用户可以在该回调中获取接收到的流消息; 若调用失败,远端会触发 onStreamMessageError 回调。
- 请确保在调用该方法前,已调用 createDataStreamEx 创建了数据通道。
- 该方法仅适用于通信场景以及直播场景下的主播用户,如果直播场景下的观众调用此方法可能会造成观众变主播。
参数
- streamId
- 数据流 ID。可以通过 createDataStreamEx 获取。
- data
- 待发送的数据。
- length
- 数据长度。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setDualStreamModeEx
在发送端设置双流模式。
abstract setDualStreamModeEx( mode: SimulcastStreamMode, streamConfig: SimulcastStreamConfig, connection: RtcConnection ): number;
详情
SDK 默认在发送端开启小流 auto 模式,效果等同于调用该方法并将 mode 设置为 AutoSimulcastStream。如果你想修改此行为,可以调用该方法并修改 mode 为 DisableSimulcastStream(始终不发送小流)或 EnableSimulcastStream(始终发送小流)。
- 调用该方法并设置 mode 为 DisableSimulcastStream 时,跟
enableDualStreamModeEx(false)
的效果相同。 - 调用该方法并设置 mode 为 EnableSimulcastStream 时,跟
enableDualStreamModeEx(true)
的效果相同。 - 两种方法均可在加入频道前后调用,若同时使用,则以后调用的方法中的设置为准。
参数
- mode
- 发送视频流的模式。详见 SimulcastStreamMode。
- streamConfig
-
视频小流的配置。详见 SimulcastStreamConfig。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVideoStreamTypeEx
设置订阅的视频流类型。
abstract setRemoteVideoStreamTypeEx( uid: number, streamType: VideoStreamType, connection: RtcConnection ): number;
详情
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamModeEx(false)
关闭双流模式,接收端可以调用该方法选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
SDK 默认在发送端开启小流 auto 模式(不主动发送小流),接收端主播可以调用本方法在接收端发起小流申请,发送端收到申请后自动切换为小流模式。
参数
- uid
- 用户 ID。
- streamType
-
视频流类型: VideoStreamType。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVideoSubscriptionOptionsEx
设置远端视频流的订阅选项。
abstract setRemoteVideoSubscriptionOptionsEx( uid: number, options: VideoSubscriptionOptions, connection: RtcConnection ): number;
详情
当远端发送双流时,可调用此方法来设置远端视频流的订阅选项。
参数
- uid
- 远端用户 ID。
- options
- 视频流的订阅设置,详见 VideoSubscriptionOptions。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setRemoteRenderModeEx
设置远端视图显示模式。
abstract setRemoteRenderModeEx( uid: number, renderMode: RenderModeType, mirrorMode: VideoMirrorModeType, connection: RtcConnection ): number;
详情
- 请在渲染了对应远端用户 ID 的 RtcSurfaceView 或 RtcTextureView 组件后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
- uid
- 远端用户 ID。
- renderMode
-
远端视图显示模式,详见 RenderModeType。
- mirrorMode
-
远端用户视图的镜像模式,详见 VideoMirrorModeType。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功
- < 0:方法调用失败
setRemoteVoicePositionEx
设置远端用户声音的 2D 位置,即水平面位置。
abstract setRemoteVoicePositionEx( uid: number, pan: number, gain: number, connection: RtcConnection ): number;
详情
设置远端用户声音的空间位置和音量,方便本地用户听声辨位。
通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。
- 为获得最佳听觉体验,建议用户佩戴有线耳机。
- 该方法需要在加入频道后调用。
参数
- uid
- 远端用户的 ID。
- pan
- 设置远端用户声音的空间位置,取值范围为 [-1.0,1.0]:
- -1.0: 声音出现在左边。
- (默认)0.0: 声音出现在正前方。
- 1.0: 声音出现在右边。
- gain
- 设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setSubscribeAudioBlocklistEx
设置音频订阅黑名单。
abstract setSubscribeAudioBlocklistEx( uidList: number[], uidNumber: number, connection: RtcConnection ): number;
详情
你可以调用该方法指定不订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅黑名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeAudioBlocklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 黑名单用户 ID 列表中的用户数量。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeAudioAllowlistEx
设置音频订阅白名单。
abstract setSubscribeAudioAllowlistEx( uidList: number[], uidNumber: number, connection: RtcConnection ): number;
详情
你可以调用该方法指定想要订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅白名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
音频订阅白名单的用户 ID 列表。
如果你想指定订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeAudioAllowlist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 白名单用户 ID 列表中的用户数量。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoBlocklistEx
设置视频订阅黑名单。
abstract setSubscribeVideoBlocklistEx( uidList: number[], uidNumber: number, connection: RtcConnection ): number;
详情
你可以调用该方法指定不订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅黑名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeVideoBlocklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 黑名单用户 ID 列表中的用户数量。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoAllowlistEx
设置视频订阅白名单。
abstract setSubscribeVideoAllowlistEx( uidList: number[], uidNumber: number, connection: RtcConnection ): number;
详情
你可以调用该方法指定想要订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅白名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅白名单的用户 ID 列表。
如果你想指定仅订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeVideoAllowlist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 白名单用户 ID 列表中的用户数量。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVideoEncoderConfigurationEx
设置本地视频编码属性。
abstract setVideoEncoderConfigurationEx( config: VideoEncoderConfiguration, connection: RtcConnection ): number;
详情
每一种视频编码属性对应一系列视频相关参数设置,包含分辨率、帧率和码率。
该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好,视频引擎便不能使用该 config 渲染本地视频,它会自动降低到一个合适的视频参数设置。
参数
- config
- 视频编码参数配置。详见 VideoEncoderConfiguration。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startOrUpdateChannelMediaRelayEx
开始或更新跨频道媒体流转发。
abstract startOrUpdateChannelMediaRelayEx( configuration: ChannelMediaRelayConfiguration, connection: RtcConnection ): number;
详情
首次成功调用该方法将开始跨频道转发媒体流。如需将流转发到多个目标频道,或退出当前的转发频道,可以再次调用该方法添加或移除转发的目标频道。
- 如果 onChannelMediaRelayStateChanged 回调报告 RelayStateRunning (2) 和 RelayOk (0), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 onChannelMediaRelayStateChanged 回调报告 RelayStateFailure (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 跨频道媒体流转发功能需要联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功
- < 0:方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: 方法调用被拒绝。可能因为 SDK 未初始化成功,或用户角色不是主播。
- -8:内部状态错误。可能因为用户角色不是主播。
startMediaRenderingTracingEx
开启视频帧渲染数据打点。
abstract startMediaRenderingTracingEx(connection: RtcConnection): number;
详情
成功调用该方法后,SDK 会以调用该方法的时刻作为起点,并通过 onVideoRenderingTracingResult 回调报告视频帧渲染的相关信息。
- SDK 默认在成功加入频道的时刻起打点,自动开始跟踪视频频的渲染事件。你可以根据实际业务场景,在合适的时机调用该方法,进行自定义打点。
- 离开当前频道后,SDK 会自动重置该时间点为下一次成功加入频道的时刻。
适用场景
声网推荐你将该方法和 app 中的 UI 设置(按钮、滑动条等)结合使用,用于针对终端用户的体验改进。例如:在终端用户在点击 加入频道
按钮的时刻调用该方法进行打点,然后通过 onVideoRenderingTracingResult 回调获取视频帧渲染过程中的指标,从而针对指标进行专项优化。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startRtmpStreamWithoutTranscodingEx
开始非转码推流。
abstract startRtmpStreamWithoutTranscodingEx( url: string, connection: RtcConnection ): number;
详情
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
调用该方法,你可以向指定的旁路推流地址推送直播音视频流。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告推流的状态。
- 请确保已开通旁路推流服务,详见旁路推流中的前提条件。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
- -19:该旁路推流 URL 已在使用中,请使用其他旁路推流 URL。
startRtmpStreamWithTranscodingEx
开始旁路推流并设置转码属性。
abstract startRtmpStreamWithTranscodingEx( url: string, transcoding: LiveTranscoding, connection: RtcConnection ): number;
详情
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
调用该方法,你可以向指定的旁路推流地址推送直播音视频流并设置转码属性。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告推流的状态。
- 请确保已开通旁路推流服务。详见旁路推流中的前提条件。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStreamEx,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- transcoding
-
旁路推流的转码属性,详见 LiveTranscoding 类。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
- -19:该旁路推流 URL 已在使用中,请使用其他旁路推流 URL。
stopRtmpStreamEx
结束旁路推流。
abstract stopRtmpStreamEx(url: string, connection: RtcConnection): number;
详情
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
调用该方法,你可以结束指定的旁路推流地址上的直播。该方法每次只能结束一个推流地址上的直播,如果你需要结束多个推流地址的直播,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告推流的状态。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateRtmpTranscodingEx
更新旁路推流转码属性。
abstract updateRtmpTranscodingEx( transcoding: LiveTranscoding, connection: RtcConnection ): number;
详情
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
开启转码推流后,你可以根据场景需求,动态更新转码属性。转码属性更新后,SDK 会触发 onTranscodingUpdated 回调。
参数
- transcoding
-
旁路推流的转码属性,详见 LiveTranscoding 类。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startChannelMediaRelayEx
开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
abstract startChannelMediaRelayEx( configuration: ChannelMediaRelayConfiguration, connection: RtcConnection ): number;
详情
- 弃用:
- 该方法已废弃。请改用 startOrUpdateChannelMediaRelayEx 。
- 如果 onChannelMediaRelayStateChanged 回调报告 RelayStateRunning (2) 和 RelayOk (0),且 onChannelMediaRelayEvent 回调报告 RelayEventPacketSentToDestChannel (4), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 onChannelMediaRelayStateChanged 回调报告 RelayStateFailure (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 成功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelayEx 方法退出当前的转发状态。
- 跨频道媒体流转发功能需要联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功
- < 0:方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: 方法调用被拒绝。可能因为 SDK 未初始化成功,或用户角色不是主播。
- -8:内部状态错误。可能因为用户角色不是主播。
stopChannelMediaRelayEx
停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。
abstract stopChannelMediaRelayEx(connection: RtcConnection): number;
详情
成功调用该方法后,SDK 会触发 onChannelMediaRelayStateChanged 回调。如果报告 RelayStateIdle (0) 和 RelayOk (0),则表示已停止转发媒体流。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
takeSnapshotEx
获取视频截图。
abstract takeSnapshotEx( connection: RtcConnection, uid: number, filePath: string ): number;
详情
该方法用于对指定用户的视频流进行截图,生成一张 JPG 格式的图片,并保存至指定的路径。
调用该方法返回时 SDK 并没有真正获取截图。成功调用该方法后,SDK 会触发 onSnapshotTaken 回调报告截图是否成功和获取截图的详情。
- 该方法需要在调用 joinChannelEx 后调用。
- 该方法用于本地视频截图时,是对 ChannelMediaOptions 中指定发布的视频流进行截图。
- 如果用户的视频经过前处理,例如,添加了水印或美颜,生成的截图会包含前处理效果。
参数
- connection
- Connection 信息。详见 RtcConnection。
- uid
- 用户 ID。如果要对本地用户的视频截图,则设为 0。
- filePath
-
截图的本地保存路径,需精确到文件名及格式, 例如:
- iOS:
/App Sandbox/Library/Caches/example.jpg
- Android:
/storage/emulated/0/Android/data/<package name>/files/example.jpg
- iOS:
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateChannelMediaOptionsEx
加入频道后更新频道媒体选项 。
abstract updateChannelMediaOptionsEx( options: ChannelMediaOptions, connection: RtcConnection ): number;
参数
- options
- 频道媒体选项,详见 ChannelMediaOptions。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:ChannelMediaOptions 结构体成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
- -8:IRtcEngine 对象内部状态错误。可能的原因是用户不在频道中。建议通过 onConnectionStateChanged 回调判断用户是否在频道中。如果收到 ConnectionStateDisconnected(1) 或 ConnectionStateFailed(5),则表示用户不在频道中。你需要在调用该方法前调用 joinChannel 加入频道。
updateChannelMediaRelayEx
更新媒体流转发的频道。
abstract updateChannelMediaRelayEx( configuration: ChannelMediaRelayConfiguration, connection: RtcConnection ): number;
详情
- 弃用:
- 该方法已废弃。请改用 startOrUpdateChannelMediaRelayEx。
成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。
成功调用该方法后,SDK 会触发 onChannelMediaRelayEvent 回调, 并在回调中报告状态码 RelayEventPacketUpdateDestChannel (7)。
onChannelMediaRelayStateChanged(RelayStateRunning, RelayOk)
后调用该方法;否则,方法调用会失败。参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功
- < 0:方法调用失败