必须包含属性 kwai-player-watermark #### 原生库 示例 ```html ``` #### Vue 示例 ```js

``` #### React 示例 ```js

``` ### ControlsPlugin 实现了默认控制条 UI 交互 参数： ``` plugins: { ControlsPlugin: { danmakuControls?: DanmakuControlsPos, // 弹幕插件在非全屏时显示的位置 / 依赖弹幕插件 danmakuControlsFull?: DanmakuControlsPos, // 弹幕插件在全屏时的显示位置 / 依赖弹幕插件 showBottomButtonBar?: boolean, // 是否按时下方播放按钮 showProgress?: boolean, // 是否显示进度条 showTime?: boolean, // 是否显示播放时间 showWindowFullScreen?: boolean, // 是否显示窗口全屏按钮 seekMode?: 'onDragChange' | 'onDragEnd', // seek 模式，拖动进度条实时seek/拖动进度条完成时seek showProgressTime?: boolean, // 是否在进度条上显示时间，默认不显示 showPlaybackRate?: boolean, // 是否展示倍速功能 showContextMenu?: boolean, // 是否展示右键菜单功能 stateChange?: (data: StateChangeData) => void, // UI状态回调 } } type StateChangeData = { type: 'controlsVisibility', value: boolean }; // 控制条显示隐藏状态变化 ``` ### PlayInfoPlugin 提供播放信息面板 ### PrefetchPlugin 提供播放地址链接预热功能，用于不自动播放且不预加载情况下的起播速度 ### PreviewPlugin 增加控制条上的预览画面，需要指定预览图地址；需要配合streamlake服务使用 ```ts import { KwaiPlayer } from '@ks-video/kwai-player-web; const player = new KwaiPlayer('#player-1' { src: 'xxx', previewUrl: 'xxxx', // 设置预览图url }); ``` ### HotkeyPlugin 可利用键盘快进快退、暂停播放、音量高低调节 | 键位 | 单击 | 长按 | | ---------- | ------------------------------------------------------------- | ----------------------------------- | | ArrowRight | 前进 10s | 3 倍速 | | ArrowLeft | 回退进度的两百分之 1 秒(若大于 10s 则为 10s、小于 5s 则为 5s) | 每 100ms 出发一次回退（时长如单击） | | ArrowUp | 增加音量的 5% | 每 100ms 增加音量的 5% | | ArrowDown | 减少音量的 5% | 每 100ms 减少音量的 5% | | Space | 播放/暂停 | -- | ### RotatePlugin 画面旋转插件 参数： ``` // 配置类型 type OptionType = 'mirror' | 'counterClockwise' | 'clockwise'; type OptionValue = 'pc' | 'mobile' | 'always'; type OptionShow = OptionValue | Record; type RotatePluginOption = { showInPlayBar?: OptionShow, showInContextMenu?: OptionShow, svgRaw?: { mirror?: string, counterClockwise?: string, clockwise?: string, } } // 配置传入 plugins: { AlphaVideoPlugin: RotatePluginOption, } ``` ### AlphaVideoPlugin 透明视频插件，支持透明视频的播放 参数： ``` plugins: { AlphaVideoPlugin: { active?: boolean, // 是否启动。默认：undefined，自动识别 type?: undefined | "2:1" | "1:1", // 透明视频类型。默认：undefined，自动识别 } } ``` #### API ##### active set: 是否启动。默认：undefined，自动识别 #### type set: 透明视频类型。默认：undefined，自动识别 可选值：undefined | "2:1" | "1:1" ## 自定义插件 可以自定义插件 + 插件名唯一，注册同名插件仅最后一次注册生效，故可采用这种方法替换已有插件。 + 例如：自定义名称为ControlsPlugin的插件，注册在完整包中，会替换默认的播控UI + 自定义插件实现需要继承PluginModule或其他基础插件的抽象类 + 自定义插件需要在实例化之前完成注册 + 注册方法仅需要执行一次 + 注销方法和销毁播放器无关，正常情况不需要调用 播放组件中的DOM分为以下三层，添加子容器需要指定一个层级，从下向上依次为VIDEO/VIDEO_INTERACTIVE/DEFAULT ### 利用钩子 - 挂载前 ```ts beforeInstall(player: IKwaiPlayer, options?: any): void ``` 数据准备完成，还未开始实例化播放内核前触发 - 挂载后 ```ts afterInstall(player: IKwaiPlayer, options?: any): void ``` 实例化播放内核后触发 - 销毁前 ```ts beforeUninstall(player: IKwaiPlayer): void ``` 销毁播放内核前触发 - 销毁后 ```ts afterUninstall(player: IKwaiPlayer): void ``` 销毁播放内核后触发 ### 注册销毁插件 实现一个插件后需要在**KwaiPlayer**对象上注册 1. 注册插件方法只用调用一次 2. 销毁播放器不需要调用注销 ```ts KwaiPlayer.register(WaterMarkPlugin); //注册 KwaiPlayer.deregister(WaterMarkPlugin); //注销 ``` ### 插件实现示例 ```ts import { IKwaiPlayer, KwaiPlayerEvent, PluginModule } from '@ks-video/kwai-player-web'; // 新插件替换已有的logger插件 // export default class ExamplePlugin extends LoggerPluginModule { // 新插件与已有插件共存 export default class ExamplePlugin extends PluginModule { private _player: IKwaiPlayer | undefined; /** * 播放器实例化前钩子 * @param player 播放器实例 * @param options 实例化播放器时指定的当前插件的参数 */ public beforeInstall(player: IKwaiPlayer, options?: any | undefined): void { this._player = player; console.log('beforeInstall', options); // 播放事件处理 this._player.on(KwaiPlayerEvent.REPORT, this._onReport); // 切换视频事件处理 this._player.on(KwaiPlayerEvent.ATTRIBUTE_CHANGE_SRC, this._onSrcChange); } /** * 播放器实例化后钩子 * @param player 播放器实例 * @param options 实例化播放器时指定的当前插件的参数 */ public afterInstall(_player: IKwaiPlayer, _options?: any): void { console.log('afterInstall'); } /** * 播放器销毁前钩子 * @param player 播放器实例 */ public beforeUninstall(_player: IKwaiPlayer): void { console.log('beforeUninstall'); } /** * 播放器销毁后钩子 * @param player 播放器实例 */ public afterUninstall(_player: IKwaiPlayer): void { console.log('afterUninstall'); this._player?.off(KwaiPlayerEvent.REPORT, this._onReport); this._player?.off(KwaiPlayerEvent.ATTRIBUTE_CHANGE_SRC, this._onSrcChange); } /** * 插件id，获取插件，传入参数等操作的标识 * 同名插件只会同时存在一个 */ public getLabel(): string { // LoggerPluginLabel return 'ExamplePlugin'; } private _onReport = (e: { type: string, value: any }): void => { } private _onSrcChange = (): void => { } } ``` # API 播放组件提供原生js方式接入，React组件方式接入，Vue2/Vue3组件方式接入。原生js、React、Vue的API和事件名称有差异，需要注意。 播放器的属性、API及事件参考了HTMLVideoElement的实现。 需要参考的文档： 1. [HTMLVideoElement](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLVideoElement) 2. [HTMLMediaElement](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLMediaElement) ## 原生库属性 **以下属性同HTMLVideoElement** | 属性 | 定义 | 备注 | | :---------------------- | :------------------- | ---- | | crossOrigin | 跨域设置 | | | preload | 当前视频预加载设置 | | | defaultPlaybackRate | 默认播放速度 | | | playbackRate | 播放速度 | | | autoplay | 自动播放 | | | loop | 循环播放开关 | | | controls | 播放控件显示开关 | | | volume | 音量 | | | muted | 静音 | | | defaultMuted | 默认静音 | | | poster | 封面图 | | | disablePictureInPicture | 画中画是否可用开关 | | | playsinline | 手机H5小窗播放开关 | | | buffered | 缓存范围 | 只读 | | duration | 视频时长 | 只读 | | ended | 是否播放结束 | 只读 | | error | 错误信息 | 只读 | | played | 已播放范围 | 只读 | | readyState | 视频状态 | 只读 | | seekable | 可seek范围 | 只读 | | seeking | 是否处于seek状态中 | 只读 | | networkState | 当前视频加载网络状态 | 只读 | | paused | 是否暂停状态 | 只读 | | videoWidth | 视频源宽 | 只读 | | videoHeight | 视频源高 | 只读 | **暂未实现的属性** + audioTracks + currentSrc 只读 + initialTime 只读 + mediaGroup + mediaKeys + moz* + sinkId + textTracks + videoTracks + width + height > width/height暂不支持，需要使用样式控制 **与HTMLVideoElement有差异的属性** ### src 可传入视频URL、manifest JSON、File。可传入空字符串进入停止状态 ### controls 依赖插件: ControlsPlugin 定义同HTMLVideoElement，用于控制播放控件，可选值有不同 + controls可选值说明 + false：关闭播放控件，如果需要自定义播放控件请使用该选项 + true：使用默认播放控件 + 'default'：使用默认播放控件 ### showInfoPanel 依赖插件: PlayInfoPlugin get: 返回是否显示信息面板 set: 设置是否显示信息面板 ### productName 依赖插件: LoggerPlugin 业务名，用于从上报数据中区分业务 ### bizData 依赖插件: LoggerPlugin 业务数据，会加入到上报中 ```ts type BizData = { resourceId?: string | number, // 资源ID userId?: string | number, // 用户id photoId?: string, // yoda上报 activityTag?: string, // yoda上报 // eslint-disable-next-line @typescript-eslint/no-explicit-any request?: { header: Record }, secretId?: string, // 不会加入上报 secretKey?: string, // 不会加入上报 isVip?: boolean | number, } & Record; ``` ### disableHotkey 依赖插件: HotkeyPlugin get: 返回当前热键功能是否开启 set: 设置当前热键功能是否开启 ### disableDownload 依赖插件: ControlsPlugin controls===‘origin’时是否使下载功能可用 ### disableAdaptive 自适应码率是否可用，默认：true > 以上已实现的可写属性均可在构造函数中传入 ### currentLevel get: 返回当前正在加载的流index set: 立即切换至指定的流index 设置为-1，切换至自动码率 ### nextLevel get: 返回下一个加载的流index set: 下一个切换的视频流index 设置为-1，切换至自动码率 ### audioTrack get: 返回当前的音频轨index set: 立即切换至指定的音频轨index ### totalVideoFrames get: 返回当前播视频总帧数 ### currentVideoFrame get: 返回当前播放位置对应的帧index set: seek至指定帧 ### showProgress get: 设置是否显示进度条 set: 获取当前是否显示进度条 > totalVideoFrames>0时可用 ## API **以下API同HTMLVideoElement** + load() + play() + pause() + requestPictureInPicture(); **以下API暂未实现** + ms* + canPlayType() + captureStream() + fastSeek() + setMediaKeys() + setSinkId() **与HTMLVideoElement有差异的API** ### constructor(id: string, data?: Partial) 构造函数 参数说明： + id: 播放器容器id + data: 播放器参数，与HTMLVideoElement相同的API定义也可同data传入 ```js type KwaiPlayerData = { src: any; crossOrigin?: string; preload?: string; defaultPlaybackRate?: number; playbackRate?: number; autoplay?: boolean; loop?: boolean; controls?: boolean | string; volume?: number; muted?: boolean; defaultMuted?: boolean; poster?: string; disablePictureInPicture?: boolean; disableDownload?: boolean; disableAdaptive?: boolean; playsinline?: boolean; plugins: { [key in string]: object }; // 参见插件说明 }; ``` ### destroy(): void 销毁 ### isFullscreen(): boolean; 是否全屏 ### requestFullscreen: (type?: "window" | "system" | undefined) => void; 请求全屏 ```type?: "window" | "system"``` 窗口全屏 | 系统全屏 ### exitFullscreen: (type?: "window" | "system" | undefined) => void; 退出全屏 ```type?: "window" | "system" | undefined``` 窗口全屏 | 系统全屏 | 自动 ### requestPictureInPicture(): Promise | undefined; 进入画中画 ### screenshot(): Promise 截图 ### refresh(): void; 刷新，重新加载视频 ### getPluginInstance(label: string | pluginLabel): PluginMap[pluginLabel] | undefined; 获取插件实例 *** > 以下API用于自定义插件 ### KwaiPlayer.register(plugin: typeof PluginModule, method: RegisterMethod = 'append'); 注册插件 使用场景： + 替换现有包中的组件，例如更换UI，使用其他播控UI插件 + 自定义插件，更多查看自定义插件说明 参数： plugin: 插件 method: 添加位置，放在最前或者最后，prepend/append，插件注册的顺序会影响到钩子调用的顺序 更多查看插件自定义组件部分内容 ### KwaiPlayer.deregister(plugin: typeof PluginModule | string); 注销插件 更多查看插件自定义组件说明 ### createSubContainer(layer = KwaiPlayerLayer.DEFAULT): HTMLDivElement 创建一个子容器，用于在播放器中添加DOM 参数: layer 添加层级 ```ts enum KwaiPlayerLayer { VIDEO = 'video', // 视频内容层，例如视频画面，水印，全景视频渲染画面 VIDEO_INTERACTIVE = 'videoInteractive', // 视频交互层，如弹幕 DEFAULT = 'default', // 播控层，如播放组件，视频信息面板 } ``` ## 原生js组件事件 **以下事件同HTMLVideoElement** | 属性 | 定义 | 备注 | | -------------- | :----------------------------- | ---- | | abort | 资源未完全加载时触发，非错误 | | | canplay | 可播时 | | | canplaythrough | 可播时，估计已加载足够数据 | | | durationchange | 视频总时长变更 | | | emptied | 媒体源设置为空时 | | | ended | 播放结束 | | | error | 发生错误 | | | loadeddata | 当前播放位置视频帧加载完成 | | | loadedmetadata | metadata加载完成 | | | loadstart | 开始加载 | | | pause | 进入暂停状态 puased转为true时 | | | play | 进入播放状态 puased转为false时 | | | playing | 播放准备开始时 | | | progress | 加载资源 | | | ratechange | 播放速度变更 | | | resize | 视频源尺寸变更 | | | seeked | seek完成 | | | seeking | seek开始 | | | stalled | 尝试获取数据但是为取到时触发 | | | suspend | 加载数据被挂起 | | | timeupdate | 播放时间变更 | | | volumechange | 音量变更 | | | waiting | 缺少数据导致播放暂停 | | **与HTMLVideoElement有差异的事件** > 以下事件与多清晰度相关 ### manifestparsed + 定义：manifest解析成功事件 + 数据： ```js { levels: { width: 640, // 宽，可选 height: 360, // 高，可选 qualityType: "360" qualityLabel: "标清" }[], // 可用流列表 currentLevel: 3, // 当前流index, audioTracks?: { lang: 'en', // 语言 qualityLabel: '', qualityType: '', }[], // 可用音频轨 audioTrack?: 0, // 当前音频轨index } ``` ### levelswitching + 定义：开始进行码率切换 + 数据： ```js { bitrate: 460560, // 码率 smooth: true, // 是否平滑切换 auto: false, // 是否自动 level: 1, // level下标 id: 1, // 切换操作id } ``` ### levelswitched + 定义：码率切换成功事件 + 数据： ```js { bitrate: 460560, // 码率 smooth: true, // 是否平滑切换 auto: false, // 是否自动 level: 1， // level下标 id: 1, // 切换操作id } ``` ### levelswitchplaying + 定义：码率切换开始播放，切换至自动码率时无此事件 + 数据： ```js { bitrate: 460560, // 码率 smooth: true, // 是否平滑切换 auto: false, // 是否自动 level: 1， // level下标 id: 1, // 切换操作id } ``` ### levelswitchfailed + 定义：切换清晰度失败 ### audiotrackswitching + 定义：音频轨开始切换 + 数据： ```js { level: 0, // 音频轨id smooth: false, // 是否平滑切换 auto: false, // 是否自动切换 id: 1 // 切换操作id } ``` ### audiotrackswitched + 定义：音频轨切换完成 + 数据： ```js { level: 0, // 音频轨id smooth: false, // 是否平滑切换 auto: false, // 是否自动切换 id: 1 // 切换操作id } ``` ## React组件与原生js组件差异 API相同 ### React事件对应表 | React组件事件 | 对应事件 | | --------------------- | :------------------ | | onAbout | abort | | onCanplay | canplay | | onCanplayThrough | canplaythrough | | onDurationChange | durationchange | | onEmptied | emptied | | onEnded | ended | | onError | error | | onLoadedData | loadeddata | | onLoadedMetadata | loadedmetadata | | onLoadStart | loadstart | | onPause | pause | | onPlay | play | | onPlaying | playing | | onProgress | progress | | onRateChange | ratechange | | onResize | resize | | onSeeked | seeked | | onSeeking | seeking | | onStalled | stalled | | onSuspend | suspend | | onTimeUpdate | timeupdate | | onVolumeChange | volumechange | | onWaiting | waiting | | onManifestParsed | manifestparsed | | onLevelSwitching | levelswitching | | onLevelSwitched | levelswitched | | onLevelSwitchPlaying | levelswitchplaying | | onLevelSwitchFailed | levelswitchfailed | | onAudioTrackSwitching | audiotrackswitching | | onAudioTrackSwitched | audiotrackswitched | ## Vue组件与原生js组件差异 事件相同 **以下props同HTMLVideoElement** + crossOrigin //是否设置跨域 + preload //是否预加载 + defaultPlaybackRate //设置默认播放倍速 + playbackRate //修改播放倍速 + autoplay //是否设置视频播自动播放 + loop //是否在视频播放结束的时候，自动返回视频开始的地方，继续播放 + controls //是否在视频底部使用默认面板 包括控制音量，跨帧，暂停/播放等 + volume //设置音量 + muted //设置音量是否静音 + defaultMuted //设置音量是否默认静音 + poster //视频播放之前，作为海报展示的图片 + disablePictureInPicture //是否禁用画中画选项 + playsinline //指明视频将内联（inline）播放，即在元素的播放区域内 + src //播放URL或者manifest内容 **Vue组件属性对照表** | Vue组件 API | 原生js组件属性 | | ------------------------------------------------------- | :------------------------------------------------ | | getError | error | | getNetworkState | networkState | | getBuffered | buffered | | getReadyState | readyState | | getSeeking | seeking | | getDuration | duration | | getPaused | paused | | getSeekable | seekable | | getEnded | ended | | getVideoWidth | videoWidth | | getVideoHeight | videoHeight | | getSrc / setSrc | src | | getCrossOrigin / setCrossOrigin | crossOrigin | | getPreload / setPreload | preload | | getCurrentTime / setCurrentTime | currentTime | | getDefaultPlaybackRate / setDefaultPlaybackRate | defaultPlaybackRate | | getPlaybackRate / setPlaybackRate | playbackRate | | getAutoplay / setAutoplay | autoplay | | getLoop / setLoop | loop | | getControls / setControls | controls | | getVolume / setVolume | volume | | getMuted / setMuted | muted | | getDefaultMuted / setDefaultMuted | defaultMuted | | getPoster / setPoster | poster | | getDisablePictureInPicture / setDisablePictureInPicture | disablePictureInPicture | | getPlaysinline / setPlaysinline | playsinline + webkit-playsinline + x5-playsinline | ### 在页面中引入 + 引入js ```html ``` + 提供挂载元素 ```html

``` + 实例化 ```html ``` 可以根据需要引入不同包 ```html ``` # 错误码 播放组件错误说明 | code | 定义 | | | :-------- | :------------------------------------------------------ | :------------- | | 10xx | 流加载错误 | 网络错误 | | 1000 | 流加载错误且无http status code，加载资源的跨域头不正确 | 网络错误 | | 1001 | 流加载错误400 | 网络错误 | | 1002 | 流加载错误401 | 网络错误 | | 1003 | 流加载错误403 | 网络错误 | | 1004 | 流加载错误404 | 网络错误 | | 1005 | 流加载错误4xx | 网络错误 | | 1006 | 流加载错误5xx | 网络错误 | | 1007 | 流加载错误，连接超时 | 网络错误 | | 1008 | 流加载错误，数据超时 | 网络错误 | | 1009 | 流加载出错，传输过程中失败 | 网络错误 | | 11xx | hlsManifestLoadError HLS manifest加载错误 | 网络错误 | | 12xx | hlsLevelLoadError HLS level加载错误 | 网络错误 | | 13xx | hls音频track playlist加载失败 | 网络错误 | | 14xx | hls key加载失败 网络错误 | 网络错误 | | 15xx | drm license加载失败 | 网络错误 | | 16xx | 解码库加载失败 | 网络错误 | | 100 | canNotSeek无法seek | | | 101 | video触发错误 且未取到MediaError.code | | | 102 | 不支持的协议 | | | 103 | 传入配置错误 | | | 106 | seek至指定帧失败 | | | 107 | 传入Src为空 | | | 111 | video触发错误 对应MediaError.code 1 | 参考MediaError | | 112 | video触发错误 对应MediaError.code 2 | 参考MediaError | | 113 | video触发错误 对应MediaError.code 3 | 参考MediaError | | 114 | video触发错误 对应MediaError.code 4 | 参考MediaError | | 200 | mediaSourceError 初始化MSE错误，MediaSource未定义时触发 | | | 201 | addSourceBufferError MSE增加SourceBuffer失败 | | | 202 | sourceBufferError MSE的SourceBuffer触发错误 | | | 203 | endOfStreamError MSE结束流错误 | | | 204 | appendBufferError MSE填充buffer错误 | | | 205 | SourceBuffer changeType 错误 | | | 301 | 解封装错误 | | | 302 | 重新封装错误 | | | 303 | remuxAllocError 重新封装alloc mdat存储错误 | | | 304 | remux worker报错 | | | 305 | 未找到解封装器 | | | 400 | manifestParsingError manifest解析错误 | | | 401 | levelSwitchError HLS level切换错误 | | | 500~506 | 加密视频解密错误 | | | 600 | wasm解码库加载失败 | | | 601 | wasm解码库启动失败 | | | 602 | wasm解码库渲染失败 | | | 603 | wasm解码时WebGL发生错误 | | | 604 | wasm解码不支持 | | | 1011~1019 | webRTC直播错误 | | 错误码111~114 参考[MediaError code说明](https://developer.mozilla.org/en-US/docs/Web/API/MediaError/code)，