WsPlayer

如何使用

使用之前，将播放器包放到前端项目的静态资源目录下，也就是webpack中的publicPath配置对应的目录

<script src="这里填播放器的包路径/index.js"></script>  // 一般通过打包工具进行配置
...
const { WsPlayer } = window;
const player = new WsPlayer(Configs)

Configs

| 字段 | 类型 | 描述 | 是否必填 | 默认值 | | --- | --- | --- | --- | --- | | url | string | 播放串地址 | true | | | mode | string | 播放模式，可选值：live、replay | | live | | MSE | boolean | 是否使用mse播放 | | true | | container | HTMLDivElement | 播放器容器 | true | | | mediaOptions 备注：mse模式可用 | mediaOptions | 媒体选项配置 | | | | events | events | 回调事件列表 | | | | watermarkConfig 备注：mse模式可用 | watermarkConfig | 水印配置 | | | | reconnectConfig 备注：mse模式可用 | reconnectConfig | 重连配置 | | | | download_split_size | number | 每次分片的文件大小，单位 MB | | 512 | | displayBufferProgress | boolean | 是否显示底部缓冲进度条,回放模式下有效 | | true | | displayErrorPrompt | boolean | 是否在播放器发生错误导致无法播放时显示提示遮罩层，实时和回放模式下有效 | | true | | displayLoading | boolean | 是否显示播放器的加载动画 | | true | | cancelAllDisplay | boolean | 取消所有的显示，一旦设置为true，传入的displayBufferProgress，displayErrorPrompt，displayLoading配置无效，播放器内部都设置为false | | false | | keepPlaying | boolean | 是否开启播放优化,在播放到无法播放的位置将自动跳到下一个可播放位置 | | true | | switchBackendOptimize | boolean | 页面切换后台优化，默认关闭，开启后，标签页离开前台后，会断开流连接 | | false | | leaveViewportOptimize | boolean | 播放元素离开视口优化，默认关闭，开启后，元素离开视口会暂停播放，断开流连接 | | false |

mediaOptions

初始媒体选项配置

| 字段 | 类型 | 描述 | 是否必填 | 默认值 | | --- | --- | --- | --- | --- | | muted | boolean | 是否静音 | false | true | | speed | number | 播放速度 | false | 1 | | autoplay | boolean | 是否自动播放 | false | true | | scale | number | 视频画面比例 可选值：0.5625(16:9) | 0.75(4:3) | 1(全屏) ，传入其他值默认按全屏显示 | false | 1 | | controls | boolean | 是否显示播放器原生控制器，mse有效 | false | false |

~~events~~

播放器提供的回调事件 备注：此配置只是为了适配之前的绑定事件方式，新的事件绑定方式参考： on()

| 事件 | 描述 | 传入参数 | | --- | --- | --- | | onTimeUpdate(time) | 播放器播放时间更新回调事件 | time：当前播放器的播放时间，单位 ms | | onConnectSuccess() | 播放器连接流媒体成功事件,http串和ws串都会触发 | | | onConnectClose | 流媒体连接关闭事件，http串不触发 | res: 关闭信息 | | onError | 播放器内部发生错误事件 | error: 错误信息 | | onPlay() | 播放器播放事件 | | | onPause() | 播放器暂停事件 | | | onEnded() | 播放器播放结束事件 | | | onDownloadStart() | 下载模式可用，下载开始回调事件 | | | onDownloadEnd() | 下载模式可用，下载完毕回调事件 | | | onDownloadStop() | 下载模式可用，下载停止回调事件，在未下载完毕时调用播放器的销毁方法，会触发此事件 | | | onDownloadSplit(size) | 下载模式可用，当下载的缓存数据大于内存限制时，文件会进行分片保存下载，每次进行分片保存时，都会触发此事件 | size：保存的分片文件大小，以字节为单位 | | onDownloadProgress | 下载模式可用，下载进度更新回调事件 | info: 下载进度信息对象```javascript info: { time: 0, // 当前已下载的时间，单位 ms progress: 0, // 当前的下载进度，范围：[0,1] }

 |
| onUnablePlay | 回放模式可用，当前时间无法播放时触发 | 
```javascript
{
  currentTime: 0,  // 当前时间，单位 ms
}

|

watermarkConfig

初始水印配置

| 字段 | 类型 | 描述 | 是否必填 | 默认值 | | --- | --- | --- | --- | --- | | text | string | 水印文本 | false | | | wrapText | string | 水印换行文本 | fasle | | | fontSize | string | 文字大小，接受css支持的font-size格式 | false | 40px | | rotate | number | 水印的旋转角度，单位：deg | false | 30 | | color | string | 水印字体颜色，接受css支持的color格式 | false | rgba(255,255,255,0.3) | | opacity | number | 水印内容的不透明度,有效值为0到1之间的数值 | false | 1 | | horizontalSpacing | number | 水印之间的水平间距，单位：px | false | 400 | | verticalSpacing | number | 水印之间的垂直间距，单位：px | false | 340 | | isCross | boolean | 相邻行的水印是否交错 | fasle | true | | offsetX | number | 水印整体x轴位置偏移量，单位：px | false | 0 | | offsetY | number | 水印整体y轴位置偏移量，单位：px | false | 0 | | useImage | boolean | 是否使用图片水印 | false | false | | imageUrl | string | 图片链接地址 | false | | | imageWidth | number | 指定图片的宽度，如果传递的数值小于等于0，则应用图片的原始宽度，单位: px | false | 0 | | imageHeight | number | 指定图片的高度，如果传递的数值小于等于0，则应用图片的原始高度，单位: px | false | 0 |

reconnectConfig

播放器会自主重连的情况：

1. 实时模式下ws连接关闭时，主动调用destroy方法导致的连接关闭不会发起重连
2. 回放模式下，由于seek操作导致的ws连接关闭
3. 下载模式下，未正常下载结束之前，服务器断开了ws连接 | 字段 | 类型 | 描述 | 是否必填 | 默认值 | | --- | --- | --- | --- | --- | | enabled | boolean | 是否开启重连机制 | false | true | | attempts | number | 重连最大次数 | fasle | 3 | | interval | number | 断开后进行重连的时间间隔，单位ms，不传递则断开时立即进行重连 | false | 0 |

使用示例

import  "../lib/wsPlayer/index.js"

const { WsPlayer } = window;
const player = new WsPlayer({
        url: 'ws://10.5.1.74:8080/media/v0.1/stream/25/1/0/live',
        mode: "live",
        MSE: true,
        container: document.getElementById("canvasContainer"),
        mediaOptions: {
          speed: 1,
          muted: true
        },
        watermarkConfig: {
          text: '默认水印',
          fontSize: 30,
          rotate: 30,
          color: '#fff',
          horizontalSpacing: 100,
          verticalSpacing: 100,
          isCross: true,
        }
      })
play.on("timeUpdate",(value: number) => {
      setDuration(value);
})
player.play()
...
// 不使用时记得销毁
  player.destroy()

WsPlayer API

API

| 方法名 | 描述 | 参数 | 返回值 | | --- | --- | --- | --- | | play() | 播放 | | | | pause() | 暂停 | | | | seek(time) | 跳转到指定的播放时间，单位ms，返回一个布尔值，true代表seek成功，false代表seek失败，备注：mse模式下，调用此方法后必须调用play()方法，才能进行进度的加载 | time: 跳转的时间，单位ms | 是否seek成功 | | setMuted(muted) | 设置静音状态 | muted：布尔值，true代表静音，false代表不静音，如果传入改参数，则按照参数值设置是否静音，不传则切换静音状态 | | | setScale(scale) | 设置画面比例 | scale：比例大小，可选值：0.5625(16:9) | 0.625(16:10) | 0.75(4:3) | defalut(全屏) ，传入其他值默认按全屏显示 | | | setVolume(volume) | 设置视频音量 | volume: 音量大小，支持[0, 1]的值 | | | setSpeed(speed) | 设置播放速度 | speed: 播放速度 | | | destroy() | 销毁播放器实例，当播放器实例不再使用时，一定要调用此方法，否则会内存泄漏 | | | | nextFrame() | 单帧前进 | | | | prevFrame() 备注：mse模式可用 | 单帧后退 | | | | digitalZoom( { xRadio , yRadio , wRadio , hRadio , baseOriginal }, container ) | 数字放大，放大视频画面 | xRadio：放大区域左上角的x坐标与视频容器宽度的比例 yRadio：放大区域左上角的y坐标与视频容器高度的比例 wRadio：放大区域的宽度与视频容器宽度的比例 hRadio：放大区域的高度与视频容器高度的比例 以上参数都为相对值，在[0 , 1]之间 baseOriginal: 表明此次操作是相对于原视频画面还是当前放大的画面，默认为true,代表相对于原视频画面 container: 指定显示的dom容器元素，如不传递则在原视频容器内部显示 | | | cancelDigitalZoom(container) | 取消指定的数字放大操作 | container：指定取消的数字放大dom容器元素，如不传递则取消原视频容器内的放大操作 | | | cancelDigitalZoomAll() | 取消所有已进行数字放大的操作 | | | | zoomHistoryBack(container) | 回退上一次数字放大操作，如果有，最多保存100条记录，超过则会清空之前的记录并重新记录 | container：指定取消的数字放大dom容器元素，如不传递则回退原视频容器内的放大操作 | | | screenShot(container) | 抓图 | container：如果传递，则抓取的图像内容是对应数字放大的图像 | base64格式的图像数据 | | setWaterMarkConfig(config) | 设置水印配置 | config：同waterMarkConfig | | | startRecord(filename，container) | 开始手动录制下载 注：建议同一时间内只进行一路视频的录制，特别是回放模式下以及开启数字放大下的录制 | filename：下载保存的文件名 container: 指定的录制目标对应的dom容器对象，与数字放大的container含义一整 | | | endRecord(container) | 结束指定的录制操作 | container: 指定的录制目标对应的dom容器对象，与数字放大的container含义一整 | | | openFishEyeExpand() | 鱼眼展开，默认展开模式是经纬视角展开 | | | | closeFishEyeExpand() | 关闭鱼眼展开 | | | | setFishEyeExpandMode(value) | 设置鱼眼展开模式 | value: 不同模式代表的值，number类型 0 // 360 + 主视角展开 1 //2x180 水平展开 2 //4x90 展开 3 //2x90垂直展开 4 //经纬视角展开 | | | endRecordAll() | 结束所有录制操作 | | | | reconnect() | 重新连接媒体流 | | 如果调用成功，会返回一个promise对象，代表重连的结果 | | releaseConnection | 释放当前的媒体流的网络连接 | | | | on(eventName,callback) | 绑定指定事件 | eventName：事件名称，参考eventName callback：回调函数 | | | off(eventName,callback) | 解绑指定事件对应的回调函数，如果传入的callback为空，则解绑该事件绑定的所有回调函数 | 同上 | | | getMediaTimeMs() | 获取当前视频播放的时间 | | 当前视频的播放时间，单位 ms | | getDuration() | 获取当前视频的总时长 | | 当前视频的总时长，单位 ms | | getPaused() | 获取当前视频是否暂停中，返回一个布尔值，true代表暂停，false代表播放 | |

| | getTimeInfo(time) 备注：mse模式可用 | 获取指定视频时间位置相关的信息，返回一个object，对应的属性值： canplay: 当前时间是否能够播放 inRange: 是否在视频时长范围内 nextStartTime: 下一个可播放的开始时间 | time：要获取的视频时间，单位 ms | ```json { canplay: true, inRange: true, nextStartTime: 0, }

 |
| jumpToNextBuffer()
备注：mse模式可用 | 跳转到下一个可播放时间的开头 |  |  |
| replaceHttpSrc(url)
备注：mse模式可用 | 替换http串并重新播放，替换后是否播放取决于autoplay配置 | `url`：要替换的http串 |  |

### 事件
#### eventName
使用`WsPlayer.on()`方法监听播放器某个事件时，支持的eventName值

| **eventName value** | **描述** | **callback传入参数** |
| --- | --- | --- |
| timeUpdate | 播放器播放时间更新回调事件 | `time`：当前播放器的播放时间，单位 ms |
| connectSuccess | 播放器连接流媒体成功事件，http串和ws串都会触发 |  |
| connectClose | 流媒体连接关闭事件，http串不触发 | `[res](#lBjIG)`: 关闭信息 |
| error | 播放器内部错误事件 | `[error](#cOSJA)`: 错误信息 |
| play | 播放器播放事件 |  |
| pause | 播放器暂停事件 |  |
| ended | 播放器播放结束事件 |  |
| insufficientBuffer | 播放器缓冲数据不足以播放事件，客户端带宽不足，实时码流掉帧，或是seek到没有录像的时间，都有可能会触发此事件 |  |
| downloadStart | 下载模式可用，下载开始回调事件 | 
 |
| downloadEnd | 下载模式可用，下载完毕回调事件 | 
 |
| downloadStop | 下载模式可用，下载停止回调事件，在未下载完毕时停止了下载，会触发此事件 | 
 |
| downloadSplit | 下载模式可用，当下载的缓存数据大于内存限制时，文件会进行分片保存下载，每次进行分片保存时，都会触发此事件 | `size`：保存的分片文件大小，以字节为单位 |
| downloadProgress | 下载模式可用，下载进度更新回调事件 | `info`: 下载进度信息对象```javascript
info: {
  time: 0,  // 当前已下载的时间，单位 ms
  progress: 0, // 当前的下载进度，范围：[0,1]
}

| | unablePlay | 当前时间无法播放时触发 |

{
  currentTime: 0,  // 当前时间，单位 ms
}

| | bitRateUpdate | 实时码率更新回调事件 | bitRate: 当前的实时码率，单位 kbps | | mediaInfo | 媒体信息回调 | mediaInfo: 当前码流的媒体信息 |

connectClose 事件

此事件回调一个关闭信息，结构如下

| 字段 | 类型 | 描述 | | --- | --- | --- | | code | number | 标志此次关闭的状态码 | | reason | string | 关闭原因 | | reconnect | boolean | 此次关闭播放器内部是否进行重连 |

code

| value | 描述 | | --- | --- | | 0 | 实时模式下连接关闭 | | 1 | 回放模式下连接关闭 | | 2 | 由于seek操作导致的连接关闭 | | 3 | 下载模式下连接关闭 | | -1 | 连接websocket发生错误导致的关闭 | | -1000 | 其他错误导致的关闭 |

error 事件

此事件回调一个错误信息，结构如下

| 字段 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 标志该错误的状态码 | | reason | | 错误原因 | | info | Object | 该错误包含的额外信息数据 | | fatal | boolean | 这个错误是否导致播放器无法继续工作 |

error_code

| value | 描述 | | --- | --- | | -1 | 连接websocket发生错误，或http加载错误 | | -2 | 浏览器不支持当前码流对应的编码格式，通过info.codecString可以拿到不支持的编码字符串 | | -3 | 传入的url地址格式不正确 | | -4 | 传入的container有误 | | -5 | 浏览器不支持Media Source Extensions API | | -6 | 取消文件保存 | | -7 | 回放模式下，seek时间超出视频时长 | | -1000 | 未知的错误 |

StreamDownloader

如何使用

<script src="这里填播放器的包路径/index.js"></script>

...
const { StreamDownloader } = window;
const downloader = new StreamDownloader(Configs)

Configs

| 字段 | 类型 | 描述 | 是否必填 | 默认值 | | --- | --- | --- | --- | --- | | url | string | 下载的回放串地址 | true | | | filename | string | 下载模式保存文件的名称 | false | 当前系统的时间戳字符串 | | download_split_size | number | 使用内存下载方式时，每次分片的文件大小，单位 MB | false | 512 | | encryptPassword | number|string | 保存的文件是否加密，如果传入值有效，则会以压缩格式保存 | false | |

API

| 方法名 | 描述 | 参数 | 返回值 | | --- | --- | --- | --- | | start() | 开始下载 | | | | stop() | 停止下载 | | | | on(eventName,callback) | 绑定指定事件 | eventName：事件名称，参考eventName callback：回调函数 | | | off(eventName,callback) | 解绑指定事件对应的回调函数，如果传入的callback为空，则解绑该事件绑定的所有回调函数 | 同上 | |

事件

eventName

使用StreamDownloader.on()方法监听播放器某个事件时，支持的eventName值

| eventName value | 描述 | callback传入参数 | | --- | --- | --- | | downloadStart | 下载开始回调事件 | | | downloadEnd | 下载完毕回调事件 | | | downloadStop | 下载停止回调事件，在未下载完毕时停止了下载，会触发此事件 | | | downloadSplit | 当下载的缓存数据大于内存限制时，文件会进行分片保存下载，每次进行分片保存时，都会触发此事件 | size：保存的分片文件大小，以字节为单位 | | downloadProgress | 下载进度更新回调事件 | info: 下载进度信息对象```javascript info: { time: 0, // 当前已下载的时间，单位 ms progress: 0, // 当前的下载进度，范围：[0,1] }

 |
| connectSuccess | 连接成功事件 |  |
| connectClose | 连接关闭事件 | [res](#lBjIG): 关闭信息 |
| error | 错误事件 | [error](#cOSJA): 错误信息 |