openvod-jssdk 0.0.0-stage → 1.1.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/LICENSE +203 -0
- package/README.md +274 -2
- package/dist/index.cjs +1209 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +278 -0
- package/dist/index.d.ts +278 -0
- package/dist/index.js +1202 -0
- package/dist/index.js.map +1 -0
- package/package.json +44 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 上海绫中信息技术有限公司 (Shanghai Lingzhong Information Technology Co., Ltd.)
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
|
202
|
+
|
|
203
|
+
Copyright 2026 上海绫中信息技术有限公司 (Shanghai Lingzhong Information Technology Co., Ltd.)
|
package/README.md
CHANGED
|
@@ -1,3 +1,275 @@
|
|
|
1
|
-
#
|
|
1
|
+
# openvod-jssdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
OpenVOD 播放器接入 SDK(v1):把「登录 → 媒资 → 播放会话 → 签名 URL → 续签 → 换清晰度」的接入逻辑收敛为唯一公共 API,
|
|
4
|
+
宿主只负责播放器元素与 UI。**零运行时依赖**(仅 `fetch`,可注入),浏览器 / Node 18+ / React Native 同一份实现。
|
|
5
|
+
|
|
6
|
+
权威设计:`docs/vod/player-sdk-intent.md`(定位与范围)、`docs/vod/player-sdk-spec.md`(接口与语义)。
|
|
7
|
+
接口参考:`docs/vod/api.md §2`(分发端 HTTP API)。首个消费方:`apps/player`。
|
|
8
|
+
|
|
9
|
+
## 安装
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
# npm 官方
|
|
13
|
+
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
|
+
```
|
|
22
|
+
|
|
23
|
+
发布产物为 **ESM + CJS + 打包后的 `.d.ts`**,零运行时依赖(连 `@openvod/*` 私有包也不需要——公共 DTO 类型
|
|
24
|
+
在 `src/types.ts` 是自包含镜像,一致性由 `bun run typecheck` 的编译期断言守住)。
|
|
25
|
+
|
|
26
|
+
## 设计边界(不变量)
|
|
27
|
+
|
|
28
|
+
| 编号 | 不变量 |
|
|
29
|
+
|---|---|
|
|
30
|
+
| N1 | SDK **永不接触视频字节与密钥材料**:不请求 `/key`、不下载分片、不持有 CEK(解密在播放器 / 浏览器本地完成) |
|
|
31
|
+
| N2 | 全部签名 URL **一律来自 `play` 响应原样透出**,SDK 不生成 / 不校验 / 不拼接 |
|
|
32
|
+
| N3 | 业务语义以服务端为准:`limit` 回退、模板自动选择、会话复用、`expires_at` 判定都不在客户端复制 |
|
|
33
|
+
| N4 | **错误保真**:服务端错误码 / 文案 / HTTP 状态原样透出,SDK 只附加 `hint` 排查建议 |
|
|
34
|
+
| N5 | 重登一律经配置的凭据源重新 `login`(v1 无 refresh token) |
|
|
35
|
+
|
|
36
|
+
## 快速开始
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
import { createPlayerSdk } from "openvod-jssdk";
|
|
40
|
+
|
|
41
|
+
// ① 口令模式(SDK 负责 login / JWT 缓存 / 到期重登)
|
|
42
|
+
const sdk = createPlayerSdk({
|
|
43
|
+
baseUrl: "https://vod.example.com", // delivery 基址(http/https,自动去尾斜杠)
|
|
44
|
+
credential: { mode: "password", username: "viewer", password: "******" },
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
// ② tokenProvider 模式(宿主自治登录,推荐 Web 宿主经自己的后端换 JWT,口令不下发浏览器)
|
|
48
|
+
const sdk2 = createPlayerSdk({
|
|
49
|
+
baseUrl: "https://vod.example.com",
|
|
50
|
+
credential: {
|
|
51
|
+
mode: "tokenProvider",
|
|
52
|
+
getToken: async () => {
|
|
53
|
+
const res = await fetch("/api/session"); // 宿主的后端路由
|
|
54
|
+
const body = await res.json();
|
|
55
|
+
return { access_token: body.access_token, expires_at: body.expires_at };
|
|
56
|
+
},
|
|
57
|
+
},
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
// ③ static 模式(宿主已有 JWT 且自行负责续期):无重登能力,过期即抛错 + auth:changed{expired}
|
|
61
|
+
const sdk3 = createPlayerSdk({
|
|
62
|
+
baseUrl: "https://vod.example.com",
|
|
63
|
+
credential: { mode: "static", token: jwtFromHost, expires_at: "2026-10-17T08:00:00Z" }, // expires_at 可省(缺省缓存至 401)
|
|
64
|
+
});
|
|
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
|
+
```
|
|
70
|
+
|
|
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
|
+
```
|
|
87
|
+
|
|
88
|
+
### 从列表到播放(完整生命周期)
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
const page = await sdk.listMedia({ limit: 50 }); // 仅 READY 媒资;next_cursor v1 恒 null
|
|
92
|
+
const detail = await sdk.getMedia("55395830"); // probe / poster / custom(公开白名单)
|
|
93
|
+
const custom = parseCustomMetadata(detail.custom); // { category?, description?, tags? }(脏数据容错)
|
|
94
|
+
|
|
95
|
+
const handle = await sdk.play("55395830"); // 建 / 复用播放会话,签发签名主清单 URL
|
|
96
|
+
video.src = handle.manifest_url; // 清单 → 密钥 → 分片全链路已带签名
|
|
97
|
+
|
|
98
|
+
// 清晰度:handle.templates 是「该媒资实际存在的模板产物」,不是全部模板
|
|
99
|
+
const options = handle.templates.map((t) => ({ label: templateLabel(t), value: t.id }));
|
|
100
|
+
await handle.switchTemplate("ctemplate00000000000002"); // 复用会话换源;返回值仍是同一 handle
|
|
101
|
+
video.src = handle.manifest_url; // 换源后读最新字段(见下方「可变视图」)
|
|
102
|
+
|
|
103
|
+
// 字幕:URL 是 typ=v 签名地址;403 时 SDK 自动重签一次
|
|
104
|
+
const tracks = handle.subtitles;
|
|
105
|
+
const vtt = await handle.fetchSubtitleText(tracks[0]);
|
|
106
|
+
|
|
107
|
+
// 播放中 token 到期:SDK 自动重签并通知宿主换源
|
|
108
|
+
const off = sdk.on("playback:refreshed", (event) => {
|
|
109
|
+
video.src = event.manifest_url; // 事件 payload 与字段逐字一致
|
|
110
|
+
});
|
|
111
|
+
|
|
112
|
+
handle.dispose(); // 停自动续签 + 本地失效(不释放服务端会话)
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### 变更订阅与生命周期
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
const off = sdk.on((event) => console.log(event.type, event)); // 全量订阅
|
|
119
|
+
sdk.on("playback:template_changed", (e) => {/* 切清晰度成功 */});
|
|
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)
|
|
125
|
+
|
|
126
|
+
| 调用 | 说明 |
|
|
127
|
+
|---|---|
|
|
128
|
+
| `sdk.auth.getAccessToken({ force? })` | 取有效 JWT(缓存命中零请求;到期前按 leeway 重登;401 兜底强制重登) |
|
|
129
|
+
| `sdk.auth.setCredential(source \| null)` | 运行时切换身份:清 token / 会话缓存 / 定时器,旧句柄全部 `disposed` |
|
|
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)`) |
|
|
155
|
+
|
|
156
|
+
## 错误处理
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
import { DeliveryError, PlayerSdkError, describeError } from "openvod-jssdk";
|
|
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
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
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
|
+
## 两段必备的宿主代码
|
|
186
|
+
|
|
187
|
+
### 换源保留进度(自动续签 / 切清晰度通用)
|
|
188
|
+
|
|
189
|
+
`switchTemplate` / `refresh` 会换掉 `manifest_url`(新 token),播放器换源后应恢复进度:
|
|
190
|
+
|
|
191
|
+
```ts
|
|
192
|
+
let resume: { time: number; wasPlaying: boolean } | null = null;
|
|
193
|
+
|
|
194
|
+
sdk.on("playback:refreshed", (event) => {
|
|
195
|
+
resume = { time: video.currentTime, wasPlaying: !video.paused };
|
|
196
|
+
video.src = event.manifest_url; // 换源(hls.js 需 destroy + attachMedia 重建)
|
|
197
|
+
});
|
|
198
|
+
|
|
199
|
+
video.addEventListener("loadedmetadata", () => {
|
|
200
|
+
if (!resume) return;
|
|
201
|
+
video.currentTime = resume.time; // 恢复失败请静默从头,不要抛给用户
|
|
202
|
+
if (resume.wasPlaying) void video.play().catch(() => {});
|
|
203
|
+
resume = null;
|
|
204
|
+
});
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### 播放器内 403 处置(清单 / 密钥 / 分片)
|
|
208
|
+
|
|
209
|
+
浏览器原生 HLS 与 hls.js 的分片 / 密钥请求 SDK 无法感知(SDK 不接触视频字节,N1)。播放器报错或长时间
|
|
210
|
+
黑屏时,用它换一套新 token 再重载:
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
async function recoverPlayback(errorCode?: number) {
|
|
214
|
+
if (errorCode !== 403) return; // 只在 403 bad_token 场景重签
|
|
215
|
+
await handle.refresh({ force: true }); // 复用会话重签(不新建会话、不消耗并发额度)
|
|
216
|
+
video.src = handle.manifest_url; // 再换源;必要时 resume 进度
|
|
217
|
+
}
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
## 排错清单
|
|
221
|
+
|
|
222
|
+
| 现象 | 排查顺序 |
|
|
223
|
+
|---|---|
|
|
224
|
+
| 列表页报 `internal / status 0` | ① 分发端是否启动:`curl <baseUrl>/healthz`;② 宿主源站是否在 `DELIVERY_CORS_ORIGINS`;③ 浏览器直连地址是否可达(运行时 `delivery_base` 是否正确) |
|
|
225
|
+
| 列表能出、点进播放黑屏 | ① token 是否过期(`handle.expires_at`);② 桶(COS / RustFS)是否放行宿主源站 CORS(分片直连对象存储);③ 产物是否完整(管理端产物列表) |
|
|
226
|
+
| 播到一半 403 / 后段失败 | token 与分片预签名过期:调大 `refreshLeewaySec` 观察自动重签,或按上文「播放器内 403 处置」手动重签 |
|
|
227
|
+
| `session_limit`(409) | 同账号并发会话达上限(`forceNew` **不绕过**):等 TTL 过期或管理端调大 `max_concurrent_sessions` |
|
|
228
|
+
| `not_playable`(409) | 媒资未就绪或所选模板无产物:回列表,或从 `handle.templates` 重选 |
|
|
229
|
+
| `auth:changed{expired}` | 账号被禁 / 口令已变:`setCredential()` 换凭据,或引导重新登录 |
|
|
230
|
+
| React 视图不更新 | `handle` 是可变视图:`switchTemplate` / `refresh` 后需重读字段重建快照(见「换源保留进度」) |
|
|
231
|
+
|
|
232
|
+
## 已知约束与宿主职责
|
|
233
|
+
|
|
234
|
+
- **`PlaybackHandle` 是可变视图**:`switchTemplate` / `refresh` 原位更新并返回**同一实例**。React 用快照驱动渲染
|
|
235
|
+
(参考 `apps/player/src/components/PlayView.tsx` 的 `snapshot(handle)`),不要靠引用比较触发重渲染。
|
|
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
|
+
## 开发
|
|
244
|
+
|
|
245
|
+
```bash
|
|
246
|
+
bun test packages/player-sdk # 单测矩阵(注入 fetch + 假时钟,无真实网络)
|
|
247
|
+
bun run --cwd packages/player-sdk test:coverage # 同上 + 覆盖率(text + coverage/lcov.info)
|
|
248
|
+
bun run --cwd packages/player-sdk typecheck # tsc(含契约镜像的编译期一致性断言)
|
|
249
|
+
bun run --cwd packages/player-sdk build # tsup → dist/{index.js,index.cjs,index.d.ts}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
- 源码:`src/{index,config,client,auth,media,playback,subtitles,events,errors,types}.ts`
|
|
253
|
+
- `src/types.ts` 是公共 DTO 的**自包含镜像**(发布包零依赖,声明文件不得出现私有包 import);
|
|
254
|
+
与 `packages/contracts` 的一致性由 `test/contract-parity.ts`(编译期,随 `typecheck`)+ `test/errors.test.ts`
|
|
255
|
+
(运行时逐字比对 ERROR_CODES)守住。
|
|
256
|
+
- 新增能力必须同步:`docs/vod/player-sdk-spec.md`(接口语义)→ 单测(T 编号)→ 本 README。
|
|
257
|
+
|
|
258
|
+
## 发布(npm 官方 + CNB 制品库)
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
bun run --cwd packages/player-sdk publish:dry # 演练:构建 + 打包清单(不联网、无需令牌)
|
|
262
|
+
bun run --cwd packages/player-sdk publish:npm # 只发 npm 官方
|
|
263
|
+
bun run --cwd packages/player-sdk publish:cnb # 只发 CNB 制品库
|
|
264
|
+
bun run --cwd packages/player-sdk publish:both # 两个都发(= 发版流水线用的命令)
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
- **版本号唯一真源是根 `package.json` 的 `version`**(本包刻意不声明 `version`,仓库守卫见
|
|
268
|
+
`apps/admin/test/version-source.test.ts`);脚本读它并注入发布清单,`--version` 可显式覆盖(补发历史版本)。
|
|
269
|
+
- 发布清单在 `.run/sdk-publish/` 暂存生成:`exports` 指向 `dist/`(仓库内仍指向 `src/`,供 workspace 直引);
|
|
270
|
+
脚本还会断言产物自包含(4 个产物文件不得 import 私有包)。
|
|
271
|
+
- 令牌只经环境变量传入、临时 `.npmrc` 权限 600 且用后即删:`NPM_TOKEN`(npm 官方)、
|
|
272
|
+
`CNB_NPM_TOKEN`(CNB,流水线内缺省回退内置 `CNB_TOKEN`)、`CNB_NPM_REGISTRY`(制品库地址)。
|
|
273
|
+
- **CI**:`.cnb.yml` 的 `.publish-sdk` 任务在 **`tag_push`** 时自动执行(也可用仓库页「发布播放器SDK」按钮手动触发):
|
|
274
|
+
单测覆盖率 → `testing:coverage` 上报 CNB 洞察/徽章(红线 95%)→ 发布到两个制品库;
|
|
275
|
+
`NPM_TOKEN` 经密钥仓库 `arsrna/env` 的 `npm.yml` 注入。tag 名与根版本不一致时脚本会拒绝发布。
|