音视频流管理
介绍音视频数据流的管理方法和回调。
EnableDualStreamMode [1/2]
在发送端开启或关闭双流模式。
public abstract int EnableDualStreamMode(bool enabled);
详情
- 弃用:
- 从 v4.2.0 起废弃,请改用 SetDualStreamMode [1/2]。
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 SetRemoteVideoStreamType 选择接收视频大流或视频小流。
- 该方法适用于发送端发送的所有类型的流,包括且不限于来自摄像头采集的视频流、屏幕共享流、自定义采集的视频流。
- 如果需要在多频道场景下开启视频双流,可以调用 EnableDualStreamModeEx 方法。
- 该方法可以在加入频道前后调用。
参数
- enabled
-
是否开启双流模式。
true
: 开启双流模式。false
: (默认) 关闭双流模式。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
EnableDualStreamMode [2/2]
在发送端开启或关闭双流模式并设置视频小流。
public abstract int EnableDualStreamMode(bool enabled, SimulcastStreamConfig streamConfig);
详情
- 弃用:
- 从 v4.2.0 起废弃,请改用 SetDualStreamMode [2/2]。
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 SetRemoteVideoStreamType 选择接收视频大流或视频小流。
- 该方法适用于发送端发送的所有类型的流,包括且不限于来自摄像头采集的视频流、屏幕共享流、自定义采集的视频流。
- 如果需要在多频道场景下开启视频双流,可以调用 EnableDualStreamModeEx 方法。
- 该方法可以在加入频道前后调用。
参数
- enabled
-
是否开启双流模式:
true
: 开启双流模式。false
: (默认) 关闭双流模式。
- streamConfig
-
视频小流的配置。详见 SimulcastStreamConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
MuteAllRemoteAudioStreams
取消或恢复订阅所有远端用户的音频流。
public abstract int MuteAllRemoteAudioStreams(bool mute);
详情
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在加入频道后调用。
- 如果需要在加入频道前设置默认不订阅远端用户音频流,可以在调用 JoinChannel [2/2] 加入频道时设置 autoSubscribeAudio 为
false
。
参数
- mute
-
是否取消订阅所有远端用户的音频流:
true
: 取消订阅所有远端用户的音频流。false
:(默认)订阅所有远端用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
MuteAllRemoteVideoStreams
取消或恢复订阅所有远端用户的视频流。
public abstract int MuteAllRemoteVideoStreams(bool mute);
详情
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流,包括在调用该方法后加入频道的用户的视频流。
- 该方法需要在加入频道后调用。
- 如果需要在加入频道前设置默认不订阅远端用户视频流,可以在调用 JoinChannel [2/2] 加入频道时设置 autoSubscribeVideo 为
false
。
参数
- mute
-
是否取消订阅所有远端用户的视频流。
true
: 取消订阅所有用户的视频流。false
:(默认)订阅所有用户的视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
MuteLocalAudioStream
取消或恢复发布本地音频流。
public abstract int MuteLocalAudioStream(bool mute);
详情
成功调用该方法后,远端会触发 OnUserMuteAudio 回调和 OnRemoteAudioStateChanged 回调。
参数
- mute
-
是否取消发布本地音频流。
true
: 取消发布。false
:(默认)发布。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
MuteLocalVideoStream
取消或恢复发布本地视频流。
public abstract int MuteLocalVideoStream(bool mute);
详情
成功调用该方法后,远端会触发 OnUserMuteVideo 回调。
- 相比于 EnableLocalVideo(
false
) 用于控制本地视频流发送的方法,该方法响应速度更快。 - 该方法不影响视频采集状态,没有禁用摄像头。
参数
- mute
-
是否取消发送本地视频流。
true
: 取消发送本地视频流。false
: (默认)发送本地视频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
MuteRemoteAudioStream
取消或恢复订阅指定远端用户的音频流。
public abstract int MuteRemoteAudioStream(uint uid, bool mute);
详情
- 该方法需要在加入频道后调用。
参数
- uid
- 指定用户的用户 ID。
- mute
-
是否取消订阅指定远端用户的音频流。
true
: 取消订阅指定用户的音频流。false
:(默认)订阅指定用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
MuteRemoteVideoStream
取消或恢复订阅指定远端用户的视频流。
public abstract int MuteRemoteVideoStream(uint uid, bool mute);
详情
- 该方法需要在加入频道后调用。
参数
- uid
- 指定用户的用户 ID。
- mute
-
是否取消订阅指定远端用户的视频流。
true
: 取消订阅指定用户的视频流。false
: (默认)订阅指定用户的视频流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
PauseAllChannelMediaRelay
暂停向所有目标频道转发媒体流。
public abstract int PauseAllChannelMediaRelay();
详情
开始跨频道转发媒体流后,如果你需要暂停向所有频道转发媒体流,可以调用该方法;暂停后,如果要恢复跨频道媒体流转发,可以调用 ResumeAllChannelMediaRelay 方法。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
ResumeAllChannelMediaRelay
恢复向所有目标频道转发媒体流。
public abstract int ResumeAllChannelMediaRelay();
详情
调用 PauseAllChannelMediaRelay 方法后,如果你需要恢复向所有目标频道转发媒体流,可以调用该方法。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
SetDualStreamMode [1/2]
在发送端设置双流模式。
public abstract int SetDualStreamMode(SIMULCAST_STREAM_MODE mode);
详情
- 如果你想修改此行为,可以调用该方法并修改 mode 为 DISABLE_SIMULCAST_STREAM(始终不发送小流)或 ENABLE_SIMULCAST_STREAM(始终发送小流)。
- 如果你在进行修改后又想恢复该默认行为,可重新调用该方法,并将 mode 设置为 AUTO_SIMULCAST_STREAM。
- 调用该方法并设置 mode 为 DISABLE_SIMULCAST_STREAM 时,跟
EnableDualStreamMode [1/2](false)
的效果相同。 - 调用该方法并设置 mode 为 ENABLE_SIMULCAST_STREAM 时,跟
EnableDualStreamMode [1/2](true)
的效果相同。 - 两种方法均可在加入频道前后调用,若同时使用,则以后调用的方法中的设置为准。
参数
- mode
- 发送视频流的模式。详见 SIMULCAST_STREAM_MODE。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
SetDualStreamMode [2/2]
在发送端设置双流模式并设置视频小流。
public abstract int SetDualStreamMode(SIMULCAST_STREAM_MODE mode, SimulcastStreamConfig streamConfig);
详情
- 如果你想修改此行为,可以调用该方法并修改 mode 为 DISABLE_SIMULCAST_STREAM(始终不发送小流)或 ENABLE_SIMULCAST_STREAM(始终发送小流)。
- 如果你在进行修改后又想恢复该默认行为,可重新调用该方法,并将 mode 设置为 AUTO_SIMULCAST_STREAM。
该方法跟 SetDualStreamMode [1/2] 的区别在于,该方法还可以进行视频小流的配置,SDK 会根据 streamConfig 中的配置发送小流。
- 调用该方法并设置 mode 为 DISABLE_SIMULCAST_STREAM 时,跟调用 并设置 enabled 为
false
的效果相同。 - 调用该方法并设置 mode 为 ENABLE_SIMULCAST_STREAM 时,跟调用 并设置 enabled 为
true
的效果相同。 - 两种方法均可在加入频道前后调用,若同时使用,则以后调用的方法中的设置为准。
参数
- mode
- 发送视频流的模式。详见 SIMULCAST_STREAM_MODE。
- streamConfig
-
视频小流的配置。详见 SimulcastStreamConfig。
注: 当设置 mode 为 DISABLE_SIMULCAST_STREAM 时,再设置 streamConfig 不会生效。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
SetRemoteDefaultVideoStreamType
设置默认订阅的视频流类型。
public abstract int SetRemoteDefaultVideoStreamType(VIDEO_STREAM_TYPE streamType);
详情
在网络条件受限的情况下,如果发送端没有调用 EnableDualStreamMode [2/2] (false)
关闭双流模式,接收端可以选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需默认接收所有用户的视频小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
SDK 默认在发送端开启小流 auto 模式(不主动发送小流),主播身份的接收端可以调用本方法在接收端发起小流申请(观众角色的接收端调用该方法不生效),发送端收到申请后自动切换为小流模式。
- 该方法只能在加入频道前调用。SDK 不支持你在加入频道后修改默认订阅的视频流类型。
- 如果你既调用了该方法,也调用了 SetRemoteVideoStreamType,则 SDK 以 SetRemoteVideoStreamType 中的设置为准。
参数
- streamType
-
默认订阅的视频流类型: VIDEO_STREAM_TYPE。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
SetRemoteVideoStreamType
设置订阅的视频流类型。
public abstract int SetRemoteVideoStreamType(uint uid, VIDEO_STREAM_TYPE streamType);
详情
在网络条件受限的情况下,如果发送端没有调用 EnableDualStreamMode [2/2](false)
关闭双流模式,接收端可以调用该方法选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
SDK 默认在发送端开启小流 auto 模式(不主动发送小流),主播身份的接收端可以调用本方法在接收端发起小流申请(观众角色的接收端调用该方法不生效),发送端收到申请后自动切换为小流模式。
参数
- uid
- 用户 ID。
- streamType
-
视频流类型: VIDEO_STREAM_TYPE。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
SetRemoteVideoSubscriptionOptions
设置远端视频流的订阅选项。
public abstract int SetRemoteVideoSubscriptionOptions(uint uid, VideoSubscriptionOptions options);
详情
当远端发送双流时,可调用此方法来设置远端视频流的订阅选项。
- 如果你只注册了 IVideoFrameObserver 对象,则默认订阅原始视频数据和编码后的视频数据 (效果等同于 encodedFrameOnly 设置为
false
)。 - 如果你只注册了 IVideoEncodedFrameObserver 对象,则默认只订阅编码后的视频数据 (效果等同于 encodedFrameOnly 设置为
true
)。 - 如果你先后注册了 IVideoFrameObserver 和 IVideoEncodedFrameObserver 对象,则默认订阅原始视频数据和编码后的视频数据 (效果等同于 encodedFrameOnly 设置为
false
)。 - 如果你先调用该方法设置了 options 参数、然后再注册 IVideoFrameObserver 或 IVideoEncodedFrameObserver 对象,则需要再次调用该方法并按照以上两项描述设置 options 参数,以获得预期的效果。
- 调用 JoinChannel [2/2] 加入频道时设置 autoSubscribeVideo 为
false
。 - 在收到 OnUserJoined 回调后调用该方法,设置对指定远端用户视频流的订阅选项。
- 调用 MuteRemoteVideoStream 方法,开始恢复订阅指定远端用户的视频流。如果你在上一步中将 encodedFrameOnly 设置为
true
,SDK 会在本地触发 OnEncodedVideoFrameReceived 回调,上报接收到的编码后视频帧信息。
参数
- uid
- 远端用户 ID。
- options
- 视频流的订阅设置,详见 VideoSubscriptionOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
SetSubscribeAudioBlocklist
设置音频订阅黑名单。
public abstract int SetSubscribeAudioBlocklist(uint[] uidList, int uidNumber);
详情
你可以调用该方法指定不订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅黑名单不受 MuteRemoteAudioStream、MuteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 SetSubscribeAudioBlocklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 黑名单用户 ID 列表中的用户数量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
SetSubscribeAudioAllowlist
设置音频订阅白名单。
public abstract int SetSubscribeAudioAllowlist(uint[] uidList, int uidNumber);
详情
你可以调用该方法指定想要订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅白名单不受 MuteRemoteAudioStream、MuteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
音频订阅白名单的用户 ID 列表。
如果你想指定订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 SetSubscribeAudioAllowlist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 白名单用户 ID 列表中的用户数量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
SetSubscribeVideoBlocklist
设置视频订阅黑名单。
public abstract int SetSubscribeVideoBlocklist(uint[] uidList, int uidNumber);
详情
你可以调用该方法指定不订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅黑名单不受 MuteRemoteVideoStream、MuteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 SetSubscribeVideoBlocklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 黑名单用户 ID 列表中的用户数量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
SetSubscribeVideoAllowlist
设置视频订阅白名单。
public abstract int SetSubscribeVideoAllowlist(uint[] uidList, int uidNumber);
详情
你可以调用该方法指定想要订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅白名单不受 MuteRemoteVideoStream、MuteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅白名单的用户 ID 列表。
如果你想指定仅订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 SetSubscribeVideoAllowlist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 白名单用户 ID 列表中的用户数量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
StartChannelMediaRelay
开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
public abstract int StartChannelMediaRelay(ChannelMediaRelayConfiguration configuration);
详情
- 弃用:
- 该方法已废弃。请改用 StartOrUpdateChannelMediaRelay 。
- 如果 OnChannelMediaRelayStateChanged 回调报告 RELAY_STATE_RUNNING (2) 和 RELAY_OK (0),且 OnChannelMediaRelayEvent 回调报告 RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 OnChannelMediaRelayStateChanged 回调报告 RELAY_STATE_FAILURE (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 成功调用该方法后,若你想再次调用该方法,必须先调用 StopChannelMediaRelay 方法退出当前的转发状态。
- 跨频道媒体流转发功能需要联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration。
返回值
- 0:方法调用成功
- < 0:方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: 方法调用被拒绝。可能因为 SDK 未初始化成功,或用户角色不是主播。
- -8:内部状态错误。可能因为用户角色不是主播。
StartOrUpdateChannelMediaRelay
开始或更新跨频道媒体流转发。
public abstract int StartOrUpdateChannelMediaRelay(ChannelMediaRelayConfiguration configuration);
详情
首次成功调用该方法将开始跨频道转发媒体流。如需将流转发到多个目标频道,或退出当前的转发频道,可以再次调用该方法添加或移除转发的目标频道。该功能最多支持将媒体流转发至 6 个目标频道。
- 如果 OnChannelMediaRelayStateChanged 回调报告 RELAY_STATE_RUNNING (2) 和 RELAY_OK (0), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 OnChannelMediaRelayStateChanged 回调报告 RELAY_STATE_FAILURE (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 跨频道媒体流转发功能需要联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration。
返回值
- 0:方法调用成功
- < 0:方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: 方法调用被拒绝。可能因为 SDK 未初始化成功,或用户角色不是主播。
- -8:内部状态错误。可能因为用户角色不是主播。
StopChannelMediaRelay
停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。
public abstract int StopChannelMediaRelay();
详情
成功调用该方法后,SDK 会触发 OnChannelMediaRelayStateChanged 回调。如果报告 RELAY_STATE_IDLE (0) 和 RELAY_OK (0),则表示已停止转发媒体流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
UpdateChannelMediaRelay
更新媒体流转发的频道。
public abstract int UpdateChannelMediaRelay(ChannelMediaRelayConfiguration configuration);
详情
- 弃用:
- 该方法已废弃。请改用 StartOrUpdateChannelMediaRelay 。
成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。
成功调用该方法后,SDK 会触发 OnChannelMediaRelayEvent 回调, 并在回调中报告状态码 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7)。
OnChannelMediaRelayStateChanged(RELAY_STATE_RUNNING, RELAY_OK)
后调用该方法;否则,方法调用会失败。参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。
返回值
- 0:方法调用成功
- < 0:方法调用失败
OnAudioSubscribeStateChanged
音频订阅状态发生改变回调。
public virtual void OnAudioSubscribeStateChanged(string channel, uint uid, STREAM_SUBSCRIBE_STATE oldState, STREAM_SUBSCRIBE_STATE newState, int elapseSinceLastState)
参数
- channel
- 频道名。
- uid
- 远端用户的 ID。
- oldState
- 之前的订阅状态,详见 STREAM_SUBSCRIBE_STATE。
- newState
- 当前的订阅状态,详见 STREAM_SUBSCRIBE_STATE。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
OnChannelMediaRelayEvent
跨频道媒体流转发事件回调。
public virtual void OnChannelMediaRelayEvent(int code) { }
- 弃用:
- 该回调已废弃。
参数
- code
-
跨频道媒体流转发事件码。详见 CHANNEL_MEDIA_RELAY_EVENT。
OnChannelMediaRelayStateChanged
跨频道媒体流转发状态发生改变回调。
public virtual void OnChannelMediaRelayStateChanged(int state, int code) {}
当跨频道媒体流转发状态发生改变时,SDK 会触发该回调,并报告当前的转发状态以及相关的错误信息。
参数
- state
-
跨频道媒体流转发状态。详见 CHANNEL_MEDIA_RELAY_STATE。
- code
-
跨频道媒体流转发出错的错误码。详见 CHANNEL_MEDIA_RELAY_ERROR。