视频基础功能
DisableVideo
关闭视频模块。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int DisableVideo();
详情
该方法用于关闭视频模块,可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启纯音频模式,在通话中调用则由视频模式切换为纯音频模式。 调用 EnableVideo 方法可开启视频模式。
成功调用该方法后,远端会触发 FOnUserEnableVideo (false
) 回调。
- 该方法设置的是内部引擎为禁用状态,在离开频道后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制视频模块:
- EnableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- MuteLocalVideoStream: 是否发布本地视频流。
- MuteRemoteVideoStream: 是否接收并播放远端视频流。
- MuteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
EnableLocalVideo
开关本地视频采集。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int EnableLocalVideo(bool enabled);
详情
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
调用 EnableVideo 后,本地视频采集即默认开启。
如果你在频道内调用 EnableLocalVideo(false
) 关闭本地视频采集,也会同时停止在频道内发布视频流。如果想要重新开启,则可调用 EnableLocalVideo(true
),然后调用 UpdateChannelMediaOptions 并设置 options 参数,将本地采集的视频流发布到频道中。
成功禁用或启用本地视频采集后,远端会触发 FOnRemoteVideoStateChanged 回调。
- 该方法在加入频道前后都能调用。
- 该方法设置内部引擎为启用状态,在离开频道后仍然有效。
参数
- enabled
是否开启本地视频采集。
true
:(默认)开启本地视频采集。false
: 关闭本地视频采集。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为false
时,该方法不需要本地有摄像头。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
EnableVideo
启用视频模块。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int EnableVideo();
详情
该方法可以在加入频道前或者通话中调用,在加入频道前调用则自动开启视频模块;在通话中调用则由音频模式切换为视频模式。调用 DisableVideo 方法可关闭视频模式。
成功调用该方法后,远端会触发 FOnRemoteVideoStateChanged 回调。
- 该方法设置的是内部引擎为启用状态,在离开频道后仍然有效。
- 调用该方法会重置整个引擎,响应时间较慢。你可以根据实际需求用以下方法来独立控制视频模块的某一项功能:
- EnableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- MuteLocalVideoStream: 是否发布本地视频流。
- MuteRemoteVideoStream: 是否接收并播放远端视频流。
- MuteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
- 在频道内调用该方法时,会重置 EnableLocalVideo、MuteRemoteVideoStream 和 MuteAllRemoteVideoStreams 的设置,需谨慎使用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
QueryCodecCapability
查询当前设备支持的视频编解码能力。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int QueryCodecCapability(TArray<FCodecCapInfo> codecInfo);
详情
参数
- codecInfo
输入和输出参数,表示设备视频编码能力的数组。详见 FCodecCapInfo。
- 输入值:用户执行该方法时定义的 FCodecCapInfo,表示待查询的视频编解码能力。
- 输出值:方法执行完毕后输出的 FCodecCapInfo,表示设备实际支持的视频编解码能力。
- size
- 输入和输出参数,表示 FCodecCapInfo 数组的大小。
- 输入值:用户执行该方法时定义的 FCodecCapInfo 的大小。
- 输出值:方法执行完毕后输出的 FCodecCapInfo 的大小。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetVideoEncoderConfiguration
设置视频编码属性。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int SetVideoEncoderConfiguration(const FVideoEncoderConfiguration& config);
详情
设置本地视频的编码属性。每一种视频编码属性对应一系列视频相关参数设置,包含分辨率、帧率和码率。
该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好,视频引擎便不能使用该 config 渲染本地视频,它会自动降低到一个合适的视频参数设置。
- 该方法在加入频道前后都能调用。如果用户在加入频道后不需要重新设置视频编码属性,则建议在 EnableVideo 前调用该方法,可以加快首帧出图的时间。
- 该方法和 FGetMirrorApplied 方法均支持设置镜像效果,声网建议你仅选择一种方法进行设置,同时使用两种方法会导致镜像效果叠加从而造成设置镜像失败。
参数
- config
- 视频编码参数配置。详见 FVideoEncoderConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetVideoEncoderConfigurationEx
设置视频编码属性。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int SetVideoEncoderConfigurationEx(const FVideoEncoderConfiguration& config, const FRtcConnection& connection);
详情
设置本地视频的编码属性。每一种视频编码属性对应一系列视频相关参数设置,包含分辨率、帧率和码率。
该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好,视频引擎便不能使用该 config 渲染本地视频,它会自动降低到一个合适的视频参数设置。
参数
- config
- 视频编码参数配置。详见 FVideoEncoderConfiguration。
- connection
- Connection 信息。详见 FRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetVideoScenario
设置视频业务场景。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int SetVideoScenario(EVIDEO_APPLICATION_SCENARIO_TYPE scenarioType);
详情
成功调用该方法设置视频业务场景后,SDK 会基于指定场景启用最佳实践策略,自动调整关键性能指标,进而优化视频体验质量。
参数
- scenarioType
- 视频业务场景。详见 EVIDEO_APPLICATION_SCENARIO_TYPE。设置为 APPLICATION_SCENARIO_MEETING (1) 后,SDK 会启用以下策略:
- 针对会议场景对小流码率要求较高的情况,自动启用多项抗弱网技术,提升小流的抗弱网能力,确保多路流订阅时接收端的流畅性。
- 实时监测接收端大流的订阅人数,根据订阅人数动态调节大流配置:
- 无人订阅大流时,会自动降低大流的码率和帧率,节省上行带宽和消耗。
- 有人订阅大流时,大流会重置为用户最近一次调用 SetVideoEncoderConfiguration 时的 FVideoEncoderConfiguration 配置。如果用户此前没有进行设置,则使用如下值:
- 视频分辨率:桌面端为 1280 × 720;移动端为 960 × 540
- 视频帧率:15 fps
- 码率:桌面端为 1600 Kbps;移动端为 1000 Kbps
- 实时监测接收端小流的订阅人数,根据订阅人数动态开启和关闭小流: 信息如果用户已调用 SetDualStreamMode 将小流设置为始终不发送 (DISABLE_SIMULCAST_STREAM),会议场景对小流的动态开关不生效。
- 无人订阅小流时,自动关闭小流,节省上行带宽和消耗。
- 有人订阅小流时,开启小流并重置为用户最近一次调用 SetDualStreamMode 时的 FSimulcastStreamConfig 配置。如果用户此前没有进行设置,则使用如下值:
- 视频分辨率:480 × 272
- 视频帧率:15 fps
- 码率:500 Kbps
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -1:一般性的错误(未明确归类)。
- -4:不支持设置视频业务场景。可能的原因是当前使用的是音频 SDK。
- -7:IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
StartPreview
开启视频预览并指定预览的视频源。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int StartPreview(EVIDEO_SOURCE_TYPE sourceType = EVIDEO_SOURCE_TYPE::VIDEO_SOURCE_CAMERA_PRIMARY);
详情
- 调用 SetupLocalVideo 初始化本地视图。
- 调用 EnableVideo 开启视频模块。
- 本地预览默认开启镜像功能。
- 如果调用 LeaveChannel退出频道,本地预览依然处于开启状态,如需要关闭本地预览,需要调用 StopPreview。
- 该方法中设置的视频源类型需要跟 SetupLocalVideo 中 FVideoCanvas 的视频源类型一致。
参数
- sourceType
- 视频源的类型,详见 EVIDEO_SOURCE_TYPE。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
StopPreview
停止视频预览。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int StopPreview(EVIDEO_SOURCE_TYPE sourceType = EVIDEO_SOURCE_TYPE::VIDEO_SOURCE_CAMERA_PRIMARY);
详情
调用 StartPreview 开启预览后,如果你想关闭本地视频预览,请调用该方法。
参数
- sourceType
- 视频源的类型,详见 EVIDEO_SOURCE_TYPE。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
FOnFirstLocalVideoFrame
已显示本地视频首帧回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_FourParams(FOnFirstLocalVideoFrame, EVIDEO_SOURCE_TYPE, source, int, width, int, height, int, elapsed);
详情
本地视频首帧显示在本地视图上时,SDK 会触发此回调。
参数
- source
- 视频源的类型。详见 EVIDEO_SOURCE_TYPE。
- width
- 本地渲染视频的宽 (px) 。
- height
- 本地渲染视频的高 (px)。
- elapsed
FOnFirstLocalVideoFramePublished
已发布本地视频首帧回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnFirstLocalVideoFramePublished, EVIDEO_SOURCE_TYPE, source, int, elapsed);
详情
- 开启本地视频的情况下,调用 JoinChannel 成功加入频道后。
- 调用 MuteLocalVideoStream(
true
),再调用 MuteLocalVideoStream(false
) 后。 - 调用 DisableVideo,再调用 EnableVideo 后。
- 调用 PushVideoFrame 成功向 SDK 推送视频帧后。
参数
- source
- 视频源的类型。详见 EVIDEO_SOURCE_TYPE。
- elapsed
- 从调用 JoinChannel 方法到触发该回调的时间间隔(毫秒)。
FOnFirstRemoteVideoDecoded
已接收到远端视频并完成解码回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_FourParams(FOnFirstRemoteVideoDecoded, int64, uid, int, width, int, height, int, elapsed);
详情
- 远端用户首次上线后发送视频。
- 远端用户视频离线再上线后发送视频。出现这种中断的可能原因包括:
- 远端用户离开频道。
- 远端用户掉线。
- 远端用户调用 DisableVideo 方法关闭视频模块。
参数
- uid
- 用户 ID,指定是哪个用户的视频流。
- width
- 视频流宽(px)。
- height
- 视频流高(px)。
- elapsed
- 从本地调用 JoinChannel 开始到该回调触发的延迟(毫秒)。
FOnFirstRemoteVideoFrame
渲染器已接收首帧远端视频回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_FourParams(FOnFirstRemoteVideoFrame, int64, userId, int, width, int, height, int, elapsed);
参数
- userId
- 用户 ID,指定是哪个用户的视频流。
- width
- 视频流宽(px)。
- height
- 视频流高(px)。
- elapsed
- 从本地调用 JoinChannel 到发生此事件过去的时间(毫秒)。
FOnLocalVideoStateChanged
本地视频状态发生改变回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_ThreeParams(FOnLocalVideoStateChanged, EVIDEO_SOURCE_TYPE, source, ELOCAL_VIDEO_STREAM_STATE, state, ELOCAL_VIDEO_STREAM_ERROR, error);
详情
本地视频的状态发生改变时,SDK 会触发该回调返回当前的本地视频状态。你可以通过该回调了解当前视频的状态以及出现故障的原因,方便排查问题。
LOCAL_VIDEO_STREAM_STATE_FAILED
,错误码为 LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE
: - 应用退到后台,系统回收摄像头。
- 在 Android 9 及以上版本的设备上,应用退到后台,系统回收摄像头。
- 在 Android 6 及以上版本的设备上,摄像头被第三方应用占用。当第三方应用释放摄像头时,SDK 会触发
FOnLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING,LOCAL_VIDEO_STREAM_ERROR_OK)
回调。 - 摄像头正常启动,但连续 4 秒都没有输出采集的视频。
摄像头输出采集的视频帧时,如果连续 15 帧中,所有视频帧都一样,SDK 触发 FOnLocalVideoStateChanged 回调,状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING,错误码为 LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE。注意,帧重复检测仅针对分辨率大于 200 × 200、帧率大于等于 10 fps、码率小于 20 Kbps 的视频帧。
参数
- source
- 视频源的类型。详见 EVIDEO_SOURCE_TYPE。
- state
本地视频状态,详见 ELOCAL_VIDEO_STREAM_STATE。
- error
本地视频出错原因,详见 ELOCAL_VIDEO_STREAM_ERROR。
FOnLocalVideoStats
本地视频流统计信息回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnLocalVideoStats, EVIDEO_SOURCE_TYPE, source, const FLocalVideoStats&, stats);
详情
该回调描述本地设备发送视频流的统计信息,每 2 秒触发一次。
参数
- source
- 视频源的类型。详见 EVIDEO_SOURCE_TYPE。
- stats
- 本地视频流统计信息。详见 FLocalVideoStats。
FOnRemoteVideoStateChanged
远端视频状态发生改变回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_FourParams(FOnRemoteVideoStateChanged, int64, uid, EREMOTE_VIDEO_STATE, state, EREMOTE_VIDEO_STATE_REASON, reason, int, elapsed);
详情
参数
- uid
- 发生视频状态改变的远端用户 ID。
- state
远端视频流状态,详见 EREMOTE_VIDEO_STATE。
- reason
远端视频流状态改变的具体原因,详见 EREMOTE_VIDEO_STATE_REASON。
- elapsed
- 从本地用户调用 JoinChannel 方法到发生本事件经历的时间,单位为毫秒。
FOnRemoteVideoStats
通话中远端视频流的统计信息回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnRemoteVideoStats, const FRemoteVideoStats&, stats);
详情
该回调描述远端用户在通话中端到端的视频流统计信息, 针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播, 该回调每 2 秒会被触发多次。
参数
- stats
- 远端视频统计数据。详见 FRemoteVideoStats。
FOnRemoteVideoTransportStats
通话中远端视频流传输的统计信息回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_FourParams(FOnRemoteVideoTransportStats, int64, uid, int, delay, int, lost, int, rxKBitRate);
详情
该回调描述远端用户通话中端到端的网络统计信息,通过视频包计算,用客观的数据,如丢包、 网络延迟等,展示当前网络状态。
通话中,当用户收到远端用户/主播发送的视频数据包后,会每 2 秒触发一次该回调。
参数
- uid
- 用户 ID,指定是哪个用户/主播的视频包。
- delay
- 视频包从发送端到接收端的延时(毫秒)。
- lost
- 视频包从发送端到接收端的丢包率 (%)。
- rxKBitRate
- 远端视频包的接收码率(Kbps)。
FOnUserEnableLocalVideo
远端用户开/关本地视频采集回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnUserEnableLocalVideo, int64, uid, bool, enabled);
详情
该回调是由远端用户调用 EnableLocalVideo 方法开启或关闭视频采集触发的。
参数
- uid
- 用户 ID,提示是哪个用户的视频流。
- enabled
- 远端用户是否启用视频采集:
-
true
: 该用户已启用视频功能。启用后,其他用户可以接收到该用户的视频流。 -
false
: 该用户已关闭视频功能。关闭后,该用户仍然可以接收其他用户的视频流,但其他用户接收不到该用户的视频流。
-
FOnUserEnableVideo
远端用户开/关视频模块回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnUserEnableVideo, int64, uid, bool, enabled);
详情
关闭视频功能是指该用户只能进行语音通话,不能显示、发送自己的视频,也不能接收、显示别人的视频。
该回调是由远端用户调用 EnableVideo 或 DisableVideo 方法开启或关闭视频模块触发的。
参数
- uid
- 用户 ID,提示是哪个用户的视频流。
- enabled
-
true
: 该用户已启用视频功能。 -
false
: 该用户已关闭视频功能。
-
FOnUserMuteVideo
远端用户取消或恢复发布视频流回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnUserMuteVideo, int64, userId, bool, muted);
详情
当远端用户调用 MuteLocalVideoStream 取消或恢复发布视频流时,SDK 会触发该回调向本地用户报告远端用户的发流状况。
参数
- uid
- 远端用户 ID。
- muted
- 远端用户是否取消发布视频流:
true
: 取消发布视频流。false
: 发布视频流。
FOnVideoPublishStateChanged
视频发布状态改变回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_FiveParams(FOnVideoPublishStateChanged, EVIDEO_SOURCE_TYPE, source, FString, channel, ESTREAM_PUBLISH_STATE, oldState, ESTREAM_PUBLISH_STATE, newState, int, elapseSinceLastState);
参数
- channel
- 频道名。
- source
- 视频源的类型。详见 EVIDEO_SOURCE_TYPE。
- oldState
- 之前的发布状态,详见 ESTREAM_PUBLISH_STATE。
- newState
- 当前的发布状态,详见 ESTREAM_PUBLISH_STATE。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
FOnVideoSizeChanged
本地或远端视频大小和旋转信息发生改变回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_FiveParams(FOnVideoSizeChanged, EVIDEO_SOURCE_TYPE, sourceType, int64, uid, int, width, int, height, int, rotation);
参数
- sourceType
- 视频源的类型。详见 EVIDEO_SOURCE_TYPE。
- uid
- 图像尺寸和旋转信息发生变化的用户 ID(本地用户的 uid 为 0。此时视频为本地用户的视频预览)。
- width
- 视频流的宽度(像素)。
- height
- 视频流的高度(像素)。
- rotation
- 旋转信息,取值范围 [0,360)。信息在 iOS 平台上,该参数值始终为 0。
FOnVideoStopped
视频功能已停止回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnVideoStopped);
详情
App 如需在停止视频后对 view 做其他处理(比如显示其他画面),可以在这个回调中进行。