@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
package/README.md
CHANGED
|
@@ -1,3 +1,22 @@
|
|
|
1
|
-
#
|
|
1
|
+
# MeshStream Docs MCP
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
只读 MCP 原型,数据源是官网文档 Markdown。它提供四个工具:
|
|
4
|
+
|
|
5
|
+
- `search_docs`
|
|
6
|
+
- `get_sdk_release`
|
|
7
|
+
- `get_integration_guide`
|
|
8
|
+
- `get_troubleshooting_guide`
|
|
9
|
+
|
|
10
|
+
## 本地运行
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm install
|
|
14
|
+
npm test
|
|
15
|
+
npm start
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
本地开发默认从仓库的 `apps/developer-site/docs/` 读取。打包时会把官网文档快照复制到
|
|
19
|
+
包内的 `content/`,独立安装后无需访问源码仓库;也可以通过 `MESHSTREAM_DOCS_ROOT`
|
|
20
|
+
指向经过版本锁定的文档快照。
|
|
21
|
+
|
|
22
|
+
当前 MCP 只读官网资料,不接收 SDK Key,不访问客户项目文件,也不执行代码或生产操作。
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
sidebar_position: 2
|
|
3
|
+
title: AI Coding
|
|
4
|
+
sidebar_label: AI Coding
|
|
5
|
+
description: 使用 Codex、Cursor 或 Claude Code,通过官方任务模板完成 MeshStream SDK 接入、排错和 P2P 验收。
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# AI Coding
|
|
9
|
+
|
|
10
|
+
MeshStream 的 AI Coding 资料让 AI 编辑器基于官方 SDK 文档协助完成接入。当前页面提供可直接复制的任务模板;执行结果仍以本地构建、播放和真实 P2P 互传证据为准。
|
|
11
|
+
|
|
12
|
+
## 快速开始
|
|
13
|
+
|
|
14
|
+
在项目根目录打开 Codex、Cursor 或 Claude Code,先把下面的任务完整粘贴到对话框:
|
|
15
|
+
|
|
16
|
+
```text
|
|
17
|
+
请在当前项目中集成 MeshStream Web SDK。
|
|
18
|
+
|
|
19
|
+
执行顺序:
|
|
20
|
+
1. 识别项目框架、播放器、媒体协议和包管理器。
|
|
21
|
+
2. 阅读 MeshStream 官方 Web SDK 安装、快速接入、统计和故障排查文档。
|
|
22
|
+
3. 使用当前公开渠道可安装的精确 SDK 版本,不猜测不存在的 API、版本或配置项。
|
|
23
|
+
4. 复用现有播放器,不替换源站、CDN、DRM 或业务鉴权。
|
|
24
|
+
5. 保留 CDN 回退,并在播放结束、切源和页面销毁时释放 MeshStream 会话。
|
|
25
|
+
6. 修改代码后运行项目已有的构建和测试命令。
|
|
26
|
+
7. 报告修改文件、实际 SDK 版本、构建结果和仍未验证的事项。
|
|
27
|
+
|
|
28
|
+
如果项目中没有可播放的媒体地址或 SDK Key,先生成需要我补充的清单,不要写入凭据。
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Web 播放项目接入任务
|
|
32
|
+
|
|
33
|
+
对于 Vue、React 或原生 Web 项目,可以继续使用这段任务。它要求 AI 保持现有播放器控制权,并验证 P2P 失败时播放仍能继续:
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
在当前 Web 播放页面接入 MeshStream:
|
|
37
|
+
|
|
38
|
+
- 播放器:请根据项目实际代码填写,例如 hls.js、Shaka 或 dash.js。
|
|
39
|
+
- 协议:请根据实际媒体地址填写 HLS 或 DASH。
|
|
40
|
+
- 使用稳定的 contentId;不要把带签名参数的完整 URL 当作长期内容标识。
|
|
41
|
+
- SDK Key 从环境变量读取,不要提交到 Git、日志或页面源码。
|
|
42
|
+
- 保留现有 ABR、DRM、源站请求头和播放器生命周期。
|
|
43
|
+
- 加速初始化失败、Tracker 不可用或 Peer 超时必须回退 CDN。
|
|
44
|
+
- 页面隐藏、切换媒体和销毁播放器时调用对应的 dispose/release。
|
|
45
|
+
|
|
46
|
+
完成后输出:
|
|
47
|
+
1. 修改文件和依赖版本;
|
|
48
|
+
2. 构建与测试命令及结果;
|
|
49
|
+
3. CDN 播放结果;
|
|
50
|
+
4. P2P 是否真正传输;
|
|
51
|
+
5. 未执行的真机、跨网络或生产验收项。
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## P2P 验收任务
|
|
55
|
+
|
|
56
|
+
Peer 数量大于零只代表连接建立。需要两个使用同一内容标识的播放端,分别记录接收端下载和发送端上传字节:
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
请对当前 MeshStream 播放接入执行双端 P2P 验收:
|
|
60
|
+
|
|
61
|
+
1. 启动发送端并缓存至少一个可共享分片。
|
|
62
|
+
2. 再启动接收端,使用相同的 contentId、清晰度和媒体内容。
|
|
63
|
+
3. 记录带时间戳的 Peer 数、P2P 下载字节、P2P 上传字节、CDN 下载字节和 rebuffer 次数。
|
|
64
|
+
4. 只有接收端 P2P 下载字节增长且发送端 P2P 上传字节同步增长,才能报告真实互传通过。
|
|
65
|
+
5. 停止或阻断 P2P,确认播放器继续通过 CDN 播放。
|
|
66
|
+
6. 销毁两个会话,确认 WebSocket、Peer、监听器和定时器释放。
|
|
67
|
+
|
|
68
|
+
请将通过、失败、阻塞和未执行分别列出,不要用“Peer > 0”代替互传结论。
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## 故障排查任务
|
|
72
|
+
|
|
73
|
+
```text
|
|
74
|
+
请排查 MeshStream 播放正常但没有 P2P 的问题,按以下顺序检查:
|
|
75
|
+
|
|
76
|
+
1. SDK Key、应用状态、额度和 bootstrap 响应;
|
|
77
|
+
2. contentId、协议、清晰度和 swarm 是否一致;
|
|
78
|
+
3. Tracker WebSocket 握手、announce 和 Peer 发现时间;
|
|
79
|
+
4. WebRTC、ICE、浏览器权限和网络限制;
|
|
80
|
+
5. P2P 分片是否真的命中,以及超时后的 CDN 回退;
|
|
81
|
+
6. session dispose 后是否仍有连接或定时器。
|
|
82
|
+
|
|
83
|
+
输出每一步的证据、结论和下一步动作,不要通过关闭错误日志来掩盖问题。
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## 版本与凭据规则
|
|
87
|
+
|
|
88
|
+
- 只使用[选择 SDK](./sdk/overview.md)和对应安装页中已经公开的版本。
|
|
89
|
+
- SDK Key 放在本地环境变量或受限的运行时配置中,不提交仓库。
|
|
90
|
+
- 签名播放地址、Authorization、Cookie、SecretKey 和生产日志不要粘贴到 AI 对话中。
|
|
91
|
+
- AI 生成的代码必须经过构建、播放、真实互传、CDN 回退和释放验证后才能上线。
|
|
92
|
+
- 当前页面提供任务模板;官方 MCP 和可安装 Skills 会在版本索引、公开包和验收流程稳定后单独发布。
|
|
93
|
+
|
|
94
|
+
## 下一步
|
|
95
|
+
|
|
96
|
+
- [选择 SDK](./sdk/overview.md)
|
|
97
|
+
- [Web SDK 安装与配置](./sdk/web-setup.md)
|
|
98
|
+
- [Web SDK 快速接入](./sdk/web.md)
|
|
99
|
+
- [统计与用量](./concepts/statistics.md)
|
|
100
|
+
- [故障排查](./troubleshooting.md)
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 高级配置
|
|
3
|
+
sidebar_label: 高级配置
|
|
4
|
+
unlisted: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 高级配置
|
|
8
|
+
|
|
9
|
+
大多数客户不需要直接调用平台 API。安装 SDK 后,SDK 会使用内置的 Bootstrap 地址完成配置拉取、会话鉴权、Tracker 发现和用量上报;业务代码只需要传入控制台生成的 `key` 和播放地址。
|
|
10
|
+
|
|
11
|
+
## 默认配置
|
|
12
|
+
|
|
13
|
+
SaaS 版本默认使用:
|
|
14
|
+
|
|
15
|
+
```text
|
|
16
|
+
https://api.meshstream.net/config-api/v1/sdk/bootstrap
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
不要在业务代码中自行拼接 Access、Tracker 或 Event Collector 地址,也不要自行维护会话 Token。SDK 会根据 Bootstrap 返回的策略选择服务,并在 Token 临近过期时自动续期。
|
|
20
|
+
|
|
21
|
+
## 私有部署
|
|
22
|
+
|
|
23
|
+
只有私有化部署或企业专属网关才需要覆盖 Bootstrap 地址。Web、Android 和 iOS SDK 都提供了对应的高级配置字段:
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
bootstrapUrl / bootstrapURL
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
覆盖时填写完整的 `https://` 地址,例如:
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
https://p2p-api.example.com/v1/sdk/bootstrap
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
私有地址必须能够返回与 SaaS Bootstrap 兼容的配置,并通过 HTTPS 对外提供。普通 SaaS 客户保持默认值即可。
|
|
36
|
+
|
|
37
|
+
## Bootstrap 请求字段
|
|
38
|
+
|
|
39
|
+
SDK 会自动发送以下信息,客户无需手动组装请求:
|
|
40
|
+
|
|
41
|
+
| 字段 | 说明 |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `key` | 控制台签发的 SDK Key |
|
|
44
|
+
| `platform` | `web`、`android`、`ios` 或 `macos` |
|
|
45
|
+
| `contentId` | 可选,业务侧指定的稳定内容标识;不传时由 SDK 根据播放地址派生 |
|
|
46
|
+
|
|
47
|
+
SDK 不接受客户端传入的区域字段。服务端从 SDK Key 解析租户的 `homeRegion`,并从请求网络
|
|
48
|
+
推导访问侧的 `scheduling.region`、国家和运营商信息,用于 Tracker/ICE 就近调度。两者不是同一
|
|
49
|
+
个概念:`homeRegion` 决定租户的数据归属,访问侧调度不会改变数据驻留区域。
|
|
50
|
+
|
|
51
|
+
Bootstrap 成功响应会包含 `homeRegion`、`edgeRegion`、`primaryTrackerUrl`、`trackerUrls`、`iceServers` 和 `reportUrl`。
|
|
52
|
+
其中 `primaryTrackerUrl` 是服务端综合地域、健康状态、draining 和容量准入后选出的主 Tracker;
|
|
53
|
+
SDK 先连接主 Tracker,其余 `trackerUrls` 仅用于故障切换。
|
|
54
|
+
当请求到达错误的区域副本时,区域路由器应在请求进入 Config API 前完成转发;启用区域强校验的
|
|
55
|
+
副本会对错误归属返回 HTTP `421`,对无法解析 `homeRegion` 返回 HTTP `503`。SDK 不会根据响应
|
|
56
|
+
自行切换数据中心,播放仍应保留 CDN 兜底。
|
|
57
|
+
|
|
58
|
+
`iceServers` 由服务端按以下优先级选择:控制台为 SDK Key 或应用配置的自定义 ICE 列表优先;未配置时,
|
|
59
|
+
确认国家为中国大陆使用中国 ICE 池 `stun:stun.chat.bilibili.com:3478` 和
|
|
60
|
+
`stun:stun.miwifi.com:3478`;非中国或无法确认时使用海外池 `stun:stun.cloudflare.com:3478` 和
|
|
61
|
+
`stun:stun.l.google.com:19302`。SDK 客户端不应自行推断国家或覆盖 Bootstrap 返回的结果。
|
|
62
|
+
|
|
63
|
+
移动端还会自动采集包名、签名摘要等平台身份信息,用于控制台配置的应用校验。业务代码不需要设置 `tenantId`、`applicationId`、`packageName` 或内部节点地址。
|
|
64
|
+
|
|
65
|
+
## 播放与降级
|
|
66
|
+
|
|
67
|
+
Bootstrap 失败、Key 被停用或 P2P 暂时没有可用节点时,不应仅据此中断播放或替换当前播放地址。应用应继续使用各端 SDK 返回或管理的会话播放地址,媒体通过客户已有的交付路径保持可用。Bootstrap 只负责加速能力配置,不替代媒体源鉴权;媒体源的签名 URL、Cookie 和请求头仍由客户自己的源站策略负责。
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: SDK 错误与降级
|
|
3
|
+
sidebar_position: 2
|
|
4
|
+
unlisted: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# SDK 错误与降级
|
|
8
|
+
|
|
9
|
+
MeshStream 将 P2P 作为加速层,而不是播放可用性的前提。对于已创建的播放会话,Bootstrap、Tracker、上报或节点发现暂时不可用,不代表媒体播放失败;播放器应保留各端 SDK 返回或管理的当前播放地址,不要仅因加速状态变化而替换地址或中断播放。媒体仍通过客户已有的交付路径保持可用。
|
|
10
|
+
|
|
11
|
+
## 常见错误
|
|
12
|
+
|
|
13
|
+
| 错误 | 含义 | 处理建议 |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| `TRACKER_UNAVAILABLE` | 当前没有可用 Tracker 节点,或 WSS 连接失败 | 保持当前播放会话;检查 Key、网络权限、服务端路由和 Tracker 状态 |
|
|
16
|
+
| Bootstrap 失败 | 配置服务不可达或 Key 无效 | 保持正常播放;检查网络与控制台中 Key 状态 |
|
|
17
|
+
| HTTP `421` | 请求到达了不属于该租户 `homeRegion` 的区域副本 | 由全局路由器重试到正确中心;SDK 不自行切换中心 |
|
|
18
|
+
| HTTP `503 HOME_REGION_UNRESOLVED` | 服务端无法解析 SDK Key 的租户归属,或归属配置暂不可用 | 修复 SDK Key 的租户归属或服务端路由配置后重试;不要把客户端区域字段作为补救参数 |
|
|
19
|
+
| Admission 拒绝 | 平台身份不匹配或 Key 被禁用 | 检查控制台中 Key 的平台绑定与允许列表 |
|
|
20
|
+
| 统计上报失败 | SDK 的后台统计链路暂时不可达 | 无需处理;SDK 会异步重试或丢弃,不影响播放 |
|
|
21
|
+
|
|
22
|
+
更多错误细节请以对应 SDK 的运行时日志为准。
|
|
23
|
+
|
|
24
|
+
## 一次播放的处理阶段
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
initialize({ key })
|
|
28
|
+
→ 配置拉取与鉴权 SDK 自动完成
|
|
29
|
+
→ Peer 发现与信令 SDK 自动完成
|
|
30
|
+
→ 媒体交付 P2P 优先,客户现有交付路径保障可用性
|
|
31
|
+
→ 用量统计 SDK 后台异步完成
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
这些阶段不需要业务代码逐步调用,也不建议客户直接对接内部 Access、Tracker 或 Event Collector 服务。客户端不传入 `areaCode`、`area_code` 或 `region`;租户 `homeRegion` 和访问侧 `edgeRegion` 均由服务端决定。加速阶段出现故障时,已创建会话仍应保持正常播放。判断接入是否正确的标准是:**故意禁用 P2P 时,播放器依然能播完整个视频**。
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 最佳实践
|
|
3
|
+
sidebar_position: 3
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
import Tabs from '@theme/Tabs';
|
|
7
|
+
import TabItem from '@theme/TabItem';
|
|
8
|
+
|
|
9
|
+
# 最佳实践
|
|
10
|
+
|
|
11
|
+
MeshStream 不替换业务播放器或 CDN。生产接入应遵循四项原则:每次播放创建独立会话;始终使用 SDK 返回的播放地址;在内容切换和生命周期结束时释放会话;在上线前验证加速不可用时的正常播放路径。
|
|
12
|
+
|
|
13
|
+
## 所有平台通用
|
|
14
|
+
|
|
15
|
+
### 使用稳定的内容标识
|
|
16
|
+
|
|
17
|
+
播放地址含临时签名、Token 或追踪参数时,显式传入稳定的 `contentId`,例如 `movie-2026-001` 或 `live-channel-main`。不要把完整签名 URL 当作内容身份,否则同一内容无法稳定识别和复用。
|
|
18
|
+
|
|
19
|
+
### 服务端调度与降级验收
|
|
20
|
+
|
|
21
|
+
SDK 不需要传入区域代码。服务端根据 SDK Key 的租户归属和请求网络完成服务调度,业务代码不应自行拼接内部服务地址。上线前应完成一次降级验收:确认控制台出现会话,确认播放器使用 `playbackUrl`,再关闭 P2P 或阻断加速连接,验证媒体仍能通过现有 CDN 完整播放。
|
|
22
|
+
|
|
23
|
+
### 分片长度决定起播命中速度
|
|
24
|
+
|
|
25
|
+
HLS/DASH 的分片时长应结合播放器缓冲策略、直播延迟目标和 CDN 配置确定。通常可从约 1--2 秒开始评估;分片过长会延后共享建立,分片过短则可能增加请求和调度开销。Web SDK 的 DASH 点播可配置初始等待时间;直播场景应优先保证及时起播。需要关闭点播初始等待时,可显式设置 `httpDownloadInitialTimeoutMs: 0`。
|
|
26
|
+
|
|
27
|
+
## 按平台实践
|
|
28
|
+
|
|
29
|
+
<Tabs groupId="platform" queryString="platform">
|
|
30
|
+
<TabItem value="web" label="Web" default>
|
|
31
|
+
|
|
32
|
+
### 绑定已有播放器
|
|
33
|
+
|
|
34
|
+
`attach` 应绑定已有的 `<video>` 元素。页面切换、React 组件卸载或内容切换时,先释放旧会话,再创建新会话,避免多个会话同时占用连接和缓存。
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
const session = attach({
|
|
38
|
+
key: "your_sdk_key",
|
|
39
|
+
url: signedM3u8Url,
|
|
40
|
+
contentId: "movie-2026-001",
|
|
41
|
+
video,
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
await session.start();
|
|
45
|
+
// React useEffect cleanup、路由切换或切换视频时执行
|
|
46
|
+
session.dispose();
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
**播放器边界:** HLS/DASH 清单解析、ABR 和渲染仍由现有播放器负责。
|
|
50
|
+
|
|
51
|
+
**认证处理:** 使用 `originHeaders` 访问源站,不要将鉴权头暴露给 Peer。
|
|
52
|
+
|
|
53
|
+
**验收注意:** iOS Safari 没有 MSE 时使用原生 HLS,不能以 Web P2P 命中率作为验收条件。多个视频实例必须各自创建和释放会话。
|
|
54
|
+
|
|
55
|
+
</TabItem>
|
|
56
|
+
<TabItem value="android" label="Android">
|
|
57
|
+
|
|
58
|
+
### 将会话地址交给 Media3 / ExoPlayer
|
|
59
|
+
|
|
60
|
+
初始化 SDK 后,为每条播放内容创建会话,并将会话地址写入 `MediaItem`。播放器 `release()` 与会话 `close()` 应在页面或播放控制器销毁时一起调用。
|
|
61
|
+
|
|
62
|
+
```kotlin
|
|
63
|
+
val session = client.createPlaybackSession(
|
|
64
|
+
originUrl,
|
|
65
|
+
PlaybackOptions(contentId = "movie-2026-001"),
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
player.setMediaItem(MediaItem.fromUri(session.playbackUrl))
|
|
69
|
+
player.prepare()
|
|
70
|
+
player.play()
|
|
71
|
+
|
|
72
|
+
// onStop、切换内容或 ViewModel 清理时
|
|
73
|
+
session.close()
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
**错误处理:** 在 `onError` 中保持原有 CDN 播放兜底逻辑,不要将 P2P 初始化失败视为播放器错误。
|
|
77
|
+
|
|
78
|
+
**前后台:** 遵循应用现有的播放策略,SDK 不保证后台持续维持 Peer 连接。
|
|
79
|
+
|
|
80
|
+
**列表播放:** 只有实际可见、正在播放的项应保留会话。动态签名地址必须传稳定 `contentId`。
|
|
81
|
+
|
|
82
|
+
</TabItem>
|
|
83
|
+
<TabItem value="ios" label="iOS / macOS">
|
|
84
|
+
|
|
85
|
+
### 由播放器拥有者管理会话
|
|
86
|
+
|
|
87
|
+
`PlaybackSession` 应和 `AVPlayerItem` 处于同一生命周期:创建 item 前准备会话,替换 item 或页面销毁时关闭会话。不要只释放 `AVPlayer` 而遗留会话。
|
|
88
|
+
|
|
89
|
+
```objc
|
|
90
|
+
PlaybackSession *session = [client createPlaybackSessionWithURL:originURL error:nil];
|
|
91
|
+
AVPlayerItem *item = [AVPlayerItem playerItemWithURL:session.playbackUrl];
|
|
92
|
+
self.player = [AVPlayer playerWithPlayerItem:item];
|
|
93
|
+
[self.player play];
|
|
94
|
+
|
|
95
|
+
// 切换内容、dealloc 或退出播放页时
|
|
96
|
+
[session close];
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**播放器边界:** `AVPlayer` 原生支持 HLS;播放 DASH 时,由业务侧使用支持 DASH 的播放器。
|
|
100
|
+
|
|
101
|
+
**认证与标识:** 对签名 URL 使用稳定 `contentId`;源站认证信息仅通过 `originHeaders` 访问源站。
|
|
102
|
+
|
|
103
|
+
**平台差异:** iOS 和 macOS 使用同一套 Apple SDK,但播放器行为和后台策略应分别验证。
|
|
104
|
+
|
|
105
|
+
</TabItem>
|
|
106
|
+
<TabItem value="windows" label="Windows">
|
|
107
|
+
|
|
108
|
+
### 明确资源所有权和销毁顺序
|
|
109
|
+
|
|
110
|
+
Windows SDK 使用 C ABI。播放器应使用 `meshstream_session_get_playback_url` 返回的地址;停止播放后先销毁会话,再销毁客户端,防止持有失效的地址或统计句柄。
|
|
111
|
+
|
|
112
|
+
```c
|
|
113
|
+
meshstream_session_t* session = NULL;
|
|
114
|
+
meshstream_playback_options_t options = {0};
|
|
115
|
+
options.struct_size = sizeof(options);
|
|
116
|
+
options.version = MESHSTREAM_PLAYBACK_OPTIONS_VERSION;
|
|
117
|
+
options.content_id = "asset-12345";
|
|
118
|
+
meshstream_client_create_playback_session(client, playback_url, &options, &session, NULL);
|
|
119
|
+
|
|
120
|
+
const char* sdk_playback_url = meshstream_session_get_playback_url(session);
|
|
121
|
+
// 将 sdk_playback_url 交给 VLC、ffplay 或自研播放器
|
|
122
|
+
|
|
123
|
+
meshstream_session_destroy(session);
|
|
124
|
+
meshstream_client_destroy(client);
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
**播放器边界:** HLS/DASH 是否可播放由业务播放器决定,SDK 不负责解码和渲染。
|
|
128
|
+
|
|
129
|
+
**并发会话:** 每个播放器使用独立的 `meshstream_session_t`,不要跨内容复用句柄。
|
|
130
|
+
|
|
131
|
+
**退出顺序:** 等待播放器停止读取地址后再销毁 session;通过 `meshstream_session_get_stats` 读取快照,避免在播放器线程中阻塞统计读取。
|
|
132
|
+
|
|
133
|
+
</TabItem>
|
|
134
|
+
</Tabs>
|
|
135
|
+
|
|
136
|
+
## 常见遗漏
|
|
137
|
+
|
|
138
|
+
| 现象 | 优先检查 |
|
|
139
|
+
| --- | --- |
|
|
140
|
+
| 一直是 CDN | Key、HTTPS/WSS 网络权限、内容标识、可用 Peer,以及服务端 Tracker/ICE 调度状态 |
|
|
141
|
+
| 控制台没有统计 | 是否使用 `playbackUrl`、会话是否正常结束、是否过早释放应用进程 |
|
|
142
|
+
| 切换内容后异常 | 旧会话是否已释放,新内容是否创建了独立会话 |
|
|
143
|
+
| 签名地址无法聚合 | 是否传入稳定 `contentId`,而不是完整签名 URL |
|
|
144
|
+
|
|
145
|
+
需要更具体的 SDK 参数和 API,请查看 [Web](./sdk/web.md)、[Android](./sdk/android.md)、[iOS](./sdk/ios.md) 或 [Windows](./sdk/windows.md) 文档。
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 用量与计费
|
|
3
|
+
sidebar_position: 4
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 用量与计费
|
|
7
|
+
|
|
8
|
+
MeshStream 只按实际产生的 **P2P 下载流量**计入额度。
|
|
9
|
+
|
|
10
|
+
## 计量方式
|
|
11
|
+
|
|
12
|
+
- 计费对象:`p2pDownloaded`,也就是播放器实际从其他设备接收的 P2P 媒体字节。
|
|
13
|
+
- 不计费对象:CDN 回源流量、P2P 上传贡献,以及平台服务产生的控制和统计流量。
|
|
14
|
+
- CDN 回源费用仍按客户自己的 CDN 服务商规则结算。
|
|
15
|
+
- 计量维度:应用、Key、平台。
|
|
16
|
+
- 会话未结束或未调用 `dispose` 的播放不生成完整计量记录。
|
|
17
|
+
|
|
18
|
+
## 配额与套餐
|
|
19
|
+
|
|
20
|
+
- 每个应用在控制台有当前套餐的 P2P 下载用量配额。
|
|
21
|
+
- 每日赠送额度、签到奖励、套餐额度和加油包都只抵扣 P2P 下载流量。
|
|
22
|
+
- 当 P2P 未命中时,SDK 自动回到客户 CDN,播放继续但不会产生 MeshStream 额度扣减。
|
|
23
|
+
- 接近配额时,控制台会展示用量进度;超出后播放将自动回落至客户 CDN。
|
|
24
|
+
|
|
25
|
+
## 账单与支付
|
|
26
|
+
|
|
27
|
+
- 控制台提供账单、订阅和用量明细。
|
|
28
|
+
- 如需调整套餐或有大额流量计划,请在控制台联系平台方。
|
|
29
|
+
|
|
30
|
+
## 控制台字段口径
|
|
31
|
+
|
|
32
|
+
| 字段 | 作用 | 是否扣额度 |
|
|
33
|
+
| --- | --- | --- |
|
|
34
|
+
| P2P 下载流量 | 观察 P2P 实际分发效果 | 是 |
|
|
35
|
+
| CDN 回源流量 | 观察降级和命中率 | 否 |
|
|
36
|
+
| P2P 上传贡献 | 观察设备分享能力 | 否 |
|
|
37
|
+
|
|
38
|
+
命中率仍按 `P2P 下载流量 / (P2P 下载流量 + CDN 回源流量)` 计算,因此后台看到的 CDN 流量不会消失,只是不再混入额度扣减。
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Key、应用与内容标识
|
|
3
|
+
sidebar_label: 身份模型
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Key、应用与内容标识
|
|
7
|
+
|
|
8
|
+
- **应用**:控制台中的业务归属单元。应用下可以创建多个 SDK Key,并统一查看用量和播放数据。
|
|
9
|
+
- **SDK Key**:应用的客户端接入标识,可按平台创建多个。它不是管理员密码,也不应被当作服务端密钥使用。
|
|
10
|
+
- **内容标识**:用于判断不同播放请求是否属于同一内容。SDK 会根据播放地址自动识别;地址带动态签名时,可以传入稳定的 `contentId`。
|
|
11
|
+
|
|
12
|
+
SDK Key 可以出现在客户端代码中,但不能替代管理后台的管理员凭证。Key 是否启用、是否允许 P2P 和是否允许移动网络加速由平台配置控制。
|
|
13
|
+
|
|
14
|
+
## 常用术语
|
|
15
|
+
|
|
16
|
+
| 术语 | 统一含义 |
|
|
17
|
+
| --- | --- |
|
|
18
|
+
| Peer | 参与同一内容播放的其他设备;本设备可以从 Peer 下载,也可以向 Peer 上传已获取的媒体分片 |
|
|
19
|
+
| P2P 下载流量 | 本设备通过其他设备获取的媒体流量,也是 MeshStream 的计费流量 |
|
|
20
|
+
| P2P 上传贡献 | 本设备向其他设备分享的媒体流量,不计 MeshStream 额度 |
|
|
21
|
+
| CDN 回源 | P2P 不可用、未命中或超时时,从客户 CDN 获取媒体分片 |
|
|
22
|
+
| 播放地址 | 客户提供给 SDK 的原始媒体地址,通常是 HLS 的 `.m3u8` 或 DASH 的 `.mpd` |
|
|
23
|
+
| SDK 播放地址 | SDK 返回给播放器使用的播放地址;业务代码应使用它播放,不要重新拼接原始地址 |
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 多区域接入
|
|
3
|
+
sidebar_label: 多区域接入
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 多区域接入
|
|
7
|
+
|
|
8
|
+
SDK 不使用客户端区域枚举。平台从 SDK Key 解析租户的 `homeRegion`,作为账号、数据和未来控制面
|
|
9
|
+
路由的归属;同时根据请求网络推导访问侧 `edgeRegion`、国家和运营商,用于 Tracker/ICE 就近调度。
|
|
10
|
+
访问侧调度不会改变租户数据归属,也不会要求业务代码传入区域。
|
|
11
|
+
|
|
12
|
+
当前单中心部署由一个控制面、数据库、Redis、Access、Config、Event Collector 和 Tracker 统一负责。
|
|
13
|
+
扩展第二个中心前,需要先部署完整区域栈、完成健康检查和全局路由,再开启区域强校验。错误区域请求
|
|
14
|
+
返回 `421 Misdirected Request`,无法解析租户归属返回 `503`;SDK 不负责自行切换数据中心,CDN
|
|
15
|
+
回源始终作为播放兜底。
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 工作原理
|
|
3
|
+
sidebar_label: 工作原理
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
import Link from '@docusaurus/Link';
|
|
7
|
+
|
|
8
|
+
# 工作原理
|
|
9
|
+
|
|
10
|
+
MeshStream 不替换客户现有的播放器、源站或 CDN。SDK 为每次播放创建独立会话,在播放器和媒体网络之间协调分发路径:能够从其他播放设备获取时优先复用已有分片,否则继续从客户 CDN 获取。
|
|
11
|
+
|
|
12
|
+
## 一次播放的完整流程
|
|
13
|
+
|
|
14
|
+
```mermaid
|
|
15
|
+
flowchart LR
|
|
16
|
+
Player[业务播放器] -->|播放地址 + SDK Key| SDK[MeshStream SDK]
|
|
17
|
+
SDK -->|优先请求已有分片| Peer[其他播放设备]
|
|
18
|
+
Peer -->|返回可用分片| SDK
|
|
19
|
+
SDK -->|无可用设备或请求超时| CDN[客户 CDN]
|
|
20
|
+
CDN -->|返回媒体分片| SDK
|
|
21
|
+
SDK -->|交给播放器| Player
|
|
22
|
+
SDK -->|会话与流量数据| Console[用户控制台]
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
播放过程由 SDK 自动完成:
|
|
26
|
+
|
|
27
|
+
1. 播放器把原始 HLS 或 DASH 地址交给 SDK,并传入 SDK Key。
|
|
28
|
+
2. SDK 根据应用和内容识别播放会话,让观看同一内容的设备具备复用条件。
|
|
29
|
+
3. 每个分片请求根据可用设备、网络状态、播放器缓冲和响应速度选择来源。
|
|
30
|
+
4. 从其他设备获取的分片计入 P2P 下载流量;无法获取时自动从客户 CDN 获取。
|
|
31
|
+
5. 会话结束后,SDK 异步记录流量、连接和降级信息,客户在控制台查看结果。
|
|
32
|
+
|
|
33
|
+
## 两种分发路径
|
|
34
|
+
|
|
35
|
+
### 从其他设备获取
|
|
36
|
+
|
|
37
|
+
当同一应用下有其他设备已经获取了相同内容,并且网络条件允许连接时,SDK 可以从这些设备获取媒体分片。设备分享的上传流量不计 MeshStream 额度。
|
|
38
|
+
|
|
39
|
+
### 从客户 CDN 获取
|
|
40
|
+
|
|
41
|
+
以下情况会继续使用客户 CDN:
|
|
42
|
+
|
|
43
|
+
- 当前没有可用的其他设备;
|
|
44
|
+
- 网络环境不适合设备间连接;
|
|
45
|
+
- 分片请求超时或返回异常;
|
|
46
|
+
- SDK Key、应用策略或服务暂时不可用。
|
|
47
|
+
|
|
48
|
+
CDN 路径是播放兜底,不会因为加速能力暂时不可用而中断播放。CDN 回源流量由客户继续按照自己的 CDN 服务商规则结算。
|
|
49
|
+
|
|
50
|
+
## 对播放器的影响
|
|
51
|
+
|
|
52
|
+
- 播放器继续负责 HLS/DASH 清单解析、ABR、解码和渲染;
|
|
53
|
+
- 业务代码应播放 SDK 返回的 `playbackUrl`,不要重新拼接原始地址;
|
|
54
|
+
- 源站的签名 URL、Cookie、请求头和 DRM 策略继续由客户控制;
|
|
55
|
+
- 播放地址带动态签名时,可以传入稳定的 `contentId`,帮助不同会话识别同一内容;
|
|
56
|
+
- SDK 的加速状态不应作为停止播放的条件。
|
|
57
|
+
|
|
58
|
+
## 计量口径
|
|
59
|
+
|
|
60
|
+
| 数据 | 含义 | 是否扣 MeshStream 额度 |
|
|
61
|
+
| --- | --- | --- |
|
|
62
|
+
| P2P 下载流量 | 本设备从其他播放设备获取的媒体流量 | 是 |
|
|
63
|
+
| P2P 上传贡献 | 本设备向其他播放设备分享的媒体流量 | 否 |
|
|
64
|
+
| CDN 回源流量 | 本设备从客户 CDN 获取的媒体流量 | 否 |
|
|
65
|
+
|
|
66
|
+
命中率按 `P2P 下载流量 / (P2P 下载流量 + CDN 回源流量)` 计算,用于观察加速效果,不代表播放器只能使用其中一种路径。
|
|
67
|
+
|
|
68
|
+
## 接入后的验证方式
|
|
69
|
+
|
|
70
|
+
1. 使用同一应用下的 SDK Key 播放同一内容,确认播放器播放的是 SDK 返回的 `playbackUrl`。
|
|
71
|
+
2. 在控制台观察播放会话、Peer 数量和 P2P 下载流量。
|
|
72
|
+
3. 临时关闭 P2P 或断开网络,确认播放器仍能通过客户 CDN 完成播放。
|
|
73
|
+
|
|
74
|
+
下一步:[快速开始](../quickstart.md) · [SDK 接入](../sdk/web.md) · [统计与用量](./statistics.md)
|
|
75
|
+
|
|
76
|
+
## 场景与效果验证
|
|
77
|
+
|
|
78
|
+
- <Link to="/solutions/live-streaming">直播 P2P CDN 方案</Link>:先判断同内容并发、网络和延迟条件,再设计灰度与 CDN 回退验证。
|
|
79
|
+
- <Link to="/guides/reduce-video-cdn-cost">视频 CDN 成本优化与分流测量指南</Link>:区分分流字节与净成本,按可比业务窗口评估效果。
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 统计与用量
|
|
3
|
+
sidebar_position: 3
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
import Link from '@docusaurus/Link';
|
|
7
|
+
|
|
8
|
+
# 统计与用量
|
|
9
|
+
|
|
10
|
+
SDK 在播放过程中异步上报运行数据,在用户控制台按应用、Key 和平台聚合展示。上报是后台链路,失败不会影响播放。
|
|
11
|
+
|
|
12
|
+
## 上报维度
|
|
13
|
+
|
|
14
|
+
- **应用与 Key**:用量归属到具体应用和 Key,便于按业务或平台拆分。
|
|
15
|
+
- **平台**:Web / Android / Windows / iOS。
|
|
16
|
+
|
|
17
|
+
## 主要指标
|
|
18
|
+
|
|
19
|
+
| 指标 | 含义 |
|
|
20
|
+
| --- | --- |
|
|
21
|
+
| Peer 数 | 当前播放会话连接的其他设备数 |
|
|
22
|
+
| P2P 下载流量 | 经 P2P 分发的字节量,也是 MeshStream 的计费流量 |
|
|
23
|
+
| CDN 回源流量 | P2P 未命中时从客户 CDN 获取的字节量,仅用于效果和故障分析,不扣 MeshStream 额度 |
|
|
24
|
+
| P2P 上传贡献 | 当前设备向其他设备分享的字节量,不收费 |
|
|
25
|
+
| 命中率 | P2P 下载流量占 P2P 下载流量与 CDN 回源流量之和的比例 |
|
|
26
|
+
| 会话数 | 完成或活跃的播放会话数量 |
|
|
27
|
+
|
|
28
|
+
## CDN 分流率的计算与验证 {#offload-rate}
|
|
29
|
+
|
|
30
|
+
CDN 分流率按实际下载字节计算:
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
CDN 分流率 = P2P 下载流量 /(P2P 下载流量 + CDN 回源流量)× 100%
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
分流率不设固定承诺值,应以业务的实际统计结果为准。结果取决于同一内容的并发量、用户播放进度、用户之间的网络可达性、地域分布、媒体格式、分片时长和缓存策略。
|
|
37
|
+
|
|
38
|
+
验证时应使用相同应用和播放地址,启动多台真实设备持续播放,并分别记录 P2P 下载流量和 CDN 回源流量。直播与点播需要分开统计;预热阶段、异常退出和仅有单个观看用户的时段不应与稳定并发阶段混为一组。建议同时记录测试时间、设备数量、平台、区域、媒体协议和分片时长,确保不同轮次可以复现和比较。
|
|
39
|
+
|
|
40
|
+
## 查看方式
|
|
41
|
+
|
|
42
|
+
在用户控制台的用量与会话页面按时间范围和平台筛选。新会话数据通常在播放结束并调用 `dispose` 后完成上报;播放过程中即可看到实时活跃会话。
|
|
43
|
+
|
|
44
|
+
## 注意事项
|
|
45
|
+
|
|
46
|
+
- 播放结束后务必调用 `dispose` / `close`,未释放的会话不会生成完整统计。
|
|
47
|
+
- 统计由 SDK 在后台异步完成,业务代码只需在播放结束时正确释放会话。
|
|
48
|
+
|
|
49
|
+
## 场景与效果验证
|
|
50
|
+
|
|
51
|
+
- <Link to="/solutions/live-streaming">直播 P2P CDN 方案</Link>:先判断同内容并发、网络和延迟条件,再设计灰度与 CDN 回退验证。
|
|
52
|
+
- <Link to="/guides/reduce-video-cdn-cost">视频 CDN 成本优化与分流测量指南</Link>:区分分流字节与净成本,按可比业务窗口评估效果。
|
package/content/intro.md
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
---
|
|
2
|
+
sidebar_position: 1
|
|
3
|
+
title: 简介
|
|
4
|
+
description: 面向 Web、Android、iOS 与 Windows 播放场景的 P2P 媒体加速平台。
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 简介
|
|
8
|
+
|
|
9
|
+
MeshStream 是面向视频、直播和音频业务的 P2P 媒体加速平台。它以 SDK 的形式接入现有播放链路,在不替换播放器、源站和 CDN 的前提下,为可复用的媒体分片提供额外的传输路径。
|
|
10
|
+
|
|
11
|
+
## 产品定位
|
|
12
|
+
|
|
13
|
+
热点内容会在短时间内产生大量相同的媒体请求。MeshStream 允许符合策略和网络条件的观看设备复用已获取的媒体分片,从而降低热点内容对 CDN 带宽的集中压力。P2P 是可控的增强路径,CDN 始终保留为稳定的播放路径。
|
|
14
|
+
|
|
15
|
+
MeshStream 不改变业务应用对播放器、源站、DRM 或 CDN 的既有所有权和控制边界:播放器继续负责清单解析、ABR、解码和渲染;源站继续负责媒体授权;CDN 继续提供完整的可用性保障。
|
|
16
|
+
|
|
17
|
+
## 播放会话模型
|
|
18
|
+
|
|
19
|
+

|
|
20
|
+
|
|
21
|
+
每次播放都应创建一个独立的会话,标准流程如下:
|
|
22
|
+
|
|
23
|
+
1. 业务应用将原始媒体地址和 SDK Key 交给 SDK;
|
|
24
|
+
2. SDK 创建播放会话,并返回本次会话对应的播放地址;
|
|
25
|
+
3. 业务播放器加载 SDK 返回的播放地址,继续执行原有播放流程;
|
|
26
|
+
4. 会话结束、切换内容或页面销毁时,业务应用释放该会话。
|
|
27
|
+
|
|
28
|
+
SDK 会根据内容标识、网络条件和服务策略选择可用的传输路径。加速能力暂不可用时,播放器仍可通过原有 CDN 路径继续播放。
|
|
29
|
+
|
|
30
|
+
## 接入边界
|
|
31
|
+
|
|
32
|
+
- **播放器保持不变**:SDK 不接管 ABR、解码、渲染或 DRM。播放器必须继续支持业务使用的媒体格式。
|
|
33
|
+
- **跨平台统一**:同一应用可接入 Web、Android、iOS 和 Windows SDK,使用统一的 Key、内容标识和统计口径。
|
|
34
|
+
- **媒体格式**:HLS 和 DASH 由业务播放器负责解析;MP4、MP3 直链是否启用加速,取决于平台能力、Service Worker(Web)和源站 Range 支持。
|
|
35
|
+
- **鉴权责任清晰**:签名 URL、Cookie、Authorization、源站请求头和 DRM 仍由业务方的媒体服务负责。源站凭证不会发送给其他观看设备。
|
|
36
|
+
- **故障隔离**:配置、网络或加速连接异常不应阻断播放器。业务代码不应把“加速不可用”当作“媒体不可播放”处理。
|
|
37
|
+
|
|
38
|
+
## 统计与用量
|
|
39
|
+
|
|
40
|
+
SDK 在播放过程中异步记录会话状态、P2P 传输、CDN 传输、Peer 数量和异常原因,并在控制台按应用、Key、平台和内容维度聚合展示。
|
|
41
|
+
|
|
42
|
+
MeshStream 的额度仅按实际产生的 P2P 下载流量计算。未命中 P2P 时,播放仍可使用业务方 CDN;相关 CDN 传输数据用于效果分析和故障诊断,不计入 MeshStream 的 P2P 额度。
|
|
43
|
+
|
|
44
|
+
## 适用场景
|
|
45
|
+
|
|
46
|
+
- 直播、点播、赛事和大型活动等具有明显重复观看特征的内容;
|
|
47
|
+
- 需要降低热点内容 CDN 峰值带宽或缓解源站压力的业务;
|
|
48
|
+
- 希望在保留现有播放器和 CDN 的基础上,以灰度方式引入 P2P 能力的团队。
|
|
49
|
+
|
|
50
|
+
## 推荐阅读顺序
|
|
51
|
+
|
|
52
|
+
1. [快速开始](./quickstart.md):创建 Key,完成一次最小接入并验证播放链路;
|
|
53
|
+
2. [选择 SDK](./sdk/overview.md):按平台进入“安装与配置 → 快速接入 → 高级用法”;
|
|
54
|
+
3. [核心概念](./concepts/p2p.md) 与 [最佳实践](./best-practices.md):了解内容标识、会话生命周期和上线验收要求。
|