视频基础功能
disableVideo
关闭视频模块。
public abstract int disableVideo();
该方法用于关闭视频模块,可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启纯音频模式,在通话中调用则由视频模式切换为纯音频模式。 调用 enableVideo
方法可开启视频模式。
成功调用该方法后,远端会触发 onUserEnableVideo
(false
) 回调。
注意:
-
该方法设置的是内部引擎为禁用状态,在离开频道后仍然有效。
-
该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制视频模块:
-
enableLocalVideo
: 是否启动摄像头采集并创建本地视频流。 -
muteLocalVideoStream
: 是否发布本地视频流。 -
muteRemoteVideoStream
: 是否接收并播放远端视频流。 -
muteAllRemoteVideoStreams
: 是否接收并播放所有远端视频流。
-
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码
了解详情和解决建议。
enableLocalVideo
开关本地视频采集。
public abstract int enableLocalVideo(boolean enabled);
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
调用 enableVideo
后,本地视频采集即默认开启。你可以调用 enableLocalVideo
(false
) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 enableLocalVideo
(true
)。
成功禁用或启用本地视频采集后,远端会触发 onRemoteVideoStateChanged
回调。
注意:
-
该方法在加入频道前后都能调用。
-
该方法设置内部引擎为启用状态,在离开频道后仍然有效。
参数
参数名 | 描述 |
---|---|
enabled | 是否开启本地视频采集。
|
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码
了解详情和解决建议。
enableVideo
启用视频模块。
public abstract int enableVideo();
该方法可以在加入频道前或者通话中调用,在加入频道前调用则自动开启视频模块;在通话中调用则由音频模式切换为视频模式。调用 disableVideo
方法可关闭视频模式。
成功调用该方法后,远端会触发 onRemoteVideoStateChanged
回调。
注意:
-
该方法设置的是内部引擎为启用状态,在离开频道后仍然有效。
-
调用该方法会重置整个引擎,响应时间较慢。你可以根据实际需求用以下方法来独立控制视频模块的某一项功能:
-
enableLocalVideo
: 是否启动摄像头采集并创建本地视频流。 -
muteLocalVideoStream
: 是否发布本地视频流。 -
muteRemoteVideoStream
: 是否接收并播放远端视频流。 -
muteAllRemoteVideoStreams
: 是否接收并播放所有远端视频流。
-
-
在频道内调用该方法时,会重置
enableLocalVideo
、muteRemoteVideoStream
和muteAllRemoteVideoStreams
的设置,需谨慎使用。
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码
了解详情和解决建议。
queryCodecCapability
setVideoEncoderConfiguration
设置视频编码属性。
public abstract int setVideoEncoderConfiguration(VideoEncoderConfiguration config);
设置本地视频的编码属性。
注意:
-
该方法在加入频道前后都能调用。如果用户在加入频道后不需要重新设置视频编码属性,则建议在
enableVideo
前调用该方法,可以加快首帧出图的时间。 -
该方法和
getMirrorApplied
方法均支持设置镜像效果,声网建议你仅选择一种方法进行设置,同时使用两种方法会导致镜像效果叠加从而造成设置镜像失败。
参数
参数名 | 描述 |
---|---|
config | 视频编码参数配置。详见 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码
了解详情和解决建议。
setVideoEncoderConfigurationEx
设置本地视频编码属性。
public abstract int setVideoEncoderConfigurationEx(
VideoEncoderConfiguration config, RtcConnection connection);
每一种视频编码属性对应一系列视频相关参数设置,包含分辨率、帧率和码率。
该方法的 config
参数设置是在理想网络状态下能达到的最大值。如果网络状态不好,视频引擎便不能使用该 config
渲染本地视频,它会自动降低到一个合适的视频参数设置。
参数
参数名 | 描述 |
---|---|
config | 视频编码参数配置。详见 |
connection | Connection 信息。详见 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码
了解详情和解决建议。
setVideoProfile
设置视频编码配置。
public abstract int setVideoProfile(int profile, boolean swapWidthAndHeight);
该方法已废弃。请改用 setVideoEncoderConfiguration
方法。
该方法设置视频的编码属性。该方法在加入频道前后都能调用。 如果用户加入频道后不需要重新设置视频编码属性,则建议在 enableVideo
前调用该方法,可以加快首帧出图的时间。
参数
参数名 | 描述 |
---|---|
profile | 视频属性。 |
swapWidthAndHeight | SDK 会按照你选择的视频属性 (
|
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码
了解详情和解决建议。
setVideoScenario
设置视频业务场景。
public abstract int setVideoScenario(Constants.VideoScenario scenarioType);
v4.2.0
成功调用该方法设置视频业务场景后,SDK 会基于指定场景启用最佳实践策略,自动调整关键性能指标,进而优化视频体验质量。
注意: 该方法需要在加入频道前调用。
参数
参数名 | 描述 |
---|---|
scenarioType | 视频业务场景。详见
|
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码
了解详情和解决建议。
startPreview [1/2]
开启视频预览。
public abstract int startPreview();
该方法用于启动本地视频预览。调用该方法前,必须:
-
调用
setupLocalVideo
初始化本地视图。 -
调用
enableVideo
开启视频模块。
注意:
-
本地预览默认开启镜像功能。
-
如果调用
leaveChannel [1/2]
退出频道,本地预览依然处于开启状态,如需要关闭本地预览,需要调用stopPreview [1/2]
。
返回值
-
0:方法调用成功。
-
< 0:方法调用失败。详见
错误码
了解详情和解决建议。
startPreview [2/2]
开启视频预览并指定预览的视频源。
public abstract int startPreview(Constants.VideoSourceType sourceType);
该方法用于启动本地视频预览。调用该方法前,必须:
-
调用
setupLocalVideo
初始化本地视图。 -
调用
enableVideo
开启视频模块。
注意:
-
本地预览默认开启镜像功能。
-
如果调用
leaveChannel [2/2]
退出频道,本地预览依然处于开启状态,如需要关闭本地预览,需要调用stopPreview [2/2]
。 -
该方法中设置的视频源类型需要跟
setupLocalVideo
中VideoCanvas
的视频源类型一致。
参数
参数名 | 描述 |
---|---|
sourceType | 视频源的类型,详见 |
返回值
-
0:方法调用成功。
-
< 0:方法调用失败。详见
错误码
了解详情和解决建议。
stopPreview [1/2]
停止视频预览。
public abstract int stopPreview();
调用 startPreview [1/2]
开启预览后,如果你想关闭本地视频预览,请调用该方法。
注: 请在加入频道前或离开频道后调用该方法。
返回值
-
0:方法调用成功。
-
< 0:方法调用失败。详见
错误码
了解详情和解决建议。
stopPreview [2/2]
停止视频预览。
public abstract int stopPreview(Constants.VideoSourceType sourceType);
调用 startPreview [2/2]
开启预览后,如果你想关闭本地视频预览,请调用该方法。
注: 请在加入频道前或离开频道后调用该方法。
参数
参数名 | 描述 |
---|---|
sourceType | 视频源的类型,详见 |
返回值
-
0:方法调用成功。
-
< 0:方法调用失败。详见
错误码
了解详情和解决建议。
onFirstLocalVideoFrame
已显示本地视频首帧回调。
public void onFirstLocalVideoFrame(
Constants.VideoSourceType source, int width, int height, int elapsed) {}
本地视频首帧显示在本地视图上时,SDK 会触发此回调。
参数
参数名 | 描述 |
---|---|
source | 视频源的类型。详见 |
width | 本地渲染视频的宽 (px) 。 |
height | 本地渲染视频的高 (px)。 |
elapsed | 从调用 |
onFirstLocalVideoFramePublished
已发布本地视频首帧回调。
public void onFirstLocalVideoFramePublished(Constants.VideoSourceType source, int elapsed) {}
SDK 会在以下三种时机触发该回调:
-
开启本地视频的情况下,调用
joinChannel [2/2]
成功加入频道后。 -
调用
muteLocalVideoStream
(true
),再调用muteLocalVideoStream
(false
) 后。 -
调用
disableVideo
,再调用enableVideo
后。 -
调用
pushExternalVideoFrame [1/2]
成功向 SDK 推送视频帧后。
参数
参数名 | 描述 |
---|---|
source | 视频源的类型。详见 |
elapsed | 从调用 |
onFirstRemoteVideoDecoded
已接收到远端视频并完成解码回调。
public void onFirstRemoteVideoDecoded(int uid, int width, int height, int elapsed) {}
SDK 会在以下时机触发该回调:
-
远端用户首次上线后发送视频。
-
远端用户视频离线再上线后发送视频。出现这种中断的可能原因包括:
-
远端用户离开频道。
-
远端用户掉线。
-
远端用户调用
muteLocalVideoStream
方法停止发送本地视频流。 -
远端用户调用
disableVideo
方法关闭视频模块。
-
参数
参数名 | 描述 |
---|---|
uid | 用户 ID,指定是哪个用户的视频流。 |
width | 视频流宽(px)。 |
height | 视频流高(px)。 |
elapsed | 从本地调用 |
onFirstRemoteVideoFrame
渲染器已接收首帧远端视频回调。
public void onFirstRemoteVideoFrame(int uid, int width, int height, int elapsed) {}
参数
参数名 | 描述 |
---|---|
uid | 用户 ID,指定是哪个用户的视频流。 |
width | 视频流宽(px)。 |
height | 视频流高(px)。 |
elapsed | 从本地调用 |
onLocalVideoStateChanged
本地视频状态发生改变回调。
public void onLocalVideoStateChanged(Constants.VideoSourceType source, int state, int error) {
super.onLocalVideoStateChanged(source, state, error);
mCallbackObj = new Object[] {source, state, error};
}
本地视频的状态发生改变时,SDK 会触发该回调返回当前的本地视频状态。你可以通过该回调了解当前视频的状态以及出现故障的原因,方便排查问题。
SDK 会在如下情况触发 onLocalVideoStateChanged
回调,状态为 LOCAL_VIDEO_STREAM_STATE_FAILED
,错误码为 LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE
:
-
在 Android 9 及以上版本的设备上,应用退到后台,系统回收摄像头。
-
在 Android 6 及以上版本的设备上,摄像头被第三方应用占用。当第三方应用释放摄像头时,SDK 会触发
回调。onLocalVideoStateChanged
(LOCAL_VIDEO_STREAM_STATE_CAPTURING,LOCAL_VIDEO_STREAM_ERROR_OK) -
摄像头正常启动,但连续 4 秒都没有输出采集的视频。
摄像头输出采集的视频帧时,如果连续 15 帧中,所有视频帧都一样,SDK 触发 onLocalVideoStateChanged
回调,状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING
,错误码为 LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE
。注意,帧重复检测仅针对分辨率大于 200 × 200、帧率大于等于 10 fps、码率小于 20 Kbps 的视频帧。
注意: 对某些机型而言,当本地视频采集设备正在使用中时,SDK 不会在本地视频状态发生改变时触发该回调,你需要自行做超时判断。
参数
参数名 | 描述 |
---|---|
source | 视频源的类型。详见 |
state |
|
error |
|
onLocalVideoStats
本地视频流统计信息回调。
public void onLocalVideoStats(Constants.VideoSourceType source, LocalVideoStats stats) {}
该回调描述本地设备发送视频流的统计信息,每 2 秒触发一次。
参数
参数名 | 描述 |
---|---|
source | 视频源的类型。详见 |
stats | 本地视频流统计信息。详见 |
onRemoteVideoStateChanged
远端视频状态发生改变回调。
public void onRemoteVideoStateChanged(int uid, int state, int reason, int elapsed) {}
注意: 频道内的用户(通信场景)或主播(直播场景)人数超过 17 人时,该回调可能不准确。
参数
参数名 | 描述 |
---|---|
uid | 发生视频状态改变的远端用户 ID。 |
state | 远端视频流状态:
|
reason | 远端视频流状态改变的具体原因:
|
elapsed | 从本地用户调用 |
onRemoteVideoStats
通话中远端视频流的统计信息回调。
public void onRemoteVideoStats(RemoteVideoStats stats) {}
该回调描述远端用户在通话中端到端的视频流统计信息, 针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播, 该回调每 2 秒会被触发多次。
参数
参数名 | 描述 |
---|---|
stats | 远端视频统计数据。详见 |
onRemoteVideoTransportStats
通话中远端视频流传输的统计信息回调。
public void onRemoteVideoTransportStats(int uid, int delay, int lost, int rxKBitRate) {}
该回调已被废弃,请改用 onRemoteVideoStats
。
该回调描述远端用户通话中端到端的网络统计信息,通过视频包计算,用客观的数据,如丢包、 网络延迟等,展示当前网络状态。
通话中,当用户收到远端用户/主播发送的视频数据包后,会每 2 秒触发一次该回调。
参数
参数名 | 描述 |
---|---|
uid | 用户 ID,指定是哪个用户/主播的视频包。 |
delay | 视频包从发送端到接收端的延时(毫秒)。 |
lost | 视频包从发送端到接收端的丢包率 (%)。 |
rxKBitRate | 远端视频包的接收码率(Kbps)。 |
onUserEnableLocalVideo
远端用户开/关本地视频采集回调。
public void onUserEnableLocalVideo(int uid, boolean enabled) {}
该回调是由远端用户调用 enableLocalVideo
方法开启或关闭视频采集触发的。
参数
参数名 | 描述 |
---|---|
uid | 用户 ID,提示是哪个用户的视频流。 |
enabled | 远端用户是否启用视频采集:
|
onUserEnableVideo
远端用户开/关视频模块回调。
public void onUserEnableVideo(int uid, boolean enabled) {}
关闭视频功能是指该用户只能进行语音通话,不能显示、发送自己的视频,也不能接收、显示别人的视频。
该回调是由远端用户调用 enableVideo
或 disableVideo
方法开启或关闭视频模块触发的。
参数
参数名 | 描述 |
---|---|
uid | 用户 ID,提示是哪个用户的视频流。 |
enabled |
|
onUserMuteVideo
远端用户取消或恢复发布视频流回调。
public void onUserMuteVideo(int uid, boolean muted) {}
当远端用户调用 muteLocalVideoStream
取消或恢复发布视频流时,SDK 会触发该回调向本地用户报告远端用户的发流状况。
注意: 当频道内的用户(通信场景)或主播(直播场景)的人数超过 17 时,该回调可能不准确。
参数
参数名 | 描述 |
---|---|
uid | 远端用户 ID。 |
muted | 远端用户是否取消发布视频流:
|
onVideoPublishStateChanged
视频发布状态改变回调。
public void onVideoPublishStateChanged(Constants.VideoSourceType source, String channel,
int oldState, int newState, int elapseSinceLastState) {}
参数
参数名 | 描述 |
---|---|
channel | 频道名。 |
source | 视频源的类型。详见 |
oldState | 之前的发布状态,详见 |
newState | 当前的发布状态,详见 |
elapseSinceLastState | 两次状态变化时间间隔(毫秒)。 |
onVideoSizeChanged
本地或远端视频大小和旋转信息发生改变回调。
public void onVideoSizeChanged(
Constants.VideoSourceType source, int uid, int width, int height, int rotation) {}
参数
参数名 | 描述 |
---|---|
source | 视频源的类型。详见 |
uid | 图像尺寸和旋转信息发生变化的用户 ID(本地用户的 |
width | 视频流的宽度(像素)。 |
height | 视频流的高度(像素)。 |
rotation | 旋转信息,取值范围 [0,360)。 |
onVideoStopped
视频功能已停止回调。
public void onVideoStopped() {}
请改用 onLocalVideoStateChanged
回调中的 LOCAL_VIDEO_STREAM_STATE_STOPPED
(0)。
App 如需在停止视频后对 view
做其他处理(比如显示其他画面),可以在这个回调中进行。