@video-lab/player-core 3.1.0 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +57 -23
- package/dist/index.cjs +518 -147
- package/dist/index.d.cts +21 -18
- package/dist/index.d.mts +21 -18
- package/dist/index.mjs +517 -146
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -10,45 +10,64 @@ Video Lab Player 的播放核心。它包装 xgplayer，并对外提供统一的
|
|
|
10
10
|
pnpm add @video-lab/player-core
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
+
## 什么时候直接使用它
|
|
14
|
+
|
|
15
|
+
| 你的场景 | 推荐入口 |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| React / Vue 业务页面，使用 SDK 默认组合 | `@video-lab/react` / `@video-lab/vue` |
|
|
18
|
+
| 需要 iframe 隔离 | `@video-lab/react-frame` / `@video-lab/vue-frame` |
|
|
19
|
+
| 自己持有 DOM、渲染覆盖层和播放器生命周期 | 本包 |
|
|
20
|
+
| 静态 CMS iframe | `@video-lab/embed-helper` |
|
|
21
|
+
|
|
22
|
+
直接使用本包意味着宿主自己负责创建容器、把 `PlayerEvent` 连接到 UI、处理命令 rejection，并在页面卸载时
|
|
23
|
+
销毁句柄。它不是“功能更全”的默认业务入口；框架宿主优先使用对应组合包。
|
|
24
|
+
|
|
13
25
|
## 已实现范围
|
|
14
26
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
|
18
|
-
|
|
19
|
-
| `
|
|
20
|
-
| `
|
|
21
|
-
| `
|
|
22
|
-
| `
|
|
23
|
-
| `
|
|
24
|
-
| `
|
|
25
|
-
| `
|
|
26
|
-
| `
|
|
27
|
-
| `
|
|
28
|
-
| `
|
|
29
|
-
|
|
27
|
+
生产装配以 `src/create-player.ts` 为准。它固定注册下面这些 SDK `BasePlugin`；消费方不能逐个关闭：
|
|
28
|
+
|
|
29
|
+
| 组件 | 职责 |
|
|
30
|
+
|:---|:---|
|
|
31
|
+
| `SafeDestroyPlugin` | 清理事件与根节点样式，支持重复销毁 |
|
|
32
|
+
| `AutoplayGuardPlugin` | 上报自动播放被拒绝 |
|
|
33
|
+
| `VisibilityPlugin` | 在适用平台处理页面切回后的恢复意图 |
|
|
34
|
+
| `CompatPlugin` | 识别 UC / 夸克等已知兼容风险并上报 |
|
|
35
|
+
| `WakeLockPlugin` | 播放时维持屏幕唤醒 |
|
|
36
|
+
| `FullscreenGuardPlugin` | 规避已知全屏崩溃入口 |
|
|
37
|
+
| `ZIndexGuardPlugin` | 归一播放器根节点层级 |
|
|
38
|
+
| `HealthMonitorPlugin` | 测量卡顿并提交观测与恢复意图 |
|
|
39
|
+
| `PlayableStatePlugin` | 聚合可播放状态并发出 `playablechange` |
|
|
40
|
+
| `MediaSessionPlugin` | 将媒体元信息同步给 W3C Media Session |
|
|
41
|
+
|
|
42
|
+
`SourceRouter` 是构造前运行的纯函数，不是 xgplayer 插件；网络与媒体恢复由
|
|
43
|
+
`PlaybackRecovery` / `RecoveryController` 统一调度。`ReconnectPlugin` 与
|
|
44
|
+
`ErrorRecoveryPlugin` 的源码只保留历史回归，不进入生产 preset。HLS 会按路由追加 SDK 自有的
|
|
45
|
+
`OwnedHlsPlugin`，字幕与弹幕插件只在对应配置启用时注册。
|
|
30
46
|
|
|
31
47
|
支持清晰度与 ABR：`setQuality` 命令、`qualitychange` 事件及 `ready.quality` 档位清单（单码率源为空数组）。也支持字幕、弹幕和通过 `source.hls.lowLatencyMode` 显式开启的低延迟 HLS。
|
|
32
48
|
|
|
33
49
|
## 用法
|
|
34
50
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
51
|
+
```html
|
|
52
|
+
<div id="video-player"></div>
|
|
53
|
+
```
|
|
54
|
+
|
|
38
55
|
```ts
|
|
39
56
|
import { createPlayer } from '@video-lab/player-core'
|
|
57
|
+
import '@video-lab/player-core/style.css'
|
|
58
|
+
|
|
59
|
+
const container = document.querySelector('#video-player')
|
|
60
|
+
if (!(container instanceof HTMLElement)) throw new Error('播放器容器未找到')
|
|
40
61
|
|
|
41
62
|
const player = createPlayer({
|
|
42
63
|
el: container,
|
|
43
64
|
config: {
|
|
44
65
|
source: {
|
|
45
66
|
sources: [
|
|
46
|
-
{ url: 'https://
|
|
47
|
-
{ url: 'https://
|
|
67
|
+
{ url: 'https://media.example.com/video/master.m3u8', type: 'hls' },
|
|
68
|
+
{ url: 'https://media.example.com/video.mp4', type: 'mp4' },
|
|
48
69
|
],
|
|
49
|
-
live: true,
|
|
50
70
|
},
|
|
51
|
-
autoplay: true,
|
|
52
71
|
muted: true,
|
|
53
72
|
},
|
|
54
73
|
onEvent: (e) => console.log(e.event, e.payload),
|
|
@@ -56,9 +75,22 @@ const player = createPlayer({
|
|
|
56
75
|
|
|
57
76
|
await player.play()
|
|
58
77
|
player.seek(30)
|
|
59
|
-
|
|
78
|
+
|
|
79
|
+
window.addEventListener('pagehide', () => player.destroy(), { once: true })
|
|
60
80
|
```
|
|
61
81
|
|
|
82
|
+
`destroy()` 是幂等的，但应在组件卸载或页面离开时调用；不要在播放器创建后立即销毁。
|
|
83
|
+
|
|
84
|
+
## 接入完成清单
|
|
85
|
+
|
|
86
|
+
- 宿主通过 `config.source` 提供已授权的媒体地址；SDK 不接收请求头，也不刷新签名 URL。
|
|
87
|
+
- 将 `onEvent` 用于本地 UI 和状态同步；`timeupdate` 等事件可能高频，不能在回调里直接发送网络请求。
|
|
88
|
+
- 需要可排序、可去重的上报时消费带 `delivery` 的 `onEvent`，再交给 `@video-lab/telemetry`；该包只归一事件，
|
|
89
|
+
业务方仍负责 transport 的队列、批量和失败观测。
|
|
90
|
+
- 所有异步命令都 `await` 并处理 rejection；`error` 是诊断事实，加载/重试按钮应以 `playablechange`
|
|
91
|
+
的 `playable`、`recoverable`、`action` 驱动。
|
|
92
|
+
- 组件或页面卸载时调用 `destroy()`；需要切换 HLS/FLV 等不同内核时先销毁，再以新源重建。
|
|
93
|
+
|
|
62
94
|
## 设计上值得知道的几件事
|
|
63
95
|
|
|
64
96
|
**`SourceRouter` 不是 xgplayer 的 BasePlugin,是纯函数。** 选源必须发生在 `new Player()` **之前**——内核插件(hls.js / flv.js)得在构造时就注册进去,而 BasePlugin 的生命周期最早只到 `beforeCreate`,拿不到这个时机。纯函数也更好测:UA 直接传进来,不用为了测 iOS 去改 `navigator`。
|
|
@@ -97,3 +129,5 @@ pnpm --filter @video-lab/player-core test
|
|
|
97
129
|
宿主 UI 读取 `playablechange` 的 `playable`、`recoverable`、`action`。`error` 只提供诊断；预算耗尽才给出 `action: 'retry'`，宿主无需按错误原因拼接重试状态。组合层可通过构造配置关闭默认 Error/Loading 覆盖层，事件仍保留。静态 iframe URL 没有宿主命令通道，内部按钮仍走同一调度。
|
|
98
130
|
|
|
99
131
|
更多迁移语义见 [ADR-099](../../docs/adr/ADR-099-unified-recovery-contract.md)。
|
|
132
|
+
|
|
133
|
+
继续阅读：[五种接入方式怎么选](../../apps/docs/guide/access-modes.md)、[按场景查 API](../../apps/docs/reference/by-scenario.md)、[完整宿主接入与错误/恢复语义](../../docs/guides/USER-GUIDE.md)。
|