接口说明

名称

类型

说明

id

String

播放器外层容器的DOM元素ID。

source

String

使用URL播放方式时，通过source属性来指定视频播放地址URL。

vid

String

媒体转码服务的媒体ID。

playauth

String

播放凭证，获取播放凭证请参见获取音视频播放凭证。

playConfig

JSON

使用Vid方式（VidAuth和VidSts方式）播放时的自定义设置字段，会透传给点播接口。支持设置的自定义字段及参数说明，请参见媒体播放自定义设置 PlayConfig。取值示例：

{"PlayDomain":"vod.test_domain","PreviewTime":"20","MtsHlsUriToken":"yqCD7******oVjslp5Q"}

authTimeout

Number

通过Vid方式（VidAuth和VidSts方式）播放时，获取到的视频播放URL的有效时长。单位：秒，默认取值：7200。

请确保该时长大于视频的实际时长，防止播放地址在播放完成前过期。

height

String

播放器高度，取值：

• 100%

• 100px

width

String

播放器宽度，取值：

• 100%

• 100px

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属性会失效。取值：

• true：开启自动播放。

• false（默认值）：关闭自动播放。

autoplayPolicy

Object

播放器自适应静音自动播放策略。仅当autoplay设置为true时，本属性生效。配置示例如下：

autoplayPolicy: {
  fallbackToMute: true, // 有声自动播放失败后，是否降级为静音自动播放，默认为false
  showUnmuteBtn: true, // 静音自动播放时，是否居中显示静音大按钮，默认为true
}

rePlay

Boolean

播放器自动循环播放。

useH5Prism

Boolean

指定使用H5播放器。

useFlashPrism

Boolean

指定使用Flash播放器。

playsinline

Boolean

H5是否内置播放，有些Android浏览器不起作用。

skinRes

Url

皮肤图片，不建议随意修改该字段，如要修改，请参见设置播放器皮肤。

skinLayout

Array | Boolean

功能组件布局配置，不传该字段使用默认布局。取值：false表示隐藏所有功能组件。更多信息，请参见配置skinLayout属性。

skinLayoutIgnore

Array

需要隐藏的UI组件。组件名称请参见点播组件参数说明。配置示例如下：

skinLayoutIgnore: [
  'bigPlayButton', // 隐藏大播放按钮
  'controlBar.fullScreenButton' // 隐藏控制条上的全屏按钮（通过点运算符进行子组件选择）
]

controlBarVisibility

String

控制面板的实现，取值：

• click：单击播放器区域。

• hover（默认值）：移动到播放器区域。

• always：控制面板一直显示。

• never：隐藏整个控制面板。

showBarTime

Number

控制栏自动隐藏时间，单位：毫秒。

extraInfo

String

JSON串，用于定制性的接口参数，目前仅Flash支持，取值：

• fullTitle：测试页面，全屏时显示视频标题。

• m3u8BufferLength：播放HLS文件时加载缓存，ts文件长度，单位为秒。

enableSystemMenu

Boolean

是否允许系统右键菜单显示，默认为false。

format

String

指定播放地址格式，取值：

• 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：不显示按钮。

disableSeek

Boolean

禁用进度条的Seek，取值：

• true：禁用。

• false（默认值）：不禁用。

encryptType

Number

设置是否播放阿里云视频加密（私有加密）视频，默认值为0，取值：

• 0：播放不加密视频。

• 1：播放私有加密视频。

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倍速。

hlsOption.maxLiveSyncPlaybackRate

Number

HLS直播模式下，设置直播追帧时的播放速度，默认为1，表示不追帧。

• 配置示例：

  hlsOption: {
    maxLiveSyncPlaybackRate: 1.5, // 设置追帧的倍速
    liveSyncDurationCount: 3 // 设置触发追帧的延迟切片个数
  }

• 示例含义：当直播延迟大于3个切片的时长时，播放器会以1.5倍速播放追赶进度到3个切片（考虑到播放器需要一定的缓冲以应对网络变化，请谨慎修改liveSyncDurationCount的值，该值太小可能会引发卡顿）。

flvFrameChasing

Boolean

FLV直播模式下，是否开启追帧，取值：

• true：开启追帧。

• false：不开启追帧。

默认值为false。

keyShortCuts

Boolean

是否启用快捷键，取值：

• true：开启快捷键。

• false：不开启快捷键。

默认值为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****

traceId

String

traceId为您自有的用户唯一标识符，将traceId传入公共埋点，便于跟踪上报日志。正常情况下，Web播放器SDK已默认开启日志上报，传递traceId，可便于您标识用户身份；如果不传递，Web播放器SDK会默认生成一个uuid（播放器SDK生成的唯一标识符）并存储在浏览器缓存中。

textTracks

Array

设置WebVTT外挂字幕，示例如下：

textTracks: [
  { kind: 'subtitles', label: '中文', src: '字幕地址', srclang: 'zh-CN', default: true },
	{ kind: 'subtitles', label: '英文（美国）', src: '字幕地址', srclang: 'en-US' }
],

ratio

Number

设置播放器按照固定比例缩放。例如：已知视频长宽比为16:9，通过设置播放器参数为width: "100%", ratio: 16/9，如此播放器则可以和视频内容保持比例一致，并且可以随页面缩放而自动等比例缩放。

extLanguageTexts

Object

播放器SDK内置了一套中英文界面文案，您可以通过本属性自定义部分界面的显示文案。以修改分辨率的显示文案为例：HD默认显示为高清，可以通过以下方式修改HD显示为1080p。

extLanguageTexts: {
    'zh-cn': {
      'HD': "1080p"
    }
}

speedLevels

Array

设置自定义倍速列表数组，key表示倍速数值，text表示UI文本，若不传则会使用默认列表。参数取值示例如下：

speedLevels: [
  {"key": 0.25, "text": "0.25"},
  {"key": 0.5, "text": "0.5"},
  {"key": 1, "text": "原速"},
  {"key": 1.25, "text": "1.25"},
  {"key": 1.5, "text": "1.5"},
  {"key": 2,"text": "2"}
]

logo

Array

设置自定义Logo图片。示例如下：

    logo: [{
      width: 30,
      position: 'bottom-right',
      origin: 'content',
      src: 'a.png'
    },
    {
      width: 20,
      position: 'bottom-right',
      offsetY: -20,
      origin: 'content',
      src: 'b.png'
    }]

字段解释如下：

• src：Logo图片地址。

• origin：定位参照物。取值如下：

  • box：播放器

  • content：视频内容

• width/height：Logo的宽高，单位是百分比（根据origin计算），如果只指定一边，则另一边按图片比例缩放。

• position：Logo的相对位置，相对origin定位。取值如下：

  • top-left：左上

  • top-right：右上

  • bottom-left：左下

  • bottom-right：右下

• offsetX/offsetY：相对于position的偏移，单位：百分比%（根据origin计算）。

license

Object

如需使用播放质量监控、单点追查、播放H.265/H.266编码协议视频流等增值功能，请先填写Web播放器SDK增值服务申请表单申请License授权后，再按如下方式接入License：

// domian为申请License授权时所填写的域名
// Key为License密钥
license: {
    domain: "example.com",
    key: "example-key"
  }

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 秒开始播放。

dbClickFullscreen

Boolean

是否开启双击全屏，默认在 PC 端开启。

名称

说明

ready

播放器视频初始化按钮渲染完毕。播放器UI初始设置需要此事件后触发，以避免UI被初始化所覆盖。

play

视频由暂停恢复为播放时触发。

pause

视频暂停时触发。

canplay

能够开始播放音频和视频时发生，会多次触发，仅限H5播放器。

playing

播放中，会触发多次。

ended

当前视频播放完毕时触发。

liveStreamStop

直播流中断时触发。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。打印日志中的参数data.paramData中的参数字段traceId为拉流的TraceId，source为当前RTS流的播放地址。

player.on('rtsTraceId', function(data) {
  console.log('[EVENT]rtsTraceId', data.paramData);
})

autoplay

自动播放成功或失败时会触发。回调参数event.paramData为true时表示自动播放成功；为false时表示自动播放失败，此时需要用户交互才能播放。

mutedAutoplay

当autoplayPolicy.fallbackToMute设置为true时，静音自动播放成功时触发。

videoUnavailable

当视频编码格式不支持导致视频播放发生黑屏时触发。例如在不支持H.265的浏览器上播放视频，会出现视频黑屏，只有声音播放，此时会触发该事件。