@meshstream/docs-mcp 0.0.0-stage → 0.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/README.md +21 -2
- package/content/ai-coding.md +100 -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 +21 -4
- package/src/catalog.mjs +164 -0
- package/src/server.mjs +43 -0
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Windows SDK 高级用法
|
|
3
|
+
sidebar_label: 高级用法
|
|
4
|
+
pagination_label: "Windows SDK 高级用法"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Windows SDK 高级用法
|
|
8
|
+
|
|
9
|
+
本页介绍多会话、直播/点播、鉴权和运行时控制。基础接入请参阅 [Windows SDK 快速接入](./windows.md)。
|
|
10
|
+
|
|
11
|
+
## 直播与点播接入策略
|
|
12
|
+
|
|
13
|
+
SDK 自动识别直播/点播,[基础接入方式相同](./windows.md)。播放期间可回传播放器状态,帮助 P2P 调度;不回传也可正常播放。
|
|
14
|
+
|
|
15
|
+
### 直播
|
|
16
|
+
|
|
17
|
+
<span id="直播回传缓冲余量" />
|
|
18
|
+
|
|
19
|
+
<span id="缓冲反馈" />
|
|
20
|
+
|
|
21
|
+
回传当前位置之后连续可播放的缓冲时长,帮助 SDK 调整 P2P 预取。例如播放到 60 秒、缓冲到 70 秒,应传 **10,000 毫秒**。直播起播位置与目标延迟由播放器设置。
|
|
22
|
+
|
|
23
|
+
```cpp
|
|
24
|
+
meshstream_session_update_buffered_duration_ms(session, buffered_duration_ms);
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### 点播(VOD)
|
|
28
|
+
|
|
29
|
+
<span id="点播另外回传播放位置" />
|
|
30
|
+
|
|
31
|
+
<span id="播放进度与缓冲反馈" />
|
|
32
|
+
|
|
33
|
+
除缓冲时长外,回传当前播放位置,帮助 SDK 在已连接且拥有目标分片的 Peer 中优先选择进度接近的节点。Seek 完成后立即更新位置。
|
|
34
|
+
|
|
35
|
+
```cpp
|
|
36
|
+
meshstream_session_update_current_position_ms(session, position_ms);
|
|
37
|
+
meshstream_session_update_buffered_duration_ms(session, buffered_duration_ms);
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
数值均为非负毫秒,缓冲时长不能跨越断档。播放器状态有效后通常每秒回传一次;关闭会话前停止回传并等待在途调用结束。
|
|
41
|
+
|
|
42
|
+
<span id="播放器状态回传" />
|
|
43
|
+
|
|
44
|
+
<span id="接入示例" />
|
|
45
|
+
|
|
46
|
+
<span id="播放器状态回传示例" />
|
|
47
|
+
|
|
48
|
+
<details>
|
|
49
|
+
<summary>完整播放器状态回传示例</summary>
|
|
50
|
+
|
|
51
|
+
由宿主播放器提供有效的有符号毫秒值,函数校验后再转换为 C API 所需的 `uint64_t`。
|
|
52
|
+
|
|
53
|
+
```cpp
|
|
54
|
+
void sync_playback_state(
|
|
55
|
+
meshstream_session_t* session,
|
|
56
|
+
bool is_live,
|
|
57
|
+
int64_t current_position_ms,
|
|
58
|
+
int64_t buffered_duration_ms) {
|
|
59
|
+
if (!session) return;
|
|
60
|
+
if (buffered_duration_ms >= 0) {
|
|
61
|
+
meshstream_session_update_buffered_duration_ms(
|
|
62
|
+
session, static_cast<uint64_t>(buffered_duration_ms));
|
|
63
|
+
}
|
|
64
|
+
if (!is_live && current_position_ms >= 0) {
|
|
65
|
+
meshstream_session_update_current_position_ms(
|
|
66
|
+
session, static_cast<uint64_t>(current_position_ms));
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
</details>
|
|
72
|
+
|
|
73
|
+
## MP4 / MP3 直链播放
|
|
74
|
+
|
|
75
|
+
MP4 和 MP3 属于点播直链:播放器直接加载文件地址,而不是 HLS `.m3u8` 或 DASH `.mpd` 清单。为同一视频或音频设置稳定的 `content_id`;地址不带扩展名时,显式填写 `mime_type`。
|
|
76
|
+
|
|
77
|
+
```cpp
|
|
78
|
+
meshstream_playback_options_t options{};
|
|
79
|
+
options.struct_size = sizeof(options);
|
|
80
|
+
options.version = MESHSTREAM_PLAYBACK_OPTIONS_VERSION;
|
|
81
|
+
options.content_id = "trailer-2026";
|
|
82
|
+
options.mime_type = "mp4";
|
|
83
|
+
|
|
84
|
+
meshstream_session_t* session = nullptr;
|
|
85
|
+
int32_t rc = meshstream_client_create_playback_session(
|
|
86
|
+
client,
|
|
87
|
+
"https://cdn.example.com/video/trailer.mp4",
|
|
88
|
+
&options,
|
|
89
|
+
&session,
|
|
90
|
+
nullptr);
|
|
91
|
+
if (rc == MESHSTREAM_OK) {
|
|
92
|
+
const char* playback_url = meshstream_session_get_playback_url(session);
|
|
93
|
+
// 将 playback_url 交给支持 MP4 的播放器。
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
MP3 只需将地址和 `mime_type` 分别替换为 `.mp3` 和 `"mp3"`,并交给支持音频播放的宿主播放器。媒体源需要支持单 Range 请求并返回有效的 `Content-Range`。不满足该条件时,文件仍按原有方式播放,但不会启用加速。
|
|
98
|
+
|
|
99
|
+
## 为每路播放单独配置
|
|
100
|
+
|
|
101
|
+
一个 `meshstream_client_t` 可以管理多个独立 `meshstream_session_t`。每个播放器实例都应创建自己的会话;切换节目时销毁旧会话,再为新内容创建会话。
|
|
102
|
+
|
|
103
|
+
### 动态地址与源站鉴权
|
|
104
|
+
|
|
105
|
+
通过 `origin_headers_json` 传递仅发往源站的 JSON 请求头:
|
|
106
|
+
|
|
107
|
+
```cpp
|
|
108
|
+
meshstream_playback_options_t options{};
|
|
109
|
+
options.struct_size = sizeof(options);
|
|
110
|
+
options.version = MESHSTREAM_PLAYBACK_OPTIONS_VERSION;
|
|
111
|
+
options.content_id = "movie-2026-001";
|
|
112
|
+
options.mime_type = "m3u8"; // 无扩展名地址时显式指定;DASH 使用 mpd,直链媒体使用 mp4 或 mp3
|
|
113
|
+
options.origin_headers_json = "{\"Authorization\":\"Bearer origin-token\"}";
|
|
114
|
+
|
|
115
|
+
meshstream_session_t* session = nullptr;
|
|
116
|
+
if (meshstream_client_create_playback_session(
|
|
117
|
+
client, signed_url, &options, &session, nullptr) == MESHSTREAM_OK) {
|
|
118
|
+
const char* playback_url = meshstream_session_get_playback_url(session);
|
|
119
|
+
// 将 playback_url 交给播放器。
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
该字段不得记录日志,也不会发送给其他观看设备。
|
|
124
|
+
|
|
125
|
+
## 预加载与内容切换
|
|
126
|
+
|
|
127
|
+
显式 `preload` 是可选的 HLS/DASH 预热:后台获取清单与首个媒体分片,不会下载整部视频。它也可提前启动 Tracker/Peer 连接,但排队成功不保证 Peer 已连接或媒体已就绪。尚未播放的候选会话不会向 Peer 上传媒体。MP4/MP3 直链不使用这条显式预加载流程。
|
|
128
|
+
|
|
129
|
+
保存候选会话,选中时复用其播放地址。关闭任一会话前,先停止状态回传、等待在途调用结束并取消其事件订阅,避免回调访问已关闭的会话。预加载不负责解码器准备,也不会渲染首帧。
|
|
130
|
+
|
|
131
|
+
宿主持有 `current_session`、`next_session`,类型均为 `meshstream_session_t*`,初始为 `nullptr`。每个播放器独立管理自己的会话;`next_url` 是候选地址,`next_content_id` 是稳定内容 ID。
|
|
132
|
+
|
|
133
|
+
### 准备候选内容
|
|
134
|
+
|
|
135
|
+
```cpp
|
|
136
|
+
meshstream_playback_options_t options{};
|
|
137
|
+
options.struct_size = sizeof(options);
|
|
138
|
+
options.version = MESHSTREAM_PLAYBACK_OPTIONS_VERSION;
|
|
139
|
+
options.content_id = next_content_id;
|
|
140
|
+
options.mime_type = "m3u8";
|
|
141
|
+
|
|
142
|
+
meshstream_session_t* candidate = nullptr;
|
|
143
|
+
int32_t rc = meshstream_client_create_playback_session(
|
|
144
|
+
client, next_url, &options, &candidate, nullptr);
|
|
145
|
+
if (rc == MESHSTREAM_OK) {
|
|
146
|
+
if (next_session) meshstream_session_destroy(next_session);
|
|
147
|
+
next_session = candidate;
|
|
148
|
+
int32_t preload_rc = meshstream_session_preload(next_session);
|
|
149
|
+
// MESHSTREAM_OK: queued; MESHSTREAM_PRELOAD_SKIPPED: not queued.
|
|
150
|
+
(void)preload_rc;
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
`MESHSTREAM_OK` 表示已排队;`MESHSTREAM_PRELOAD_SKIPPED` 表示本次未排队,例如直链媒体或预热已经运行,不属于播放失败。其他返回码按错误处理;创建候选失败时不要替换当前会话。
|
|
155
|
+
|
|
156
|
+
### 切换至候选内容
|
|
157
|
+
|
|
158
|
+
执行下面代码前,先停止并等待旧会话回调结束,停止宿主播放器并解除旧媒体引用。启用候选会话后,由所用播放器的接口加载其地址;播放期间保持当前会话存活:
|
|
159
|
+
|
|
160
|
+
```cpp
|
|
161
|
+
if (next_session) {
|
|
162
|
+
if (current_session) meshstream_session_destroy(current_session);
|
|
163
|
+
current_session = next_session;
|
|
164
|
+
next_session = nullptr;
|
|
165
|
+
const char* playback_url = meshstream_session_get_playback_url(current_session);
|
|
166
|
+
// Load playback_url in the host player, then start playback.
|
|
167
|
+
(void)playback_url;
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### 取消候选内容
|
|
172
|
+
|
|
173
|
+
仅关闭已丢弃的候选会话,当前播放不受影响:
|
|
174
|
+
|
|
175
|
+
```cpp
|
|
176
|
+
if (next_session) {
|
|
177
|
+
meshstream_session_destroy(next_session);
|
|
178
|
+
next_session = nullptr;
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## 运行时控制
|
|
183
|
+
|
|
184
|
+
```cpp
|
|
185
|
+
meshstream_session_set_p2p_enabled(session, 0); // 临时关闭 P2P
|
|
186
|
+
meshstream_session_set_p2p_enabled(session, 1);
|
|
187
|
+
|
|
188
|
+
meshstream_stats_t stats{};
|
|
189
|
+
meshstream_session_get_stats(session, &stats);
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`meshstream_session_set_p2p_enabled` 只影响当前会话的加速状态,不影响播放器继续使用 `playback_url` 播放。
|
|
193
|
+
|
|
194
|
+
## 事件与监控
|
|
195
|
+
|
|
196
|
+
Windows SDK 通过拉取快照进行监控:
|
|
197
|
+
|
|
198
|
+
```cpp
|
|
199
|
+
meshstream_stats_t stats{};
|
|
200
|
+
meshstream_session_get_stats(session, &stats);
|
|
201
|
+
|
|
202
|
+
meshstream_status_t status{};
|
|
203
|
+
meshstream_session_get_status(session, &status);
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
重点观察 P2P 下载、分享和媒体源下载流量,以及连接和分片成功/失败计数。状态和统计仅用于展示、告警和诊断,不应决定播放器是否继续播放。
|
|
207
|
+
|
|
208
|
+
<span id="接入验证" />
|
|
209
|
+
|
|
210
|
+
<details>
|
|
211
|
+
<summary>验证 P2P 效果</summary>
|
|
212
|
+
|
|
213
|
+
1. 先用单设备确认正常播放、点播拖动,以及关闭 P2P 后仍能播放。
|
|
214
|
+
2. 用两个设备播放同一内容,保持 `content_id` 一致;点播选择有重叠的播放进度,直播选择同一频道。媒体字节和时间轴应保持一致,不同资产或个性化清单不要复用同一个 ID。
|
|
215
|
+
3. 检查回传单位为毫秒,并在媒体清单加载后持续更新。当前位置 60 秒、连续缓冲到 70 秒时,缓冲值应为 10,000 毫秒;点播 Seek 完成后立即更新位置。
|
|
216
|
+
4. 在一段播放时间内观察 P2P 下载字节数与下载分担率的变化。仅有 Peer 连接不代表实际通过 P2P 下载了媒体;分片可用性、网络环境和平台策略都会影响结果。
|
|
217
|
+
5. 关闭 P2P,确认播放器继续通过 CDN 播放。随后停止状态回传并取消事件订阅,再关闭会话,确认切换内容后没有继续调用已关闭的会话。
|
|
218
|
+
|
|
219
|
+
</details>
|
|
220
|
+
|
|
221
|
+
## 网络与平台策略
|
|
222
|
+
|
|
223
|
+
SDK 自动处理应用身份和服务连接,业务代码不需要填写服务地址、区域或访问 Token。`meshstream_session_set_p2p_enabled` 是本地会话开关,控制台策略优先级更高。
|
|
224
|
+
|
|
225
|
+
## 生命周期与兜底
|
|
226
|
+
|
|
227
|
+
- 每个播放器实例对应一个 `meshstream_session_t`。
|
|
228
|
+
- 切换频道或节目时先调用 `meshstream_session_destroy`,再创建新会话。
|
|
229
|
+
- 应用退出时先销毁全部会话,再调用 `meshstream_client_destroy`。
|
|
230
|
+
- 加速、鉴权或网络异常时,继续使用 SDK 返回的播放地址。
|
|
231
|
+
- `MESHSTREAM_CREATE_PLAYBACK_SESSION_FAILED` 表示会话创建失败,业务应保留原始播放地址作为兜底。
|
|
232
|
+
|
|
233
|
+
停止播放时先销毁会话,再销毁客户端。加速暂不可用时仍保持正常播放;记录流量统计和诊断信息,便于生产排障。
|
|
234
|
+
|
|
235
|
+
## 能力边界
|
|
236
|
+
|
|
237
|
+
SDK 负责播放会话和加速处理;VLC、libVLC、mpv 或自研播放器负责清单解析、ABR、解码、渲染和播放器缓存。SDK 不替换播放器,也不承诺应用退出或进入后台后持续分享媒体数据。
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Windows SDK 安装与配置
|
|
3
|
+
sidebar_label: 安装与配置
|
|
4
|
+
description: "Windows SDK 安装与配置指南:平台要求、依赖安装和应用设置。"
|
|
5
|
+
pagination_label: "Windows SDK 安装与配置"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Windows SDK 安装与配置
|
|
9
|
+
|
|
10
|
+
MeshStream Windows SDK 通过 C ABI 为桌面播放器提供 P2P 加速能力。应用继续使用自己的播放器,SDK 负责播放会话和加速处理。
|
|
11
|
+
|
|
12
|
+
## 平台与运行环境
|
|
13
|
+
|
|
14
|
+
| 项目 | 当前发布支持 |
|
|
15
|
+
| --- | --- |
|
|
16
|
+
| Windows 系统 | Windows 10 / 11 x64 |
|
|
17
|
+
| CPU 架构 | x64 |
|
|
18
|
+
| 接入语言 | C / C++(通过 `meshstream.h`) |
|
|
19
|
+
| 运行库 | Microsoft Visual C++ 2015-2022 Redistributable(x64) |
|
|
20
|
+
|
|
21
|
+
当前 Windows 发布包仅提供 x64 DLL 和导入库。Windows ARM64、x86 以及其他系统版本尚未作为发布支持范围;不要将 x64 DLL 随应用发布到这些环境。
|
|
22
|
+
|
|
23
|
+
## 接入前准备
|
|
24
|
+
|
|
25
|
+
开始接入前,请准备:
|
|
26
|
+
|
|
27
|
+
- MeshStream Windows SDK 动态库和公开头文件 `meshstream.h`;
|
|
28
|
+
- 控制台创建的 SDK Key;
|
|
29
|
+
- 一个支持目标媒体格式的播放器,例如 VLC、ffplay 或自研播放器;
|
|
30
|
+
- 一个可播放的 HLS `.m3u8`、DASH `.mpd`、支持 Range 的 MP4 或 MP3 地址;
|
|
31
|
+
|
|
32
|
+
## 添加 SDK
|
|
33
|
+
|
|
34
|
+
Windows SDK 发布包包含以下文件:
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
include/meshstream.h
|
|
38
|
+
lib/p2pcdn_core.dll
|
|
39
|
+
lib/p2pcdn_core.dll.lib
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
在工程中完成以下操作:
|
|
43
|
+
|
|
44
|
+
1. 将 `include` 加入 C/C++ 头文件搜索路径,并包含 `meshstream.h`;
|
|
45
|
+
2. 将 `lib/p2pcdn_core.dll.lib` 加入链接输入;
|
|
46
|
+
3. 将 `lib/p2pcdn_core.dll` 放在应用可执行文件同级目录,或放入系统 `PATH`;
|
|
47
|
+
4. 在未安装运行库的机器上安装 Microsoft Visual C++ 2015-2022 Redistributable(x64)。
|
|
48
|
+
|
|
49
|
+
业务代码只应依赖 `meshstream.h` 公共接口,不要依赖 DLL 的内部文件名或本地代理地址格式。
|
|
50
|
+
|
|
51
|
+
## 下一步
|
|
52
|
+
|
|
53
|
+
完成以上配置后,进入[快速接入](./windows.md),创建会话、连接播放器,并在播放结束后释放资源。
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Windows SDK 快速接入
|
|
3
|
+
sidebar_label: 快速接入
|
|
4
|
+
description: "Windows SDK 快速接入指南:创建播放会话、连接播放器、查看状态并释放资源。"
|
|
5
|
+
pagination_label: "Windows SDK 快速接入"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Windows SDK 快速接入
|
|
9
|
+
|
|
10
|
+
MeshStream Windows SDK 通过 C ABI 为桌面播放器提供 P2P 加速能力。应用继续使用自己的播放器,SDK 负责播放会话和加速处理。
|
|
11
|
+
|
|
12
|
+
<span id="平台与运行环境" />
|
|
13
|
+
<span id="接入前准备" />
|
|
14
|
+
<span id="添加-sdk" />
|
|
15
|
+
|
|
16
|
+
运行代码前,请先完成[安装与配置](./windows-setup.md),准备 SDK Key 和可播放媒体地址,并配置应用网络策略。
|
|
17
|
+
|
|
18
|
+
## 快速开始
|
|
19
|
+
|
|
20
|
+
按以下四步接入:初始化 Client、创建播放会话、将 SDK 地址交给播放器、播放结束后释放资源。
|
|
21
|
+
|
|
22
|
+
### 1. 初始化 Client
|
|
23
|
+
|
|
24
|
+
```c
|
|
25
|
+
#include "meshstream.h"
|
|
26
|
+
|
|
27
|
+
meshstream_config_t config = {0};
|
|
28
|
+
meshstream_config_default(&config);
|
|
29
|
+
config.key = "your_sdk_key";
|
|
30
|
+
|
|
31
|
+
meshstream_client_t* client = NULL;
|
|
32
|
+
if (meshstream_client_create(&config, &client) != MESHSTREAM_OK) {
|
|
33
|
+
// 记录本地初始化错误;业务可自行决定是否降级为原始播放地址。
|
|
34
|
+
return;
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### 2. 创建会话并交给播放器
|
|
39
|
+
|
|
40
|
+
`origin_url` 是原始媒体地址。每次播放创建一个会话,并始终将 SDK 返回的 `playback_url` 交给播放器。会话地址会保留现有媒体播放链路;P2P 是否可用只影响加速状态,不决定是否使用该地址。
|
|
41
|
+
|
|
42
|
+
```c
|
|
43
|
+
const char* origin_url = "https://cdn.example.com/video/master.m3u8";
|
|
44
|
+
|
|
45
|
+
meshstream_session_t* session = NULL;
|
|
46
|
+
meshstream_playback_options_t options = {0};
|
|
47
|
+
options.struct_size = sizeof(options);
|
|
48
|
+
options.version = MESHSTREAM_PLAYBACK_OPTIONS_VERSION;
|
|
49
|
+
options.content_id = "asset-12345";
|
|
50
|
+
|
|
51
|
+
if (meshstream_client_create_playback_session(
|
|
52
|
+
client, origin_url, &options, &session, NULL) != MESHSTREAM_OK) {
|
|
53
|
+
meshstream_client_destroy(client);
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
56
|
+
const char* playback_url = meshstream_session_get_playback_url(session);
|
|
57
|
+
|
|
58
|
+
// 在 session 有效期间,将 playback_url 交给 VLC、libVLC、mpv 或自研播放器。
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### 3. 播放结束时释放会话
|
|
62
|
+
|
|
63
|
+
```c
|
|
64
|
+
if (session != NULL) {
|
|
65
|
+
meshstream_session_destroy(session);
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### 4. 应用退出时释放 Client
|
|
70
|
+
|
|
71
|
+
```c
|
|
72
|
+
meshstream_client_destroy(client);
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
加速暂不可用不会阻断播放,播放器仍使用会话返回的 `playback_url`。只有客户端或会话创建因本地配置、资源或编程错误而失败时,业务才可自行选择记录错误并直接播放 `origin_url`;这属于业务降级,不经过 SDK,也不会计入 SDK 用量统计。
|
|
76
|
+
|
|
77
|
+
## 预加载下一条内容
|
|
78
|
+
|
|
79
|
+
对于可能马上播放的 HLS 或 DASH 内容,可先创建候选会话并调用 `meshstream_session_preload`。调用不等待网络,只预热清单和首个分片,也不创建或驱动播放器。用户切换时直接将同一会话的播放地址交给播放器;候选内容取消时销毁该会话。
|
|
80
|
+
|
|
81
|
+
## 配置项
|
|
82
|
+
|
|
83
|
+
| 字段 | 默认值 | 说明 |
|
|
84
|
+
| --- | --- | --- |
|
|
85
|
+
| `key` | 必填 | 控制台签发的 SDK Key |
|
|
86
|
+
| `log_level` | `0` | 日志级别;生产环境建议保持默认值 |
|
|
87
|
+
|
|
88
|
+
Windows SDK 的服务发现地址、应用身份和策略由 SDK 自动处理,业务代码无需填写服务端地址或 Token。
|
|
89
|
+
|
|
90
|
+
Windows SDK 不接受客户端区域参数。租户 `homeRegion` 从 SDK Key 服务端解析,访问侧 Tracker/ICE
|
|
91
|
+
调度根据请求网络完成;业务代码无需选择数据中心。
|
|
92
|
+
|
|
93
|
+
## 动态地址与源站请求头
|
|
94
|
+
|
|
95
|
+
播放地址带短期签名参数时,为同一内容设置稳定的 `content_id`。如需附加源站鉴权请求头,通过 `origin_headers_json` 传入 JSON 对象:
|
|
96
|
+
|
|
97
|
+
```c
|
|
98
|
+
options.content_id = "asset-12345";
|
|
99
|
+
options.mime_type = "m3u8"; // DASH 使用 mpd;直链媒体使用 mp4 或 mp3
|
|
100
|
+
options.origin_headers_json = "{\"Authorization\":\"Bearer origin-token\"}";
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
这些请求头只用于访问客户媒体源,不会发送给其他观看设备。不要将 Token、Cookie 或完整签名 URL 写入应用日志。
|
|
104
|
+
|
|
105
|
+
## 播放会话 API
|
|
106
|
+
|
|
107
|
+
| 方法 | 说明 |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| `meshstream_client_create_playback_session` | 创建播放会话并返回 SDK 播放地址 |
|
|
110
|
+
| `meshstream_session_get_playback_url` | 获取交给播放器的播放地址 |
|
|
111
|
+
| `meshstream_session_preload` | 异步预热 HLS/DASH 清单与首个分片,不会播放媒体 |
|
|
112
|
+
| `meshstream_session_set_p2p_enabled` | 运行时开关 P2P,不影响 CDN 播放 |
|
|
113
|
+
| `meshstream_session_update_buffered_duration_ms` | 上报当前播放时间到缓冲前沿的时长,用于调整后台 P2P 预取 |
|
|
114
|
+
| `meshstream_session_update_current_position_ms` | 上报当前播放位置;点播用于匹配进度接近的节点,seek 后应立即调用 |
|
|
115
|
+
| `meshstream_session_get_stats` | 获取当前会话的流量和 Peer 数量快照 |
|
|
116
|
+
| `meshstream_session_destroy` | 结束播放会话并释放相关资源 |
|
|
117
|
+
| `meshstream_client_destroy` | 释放客户端及其资源 |
|
|
118
|
+
|
|
119
|
+
## 事件与统计
|
|
120
|
+
|
|
121
|
+
Windows SDK 通过 `meshstream_session_get_stats` 获取统计快照。主要字段包括:
|
|
122
|
+
|
|
123
|
+
- `p2p_downloaded`:本设备通过 P2P 获取的字节数;
|
|
124
|
+
- `p2p_uploaded`:本设备向其他设备分享的字节数;
|
|
125
|
+
- `http_downloaded`:从客户 CDN 获取的字节数;
|
|
126
|
+
- `connected_peers`:当前连接的其他设备数;
|
|
127
|
+
- `peer_connect_errors`:连接其他设备失败的累计次数。
|
|
128
|
+
|
|
129
|
+
可通过 `meshstream_session_get_status` 获取当前会话的加速状态;该状态仅用于展示与诊断,不能作为停止播放器的条件。
|
|
130
|
+
|
|
131
|
+
## HLS、DASH 与 MP4/MP3 直链播放
|
|
132
|
+
|
|
133
|
+
- SDK 支持 HLS、DASH,以及带 Range 的 MP4/MP3 直链播放请求,但不负责格式解码。
|
|
134
|
+
- MP4/MP3 需要源站支持单 Range,并返回有效的 `Content-Range`;不满足条件时保持正常播放但不启用加速。
|
|
135
|
+
- 播放器需要自行支持对应格式,并播放 SDK 返回的播放地址。
|
|
136
|
+
- 加速、网络或配置暂时不可用时,播放仍会继续,不应将加速状态作为停止播放的条件。
|
|
137
|
+
|
|
138
|
+
## 播放容错
|
|
139
|
+
|
|
140
|
+
以下情况只会关闭或降低加速能力,不会阻断媒体播放:
|
|
141
|
+
|
|
142
|
+
- SDK Key、应用或平台校验未通过;
|
|
143
|
+
- 当前没有可用的加速连接;
|
|
144
|
+
- 网络条件不满足加速要求;
|
|
145
|
+
- 单个媒体请求超时或失败;
|
|
146
|
+
- 平台服务暂时不可用。
|
|
147
|
+
|
|
148
|
+
## 错误码
|
|
149
|
+
|
|
150
|
+
| 宏 | 值 | 含义 |
|
|
151
|
+
| --- | ---: | --- |
|
|
152
|
+
| `MESHSTREAM_OK` | 0 | 成功 |
|
|
153
|
+
| `MESHSTREAM_INVALID_ARGUMENT` | 1 | 参数错误 |
|
|
154
|
+
| `MESHSTREAM_RUNTIME_ERROR` | 2 | 运行时错误 |
|
|
155
|
+
| `MESHSTREAM_CREATE_PLAYBACK_SESSION_FAILED` | 3 | 播放会话创建失败 |
|
|
156
|
+
| `MESHSTREAM_PRELOAD_SKIPPED` | 4 | 不支持预热或预热已在执行 |
|
|
157
|
+
|
|
158
|
+
## 下一步
|
|
159
|
+
|
|
160
|
+
[快速开始](../quickstart.md) · [最佳实践](../best-practices.md) · [故障排查](../troubleshooting.md)
|
|
161
|
+
|
|
162
|
+
相关文档:[安装与配置](./windows-setup.md) · [高级用法](./windows-advanced.md)。
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 故障排查
|
|
3
|
+
sidebar_position: 99
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 故障排查
|
|
7
|
+
|
|
8
|
+
先确认播放器使用的是 SDK 返回的 `playbackUrl`,并且播放会话在播放器结束前没有被提前释放。下面的检查顺序适用于 Web、Android、iOS 和 Windows SDK。
|
|
9
|
+
|
|
10
|
+
## 快速定位
|
|
11
|
+
|
|
12
|
+
| 现象 | 优先检查 | 正常预期 |
|
|
13
|
+
| --- | --- | --- |
|
|
14
|
+
| 播放失败 | 原始播放地址、源站鉴权、播放器错误日志 | SDK 不应替换播放器的鉴权和解码逻辑 |
|
|
15
|
+
| 播放正常但没有加速 | Key 状态、内容标识、网络权限、是否存在其他合格观看者 | 加速暂不可用时,播放仍可继续 |
|
|
16
|
+
| Peer 数量为 0 | 应用、Key、`contentId` 和播放内容是否一致 | 没有其他相同内容的在线观看者时,0 是正常结果 |
|
|
17
|
+
| 控制台没有数据 | 会话是否正常结束、上报域名是否可达、查询时间范围 | 统计为异步处理,可能有短暂延迟 |
|
|
18
|
+
| 只有部分设备异常 | 平台版本、ABI、浏览器 Service Worker、网络策略 | 先按平台文档确认运行环境 |
|
|
19
|
+
|
|
20
|
+
## `TRACKER_UNAVAILABLE`
|
|
21
|
+
|
|
22
|
+
这表示当前会话暂时无法建立加速连接。请依次检查:
|
|
23
|
+
|
|
24
|
+
1. 控制台中的 SDK Key 是否已启用,且绑定了正确的应用和平台。
|
|
25
|
+
2. 应用是否允许访问配置服务和加速服务使用的 HTTPS/WSS 地址。
|
|
26
|
+
3. 浏览器、企业网关、防火墙或 VPN 是否拦截了 WebSocket。
|
|
27
|
+
4. 播放地址是否仍可由播放器直接访问。
|
|
28
|
+
|
|
29
|
+
这类问题不会改变播放器的正常播放路径。修复 Key 或网络策略后,重新创建播放会话即可验证,不要在同一个失败会话上反复重试。
|
|
30
|
+
|
|
31
|
+
## Peer 数量为 0
|
|
32
|
+
|
|
33
|
+
Peer 只有在以下条件同时满足时才会出现:
|
|
34
|
+
|
|
35
|
+
- 客户端使用同一应用下允许互通的 SDK Key;
|
|
36
|
+
- 播放的是同一份内容,且 `contentId` 稳定;
|
|
37
|
+
- 其他观看者此时仍在线,并且已请求相同内容;
|
|
38
|
+
- 客户端网络允许建立必要的连接。
|
|
39
|
+
|
|
40
|
+
动态签名 URL 不应直接作为内容标识。请给每个实际媒体内容传入稳定的 `contentId`,不要把每次变化的签名、时间戳或随机参数拼进标识。刚开始播放时 Peer 为 0 也很常见,等待其他观看者加入后再观察。
|
|
41
|
+
|
|
42
|
+
## 播放地址不生效
|
|
43
|
+
|
|
44
|
+
SDK 创建会话后会返回新的播放地址。请确认:
|
|
45
|
+
|
|
46
|
+
1. 播放器加载的是 `session.playbackUrl`,而不是仍保存的原始 URL。
|
|
47
|
+
2. URL 没有被业务层重新拼接、编码或替换。
|
|
48
|
+
3. 播放器请求所需的 Cookie、Authorization 或其他源站请求头已按平台 API 传入。
|
|
49
|
+
4. 播放地址的有效期覆盖整个播放过程;短时签名地址需要在业务层按源站规则刷新。
|
|
50
|
+
|
|
51
|
+
SDK 不会替客户生成媒体鉴权,也不会把源站 Token 发送给其他观看者。
|
|
52
|
+
|
|
53
|
+
## `401`、`403`、`421` 或 `503`
|
|
54
|
+
|
|
55
|
+
- `401` / `403`:通常是媒体 URL、Cookie、Authorization 或源站白名单校验失败。先用播放器之外的受控请求验证原始地址权限。
|
|
56
|
+
- `421`:请求到达了不匹配的服务区域。检查部署入口、反向代理和租户区域路由,不要在客户端临时添加区域字段。
|
|
57
|
+
- `503 HOME_REGION_UNRESOLVED`:服务端无法解析 SDK Key 的租户归属区域。检查 Key 是否来自当前环境,以及服务端区域配置是否完整。
|
|
58
|
+
|
|
59
|
+
修复服务端或源站配置后,请关闭旧会话并创建新会话。不要把这些响应当作播放器解码错误处理。
|
|
60
|
+
|
|
61
|
+
## 播放正常但控制台没有统计
|
|
62
|
+
|
|
63
|
+
统计通过后台链路异步处理,不要求业务代码直接调用统计接口。请确认:
|
|
64
|
+
|
|
65
|
+
- 会话确实调用了 `close`、`dispose` 或平台对应的释放方法;
|
|
66
|
+
- 播放器没有在初始化后立即销毁会话;
|
|
67
|
+
- 统计和配置域名没有被 CSP、代理或防火墙拦截;
|
|
68
|
+
- 控制台查询的应用、Key、平台和时间范围正确。
|
|
69
|
+
|
|
70
|
+
短暂延迟是正常的。不要因为统计尚未出现就重复初始化 SDK 或重放上报请求。
|
|
71
|
+
|
|
72
|
+
## 切换内容后仍显示旧数据
|
|
73
|
+
|
|
74
|
+
每路媒体内容都应创建独立播放会话。切换内容时按以下顺序处理:
|
|
75
|
+
|
|
76
|
+
1. 停止旧播放器并释放旧会话;
|
|
77
|
+
2. 使用新的 URL 和稳定的 `contentId` 创建会话;
|
|
78
|
+
3. 将新会话返回的 `playbackUrl` 交给播放器;
|
|
79
|
+
4. 将新的缓冲区和播放位置同步给新会话。
|
|
80
|
+
|
|
81
|
+
不要跨不同媒体内容复用同一个会话或 `contentId`。
|
|
82
|
+
|
|
83
|
+
## MP4、MP3 或分段请求异常
|
|
84
|
+
|
|
85
|
+
MP4/MP3 直链加速需要播放器和源站支持单 Range 请求,并返回有效的 `206 Partial Content` 与 `Content-Range`。请检查:
|
|
86
|
+
|
|
87
|
+
- 源站或 CDN 没有移除 Range 请求头;
|
|
88
|
+
- `Content-Length`、`Content-Range` 和 MIME 类型正确;
|
|
89
|
+
- Web 端已按文档注册并启用同源 Service Worker;
|
|
90
|
+
- 没有扩展名的 URL 已显式设置正确的 MIME 类型。
|
|
91
|
+
|
|
92
|
+
条件不满足时,媒体仍可按普通方式播放,但不会启用对应的加速能力。
|
|
93
|
+
|
|
94
|
+
## 直播延迟或卡顿
|
|
95
|
+
|
|
96
|
+
先区分播放器缓冲问题和加速连接问题:
|
|
97
|
+
|
|
98
|
+
1. 记录播放器的缓冲时长、当前播放位置和清单刷新错误;
|
|
99
|
+
2. 确认直播会话使用稳定的直播 `contentId`,不要为每个分片创建会话;
|
|
100
|
+
3. 检查直播清单、分片和鉴权 URL 是否持续有效;
|
|
101
|
+
4. 对比关闭 P2P 后的同一播放地址,确认问题是否只在加速开启时出现。
|
|
102
|
+
|
|
103
|
+
不要为了追求更低延迟而关闭播放器自身的直播缓冲和重连策略。
|
|
104
|
+
|
|
105
|
+
## 安全与日志
|
|
106
|
+
|
|
107
|
+
提交问题时可以提供时间、平台、SDK 版本、脱敏后的 Key 后缀、`contentId`、会话 ID、错误码和统计摘要。请勿上传完整 SDK Key、源站 Token、Cookie、Authorization 请求头或用户个人信息。
|
|
108
|
+
|
|
109
|
+
## 提交工单前的最小信息
|
|
110
|
+
|
|
111
|
+
```text
|
|
112
|
+
发生时间(含时区):
|
|
113
|
+
平台与系统版本:
|
|
114
|
+
SDK 版本:
|
|
115
|
+
应用 / Key(脱敏):
|
|
116
|
+
contentId:
|
|
117
|
+
原始媒体类型:HLS / DASH / MP4 / MP3
|
|
118
|
+
现象:播放失败 / Peer 为 0 / 无统计 / 卡顿 / 其他
|
|
119
|
+
错误码或日志(已脱敏):
|
|
120
|
+
是否更换网络后复现:是 / 否
|
|
121
|
+
是否使用 SDK 返回的 playbackUrl:是 / 否
|
|
122
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,23 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@meshstream/docs-mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
6
|
-
}
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"private": false,
|
|
5
|
+
"description": "Read-only MCP server for the MeshStream official developer documentation.",
|
|
6
|
+
"repository": { "type": "git", "url": "git+https://github.com/Mesh-Stream/meshstream-ai-tools.git", "directory": "packages/docs-mcp" },
|
|
7
|
+
"homepage": "https://meshstream.net/docs/ai-coding",
|
|
8
|
+
"type": "module",
|
|
9
|
+
"publishConfig": { "access": "public" },
|
|
10
|
+
"files": ["src", "content", "README.md"],
|
|
11
|
+
"scripts": {
|
|
12
|
+
"prepack": "node scripts/sync-content.mjs",
|
|
13
|
+
"start": "node src/server.mjs",
|
|
14
|
+
"test": "node --test test/*.test.mjs"
|
|
15
|
+
},
|
|
16
|
+
"bin": {
|
|
17
|
+
"meshstream-docs-mcp": "src/server.mjs"
|
|
18
|
+
},
|
|
19
|
+
"dependencies": {
|
|
20
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
21
|
+
"zod": "^4.6.7"
|
|
22
|
+
}
|
|
23
|
+
}
|