Web播放器SDK接口说明 - 音视频终端SDK

本文对阿里云Web播放器SDK的属性、方法和事件进行了说明，并提供了播放器接口的示例代码。

属性

名称	类型	说明
id	String	播放器外层容器的dom元素ID。
source	String	使用URL播放方式时，通过source属性来指定视频播放地址URL。说明 URL播放方式的播放优先级最高，高于VID+PlayAuth、STS等其他播放方式，即使用VID+PlayAuth、STS等其他播放方式时，不能指定source属性，若指定了source属性，播放器将优先选择source中的地址播放。建议仅设置一种播放方式。 URL播放方式支持多清晰度设置，通过source属性来指定多路清晰度流的地址，更多信息，请参见多清晰度播放。示例如下： `source:’{“HD”:”address1”,”SD”:”address2”}’`
vid	String	媒体转码服务的媒体ID。
playauth	String	播放凭证，获取播放凭证请参见获取音视频播放凭证。
height	String	播放器高度，取值： 100% 100px 说明 Chrome浏览器下Flash播放器分别不能小于397x297px。
width	String	播放器宽度，取值： 100% 100px 说明 Chrome浏览器下Flash播放器分别不能小于397x297px。
videoWidth	String	视频宽度，仅H5模式支持。更多信息，请参见设置显示模式。
videoHeight	String	视频高度，仅H5模式支持。更多信息，请参见设置显示模式。
preload	Boolean	播放器自动加载，目前仅H5模式可用。
cover	String	播放器默认封面图片，请填写正确的图片URL地址。需要autoplay值为false时，才生效。Flash播放器封面也需要开启允许跨域访问。
isLive	Boolean	播放内容是否为直播，直播时会禁止用户拖动进度条。默认值为false，播放直播流时需要设置为true。
autoplay	Boolean	播放器是否自动播放，在移动端autoplay属性会失效。说明 Safari11不支持自动播放，如果需要，可通过右键单击浏览器地址栏，选择此网站的设置 > 允许全部自动播放来设置。
rePlay	Boolean	播放器自动循环播放。
useH5Prism	Boolean	指定使用H5播放器。
useFlashPrism	Boolean	指定使用Flash播放器。
playsinline	Boolean	H5是否内置播放，有的Android浏览器不起作用。
skinRes	Url	皮肤图片，不建议随意修改该字段，如要修改，更多信息，请参见设置播放器皮肤。
skinLayout	Array \| Boolean	功能组件布局配置，不传该字段使用默认布局。取值：false隐藏所有功能组件。更多信息，请参见配置skinLayout属性。
controlBarVisibility	String	控制面板的实现，默认值为：hover。取值： click：点击播放器区域。 hover：移动到播放器区域。 always：控制面板一直显示。 never：隐藏整个控制面板。
showBarTime	String	控制栏自动隐藏时间，单位毫秒。
extraInfo	String	JSON串，用于定制性的接口参数，目前仅Flash支持，取值： fullTitle：测试页面，全屏时显示视频标题。 m3u8BufferLength：播放HLS文件时加载缓存，ts文件长度，单位为秒。
enableSystemMenu	Boolean	是否允许系统右键菜单显示，默认为false。
format	String	指定播放地址格式，只有使用vid的播放方式时支持可选值，取值： mp4 hls或m3u8 flv mp3 默认为空，仅H5支持。
mediaType	String	指定返回音频还是视频，只有使用vid的播放方式时支持，默认值为video。取值： video：视频。 audio：针对只包含音频的视频格式，比如音频的MP4。仅H5支持。
qualitySort	String	指定排序方式，只有使用Vid + PlayAuth播放方式时支持。取值： desc：表示按倒序排序（即：从大到小排序）。 asc：示按正序排序（即：从小到大排序）。默认值：asc，仅H5支持。
definition	String	显示视频清晰度，多个使用半角逗号（,）分隔，比如：‘FD,LD’，此值是vid对应流清晰度的一个子集，仅H5模式支持。取值： FD（流畅） LD（标清） SD（高清） HD（超清） OD（原画） 2K（2K） 4K（4K）
defaultDefinition	String	默认视频清晰度，此值是vid对应流的一个清晰度，仅H5模式支持。取值： FD（流畅） LD（标清） SD（高清） HD（超清） OD（原画） 2K（2K） 4K（4K）
autoPlayDelay	Number	延迟播放时间，单位：秒。更多信息，请参见配置延迟播放。
autoPlayDelayDisplayText	String	延迟播放提示文本，更多信息，请参见配置延迟播放。
language	String	国际化，默认为zh-cn。如果未设置，则采用浏览器语言。取值： zh-cn：中文。 en-us：英文。
languageTexts	JSON	自定义国际化文本JSON结构，key的值需要和language属性值对应起来。示例：{jp:{Play:”Play”}}自定义值请参见JSON结构。
snapshot	Boolean	是否启用Flash截图功能。取值： true：启用。 false：禁用。（默认值）
snapshotWatermark	Object	H5设置截图水印。
useHlsPluginForSafari	Boolean	Safari浏览器是否启用HLS插件播放，Safari 11除外。取值： true：启用。 false：禁用。（默认值）
enableStashBufferForFlv	Boolean	H5播放FLV时，设置是否启用播放缓存，只在直播下起作用。取值： true：启用。（默认值） false：禁用。
stashInitialSizeForFlv	Number	H5播放FLV时，初始缓存大小，只在直播下起作用。默认32KB。当设置的值较小时，会提升起播速度，但是值太小时，可能会导致播放一小段之后卡顿。
loadDataTimeout	Number	缓冲多长时间后，提示用户切换低清晰度，单位：秒。默认20秒。
waitingTimeout	Number	最大缓冲超时时间，超过这个时间会有错误提示，单位：秒。默认60秒。
diagnosisButtonVisible	Boolean	是否显示检测按钮，取值： true：显示按钮。 false：不显示按钮。默认值为true。
disableSeek	Boolean	禁用进度条的Seek，取值： true：禁用。 false：不禁用。默认值为false。说明仅Flash支持。
encryptType	Number	设置是否播放阿里云视频加密（私有加密）视频，默认值为0，取值： 0：播放不加密视频。 1：播放私有加密视频。说明私有加密采用VID+playauth的方式进行播放。 Web端标准加密使用URL方式播放，请参见如何播放加密视频。
progressMarkers	Array	进度条打点内容数组，更多信息，请参见进度条标记。
vodRetry	Number	点播失败重试次数，默认3次。
liveRetry	Number	直播播放失败重试次数，默认5次。
hlsFrameChasing	Boolean	HLS直播模式下，是否开启追帧。取值： true：开启追帧。 false：不开启追帧。（默认值）
chasingFirstParagraph	Number	第一段追帧，单位：秒。默认20秒。
chasingSecondParagraph	Number	第二段追帧，单位：秒。默认40秒。
chasingFirstSpeed	Number	第一段追帧的倍速，默认1.1倍速。
chasingSecondSpeed	Number	第二段追帧的倍速，默认1.2倍速。
flvFrameChasing	Boolean	FLV直播模式下，是否开启追帧，取值： true：开启追帧。 false：不开启追帧。默认值为false。
keyShortCuts	Boolean	是否启用快捷键，取值： true：开启快捷键。 false：不开启快捷键。默认值为false。说明方向键（左右键）控制快进和快退，方向键（上下键）控制音量的增减，空格键暂停和播放。
keyFastForwardStep	Number	快进快退的时间长度，单位：秒。默认10秒。
rtsFallbackSource	String	RTS的降级地址（如HLS地址或FLV地址）。在使用超低延时直播RTS地址播放的场景下，当浏览器不兼容RTS或RTS拉流失败时，会自动降级到该地址播放。
rtsLoadDataTimeout	Number	配置RTS拉取不到数据的超时时间（超时会重试），单位：毫秒。默认为3000毫秒。
traceId	String	traceId为您自有的用户唯一标识符，将traceId传入公共埋点，便于跟踪上报日志。正常情况下，Web播放器SDK已默认开启日志上报，传递traceId，可便于您标识用户身份；如果不传递，Web播放器SDK会默认生成一个uuid（播放器SDK生成的唯一标识符）并存储在浏览器缓存中。说明 Web播放器SDK 2.10.0及以上版本支持。
textTracks	Array	设置WebVTT外挂字幕，示例如下： `textTracks:[{kind:'subtitles',label:'英文（美国）',src:'字幕地址',srclang:'en-US'}],` 字段解释如下： kind：vtt类型，取值包括subtitles和captions。 label：用于显示的字幕名称。 srclang：字幕语言。 src：字幕地址，请允许跨域访问。说明 Web播放器SDK 2.12.0及以上版本支持。 WebVTT外挂字幕暂不支持以下浏览器： IE 安卓QQ浏览器、OPPO/一加的系统浏览器其他劫持video标签的浏览器

方法

方法需要在ready事件发生之后或创建播放器ready回调里，H5模式下可以在创建播放器构造函数的回调函数里调用。示例如下：

H5播放器

//H5 播放器
 var player = new Aliplayer({},function(player) {
    player.play();
 });

Flash播放器

//Flash 播放器
 player.on('ready',function(e) {
    player.play();
 });

名称	参数	说明
play	无	播放视频。
pause	无	暂停视频。
replay	无	重播视频。
seek	time	跳转到某个已加载的时刻进行播放，时间单位：秒。
getCurrentTime	无	获取当前的播放时刻，返回的时间单位：秒。
getDuration	无	获取视频总时长，返回的单位为秒，这个需要在视频加载完成以后才可以获取到，可以在play事件后获取。
getVolume	无	获取当前的音量，返回值为0~1的实数。iOS和部分Android会失效。
setVolume	无	设置音量，vol为0~1的实数，iOS和部分Android会失效。
loadByUrl	url，time	直接播放视频url，time为可选值（单位：秒）。目前只支持同种格式（MP4、FLV、HLS）之间切换。暂不支持直播RTMP流切换。
replayByVidAndPlayAuth	vid：视频ID，playauth：播放凭证	目前只支持H5播放器。暂不支持不同格式视频间的之间切换。暂不支持直播RTMP流切换。可用于点播DRM流的切换，用法：`player.replayByVidAndPlayAuth(vid,playauth)`。
replayByVidAndAuthInfo	仅MPS用户时使用参数顺序为：vid、accId、accSecret、stsToken、authInfo、domainRegion	目前只支持H5播放器。暂不支持不同格式视频间的之间切换。暂不支持直播rtmp流切换。
setPlayerSize	w，h	设置播放器大小，取值： 400px 60% Chrome浏览器下Flash播放器分别不能小于397x297px。
setSpeed	speed	手动设置播放的倍速，支持0.5~2倍速播放，倍速播放仅H5模式支持。移动端可能会失效，比如Android微信。倍速播放UI默认是开启的。说明关掉倍速的方法：目前无法单独关闭或者自定义倍速，只能整体关掉设置。通过hack方式关掉倍速是通过样式覆盖来实现的： `.prism-setting-speed { display: none !important; }`
setSanpshotProperties	width：宽度，height：高度，rate：截图质量	设置截图参数。
fullscreenService.requestFullScreen	无	播放器全屏，仅H5支持。
fullscreenService.cancelFullScreen	无	播放器退出全屏，iOS调用无效，仅H5支持。
fullscreenService.getIsFullScreen	无	获取播放器全屏状态，仅H5支持。
getStatus	无	获取播放器状态，取值： init：初始化。 ready：准备。 loading：加载中。 play：播放。 pause：暂停。 playing：正在播放。 waiting：等待缓冲。 error：错误。 ended：结束。
setRotate	rotate：旋转角度	参数为旋转角度，正数为正时针旋转，负数为逆时针旋转。示例：setRotate(90)。更多信息，请参见设置显示模式。
getRotate	无	获取旋转角度。更多信息，请参见设置显示模式。
setImage	image：镜像类型	设置镜像，取值： horizon：水平。 vertical：垂直。示例：setImage(‘horizon’)。更多信息，请参见设置显示模式。
dispose	无	播放器销毁。
setCover	cover：封面地址	设置封面。
setProgressMarkers	markers：打点数据集合	设置打点数据。
setPreviewTime	time：试看时间	设置试看时间，单位：秒。更多信息，请参见试看。
getPreviewTime	无	获取试看时间。
isPreview	无	是否试看。
getCurrentPDT	无	HLS的视频格式支持实时获取ProgramDateTime。
setTraceId	traceId：公共埋点	传入公共埋点，用于日志跟踪，用法：`player.setTraceId(traceId);`。说明 Web播放器SDK 2.10.0及以上版本支持。
setTextTracks	textTracks	设置一组WebVTT字幕，示例如下： `player.setTextTracks([{kind:'subtitles',label:'英文（美国）',src:'字幕地址',srclang:'en-US'}])` 说明 Web播放器SDK 2.12.0及以上版本支持。

事件

播放器事件

名称	说明
ready	播放器视频初始化按钮渲染完毕。播放器UI初始设置需要此事件后触发，避免UI被初始化所覆盖。说明播放器提供的方法需要在该事件发生后才可以调用。
play	视频由暂停恢复为播放时触发。
pause	视频暂停时触发。
canplay	能够开始播放音频和视频时发生，会多次触发，仅H5播放器。
playing	播放中，会触发多次。
ended	当前视频播放完毕时触发。
liveStreamStop	直播流中断时触发。HLS直播流在重试5次未成功后触发。提示上层流中断或需要重新加载视频。说明如果HLS直播流断流或者出错，播放器会自动重试5次，不需要上层添加重试逻辑。
onM3u8Retry	HLS直播流中断后重试事件，每次断流只触发一次。
hideBar	控制栏自动隐藏事件。
showBar	控制栏自动显示事件。
waiting	数据缓冲事件。
timeupdate	播放位置发生改变时触发，仅H5模式播放器。可通过getCurrentTime方法，得到当前播放时间。
snapshoted	截图完成事件。
requestFullScreen	全屏事件，仅H5模式支持。
cancelFullScreen	取消全屏事件，iOS下不会触发，仅H5模式支持。
error	错误事件。
startSeek	开始拖拽，参数返回拖拽点的时间。
completeSeek	完成拖拽，参数返回拖拽点的时间。
resolutionChange	直播情况下，推流端切换了分辨率。
seiFrame	HLS或FLV收到SEI消息。
rtsFallback	当RTS降级时触发。其中，参数`reason`为降级的原因，`fallbackUrl`为降级到的地址。
settingSelected	当设置列表（倍速、清晰度、字幕等）被选中时触发。 `/** * 设置列表被选中，如切换倍速到1.25X： * {name: '倍速', type: 'speed', text: '1.25X', key: 1.25} */`
rtsTraceId	当RTS拉流成功时触发，通过订阅该事件，可以获取到RTS TraceId。回调函数的参数中traceId为拉流的TraceId，source为当前RTS流的播放地址。 `player.on('rtsTraceId', function(data) { console.log('[EVENT]rtsTraceId', data.paramData); })`

订阅事件

通过播放器实例的on方法订阅。示例如下：

var handleReady = function(e)
{
 console.log(e);
}
player.on('ready',handleReady);

通过播放器实例的off方法取消订阅。示例如下：
```
player.off('ready',handleReady);
```