智汇云-企业数智化核心引擎

# WEB端HEVC、解密播放SDK文档

## WebPlayer（原名：QhwwPlayer） 简单介绍

WebPlayer（原名：QhwwPlayer） 是奇虎360视频云为解决HEVC(H265)在Web端播放、H265+H264视频解密([Vcodec 检测](https://github.com/huzunjie/Flv-Vcodec-Detection))，实现的一套基于WebAssembly、WebWorker、Websocket的模块化WEB端播放器。

> （1）WebPlayer 强依赖的浏览器API有：WebAssembly、Promise、WebWorker、fetch、ArrayBuffer、AudioContext、WebGL、Blob、Websocket等，建议使用者基于这些API结合自身业务覆盖浏览器类型决定是否启用本播放器。
> （2）IE、Edge浏览器中js异常，建议判断UA选择是否启用本播放器
> （3）QhwwPlayer于2021年2月25日更名为 WebPlayer，之前的js地址仍可使用
> （4）如果你是前端从业者，想从技术方向对这个播放器加深了解，可以[参考这里的文章介绍](http://blog.pyzy.net/post/qhww.html)。

**注意：本播放器基于WASM软解，帧率码率越高CPU消耗依赖也越高，如果非必要情况不建议使用。**

## WebPlayer 媒体播放能力

| 场景 | 协议 | 编码 | 解密 | 有音无画 | 有画无音 | 备注 |
| -------- | -------- | -------- | -------- | ------------ |
| 直播 | HTTP(S)-FLV| H264/H265 | 支持 | 支持 | 支持| 延迟追帧可通过delayTimeLimit 控制 |
| 点播 | HTTP(S)-MP4 | H264/H265 | 支持 | 支持 | 支持 | [服务端需要支持Content-Length的ResponseHeader读取](https://zyun.360.cn/developer/doc?did=kyqqmtzysb) |
| 直播 点播 | HTTP(S)-HLS| H264/H265 | 支持 | 支持 | 支持 | - |

> 注意：有画无音的情况，如果是流中没有音轨，则需要通过 renderType  明确设定不渲染声音。

## WebPlayer API 文档

### 示例 - DEMO

本示例实现中包含了播放器整体逻辑流程中各环节的数据生产、消费状况的实时统计报告，业务应用中除非有异常控制策略的开发需求，未必有相应数据展示的必要，请自行斟酌选用，以减少代码量、提高执行效率。

[示例DEMO请点击这里移步查阅](http://lab.pyzy.net/qhww/ "示例DEMO请点击这里移步查阅")。

各参数、API方法、事件的使用说明，请参考本文档后续相关内容。

### 获取及引用方式
如上文示例，在自己的业务页面中引入`https://s.ssl.qhimg.com/pkg/serviceplatform/WebPlayer_v1.3.0360.js`后，可以在window域下得到`WebPlayer`类，设置一个DOM元素为播放器的容器，便可以实例化播放器了:

>** 360集团内部开发者**使用，可以基于公司私有npm库安装引用： `qnpm install @q/QhwwPlayer -S`

```html
<div id="container"></div>
<script src="https://s.ssl.qhimg.com/pkg/serviceplatform/WebPlayer_v1.3.0360.js" type="text/javascript"></script>
<script type="text/javascript">
 window.qhwwPlayer = new window.WebPlayer({
 isLive: true,
 container: '#container',
 src: '要播放的媒体URL',
 });
</script>
```
### WebPlayer 类 - 静态属性

| 属性名 | 值类型  | 备注  |
| -------- | -------- | ------------ |
| isSupport | Boolean | 环境兼容判断；可用于在实例化之前判断当前浏览器环境是否兼容。 |

也就是可以通过 `WebPlayer.isSupport` 得到当前环境是否兼容该播放器的Boolean结果。

### WebPlayer 类 - 参数说明

前文我们提到可以`new WebPlayer(options)`得到一个播放器实例，那么其中的`options`具体可以设置哪些内容，可以参考下文：

| 属性名 | 值类型 | 是否必填 | 备注 |
| -------- | -------- | -------- | ------------ |
| autoplay | Boolean | 否 | 是否在实例化播放器后自动播放；默认flase。 注意：部分浏览器环境会限制自动播放媒体资源，除非用户手动触发， 为了保证兼容性，建议播放器实例在用户操作行为中进行。 |
| isLive | Boolean | 是 | 是否直播；直播点播内部逻辑不同，需要业务指定。 |
| isHLS | Boolean | 否 | 是否HLS资源；若不设置将自动按URL后缀是否`.m3u8`区分。 |
| src | String | 是 | 播放地址(相对或绝对路径，如果是跨域需要设置允许跨域头)。 |
| container | String | 是 | DOM Selector；要放置UI的DOM容器的Selector或DOM对象。 |
| key | String | 否 | 解密key，明文或加密后的字串（具体加密方式请联系360视频云工作人员获取）。 |
| keyForKey | String | 否 | 当key为加密字串时用于解密key的秘钥。 |
| keyType | Number | 否 | 解密方式：DK_TYPE_SHUIDI = 0, DK_TYPE_FFMPEG = 1, DK_TYPE_DISHI = 2。 |
| keyList | Array | 否 | 用于跟随帧内index使用动态解密的 KeyMap，格式如： [{ index: 0, key: "aaa"}]。 |
| logLevel | Number | 否 | 输出日志级别；可选 0 ~ 2，默认 0 - 不输出任何调试日志。 |
| volume | Number | 否 | 默认音量，默认1。 |
| maxVolume | Number | 否 | 用户可操作设置的最大音量，默认5。 |
| playbackRate | Number | 否 | 默认倍速，默认1。 |
| maxPlaybackRate | Number | 否 | 用户可操作设置的最大倍速，默认2。 |
| viewMode | String | 否 | 设置视窗宽高填充方式，默认contain contain-按实际比例 100% 展示。 cover-按高度 100% 展示。 fill-按宽高 100% 填充。 none-不设置样式（可以通过外部CSS控制）。 |
| decodeMode | Number | 否 | 解码模式： 0~3，值越大丢帧越狠，0保持原状；该值通常不需要手动设置，播放器内部有动态适配逻辑。 |
| minDecoderBufferSize | Number | 否 | 要启动解码器时必须准备就绪的数据量，默认 512 \* 1024； 数值越大播放越稳定，但等待时长也就更长。 **注意：在FLV直播的场景中，这里可以设置值为1来保证最佳体验； 播放器内部会自动判定FLV已加载的数据是否够解码使用。** |
| chunkSize | Number | 否 | 单次加载的buffer块大小(对于直播，相当于内存传递的最大块体积， 对于点播相当于单次下载的range长度)，默认 512 \* 1024。 |
| maxLoaderCacheSize | Number | 否 | 下载缓存可以使用的内存上限，默认 2 \* 1024 \* 1024。 |
| maxDecoderVCacheLength | Number | 否 | 解码数据队列中视频缓存最大帧数，默认 300。 |
| maxDecoderACacheLength | Number | 否 | 解码数据队列中音频缓存最大帧数，默认 500。 |
| decoderMemorySize | Number | 否 | 解码器内存上限设置，默认值 5 \* 1024 \* 1024。 |
| yuvRenderDelay | Number | 否 | 画面渲染延迟时长（毫秒），默认值 -20；可用于控制音画同步。 |
| pcmRenderDuration | Number | 否 | 音频渲染器最大缓冲时长（毫秒），即允许预先将最多多长时间的音频推入硬件队列， 这里时间过长会影响动态调整倍速的响应速度，默认值 1000。 *注意：这个值不可以小于waitingPcmDur。* |
| waitingPcmDur | Number | 否 | 当音频资源不足时，等待至少准备多少毫秒的数据再重启播放，默认值 500。 *注意：这个值不可以大于pcmRenderDuration。*|
| waitingYuvNum | Number | 否 | 无音频的媒体播放触发waiting后，至少等到准备几帧画面数据再恢复播放。默认值10。|
| waitingProbation | Number | 否 | 渲染数据不足时候，waiting缓期毫秒数， 如果这个时长内数据就绪，那么不触发waiting事件。默认值100。|
| *sei* | Number | 否 | 是否解码SEI数据；0 不需要；1需要，默认 0 |
| renderType | String | 否 | 渲染模式：yuv 仅渲染画面；pcm 仅渲染声音；all 全部渲染；默认 all |
| resample | Number | 否 | 是否需要对音频重新采样 - 0 不需要 1 需要，默认0。 部分浏览器不支持底采样率音频，要兼容需要开启该配置。 |
| delayTimeLimit | Number | 否 | **想要控制的直播延迟的最长毫秒值。** 即缓存区允许暂存的待渲染帧时长毫秒值； 当缓存时长大于该值则触发倍速播放来提高消费效率、降低延时。 注意：太小将增加缓冲概率。建议结合GOP时长设置。 **默认值0**；不传值或传值为0，则不启用动态倍速渲染追帧达成低延时模式。 |
| rtwPlaybackRate | Number | 否 | 大于1的浮点数（默认值2.23）； 参数 delayTimeLimit 开启追帧播放时，该参数用于控制追帧播放的最高倍速值。 |
| lowpassFrequencyVal | Number | 否 | 低通滤波频率值，可用于降噪；默认值 4500。 播放过程中频率大于该参数值的声波将被过滤掉。 |
| isRelay | Boolean | 否 | 是否为360摄像头私有协议websocket视频流。 默认不设置即可。 |
| relayKey | String | 否 | 360摄像头私有协议websocket视频流的解密秘钥。 当isRelay=true时生效，同时，key/keyList失效。 |
| CDNType | Int | 否 | CDN服务商类型，默认为0：普通。1-云帆，2-PPIO，3-星域，0-普通 |
| yfDebug | Boolean | 否 | 是否启用云帆SDK的Log。 默认不设置即可。也可以在localStorage中设置yfDebug=true开启Log日志 |
| seekTo | Boolean | 否 | M3U8从第N毫秒开播（定制接口，单位毫秒）。 默认不设置即可，或传null。 UI展现：不显示进度条、停止按钮、当前时间和总时长。 此功能适用于云存、卡录回放的伪直播模式 |
| localJsUrl | Object | 否 | 局域网环境使用，配置外部加载js地址。 子参数如下： ffmpeg--解密解码库 yfCloud--云帆SDK ppio--PPIO SDK xyvod--网心星域SDK decrypt--Relay私有协议的解密库|
| poster | String | 否 | 封面图。 |
| controls | Boolean | 否 | 是否显示控制条。 |
| showLoading | Boolean | 否 | 是否显示Loading动图。 |
| ableDblClick | Boolean | 否 | 是否启用双击全屏，默认true启用。 |
| showErrorMsg | Boolean | 否 | 是否在播放器内显示错误提示信息，默认false不显示。 |

`以上参数可以结合自己的应用场景和需求，进行适当配置，达到最佳体验效果。`

**比如在Flv直播中，要保证“首屏效率”及“低延时”可以参考如下设置：**

| 属性名 |  含义  |  建议值  | 备注  |
| -------- | --------  | -------- | ------------ |
| minDecoderBufferSize | 解码器启动前，必须加载到的数据量字节长度  | 1 |  设置1，将交给QHWW内部判断逻辑自动识别控制 | 
| waitingYuvNum  | 渲染帧不足时画面帧至少多少帧再重启播放   | 1 |  设置尽量小的值，有数据立即渲染，减少延迟 |
| waitingPcmDur  | 渲染帧不足时音频帧至少多少毫秒重启播放   | 50 |  设置尽量小的值，有数据立即渲染，减少延迟 |
| waitingProbation    | 渲染帧不足时缓刑多少毫秒再触发waiting   | 500 |  设置偏大一点的值，若数据及时恢复则直接播放，减少零碎的等待 |
| delayTimeLimit   | 直播中内存中允许存放最多多少毫秒待渲染帧   | 1000 |  可以结合GOP和希望兼容的网络抖动带来的延迟偏差设置 |

### WebPlayer 实例 - 属性说明

前文我们通过`const qhwwPlayer = new WebPlayer(options)`得到一个播放器实例后，通过 `qhwwPlayer.属性名`可以直接读写的播放器属性，可参考下面表格内容：

| 属性名 | 值类型 | 是否只读 | 备注 |
| -------- | -------- | -------- | ------------ |
| ready | Boolean | 是 | 播放器实例是否就绪；依赖异步载入的WebWorker\WASM等，所以实例化完毕，未必就是ready状态了。 |
| autoplay | Boolean | 是 | 是否在实例化播放器后自动播放。 |
| isLive | Boolean | 是 | 是否直播。 |
| isHLS | Boolean | 是 | 是否HLS。 |
| currentSrc | String | 是 | 格式化后的当前媒体路径字串。 |
| src | String | 否 | 当前媒体路径字串；写操作会同步影响currentSrc的值。 |
| key | String | 否 | 解密key，明文或按360视频云规则加密后的字串（具体加密方式需要联系360工作人员获取）。 |
| keyForKey | String | 否 | 当key为加密字串时用于解密key的秘钥。 |
| keyType | Number | 否 | 解密方式：DK_TYPE_SHUIDI = 0, DK_TYPE_FFMPEG = 1, DK_TYPE_DISHI = 2。 |
| keyList | Array | 否 | 用于跟随帧内index使用动态解密的 KeyMap，格式如： [{ index: 0, key: "aaa"}]。 |
| duration | Number | 是 | 媒体时长(秒)。 |
| currentTime | Number | 是 | 播放进度时间(秒)。 |
| paused | Boolean | 是 | 是否暂停状态。 |
| ended | Boolean | 是 | 是否播放结束状态。 |
| seeking | Boolean | 是 | 是否正在seek。 |
| error | Any | 是 | 异常信息。 |
| videoWidth | Number | 是 | 视频画面宽度。 |
| videoHeight | Number | 是 | 视频画面高度。 |
| poster | String | 否 | 封面图。 |
| controls | Boolean | 否 | 是否显示控制条。 |
| volume | Number | 否 | 音量。 |
| playbackRate | Number | 否 | 播放倍速。 |
| fullscreen | Boolean | 否 | 是否全屏模式。 |
| viewMode | String | 否 | 设置视窗宽高填充方式，默认contain contain-按实际比例 100% 展示。 cover-按高度 100% 展示。 fill-按宽高 100% 填充。 none-不设置样式（可以通过外部CSS控制）。 |
| waitingPcmDur | Number | 否 | 当音频资源不足时，等待至少准备多少毫秒的数据再重启播放，默认值 500。 *注意：这个值不可以大于pcmRenderDuration。*|
| waitingYuvNum | Number | 否 | 无音频的媒体播放触发waiting后，至少等到准备几帧画面数据再恢复播放。默认值10。|
| waitingProbation | Number | 否 | 渲染数据不足时候，waiting试用期毫秒数，如果这个时长内数据就绪，那么不触发waiting事件。默认值100。|
| delayTimeLimit | Number | 否 | **想要控制的直播延迟的最长毫秒值。** 即缓存区允许暂存的待渲染帧时长毫秒值；大于该值则自动触发动态倍速播放来提高缓存数据的消费效率。注意：太小将增加缓冲概率。 **动态倍速规则为：**缓存总时长大于delayTimeLimit设置值的3倍则启用`100%*rtwPlaybackRate`的速度追帧，缓存总时长等于delayTimeLimit则按正常1倍速度播放。 **默认值0**；不传值或传值为0，则不启用动态倍速渲染追帧达成低延时模式。 |
| rtwPlaybackRate | Number | 否 | 大于1的浮点数； 参数 delayTimeLimit 开启追帧播放时，该参数用于控制追帧播放的最高倍速值。 |
| lowpassFrequencyVal | Number | 否 | 低通滤波频率值，可用于降噪；默认值 4500。 播放过程中频率大于该参数值的声波将被过滤掉。 |
| isRelay | Boolean | 否 | 是否为360摄像头私有协议websocket视频流。 默认不设置即可。 |
| relayKey | String | 否 | 360摄像头私有协议websocket视频流的解密秘钥。 当isRelay=true时生效，同时，key/keyList失效。 |

### WebPlayer 实例 - 方法说明
前文我们通过`const qhwwPlayer = new WebPlayer(options)`得到一个播放器实例后，通过 `qhwwPlayer.方法名()`可以执行的操作方法，可参考下面表格内容：

| 方法名 | 返回值 | 接受参数  | 备注  |
| -------- | -------- | -------- | ------------ |
| play | Promise | 否 | 开始播放。 |
| pause | Promise | 否 | 暂停播放。 |
| stop | Promise | 否 | 停止播放；相对pause将重置掉内部状态。 |
| seek | Promise | time: Number 毫秒 | seek到指定的位置。 |
| destroy | Promise | 否 | 销毁播放器实例；释放资源。 |

### WebPlayer 实例 - 事件说明

前文我们通过`const qhwwPlayer = new WebPlayer(options)`得到一个播放器实例后，首先假设有个监听函数：

```
function eventHandler(event) { 
    const 返回值 = event.data;
    ...
} 
```
那么我们可以通过 `qhwwPlayer.on('eventType', eventHandler)`监听播放器事件。
可以通过`qhwwPlayer.off('eventType', eventHandler)`解除监听播放器事件。

另外，事件绑定时候有两个特殊的特性：

1、事件绑定支持`before`、`after`修饰符。
> 可以用类似`qhwwPlayer.on('eventType@before', eventHandler)`的方式绑定监听，来控制`eventHandler`是放在其他监听器前面还是后面执行；

2、事件绑定支持设置eventType为`*`，来做泛事件绑定。
> 这样绑定的监听函数在任意事件触发时都会执行，*所以必须要慎重使用*。

具体支持的事件类型可参考下面表格内容：

| 事件类型 | 返回值类型 | 返回值内容 | 备注 |
| -------- | -------- | -------- | ------------ |
| ready | Array | 各组件的安装状态 | 播放器就绪（实例化完毕后可能需要等待异步载入webWorker\WASM等）。 |
| canplay | Undefined | - | 检测资源有效性，是否可播放。 |
| canplaythrough | Undefined | - | 资源加载到终点。 |
| play | Undefined | - | 触发了播放操作。 |
| pause | Undefined | - | 触发了暂停操作。 |
| stop | Undefined | - | 触发了停止操作。 |
| ended | Undefined | - | 播放结束了。 |
| playing | Undefined | - | 在媒体开始播放时触发（可能发生在：初次播放、暂停后恢复、结束后重新开始、资源不足导致的卡顿）。 |
| waiting | Undefined | - | 触发播放后帧数据资源不足，需要等待时触发。 |
| error | Any | 错误信息 | 在发生错误时触发。 |
| loadstart | Object | {src, isLive} | 在媒体开始加载时触发。 |
| progress | Object | 单数据包体积&处于流中的range位置 | 告知媒体相关部分的下载进度时周期性地触发。 |
| loadedmetadata | Object | 媒体源的长度、音视频格式、时长等基本信息 | 媒体的元数据已经加载完毕；已经解码拿到基本媒体信息了。 |
| seeking | Nubmer | 要seek到的位置（秒） | 切换播放位置时触发。 |
| seeked | Nubmer | 接下来解码依赖的数据游标位置 | 切换播放位置完毕后触发。 |
| timeupdate | Object | 当前播放器的渲染进展，包含队列数据帧数、时长等状态信息 | 元素的currentTime属性表示的时间已经改变。 |
| durationchange | Number | 当前媒体时长值 | 媒体的时间长度发生了改变。 |
| ratechange | Number | 当前变化后的倍速值 | 倍速发生了变化。 |
| volumechange | Number | 当前变化后的音量值 | 音量值发生了变化。 |
| streamQueueChange | Object | 变化后的队列长度和数据体积 | 下载器数据队列发生变化。 |
| pcmQueueChange | Number | 变化后的队列长度 | 待渲染的音频帧数据队列发生变化。 |
| pcmQueueDurChange | Number | 变化后的队列时长毫秒值 | 待渲染的音频帧数据队列发生变化。 |
| yuvQueueChange | Number | 变化后的队列长度 | 待渲染的画面帧数据队列发生变化。 |
| yuvQueueDurChange | Number | 变化后的队列时长毫秒值 | 待渲染的画面帧数据队列发生变化。 |
| pcmFrameData | Object | 音频时间戳、时长、字节体积 | 解码器输出了一个音频帧数据；只要解码不停会不停的触发。 |
| yuvFrameData | Object | 视频时间戳、字节体积、估算帧率 | 解码器输出了一个画面帧数据；只要解码不停会不停的触发。 |
| seiUpdate | Object | SEI数据及时间戳 | 当实例化播放器时设置了sei参数为1，播放过程中会触发这个事件，并在事件返回数据中返回相应数据。 这里事件对象 evt.data.sei 拿到的将是SEI的内容buffer，可能需要根据规则约定截取或转字符串使用。 ArrayBuffer 转字符串可参考：`String.fromCharCode.apply(null, new Uint16Array(data.sei ))` 或 `new TextDecoder('utf8').decode(new Uint8Array( data.sei ))` |

## 写在后面

根据你的需求或应用场景不同，可能有未能达成满足、或实现并非最优的地方，欢迎随时反馈；具体可联系 gengxiandong(at)360.cn  。

网络加速

存储服务

视觉分析

内容审核

人脸与人体识别

OCR识别

图像技术

AI市场

基础组件

内容建站

视频服务

视频工具

视频应用

物联网平台

应用开发

运维效能

应用安全

研发效能

云计算

大数据

容器服务

AI开发平台

视频

物联网

数据上云

IoT设备

账号体系

智慧城市

电商视频解决方案

教育

全屋智能

医疗

智能制造

游戏

SDK管理

电话咨询：

热门产品

帮助文档

服务条款

关注或联系我们

请您联系我们

小安提醒您

1对1免费 咨询智汇云专属顾问

为您量身定制产品解决方案

1对1免费咨询智汇云专属顾问