API文档¶
本文是PCWeb播放器SDK的API文档
属性¶
currentState¶
| 参数类型 | 只读 | 描述 |
|---|---|---|
| PlayerState | 是 | 返回当前播放器状态 |
PlayerState枚举相关说明：
| 枚举名 | 枚举值 | 说明 |
|---|---|---|
| init | init | 初始化 |
| canplay | canplay | 可以播放状态 |
| loading | loading | 正在进行加载 |
| playing | playing | 正在进行播放 |
| seeking | seeking | 正在进行快进操作 |
| waiting | waiting | 播放出现缓冲区不足，正在缓冲 |
| pause | paused | 播放暂停 |
| smoothswitching | smoothswitching | 正在进行无缝切换操作 |
| ended | ended | 播放完成 |
| error | error | 播放出现错误 |
kernelType¶
| 参数类型 | 只读 | 描述 |
|---|---|---|
| KernelType | 是 | 返回当前播放内核类型 |
KernelType枚举相关说明：
| 枚举名 | 枚举值 | 说明 |
|---|---|---|
| unknow | 9 | 未知 |
| native | 0 | 浏览器原生播放 |
| hls | 1 | hls.js内核播放 |
| dash | 2 | dash.js内核播放 |
| webassembly | 3 | 自研wasm内核播放 |
videoElement¶
| 参数类型 | 只读 | 描述 |
|---|---|---|
| HTMLElement | 是 | 返回当前播放器显示对象，用户需将此对象添加到舞台，进行实际显示 |
currentTime¶
| 参数类型 | 只读 | 描述 |
|---|---|---|
| number | 是 | 当前播放器时间 |
downloadSpeed¶
| 参数类型 | 只读 | 描述 |
|---|---|---|
| number | 是 | 返回当前播放器下载速度的实时速度 |
duration¶
| 参数类型 | 只读 | 描述 |
|---|---|---|
| number | 是 | 返回当前播放视频的时间长度 |
ended¶
| 参数类型 | 只读 | 描述 |
|---|---|---|
| boolean | 是 | 返回当前播放视频是否播放结束 |
loadInfos¶
| 参数类型 | 只读 | 描述 |
|---|---|---|
| [string,string][] | 是 | 描述播放器加载信息，左值表示时间，右值表示时间发生时间点，以毫秒(ms)为单位 |
loop¶
| 参数类型 | 只读 | 读取操作描述 | 写入操作描述 |
|---|---|---|---|
| boolean | 否 | 获取当前循环播放状态 | 设置当前是否循环播放 |
muted¶
| 参数类型 | 只读 | 读取操作描述 | 写入操作描述 |
|---|---|---|---|
| boolean | 否 | 获取当前静音状态 | 设置当前是否静音 |
paused¶
| 参数类型 | 只读 | 描述 |
|---|---|---|
| boolean | 是 | 获取视频是否处于暂停状态 |
rate¶
| 参数类型 | 只读 | 读取操作描述 | 写入操作描述 |
|---|---|---|---|
| number | 否 | 获取当前播放速率 | 设置当前播放速率 |
src¶
| 参数类型 | 只读 | 描述 |
|---|---|---|
| string | 是 | 获取视频播放地址 |
volume¶
| 参数类型 | 只读 | 读取操作描述 | 写入操作描述 |
|---|---|---|---|
| number | 否 | 获取当前播放音量 | 设置当前播放音量 |
方法¶
addEventListener¶
添加事件监听器，用于指定事件类型的回调函数注册。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| type | string | 事件类型名称 |
| listener | EventListener | 事件回调函数 |
返回值: 无
destroy¶
销毁当前对象，释放资源。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| 无 | 无 | 无 |
返回值: 无
dispatchEvent¶
派发一个事件给事件处理器，使得事件能够被对应的监听器处理。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| event | PlayerEvent | 要派发的事件对象 |
返回值:无
enterPip¶
进入画中画模式。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| 无 | 无 | 无 |
返回值: Promise
进入画中画模式后，返回的Promise对象在成功解析时，会提供一个PictureInPictureWindow对象，该对象可以用于控制画中画窗口的尺寸等属性。这是一个较新的Web API，允许视频元素在页面之外以小窗口形式继续播放。
exitPip¶
退出画中画模式。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| 无 | 无 | 无 |
返回值: Promise
调用exitPip方法可以使得视频离开画中画模式，返回的Promise对象在成功解析时表示画中画窗口已成功关闭。这允许开发者在视频不再需要以小窗口形式播放时，将其移出画中画模式，恢复到正常的页面内播放状态。
getDebugInfo¶
获取调试信息。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| 无 | 无 | 无 |
返回值: MgtvKernelDebugInfo
调用getDebugInfo方法可以获取到特定的调试信息，这些信息对于开发者来说非常有用，可以帮助诊断和解决程序运行中的问题。返回的MgtvKernelDebugInfo对象包含了一系列的调试数据和状态信息。
getP2pStatus¶
获取点对点（P2P）状态。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| 无 | 无 | 无 |
返回值: number
调用getP2pStatus方法将返回一个数字类型的值，该值表示当前点对点连接的状态。这个状态值可以用于判断P2P连接是否成功建立、是否存在问题或者是否已被关闭等，从而帮助开发者进行相应的处理和决策。
getStream¶
根据索引获取流信息。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| index | number | 流的索引值 |
返回值: LoadOptionStream
getStream方法根据提供的索引值返回一个LoadOptionStream对象，该对象包含了流的详细信息。这对于管理和操作媒体流非常有用，尤其是在处理多个流时，可以通过索引快速访问特定的流。
init¶
如果需要调用load重新播放视频，需要重置播放器，并且重新初始化。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| config | MgtvKernelConfig | 播放器的配置信息 |
返回值: void
在使用load方法重新播放视频之前，您可能需要重置播放器到初始状态。init方法接收一个MgtvKernelConfig对象作为参数，该对象包含了初始化播放器所需的配置信息。一旦播放器被重置并重新初始化，您就可以使用load方法加载新的视频源。
示例
kernel.stop(); // 停止当前视频播放
kernel.init(config); // 使用新的配置信息重新初始化播放器
kernel.load(src, option); // 加载新的视频源
load¶
加载视频资源并准备播放。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| source | string | 视频资源的URL地址 |
| option | LoadOption | 加载选项配置 |
返回值: Promise
load方法用于缓冲视频资源，如果加载成功，将触发load_success事件，允许追踪加载过程的时间。一旦加载成功，可以立即调用play方法开始播放。若加载失败，则会触发play_error事件。如果使用Promise方式调用，还需处理相应的错误，例如进行重试。
示例
const { stream } = data; // 假设data是从某处获取的包含stream信息的对象
kernel.load(url, {
index: 3, // stream相应的索引
streams: stream, // 一层stream信息
startPosition: 100, // 起播时间，单位秒
// ... 其他参数请参考文档，尽量提供详细信息
}).then((data) => {
console.log(data.loadInfos); // 输出加载过程中的详细信息
kernel.play(); // 开始播放视频
}).catch(error => {
retry(); // 应从二层开始重试
});
// 通过事件控制播放流程
kernel.once("load_success", (event) => {
const { loadInfos } = event.data; // 获取加载过程中的详细信息，可用于上报
kernel.play(); // 开始播放视频
});
kernel.on("play_error", (error) => {
retry(); // 进行重试或其他错误处理
});
| 参数 | 类型 | 描述 |
|---|---|---|
| src | string | 视频播放的URL |
| startPosition | number | 起播时间 |
| level | number | 起播清晰度 |
| dramData | object | DRM加密相关数据 |
| drmType: string | ||
| licenseUrl: string |
off¶
移除指定类型的事件监听器。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| type | string | 事件类型名称 |
| listener | EventListener | 要移除的事件监听器 |
返回值: void
off方法用于从对象中移除之前添加的事件监听器。这通常在不再需要监听特定事件时使用，以防止潜在的内存泄漏。该方法是EventDispatcher的一部分，因此可以在任何继承自EventDispatcher的对象上使用。
on¶
添加指定类型的事件监听器。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| type | string | 事件类型名称 |
| listener | EventListener | 要添加的事件监听器 |
返回值: void
on方法用于向对象添加事件监听器。当指定类型的事件发生时，注册的监听器函数将被调用。这是处理事件和响应用户操作或其他行为的基本机制之一。作为EventDispatcher的一部分，on方法可以应用于任何继承自EventDispatcher的对象。
once¶
添加一个仅执行一次的事件监听器。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| type | string | 事件类型名称 |
| listener | EventListener | 事件监听器 |
返回值: void
once方法用于注册一个事件监听器，与on方法类似，但它确保监听器函数仅执行一次。一旦事件被触发，监听器将自动从事件队列中移除。这在需要对某个事件做出一次性响应时非常有用，例如，只在第一次发生错误时记录日志或执行特定的初始化操作。
pause¶
尝试暂停播放。
返回值: Promise
pause方法用于请求暂停视频或音频的播放。成功执行后，视频或音频的播放状态将变为暂停。该方法返回一个Promise对象，可以在Promise解决后执行相应的操作，例如更新UI状态或进行其他逻辑处理。
play¶
尝试播放视频。
返回值: Promise
play方法用于尝试开始播放视频或音频。如果播放成功，Promise将解决，否则将被拒绝。这个方法通常用于在页面加载后自动开始播放媒体内容。
removeEventListener¶
移除指定类型的事件监听器。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| type | string | 事件类型名称 |
| listener | EventListener | 要移除的事件监听器 |
返回值: void
removeEventListener方法用于从对象中移除之前添加的事件监听器。这通常在不再需要监听特定事件时使用，以防止潜在的内存泄漏。
screenShot¶
视频截图功能。
返回值: string
screenShot方法用于捕获当前视频帧的截图，并返回截图的URL或数据。这对于用户需要保存或分享视频特定时刻的画面非常有用。
seek¶
跳转到视频位置。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| time | number | 目标位置 |
返回值: void
seek方法用于将视频播放位置跳转到指定的时间点。这允许用户快速导航到视频的特定部分。
smoothswitchsource¶
无缝切换视频。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| src | string | 视频资源 |
| option | LoadOption | 选项 |
返回值: Promise
smoothswitchsource方法用于在不中断播放的情况下切换到另一个视频源。它支持平滑过渡，通常用于在不同清晰度或格式之间切换。
kernel.smoothswitchsource(src,{index:1}).then(()=>{
console.log('switching to '+src+' succesfully')
}).catch((err)=>{
if(err.code === 500002){
//用户操作，导致取消
}else{
//need retry.
}
}
stop¶
切换视频时，需要先调用stop。
返回值: void
stop方法用于在切换视频源之前停止当前视频的播放。这是为了确保平滑地切换到新的视频源。
getFormat（static）¶
获取播放器支持的编码类型。
返回值: Promise<"h264" | "h265">
getFormat方法用于检测并返回当前播放器支持的编码类型，例如"h264"或"h265"。这对于确定视频的最佳播放格式非常有用。
getVersion（static）¶
获取内核版本号。
返回值: string
getVersion方法返回当前内核的版本号。这有助于开发者了解和维护与特定版本相关的功能和修复。
initPlugin（static）¶
初始化插件，有些视频格式需求特定插件才可以播放。
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| type | PluginType | 插件类型 |
返回值: Promise
initPlugin方法用于初始化特定类型的插件，以便播放器能够支持更多的视频格式。这对于确保视频内容能够顺利播放至关重要。
初始化¶
const options = {...} //初始化参数
const kernel = new MgtvKernel(options)
初始化参数：
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| videoType | "main" | "ad" | main |
| IsInternal | boolean | true | 是否是国内版 |
| p2p | boolean | true | 是否开启p2p |
| isLive | boolean | false | 是否直播 |
| isIpad | boolean | false | 是否是ipad平台 |
| maxBufferTime | number | 60 | 最大缓存时间 |
| levelTimeout | number | 11 | 三层请求超时时间 |
| lobparam | Object |
lobparam：
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| did | string | 设备id | |
| uuid | string | 用户id | |
| suuid | string | 会话id | |
| vid | string | 视频id | |
| wver | string | 网页版本 | |
| pver | string | 播放器版本 |