@meshstream/docs-mcp 0.0.0-stage → 0.2.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 +25 -2
- package/content/ai-coding.md +161 -0
- package/content/api/bootstrap.md +67 -0
- package/content/api/errors.md +34 -0
- package/content/best-practices.md +145 -0
- package/content/billing/usage.md +38 -0
- package/content/concepts/identity.md +23 -0
- package/content/concepts/multi-region.md +15 -0
- package/content/concepts/p2p.md +79 -0
- package/content/concepts/statistics.md +52 -0
- package/content/intro.md +54 -0
- package/content/legal/privacy.md +110 -0
- package/content/legal/terms.md +173 -0
- package/content/quickstart.md +198 -0
- package/content/sdk/android-advanced.md +228 -0
- package/content/sdk/android-setup.md +139 -0
- package/content/sdk/android.md +190 -0
- package/content/sdk/flutter-advanced.md +285 -0
- package/content/sdk/flutter-setup.md +123 -0
- package/content/sdk/flutter.md +91 -0
- package/content/sdk/ios-advanced.md +268 -0
- package/content/sdk/ios-setup.md +113 -0
- package/content/sdk/ios.md +156 -0
- package/content/sdk/overview.md +40 -0
- package/content/sdk/react-native-advanced.md +269 -0
- package/content/sdk/react-native-setup.md +86 -0
- package/content/sdk/react-native.md +52 -0
- package/content/sdk/uniapp-advanced.md +274 -0
- package/content/sdk/uniapp-setup.md +92 -0
- package/content/sdk/uniapp.md +55 -0
- package/content/sdk/web-advanced.md +241 -0
- package/content/sdk/web-setup.md +42 -0
- package/content/sdk/web.md +105 -0
- package/content/sdk/windows-advanced.md +237 -0
- package/content/sdk/windows-setup.md +53 -0
- package/content/sdk/windows.md +162 -0
- package/content/troubleshooting.md +122 -0
- package/package.json +31 -4
- package/src/catalog.mjs +249 -0
- package/src/server.mjs +74 -0
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: React Native SDK 高级用法
|
|
3
|
+
sidebar_label: 高级用法
|
|
4
|
+
description: "React Native SDK 高级用法:直播点播、MP4/MP3、源站鉴权、预加载、运行时控制、监控与生命周期。"
|
|
5
|
+
pagination_label: "React Native SDK 高级用法"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# React Native SDK 高级用法
|
|
9
|
+
|
|
10
|
+
本页按原生 SDK 的接入场景组织:直播/点播、文件直链、每路配置、预加载、运行时控制、监控与平台策略。示例复用[快速接入](./react-native.md)创建的 client,播放器变量由业务应用持有。
|
|
11
|
+
|
|
12
|
+
## 直播与点播接入策略
|
|
13
|
+
|
|
14
|
+
SDK 自动识别直播/点播,[基础接入方式相同](./react-native.md)。播放期间可回传播放器状态,帮助 P2P 调度;不回传也可正常播放。
|
|
15
|
+
|
|
16
|
+
### 直播
|
|
17
|
+
|
|
18
|
+
<span id="直播回传缓冲余量" />
|
|
19
|
+
|
|
20
|
+
<span id="缓冲反馈" />
|
|
21
|
+
|
|
22
|
+
回传当前位置之后连续可播放的缓冲时长,帮助 SDK 调整 P2P 预取。例如播放到 60 秒、缓冲到 70 秒,应传 **10,000 毫秒**。直播起播位置与目标延迟由播放器设置。
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
await session.updateBufferedDurationMs(bufferedDurationMs);
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### 点播(VOD)
|
|
29
|
+
|
|
30
|
+
<span id="点播另外回传播放位置" />
|
|
31
|
+
|
|
32
|
+
<span id="播放进度与缓冲反馈" />
|
|
33
|
+
|
|
34
|
+
除缓冲时长外,回传当前播放位置,帮助 SDK 在已连接且拥有目标分片的 Peer 中优先选择进度接近的节点。Seek 完成后立即更新位置。
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
await session.updateCurrentPositionMs(positionMs);
|
|
38
|
+
await session.updateBufferedDurationMs(bufferedDurationMs);
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
数值均为非负毫秒,缓冲时长不能跨越断档。播放器状态有效后通常每秒回传一次;关闭会话前停止回传并等待在途调用结束。
|
|
42
|
+
|
|
43
|
+
<span id="播放器状态回传" />
|
|
44
|
+
|
|
45
|
+
<span id="播放位置与连续缓冲" />
|
|
46
|
+
|
|
47
|
+
<span id="播放器状态同步" />
|
|
48
|
+
|
|
49
|
+
<span id="接入示例" />
|
|
50
|
+
|
|
51
|
+
<span id="播放器状态回传示例" />
|
|
52
|
+
|
|
53
|
+
<details>
|
|
54
|
+
<summary>完整播放器状态回传示例</summary>
|
|
55
|
+
|
|
56
|
+
将播放器回调转换为下面的毫秒输入;异步回传应串行执行,并处理桥接调用异常。
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
async function syncPlaybackState(
|
|
60
|
+
positionMs: number, bufferedDurationMs: number, isLive: boolean,
|
|
61
|
+
) {
|
|
62
|
+
if (!isLive && Number.isFinite(positionMs) && positionMs >= 0) {
|
|
63
|
+
await session.updateCurrentPositionMs(positionMs);
|
|
64
|
+
}
|
|
65
|
+
if (Number.isFinite(bufferedDurationMs) && bufferedDurationMs >= 0) {
|
|
66
|
+
await session.updateBufferedDurationMs(bufferedDurationMs);
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
</details>
|
|
72
|
+
|
|
73
|
+
## MP4 / MP3 直链播放
|
|
74
|
+
|
|
75
|
+
MP4 与 MP3 使用文件直链。为同一内容设置稳定的 `contentId`;地址没有扩展名时显式指定 `mimeType`:
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
const session = await client.createPlaybackSession({
|
|
79
|
+
url: 'https://cdn.example.com/video/trailer.mp4',
|
|
80
|
+
contentId: 'trailer-2026',
|
|
81
|
+
mimeType: 'mp4',
|
|
82
|
+
});
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
将 `session.playbackUrl` 交给支持该格式的播放器。MP3 只需替换媒体地址并将类型设为 `mp3`。文件加速要求源站支持单区间 HTTP Range 请求,并返回有效的 `Content-Range`;不满足条件时不启用 P2P 加速,实际播放与拖动结果仍取决于源站和播放器。SDK 不负责解码,也不绕过 DRM。
|
|
86
|
+
|
|
87
|
+
## 每路播放配置与源站鉴权
|
|
88
|
+
|
|
89
|
+
<span id="动态地址与源站请求头" />
|
|
90
|
+
|
|
91
|
+
客户端配置用于创建 client,每个媒体资源的参数在创建 session 时单独传入:
|
|
92
|
+
|
|
93
|
+
| 层级 | 参数 | 用途 |
|
|
94
|
+
| --- | --- | --- |
|
|
95
|
+
| Client | `key` | 对应应用和平台的 SDK Key |
|
|
96
|
+
| Client | `p2pEnabled` | 初始 P2P 意愿,仍受控制台策略约束 |
|
|
97
|
+
| Session | `url` | 必填的原始媒体地址 |
|
|
98
|
+
| Session | `contentId` | 同一内容的稳定标识 |
|
|
99
|
+
| Session | `mimeType` | `m3u8`、`mpd`、`mp4` 或 `mp3` |
|
|
100
|
+
| Session | `originHeaders` | 仅发给媒体源的请求头 |
|
|
101
|
+
|
|
102
|
+
对带短期签名的地址传入稳定 `contentId`。没有扩展名时填写 `mimeType`;源站鉴权头通过 `originHeaders` 传入:
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
const session = await client.createPlaybackSession({
|
|
106
|
+
url: signedUrl,
|
|
107
|
+
contentId: 'movie-2026-001',
|
|
108
|
+
mimeType: 'mp4',
|
|
109
|
+
originHeaders: { Authorization: `Bearer ${originToken}` },
|
|
110
|
+
});
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
这些请求头只用于源站请求,不会发送到 Peer。签名续期由业务层负责,续期后继续使用同一个 `contentId`;不要把 SDK Key、源站 Token 或完整签名 URL 写入日志。
|
|
114
|
+
|
|
115
|
+
## 预加载与内容切换
|
|
116
|
+
|
|
117
|
+
<span id="多会话与预加载" />
|
|
118
|
+
|
|
119
|
+
显式 `preload` 是可选的 HLS/DASH 预热:后台获取清单与首个媒体分片,不会下载整部视频。它也可提前启动 Tracker/Peer 连接,但排队成功不保证 Peer 已连接或媒体已就绪。尚未播放的候选会话不会向 Peer 上传媒体。MP4/MP3 直链不使用这条显式预加载流程。
|
|
120
|
+
|
|
121
|
+
保存候选会话,选中时复用其播放地址。关闭任一会话前,先停止状态回传、等待在途调用结束并取消其事件订阅,避免回调访问已关闭的会话。预加载不负责解码器准备,也不会渲染首帧。
|
|
122
|
+
|
|
123
|
+
每个播放器使用独立的 session。列表预览可以提前创建下一条会话:
|
|
124
|
+
|
|
125
|
+
### 准备候选内容
|
|
126
|
+
|
|
127
|
+
```ts
|
|
128
|
+
const next = await client.createPlaybackSession({
|
|
129
|
+
url: nextItem.url,
|
|
130
|
+
contentId: nextItem.id,
|
|
131
|
+
mimeType: 'm3u8',
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
const queued = await next.preload();
|
|
135
|
+
if (queued) {
|
|
136
|
+
// 只有真正切换时才把 next.playbackUrl 交给播放器。
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
`preload()` 返回 `true` 只表示预热已排队,不代表首帧已经出图。候选内容不再需要时及时关闭 session,避免连接长期占用。
|
|
141
|
+
|
|
142
|
+
### 切换至候选内容
|
|
143
|
+
|
|
144
|
+
真正切换时,先从播放器解除旧媒体引用并关闭旧会话,再使用 `next.playbackUrl`,把 `next` 保留为当前会话。预加载不会驱动播放器,排队成功也不代表 Peer 已就绪;预热可能产生网络流量。
|
|
145
|
+
|
|
146
|
+
### 取消候选内容
|
|
147
|
+
|
|
148
|
+
若取消候选内容,则关闭它:
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
await next.close();
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## 运行时控制
|
|
155
|
+
|
|
156
|
+
<span id="p2p-开关与-cdn-回退" />
|
|
157
|
+
|
|
158
|
+
### P2P 开关
|
|
159
|
+
|
|
160
|
+
灰度或排障时可以只关闭当前会话的 P2P:
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
await session.setP2pEnabled(false);
|
|
164
|
+
// 播放器继续使用 session.playbackUrl。
|
|
165
|
+
await session.setP2pEnabled(true);
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
P2P、Tracker 或配置不可用时,继续播放 `session.playbackUrl`。不要因为 Peer 数为零、收到 `p2pUnavailable` 或单次请求回源就替换 URL 或停止播放器。
|
|
169
|
+
|
|
170
|
+
## 事件与监控
|
|
171
|
+
|
|
172
|
+
<span id="事件状态与诊断" />
|
|
173
|
+
|
|
174
|
+
<span id="版本与兼容性诊断" />
|
|
175
|
+
|
|
176
|
+
同时按 `clientId` 和 `sessionId` 过滤事件,并在关闭会话前移除订阅:
|
|
177
|
+
|
|
178
|
+
```ts
|
|
179
|
+
const subscription = addMeshStreamEventListener((event) => {
|
|
180
|
+
if (event.type === 'p2pUnavailable') {
|
|
181
|
+
console.info('P2P unavailable:', event.reason);
|
|
182
|
+
}
|
|
183
|
+
if (event.type === 'statistics') {
|
|
184
|
+
console.info('peers=', event.statistics?.connectedPeers);
|
|
185
|
+
}
|
|
186
|
+
}, { clientId: client.clientId, sessionId: session.sessionId });
|
|
187
|
+
|
|
188
|
+
const status = await client.getStatus();
|
|
189
|
+
const stats = await session.getStats();
|
|
190
|
+
const diagnostics = await session.getDiagnostics();
|
|
191
|
+
|
|
192
|
+
subscription.remove();
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
可用事件包括 `peerCountChanged`、`playbackPrepared`、`p2pReady`、`p2pUnavailable`、`statistics`、`cdnFallback`、`trackerError` 和 `peerConnectError`。`cdnFallback` 是某次请求回源的统计,不代表整个会话切换成 CDN。
|
|
196
|
+
|
|
197
|
+
| 字段 | 含义 |
|
|
198
|
+
| --- | --- |
|
|
199
|
+
| `httpDownloaded` | HTTP/CDN 下载字节 |
|
|
200
|
+
| `p2pDownloaded` | 从 Peer 获取的字节 |
|
|
201
|
+
| `p2pUploaded` | 向 Peer 分享的字节 |
|
|
202
|
+
| `connectedPeers` | 当前已连接 Peer 数量 |
|
|
203
|
+
| `downloadOffloadRatio` | P2P 下载字节 / HTTP 与 P2P 总下载字节,范围 0–1 |
|
|
204
|
+
|
|
205
|
+
百分比展示时将 `downloadOffloadRatio` 乘以 100;它是下载分流比例,不是上传分享比例。尚无下载数据时为零,不能仅凭有 Peer 或单次 CDN 回退判断分流效果。通过 `getDiagnostics()` 查看连接耗时和错误信息;可选字段可能为空。
|
|
206
|
+
|
|
207
|
+
### 版本诊断
|
|
208
|
+
|
|
209
|
+
提交问题时记录 JavaScript 包版本、原生 SDK 版本和平台:
|
|
210
|
+
|
|
211
|
+
```ts
|
|
212
|
+
const version = await MeshStream.getVersion();
|
|
213
|
+
// { packageVersion, nativeSdkVersion, platform }
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
<span id="接入验证" />
|
|
217
|
+
|
|
218
|
+
<details>
|
|
219
|
+
<summary>验证 P2P 效果</summary>
|
|
220
|
+
|
|
221
|
+
1. 先用单设备确认正常播放、点播拖动,以及关闭 P2P 后仍能播放。
|
|
222
|
+
2. 用两个设备播放同一内容,保持 `contentId` 一致;点播选择有重叠的播放进度,直播选择同一频道。媒体字节和时间轴应保持一致,不同资产或个性化清单不要复用同一个 ID。
|
|
223
|
+
3. 检查回传单位为毫秒,并在媒体清单加载后持续更新。当前位置 60 秒、连续缓冲到 70 秒时,缓冲值应为 10,000 毫秒;点播 Seek 完成后立即更新位置。
|
|
224
|
+
4. 在一段播放时间内观察 P2P 下载字节数与下载分担率的变化。仅有 Peer 连接不代表实际通过 P2P 下载了媒体;分片可用性、网络环境和平台策略都会影响结果。
|
|
225
|
+
5. 关闭 P2P,确认播放器继续通过 CDN 播放。随后停止状态回传并取消事件订阅,再关闭会话,确认切换内容后没有继续调用已关闭的会话。
|
|
226
|
+
|
|
227
|
+
</details>
|
|
228
|
+
|
|
229
|
+
## 网络与平台策略
|
|
230
|
+
|
|
231
|
+
Wi-Fi、蜂窝网络、以太网、账户权限与额度由原生 SDK 和控制台策略共同判断,本地 P2P 开关不能覆盖服务端限制。不要向客户端传入 `region`、`areaCode` 或 Tracker/ICE 地址。通过 `getStatus()` 查看 `effectiveP2pEnabled` 与 `reason`;单纯 Peer 数为零不代表播放异常。
|
|
232
|
+
|
|
233
|
+
SDK 播放地址使用 HTTP 回环代理,即使媒体源是 HTTPS 也需要完成 [Android/iOS 网络配置](./react-native-setup.md),并确保 Release 包同样生效。已有网络策略时合并必要例外;公网 HTTP 媒体源仅放行所需域名,优先使用 HTTPS。
|
|
234
|
+
|
|
235
|
+
## 生命周期与后台播放
|
|
236
|
+
|
|
237
|
+
<span id="生命周期顺序" />
|
|
238
|
+
|
|
239
|
+
切换内容或销毁播放页面时:
|
|
240
|
+
|
|
241
|
+
1. 停止状态回传,等待在途回传结束,并取消事件订阅。
|
|
242
|
+
2. 停止播放器并解除当前媒体引用。
|
|
243
|
+
3. 关闭当前 session 及不再需要的预加载候选会话。
|
|
244
|
+
4. 只有其他活动会话都不再需要 client 时,才关闭 client。
|
|
245
|
+
|
|
246
|
+
后台或画中画仍在播放时,保留对应播放器和会话,由宿主应用配置后台模式、音频会话与播放器能力。页面离开是否释放资源需遵循业务播放策略,不能直接关闭仍在后台播放的会话。SDK 不绕过操作系统限制,也不保证后台持续分享。
|
|
247
|
+
|
|
248
|
+
```ts
|
|
249
|
+
await session.close();
|
|
250
|
+
await client.close();
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
## 能力边界
|
|
254
|
+
|
|
255
|
+
以下为当前 React Native 封装的公共 API 范围;以本页公开参数为准,不要直接传入仅原生 SDK 支持的字段:
|
|
256
|
+
|
|
257
|
+
| 能力 | 当前封装入口 |
|
|
258
|
+
| --- | --- |
|
|
259
|
+
| HLS / DASH / MP4 / MP3、源站请求头、稳定内容标识 | 通过会话参数使用 |
|
|
260
|
+
| 多会话、预加载、P2P 开关、状态回传、统计 | 使用本页对应方法 |
|
|
261
|
+
| `maxMemoryBytes`、Peer 连接上限、请求超时、原生日志级别 | 当前未开放对应公共配置项 |
|
|
262
|
+
| Apple `setPictureInPictureActive` | 当前未开放对应桥接方法;播放器支持画中画不等于封装已提供此接口 |
|
|
263
|
+
| 解码、ABR、DRM、播放器缓存、系统后台权限 | 由播放器与应用管理 |
|
|
264
|
+
|
|
265
|
+
P2P 不可用不等于媒体不可播放。会话有效时继续使用其播放地址,是否重试或终止由播放器错误及源站响应决定;原生初始化或桥接调用失败仍需由应用处理。
|
|
266
|
+
|
|
267
|
+
## 相关文档
|
|
268
|
+
|
|
269
|
+
[安装与配置](./react-native-setup.md) · [快速接入](./react-native.md) · [故障排查](../troubleshooting.md)
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: React Native SDK 安装与配置
|
|
3
|
+
sidebar_label: 安装与配置
|
|
4
|
+
description: "React Native SDK 安装与配置指南:平台要求、依赖安装和应用设置。"
|
|
5
|
+
pagination_label: "React Native SDK 安装与配置"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# React Native SDK 安装与配置
|
|
9
|
+
|
|
10
|
+
当前 npm 包版本为 `react-native-meshstream 1.0.6`,发布于 [npm](https://www.npmjs.com/package/react-native-meshstream/v/1.0.6)。它提供统一的 JavaScript client/session API,播放器仍由应用管理。
|
|
11
|
+
|
|
12
|
+
## 接入准备
|
|
13
|
+
|
|
14
|
+
- React Native 0.72+;
|
|
15
|
+
- 控制台创建的 React Native 应用 SDK Key;
|
|
16
|
+
- 一个可播放的 HLS `.m3u8`、DASH `.mpd`、支持 Range 的 MP4 或 MP3 地址;
|
|
17
|
+
- 一个播放器,例如 `react-native-video`。
|
|
18
|
+
|
|
19
|
+
插件 Android 声明下限为 API 21,iOS 为 15+。应用实际下限取插件、React Native、播放器和其他依赖的最高要求;当前示例使用 Android API 24、iOS 15.1。Android 桥接固定使用 `io.meshstream:meshstream-android-sdk:1.0.10`,iOS 桥接固定使用 `MeshStreamKit 1.0.10`。
|
|
20
|
+
|
|
21
|
+
Android 原生依赖包含 `armeabi-v7a`、`arm64-v8a`、`x86`、`x86_64` 四种 ABI。真机与模拟器需同时满足框架和播放器的系统及架构要求。
|
|
22
|
+
|
|
23
|
+
## 安装
|
|
24
|
+
|
|
25
|
+
Android 权限与编译要求见[原生工程配置](./android-setup.md#工程配置),R8 和缓存预算见[混淆与内存](./android-setup.md#混淆与内存)。保留 React Native 工程要求的 Java/Kotlin 编译目标。
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install --save-exact react-native-meshstream@1.0.6
|
|
29
|
+
npm install react-native-video
|
|
30
|
+
cd ios && pod install --repo-update
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
在 `android/settings.gradle`(或 `settings.gradle.kts`)中合并以下仓库配置。`PREFER_SETTINGS` 避免 React Native Gradle 插件添加的工程级仓库覆盖这里的设置:
|
|
34
|
+
|
|
35
|
+
```kotlin
|
|
36
|
+
dependencyResolutionManagement {
|
|
37
|
+
repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
|
|
38
|
+
repositories {
|
|
39
|
+
google()
|
|
40
|
+
mavenCentral()
|
|
41
|
+
maven {
|
|
42
|
+
url = uri("https://sdk.meshstream.net/maven")
|
|
43
|
+
content { includeGroup("io.meshstream") }
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
应用其他依赖所需的仓库也应保留在同一个 settings 配置块中,包括替代 JavaScript 引擎要求的本地仓库。已有 `dependencyResolutionManagement` 时合并配置,不要重复声明。
|
|
50
|
+
|
|
51
|
+
原生依赖会从公开 Maven/CocoaPods 解析,请按上面的仓库配置安装并使用已发布版本。
|
|
52
|
+
|
|
53
|
+
## Android 本地代理网络配置
|
|
54
|
+
|
|
55
|
+
SDK 播放地址使用 HTTP 回环代理,即使媒体源为 HTTPS,也需放行该代理。在 `android/app/src/main/AndroidManifest.xml` 的 `<application>` 中添加 `android:networkSecurityConfig="@xml/meshstream_network_security_config"`,并创建 `android/app/src/main/res/xml/meshstream_network_security_config.xml`,使 Debug 和 Release 均生效:
|
|
56
|
+
|
|
57
|
+
```xml
|
|
58
|
+
<?xml version="1.0" encoding="utf-8"?>
|
|
59
|
+
<network-security-config>
|
|
60
|
+
<base-config cleartextTrafficPermitted="false" />
|
|
61
|
+
<domain-config cleartextTrafficPermitted="true">
|
|
62
|
+
<domain includeSubdomains="false">127.0.0.1</domain>
|
|
63
|
+
<domain includeSubdomains="false">localhost</domain>
|
|
64
|
+
</domain-config>
|
|
65
|
+
</network-security-config>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
已有网络安全策略时合并回环地址规则,保留原有配置。公网 HTTP 媒体源需要另行配置域名规则;建议使用 HTTPS。需要兼容 Android 6.0(API 23)的应用,参见 [Android 本地代理配置](./android-setup.md#允许本地播放代理)。
|
|
69
|
+
|
|
70
|
+
## iOS 本地代理网络配置
|
|
71
|
+
|
|
72
|
+
在应用 Target 的 `ios/应用名/Info.plist` 中合并以下设置,允许播放器访问本机 HTTP 代理:
|
|
73
|
+
|
|
74
|
+
```xml
|
|
75
|
+
<key>NSAppTransportSecurity</key>
|
|
76
|
+
<dict>
|
|
77
|
+
<key>NSAllowsLocalNetworking</key>
|
|
78
|
+
<true/>
|
|
79
|
+
</dict>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
已有 ATS 字典时合并该键并保留其他限制。网络配置变更后重新构建原生应用;仅刷新 JavaScript 不会更新 Manifest 或 Info.plist。
|
|
83
|
+
|
|
84
|
+
## 下一步
|
|
85
|
+
|
|
86
|
+
完成以上配置后,进入[快速接入](./react-native.md),创建会话、连接播放器,并在播放结束后释放资源。
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: React Native SDK 快速接入
|
|
3
|
+
sidebar_label: 快速接入
|
|
4
|
+
description: "React Native SDK 快速接入指南:创建播放会话、连接播放器、查看状态并释放资源。"
|
|
5
|
+
pagination_label: "React Native SDK 快速接入"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# React Native SDK 快速接入
|
|
9
|
+
|
|
10
|
+
当前 npm 包版本为 `react-native-meshstream 1.0.6`,发布于 [npm](https://www.npmjs.com/package/react-native-meshstream/v/1.0.6)。它提供统一的 JavaScript client/session API,播放器仍由应用管理。
|
|
11
|
+
|
|
12
|
+
<span id="接入准备" />
|
|
13
|
+
<span id="安装" />
|
|
14
|
+
<span id="android-本地代理网络配置" />
|
|
15
|
+
<span id="ios-本地代理网络配置" />
|
|
16
|
+
|
|
17
|
+
运行代码前,请先完成[安装与配置](./react-native-setup.md),准备 SDK Key 和可播放媒体地址,并配置应用网络策略。
|
|
18
|
+
|
|
19
|
+
## 最小接入
|
|
20
|
+
|
|
21
|
+
```tsx
|
|
22
|
+
import Video from 'react-native-video';
|
|
23
|
+
import { MeshStream } from 'react-native-meshstream';
|
|
24
|
+
|
|
25
|
+
const client = await MeshStream.create({ key: 'your_sdk_key' });
|
|
26
|
+
const session = await client.createPlaybackSession({
|
|
27
|
+
url: 'https://cdn.example.com/live/playlist.m3u8',
|
|
28
|
+
contentId: 'live-channel-42',
|
|
29
|
+
mimeType: 'm3u8',
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
<Video source={{ uri: session.playbackUrl }} controls />;
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
切换内容或播放器销毁时关闭当前资源:
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
await session.close();
|
|
39
|
+
await client.close();
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
P2P 策略、Tracker 或 Peer 不可用时会回退 CDN,不应因此停止播放器。可使用 `getStatus()`、`getStats()` 和 `getDiagnostics()` 查看状态,并通过 `addMeshStreamEventListener` 订阅事件。
|
|
43
|
+
|
|
44
|
+
## 预加载与多播放器
|
|
45
|
+
|
|
46
|
+
一个 client 可以管理多个独立 session。下一条内容可先创建 session 并调用 `await next.preload()`;只有真正播放时才把 `next.playbackUrl` 交给播放器。取消候选内容时关闭对应 session。
|
|
47
|
+
|
|
48
|
+
## 版本与验证
|
|
49
|
+
|
|
50
|
+
React Native 包版本独立于原生 SDK 版本。诊断时同时记录 npm 包版本和原生 SDK 版本。示例与发布记录见 [React Native SDK GitHub 仓库](https://github.com/Mesh-Stream/meshstream-p2p-react-native-sdk)。
|
|
51
|
+
|
|
52
|
+
相关文档:[安装与配置](./react-native-setup.md) · [高级用法](./react-native-advanced.md)。
|
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Uniapp SDK 高级用法
|
|
3
|
+
sidebar_label: 高级用法
|
|
4
|
+
description: "Uniapp SDK 高级用法:直播点播、MP4/MP3、源站鉴权、预加载、运行时控制、监控与生命周期。"
|
|
5
|
+
pagination_label: "Uniapp SDK 高级用法"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Uniapp SDK 高级用法
|
|
9
|
+
|
|
10
|
+
本页按原生 SDK 的接入场景组织:直播/点播、文件直链、每路配置、预加载、运行时控制、监控与平台策略。示例复用[快速接入](./uniapp.md)创建的 client,播放器变量由业务应用持有。
|
|
11
|
+
|
|
12
|
+
## 直播与点播接入策略
|
|
13
|
+
|
|
14
|
+
SDK 自动识别直播/点播,[基础接入方式相同](./uniapp.md)。播放期间可回传播放器状态,帮助 P2P 调度;不回传也可正常播放。
|
|
15
|
+
|
|
16
|
+
### 直播
|
|
17
|
+
|
|
18
|
+
<span id="直播回传缓冲余量" />
|
|
19
|
+
|
|
20
|
+
<span id="缓冲反馈" />
|
|
21
|
+
|
|
22
|
+
回传当前位置之后连续可播放的缓冲时长,帮助 SDK 调整 P2P 预取。例如播放到 60 秒、缓冲到 70 秒,应传 **10,000 毫秒**。直播起播位置与目标延迟由播放器设置。
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
await MeshStream.updateBufferedDurationMs(
|
|
26
|
+
client.clientId, session.sessionId, bufferedDurationMs,
|
|
27
|
+
)
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
### 点播(VOD)
|
|
31
|
+
|
|
32
|
+
<span id="点播另外回传播放位置" />
|
|
33
|
+
|
|
34
|
+
<span id="播放进度与缓冲反馈" />
|
|
35
|
+
|
|
36
|
+
除缓冲时长外,回传当前播放位置,帮助 SDK 在已连接且拥有目标分片的 Peer 中优先选择进度接近的节点。Seek 完成后立即更新位置。
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
await MeshStream.updateCurrentPositionMs(
|
|
40
|
+
client.clientId, session.sessionId, positionMs,
|
|
41
|
+
)
|
|
42
|
+
await MeshStream.updateBufferedDurationMs(
|
|
43
|
+
client.clientId, session.sessionId, bufferedDurationMs,
|
|
44
|
+
)
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
数值均为非负毫秒,缓冲时长不能跨越断档。播放器状态有效后通常每秒回传一次;关闭会话前停止回传并等待在途调用结束。
|
|
48
|
+
|
|
49
|
+
<span id="播放器状态回传" />
|
|
50
|
+
|
|
51
|
+
<span id="播放位置与连续缓冲" />
|
|
52
|
+
|
|
53
|
+
<span id="播放器状态同步" />
|
|
54
|
+
|
|
55
|
+
<span id="接入示例" />
|
|
56
|
+
|
|
57
|
+
<span id="播放器状态回传示例" />
|
|
58
|
+
|
|
59
|
+
<details>
|
|
60
|
+
<summary>完整播放器状态回传示例</summary>
|
|
61
|
+
|
|
62
|
+
将播放器回调转换为下面的毫秒输入;异步回传应串行执行,并处理桥接调用异常。
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
async function syncPlaybackState(positionMs, bufferedDurationMs, isLive) {
|
|
66
|
+
if (!isLive && Number.isFinite(positionMs) && positionMs >= 0) {
|
|
67
|
+
await MeshStream.updateCurrentPositionMs(
|
|
68
|
+
client.clientId, session.sessionId, positionMs,
|
|
69
|
+
)
|
|
70
|
+
}
|
|
71
|
+
if (Number.isFinite(bufferedDurationMs) && bufferedDurationMs >= 0) {
|
|
72
|
+
await MeshStream.updateBufferedDurationMs(
|
|
73
|
+
client.clientId, session.sessionId, bufferedDurationMs,
|
|
74
|
+
)
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
</details>
|
|
80
|
+
|
|
81
|
+
## MP4 / MP3 直链播放
|
|
82
|
+
|
|
83
|
+
MP4 与 MP3 使用文件直链。为同一内容设置稳定的 `contentId`;地址没有扩展名时显式指定 `mimeType`:
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
const session = await MeshStream.createPlaybackSession(client.clientId, {
|
|
87
|
+
url: 'https://cdn.example.com/video/trailer.mp4',
|
|
88
|
+
contentId: 'trailer-2026',
|
|
89
|
+
mimeType: 'mp4',
|
|
90
|
+
})
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
将 `session.playbackUrl` 交给支持该格式的播放器。MP3 只需替换媒体地址并将类型设为 `mp3`。文件加速要求源站支持单区间 HTTP Range 请求,并返回有效的 `Content-Range`;不满足条件时不启用 P2P 加速,实际播放与拖动结果仍取决于源站和播放器。SDK 不负责解码,也不绕过 DRM。
|
|
94
|
+
|
|
95
|
+
## 每路播放配置与源站鉴权
|
|
96
|
+
|
|
97
|
+
<span id="动态地址与源站请求头" />
|
|
98
|
+
|
|
99
|
+
客户端配置用于创建 client,每个媒体资源的参数在创建 session 时单独传入:
|
|
100
|
+
|
|
101
|
+
| 层级 | 参数 | 用途 |
|
|
102
|
+
| --- | --- | --- |
|
|
103
|
+
| Client | `key` | 对应应用和平台的 SDK Key |
|
|
104
|
+
| Client | `p2pEnabled` | 初始 P2P 意愿,仍受控制台策略约束 |
|
|
105
|
+
| Session | `url` | 必填的原始媒体地址 |
|
|
106
|
+
| Session | `contentId` | 同一内容的稳定标识 |
|
|
107
|
+
| Session | `mimeType` | `m3u8`、`mpd`、`mp4` 或 `mp3` |
|
|
108
|
+
| Session | `originHeaders` | 仅发给媒体源的请求头 |
|
|
109
|
+
|
|
110
|
+
播放地址带短期签名时传入稳定的 `contentId`;无扩展名的媒体地址显式指定 `mimeType`。源站请求头放在 `originHeaders`:
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
const session = await MeshStream.createPlaybackSession(client.clientId, {
|
|
114
|
+
url: signedUrl,
|
|
115
|
+
contentId: 'movie-2026-001',
|
|
116
|
+
mimeType: 'mp4',
|
|
117
|
+
originHeaders: { Authorization: `Bearer ${originToken}` },
|
|
118
|
+
})
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
请求头只用于源站访问,不会发送给 Peer。签名续期由业务层完成,续期后继续使用同一个 `contentId`;不要把 Key、Token 或完整签名地址写入日志。
|
|
122
|
+
|
|
123
|
+
## 预加载与内容切换
|
|
124
|
+
|
|
125
|
+
<span id="多会话与预加载" />
|
|
126
|
+
|
|
127
|
+
显式 `preload` 是可选的 HLS/DASH 预热:后台获取清单与首个媒体分片,不会下载整部视频。它也可提前启动 Tracker/Peer 连接,但排队成功不保证 Peer 已连接或媒体已就绪。尚未播放的候选会话不会向 Peer 上传媒体。MP4/MP3 直链不使用这条显式预加载流程。
|
|
128
|
+
|
|
129
|
+
保存候选会话,选中时复用其播放地址。关闭任一会话前,先停止状态回传、等待在途调用结束并取消其事件订阅,避免回调访问已关闭的会话。预加载不负责解码器准备,也不会渲染首帧。
|
|
130
|
+
|
|
131
|
+
<span id="预加载与多个会话" />
|
|
132
|
+
|
|
133
|
+
每个播放器使用独立会话。列表场景可提前创建下一条内容并预热:
|
|
134
|
+
|
|
135
|
+
### 准备候选内容
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
const next = await MeshStream.createPlaybackSession(client.clientId, {
|
|
139
|
+
url: nextItem.url,
|
|
140
|
+
contentId: nextItem.id,
|
|
141
|
+
mimeType: 'm3u8',
|
|
142
|
+
})
|
|
143
|
+
|
|
144
|
+
const queued = await MeshStream.preload(client.clientId, next.sessionId)
|
|
145
|
+
if (queued) {
|
|
146
|
+
// 真正切换时再把 next.playbackUrl 绑定给 video 播放器。
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`preload` 返回 `true` 表示预热已排队,不代表首帧已经出图。候选内容被丢弃时及时关闭会话,避免连接长期占用。
|
|
151
|
+
|
|
152
|
+
### 切换至候选内容
|
|
153
|
+
|
|
154
|
+
真正切换时,先从播放器解除旧媒体引用并关闭旧会话,再使用 `next.playbackUrl`,把 `next` 保留为当前会话。预加载不会驱动播放器,排队成功也不代表 Peer 已就绪;预热可能产生网络流量。
|
|
155
|
+
|
|
156
|
+
### 取消候选内容
|
|
157
|
+
|
|
158
|
+
若取消候选内容,则关闭它:
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
await MeshStream.closeSession(client.clientId, next.sessionId)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## 运行时控制
|
|
165
|
+
|
|
166
|
+
<span id="p2p-开关与-cdn-回退" />
|
|
167
|
+
|
|
168
|
+
### P2P 开关
|
|
169
|
+
|
|
170
|
+
灰度或排障时仅关闭当前会话的 P2P:
|
|
171
|
+
|
|
172
|
+
```ts
|
|
173
|
+
await MeshStream.setP2pEnabled(client.clientId, session.sessionId, false)
|
|
174
|
+
// video 继续使用 session.playbackUrl。
|
|
175
|
+
await MeshStream.setP2pEnabled(client.clientId, session.sessionId, true)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
P2P、Tracker 或配置不可用时,播放器继续使用 `session.playbackUrl`。不要因为 Peer 数为零、收到 `p2pUnavailable` 或单次请求回源就替换地址或停止播放。
|
|
179
|
+
|
|
180
|
+
## 事件与监控
|
|
181
|
+
|
|
182
|
+
<span id="事件状态与诊断" />
|
|
183
|
+
|
|
184
|
+
注册事件监听并按事件类型处理,页面销毁时取消订阅:
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
const removeEvents = MeshStream.addEventListener((event) => {
|
|
188
|
+
const eventClientId = event.getString ? event.getString('clientId') : event.clientId
|
|
189
|
+
const eventSessionId = event.getString ? event.getString('sessionId') : event.sessionId
|
|
190
|
+
if (eventClientId !== client.clientId || eventSessionId !== session.sessionId) return
|
|
191
|
+
const type = event.getString ? event.getString('type') : event.type
|
|
192
|
+
if (type === 'p2pUnavailable') {
|
|
193
|
+
console.info('P2P 不可用', event)
|
|
194
|
+
}
|
|
195
|
+
if (type === 'statistics') {
|
|
196
|
+
console.info('统计', event)
|
|
197
|
+
}
|
|
198
|
+
})
|
|
199
|
+
|
|
200
|
+
const status = await MeshStream.getStatus(client.clientId)
|
|
201
|
+
const stats = await MeshStream.getStats(client.clientId, session.sessionId)
|
|
202
|
+
const diagnostics = await MeshStream.getDiagnostics(
|
|
203
|
+
client.clientId, session.sessionId,
|
|
204
|
+
)
|
|
205
|
+
|
|
206
|
+
removeEvents()
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
也可以使用 `subscribeEvents` / `unsubscribeEvents` 获取数字订阅 ID。`statistics` 会携带流量和 Peer 数据,`cdnFallback` 只代表某次请求使用 CDN,不代表整个会话切换到 CDN。
|
|
210
|
+
|
|
211
|
+
| 字段 | 含义 |
|
|
212
|
+
| --- | --- |
|
|
213
|
+
| `httpDownloaded` | HTTP/CDN 下载字节 |
|
|
214
|
+
| `p2pDownloaded` | 从 Peer 获取的字节 |
|
|
215
|
+
| `p2pUploaded` | 向 Peer 分享的字节 |
|
|
216
|
+
| `connectedPeers` | 当前已连接 Peer 数量 |
|
|
217
|
+
| `downloadOffloadRatio` | P2P 下载字节 / HTTP 与 P2P 总下载字节,范围 0–1 |
|
|
218
|
+
|
|
219
|
+
百分比展示时将 `downloadOffloadRatio` 乘以 100;它是下载分流比例,不是上传分享比例。尚无下载数据时为零,不能仅凭有 Peer 或单次 CDN 回退判断分流效果。通过 `getDiagnostics()` 查看连接耗时和错误信息;可选字段可能为空。
|
|
220
|
+
|
|
221
|
+
<span id="接入验证" />
|
|
222
|
+
|
|
223
|
+
<details>
|
|
224
|
+
<summary>验证 P2P 效果</summary>
|
|
225
|
+
|
|
226
|
+
1. 先用单设备确认正常播放、点播拖动,以及关闭 P2P 后仍能播放。
|
|
227
|
+
2. 用两个设备播放同一内容,保持 `contentId` 一致;点播选择有重叠的播放进度,直播选择同一频道。媒体字节和时间轴应保持一致,不同资产或个性化清单不要复用同一个 ID。
|
|
228
|
+
3. 检查回传单位为毫秒,并在媒体清单加载后持续更新。当前位置 60 秒、连续缓冲到 70 秒时,缓冲值应为 10,000 毫秒;点播 Seek 完成后立即更新位置。
|
|
229
|
+
4. 在一段播放时间内观察 P2P 下载字节数与下载分担率的变化。仅有 Peer 连接不代表实际通过 P2P 下载了媒体;分片可用性、网络环境和平台策略都会影响结果。
|
|
230
|
+
5. 关闭 P2P,确认播放器继续通过 CDN 播放。随后停止状态回传并取消事件订阅,再关闭会话,确认切换内容后没有继续调用已关闭的会话。
|
|
231
|
+
|
|
232
|
+
</details>
|
|
233
|
+
|
|
234
|
+
## 网络与平台策略
|
|
235
|
+
|
|
236
|
+
Wi-Fi、蜂窝网络、以太网、账户权限与额度由原生 SDK 和控制台策略共同判断,本地 P2P 开关不能覆盖服务端限制。不要向客户端传入 `region`、`areaCode` 或 Tracker/ICE 地址。通过 `getStatus()` 查看 `effectiveP2pEnabled` 与 `reason`;单纯 Peer 数为零不代表播放异常。
|
|
237
|
+
|
|
238
|
+
SDK 播放地址使用 HTTP 回环代理,即使媒体源是 HTTPS 也需要完成 [Android/iOS 网络配置](./uniapp-setup.md),并确保 Release 包同样生效。已有网络策略时合并必要例外;公网 HTTP 媒体源仅放行所需域名,优先使用 HTTPS。
|
|
239
|
+
|
|
240
|
+
## 生命周期与后台播放
|
|
241
|
+
|
|
242
|
+
<span id="生命周期顺序" />
|
|
243
|
+
|
|
244
|
+
切换内容或销毁播放页面时:
|
|
245
|
+
|
|
246
|
+
1. 停止状态回传,等待在途回传结束,并取消事件订阅。
|
|
247
|
+
2. 停止播放器并解除当前媒体引用。
|
|
248
|
+
3. 关闭当前 session 及不再需要的预加载候选会话。
|
|
249
|
+
4. 只有其他活动会话都不再需要 client 时,才关闭 client。
|
|
250
|
+
|
|
251
|
+
后台或画中画仍在播放时,保留对应播放器和会话,由宿主应用配置后台模式、音频会话与播放器能力。页面离开是否释放资源需遵循业务播放策略,不能直接关闭仍在后台播放的会话。SDK 不绕过操作系统限制,也不保证后台持续分享。
|
|
252
|
+
|
|
253
|
+
```ts
|
|
254
|
+
await MeshStream.closeSession(client.clientId, session.sessionId)
|
|
255
|
+
await MeshStream.closeClient(client.clientId)
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
## 能力边界
|
|
259
|
+
|
|
260
|
+
以下为当前 Uniapp 封装的公共 API 范围;以本页公开参数为准,不要直接传入仅原生 SDK 支持的字段:
|
|
261
|
+
|
|
262
|
+
| 能力 | 当前封装入口 |
|
|
263
|
+
| --- | --- |
|
|
264
|
+
| HLS / DASH / MP4 / MP3、源站请求头、稳定内容标识 | 通过会话参数使用 |
|
|
265
|
+
| 多会话、预加载、P2P 开关、状态回传、统计 | 使用本页对应方法 |
|
|
266
|
+
| `maxMemoryBytes`、Peer 连接上限、请求超时、原生日志级别 | 当前未开放对应公共配置项 |
|
|
267
|
+
| Apple `setPictureInPictureActive` | 当前未开放对应桥接方法;播放器支持画中画不等于封装已提供此接口 |
|
|
268
|
+
| 解码、ABR、DRM、播放器缓存、系统后台权限 | 由播放器与应用管理 |
|
|
269
|
+
|
|
270
|
+
P2P 不可用不等于媒体不可播放。会话有效时继续使用其播放地址,是否重试或终止由播放器错误及源站响应决定;原生初始化或桥接调用失败仍需由应用处理。
|
|
271
|
+
|
|
272
|
+
## 相关文档
|
|
273
|
+
|
|
274
|
+
[安装与配置](./uniapp-setup.md) · [快速接入](./uniapp.md) · [故障排查](../troubleshooting.md)
|