流对象(Stream)
本章节介绍了Web SDK的Stream接口详情。
序号 |
接口 |
描述 |
1 |
initialize |
本地流初始化。 |
2 |
play |
播放该音视频流。 |
3 |
stop |
停止播放视频流。 |
4 |
resume |
恢复播放音视频。 |
5 |
close |
关闭音视频。 |
6 |
muteAudio |
禁用音频轨道。 |
7 |
muteVideo |
禁用视频轨道。 |
8 |
unmuteAudio |
启用音频轨道。 |
9 |
unmuteVideo |
启用视频轨道。 |
10 |
getId |
获取Stream唯一标识ID。 |
11 |
getUserId |
获取Stream所属的用户ID。 |
12 |
hasAudio |
流是否包含音频轨道。 |
13 |
hasVideo |
流是否包含视频轨道。 |
14 |
getAudioTrack |
获取流的音频轨道。 |
15 |
getVideoTrack |
获取流的视频轨道。 |
16 |
getType |
获取流类型。 |
17 |
getStreamInfo |
获取流信息。 |
表7.3.4.4-1 Stream接口
initialize
initialize(): Promise<StreamInitializeResult >
【功能说明】
根据createStream入参StreamConfig,初始化本地音视频流对象。流只有初始化完成后才可以播放。
【请求参数】
无
【返回参数】
StreamInitializeResult 。如果所有的媒体类型都初始化成功的时候返回。
如果任意一个媒体类型初始化失败,则返回错误,错误对象定义同样为StreamInitializeResult 。
StreamInitializeResult 表示流初始化的结果。对象继承自RtcError。提供如下方法:
getMediaCaptureResult():MediaCaptureResult[]
该方法获取所有媒体类型的初始化结果。
getMediaCaptureResultByType(type: MediaType): MediaCaptureResult
该方法获取指定媒体类型的初始化结果。
MediaCaptureResult类型定义如下:
{
type:必选,表示媒体类型,类型为MediaType,MediaType枚举值包括'audio'或者'video'。
track:可选,表示对应媒体类型如果初始化成功后的track,类型为MediaStreamTrack。
error:可选,表示对应媒体类型如果初始化失败的错误,类型为RtcError。
}
媒体类型如果初始化失败返回错误信息请参考"初始化错误信息列表"。
错误原因 |
描述 |
处理措施 |
---|---|---|
NotFoundError |
找不到满足请求参数的媒体类型(包括:音频、视频、屏幕分享)。例如:PC没有摄像头,但是请求浏览器获取视频流,则会触发该错误。 |
建议在通话开始前引导用户检查通话所需的摄像头或麦克风等设备,若无摄像头设备且需要进行语音通话,可在创建本地流对象ISDPRTC.createStream({ audio: true, video: false }) 指明仅采集麦克风。 |
NotAllowedError |
未获得用户设备列表(摄像头、麦克风、屏幕共享)的授权。 |
提示用户不授权摄像头/麦克风访问无法进行音视频通话。 |
NotReadableError |
尽管用户已经授权使用相应的设备,但是由于操作系统上某个硬件、浏览器或者网页层面发生的错误导致设备无法被访问。 |
根据浏览器的报错信息处理,并提示用户“暂时无法访问摄像头/麦克风,请确保当前没有其他应用请求访问摄像头/麦克风,并重试”。 |
OverConstrainedError |
cameraId/microphoneId参数的值无效。 |
确保cameraId/microphoneId传值正确且有效。 |
AbortError |
由于某些未知原因导致设备无法被使用。 |
- |
表7.3.4.4-2 初始化错误信息列表
play
async play(elementId: string, options?:Options): Promise<void>
【功能说明】
播放音视频流。该方法会自动创建<video> 标签,并在指定的标签上播放音频和视频,同时该标签会被添加到页面中名为“elementId ”的div容器下。
【请求参数】
elementId:必选,string类型,HTML <div> 标签ID。
options:可选,Options类型,播放选项。
Options类型定义为:
{
objectFit:可选,string类型,支持的枚举值如下:
'contain' :优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。
'cover' :优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。
'fill' :视频内容完全填充视窗。如果视频的宽高比与视窗不相匹配,那么视频将被拉伸以适应视窗。
muted:可选,boolean类型,true表示静音,false表示不静音。默认值为false。
}
【返回参数】
Promise<void>:返回一个Promise对象。
由于浏览器自动播放策略的限制,在play() 返回错误后需要引导用户通过手动触发页面控件后,调用resume接口恢复播放。
本地流通常需要mute声音以防播放从麦克风采集的声音。
stop
stop(option?:StopOption): void
【功能说明】
停止播放音视频流(移除视频流播放的dom对象)
【请求参数】
option:可选,表示停止播放的选项。如果不传,则停止该流的音频和所有分辨率的视频。
类型为StopOption,定义如下:
{
audio:可选,boolean类型。表示是否停止音频。默认为false。
video:可选,boolean类型。表示是否停止视频。默认为false。
}
【返回参数】
无
resume
async resume(option?:ResumeOption): Promise<void>
【功能说明】
恢复播放音视频。场景说明如下:
在某些版本浏览器上,移动传入play() 的div容器可能会导致音视频播放器进入‘PAUSED’状态,此时需要调用该接口恢复播放。
由于浏览器自动播放策略的限制,在play() 返回错误后需要引导用户通过手动方式调用该接口恢复播放。
【请求参数】
option:可选,表示恢复播放的选项,类型为ResumeOption,如果不传则恢复播放该流的音频和所有分辨率的视频。
ResumeOption类型定义为:
{
audio:可选,boolean类型。是否resume音频。默认为false。
video:可选,boolean类型。是否resume视频。默认为false。
}
【返回参数】
Promise<void>:返回一个Promise对象。
muteAudio
muteAudio(): boolean
【功能说明】
禁用音频轨道。
【请求参数】
无
【返回参数】
boolean类型,true表示禁用音频轨道成功,false表示禁用音频轨道失败。
muteVideo
muteVideo(): boolean
【功能说明】
禁用视频轨道。
【请求参数】
无
【返回参数】
boolean类型,true表示禁用视频轨道成功,false表示禁用视频轨道失败。
unmuteAudio
unmuteAudio(): boolean
【功能说明】
启用音频轨道。
【请求参数】
无
【返回参数】
boolean类型,true表示启用音频轨道成功,false表示启用音频轨道失败。
unmuteVideo
unmuteVideo(): boolean
【功能说明】
启用视频轨道。
【请求参数】
无
【返回参数】
boolean类型,true表示启用视频轨道成功,false表示启用视频轨道失败。
getUserId
getUserId(): string
【功能说明】
获取Stream所属的用户ID。对于本地流,如果在createStream的时候入参StreamConfig中没有设置该参数,则返回undefined
【请求参数】
无
【返回参数】
string类型,Stream所属的用户ID。
setAudioVolume
setAudioVolume(volume: number): void
【功能说明】
设置音频音量大小。
【请求参数】
volume:必选,number类型,音量大小,取值范围为[0,100]。
【返回参数】
无
getAudioLevel
getAudioLevel(): number
【功能说明】
获取实时音量级别。
【请求参数】
无
【返回参数】
number类型,返回值在(0, 1)之间,通常该值大于0.1认为用户正在说话。
hasAudio
hasAudio(): boolean
【功能说明】
该stream是否包含音频轨道。
【请求参数】
无
【返回参数】
boolean类型,true表示包含音频轨道,false表示不包含音频轨道。
hasVideo
hasVideo(): boolean
【功能说明】
该stream是否包含视频轨道
【请求参数】
无
【返回参数】
boolean类型,true表示包含视频轨道,false表示不包含视频轨道
getAudioTrack
getAudioTrack(): MediaStreamTrack
【功能说明】
获取音频轨道
【请求参数】
无
【返回参数】
MediaStreamTrack类型。
getVideoTrack
getVideoTrack(): MediaStreamTrack
【功能说明】
获取视频轨道。
【请求参数】
无,默认选择分辨率最高的视频。
【返回参数】
MediaStreamTrack类型。
getType
getType(): string
【功能说明】
获取流类型。用于判断一个流是主流还是辅流,辅流通常是一个屏幕辅流。
【请求参数】
无
【返回参数】
string类型,本地流:'local',远端主流:'main' ,远端辅流:'auxiliary'。