# ctyun-xstore-player-pc-js

**Repository Path**: ctyun-xstore/ctyun-xstore-player-pc-js

## Basic Information

- **Project Name**: ctyun-xstore-player-pc-js
- **Description**: 天翼云点播用于PC网页端的播放器代码，请按需取用。
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2019-03-11
- **Last Updated**: 2022-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web 视频播放器使用文档

## 文档版本信息

| 版本号 | 时间 | 修改内容 |
|---| ---|---|
| 1.0 | 2019.03.07 | 首次发布，实现了基本的功能 |
| 1.1 | 2021.03.05 | 支持 flv 播放 |

## 简介

天翼云媒体存储提供了点播的能力，你可以将上传的视频转码成为适合在互联网进行传播的格式，这些格式主要是 H264 编码的 MP4, HLS 和 FLV。你可以在用户控制台或者相关的后台 SDK 中取得这些视频的链接。由于这些视频是标准的视频，许多开源的浏览器均能进行播放。

为了更加便利得使用我们提供的点播功能，我们也提供基于 videojs 封装的视频播放器，以下是 Web 播放器的相关接口使用方法以及相关的接口。

请注意，本文档中的播放器使用的是传统的通过 `<script>` 标签引入的。通过 Node.js 模块化引入的我们后续推出。

## 阅读对象

本文档的读者，我们假设你已经具备一些基本的 HTML 以及 Javascript 基础。同时你已经在天翼云媒体存储服务中开通了点播服务，并且已经知道如何从该服务中取得视频的 URL。

## 初始化 Web 播放器

### Step 1: 在页面中引入文件

请将下载好的播放器文件解压缩，并且放在一个 Web 服务器中。然后在你的 HTML 文件中引入以下的 css 和 js 文件。

```html
<link href="//path/to/ctyunplayer.css" rel="stylesheet">
<script src="//path/to/ctyunplayer.js"></script>
```

### Step 2: 在页面中放置播放器容器

播放器使用的是 HTML 5 的 `<video>` 标签，请在你需要展示视频的地方引入以下容器，其中容器id，高宽都可以自定义。

`<source>` 中的 `src` 是播放视频的 url，可以在天翼云媒体存储的点播服务中取得。而`type` 字段则是有以下对应规则：

* 如果视频格式是 mp4，则该字段应为 `video/mp4`
* 如果视频格式为 hls，则该字段应为 `application/x-mpegURL`

```html
<video id="ctyunplayer-container" width="414" height="270" preload="true" playsinline>
    <source src="//path/to/ctyun/xstore/transcoded/video.hls" type="application/x-mpegURL">
</video>
```

### Step 3: 通过 JS 代码进行初始化

在页面加载完之后（通常会在 windows 的 load 事件中 或者在 HTML 的页面尾部的 `<script>` 标签中）执行以下 javascript 初始化代码

```javascript
var player = ctyunplayer("ctyunplayer-container");
player.play();
```

## Player 对象接口

在初始化了 player 之后，除了播放器原本的提供的按钮之外，你还可以通过以下的接口来实现相关的功能：

### 禁止使用右键

```javascript
player.disableContextMenu();
```

### 恢复使用右键

```javascript
player.enableContextMenu();
```

### 禁止使用画中画

*Chrome 以及同内核的浏览器适用。*

```javascript
player.disablePictureInPicture();
```

### 恢复使用画中画

*Chrome 以及同内核的浏览器适用。*

```javascript
player.enablePictureInPicture();
```

### 设置 URL

设置播放器播放的 url，该 url 的地址为视频的地址，支持 MP4 以及 HLS

```javascript
player.setUrl("//path/to/video");
```

### 设置 Poster

设置一个封面，该封面在视频未开始播放时显示，该封面应该是一个图片的 URL

```javascript
player.setPoster("//path/to/poster");
```

### 设置允许播放视频的时长

设置当前视频可以播放的时长，该功能通常用在试看的场景，在播放到视频的对应时长之后，播放器就不会继续播放后续视频了。参数的单位为`秒`

```javascript
player.setPlayableVideoDuration(300); // 最多播放到5分钟
```

### 设置片头广告

设置片头广告，片头广告播放时，播放器将不会显示控制栏，用户不能跳过广告直接观看视频。

```javascript
player.setStartAd("//path/to/start/ad/video");
```

### 设置片尾广告

设置片尾广告，在播放完视频之后继续播放该广告视频，用户不能暂停和跳过这个广告。

```javascript
player.setEndAd("//path/to/end/ad/video");
```

### 设置暂停广告

设置暂停广告，在视频暂停时会展示这个广告，该广告仅支持图片类型。

```javascript
player.setPauseAd("//path/to/pause/ad/picture");
```

### 加载视频内容

开始下载视频信息，如果你的 `<video>` 标签没有设置 `preload="true"`，可以通过这个方法开始来加载你的视频。

```javascript
player.load();
```

### 播放视频

播放视频，请注意，在你重新设置了 URL 之后，该方法会从片头广告开始播放而不是设置的视频。

```javascript
player.play();
```

### 暂停视频

调用该方法之后，如果设置了暂停广告，播放器会显示暂停广告。

```javascript
player.pause();
```

### 停止视频

停止播放视频，视频指针直接指导视频最后。

```javascript
player.stop();
```

### 从指定时间播放视频

让视频从指定时间开始播放。其中的参数单位为毫秒。

```javascript
player.seekTo(3000); // 从第3秒开始播放
```

### 获取视频的时长

获取当前播放视频的时长

```javascript
var duration = player.getDuration();
```

### 获取当前播放的位置

获取当前播放到视频的哪个时间，返回的单位为毫秒。

```javascript
var currentPosition = player.getCurrentPosition();
```

### 获取当前视频预加载的时间范围

返回一个对象，该对象描述了当前播放器预加载的视频的时间范围，该对象包含了 `from` 和 `to` 两个字段。

```javascript
var range = player.getBufferedRange();
var from = range.from;
var to = range.to;
```

### 获取当前加载的时间的结束时间

如果你的视频是从头开始加载的话，你可以调用以下方法，该方法直接返回最终的加载的最终时间点。

```javascript
var bufferedEnd = player.getBufferedEnd();
```

### 获取当前加载了视频的百分比

获取当前已经加载了视频的百分比，返回 0 ~ 1 之间的浮点数。

```javascript
var percentage = player.getBufferedPercentage();
```

### 设置音量

设置音量，从 0 ~ 1 之间的浮点数，精确到小数点后 2 位


```javascript
player.setVolume(0.30);
```

### 设置静音

设置为静音

```javascript
player.mute();
```

### 恢复音量

恢复到静音之前的音量，仅在当前为静音状态下有效。

```javascript
player.resumeVolume();
```

### 查询当前是否是静音状态

```javascript
var ismuted = player.isMuted();
```

### 进入全屏

```javascript
player.enterFullScreen();
```

### 退出全屏

```javascript
player.existFullScreen();
```

### 设置播放倍数

传入值为浮点数，可以为 0.5 或者 2.0 等均可。

```javascript
player.setSeed(4.0);
```

### 检查视频是否正在播放

```javascript
var isplaying = player.isPlaying();
```

### 检查是否暂停播放

```javascript
var ispaused = player.isPaused();
```

### 检查是否停止

```javacript
var isstop = player.isStop();
```

### 检查片头广告是否在播放中

```javascript
var isAdPlaying = player.isStartAdPlaying();
```

### 检查片尾广告是否在播放中

```javascript
var isEndAdPlaying = player.isEndAdPlaying();
```

### 暂停广告是否显示

```javascript
var isShown = player.isPausedAdShow();
```

### 设置水印

```javascript
player.setWatermark({
    /**
     * 水印文字
     */
    "text": "水印文字",
    /**
     * 水印样式，可选，可以不填写。
     */
    "className": "",
    /**
     * 水印内连样式
     */
    "style": {
        "top": "20px",
        "left": "3%",
        // "right": "",
        // "bottom": "",
        "fontSize": "26px",
        "color": "red"    
    }
});
```

### 设置文字水印

*不建议使用，请使用`setWatermark`方法代替！*

```javascript
player.setWatermarkText("watermark", {
    "top": "20px",
    "left": "3%",
    // "right": "",
    // "bottom": "",
    "fontSize": "26px",
    "color": "red"
});
```

### 设置弹幕

设置弹幕，弹幕的数据结构如下：

```javascript
var floatingTextArr = [{ 
    "value": "弹幕内容", // 弹幕内容
    "time": 1, // 显示弹幕的时间，单位为秒
    "color": 'red', // 弹幕的颜色
    "speed": 1, // 弹幕的速度
    "fontSize": 22, // 弹幕的字号
    "position_min": 0, // 弹幕浮动展示在屏幕的位置高度范围，小值，0~1，默认为 0
    "position_max": 1 // 弹幕浮动展示在屏幕的位置高度范围，大值, 0~1，默认为 1
}]; // 这是一个列表，可以有多条弹幕数据
player.setFloatingComments(floatingTextArr);
```

### 增加弹幕

为当前的弹幕列表增加弹幕内容。

```javascript
var floatingTextArr = [{ 
    "value": "弹幕内容", // 弹幕内容
    "time": 1, // 显示弹幕的时间，单位为秒
    "color": 'red', // 弹幕的颜色
    "speed": 1, // 弹幕的速度
    "fontSize": 22, // 弹幕的字号
    "position_min": 0, // 弹幕浮动展示在屏幕的位置高度范围，小值，0~1，默认为 0
    "position_max": 1 // 弹幕浮动展示在屏幕的位置高度范围，大值, 0~1，默认为 1
}]; // 这是一个列表，可以有多条弹幕数据
player.addFloatingComments(floatingTextArr);
```

### 停止播放片头广告

```javascript
player.stopStartAd();
```

### 停止播放片尾广告

```javascript
player.stopEndtAd();
```

### 隐藏当前的暂停广告

```javascript
player.hidePausedAd();
```

### 销毁当前播放器

```javascript
player.dispose();
```

## 事件

播放器在执行指定动作时会触发事件，通过以下事件注册机制可监听到相应动作时执行对应函数。请注意，这些监听事件并不不像 JS 自带的 `on("type", function())` 那样会不断叠加你的函数，也没有提供 `off` 接口，因此，你后续设置的函数会覆盖前面设置的。

### 在内容开始加载时

```javascript
player.onLoadStart(function(){

});
```

### 在开始播放时

开始播放开始时执行，该注册的方法会在播放片头广告之前执行。

```javascript
player.onPlay(function(){

});
```

### 在开始播放正片时

```javascript
player.onPlayMain(function(){

});
```

### 在暂停时

```javascript
player.onPause(function(){

});
```

### 在指定播放事件时

```javascript
player.onSeekedTo(function(){
    
});
```

### 在停止时

```javascript
player.onStop(function(){

});
```

### 在正片停止时

```javascript
player.onStopMain(function(){

});
```

### 在进入全屏时

```javascript
player.onEnterFullScreen(function(){

});
```

### 在退出全屏时

```javascript
player.onExistFullScreen(function(){

});
```

### 在错误时

```javascript
player.onError(function(){

});
```