音视频流管理
介绍音视频数据流的管理方法和回调。
enableDualStreamMode [1/2]
在发送端开启或关闭双流模式。
virtual int enableDualStreamMode(bool enabled) = 0;
详情
- 弃用:
- 从 v4.2.0 起废弃,请改用 setDualStreamMode [1/2]。
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStreamType 选择接收视频大流或视频小流。
- 该方法适用于发送端发送的所有类型的流,包括且不限于来自摄像头采集的视频流、屏幕共享流、自定义采集的视频流。
- 如果需要在多频道场景下开启视频双流,可以调用 enableDualStreamModeEx 方法。
- 该方法可以在加入频道前后调用。
参数
- enabled
-
是否开启双流模式。
true
: 开启双流模式。false
: (默认) 关闭双流模式。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableDualStreamMode [2/2]
在发送端开启或关闭双流模式并设置视频小流。
virtual int enableDualStreamMode(bool enabled, const SimulcastStreamConfig& streamConfig) = 0;
详情
- 弃用:
- 从 v4.2.0 起废弃,请改用 setDualStreamMode [2/2]。
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStreamType 选择接收视频大流或视频小流。
- 该方法适用于发送端发送的所有类型的流,包括且不限于来自摄像头采集的视频流、屏幕共享流、自定义采集的视频流。
- 如果需要在多频道场景下开启视频双流,可以调用 enableDualStreamModeEx 方法。
- 该方法可以在加入频道前后调用。
参数
- enabled
-
是否开启双流模式:
true
: 开启双流模式。false
: (默认) 关闭双流模式。
- streamConfig
-
视频小流的配置。详见 SimulcastStreamConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteAllRemoteAudioStreams
取消或恢复订阅所有远端用户的音频流。
virtual int muteAllRemoteAudioStreams(bool mute) = 0;
详情
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在加入频道后调用。
- 如果需要在加入频道前设置默认不订阅远端用户音频流,可以在调用 joinChannel [2/2] 加入频道时设置 autoSubscribeAudio 为
false
。 - 该方法的推荐设置详见设置订阅状态。
参数
- mute
-
是否取消订阅所有远端用户的音频流:
true
: 取消订阅所有远端用户的音频流。false
:(默认)订阅所有远端用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteAllRemoteVideoStreams
取消或恢复订阅所有远端用户的视频流。
virtual int muteAllRemoteVideoStreams(bool mute) = 0;
详情
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流,包括在调用该方法后加入频道的用户的视频流。
- 该方法需要在加入频道后调用。
- 如果需要在加入频道前设置默认不订阅远端用户视频流,可以在调用 joinChannel [2/2] 加入频道时设置 autoSubscribeVideo 为
false
。
参数
- mute
-
是否取消订阅所有远端用户的视频流。
true
: 取消订阅所有用户的视频流。false
:(默认)订阅所有用户的视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteLocalAudioStream
取消或恢复发布本地音频流。
virtual int muteLocalAudioStream(bool mute) = 0;
详情
成功调用该方法后,远端会触发 onUserMuteAudio 回调和 onRemoteAudioStateChanged 回调。
参数
- mute
-
是否取消发布本地音频流。
true
: 取消发布。false
:(默认)发布。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteLocalVideoStream
取消或恢复发布本地视频流。
virtual int muteLocalVideoStream(bool mute) = 0;
详情
成功调用该方法后,远端会触发 onUserMuteVideo 回调。
- 相比于 enableLocalVideo(
false
) 用于控制本地视频流发送的方法,该方法响应速度更快。 - 该方法不影响视频采集状态,没有禁用摄像头。
参数
- mute
-
是否取消发送本地视频流。
true
: 取消发送本地视频流。false
: (默认)发送本地视频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteAudioStream
取消或恢复订阅指定远端用户的音频流。
virtual int muteRemoteAudioStream(uid_t uid, bool mute) = 0;
详情
- 该方法需要在加入频道后调用。
参数
- uid
- 指定用户的用户 ID。
- mute
-
是否取消订阅指定远端用户的音频流。
true
: 取消订阅指定用户的音频流。false
:(默认)订阅指定用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteVideoStream
取消或恢复订阅指定远端用户的视频流。
virtual int muteRemoteVideoStream(uid_t userId, bool mute) = 0;
详情
- 该方法需要在加入频道后调用。
参数
- userId
- 指定用户的用户 ID。
- mute
-
是否取消订阅指定远端用户的视频流。
true
: 取消订阅指定用户的视频流。false
: (默认)订阅指定用户的视频流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pauseAllChannelMediaRelay
暂停向所有目标频道转发媒体流。
virtual int pauseAllChannelMediaRelay() = 0;
详情
开始跨频道转发媒体流后,如果你需要暂停向所有频道转发媒体流,可以调用该方法;暂停后,如果要恢复跨频道媒体流转发,可以调用 resumeAllChannelMediaRelay 方法。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
resumeAllChannelMediaRelay
恢复向所有目标频道转发媒体流。
virtual int resumeAllChannelMediaRelay() = 0;
详情
调用 pauseAllChannelMediaRelay 方法后,如果你需要恢复向所有目标频道转发媒体流,可以调用该方法。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setDualStreamMode [1/2]
在发送端设置双流模式。
virtual int setDualStreamMode(SIMULCAST_STREAM_MODE mode) = 0;
详情
- 自从
- v4.0.1
- 如果你想修改此行为,可以调用该方法并修改 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]
在发送端设置双流模式并设置视频小流。
virtual int setDualStreamMode(SIMULCAST_STREAM_MODE mode,
const SimulcastStreamConfig& streamConfig) = 0;
详情
- 自从
- v4.0.1
- 如果你想修改此行为,可以调用该方法并修改 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
设置默认订阅的视频流类型。
virtual int setRemoteDefaultVideoStreamType(VIDEO_STREAM_TYPE streamType) = 0;
详情
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode [2/2] (false)
关闭双流模式,接收端可以选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需默认接收所有用户的视频小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
SDK 默认在发送端开启小流 auto 模式(不主动发送小流),主播身份的接收端可以调用本方法在接收端发起小流申请(观众角色的接收端调用该方法不生效),发送端收到申请后自动切换为小流模式。
- 该方法只能在加入频道前调用。SDK 不支持你在加入频道后修改默认订阅的视频流类型。
- 如果你既调用了该方法,也调用了 setRemoteVideoStreamType,则 SDK 以 setRemoteVideoStreamType 中的设置为准。
参数
- streamType
-
默认订阅的视频流类型: VIDEO_STREAM_TYPE。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVideoStreamType
设置订阅的视频流类型。
virtual int setRemoteVideoStreamType(uid_t uid, VIDEO_STREAM_TYPE streamType) = 0;
详情
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode [2/2](false)
关闭双流模式,接收端可以调用该方法选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
SDK 默认在发送端开启小流 auto 模式(不主动发送小流),主播身份的接收端可以调用本方法在接收端发起小流申请(观众角色的接收端调用该方法不生效),发送端收到申请后自动切换为小流模式。
参数
- uid
- 用户 ID。
- streamType
-
视频流类型: VIDEO_STREAM_TYPE。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVideoSubscriptionOptions
设置远端视频流的订阅选项。
virtual int setRemoteVideoSubscriptionOptions(uid_t uid, const VideoSubscriptionOptions &options) = 0;
详情
当远端发送双流时,可调用此方法来设置远端视频流的订阅选项。
- 如果你只注册了 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
设置音频订阅黑名单。
virtual int setSubscribeAudioBlocklist(uid_t* uidList, int uidNumber) = 0;
详情
你可以调用该方法指定不订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅黑名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeAudioBlocklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 黑名单用户 ID 列表中的用户数量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeAudioAllowlist
设置音频订阅白名单。
virtual int setSubscribeAudioAllowlist(uid_t* uidList, int uidNumber) = 0;
详情
你可以调用该方法指定想要订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅白名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
音频订阅白名单的用户 ID 列表。
如果你想指定订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeAudioAllowlist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 白名单用户 ID 列表中的用户数量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoBlocklist
设置视频订阅黑名单。
virtual int setSubscribeVideoBlocklist(uid_t* uidList, int uidNumber) = 0;
详情
你可以调用该方法指定不订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅黑名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeVideoBlocklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 黑名单用户 ID 列表中的用户数量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoAllowlist
设置视频订阅白名单。
virtual int setSubscribeVideoAllowlist(uid_t* uidList, int uidNumber) = 0;
详情
你可以调用该方法指定想要订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅白名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅白名单的用户 ID 列表。
如果你想指定仅订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeVideoAllowlist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 白名单用户 ID 列表中的用户数量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startChannelMediaRelay
开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
virtual int startChannelMediaRelay(const ChannelMediaRelayConfiguration &configuration) = 0;
详情
- 弃用:
- 该方法已废弃。请改用 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
开始或更新跨频道媒体流转发。
virtual int startOrUpdateChannelMediaRelay(const ChannelMediaRelayConfiguration &configuration) = 0;
详情
- 自从
- v4.2.0
首次成功调用该方法将开始跨频道转发媒体流。如需将流转发到多个目标频道,或退出当前的转发频道,可以再次调用该方法添加或移除转发的目标频道。该功能最多支持将媒体流转发至 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
停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。
virtual int stopChannelMediaRelay() = 0;
详情
成功调用该方法后,SDK 会触发 onChannelMediaRelayStateChanged 回调。如果报告 RELAY_STATE_IDLE (0) 和 RELAY_OK (0),则表示已停止转发媒体流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
updateChannelMediaRelay
更新媒体流转发的频道。
virtual int updateChannelMediaRelay(const ChannelMediaRelayConfiguration &configuration) = 0;
详情
- 弃用:
- 该方法已废弃。请改用 startOrUpdateChannelMediaRelay 。
成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。
成功调用该方法后,SDK 会触发 onChannelMediaRelayEvent 回调, 并在回调中报告状态码 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7)。
onChannelMediaRelayStateChanged(RELAY_STATE_RUNNING, RELAY_OK)
后调用该方法;否则,方法调用会失败。参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。
返回值
- 0:方法调用成功
- < 0:方法调用失败
onAudioSubscribeStateChanged
音频订阅状态发生改变回调。
virtual void onAudioSubscribeStateChanged(const char* channel, uid_t uid, STREAM_SUBSCRIBE_STATE oldState, STREAM_SUBSCRIBE_STATE newState, int elapseSinceLastState) { (void)channel; (void)uid; (void)oldState; (void)newState; (void)elapseSinceLastState; }
参数
- channel
- 频道名。
- uid
- 远端用户的 ID。
- oldState
- 之前的订阅状态,详见 STREAM_SUBSCRIBE_STATE。
- newState
- 当前的订阅状态,详见 STREAM_SUBSCRIBE_STATE。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
onChannelMediaRelayEvent
跨频道媒体流转发事件回调。
virtual void onChannelMediaRelayEvent(int code) { (void)code; }
- 弃用:
- 该回调已废弃。
参数
- code
-
跨频道媒体流转发事件码。详见 CHANNEL_MEDIA_RELAY_EVENT。
onChannelMediaRelayStateChanged
跨频道媒体流转发状态发生改变回调。
virtual void onChannelMediaRelayStateChanged(CHANNEL_MEDIA_RELAY_STATE state,CHANNEL_MEDIA_RELAY_ERROR code) { }
当跨频道媒体流转发状态发生改变时,SDK 会触发该回调,并报告当前的转发状态以及相关的错误信息。
参数
- state
-
跨频道媒体流转发状态。详见 CHANNEL_MEDIA_RELAY_STATE。
- code
-
跨频道媒体流转发出错的错误码。详见 CHANNEL_MEDIA_RELAY_ERROR。