视频处理
介绍跟视频处理相关的方法和回调。
addVideoWatermark [1/2]
添加本地视频水印。
public abstract int addVideoWatermark(AgoraImage watermark);
详情
- 弃用:
- 该方法已废弃,请使用 addVideoWatermark [2/2] 作为替代。
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户,旁路推流观众,甚至采集设备都能看到或采集到该水印图片。如果你仅仅希望在旁路直播推流中添加水印,请参考 setLiveTranscoding中描述的用法。
- 在本地直播和旁路推流中,URL 的定义不同。本地直播中,URL 指本地直播视频上图片的本地绝对/相对路径;旁路推流中,URL 指旁路推流视频上图片的地址。
- 待添加图片的源文件格式必须是 PNG。如果待添加的 PNG 图片的尺寸与你该方法中设置的尺寸不一致,SDK 会对 PNG 图片进行裁剪,以与设置相符。
- 声网当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
参数
- watermark
- 待添加在本地直播推流中的水印图片:AgoraImage。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
addVideoWatermark [2/2]
添加本地视频水印。
public abstract int addVideoWatermark(String watermarkUrl, WatermarkOptions options);
详情
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户、旁路直播观众和采集设备都能看到或采集到该水印图片。当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
- 如果视频编码方向(ORIENTATION_MODE)固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
- 如果视频编码方向(ORIENTATION_MODE)固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
- 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸,否则超出部分将被裁剪。
- 你需要在调用 enableVideo 方法之后再调用该方法。
- 如果你只是在旁路推流时添加水印,你可以使用该方法或 setLiveTranscoding 方法设置水印。
- 待添加水印图片必须是 PNG 格式。该方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在该方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
- 如果你已经使用 startPreview [2/2] 方法开启本地视频预览,那么该方法的
visibleInPreview
可设置水印在预览时是否可见。 - 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
- watermarkUrl
- 待添加的水印图片的本地路径。该方法支持从本地绝对/相对路径添加水印图片。
- options
- 待添加的水印图片的设置选项,详见 WatermarkOptions 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
clearVideoWatermarks
删除已添加的视频水印。
public abstract int clearVideoWatermarks();
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
createCustomVideoTrack
创建一个自定义的视频轨道。
public abstract int createCustomVideoTrack();
详情
- 调用该方法创建视频轨道并获得视频轨道 ID。
- 在每个频道的 ChannelMediaOptions 中,将 customVideoTrackId 参数设置为你想要发布的视频轨道 ID,并将 publishCustomVideoTrack 设置为
true
。 - 调用 pushExternalVideoFrameEx [2/2] 将 videoTrackId 指定为步骤 2 中指定的视频轨道 ID,即可实现在多个频道中发布对应的自定义视频源。
返回值
- 方法调用成功,返回视频轨道 ID 作为该视频轨道的唯一标识。
- 方法调用失败,返回负值。
destroyCustomVideoTrack
销毁指定的视频轨道。
public abstract int destroyCustomVideoTrack(int video_track_id);
参数
- video_track_id
- 调用 createCustomVideoTrack 方法返回的视频轨道 ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableContentInspect
开启/关闭视频截图上传。
public abstract int enableContentInspect(boolean enabled, ContentInspectConfig config);
详情
开启视频截图上传后,SDK 会根据你在 ContentInspectConfig 中设置的模块类型和频率对本地用户发送的视频进行截图和上传。截图完成后,声网服务器会以 HTTPS 请求的形式,向你的服务器发送回调通知,并将所有截图发送至你指定的第三方云存储。
- 调用该方法前,请确保已联系技术支持开通视频截图上传服务。
- 该方法依赖于视频截图上传动态库
agora_content_inspect_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 设置是否开启视频截图上传:
true
:开启视频截图上传。false
:关闭视频截图上传。
- config
- 视频截图上传配置。详见 ContentInspectConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableFaceDetection
开启/关闭本地人脸检测。
public abstract int enableFaceDetection(boolean enabled);
详情
该方法在加入频道前后都能调用。
- 摄像头采集的画面大小
- 人脸在 view 中的位置
- 人脸距设备屏幕的距离
该方法需要在相机启动(如通过调用 startPreview [2/2] 或 enableVideo 实现)后调用。
参数
- enable
- 是否开启人脸检测:
true
:开启人脸检测。false
:(默认)关闭人脸检测。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableLocalVideo
开关本地视频采集。
public abstract int enableLocalVideo(boolean enabled);
详情
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
调用 enableVideo 后,本地视频采集即默认开启。你可以调用 enableLocalVideo(false
) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 enableLocalVideo(true
)。
成功禁用或启用本地视频采集后,远端会触发 onRemoteVideoStateChanged 回调。
- 该方法在加入频道前后都能调用。
- 该方法设置内部引擎为启用状态,在离开频道后仍然有效。
参数
- enabled
-
是否开启本地视频采集。
true
:(默认)开启本地视频采集。false
: 关闭本地视频采集。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为false
时,该方法不需要本地有摄像头。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
disableVideo
关闭视频模块。
public abstract int disableVideo();
详情
该方法用于关闭视频模块,可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启纯音频模式,在通话中调用则由视频模式切换为纯音频模式。 调用 enableVideo 方法可开启视频模式。
成功调用该方法后,远端会触发 onUserEnableVideo (false
) 回调。
- 该方法设置的是内部引擎为禁用状态,在离开频道后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制视频模块:
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableVideo
启用视频模块。
public abstract int enableVideo();
详情
该方法可以在加入频道前或者通话中调用,在加入频道前调用则自动开启视频模块;在通话中调用则由音频模式切换为视频模式。调用 disableVideo 方法可关闭视频模式。
成功调用该方法后,远端会触发 onRemoteVideoStateChanged 回调。
- 该方法设置的是内部引擎为启用状态,在离开频道后仍然有效。
- 调用该方法会重置整个引擎,响应时间较慢。你可以根据实际需求用以下方法来独立控制视频模块的某一项功能:
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
- 在频道内调用该方法时,会重置 enableLocalVideo、muteRemoteVideoStream 和 muteAllRemoteVideoStreams 的设置,需谨慎使用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableVideoImageSource
设置是否开启垫片推流功能。
public abstract int enableVideoImageSource(boolean enabled, ImageTrackOptions options);
详情
在发布视频流时,你可以调用该方法使用自定义图片来替代当前发布的视频流画面进行推流。
开启该功能后,你可以通过 ImageTrackOptions 参数自定义垫片图片;在你关闭垫片功能之后,远端用户看到的依旧是当前你发布的视频流画面。
参数
- enable
- 是否开启垫片推流:
true
:开启垫片推流。false
:(默认)关闭垫片推流。
- options
- 垫片图片设置,详见 ImageTrackOptions。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableVirtualBackground
开启/关闭虚拟背景。
public abstract int enableVirtualBackground( boolean enabled, VirtualBackgroundSource backgroundSource, SegmentationProperty segproperty);
详情
虚拟背景功能支持将本地用户原来的背景替换为静态图片、动态视频、将背景虚化,或者将人像与背景分割以实现人像画中画。成功开启虚拟背景功能后,频道内所有用户都能看到自定义的背景。
请在 enableVideo 或 startPreview [2/2] 之后调用该方法。
- 该功能对设备性能要求较高,建议你在搭载如下芯片的设备上使用:
- 骁龙 700 系列 750G 及以上
- 骁龙 800 系列 835 及以上
- 天玑 700 系列 720 及以上
- 麒麟 800 系列 810 及以上
- 麒麟 900 系列 980 及以上
- 建议你在满足如下条件的场景中使用该功能:
- 使用高清摄像设备、摄像环境光照均匀。
- 摄像画面中,物件较少,用户的人像为半身人像且基本无遮挡,背景色较单一且与用户着装颜色不同。
- 该方法依赖于虚拟背景动态库
libagora_segmentation_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启虚拟背景:
true
: 开启虚拟背景。false
: 关闭虚拟背景。
- backgroundSource
- 自定义的背景。详见 VirtualBackgroundSource。为将自定义背景图的分辨率与 SDK 的视频采集分辨率适配,SDK 会在保证自定义背景图不变形的前提下,对自定义背景图进行缩放和裁剪。
- segproperty
- 背景图像的处理属性。详见 SegmentationProperty。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -1:自定义的背景图不存在。请检查 VirtualBackgroundSource 中 source 的值。
- -2:自定义的背景图颜色格式出错。请检查 VirtualBackgroundSource 中 color 的值。
- -3:设备不支持使用虚拟背景。
getCurrentMonotonicTimeInMs
获取 SDK 当前的 Monotonic Time。
public abstract long getCurrentMonotonicTimeInMs();
详情
- 自从
- v4.2.0
Monotonic Time 是指一个单调递增的时间序列,它的值会随着时间的推移而增加。单位为毫秒。
在自定义视频采集、自定义音频采集场景中,为确保音视频同步,声网建议你调用该方法获取 SDK 当前的 Monotonic Time 后,将该值传入采集的视频帧(VideoFrame)、音频帧(AudioFrame)的时间戳参数。
返回值
- ≥0: 方法调用成功,返回 SDK 当前的 Monotonic Time(毫秒)。
- < 0: 方法调用失败。
isTextureEncodeSupported
检查视频是否支持 Texture 编码。
public abstract boolean isTextureEncodeSupported();
返回值
true
:支持 Texture 编码。false
:不支持 Texture 编码。
pushExternalVideoFrame [1/2]
推送外部原始视频帧到 SDK。
public abstract boolean pushExternalVideoFrame(AgoraVideoFrame frame);
详情
- 弃用:
- 如果你需要推送 I422 格式的视频帧,请使用该方法。其他情况下,请改用 pushExternalVideoFrame [2/2]。
调用 setExternalVideoSource 方法,设置 enabled 参数为 true
、encodedFrame 参数为 false
后,你可以调用本方法将未编码的外部视频帧推送到 SDK。
调用该方法或 pushExternalVideoFrame [2/2] 均能将视频帧数据传递给SDK。区别为 pushExternalVideoFrame [1/2] 方法不支持 texture 格式的视频数据。
参数
- frame
-
待推送的视频帧。详见 AgoraVideoFrame。
返回值
true
:推送成功。false
:推送失败。
pushExternalVideoFrame [2/2]
推送外部视频帧。
public abstract boolean pushExternalVideoFrame(VideoFrame frame);
详情
该方法主动将视频帧数据用 VideoFrame 类封装后传递给 SDK。请确保在你调用本方法前已调用 setExternalVideoSource, 并将参数 enable 设置为 true
,不然调用本方法后会一直报错。
调用该方法或 pushExternalVideoFrame [1/2] 均能将视频帧数据传递给SDK。区别为 pushExternalVideoFrame [2/2] 方法支持 texture 格式的视频数据。
参数
- frame
- 待推送的外部原始视频帧。详见 VideoFrame。
返回值
true
:推送成功。false
:推送失败。
queryCodecCapability
查询当前设备支持的视频编解码能力。
public abstract CodecCapInfo[] queryCodecCapability();
详情
- 自从
- v4.2.0
返回值
- 如果调用成功,则返回 CodecCapInfo 数组,表示设备的视频编码能力。
- 如果调用超时,请修改调用逻辑,不要在主线程中调用该方法。
setBeautyEffectOptions
设置美颜效果选项。
public abstract int setBeautyEffectOptions(boolean enabled, BeautyOptions options);
详情
开启本地美颜功能,并设置美颜效果选项。
- 请在 enableVideo 或 startPreview [2/2] 之后调用该方法。
- 该方法仅适用于 Android 5.0 及以上版本。
- 该方法依赖于视频增强动态库
libagora_clear_vision_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启美颜功能:
true
: 开启美颜功能。false
:(默认)关闭美颜功能。
- options
- 美颜选项,详细定义见 BeautyOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- ERR_NOT_SUPPORTED(4):当前设备版本低于 Android 5.0,不支持该操作。
setColorEnhanceOptions
设置色彩增强功能。
public abstract int setColorEnhanceOptions(boolean enabled, ColorEnhanceOptions options);
详情
摄像头采集到的视频画面可能存在色彩失真的现象。色彩增强功能可以通过智能调节饱和度和对比度等视频特性,提升视频色彩丰富度和色彩还原度,最终使视频画面更生动。
你可以调用该方法开启色彩增强功能并设置色彩增强的效果。
- 请在 enableVideo 后调用该方法。
- 色彩增强对设备性能有一定要求。开启色彩增强后,如果设备出现严重发烫等问题,建议你将色彩增强等级修改为消耗性能较少的等级或关闭色彩增强功能。
- 该方法和 setExtensionProperty 均可开启色彩增强功能:
- 当你使用 SDK 采集视频时,建议使用该方法(该方法只可对 SDK 采集的视频起作用)。
- 当你使用外部的视频源实现自定义视频采集,或者将外部视频源发送给 SDK 时,建议使用 setExtensionProperty 方法。
- 该方法依赖于视频增强动态库
libagora_clear_vision_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启色彩增强功能:
true
:开启色彩增强功能。false
:(默认)关闭色彩增强功能。
- options
- 色彩增强选项,用于设置色彩增强的效果。详见 ColorEnhanceOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setExternalVideoSource
设置外部视频源。
public abstract int setExternalVideoSource( boolean enable, boolean useTexture, Constants.ExternalVideoSourceType sourceType);
详情
参数
- enable
- 是否启用外部视频源:
true
: 启用外部视频源。SDK 准备接收外部视频帧。false
:(默认)不启用外部视频源。
- useTexture
- 是否使用 texture 格式的外部视频帧:
true
: 使用 texture 格式的外部视频帧。false
: 不使用 texture 格式的外部视频帧。
- sourceType
- 外部视频帧是否编码,详见 ExternalVideoSourceType。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
setLocalRenderMode [1/2]
设置本地视图显示模式。
public abstract int setLocalRenderMode(int renderMode);
详情
- 弃用:
- 该方法已废弃,请使用 setLocalRenderMode [2/2] 作为替代。
该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。
参数
- renderMode
-
本地视图显示模式。
- RENDER_MODE_HIDDEN (1):优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
- RENDER_MODE_FIT (2):优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
- RENDER_MODE_ADAPTIVE (3): 该模式已废弃,不推荐使用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalRenderMode [2/2]
更新本地视图显示模式。
public abstract int setLocalRenderMode(int renderMode, int mirrorMode);
详情
初始化本地用户视图后,你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面,不影响本地发布视频。
- 请在调用 setupLocalVideo 方法初始化本地视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新本地用户视图的显示模式。
参数
- renderMode
-
本地视图显示模式。
- RENDER_MODE_HIDDEN (1):优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
- RENDER_MODE_FIT (2):优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
- RENDER_MODE_ADAPTIVE (3): 该模式已废弃,不推荐使用。
- mirrorMode
-
本地视图的镜像模式。
- VIDEO_MIRROR_MODE_AUTO (0):SDK 决定镜像模式。如果你使用前置摄像头,默认启动本地视图镜像模式;如果你启用后置摄像头,默认关闭本地视图镜像模式。
- VIDEO_MIRROR_MODE_ENABLED (1):开启本地视图的镜像模式。
- VIDEO_MIRROR_MODE_DISABLED (2):关闭本地视图的镜像模式。
注意: 如果你使用前置摄像头,默认启动本地用户视图镜像模式;如果你使用后置摄像头,默认关闭本地视图镜像模式。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalVideoMirrorMode
设置本地视频镜像。
public abstract int setLocalVideoMirrorMode(int mode);
详情
- 弃用:
- 该方法已废弃。
参数
- mode
-
- VIDEO_MIRROR_MODE_AUTO (0):SDK 决定镜像模式。如果你使用前置摄像头,默认启动本地视图镜像模式;如果你启用后置摄像头,默认关闭本地视图镜像模式。
- VIDEO_MIRROR_MODE_ENABLED (1):开启本地视图的镜像模式。
- VIDEO_MIRROR_MODE_DISABLED (2):关闭本地视图的镜像模式。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLowlightEnhanceOptions
设置暗光增强功能。
public abstract int setLowlightEnhanceOptions(boolean enabled, LowLightEnhanceOptions options);
详情
暗光增强功能可以在光线亮度偏低(如背光、阴天、暗场景)和亮度不均匀的环境下自适应调整视频画面的亮度值,恢复或凸显图像的细节信息,最终提升视频图像的整体视觉效果。
你可以调用该方法开启暗光增强功能并设置暗光增强的效果。
- 请在 enableVideo 后调用该方法。
- 暗光增强对设备性能有一定要求。开启暗光增强后,如果设备出现严重发烫等问题,建议你将暗光增强等级修改为消耗性能较少的等级或关闭暗光增强功能。
- 该方法和 setExtensionProperty 均可开启暗光增强功能:
- 当你使用 SDK 采集视频时,建议使用该方法(该方法只可对 SDK 采集的视频起作用)。
- 当你使用外部的视频源实现自定义视频采集,或者将外部视频源发送给 SDK 时,建议使用 setExtensionProperty 方法。
- 该方法依赖于视频增强动态库
libagora_clear_vision_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启暗光增强功能:
true
: 开启暗光增强功能。false
:(默认)关闭暗光增强功能。
- options
- 暗光增强选项,用于设置暗光增强的效果。详见 LowlightEnhanceOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setRemoteRenderMode [1/2]
设置远端视图显示模式。
public abstract int setRemoteRenderMode(int userId, int renderMode);
详情
- 弃用:
- 该方法已废弃,请使用 setRemoteRenderMode [2/2]。
该方法设置远端视图显示模式。App 可以多次调用此方法更改显示模式。
参数
- userId
- 远端用户 ID。
- renderMode
-
远端用户视图的渲染模式。
- RENDER_MODE_HIDDEN (1):优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
- RENDER_MODE_FIT (2):优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRemoteRenderMode [2/2]
更新远端视图显示模式。
public abstract int setRemoteRenderMode(int userId, int renderMode, int mirrorMode);
详情
初始化远端用户视图后,你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。
- 请在调用 setupRemoteVideo 方法初始化远端视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
- userId
- 远端用户 ID。
- renderMode
-
远端用户视图的渲染模式。
- RENDER_MODE_HIDDEN (1):优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
- RENDER_MODE_FIT (2):优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
- RENDER_MODE_ADAPTIVE (3): 该模式已废弃,不推荐使用。
- mirrorMode
-
远端用户视图的镜像模式。
- VIDEO_MIRROR_MODE_AUTO (0):SDK 决定镜像模式。如果你使用前置摄像头,默认启动本地视图镜像模式;如果你启用后置摄像头,默认关闭本地视图镜像模式。
- VIDEO_MIRROR_MODE_ENABLED (1):开启本地视图的镜像模式。
- VIDEO_MIRROR_MODE_DISABLED (2):关闭本地视图的镜像模式。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setupLocalVideo
初始化本地视图。
public abstract int setupLocalVideo(VideoCanvas local);
详情
该方法初始化本地视图并设置本地用户视频显示属性,只影响本地用户看到的视频画面,不影响本地发布视频。调用该方法绑定本地视频流的显示视窗(view),并设置本地用户视图的渲染模式和镜像模式。
在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入频道。退出频道后,绑定仍然有效,如果需要解除绑定,可以调用该方法将参数 view 设为 NULL。
- 该方法在加入频道前后都能调用。
- 如果你希望在通话中更新本地用户视图的渲染或镜像模式,请使用 setLocalRenderMode [2/2] 方法。
参数
- local
- 本地视频显示属性。详见 VideoCanvas。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setupRemoteVideo
初始化远端用户视图。
public abstract int setupRemoteVideo(VideoCanvas remote);
详情
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。
调用该方法时需要指定远端视频的用户 ID,一般可以在进频道前提前设置好。如果无法在加入频道前得到远端用户的 ID,可以在收到 onUserJoined 回调时调用该方法。
如需解除某个远端用户的绑定视图,可以调用该方法并将 view 设置为空。
离开频道后,SDK 会清除远端用户视图的绑定关系。
- 如果你希望在通话中更新远端用户视图的渲染或镜像模式,请使用 setRemoteRenderMode [2/2] 方法。
- 如果你使用了录制服务,录制服务会作为一个哑客户端加入频道,因此也会触发 onUserJoined 回调。由于录制服务不会发送视频流,app 无需为它绑定视图。如果 app 无法识别哑客户端,可以在收到 onFirstRemoteVideoDecoded 回调时再绑定远端用户视图。
参数
- remote
-
远端视频显示属性。详见 VideoCanvas。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setVideoDenoiserOptions
设置视频降噪功能。
public abstract int setVideoDenoiserOptions(boolean enabled, VideoDenoiserOptions options);
详情
采光不足的环境和低端视频采集设备会使视频图像含有明显的噪声,影响视频画质。在实时互动场景下,视频噪声还会在编码过程中占用码流资源并降低编码效率。
你可以调用该方法开启视频降噪功能并设置视频降噪的效果。
- 请在 enableVideo 后调用该方法。
- 视频降噪对设备性能有一定要求。开启视频降噪后,如果设备出现严重发烫等问题,建议你将视频降噪等级修改为消耗性能较少的等级或关闭视频降噪功能。
- 该方法和 setExtensionProperty 均可开启视频降噪功能:
- 当你使用 SDK 采集视频时,建议使用该方法(该方法只可对 SDK 采集的视频起作用)。
- 当你使用外部的视频源实现自定义视频采集,或者将外部视频源发送给 SDK 时,建议使用 setExtensionProperty 方法。
- 该方法依赖于视频增强动态库
libagora_clear_vision_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启视频降噪功能:
true
: 开启视频降噪功能。false
:(默认)关闭视频降噪功能。
- options
- 视频降噪选项,用于设置视频降噪的效果。详见 VideoDenoiserOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVideoEncoderConfiguration
设置视频编码属性。
public abstract int setVideoEncoderConfiguration(VideoEncoderConfiguration config);
详情
设置本地视频的编码属性。
- 该方法在加入频道前后都能调用。如果用户在加入频道后不需要重新设置视频编码属性,则建议在 enableVideo 前调用该方法,可以加快首帧出图的时间。
- 该方法和 getMirrorApplied 方法均支持设置镜像效果,声网建议你仅选择一种方法进行设置,同时使用两种方法会导致镜像效果叠加从而造成设置镜像失败。
参数
- config
- 视频编码参数配置。详见 VideoEncoderConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVideoProfile
设置视频编码配置。
public abstract int setVideoProfile(int profile, boolean swapWidthAndHeight);
详情
- 弃用:
- 该方法已废弃。请改用 setVideoEncoderConfiguration 方法。
该方法设置视频的编码属性。该方法在加入频道前后都能调用。 如果用户加入频道后不需要重新设置视频编码属性,则建议在 enableVideo 前调用该方法,可以加快首帧出图的时间。
参数
- profile
-
视频属性。
- swapWidthAndHeight
-
SDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高:
true
: 交换宽和高false
: 不交换宽和高(默认)
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVideoScenario
设置视频业务场景。
public abstract int setVideoScenario(Constants.VideoScenario scenarioType);
详情
- 自从
- v4.2.0
成功调用该方法设置视频业务场景后,SDK 会基于指定场景启用最佳实践策略,自动调整关键性能指标,进而优化视频体验质量。
参数
- scenarioType
- 视频业务场景。详见 VideoScenario。
设置为 APPLICATION_SCENARIO_MEETING (1) 后,SDK 会启用以下策略:
- 针对会议场景对小流码率要求较高的情况,自动启用多项抗弱网技术,提升小流的抗弱网能力,确保多路流订阅时接收端的流畅性。
- 实时监测接收端大流的订阅人数,根据订阅人数动态调节大流配置:
- 无人订阅大流时,会自动降低大流的码率和帧率,节省上行带宽和消耗。
- 有人订阅大流时,大流会重置为用户最近一次调用 setVideoEncoderConfiguration 时的 VideoEncoderConfiguration 配置。如果用户此前没有进行设置,则使用如下值:
- 视频分辨率:960 × 540
- 视频帧率:15 fps
- 码率:1000 Kbps
- 实时监测接收端小流的订阅人数,根据订阅人数动态开启和关闭小流:
- 无人订阅小流时,自动关闭小流,节省上行带宽和消耗。
- 有人订阅小流时,开启小流并重置为用户最近一次调用 setDualStreamMode [2/2] 时的 SimulcastStreamConfig 配置。如果用户此前没有进行设置,则使用如下值:
- 视频分辨率:480 × 272
- 视频帧率:15 fps
- 码率:500 Kbps
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVideoQualityParameters
设置视频优化选项(仅适用于直播)。
public abstract int setVideoQualityParameters(boolean preferFrameRateOverImageQuality);
详情
- 弃用:
- 该方法已废弃。建议使用 VideoEncoderConfiguration 类中的 degradationPreference 参数设置视频质量偏好。
参数
- preferFrameRateOverImageQuality
-
画质和流畅度里,是否优先保证流畅度:
true
:优先保证流畅度。false
: (默认)优先保证画质。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startLocalVideoTranscoder
开启本地合图。
public abstract int startLocalVideoTranscoder(LocalTranscoderConfiguration config);
详情
调用该方法后,你可以在本地将多路视频流合并为一路视频流。例如:将摄像头采集的视频流、屏幕共享流、媒体播放器中的视频流、远端视频流、视频文件、图片等合并为一路视频流,然后将已合图的视频流发布到频道中。
- 本地合图对 CPU 的消耗较高,声网建议你在性能较高的设备上开启该功能。
- 如果你需要对本地采集的视频流进行合图,SDK 支持如下采集组合:
- 在 Android 平台上,最多支持 2 路摄像头采集的视频流(需要设备本身支持双摄或支持外接摄像头)+ 1 路屏幕共享合图。
- 如果你需要对本地采集的视频流进行合图,需要在 startCameraCapture 或 startScreenCapture 之后调用该方法。
- 如果你要将合图后的视频流发布到频道中,需要在调用 joinChannel [2/2] 或 updateChannelMediaOptions 时,将 ChannelMediaOptions 中的 publishTranscodedVideoTrack 设置为
true
。
适用场景
你可以在远程会议、直播、在线教育等场景下开启本地合图功能,可以让用户更加方便地查看和管理多个视频画面,同时支持人像画中画等功能。
- 调用 enableVirtualBackground,并将自定义背景图设置为 BACKGROUND_NONE,即:在摄像头采集的视频中将人像和背景分割。
- 调用 startScreenCapture,开始采集屏幕共享视频流。
- 调用该方法,并将采集人像的视频源设置为参与本地合图的视频源之一,即可在合图后的视频中实现人像画中画。
注: 在进行合图配置时,需确保采集人像的摄像头视频流在合图中的图层编号大于屏幕共享流的图层编号,否则人像会被屏幕共享覆盖、无法显示在最终合图的视频流中。
参数
- config
- 本地合图的配置,详见 LocalTranscoderConfiguration。
注意:
- 参与本地合图的每一路视频流的分辨率最大为 4096 × 2160,如果超出此限制,会导致合图不生效。
- 合图后的视频流最大分辨率为 4096 × 2160。
返回值
- 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
- 视频源的类型,详见 VideoSourceType。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
startCameraCapture
开始通过摄像头采集视频。
public abstract int startCameraCapture( Constants.VideoSourceType sourceType, CameraCapturerConfiguration config);
详情
- 自从
- v4.2.0
调用该方法可以通过指定 sourceType 同时开启多路摄像头采集。
参数
- sourceType
-
视频源的类型。详见 VideoSourceType。
注:- 移动端最多支持 2 路摄像头采集的视频流 (要求设备支持双摄或者支持外接摄像头)。
- config
-
视频采集配置。详见 CameraCapturerConfiguration。
返回值
- 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
- 视频源的类型,详见 VideoSourceType。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
stopCameraCapture
停止通过摄像头采集视频。
public abstract int stopCameraCapture(Constants.VideoSourceType sourceType);
详情
- 自从
- v4.2.0
调用 startCameraCapture 开启一路或多路摄像头采集的视频流后,你可以调用该方法,通过设置 sourceType 停止一路或多路摄像头的视频采集。
参数
- sourceType
- 视频源的类型,详见 VideoSourceType。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
takeSnapshot
获取视频截图。
public abstract int takeSnapshot(int uid, String filePath);
详情
该方法用于对指定用户的视频流进行截图,生成一张 JPG 格式的图片,并保存至指定的路径。
该方法是异步操作,调用返回时 SDK 并没有真正获取截图。成功调用该方法后,SDK 会触发 onSnapshotTaken 回调报告截图是否成功和获取截图的详情。
- 该方法需要在加入频道后调用。
- 该方法用于本地视频截图时,是对 ChannelMediaOptions 中指定发布的视频流进行截图。
- 如果用户的视频经过前处理,例如,添加了水印或美颜,生成的截图会包含前处理效果。
参数
- uid
- 用户 ID。如果要对本地用户的视频截图,则设为 0。
- filePath
-
截图的本地保存路径,需精确到文件名及格式, 例如:
- Android:
/storage/emulated/0/Android/data/<package name>/files/example.jpg
- Android:
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateLocalTranscoderConfiguration
更新本地合图配置。
public abstract int updateLocalTranscoderConfiguration(LocalTranscoderConfiguration config);
详情
调用 startLocalVideoTranscoder 后,如果你希望更新本地合图配置,请调用该方法。
参数
- config
- 本地合图的配置,详见 LocalTranscoderConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
onFacePositionChanged
报告本地人脸检测结果。
public void onFacePositionChanged( int imageWidth, int imageHeight, AgoraFacePositionInfo[] faceRectArr) {}
enableFaceDetection(true)
开启本地人脸检测后,你可以通过该回调实时获取以下人脸检测的信息:
- 摄像头采集的画面大小
- 人脸在 view 中的位置
- 人脸距设备屏幕的距离
其中,人脸距设备屏幕的距离由 SDK 通过摄像头采集的画面大小和人脸在 view 中的位置拟合计算得出。
- 当检测到摄像头前的人脸消失时,该回调会立刻触发;在无人脸的状态下,该回调触发频率会降低,以节省设备耗能。
- 当人脸距离设备屏幕过近时,SDK 不会触发该回调。
- Android 平台上,人脸距设备屏幕的距离(distance)值有一定误差,请不要用它进行精确计算。
参数
- imageWidth
- 摄像头采集画面的宽度 (px)。
- imageHeight
- 摄像头采集画面的高度 (px)。
- faceRectArr
- 检测到的人脸信息,详见 AgoraFacePositionInfo。检测到几张人脸,就会报告几个 AgoraFacePositionInfo 数组。数组长度可以为 0,表示没有检测到摄像头前出现人脸。
onFirstLocalVideoFrame
已显示本地视频首帧回调。
public void onFirstLocalVideoFrame( Constants.VideoSourceType source, int width, int height, int elapsed) {}
本地视频首帧显示在本地视图上时,SDK 会触发此回调。
参数
- source
- 视频源的类型。详见 VideoSourceType。
- width
- 本地渲染视频的宽 (px) 。
- height
- 本地渲染视频的高 (px)。
- elapsed
- 从调用 joinChannel [2/2] 到发生此事件过去的时间(毫秒)。如果在 joinChannel [2/2] 前调用了 startPreview [2/2],则是从 startPreview [2/2]到发生此事件过去的时间。
onFirstLocalVideoFramePublished
已发布本地视频首帧回调。
public void onFirstLocalVideoFramePublished(Constants.VideoSourceType source, int elapsed) {}
- 开启本地视频的情况下,调用 joinChannel [2/2] 成功加入频道后。
- 调用 muteLocalVideoStream(
true
),再调用 muteLocalVideoStream(false
) 后。 - 调用 disableVideo,再调用 enableVideo 后。
- 调用 pushExternalVideoFrame [1/2] 成功向 SDK 推送视频帧后。
参数
- source
- 视频源的类型。详见 VideoSourceType。
- elapsed
- 从调用 joinChannel [2/2] 方法到触发该回调的时间间隔(毫秒)。
onFirstRemoteVideoDecoded
已接收到远端视频并完成解码回调。
public void onFirstRemoteVideoDecoded(int uid, int width, int height, int elapsed) {}
- 远端用户首次上线后发送视频。
- 远端用户视频离线再上线后发送视频。出现这种中断的可能原因包括:
- 远端用户离开频道。
- 远端用户掉线。
- 远端用户调用 muteLocalVideoStream 方法停止发送本地视频流。
- 远端用户调用 disableVideo 方法关闭视频模块。
参数
- uid
- 用户 ID,指定是哪个用户的视频流。
- width
- 视频流宽(px)。
- height
- 视频流高(px)。
- elapsed
- 从本地调用 joinChannel [2/2] 开始到该回调触发的延迟(毫秒)。
onFirstRemoteVideoFrame
渲染器已接收首帧远端视频回调。
public void onFirstRemoteVideoFrame(int uid, int width, int height, int elapsed) {}
参数
- uid
- 用户 ID,指定是哪个用户的视频流。
- width
- 视频流宽(px)。
- height
- 视频流高(px)。
- elapsed
- 从本地调用 joinChannel [2/2] 到发生此事件过去的时间(毫秒)。
onLocalVideoStateChanged
本地视频状态发生改变回调。
public void onLocalVideoStateChanged(Constants.VideoSourceType source, int state, int error) { super.onLocalVideoStateChanged(source, state, error); mCallbackObj = new Object[] {source, state, error}; }
本地视频的状态发生改变时,SDK 会触发该回调返回当前的本地视频状态。你可以通过该回调了解当前视频的状态以及出现故障的原因,方便排查问题。
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 的视频帧。
参数
- source
- 视频源的类型。详见 VideoSourceType。
- state
-
- LOCAL_VIDEO_STREAM_STATE_STOPPED (0): 本地视频默认初始状态。
- LOCAL_VIDEO_STREAM_STATE_CAPTURING (1): 本地视频采集设备启动成功。
- LOCAL_VIDEO_STREAM_STATE_ENCODING (2): 本地视频首帧编码成功。
- LOCAL_VIDEO_STREAM_STATE_FAILED (3): 本地视频启动失败。
- error
-
- LOCAL_VIDEO_STREAM_ERROR_OK (0): 本地视频状态正常。
- LOCAL_VIDEO_STREAM_ERROR_FAILURE (1): 出错原因不明确。
- LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY (3): 本地视频采集设备正在使用中。请提示用户检查摄像头是否被其他应用占用。
- LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE (4): 本地视频采集失败。请提示用户检查视频采集设备是否正常工作,检查摄像头是否被其他应用占用,或者尝试重新加入频道。
- Android 9 及以上版本,app 切后台一段时间后,系统收回相机权限。
- Android 6 及以上版本,如果相机被第三方应用占用,且未被及时释放。如果一段时间后,相机被释放,则 SDK会再次出发该回调,并报告
state
为CAPTURING
,error
为ERROR_OK
。
- LOCAL_VIDEO_STREAM_ERROR_ENCODE_FAILURE (5):本地视频编码失败。
- LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND (8):找不到本地视频采集设备。需检查摄像头是否与设备正常连接、摄像头是否正常工作,或者尝试重新加入频道。
onLocalVideoStats
本地视频流统计信息回调。
public void onLocalVideoStats(Constants.VideoSourceType source, LocalVideoStats stats) {}
该回调描述本地设备发送视频流的统计信息,每 2 秒触发一次。
参数
- source
- 视频源的类型。详见 VideoSourceType。
- stats
- 本地视频流统计信息。详见 LocalVideoStats。
onLocalVideoTranscoderError
本地合图发生错误回调。
public void onLocalVideoTranscoderError( LocalTranscoderConfiguration.TranscodingVideoStream stream, int error) {}
详情
- 自从
- v4.2.0
当你调用 startLocalVideoTranscoder 或 updateLocalTranscoderConfiguration 失败时,SDK 会触发该回调,报告合图失败的原因。
参数
- stream
- 合图失败的视频流。详见 TranscodingVideoStream。
- error
- 本地合图出错原因。
onRemoteVideoStateChanged
远端视频状态发生改变回调。
public void onRemoteVideoStateChanged(int uid, int state, int reason, int elapsed) {}
参数
- uid
- 发生视频状态改变的远端用户 ID。
- state
-
远端视频流状态:
- REMOTE_VIDEO_STATE_STOPPED(0):远端视频默认初始状态。在
REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED(3)
、REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5)
、REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE(7)
或REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK(8)
的情况下,会报告该状态。 - REMOTE_VIDEO_STATE_STARTING(1):本地用户已接收远端视频首包。
- REMOTE_VIDEO_STATE_PLAYING(2):远端视频流正常解码播放。在
REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY(2)
、REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED(4)
、REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6)
或REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9)
的情况下,会报告该状态。 - REMOTE_VIDEO_STATE_FROZEN(3):远端视频流卡顿。在
REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION(1)
的情况下,会报告该状态。 - REMOTE_VIDEO_STATE_FAILED(4):远端视频流播放失败。在
REMOTE_VIDEO_STATE_REASON_INTERNAL(0)
的情况下,会报告该状态。
- REMOTE_VIDEO_STATE_STOPPED(0):远端视频默认初始状态。在
- reason
-
远端视频流状态改变的具体原因:
- REMOTE_VIDEO_STATE_REASON_INTERNAL(0):内部原因。
- REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION(1):网络阻塞。
- REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY(2):网络恢复正常。
- REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED(3):本地用户停止接收远端视频流或本地用户禁用视频模块。
- REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED(4):本地用户恢复接收远端视频流或本地用户启动视频模块。
- REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5):远端用户停止发送视频流或远端用户禁用视频模块。
- REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6):远端用户恢复发送视频流或远端用户启用视频模块。
- REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE(7):远端用户离开频道。
- REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK(8):远端视频流已回退为音频流。
- REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9):回退的远端音频流恢复为视频流。
- REMOTE_VIDEO_STATE_REASON_CODEC_NOT_SUPPORT(13):本地的视频解码器不支持对收到的远端视频流进行解码。
- elapsed
- 从本地用户调用 joinChannel [2/2] 方法到发生本事件经历的时间,单位为毫秒。
onRemoteVideoStats
通话中远端视频流的统计信息回调。
public void onRemoteVideoStats(RemoteVideoStats stats) {}
该回调描述远端用户在通话中端到端的视频流统计信息, 针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播, 该回调每 2 秒会被触发多次。
参数
- stats
- 远端视频统计数据。详见 RemoteVideoStats。
onRemoteVideoTransportStats
通话中远端视频流传输的统计信息回调。
public void onRemoteVideoTransportStats(int uid, int delay, int lost, int rxKBitRate) {}
- 弃用:
- 该回调已被废弃,请改用 onRemoteVideoStats。
该回调描述远端用户通话中端到端的网络统计信息,通过视频包计算,用客观的数据,如丢包、 网络延迟等,展示当前网络状态。
通话中,当用户收到远端用户/主播发送的视频数据包后,会每 2 秒触发一次该回调。
参数
- uid
- 用户 ID,指定是哪个用户/主播的视频包。
- delay
- 视频包从发送端到接收端的延时(毫秒)。
- lost
- 视频包从发送端到接收端的丢包率 (%)。
- rxKBitRate
- 远端视频包的接收码率(Kbps)。
onRhythmPlayerStateChanged
虚拟节拍器状态发生改变回调。
public void onRhythmPlayerStateChanged(int state, int errorCode) {}
虚拟节拍器状态发生改变时,SDK 会触发该回调报告当前的虚拟节拍器状态。在虚拟节拍器出现故障时,该回调可以帮助你了解当前虚拟节拍的状态以及出现故障的原因,方便你排查问题。
参数
- state
- 当前的虚拟节拍器状态。
- RHYTHM_PLAYER_STATE_IDLE (810): 虚拟节拍器未开启或已关闭。
- RHYTHM_PLAYER_STATE_OPENING (811): 正在打开节拍音频文件。
- RHYTHM_PLAYER_STATE_DECODING (812): 正在解码节拍音频文件。
- RHYTHM_PLAYER_STATE_PLAYING (813): 正在播放节拍音频文件。
- RHYTHM_PLAYER_STATE_FAILED (814): 开启虚拟节拍器失败。你可以通过报告的错误码 errorCode 排查错误原因,也可以重新尝试开启虚拟节拍器。
- errorCode
- 虚拟节拍器发生错误的错误码和错误信息。
- RHYTHM_PLAYER_ERROR_OK (0): 正常播放节拍音频文件,没有错误。
- RHYTHM_PLAYER_ERROR_FAILED (1): 一般性错误,没有明确原因。
- RHYTHM_PLAYER_ERROR_CAN_NOT_OPEN (801): 打开节拍音频文件出错。
- RHYTHM_PLAYER_ERROR_CAN_NOT_PLAY (802): 播放节拍音频文件出错。
- RHYTHM_PLAYER_ERROR_FILE_OVER_DURATION_LIMIT (803): 节拍音频文件时长超出限制。最大时长为 1.2 秒。
onSnapshotTaken
视频截图结果回调。
public void onSnapshotTaken(int uid, String filePath, int width, int height, int errCode) {}
成功调用 takeSnapshot 后,SDK 触发该回调报告截图是否成功和获取截图的详情。
参数
- uid
- 用户 ID。如果 uid 为 0,表示本地用户。
- filePath
- 截图的本地保存路径。
- width
- 图片宽度(px)。
- height
- 图片高度(px)。
- errCode
- 截图成功的提示或失败的原因。
- 0:截图成功。
- < 0: 截图失败。
- -1:写入文件失败或 JPEG 编码失败。
- -2:takeSnapshot 方法调用后 1 秒内没有收到指定用户的视频帧。可能的原因有:本地采集停止、远端停止发布或者视频数据处理堵塞。
- -3:takeSnapshot 方法调用过于频繁。
onUserEnableLocalVideo
远端用户开/关本地视频采集回调。
public void onUserEnableLocalVideo(int uid, boolean enabled) {}
该回调是由远端用户调用 enableLocalVideo 方法开启或关闭视频采集触发的。
参数
- uid
- 用户 ID,提示是哪个用户的视频流。
- enabled
-
远端用户是否启用视频采集:
-
true
: 该用户已启用视频功能。启用后,其他用户可以接收到该用户的视频流。 -
false
: 该用户已关闭视频功能。关闭后,该用户仍然可以接收其他用户的视频流,但其他用户接收不到该用户的视频流。
-
onUserEnableVideo
远端用户开/关视频模块回调。
public void onUserEnableVideo(int uid, boolean enabled) {}
关闭视频功能是指该用户只能进行语音通话,不能显示、发送自己的视频,也不能接收、显示别人的视频。
该回调是由远端用户调用 enableVideo 或 disableVideo 方法开启或关闭视频模块触发的。
参数
- uid
- 用户 ID,提示是哪个用户的视频流。
- enabled
-
-
true
: 该用户已启用视频功能。 -
false
: 该用户已关闭视频功能。
-
onUserMuteVideo
远端用户取消或恢复发布视频流回调。
public void onUserMuteVideo(int uid, boolean muted) {}
当远端用户调用 muteLocalVideoStream 取消或恢复发布视频流时,SDK 会触发该回调向本地用户报告远端用户的发流状况。
参数
- uid
- 远端用户 ID。
- muted
- 远端用户是否取消发布视频流:
true
: 取消发布视频流。false
: 发布视频流。
onVideoPublishStateChanged
视频发布状态改变回调。
public void onVideoPublishStateChanged(Constants.VideoSourceType source, String channel, int oldState, int newState, int elapseSinceLastState) {}
参数
- channel
- 频道名。
- source
- 视频源的类型。详见 VideoSourceType。
- oldState
- 之前的发布状态,详见 STREAM_PUBLISH_STATE。
- newState
- 当前的发布状态,详见 STREAM_PUBLISH_STATE。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
onVideoSizeChanged
本地或远端视频大小和旋转信息发生改变回调。
public void onVideoSizeChanged( Constants.VideoSourceType source, int uid, int width, int height, int rotation) {}
参数
- source
- 视频源的类型。详见 VideoSourceType。
- uid
- 图像尺寸和旋转信息发生变化的用户 ID(本地用户的 uid 为 0。此时视频为本地用户的视频预览)。
- width
- 视频流的宽度(像素)。
- height
- 视频流的高度(像素)。
- rotation
- 旋转信息,取值范围 [0,360)。
onVideoStopped
视频功能已停止回调。
public void onVideoStopped() {}
- 弃用:
- 请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_STOPPED(0)。
App 如需在停止视频后对 view 做其他处理(比如显示其他画面),可以在这个回调中进行。
onVideoSubscribeStateChanged
视频订阅状态发生改变回调。
public void onVideoSubscribeStateChanged( String channel, int uid, int oldState, int newState, int elapseSinceLastState) {}
参数
- channel
- 频道名。
- uid
- 远端用户的 ID。
- oldState
- 之前的订阅状态。
- SUB_STATE_IDLE (0): 加入频道后的初始订阅状态。
- SUB_STATE_NO_SUBSCRIBED (1): 订阅失败。可能是因为:
- 远端用户:
- 调用 muteLocalAudioStream(
true
) 或 muteLocalVideoStream(true
) 停止发送本地媒体流。 - 调用 disableAudio 或 disableVideo 关闭本地音频或视频模块。
- 调用 enableLocalAudio(false) 或 enableLocalVideo(false) 关闭本地音频或视频采集。
- 用户角色为观众。
- 调用 muteLocalAudioStream(
- 本地用户调用以下方法停止接收远端媒体流:
- 调用 muteRemoteAudioStream(true)、 muteAllRemoteAudioStreams(true) 停止接收远端音频流。
- 调用 muteRemoteVideoStream(true)、 muteAllRemoteVideoStreams(true) 停止接收远端视频流。
- 远端用户:
- SUB_STATE_SUBSCRIBING (2): 正在订阅。
- SUB_STATE_SUBSCRIBED (3): 收到了远端流,订阅成功。
- newState
- 当前的订阅状态。
- SUB_STATE_IDLE (0): 加入频道后的初始订阅状态。
- SUB_STATE_NO_SUBSCRIBED (1): 订阅失败。可能是因为:
- 远端用户:
- 调用 muteLocalAudioStream(
true
) 或 muteLocalVideoStream(true
) 停止发送本地媒体流。 - 调用 disableAudio 或 disableVideo 关闭本地音频或视频模块。
- 调用 enableLocalAudio(false) 或 enableLocalVideo(false) 关闭本地音频或视频采集。
- 用户角色为观众。
- 调用 muteLocalAudioStream(
- 本地用户调用以下方法停止接收远端媒体流:
- 调用 muteRemoteAudioStream(true)、 muteAllRemoteAudioStreams(true) 停止接收远端音频流。
- 调用 muteRemoteVideoStream(true)、 muteAllRemoteVideoStreams(true) 停止接收远端视频流。
- 远端用户:
- SUB_STATE_SUBSCRIBING (2): 正在订阅。
- SUB_STATE_SUBSCRIBED (3): 收到了远端流,订阅成功。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。