视频基础功能
disableVideo
关闭视频模块。
TypeScript
abstract disableVideo(): number;
该方法用于关闭视频模块。
调用时机
加入频道前后均可调用：
- 如果在加入频道前调用，则开启纯音频模式。
- 如果在加入频道后调用，则由视频模式切换为纯音频模式，然后再调用 enableVideo 方法可开启视频模式。
调用限制
- 该方法设置的是内部引擎为禁用状态，在离开频道后仍然有效。
- 调用该方法会重置整个引擎，响应时间较慢。你可以根据实际需求用以下方法来独立控制视频模块的某一项功能：
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
相关回调
成功调用该方法后，远端会触发 onUserEnableVideo (false) 回调。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
enableLocalVideo
开关本地视频采集。
TypeScript
abstract enableLocalVideo(enabled: boolean): number;
详情
该方法禁用或重新启用本地视频采集，不影响接收远端视频。
调用 enableVideo 后，本地视频采集即默认开启。
如果你在频道内调用 enableLocalVideo(false) 关闭本地视频采集，也会同时停止在频道内发布视频流。如果想要重新开启，则可调用 enableLocalVideo(true)，然后调用 updateChannelMediaOptions 并设置 options 参数，将本地采集的视频流发布到频道中。
成功禁用或启用本地视频采集后，远端会触发 onRemoteVideoStateChanged 回调。
注意
- 该方法在加入频道前后都能调用。
- 该方法设置内部引擎为启用状态，在离开频道后仍然有效。
参数
- enabled
是否开启本地视频采集。
true:（默认）开启本地视频采集。false: 关闭本地视频采集。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为false时，该方法不需要本地有摄像头。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
enableVideo
启用视频模块。
TypeScript
abstract enableVideo(): number;
视频模块默认为关闭状态，需要调用该方法启用。如果后续需要关闭视频模块，需调用 disableVideo 方法。
调用时机
该方法可以在加入频道前或者频道内调用：
- 如果在加入频道前调用，则开启视频模块。
- 如果在纯音频通话中调用，则音频通话将自动切换为视频通话。
调用限制
- 该方法设置的是内部引擎为启用状态，在离开频道后仍然有效。
- 调用该方法会重置整个引擎，响应时间较慢。你可以根据实际需求用以下方法来独立控制视频模块的某一项功能：
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
- 在频道内调用该方法时，会重置 enableLocalVideo、muteRemoteVideoStream 和 muteAllRemoteVideoStreams 的设置，需谨慎使用。
相关回调
成功调用该方法后，远端会触发 onRemoteVideoStateChanged 回调。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
queryCodecCapability
查询 SDK 支持的视频编解码能力。
TypeScript
abstract queryCodecCapability(): { codecInfo: CodecCapInfo[]; size: number };
详情
返回值
- 如果调用成功，则返回一个包含以下属性的对象：
codecInfo：CodecCapInfo 数组，表示 SDK 的视频编码能力。size：CodecCapInfo 数组的大小。
- 如果调用超时，请修改调用逻辑，不要在主线程中调用该方法。
setVideoEncoderConfiguration
设置视频编码属性。
TypeScript
abstract setVideoEncoderConfiguration(
config: VideoEncoderConfiguration
): number;
设置本地视频的编码属性。每一种视频编码属性对应一系列视频相关参数设置，包含分辨率、帧率和码率。
调用时机
该方法只能在加入频道前调用。建议在 enableVideo 前调用该方法，可以加快首帧出图的时间。
调用限制
- 该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好，视频引擎便不能使用该 config 渲染本地视频，它会自动降低到一个合适的视频参数设置。
参数
- config
- 视频编码参数配置。详见 VideoEncoderConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setVideoEncoderConfigurationEx
设置视频编码属性。
TypeScript
abstract setVideoEncoderConfigurationEx(
config: VideoEncoderConfiguration,
connection: RtcConnection
): number;
设置本地视频的编码属性。每一种视频编码属性对应一系列视频相关参数设置，包含分辨率、帧率和码率。
调用时机
该方法需要在 joinChannelEx 之后调用。
调用限制
该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好，视频引擎便不能使用该 config 渲染本地视频，它会自动降低到一个合适的视频参数设置。
参数
- config
- 视频编码参数配置。详见 VideoEncoderConfiguration。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setVideoScenario
设置视频业务场景。
TypeScript
abstract setVideoScenario(scenarioType: VideoApplicationScenarioType): number;
详情
成功调用该方法设置视频业务场景后，SDK 会基于指定场景启用最佳实践策略，自动调整关键性能指标，进而优化视频体验质量。
注意
该方法需要在加入频道前调用。
参数
- scenarioType
- 视频业务场景。详见 VideoApplicationScenarioType。ApplicationScenarioMeeting (1) 适用于会议场景。SDK 会针对该场景启用以下策略：
- 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。
- 实时监测接收端大流的订阅人数，根据订阅人数动态调节大流配置：
- 无人订阅大流时，会自动降低大流的码率和帧率，节省上行带宽和消耗。
- 有人订阅大流时，大流会重置为用户最近一次调用 setVideoEncoderConfiguration 时的 VideoEncoderConfiguration 配置。如果用户此前没有进行设置，则使用如下值：
- 视频分辨率：960 × 540
- 视频帧率：15 fps
- 码率：1000 Kbps
- 实时监测接收端小流的订阅人数，根据订阅人数动态开启和关闭小流： 信息如果用户已调用 setDualStreamMode 将小流设置为始终不发送 (DisableSimulcastStream)，会议场景对小流的动态开关不生效。
- 无人订阅小流时，自动关闭小流，节省上行带宽和消耗。
- 有人订阅小流时，开启小流并重置为用户最近一次调用 setDualStreamMode 时的 SimulcastStreamConfig 配置。如果用户此前没有进行设置，则使用如下值：
- 视频分辨率：480 × 272
- 视频帧率：15 fps
- 码率：500 Kbps
ApplicationScenario1v1 (2) 适用于视频 1v1 通话场景。针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -1：一般性的错误（未明确归类）。
- -4：不支持设置视频业务场景。可能的原因是当前使用的是音频 SDK。
- -7：IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
startPreviewWithoutSourceType
开启视频预览。
TypeScript
abstract startPreviewWithoutSourceType(): number;
该方法用于启动本地视频预览。
调用时机
该方法必须在 enableVideo 之后调用。
调用限制
- 本地预览默认开启镜像功能。
- 在离开频道后，本地预览依然处于开启状态。你需要调用 stopPreview 关闭本地预览。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
startPreview
开启视频预览并指定预览的视频源。
TypeScript
abstract startPreview(sourceType?: VideoSourceType): number;
该方法用于启动本地视频预览，并指定出现在预览画面中的视频源。
调用时机
该方法必须在 enableVideo 之后调用。
调用限制
- 本地预览默认开启镜像功能。
- 在离开频道后，本地预览依然处于开启状态。你需要调用 stopPreview 关闭本地预览。
参数
- sourceType
- 视频源的类型，详见 VideoSourceType。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
stopPreview
停止视频预览。
TypeScript
abstract stopPreview(sourceType?: VideoSourceType): number;
适用场景
调用 startPreview 开启预览后，如果你想关闭本地视频预览，请调用该方法。
调用时机
请在加入频道前或离开频道后调用该方法。
调用限制
无。
参数
- sourceType
- 视频源的类型，详见 VideoSourceType。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
onFirstLocalVideoFrame
已显示本地视频首帧回调。
TypeScript
onFirstLocalVideoFrame?(
source: VideoSourceType,
width: number,
height: number,
elapsed: number
): void;
详情
本地视频首帧显示在本地视图上时，SDK 会触发此回调。
参数
- source
- 视频源的类型。详见 VideoSourceType。
- width
- 本地渲染视频的宽 (px) 。
- height
- 本地渲染视频的高 (px)。
- elapsed
- 从调用 joinChannel 加入频道时到发生此事件过去的时间（毫秒）。如果在加入频道前调用了 startPreviewWithoutSourceType/startPreview，则该参数表示从调用 startPreviewWithoutSourceType 或 startPreview 开启本地视频预览到发生此事件过去的时间。
onFirstLocalVideoFramePublished
已发布本地视频首帧回调。
TypeScript
onFirstLocalVideoFramePublished?(
connection: RtcConnection,
elapsed: number
): void;
详情
SDK 会在以下三种时机触发该回调：
- 开启本地视频模块的情况下，调用 joinChannel 成功加入频道后。
- 调用 muteLocalVideoStream(
true)，再调用 muteLocalVideoStream(false) 后。 - 调用 disableVideo，再调用 enableVideo 后。
参数
- connection
- Connection 信息。详见 RtcConnection。
- elapsed
- 从调用 joinChannel 方法到触发该回调的时间间隔（毫秒）。
onFirstRemoteVideoDecoded
已接收到远端视频并完成解码回调。
TypeScript
onFirstRemoteVideoDecoded?(
connection: RtcConnection,
remoteUid: number,
width: number,
height: number,
elapsed: number
): void;
详情
SDK 会在以下时机触发该回调：
- 远端用户首次上线后发送视频。
- 远端用户视频离线再上线后发送视频。出现这种中断的可能原因包括：
- 远端用户离开频道。
- 远端用户掉线。
- 远端用户调用 disableVideo 方法关闭视频模块。
参数
- connection
- Connection 信息。详见 RtcConnection。
- remoteUid
- 用户 ID，指定是哪个用户的视频流。
- width
- 视频流宽（px）。
- height
- 视频流高（px）。
- elapsed
- 从本地调用 joinChannel 开始到该回调触发的延迟（毫秒）。
onFirstRemoteVideoFrame
渲染器已接收首帧远端视频回调。
TypeScript
onFirstRemoteVideoFrame?(
connection: RtcConnection,
remoteUid: number,
width: number,
height: number,
elapsed: number
): void;
详情
注意
该回调只在 SDK 渲染时才会触发；如果用户采用自定义视频渲染则不会触发，客户需要通过 SDK 以外的方法自行实现。
参数
- remoteUid
- 用户 ID，指定是哪个用户的视频流。
- connection
- Connection 信息。详见 RtcConnection。
- width
- 视频流宽（px）。
- height
- 视频流高（px）。
- elapsed
- 从本地调用 joinChannel 到发生此事件过去的时间（毫秒）。
onLocalVideoStateChanged
本地视频状态发生改变回调。
TypeScript
onLocalVideoStateChanged?(
source: VideoSourceType,
state: LocalVideoStreamState,
reason: LocalVideoStreamReason
): void;
本地视频的状态发生改变时，SDK 会触发该回调，报告当前的本地视频状态以及状态改变的原因。
适用场景
你可以通过该回调及时了解本地视频流的状态变化，并根据状态改变的原因采取相应的措施，更好地管理和调试视频流相关的问题。
触发时机
- SDK 会在如下情况触发该回调，且 state 为 LocalVideoStreamStateFailed，reason 为
LocalVideoStreamReasonCaptureFailure：- 应用退到后台，系统回收摄像头。
- Android 9 及以上版本，App 切后台一段时间后，系统会收回相机权限。
- Android 6 及以上版本，如果相机被第三方应用占用一段时间后释放，则 SDK 会触发该回调，并报告 onLocalVideoStateChanged(
LocalVideoStreamStateCapturing，LocalVideoStreamReasonOk) 回调。 - 摄像头正常启动，但连续 4 秒都没有输出采集的视频。
- 当摄像头输出采集的视频帧时，如果 SDK 检测到连续 15 个重复的视频帧，会触发该回调，且 state 为 LocalVideoStreamStateCapturing，reason 为 LocalVideoStreamReasonCaptureFailure。 信息帧重复检测仅针对分辨率大于 200 × 200、帧率大于等于 10 fps、码率小于 20 Kbps 的视频帧。
使用限制
对某些机型而言，当本地视频采集设备正在使用中时，SDK 不会在本地视频状态发生改变时触发该回调，你需要自行做超时判断。
参数
- source
- 视频源的类型。详见 VideoSourceType。
- state
本地视频状态，详见 LocalVideoStreamState。
- reason
本地视频状态改变原因，详见 LocalVideoStreamReason。
onLocalVideoStats
本地视频流统计信息回调。
TypeScript
onLocalVideoStats?(connection: RtcConnection, stats: LocalVideoStats): void;
详情
该回调描述本地设备发送视频流的统计信息，每 2 秒触发一次。
参数
- connection
- Connection 信息。详见 RtcConnection。
- stats
- 本地视频流统计信息。详见 LocalVideoStats。
onRemoteVideoStateChanged
远端视频状态发生改变回调。
TypeScript
onRemoteVideoStateChanged?(
connection: RtcConnection,
remoteUid: number,
state: RemoteVideoState,
reason: RemoteVideoStateReason,
elapsed: number
): void;
详情
注意
频道内的用户（通信场景）或主播（直播场景）人数超过 17 人时，该回调可能不准确。
参数
- connection
- Connection 信息。详见 RtcConnection。
- remoteUid
- 发生视频状态改变的远端用户 ID。
- state
远端视频流状态，详见 RemoteVideoState。
- reason
远端视频流状态改变的具体原因，详见 RemoteVideoStateReason。
- elapsed
- 从本地用户调用 joinChannel 方法到发生本事件经历的时间，单位为毫秒。
onRemoteVideoStats
通话中远端视频流的统计信息回调。
TypeScript
onRemoteVideoStats?(connection: RtcConnection, stats: RemoteVideoStats): void;
详情
该回调描述远端用户在通话中端到端的视频流统计信息， 针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播， 该回调每 2 秒会被触发多次。
参数
- connection
- Connection 信息。详见 RtcConnection。
- stats
- 远端视频统计数据。详见 RemoteVideoStats。
onRemoteVideoTransportStats
通话中远端视频流传输的统计信息回调。
TypeScript
onRemoteVideoTransportStats?(
connection: RtcConnection,
remoteUid: number,
delay: number,
lost: number,
rxKBitRate: number
): void;
详情
废弃
该回调描述远端用户通话中端到端的网络统计信息，通过视频包计算，用客观的数据，如丢包、 网络延迟等，展示当前网络状态。
通话中，当用户收到远端用户/主播发送的视频数据包后，会每 2 秒触发一次该回调。
参数
- connection
- Connection 信息。详见 RtcConnection。
- remoteUid
- 用户 ID，指定是哪个用户/主播的视频包。
- delay
- 视频包从发送端到接收端的延时（毫秒）。
- lost
- 视频包从发送端到接收端的丢包率 (%)。
- rxKBitRate
- 远端视频包的接收码率（Kbps）。
onUserEnableLocalVideo
远端用户开/关本地视频采集回调。
TypeScript
onUserEnableLocalVideo?(
connection: RtcConnection,
remoteUid: number,
enabled: boolean
): void;
详情
废弃
- RemoteVideoStateStopped(0) 和 RemoteVideoStateReasonRemoteMuted(5)。
- RemoteVideoStateDecoding (2) 和 RemoteVideoStateReasonRemoteUnmuted(6)。
该回调是由远端用户调用 enableLocalVideo 方法开启或关闭视频采集触发的。
参数
- connection
- Connection 信息。详见 RtcConnection。
- remoteUid
- 用户 ID，提示是哪个用户的视频流。
- enabled
- 远端用户是否启用视频采集：
-
true: 该用户已启用视频功能。启用后，其他用户可以接收到该用户的视频流。 -
false: 该用户已关闭视频功能。关闭后，该用户仍然可以接收其他用户的视频流，但其他用户接收不到该用户的视频流。
-
onUserEnableVideo
远端用户开/关视频模块回调。
TypeScript
onUserEnableVideo?(
connection: RtcConnection,
remoteUid: number,
enabled: boolean
): void;
详情
关闭视频功能是指该用户只能进行语音通话，不能显示、发送自己的视频，也不能接收、显示别人的视频。
该回调是由远端用户调用 enableVideo 或 disableVideo 方法开启或关闭视频模块触发的。
参数
- connection
- Connection 信息。详见 RtcConnection。
- remoteUid
- 用户 ID，提示是哪个用户的视频流。
- enabled
-
true: 该用户已启用视频功能。 -
false: 该用户已关闭视频功能。
-
onUserMuteVideo
远端用户取消或恢复发布视频流回调。
TypeScript
onUserMuteVideo?(
connection: RtcConnection,
remoteUid: number,
muted: boolean
): void;
详情
当远端用户调用 muteLocalVideoStream 取消或恢复发布视频流时，SDK 会触发该回调向本地用户报告远端用户的发流状况。
注意
当频道内的用户（通信场景）或主播（直播场景）的人数超过 17 时，该回调可能不准确。
参数
- connection
- Connection 信息。详见 RtcConnection。
- remoteUid
- 远端用户 ID。
- muted
- 远端用户是否取消发布视频流：
true: 取消发布视频流。false: 发布视频流。
onVideoPublishStateChanged
视频发布状态改变回调。
TypeScript
onVideoPublishStateChanged?(
source: VideoSourceType,
channel: string,
oldState: StreamPublishState,
newState: StreamPublishState,
elapseSinceLastState: number
): void;
参数
- channel
- 频道名。
- source
- 视频源的类型。详见 VideoSourceType。
- oldState
- 之前的发布状态，详见 StreamPublishState。
- newState
- 当前的发布状态，详见 StreamPublishState。
- elapseSinceLastState
- 两次状态变化时间间隔（毫秒）。
onVideoSizeChanged
本地或远端视频大小和旋转信息发生改变回调。
TypeScript
onVideoSizeChanged?(
connection: RtcConnection,
sourceType: VideoSourceType,
uid: number,
width: number,
height: number,
rotation: number
): void;
参数
- connection
- Connection 信息。详见 RtcConnection。
- sourceType
- 视频源的类型。详见 VideoSourceType。
- uid
- 图像尺寸和旋转信息发生变化的用户 ID（本地用户的 uid 为 0。此时视频为本地用户的视频预览）。
- width
- 视频流的宽度（像素）。
- height
- 视频流的高度（像素）。
- rotation
- 旋转信息，取值范围 [0,360)。信息在 iOS 平台上，该参数值始终为 0。
onVideoStopped
视频功能已停止回调。
TypeScript
onVideoStopped?(): void;
详情
废弃
App 如需在停止视频后对 view 做其他处理（比如显示其他画面），可以在这个回调中进行。