本文对Web播放器SDK的属性、方法、事件进行了说明,并提供了播放器接口的示例代码。
属性
如果您在使用过程中遇见问题,可以参考Web播放器常见问题或播放异常自主排查。
名称 | 类型 | 说明 |
id | String | 播放器外层容器的DOM元素ID。 |
source | String | 使用URL播放方式时,通过source属性来指定视频播放地址URL。 说明
|
vid | String | 媒体转码服务的媒体ID。 |
playauth | String | 播放凭证,获取播放凭证请参见获取音视频播放凭证。 |
playConfig | JSON | 使用Vid方式(VidAuth和VidSts方式)播放时的自定义设置字段,会透传给点播接口。支持设置的自定义字段及参数说明,请参见媒体播放自定义设置 PlayConfig。取值示例:
|
authTimeout | Number | 通过Vid方式(VidAuth和VidSts方式)播放时,获取到的视频播放URL的有效时长。单位:秒,默认取值:7200。 请确保该时长大于视频的实际时长,防止播放地址在播放完成前过期。 |
height | String | 播放器高度,取值:
说明 Chrome浏览器下Flash播放器分辨率不能小于397x297px。 |
width | String | 播放器宽度,取值:
说明 Chrome浏览器下Flash播放器分辨率不能小于397x297px。 |
autoSize | Boolean | String | 播放器尺寸自动适配视频内容,可选值 'height', 'width'。 如,您可以指定 width: '500px', autoSize: 'height',播放器会保持宽度为 500px,高度根据视频实际比例自动调整。 或者,您可以指定 height: '500px', autoSize: 'width',播放器会保持高度为 500px,宽度根据视频实际比例自动调整 注:autoSize: true 等同于 autoSize: 'height',即默认是高度自适应。 |
videoWidth | String | 视频宽度,仅H5模式支持。更多信息,请参见设置显示模式。 |
videoHeight | String | 视频高度,仅H5模式支持。更多信息,请参见设置显示模式。 |
preload | Boolean | 播放器自动加载,目前仅H5模式可用。 |
cover | String | 播放器默认封面图片,请填写正确的图片URL地址。需要autoplay值为false时,才生效。Flash播放器封面也需要开启允许跨域访问。 |
isLive | Boolean | 播放内容是否为直播,直播时会禁止用户拖动进度条。默认值为false,播放直播流时需要设置为true。 |
autoplay | Boolean | 播放器是否自动播放,在移动端autoplay属性会失效。取值:
说明 由于浏览器的限制,Web播放器SDK会出现自动播放失败的场景,具体说明请参见自动播放。 |
autoplayPolicy | Object | 播放器自适应静音自动播放策略。仅当
说明
|
rePlay | Boolean | 播放器自动循环播放。 |
useH5Prism | Boolean | 指定使用H5播放器。 |
useFlashPrism | Boolean | 指定使用Flash播放器。 |
playsinline | Boolean | H5是否内置播放,有些Android浏览器不起作用。 |
skinRes | Url | 皮肤图片,不建议随意修改该字段,如要修改,请参见设置播放器皮肤。 |
skinLayout | Array | Boolean | 功能组件布局配置,不传该字段使用默认布局。取值:false表示隐藏所有功能组件。更多信息,请参见配置skinLayout属性。 |
skinLayoutIgnore | Array | 需要隐藏的UI组件。组件名称请参见点播组件参数说明。配置示例如下:
说明 skinLayoutIgnore的优先级要高于skinLayout属性。 |
controlBarVisibility | String | 控制面板的实现,取值:
|
showBarTime | Number | 控制栏自动隐藏时间,单位:毫秒。 |
extraInfo | String | JSON串,用于定制性的接口参数,目前仅Flash支持,取值:
|
enableSystemMenu | Boolean | 是否允许系统右键菜单显示,默认为false。 |
format | String | 指定播放地址格式,取值:
默认为空,仅H5支持。 |
mediaType | String | 指定返回音频还是视频,只有使用vid的播放方式时支持,默认值为video。取值:
|
qualitySort | String | 指定排序方式,只有使用Vid + PlayAuth播放方式时支持。取值:
默认值:asc,仅H5支持。 |
definition | String | 显示视频清晰度,多个使用半角逗号(,)分隔,比如:‘FD,LD’,此值是vid对应流清晰度的一个子集,仅H5模式支持。取值:
|
defaultDefinition | String | 默认视频清晰度,此值是vid对应流的一个清晰度,仅H5模式支持。取值:
|
autoPlayDelay | Number | 延迟播放时间,单位:秒。更多信息,请参见配置延迟播放。 |
autoPlayDelayDisplayText | String | 延迟播放提示文本,更多信息,请参见配置延迟播放。 |
language | String | 国际化,默认为zh-cn。如果未设置,则采用浏览器语言。取值:
|
languageTexts | JSON | 自定义国际化文本JSON结构,key的值需要和language属性值对应起来。示例:{jp:{Play:”Play”}}自定义值请参见JSON结构。 |
snapshot | Boolean | 是否启用Flash截图功能。取值:
|
snapshotWatermark | Object | H5设置截图水印。 |
useHlsPluginForSafari | Boolean | Safari浏览器是否启用HLS插件播放,Safari 11除外。取值:
|
enableStashBufferForFlv | Boolean | H5播放FLV时,设置是否启用播放缓存,只在直播下起作用。取值:
|
stashInitialSizeForFlv | Number | H5播放FLV时,初始缓存大小,只在直播下起作用。默认32KB。 当设置的值较小时,会提升起播速度,但是值太小时,可能会导致播放一小段之后卡顿。 |
loadDataTimeout | Number | 缓冲多长时间后,提示用户切换低清晰度,单位:秒。默认20秒。 |
waitingTimeout | Number | 最大缓冲超时时间,超过这个时间会有错误提示,单位:秒。默认60秒。 |
diagnosisButtonVisible | Boolean | 是否显示检测按钮,取值:
|
disableSeek | Boolean | 禁用进度条的Seek,取值:
|
encryptType | Number | 设置是否播放阿里云视频加密(私有加密)视频,默认值为0,取值:
|
progressMarkers | Array | 进度条打点内容数组,更多信息,请参见进度条标记。 |
vodRetry | Number | 点播失败重试次数,默认3次。 |
liveRetry | Number | 直播播放失败重试次数,默认5次。 |
hlsFrameChasing | Boolean | HLS直播模式下,是否开启追帧。取值:
说明 仅2.21.0以下版本Web播放器SDK支持设置本参数,2.21.0及以上版本如需在HLS直播模式下设置追帧,请参考 |
chasingFirstParagraph | Number | 第一段追帧,单位:秒。默认20秒。 说明 仅2.21.0以下版本Web播放器SDK支持设置本参数,2.21.0及以上版本如需在HLS直播模式下设置追帧,请参考 |
chasingSecondParagraph | Number | 第二段追帧,单位:秒。默认40秒。 说明 仅2.21.0以下版本Web播放器SDK支持设置本参数,2.21.0及以上版本如需在HLS直播模式下设置追帧,请参考 |
chasingFirstSpeed | Number | 第一段追帧的倍速,默认1.1倍速。 说明 仅2.21.0以下版本Web播放器SDK支持设置本参数,2.21.0及以上版本如需在HLS直播模式下设置追帧,请参考 |
chasingSecondSpeed | Number | 第二段追帧的倍速,默认1.2倍速。 说明 仅2.21.0以下版本Web播放器SDK支持设置本参数,2.21.0及以上版本如需在HLS直播模式下设置追帧,请参考 |
hlsOption.maxLiveSyncPlaybackRate | Number | HLS直播模式下,设置直播追帧时的播放速度,默认为1,表示不追帧。
说明 仅2.21.0及以上版本Web播放器SDK支持设置本参数。 |
flvFrameChasing | Boolean | FLV直播模式下,是否开启追帧,取值:
默认值为false。 |
keyShortCuts | Boolean | 是否启用快捷键,取值:
默认值为false。 说明 方向键(左右键)控制快进和快退,方向键(上下键)控制音量的增减,空格键暂停和播放。 |
keyFastForwardStep | Number | 快进快退的时间长度,单位:秒。默认为10秒。 |
rtsFallback | Boolean | 当浏览器不支持RTS或RTS拉流失败时,播放器会自动尝试使用FLV/HLS进行降级播放,且优先选择延迟更低的FLV,当浏览器不支持FLV时,会选择HLS。 此功能是默认开启的,如果您需要禁用,可以传false。 |
rtsFallbackType | String | 指定RTS降级到的协议,可选 HLS/FLV,默认不传此参数,代表自动选择,播放器会优先选择延迟更低的FLV,如果浏览器不支持则降级到HLS。 |
rtsFallbackSource | String | 我们推荐使用播放器的默认降级策略,但是如果您希望指定固定的拉流地址进行降级,可以使用此参数。 |
mediaAuth | String | 通用媒体管理服务的视频播放凭证。 可以登录通用媒体管理服务控制台获取(路径: )。示例:pg89f1200baw94rmcky2e**** 说明 Web播放器SDK 2.10.0及以上版本支持。 |
traceId | String | traceId为您自有的用户唯一标识符,将traceId传入公共埋点,便于跟踪上报日志。正常情况下,Web播放器SDK已默认开启日志上报,传递traceId,可便于您标识用户身份;如果不传递,Web播放器SDK会默认生成一个uuid(播放器SDK生成的唯一标识符)并存储在浏览器缓存中。 说明 Web播放器SDK 2.10.0及以上版本支持。 |
textTracks | Array | 设置WebVTT外挂字幕,示例如下:
字段解释如下:
|
ratio | Number | 设置播放器按照固定比例缩放。例如:已知视频长宽比为16:9,通过设置播放器参数为 |
extLanguageTexts | Object | 播放器SDK内置了一套中英文界面文案,您可以通过本属性自定义部分界面的显示文案。以修改分辨率的显示文案为例:HD默认显示为高清,可以通过以下方式修改HD显示为1080p。
|
speedLevels | Array | 设置自定义倍速列表数组,key表示倍速数值,text表示UI文本,若不传则会使用默认列表。参数取值示例如下:
|
logo | Array | 设置自定义Logo图片。示例如下:
字段解释如下:
|
license | Object | 如需使用播放质量监控、单点追查、播放H.265/H.266编码协议视频流等增值功能,请先填写Web播放器SDK增值服务申请表单申请License授权后,再按如下方式接入License:
|
mute | Boolean | 设置是否静音播放。在浏览器禁止自动播放时可以通过配置此参数进行静音自动播放。详情请参见自动播放。 |
clickPause | Boolean | 点击视频画面进行暂停或播放。 |
disablePip | Boolean | 隐藏浏览器自带的画中画按钮。 说明
|
env | String | 播放器的埋点数据默认会上传到中国数据中心,如果您有海外数据合规需求,请传入参数 env: 'SEA',数据将上传到新加坡数据中心。 |
watchStartTime | Number | 单独使用,代表开始播放的时间; 和 watchEndTime 配合使用,开启区间播放功能,只能在开始和结束时间范围内播放和拖拽进度条。 单位:秒 |
watchEndTime | Number | 和 watchStartTime 配合使用,开启区间播放功能,只能在开始和结束时间范围内播放和拖拽进度条。 如果参数值小于watchStartTime,则watchStartTime失效。 单位:秒 |
start | Number | 和 end 配合使用,截取视频的一部分作为一个独立的视频。如:原视频时长 60 秒,设置 start:10、end:30 后,视频显示时长为 20 秒,并从原视频的第 10 秒开始播放。 |
end | Number | 和 start 配合使用,截取视频的一部分作为一个独立的视频。如:原视频时长 60 秒,设置 start:10、end:30 后,视频显示时长为 20 秒,并从原视频的第 10 秒开始播放。 |
方法
方法需要在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会失效。 |
mute | 无 | 设置静音。 |
unMute | 无 | 取消静音。 |
loadByUrl | url(String),time(Number) | 直接播放视频url,time为可选值(单位:秒)。目前只支持同种格式(MP4、FLV、HLS)之间切换。暂不支持直播RTMP流切换。 |
replayByVidAndPlayAuth | vid(String):视频ID,playauth(String):播放凭证 | 目前只支持H5播放器。暂不支持不同格式视频间的切换。暂不支持直播RTMP流切换。 可用于点播DRM流的切换,用法: |
replayByVidAndAuthInfo | 仅MPS用户时使用参数顺序为:vid(String)、accId(String)、accSecret(String)、stsToken(String)、authInfo(String)、domainRegion(String) | 目前只支持H5播放器。暂不支持不同格式视频间的之间切换。暂不支持直播rtmp流切换。 |
setPlayerSize | w(String),h(String) | 设置播放器大小,取值:
Chrome浏览器下Flash播放器分辨率不能小于397x297px。 |
setSpeed | speed(Number) | 手动设置播放的倍速,支持0.5~2倍速播放,倍速播放仅H5模式支持。移动端可能会失效,比如Android微信。倍速播放UI默认是开启的。 说明 关掉倍速的方法:
|
setSanpshotProperties | width(Number):宽度,height(Number):高度,rate(Number):截图质量 | 设置截图参数,高度、宽度单位为px,截图质量取值范围为0-1之间的数字,默认是1。视频截图详细说明请参见视频截图。 |
fullscreenService.requestFullScreen | 无 | 播放器全屏,仅H5支持。 |
fullscreenService.cancelFullScreen | 无 | 播放器退出全屏,iOS调用无效,仅H5支持。 |
fullscreenService.getIsFullScreen | 无 | 获取播放器全屏状态,仅H5支持。 |
getStatus | 无 | 获取播放器状态,取值:
|
setRotate | rotate(Number):旋转角度 | 参数为旋转角度,正数表示正时针旋转,负数表示逆时针旋转。示例:setRotate(90)。更多信息,请参见设置显示模式。 |
getRotate | 无 | 获取旋转角度。更多信息,请参见设置显示模式。 |
setImage | image(String):镜像类型 | 设置镜像,取值:
示例:setImage(‘horizon’)。更多信息,请参见设置显示模式。 |
dispose | 无 | 播放器销毁。 |
setCover | cover(String):封面地址 | 设置封面。 |
setProgressMarkers | markers(Array):打点数据集合 | 设置打点数据。 |
setPreviewTime | time(Number):试看时间 | 设置试看时间,单位:秒。更多信息,请参见试看。 |
getPreviewTime | 无 | 获取试看时间。 |
isPreview | 无 | 是否试看。 |
getCurrentPDT | 无 | HLS的视频格式支持实时获取ProgramDateTime。 |
replayByMediaAuth | mediaAuth(String) | 使用mediaAuth播放通用媒体管理服务的视频,用法: 说明 Web播放器SDK 2.10.0及以上版本支持。 |
setTraceId | traceId(String):公共埋点 | 传入公共埋点,用于日志跟踪,用法: 说明 Web播放器SDK 2.10.0及以上版本支持。 |
setTextTracks | textTracks(Array) | 设置一组WebVTT字幕,示例如下:
说明 Web播放器SDK 2.12.0及以上版本支持。 |
setLogo | logo(Array) | 设置自定义Logo图片。示例如下:
各字段的详细解释参考属性:logo。 |
setWatchTime | startTime(Number), endTime(Number) | 动态更新当前视频的 watchStartTime/watchEndTime |
setNextWatchTime | startTime(Number), endTime(Number) | 设置下一个视频的 watchStartTime/watchEndTime。 如果您要使用 loadByUrl/replayByVidAndPlayAuth 切换视频,且下一个视频的播放区间和当前视频不同,可以先调用 setNextWatchTime 设置下个视频的区间。 |
setStartEnd | start(Number), end(Number) | 动态更新当前视频的 start/end。 |
setNextStartEnd | start(Number), end(Number) | 设置下一个视频的 start/end。 如果您要使用 loadByUrl/replayByVidAndPlayAuth 切换视频,且下一个视频的截取区间和当前视频不同,可以先调用 setNextStartEnd 设置下个视频的区间。 |
takeSnapshot | 无 | 截图,返回的 base64 可以直接用 img.src 加载。 可以使用 setSanpshotProperties 设置截图质量,snapshotWatermark 设置截图水印。 注:部分移动端浏览器由于 video 被劫持(如 UC、QQ 浏览器),可能无法使用截图功能。 |
事件
播放器事件
名称 | 说明 |
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降级时触发。其中,参数 |
settingSelected | 当设置列表(倍速、清晰度、字幕等)被选中时触发。 说明 因开源倍速插件与播放器设置不同步,使用它需自定义代码并重新编译。您可定义事件监听,若需要使用播放器的
|
rtsTraceId | 当RTS拉流成功时触发,通过订阅该事件,可以获取到RTS TraceId。打印日志中的参数
|
autoplay | 自动播放成功或失败时会触发。回调参数 |
mutedAutoplay | 当 |
videoUnavailable | 当视频编码格式不支持导致视频播放发生黑屏时触发。例如在不支持H.265的浏览器上播放视频,会出现视频黑屏,只有声音播放,此时会触发该事件。 |
订阅事件
通过播放器实例的on方法订阅。示例如下:
var handleReady = function(e) { console.log(e); } player.on('ready',handleReady);
通过播放器实例的off方法取消订阅。示例如下:
player.off('ready',handleReady);