npm package: @lnltch-players/aliyun
Description: web视频播放器SDK 阿里云版本，使用时请自行申请 获取播放器SDK License
Author: lnltch
Latest version: 1.2.0

# lnltch-players/aliyun

web视频播放器SDK 阿里云版本，使用时请自行申请 获取播放器SDK License

## 播放器介绍:
https://help.aliyun.com/zh/vod/developer-reference/online-trial-and-source-code-of-demos

## License申请地址
https://common-buy.aliyun.com/?commodityCode=ice_sdk_public_cn
由于此插件只需Web端的版本即可，所以仅需购买web基础版本即可（暂定为不包括H.265）

## v1.2.0更新内容
 - 删除了 aliplayercomponents.min.js，无需引用，请删除
 - 更改部分配置项


## 使用方法

#### 1. 安装
```bash
# with npm
npm install --save aliyun-aliplayer @lnltch-players/aliyun
# with yarn
yarn add aliyun-aliplayer @lnltch-players/aliyun
# with pnpm
pnpm add aliyun-aliplayer @lnltch-players/aliyun
```


#### 2. 使用

```javascript
import lnltchPlayer from "@lnltch-players/aliyun"
import '@lnltch-players/aliyun/dist/index.css'

//elementId元素ID 无需加#
const player = new lnltchPlayer('elementId',options,(player)=>{
    console.log('视频插件初始化完成')
})
// 调用示例，具体方法请参考API
player.play() //播放
player.pause() //暂停
player.seek(100)// 跳转到100s
//获取阿里云播放器初始化实例，可直接调用相关方法,直接使用原生插件的相关API
player.getAliPlayer() //
```

## 配置项（options)
|名称|类型|必填|默认值|说明|
| ---- | ---- | ---- | ---- | ---- |
|licenseDomain|String|是|""|阿里云播放器license配置的 Web 域名|
|licenseKey|String|是|""|阿里云播放器申请到的licenseKey|
|memoryVideo|String|是|""|视频唯一标识，建议为视频ID|
|**type**|String|否|“video”|如需播放MP3,AAC文件请使用audio|
|width|Number|否|element的宽度|播放器宽度|
|height|Number|否|element的高度|播放器高度|
|autoSize|Boolean|否|true|高度自适应|
|isLive|Boolean|否|false|播放内容是否为直播，直播时会禁止用户拖动进度条|
|poster|String|否|''|视频封面图url地址|
|cover|String|否|''|视频封面图url地址 cover > poster|
|loop|Boolean|否|false|播放器自动循环播放|
|preload|Boolean|否|false|播放器自动加载|
|muted|Boolean|否|false|设置是否静音播放。在浏览器禁止自动播放时可以通过配置此参数进行静音自动播放|
|autoplay|Boolean|否|false|播放器是否自动播放|
|autoplayPolicy|Object|否|{ fallbackToMute: false,falseshowUnmuteBtn: true }|播放器自适应静音自动播放策略。仅当autoplay设置为true时，本属性生效|
|useH5Prism|Boolean|否|true|指定使用H5播放器|
|playsinline|Boolean|否|true|H5是否内置播放，有些Android浏览器不起作用|
|bulletText|String|否|""|播放器水印文字|
|bulletStyle|Object|否|{ fontSize: '16px', color: '#00c1de' }|播放器水印演示|
|speedLevels|Array<{ key: number, text: string }>|否|[{ "key": 0.5, "text": "0.5x" },{ "key": 0.75, "text": "0.75x" },{ "key": 1, "text": "1x" },{ "key": 1.25, "text": "1.25x" },{ "key": 1.5, "text": "1.5x" },{ "key": 2, "text": "2x" }]|设置自定义倍速列表数组，key表示倍速数值，text表示UI文本，若不传则会使用默认列表|
|sources|Array<{ name: string, url: string }>,string|是|“”|播放地址|
|enableHotkeys|Boolean|否|true|启用快捷键，空格播放，esc退出全屏等|
|disableSeek|Boolean|否|false|禁用进度条|
|showRate|Boolean|否|true|显示倍速设置项|
|saveTime|Function|否||保存播放时间|
|saveTimeInterval|Number|否|30|每隔{}s调用一次saveTime|
|ratio|Number|否||设置播放器按照固定比例缩放。例如：已知视频长宽比为16:9，通过设置播放器参数为width: "100%", ratio: 16/9，如此播放器则可以和视频内容保持比例一致，并且可以随页面缩放而自动等比例缩放。|
|disablePip|Boolean|否|false|隐藏浏览器自带的画中画按钮。|
|textTracks|Array<{ kind: string, label: string, src: string, srclang: string, default?: boolean }>|否|[]|设置WebVTT外挂字幕|
|watchStartTime|Number|否||单独使用，代表开始播放的时间；和 watchEndTime 配合使用，开启区间播放功能，只能在开始和结束时间范围内播放和拖拽进度条。单位：秒|
|watchEndTime|Number|否||和 watchStartTime 配合使用，开启区间播放功能，只能在开始和结束时间范围内播放和拖拽进度条。如果参数值小于watchStartTime，则watchStartTime失效。单位：秒|
|start|Number|否||<strong>[慎用]</strong> 和 end 配合使用，截取视频的一部分作为一个独立的视频。如：原视频时长 60 秒，设置 start:10、end:30 后，视频显示时长为 20 秒，并从原视频的第 10 秒开始播放。|
|end|Number|否||<strong>[慎用]</strong> 和 start 配合使用，截取视频的一部分作为一个独立的视频。如：原视频时长 60 秒，设置 start:10、end:30 后，视频显示时长为 20 秒，并从原视频的第 10 秒开始播放。|
|isLiveUpdateWatchEndTime|Boolean|否|false|动态更新watchEndTime为当前时间后{isLiveUpdateWatchEndTimeIncrement}秒，禁止直接快进看完视频内容|
|isLiveUpdateWatchEndTimeIncrement|Number|否|10|仅isLiveUpdateWatchEndTime为true时生效|
|skinLayout|Array|否||[参考文档][api]|
|skinLayoutIgnore|Array|否||[参考文档][api]|
|**controlBarVisibility**|String|“hover”||控制面板的实现，取值：click：单击播放器区域。hover（默认值）：移动到播放器区域。always：控制面板一直显示。never：隐藏整个控制面板。|
|**showSkipButton**|Boolean|true||是否显示快进快退按钮，小屏幕自动隐藏|
|**skipStep**|Number|否|10|快进、快退时间，单位：秒|
|**showPlayNext**|Boolean|false||是否显示播放下一集按钮，当使用playlist时，此设置无效|
|**handlePlayNext**|Function|否||播放下一集按钮调用方法|
|**playlist**|Array<{id:string,name:string,poster:string,duration:number}>|否||**播放列表，使用请看下面的关于**|
|**getCDNSourceAndProgress**|Function|否||**地址和进度获取方法，使用请看下面的关于**|

#### 关于saveTime
```javascript
// getTime 已废弃，如果初始化传入时间，请使用watchStartTime，不传默认取播放器存放在本地（localstorage中存储的进度，如不存在，从头开始播放

saveTime:(memoryVideo,currentTime)=>{
    //memoryVideo,初始化插件时传入的视频唯一标志
    //currentTime,播放进度 秒
    //可保存到后台记录
    saveTimeApi({videoId:memoryVideo,currentTime:currentTime})
        .then(()=>{
            console.log("保存成功")
        }
    )
}
```

#### 关于showPlayNext，handlePlayNext，playlist，getCDNSourceAndProgress
当设置playlist后，播放器将自动判断是否显示下一集按钮，并自动生成相应的方法，无需设置
showPlayNext，handlePlayNext

getCDNSourceAndProgress 为异步获取播放器地址和进度的方式
```javascript

//getCDNSourceAndProgress
const getCDNSourceAndProgress = async (id: string) => {
  const sources = await getVideoCDN(id)
  const progress = await getVideoProgress(id)
  return new Promise((resolve) => {
    resolve({
      source: sources,
      progress: progress
    })
  })
}

const player = new lnltchPlayer('elementId',{
    ...
    playlist:[
        {
          id: "1",
          name: "第一集 播放器的安装和使用（1）",
          poster: "http://localhost/poster.jpg",
          duration: 700
        },
        {
          id: "2",
          name: "第二集 播放器的安装和使用（2）",
          poster: "http://localhost/poster.jpg",
          duration: 600
        }
    ],
    getCDNSourceAndProgress:getCDNSourceAndProgress
    ...
})
```


```javascript
// getTime 已废弃，如果初始化传入时间，请使用watchStartTime，不传默认取播放器存放在本地（localstorage中存储的进度，如不存在，从头开始播放

saveTime:(memoryVideo,currentTime)=>{
    //memoryVideo,初始化插件时传入的视频唯一标志
    //currentTime,播放进度 秒
    //可保存到后台记录
    saveTimeApi({videoId:memoryVideo,currentTime:currentTime})
        .then(()=>{
            console.log("保存成功")
        }
    )
}
```

## 事件
#### getAliPlayer
获取播放实例
```javascript
const player = new lnltchPlayer()
const aliyunPlayer = player.getAliPlayer() // 请在ready后执行
```
#### play
播放视频
```javascript
const player = new lnltchPlayer()
player.play()
```

#### pause
暂停视频
```javascript
const player = new lnltchPlayer()
player.pause() 
```
#### replay
重新播放视频
```javascript
const player = new lnltchPlayer()
player.replay()
```
#### dispose
销毁实例
```javascript
const player = new lnltchPlayer()
player.dispose()
```
#### seek
跳转到指定时刻进行播放
```javascript
const player = new lnltchPlayer()
player.seek(100)
```
#### getCurrentTime
获取当前的播放时刻，返回的时间单位：秒。
```javascript
const player = new lnltchPlayer()
const currentTime = player.getCurrentTime()
```
#### getDuration
获取视频总时长，返回的单位为秒，这个需要在视频加载完成以后才可以获取到，可以在play事件后获取。
```javascript
const player = new lnltchPlayer()
const duration = player.getDuration()
```
#### getPlayTime
获取用户的真实播放时长（不包含暂停时长，倍速情况下统计真实物理时间），返回值的单位是秒。
```javascript
const player = new lnltchPlayer()
const playTime = player.getPlayTime()
```

#### playPlaylist
播放播放列表中的视频，index从0开始
```javascript
const player = new lnltchPlayer()
player.playPlaylist(1)
```

#### on
切换视频。目前只支持同种格式（如MP4、HLS、FLV）之间切换，不同格式切换请销毁实例后重新创建。
```javascript
const player = new lnltchPlayer()
player.on('eventType',()=>{
    console.log("事件响应")
})

//eventType可用值范围
enum EventType {
  ready = 'ready',
  play = 'play',
  pause = 'pause',
  canplay = 'canplay',
  playing = 'playing',
  ended = 'ended',
  waiting = 'waiting',
  timeupdate = 'timeupdate',
  requestFullscreen = 'requestFullscreen',
  cancelFullscreen = 'cancelFullscreen',
  error = 'error',
  startSeek = 'startSeek',
  completeSeek = 'completeSeek',
  settingSelected = 'settingSelected',
  autoPlay = 'autoPlay',
  mutedAutoPlay = 'mutedAutoPlay',
  videoUnavailable = 'videoUnavailable',
}
```

#### getStatus
获取播放器状态。返回类型String
```javascript
const player = new lnltchPlayer()
const status = player.getStatus() 
```

## 其它方法
参考 https://help.aliyun.com/zh/vod/developer-reference/api-operations

## [License][license]
lnltch-players/aliyun is [licensed][license] under the MIT.

[license]: LICENSE

[api]: https://help.aliyun.com/zh/vod/developer-reference/api-operations