openvod-jssdk 1.2.2 → 1.2.5
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 +162 -189
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,275 +1,248 @@
|
|
|
1
1
|
# openvod-jssdk
|
|
2
2
|
|
|
3
|
-
OpenVOD 播放器接入 SDK
|
|
4
|
-
|
|
3
|
+
OpenVOD 播放器接入 SDK。它帮你把「登录 → 拿媒资列表 → 发起播放 → 拿到播放地址 → 播放中自动续期」这些事都做好,
|
|
4
|
+
你只需要负责把播放地址交给 `<video>` 播放,以及处理界面上的事。
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
接口参考:`docs/vod/api.md §2`(分发端 HTTP API)。首个消费方:`apps/player`。
|
|
6
|
+
可以在浏览器、Node 18+、React Native 里使用,没有任何依赖。
|
|
8
7
|
|
|
9
8
|
## 安装
|
|
10
9
|
|
|
11
10
|
```bash
|
|
12
|
-
# npm 官方
|
|
13
11
|
npm i openvod-jssdk
|
|
14
|
-
|
|
15
|
-
# CNB 制品库(组织级 npm 制品库;地址在「制品库 → 设置 → 基础设置」查看)
|
|
16
|
-
npm i openvod-jssdk --registry=https://npm.cnb.cool/<组织>/<制品库>/-/packages/
|
|
17
|
-
# 长期使用建议写进项目 .npmrc:
|
|
18
|
-
# registry=https://npm.cnb.cool/<组织>/<制品库>/-/packages/
|
|
19
|
-
# always-auth=true
|
|
20
|
-
# //npm.cnb.cool/<组织>/<制品库>/-/packages/:_authToken=${CNB_TOKEN}
|
|
21
12
|
```
|
|
22
13
|
|
|
23
|
-
|
|
24
|
-
在 `src/types.ts` 是自包含镜像,一致性由 `bun run typecheck` 的编译期断言守住)。
|
|
14
|
+
如果用 CNB 制品库:
|
|
25
15
|
|
|
26
|
-
|
|
16
|
+
```bash
|
|
17
|
+
npm i openvod-jssdk --registry=https://npm.cnb.cool/arsrna/media/openvod/-/packages/
|
|
18
|
+
```
|
|
27
19
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
20
|
+
长期使用建议写进项目的 `.npmrc`:
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
registry=https://npm.cnb.cool/arsrna/media/openvod/-/packages/
|
|
24
|
+
always-auth=true
|
|
25
|
+
//npm.cnb.cool/arsrna/media/openvod/-/packages/:_authToken=${CNB_TOKEN}
|
|
26
|
+
```
|
|
35
27
|
|
|
36
28
|
## 快速开始
|
|
37
29
|
|
|
30
|
+
SDK 创建时要告诉它两件事:服务地址(`baseUrl`),以及用什么方式登录。登录方式有四种,按你的场景选一种:
|
|
31
|
+
|
|
32
|
+
### 方式一:用户名密码(最简单)
|
|
33
|
+
|
|
34
|
+
SDK 自己负责登录和续登,适合快速跑通:
|
|
35
|
+
|
|
38
36
|
```ts
|
|
39
37
|
import { createPlayerSdk } from "openvod-jssdk";
|
|
40
38
|
|
|
41
|
-
// ① 口令模式(SDK 负责 login / JWT 缓存 / 到期重登)
|
|
42
39
|
const sdk = createPlayerSdk({
|
|
43
|
-
baseUrl: "https://vod.example.com",
|
|
40
|
+
baseUrl: "https://vod.example.com",
|
|
44
41
|
credential: { mode: "password", username: "viewer", password: "******" },
|
|
45
42
|
});
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### 方式二:由你的后端提供 token(网页端推荐)
|
|
46
46
|
|
|
47
|
-
|
|
48
|
-
|
|
47
|
+
不要把用户密码放进浏览器。让用户先登录你的网站,你的后端把 token 发给前端,SDK 每次需要时找你要:
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
const sdk = createPlayerSdk({
|
|
49
51
|
baseUrl: "https://vod.example.com",
|
|
50
52
|
credential: {
|
|
51
53
|
mode: "tokenProvider",
|
|
52
54
|
getToken: async () => {
|
|
53
|
-
const res = await fetch("/api/session");
|
|
55
|
+
const res = await fetch("/api/session"); // 你自己的后端接口
|
|
54
56
|
const body = await res.json();
|
|
55
57
|
return { access_token: body.access_token, expires_at: body.expires_at };
|
|
56
58
|
},
|
|
57
59
|
},
|
|
58
60
|
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### 方式三:直接给一个现成的 token
|
|
59
64
|
|
|
60
|
-
|
|
61
|
-
|
|
65
|
+
你自己负责 token 的更新。token 过期后 SDK 不会重新登录,只能报错:
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
const sdk = createPlayerSdk({
|
|
62
69
|
baseUrl: "https://vod.example.com",
|
|
63
|
-
credential: { mode: "static", token: jwtFromHost, expires_at: "2026-10-17T08:00:00Z" },
|
|
70
|
+
credential: { mode: "static", token: jwtFromHost, expires_at: "2026-10-17T08:00:00Z" },
|
|
64
71
|
});
|
|
65
|
-
|
|
66
|
-
// ④ attach 模式(不配置 credential):仅接管已有签名 URL,零请求
|
|
67
|
-
const sdk4 = createPlayerSdk({ baseUrl: "https://vod.example.com" });
|
|
68
|
-
const attached = sdk4.attachPlayback({ media_id: "55395830", manifest_url: signedUrlFromServer });
|
|
69
72
|
```
|
|
70
73
|
|
|
71
|
-
###
|
|
72
|
-
|
|
73
|
-
```
|
|
74
|
-
宿主 SDK delivery
|
|
75
|
-
│ createPlayerSdk(config) ──▶ 同步构造(零网络请求)
|
|
76
|
-
│ sdk.listMedia() ─────────▶ getAccessToken ── login(或 getToken) ──▶ POST /v1/auth/login
|
|
77
|
-
│ ◀── JWT 缓存(leeway 内零请求;401 → 重登一次并重试)
|
|
78
|
-
│ sdk.play(id) ────────────▶ 会话缓存命中? ── 命中 → 零请求返回 handle
|
|
79
|
-
│ │ 未命中/将过期 → POST /v1/media/{id}/play
|
|
80
|
-
│ ◀── handle{ sid, manifest_url, expires_at, template_id, templates, subtitles }
|
|
81
|
-
│ video.src = manifest_url ─▶ (播放器自行取 /key 与分片;SDK 不介入)
|
|
82
|
-
│ ├─ 到期前 refreshLeewaySec:自动 play 重签 ─▶ emit playback:refreshed{auto}
|
|
83
|
-
│ sdk.on("playback:refreshed") ─ 宿主换源(保留进度,见下)
|
|
84
|
-
│ handle.switchTemplate(id) ▶ POST play(template_id) → 原位更新 ─▶ emit playback:template_changed
|
|
85
|
-
│ handle.dispose() / sdk.dispose() ▶ 停定时器 + 本地失效(服务端会话按 TTL 过期)
|
|
86
|
-
```
|
|
74
|
+
### 方式四:不登录,只播放一个现成的地址
|
|
87
75
|
|
|
88
|
-
|
|
76
|
+
如果你已经从别处拿到了签名好的播放地址,SDK 可以直接接管它,不会发任何请求:
|
|
89
77
|
|
|
90
78
|
```ts
|
|
91
|
-
const
|
|
92
|
-
const
|
|
93
|
-
|
|
79
|
+
const sdk = createPlayerSdk({ baseUrl: "https://vod.example.com" });
|
|
80
|
+
const handle = sdk.attachPlayback({ media_id: "55395830", manifest_url: signedUrlFromServer });
|
|
81
|
+
```
|
|
94
82
|
|
|
95
|
-
|
|
96
|
-
video.src = handle.manifest_url; // 清单 → 密钥 → 分片全链路已带签名
|
|
83
|
+
## 从列表到播放
|
|
97
84
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
await
|
|
101
|
-
video.src = handle.manifest_url; // 换源后读最新字段(见下方「可变视图」)
|
|
85
|
+
```ts
|
|
86
|
+
// 拿媒资列表(只会返回已经转码完成、可以播放的媒资)
|
|
87
|
+
const page = await sdk.listMedia({ limit: 50 });
|
|
102
88
|
|
|
103
|
-
//
|
|
104
|
-
const
|
|
105
|
-
const vtt = await handle.fetchSubtitleText(tracks[0]);
|
|
89
|
+
// 拿单个媒资详情(封面、描述、标签等)
|
|
90
|
+
const detail = await sdk.getMedia("55395830");
|
|
106
91
|
|
|
107
|
-
//
|
|
108
|
-
const
|
|
109
|
-
video.src = event.manifest_url; // 事件 payload 与字段逐字一致
|
|
110
|
-
});
|
|
92
|
+
// 发起播放,拿到播放句柄
|
|
93
|
+
const handle = await sdk.play("55395830");
|
|
111
94
|
|
|
112
|
-
|
|
95
|
+
// 把地址交给播放器,之后清单、分片、解密密钥的请求都会自动带上签名
|
|
96
|
+
video.src = handle.manifest_url;
|
|
113
97
|
```
|
|
114
98
|
|
|
115
|
-
###
|
|
99
|
+
### 切换清晰度
|
|
116
100
|
|
|
117
101
|
```ts
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
sdk.on("error", (e) => {/* e.operation:login / list_media / get_media / play / refresh / switch_template / subtitle / auto_refresh */});
|
|
121
|
-
sdk.dispose(); // 清全部定时器与缓存(服务端会话按 TTL 自然过期)
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
## API 速览(完整签名见 spec §2.3)
|
|
102
|
+
// handle.templates 是这个媒资实际有的清晰度选项
|
|
103
|
+
const options = handle.templates.map((t) => ({ label: t.name, value: t.id }));
|
|
125
104
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
| `sdk.listMedia({ limit?, signal? })` | 媒资列表(`limit` 原样传给服务端,由服务端裁决) |
|
|
131
|
-
| `sdk.getMedia(id, { signal? })` | 媒资详情(非 READY 也返回,`playable=false`) |
|
|
132
|
-
| `sdk.play(id, { templateId?, forceNew?, signal? })` | 建 / 复用会话;**本地缓存新鲜时零请求**;并发同语义调用 single-flight |
|
|
133
|
-
| `sdk.attachPlayback(descriptor)` | 接管已有签名 URL(零请求;无凭据时 `refresh` / `switchTemplate` 抛 `sdk_no_credential`) |
|
|
134
|
-
| `sdk.fetchSubtitleText(track)` | 拉 VTT 文本(自动定位所属句柄以支持 403 重签重试) |
|
|
135
|
-
| `handle.switchTemplate(id)` | 复用会话换源(`id === 当前 template_id` 时空操作;失败不打断当前播放) |
|
|
136
|
-
| `handle.refresh({ force? })` | 重新签发;`force: true` 强制请求(用于「重新播放」) |
|
|
137
|
-
| `handle.fetchSubtitleText(track)` | 句柄内字幕文本(403 → 重签 → 新 URL 重试一次) |
|
|
138
|
-
| `handle.dispose()` | 停定时器 + 句柄失效(服务端无释放端点) |
|
|
139
|
-
| `sdk.dispose()` | 清全部定时器与缓存;销毁后所有入口抛 `sdk_disposed` |
|
|
140
|
-
|
|
141
|
-
### 配置项(`PlayerSdkConfig`)
|
|
142
|
-
|
|
143
|
-
| 字段 | 默认 | 说明 |
|
|
144
|
-
|---|---|---|
|
|
145
|
-
| `baseUrl` | 必填 | delivery 基址,仅 http/https;非法抛 `sdk_invalid_config` |
|
|
146
|
-
| `credential` | 无 | 见上文三种模式 + attach |
|
|
147
|
-
| `fetch` | 全局 `fetch` | 注入自定义实现(RN / 测试 / 代理) |
|
|
148
|
-
| `timeoutMs` | `10000` | 单请求超时 |
|
|
149
|
-
| `retries` | `0` | **幂等 GET** 的网络层重试次数(5xx / 网络失败;POST 不重试) |
|
|
150
|
-
| `jwtRefreshLeewaySec` | `300` | JWT 到期前多久重登 |
|
|
151
|
-
| `refreshLeewaySec` | `300` | 会话 / 清单 token 到期前多久自动重签 |
|
|
152
|
-
| `autoRefresh` | `true` | 关掉后只提供手动 `refresh()` |
|
|
153
|
-
| `storage` | 无(纯内存) | 注入 JWT 持久化(仅存 `{ access_token, expires_at, identity }`,**不存口令 / 播放 URL**)。安全建议:**不推荐 `localStorage`**;浏览器用内存或 `sessionStorage`,移动端用 Keychain / Keystore 等安全存储 |
|
|
154
|
-
| `onEvent` | 无 | 全局事件监听(等价 `sdk.on(listener)`) |
|
|
105
|
+
// 切换后播放地址会变,需要重新赋给播放器(见下文「换源时保留播放进度」)
|
|
106
|
+
await handle.switchTemplate("ctemplate00000000000002");
|
|
107
|
+
video.src = handle.manifest_url;
|
|
108
|
+
```
|
|
155
109
|
|
|
156
|
-
|
|
110
|
+
### 字幕
|
|
157
111
|
|
|
158
112
|
```ts
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
try {
|
|
162
|
-
await sdk.play(mediaId);
|
|
163
|
-
} catch (e) {
|
|
164
|
-
if (e instanceof DeliveryError) {
|
|
165
|
-
e.code; // api.md §0.2 错误码(类型来自契约 ErrorCode)
|
|
166
|
-
e.status; // HTTP 状态;0 = 网络 / 超时 / 取消
|
|
167
|
-
e.message; // 服务端文案原样(N4)
|
|
168
|
-
e.hint; // SDK 排查建议(describeError(code))
|
|
169
|
-
} else if (e instanceof PlayerSdkError) {
|
|
170
|
-
e.code; // sdk_invalid_config | sdk_no_credential | sdk_disposed | sdk_bad_response
|
|
171
|
-
}
|
|
172
|
-
}
|
|
113
|
+
const tracks = handle.subtitles; // 可用的字幕轨道
|
|
114
|
+
const vtt = await handle.fetchSubtitleText(tracks[0]); // 拿到字幕文本
|
|
173
115
|
```
|
|
174
116
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
| 场景 | 表现 | 处理 |
|
|
178
|
-
|---|---|---|
|
|
179
|
-
| 分发端未启动 / CORS 未放行 | `DeliveryError{code:"internal", status:0}` | 检查 `DELIVERY_CORS_ORIGINS` 是否放行宿主源站 |
|
|
180
|
-
| 账号被禁 / 口令已变 | `unauthorized`(重登一次后仍 401)+ `auth:changed{expired}` | 引导重新登录或 `setCredential()` |
|
|
181
|
-
| 播放器内清单 / 密钥 / 分片 403 | 播放中断(SDK 无法感知播放器内部请求) | 调 `handle.refresh({ force: true })` 换源 |
|
|
182
|
-
| 并发会话达上限 | `session_limit`(**`forceNew` 不绕过上限**) | 等旧会话过期或管理端调大 `max_concurrent_sessions` |
|
|
183
|
-
| 媒资未就绪 / 模板无产物 | `not_playable` | 回列表或从 `handle.templates` 重选 |
|
|
184
|
-
|
|
185
|
-
## 两段必备的宿主代码
|
|
117
|
+
## 播放中你需要处理的两件事
|
|
186
118
|
|
|
187
|
-
###
|
|
119
|
+
### 1. token 快过期时,SDK 会自动换新地址,你要负责换源
|
|
188
120
|
|
|
189
|
-
|
|
121
|
+
播放地址里的签名是有有效期的。快到期时 SDK 会自动请求一个新地址,并发出 `playback:refreshed` 事件。
|
|
122
|
+
**新地址不会自动生效**,你需要监听事件、换源,并恢复播放进度:
|
|
190
123
|
|
|
191
124
|
```ts
|
|
192
125
|
let resume: { time: number; wasPlaying: boolean } | null = null;
|
|
193
126
|
|
|
194
127
|
sdk.on("playback:refreshed", (event) => {
|
|
128
|
+
// 先记下当前的播放进度和播放状态
|
|
195
129
|
resume = { time: video.currentTime, wasPlaying: !video.paused };
|
|
196
|
-
|
|
130
|
+
// 换成新地址(如果用 hls.js,需要销毁重建实例)
|
|
131
|
+
video.src = event.manifest_url;
|
|
197
132
|
});
|
|
198
133
|
|
|
199
134
|
video.addEventListener("loadedmetadata", () => {
|
|
200
135
|
if (!resume) return;
|
|
201
|
-
video.currentTime = resume.time;
|
|
136
|
+
video.currentTime = resume.time; // 恢复进度,失败就从头播,别报错打断用户
|
|
202
137
|
if (resume.wasPlaying) void video.play().catch(() => {});
|
|
203
138
|
resume = null;
|
|
204
139
|
});
|
|
205
140
|
```
|
|
206
141
|
|
|
207
|
-
|
|
142
|
+
切换清晰度时也一样:`switchTemplate` 会换地址并触发 `playback:template_changed` 事件,同样需要换源和恢复进度。
|
|
208
143
|
|
|
209
|
-
|
|
210
|
-
|
|
144
|
+
### 2. 播放器里出现 403 时,手动换一套新签名
|
|
145
|
+
|
|
146
|
+
播放器内部请求分片、密钥时报 403(常见于播放暂停太久、签名已过期),SDK 感知不到这些请求,
|
|
147
|
+
需要你手动重签一次再换源:
|
|
211
148
|
|
|
212
149
|
```ts
|
|
213
150
|
async function recoverPlayback(errorCode?: number) {
|
|
214
|
-
if (errorCode !== 403) return;
|
|
215
|
-
await handle.refresh({ force: true });
|
|
216
|
-
video.src = handle.manifest_url;
|
|
151
|
+
if (errorCode !== 403) return;
|
|
152
|
+
await handle.refresh({ force: true }); // 复用当前会话重签,不会新开会话
|
|
153
|
+
video.src = handle.manifest_url;
|
|
217
154
|
}
|
|
218
155
|
```
|
|
219
156
|
|
|
220
|
-
##
|
|
157
|
+
## 配置项
|
|
221
158
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
- **换源是宿主职责**:SDK 只发事件(`playback:refreshed` / `playback:template_changed`),把新 `manifest_url`
|
|
237
|
-
赋给播放器元素由宿主完成;换源后的进度保留同样由宿主实现。
|
|
238
|
-
- **字幕挂载与渲染**:SDK 只给轨道数据与 VTT 文本,不做解析 / 样式 / 重排。
|
|
239
|
-
- **自动续签失败**:先等 30s 重试一次,仍失败发 `error{operation:"auto_refresh"}` 并停止(防故障放大)。
|
|
240
|
-
- **多标签 / 多账号**:`storage` 默认不启用(纯内存,关标签即失效);启用时仅按 `identity` 校验,切换身份自动清除。
|
|
241
|
-
- 客户端不复制服务端策略:`limit` 非法回退、模板自动选择、会话并发上限一律由服务端裁决。
|
|
242
|
-
|
|
243
|
-
## 开发
|
|
159
|
+
```ts
|
|
160
|
+
const sdk = createPlayerSdk({
|
|
161
|
+
baseUrl: "https://vod.example.com", // 必填,服务地址
|
|
162
|
+
credential: { /* 见「快速开始」四种方式 */ },
|
|
163
|
+
fetch: myFetch, // 可选:自定义请求实现(React Native、测试、代理场景)
|
|
164
|
+
timeoutMs: 10000, // 单个请求的超时时间
|
|
165
|
+
retries: 0, // 列表、详情这类查询请求失败时自动重试几次(只重试查询,不重试播放)
|
|
166
|
+
jwtRefreshLeewaySec: 300, // 登录凭证到期前多久自动重新登录
|
|
167
|
+
refreshLeewaySec: 300, // 播放地址到期前多久自动换新
|
|
168
|
+
autoRefresh: true, // 设为 false 则不自动换新,只能手动调 handle.refresh()
|
|
169
|
+
storage: myStorage, // 可选:把登录凭证存起来(默认只存在内存里,关页面就没了)
|
|
170
|
+
onEvent: (e) => {}, // 可选:监听所有事件,等价于 sdk.on(listener)
|
|
171
|
+
});
|
|
172
|
+
```
|
|
244
173
|
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
174
|
+
关于 `storage` 的安全提醒:**不建议用 `localStorage` 存登录凭证**。
|
|
175
|
+
浏览器里用内存或 `sessionStorage`,App 里用系统安全存储(iOS Keychain / Android Keystore)。
|
|
176
|
+
|
|
177
|
+
## 事件
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
// 监听单个事件,返回的函数用来取消监听
|
|
181
|
+
const off = sdk.on("playback:refreshed", (e) => {});
|
|
182
|
+
off();
|
|
183
|
+
|
|
184
|
+
// 或者监听全部事件
|
|
185
|
+
const offAll = sdk.on((event) => console.log(event.type, event));
|
|
186
|
+
offAll();
|
|
250
187
|
```
|
|
251
188
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
189
|
+
| 事件 | 什么时候发生 |
|
|
190
|
+
|---|---|
|
|
191
|
+
| `playback:refreshed` | 播放地址快过期,SDK 自动换了新地址(你需要换源) |
|
|
192
|
+
| `playback:template_changed` | 切换清晰度成功(你需要换源) |
|
|
193
|
+
| `auth:changed` | 登录状态变了,比如凭证过期、账号被禁 |
|
|
194
|
+
| `error` | 出错了,`e.operation` 会告诉你是哪一步出的问题 |
|
|
257
195
|
|
|
258
|
-
##
|
|
196
|
+
## 错误处理
|
|
259
197
|
|
|
260
|
-
```
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
198
|
+
```ts
|
|
199
|
+
import { DeliveryError, PlayerSdkError } from "openvod-jssdk";
|
|
200
|
+
|
|
201
|
+
try {
|
|
202
|
+
await sdk.play(mediaId);
|
|
203
|
+
} catch (e) {
|
|
204
|
+
if (e instanceof DeliveryError) {
|
|
205
|
+
e.code; // 服务端返回的错误码,如 "session_limit"
|
|
206
|
+
e.status; // HTTP 状态码;0 表示网络不通、超时或请求被取消
|
|
207
|
+
e.message; // 服务端返回的原始错误说明
|
|
208
|
+
e.hint; // SDK 附带的排查建议
|
|
209
|
+
} else if (e instanceof PlayerSdkError) {
|
|
210
|
+
e.code; // SDK 自己的问题,如配置不对、没配登录方式、SDK 已销毁
|
|
211
|
+
}
|
|
212
|
+
}
|
|
265
213
|
```
|
|
266
214
|
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
215
|
+
常见错误:
|
|
216
|
+
|
|
217
|
+
| 错误 | 意思 | 怎么办 |
|
|
218
|
+
|---|---|---|
|
|
219
|
+
| `internal` + status 0 | 连不上服务,或服务没开 CORS | 见下方「常见问题」 |
|
|
220
|
+
| `unauthorized` | 账号被禁或密码改了 | 引导用户重新登录 |
|
|
221
|
+
| `session_limit` | 这个账号同时播放的设备数到上限了 | 等旧会话过期,或在管理台调大上限 |
|
|
222
|
+
| `not_playable` | 媒资还没转码完,或所选清晰度没有产物 | 回列表刷新,或换个清晰度 |
|
|
223
|
+
| 播放器里 403 | 播放地址里的签名过期了 | 调 `handle.refresh({ force: true })` 后换源 |
|
|
224
|
+
|
|
225
|
+
## 常见问题
|
|
226
|
+
|
|
227
|
+
**列表页报错,什么都出不来?**
|
|
228
|
+
1. 先确认服务能访问:浏览器打开 `<baseUrl>/healthz`。
|
|
229
|
+
2. 如果是网页直连,确认服务端的 CORS 配置里加了你网站的域名。
|
|
230
|
+
|
|
231
|
+
**列表能出来,点进去播放黑屏?**
|
|
232
|
+
1. 检查播放地址是否过期(`handle.expires_at`)。
|
|
233
|
+
2. 视频文件是从对象存储直接拉取的,确认对象存储的 CORS 配置放行了你的域名。
|
|
234
|
+
3. 确认这个媒资的转码产物是完整的(去管理台看产物列表)。
|
|
235
|
+
|
|
236
|
+
**播到一半突然失败?**
|
|
237
|
+
多半是签名过期了,参考上文「播放器里出现 403 时」手动重签。
|
|
238
|
+
|
|
239
|
+
**React 里改了清晰度但界面没变?**
|
|
240
|
+
`handle` 里的字段会被 SDK 原地更新,但 React 检测不到这种变化。
|
|
241
|
+
切换后自己读一遍 `handle` 的最新字段、存成新的 state 就好。
|
|
242
|
+
|
|
243
|
+
## 用完记得清理
|
|
244
|
+
|
|
245
|
+
```ts
|
|
246
|
+
handle.dispose(); // 停止这个播放的自动续签(服务端会话会自己过期)
|
|
247
|
+
sdk.dispose(); // 清掉 SDK 的全部定时器和缓存,之后所有调用都会报错
|
|
248
|
+
```
|