@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.
Files changed (40) hide show
  1. package/README.md +21 -2
  2. package/content/ai-coding.md +100 -0
  3. package/content/api/bootstrap.md +67 -0
  4. package/content/api/errors.md +34 -0
  5. package/content/best-practices.md +145 -0
  6. package/content/billing/usage.md +38 -0
  7. package/content/concepts/identity.md +23 -0
  8. package/content/concepts/multi-region.md +15 -0
  9. package/content/concepts/p2p.md +79 -0
  10. package/content/concepts/statistics.md +52 -0
  11. package/content/intro.md +54 -0
  12. package/content/legal/privacy.md +110 -0
  13. package/content/legal/terms.md +173 -0
  14. package/content/quickstart.md +198 -0
  15. package/content/sdk/android-advanced.md +228 -0
  16. package/content/sdk/android-setup.md +139 -0
  17. package/content/sdk/android.md +190 -0
  18. package/content/sdk/flutter-advanced.md +285 -0
  19. package/content/sdk/flutter-setup.md +123 -0
  20. package/content/sdk/flutter.md +91 -0
  21. package/content/sdk/ios-advanced.md +268 -0
  22. package/content/sdk/ios-setup.md +113 -0
  23. package/content/sdk/ios.md +156 -0
  24. package/content/sdk/overview.md +40 -0
  25. package/content/sdk/react-native-advanced.md +269 -0
  26. package/content/sdk/react-native-setup.md +86 -0
  27. package/content/sdk/react-native.md +52 -0
  28. package/content/sdk/uniapp-advanced.md +274 -0
  29. package/content/sdk/uniapp-setup.md +92 -0
  30. package/content/sdk/uniapp.md +55 -0
  31. package/content/sdk/web-advanced.md +241 -0
  32. package/content/sdk/web-setup.md +42 -0
  33. package/content/sdk/web.md +105 -0
  34. package/content/sdk/windows-advanced.md +237 -0
  35. package/content/sdk/windows-setup.md +53 -0
  36. package/content/sdk/windows.md +162 -0
  37. package/content/troubleshooting.md +122 -0
  38. package/package.json +21 -4
  39. package/src/catalog.mjs +164 -0
  40. package/src/server.mjs +43 -0
@@ -0,0 +1,92 @@
1
+ ---
2
+ title: Uniapp SDK 安装与配置
3
+ sidebar_label: 安装与配置
4
+ description: "Uniapp SDK 安装与配置指南:平台要求、依赖安装和应用设置。"
5
+ pagination_label: "Uniapp SDK 安装与配置"
6
+ ---
7
+
8
+ # Uniapp SDK 安装与配置
9
+
10
+ 当前 DCloud 插件版本为 `meshstream-p2p 1.0.7`,可从 [DCloud 插件市场](https://ext.dcloud.net.cn/plugin?name=meshstream-p2p)安装。插件用于 uni-app Vue 3 App,不提供播放器界面或解码器。
11
+
12
+ ## 接入准备
13
+
14
+ - HBuilderX 4.25+;
15
+ - 控制台创建的 uni-app 应用 SDK Key;
16
+ - 一个可播放的 HLS `.m3u8`、DASH `.mpd`、支持 Range 的 MP4 或 MP3 地址;
17
+ - 一个支持目标格式的 uni-app 播放器;
18
+ - Android 或 iOS 自定义基座/云打包环境。
19
+
20
+ 插件 Android 声明下限为 API 21,iOS 为 15.0。应用实际下限取插件、HBuilderX 基座、播放器和其他依赖的最高要求;当前示例使用 Android API 24。插件固定使用公开 Android SDK `io.meshstream:meshstream-android-sdk:1.0.10` 和 iOS `MeshStreamKit 1.0.10`。
21
+
22
+ Android 原生依赖包含 `armeabi-v7a`、`arm64-v8a`、`x86`、`x86_64` 四种 ABI。真机与模拟器需同时满足框架、HBuilderX 基座和播放器的系统及架构要求。
23
+
24
+ ## 安装
25
+
26
+ Android 权限与编译要求见[原生工程配置](./android-setup.md#工程配置),R8 和缓存预算见[混淆与内存](./android-setup.md#混淆与内存)。保留 HBuilderX 基座要求的 Java/Kotlin 编译目标。
27
+
28
+ 在 HBuilderX 中通过插件市场安装精确版本 `1.0.7`,或将已发布插件包解压到项目的 `uni_modules/meshstream-p2p/`,确保 `package.json` 直接位于该目录下。
29
+
30
+ 标准基座不包含该插件所需的原生 SDK。请使用自定义基座或云打包,并确保 Android Maven、iOS CocoaPods 能解析公开原生依赖。
31
+
32
+ ## 平台网络配置
33
+
34
+ SDK 返回的播放地址使用本机 HTTP 回环代理,即使原始媒体源为 HTTPS,播放器也需要访问该代理。
35
+
36
+ ### Android
37
+
38
+ 插件附带 Android Manifest 和回环地址网络策略。请保留插件的 `utssdk/app-android/AndroidManifest.xml` 与 `res/xml/` 资源;若宿主应用已有网络安全配置,应将回环规则合并到最终生效的策略中。
39
+
40
+ 需要由应用统一管理网络策略时,可创建 `nativeResources/android/res/xml/meshstream_app_network_security_config.xml`:
41
+
42
+ ```xml
43
+ <?xml version="1.0" encoding="utf-8"?>
44
+ <network-security-config>
45
+ <base-config cleartextTrafficPermitted="false" />
46
+ <domain-config cleartextTrafficPermitted="true">
47
+ <domain includeSubdomains="false">127.0.0.1</domain>
48
+ <domain includeSubdomains="false">localhost</domain>
49
+ </domain-config>
50
+ </network-security-config>
51
+ ```
52
+
53
+ 在应用项目根目录创建或合并 `AndroidManifest.xml`,将 `com.example.app` 替换为云打包时使用的 Android 包名:
54
+
55
+ ```xml
56
+ <?xml version="1.0" encoding="utf-8"?>
57
+ <manifest xmlns:android="http://schemas.android.com/apk/res/android"
58
+ xmlns:tools="http://schemas.android.com/tools"
59
+ package="com.example.app">
60
+ <application
61
+ android:networkSecurityConfig="@xml/meshstream_app_network_security_config"
62
+ tools:replace="android:networkSecurityConfig" />
63
+ </manifest>
64
+ ```
65
+
66
+ 已有策略时保留业务域名规则;公网 HTTP 媒体源需要单独配置,建议使用 HTTPS。上述按域名放行适用于 API 24 及以上;需要兼容 API 23 时参照 [Android 网络配置](./android-setup.md#允许本地播放代理)。配置文件的合并方式见 [DCloud Android 原生配置](https://uniapp.dcloud.net.cn/tutorial/app-nativeresource-android.html)。
67
+
68
+ ### iOS
69
+
70
+ 在应用项目根目录创建或合并 `Info.plist`,添加本地网络的 ATS 许可:
71
+
72
+ ```xml
73
+ <?xml version="1.0" encoding="UTF-8"?>
74
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
75
+ <plist version="1.0">
76
+ <dict>
77
+ <key>NSAppTransportSecurity</key>
78
+ <dict>
79
+ <key>NSAllowsLocalNetworking</key>
80
+ <true/>
81
+ </dict>
82
+ </dict>
83
+ </plist>
84
+ ```
85
+
86
+ 已有 ATS 字典时合并该键,保留其他限制。配置位置与合并方式见 [DCloud iOS 原生配置](https://uniapp.dcloud.net.cn/tutorial/app-nativeresource-ios.html)。
87
+
88
+ 修改 Android/iOS 原生网络配置后,需要重新制作自定义基座或云打包,并重新安装;页面热更新不会更新这些配置。
89
+
90
+ ## 下一步
91
+
92
+ 完成以上配置后,进入[快速接入](./uniapp.md),创建会话、连接播放器,并在播放结束后释放资源。
@@ -0,0 +1,55 @@
1
+ ---
2
+ title: Uniapp SDK 快速接入
3
+ sidebar_label: 快速接入
4
+ description: "Uniapp SDK 快速接入指南:创建播放会话、连接播放器、查看状态并释放资源。"
5
+ pagination_label: "Uniapp SDK 快速接入"
6
+ ---
7
+
8
+ # Uniapp SDK 快速接入
9
+
10
+ 当前 DCloud 插件版本为 `meshstream-p2p 1.0.7`,可从 [DCloud 插件市场](https://ext.dcloud.net.cn/plugin?name=meshstream-p2p)安装。插件用于 uni-app Vue 3 App,不提供播放器界面或解码器。
11
+
12
+ <span id="接入准备" />
13
+ <span id="安装" />
14
+ <span id="平台网络配置" />
15
+ <span id="android" />
16
+ <span id="ios" />
17
+
18
+ 运行代码前,请先完成[安装与配置](./uniapp-setup.md),准备 SDK Key 和可播放媒体地址,并配置应用网络策略。
19
+
20
+ ## 最小接入
21
+
22
+ JavaScript 页面使用插件提供的入口:
23
+
24
+ ```ts
25
+ import { MeshStream } from '@/uni_modules/meshstream-p2p/javascript.js'
26
+
27
+ const client = await MeshStream.create({
28
+ key: 'your_sdk_key',
29
+ p2pEnabled: true,
30
+ })
31
+ const session = await MeshStream.createPlaybackSession(client.clientId, {
32
+ url: 'https://cdn.example.com/live/playlist.m3u8',
33
+ contentId: 'live-channel-42',
34
+ mimeType: 'm3u8',
35
+ })
36
+
37
+ // 将 session.playbackUrl 绑定到现有 video 播放器。
38
+ await MeshStream.updateCurrentPositionMs(client.clientId, session.sessionId, positionMs)
39
+ await MeshStream.updateBufferedDurationMs(client.clientId, session.sessionId, bufferedDurationMs)
40
+ ```
41
+
42
+ 切换内容或页面销毁时:
43
+
44
+ ```ts
45
+ await MeshStream.closeSession(client.clientId, session.sessionId)
46
+ await MeshStream.closeClient(client.clientId)
47
+ ```
48
+
49
+ P2P 不可用时仍会通过 CDN 播放。预加载使用 `await MeshStream.preload(client.clientId, session.sessionId)`;事件使用 `subscribeEvents` 注册并用 `unsubscribeEvents` 取消。
50
+
51
+ ## 版本与验证
52
+
53
+ Uniapp 插件版本独立于 Android/iOS 原生 SDK 版本。遇到问题时同时记录插件版本、HBuilderX 版本、基座、平台和播放器版本。示例与发布记录见 [Uniapp SDK GitHub 仓库](https://github.com/Mesh-Stream/meshstream-p2p-uniapp-sdk)。
54
+
55
+ 相关文档:[安装与配置](./uniapp-setup.md) · [高级用法](./uniapp-advanced.md)。
@@ -0,0 +1,241 @@
1
+ ---
2
+ title: Web SDK 高级用法
3
+ sidebar_label: 高级用法
4
+ pagination_label: "Web SDK 高级用法"
5
+ ---
6
+
7
+ # Web SDK 高级用法
8
+
9
+ 本页用于已完成 [基础接入](./web.md) 后的生产配置。Service Worker、已有播放器适配、动态地址与鉴权、低延迟调优、诊断和灰度发布均属于高级能力,不影响基础播放链路。
10
+
11
+ ## Service Worker 传输
12
+
13
+ Service Worker 是可选传输层,不是 Web SDK 的前置条件。默认情况下 SDK 优先使用浏览器可用的加速方式;当 Service Worker 不可用时,当前会话仍通过既有媒体交付路径正常播放。
14
+
15
+ 先执行 `npm run build:web-sdk:release`,将发布包中的 `dist/meshstream-sw.js` 部署到与页面同源的 HTTPS 路径,例如 `/meshstream-sw.js`。`localhost` 可用于本地开发。
16
+
17
+ ```ts
18
+ import { attach } from "@meshstream/p2p-web";
19
+
20
+ const session = attach({
21
+ key,
22
+ url,
23
+ video,
24
+ transportPreference: "auto",
25
+ serviceWorker: {
26
+ url: "/meshstream-sw.js",
27
+ scope: "/",
28
+ autoRegister: true,
29
+ p2pTimeoutMs: 5000,
30
+ onSegmentStats: ({ source, bytes }) => {
31
+ console.debug("MeshStream segment", source, bytes);
32
+ },
33
+ },
34
+ });
35
+
36
+ await session.start();
37
+ ```
38
+
39
+ | `transportPreference` | 适用场景 |
40
+ | --- | --- |
41
+ | `auto` | 默认值。优先 MSE,必要时使用可用的 Service Worker。 |
42
+ | `mse` | 仅使用 MSE 加速;用于回滚 Service Worker 方案。 |
43
+ | `service-worker` | 强制验证 Worker 路径,仅建议灰度和兼容性测试。 |
44
+ | `cdn` | 关闭当前会话的加速,用于播放对照和应急处理。 |
45
+
46
+ Service Worker 只能控制同源且由其 `scope` 覆盖的页面。`onSegmentStats` 中的 `source` 表示当前分片是否使用了加速,可用于评估实际效果。
47
+
48
+ ### 上线验收
49
+
50
+ 1. 验证 Worker 脚本可通过 HTTPS 访问,且页面位于其 `scope` 内。
51
+ 2. 使用 `auto` 验证正常播放,并确认关闭加速后播放仍正常。
52
+ 3. 在两个同时播放同一内容的测试端确认出现 P2P 下载流量,不要只看连接数量。
53
+ 4. 灰度使用 `service-worker`,确认失败时仍可播放;回滚时移除 `serviceWorker` 配置或切换为 `mse`。
54
+
55
+ ## 动态地址与源站鉴权
56
+
57
+ 签名 URL 每次变化时,使用稳定的 `contentId` 标识同一内容,以保持加速效果。`originHeaders` 仅用于请求客户媒体源,不会发送给其他观看设备。
58
+
59
+ ```ts
60
+ const session = attach({
61
+ key,
62
+ url: signedM3u8Url,
63
+ contentId: "asset-12345",
64
+ video,
65
+ originHeaders: {
66
+ Authorization: `Bearer ${token}`,
67
+ "X-Playback-Session": playbackSession,
68
+ },
69
+ });
70
+
71
+ await session.start();
72
+ window.addEventListener("pagehide", () => session.dispose(), { once: true });
73
+ ```
74
+
75
+ 令牌在播放期间轮换时使用同步的 `originHeadersProvider`。回调不能返回 `Promise`,业务应先刷新本地令牌状态:
76
+
77
+ ```ts
78
+ const session = attach({
79
+ key,
80
+ url: signedM3u8Url,
81
+ video,
82
+ originHeadersProvider: ({ kind }) =>
83
+ kind === "segment" ? { Authorization: `Bearer ${currentToken}` } : undefined,
84
+ });
85
+ ```
86
+
87
+ 浏览器仍会执行 CORS 与受限请求头规则。跨域媒体请求保持原有请求方式,不会附加 SDK 配置的鉴权头;不要把源站 Token、Cookie 或签名 URL 写入日志。
88
+
89
+ ## MP4 / MP3 直链播放
90
+
91
+ 这里的“直链播放”是指播放器直接加载一个 `.mp4` 或 `.mp3` 文件地址,而不是加载 HLS `.m3u8` 或 DASH `.mpd` 清单。MP4 和 MP3 的加速仅通过同源 Service Worker 启用;不满足使用条件时,当前会话仍通过既有媒体交付路径正常播放。
92
+
93
+ 接入前必须满足以下条件:
94
+
95
+ - 页面与 Worker 使用 HTTPS(`localhost` 开发环境除外),且 Worker 已激活并控制页面;
96
+ - Worker 与页面同源,且站点已部署 `meshstream-sw.js`;SDK 会为直链媒体默认尝试注册 Worker,也可使用前文的 `serviceWorker` 显式设置路径与 scope;
97
+ - 源站支持单 Range 请求,并正确返回 `Content-Range`;
98
+ - 跨源媒体响应暴露 `Content-Length`、`Content-Type`、`Accept-Ranges`,并允许 `Range` 请求头。
99
+
100
+ 下面示例分别展示视频和音频直链的接入方式;两者的 Service Worker 和源站条件相同。
101
+
102
+ ```ts title="MP4 视频"
103
+ const session = attach({
104
+ key,
105
+ url: "https://cdn.example.com/video/trailer.mp4",
106
+ contentId: "trailer-2026",
107
+ video: document.querySelector("video")!,
108
+ serviceWorker: {
109
+ url: "/meshstream-sw.js",
110
+ scope: "/",
111
+ autoRegister: true,
112
+ },
113
+ });
114
+
115
+ await session.start();
116
+ window.addEventListener("pagehide", () => session.dispose(), { once: true });
117
+ ```
118
+
119
+ ```ts title="MP3 音频"
120
+ const session = attach({
121
+ key,
122
+ url: "https://cdn.example.com/audio/episode-01.mp3",
123
+ contentId: "podcast-episode-01",
124
+ video: document.querySelector("audio")!,
125
+ serviceWorker: {
126
+ url: "/meshstream-sw.js",
127
+ scope: "/",
128
+ autoRegister: true,
129
+ },
130
+ });
131
+
132
+ await session.start();
133
+ window.addEventListener("pagehide", () => session.dispose(), { once: true });
134
+ ```
135
+
136
+ 无扩展名的受鉴权直链,请额外传入 `mimeType: "mp4"` 或 `mimeType: "mp3"`,避免浏览器无法通过地址判断媒体类型。
137
+
138
+ 整文件请求、后缀 Range、多 Range、媒体元数据或无法安全拆分的请求保持原有媒体请求方式。Worker 未启动或源站不满足 Range 条件时,SDK 不会阻断 MP4/MP3 播放,只是不启用加速。
139
+
140
+ ## 已有播放器适配
141
+
142
+ 业务已有播放器实例时,从适配器入口接入。SDK 仅接管 P2P 会话与媒体请求路径,播放器的 ABR、解码、渲染和销毁仍由业务负责。
143
+
144
+ ```ts
145
+ import Hls from "hls.js";
146
+ import { attachToHls } from "@meshstream/p2p-web/adapters";
147
+
148
+ const hls = new Hls({ maxBufferLength: 30 });
149
+ const session = attachToHls({ key, url, video, player: hls });
150
+
151
+ await session.start();
152
+ hls.loadSource(url);
153
+ hls.attachMedia(video);
154
+
155
+ window.addEventListener("pagehide", () => {
156
+ session.dispose();
157
+ hls.destroy();
158
+ }, { once: true });
159
+ ```
160
+
161
+ 必须在 `loadSource` 前调用 `session.start()`,以便第一批媒体请求可以参与加速。不要在同一媒体元素或同一播放地址上同时使用 `attach` 与 `attachToHls`。
162
+
163
+ | 接入方式 | 场景 | 说明 |
164
+ | --- | --- | --- |
165
+ | `attach` | 新页面或原生媒体元素 | 基础用法,SDK 创建并管理所需播放器。 |
166
+ | `attachToHls` | 业务已有 hls.js | 业务保留 hls.js 生命周期和 ABR 配置。 |
167
+ | `attachToShaka` | 已有 Shaka HLS/DASH 实例 | SDK 绑定 P2P 会话,业务销毁实例。 |
168
+ | `attachToDashJs` | dash.js `>=3.1.0 <6` | 在初始化前安装请求加载器。 |
169
+ | `attachToRxPlayer` | RxPlayer DASH | 常规音视频分片进入 P2P 请求路径。 |
170
+ | `attachToVhs` | Video.js VHS HLS | 需要同源 Service Worker。 |
171
+ | `attachToVideoJs`、Plyr、DPlayer、ArtPlayer | 媒体元素桥接 | 不是各播放器引擎的原生加载器插件。 |
172
+
173
+ 已有 Shaka 实例需要同时传入创建该实例的 `shakaLibrary`,让 P2P 请求插件注册到同一个播放器运行时:
174
+
175
+ ```ts
176
+ import shaka from "shaka-player";
177
+ import { attachToShaka } from "@meshstream/p2p-web/adapters";
178
+
179
+ const player = new shaka.Player();
180
+ await player.attach(video);
181
+ const session = attachToShaka({ key, url, player, shakaLibrary: shaka });
182
+ await session.start();
183
+ ```
184
+
185
+ ## HLS 与低延迟配置
186
+
187
+ SDK 自动识别直播和点播。未显式设置直播延迟时,识别到 HLS 直播媒体清单后使用 `liveSyncDurationCount: 3` 和 `liveMaxLatencyDurationCount: 6`,避免扩大同步窗口而增加直播延迟。
188
+
189
+ `hlsConfig` 是当前唯一由 Web SDK 对外暴露的播放器调优参数,用于 SDK 创建的 hls.js 实例。业务可通过它调整缓冲、ABR 或低延迟参数;已有 hls.js 实例应在创建时自行配置。DASH 没有等价的 `dashConfig`:使用 Shaka、dash.js 或 RxPlayer 时,继续在业务创建的播放器实例上配置。MP4/MP3 不使用播放器调优参数,固定走 Service Worker 的 Range 传输。
190
+
191
+ ```ts
192
+ const session = attach({
193
+ key,
194
+ url,
195
+ video,
196
+ hlsConfig: {
197
+ liveSyncDurationCount: 3,
198
+ liveMaxLatencyDurationCount: 6,
199
+ },
200
+ });
201
+ ```
202
+
203
+ 低延迟 HLS/DASH 的 CMAF 部分分片、DRM、字幕以及无法安全处理的 Range 请求保持播放器/CDN 原路径。SDK 只分发完整媒体分片,避免破坏播放器取消请求与延迟控制语义。
204
+
205
+ ## 运行时控制与可观测性
206
+
207
+ `setP2pEnabled(false)` 可以在播放期间关闭加速,不影响正常播放。`statistics()` 返回流量和错误计数;`diagnostics()` 返回最近的连接诊断;`qoe()` 返回可直接写入业务遥测的匿名质量快照。
208
+
209
+ ```ts
210
+ const unsubscribe = session.addEventListener({
211
+ onP2pReady() {
212
+ console.info("P2P ready");
213
+ },
214
+ onP2pUnavailable(reason) {
215
+ console.info("CDN fallback", reason);
216
+ },
217
+ onPeerCountChanged(count) {
218
+ updatePeerCount(count);
219
+ },
220
+ onStatistics(stats) {
221
+ reportDeliveryStats(stats);
222
+ },
223
+ });
224
+
225
+ const qoe = session.qoe();
226
+ // qoe.p2pDownloadRatio, qoe.firstPeerConnectMs, qoe.fallbackCount
227
+
228
+ window.addEventListener("pagehide", () => {
229
+ unsubscribe();
230
+ session.dispose();
231
+ }, { once: true });
232
+ ```
233
+
234
+ 诊断与统计上报失败不能影响播放器。请避免将 SDK Key、源站请求头、Cookie 或用户标识写入业务日志。
235
+
236
+ ## 生产边界
237
+
238
+ - SDK 负责播放会话和加速处理;播放器继续负责清单、ABR、解码、渲染和播放生命周期。
239
+ - 加速、网络、配置或统计出现问题时,保留当前会话管理的播放器地址;不要仅因加速状态变化而替换地址或停止播放。
240
+ - iPhone/iPad Safari 没有 MSE HLS P2P 路径,应使用原生 HLS 播放器配合同源 Service Worker 传输。仅当 Worker 未激活、未接管页面或运行条件不满足时,才回退至 CDN。macOS Safari 是否使用 MSE 路径取决于当前版本和运行时能力,应以 `getCapability()` 结果为准;如需统一验证 Worker 路径,可在受控灰度中设置 `transportPreference: "service-worker"`。
241
+ - MP4/MP3 仅对可安全拆分的单 Range 请求启用加速,其余请求保持原有播放方式。
@@ -0,0 +1,42 @@
1
+ ---
2
+ title: Web SDK 安装与配置
3
+ sidebar_label: 安装与配置
4
+ description: "Web SDK 安装与配置指南:平台要求、依赖安装和应用设置。"
5
+ pagination_label: "Web SDK 安装与配置"
6
+ ---
7
+
8
+ import Link from '@docusaurus/Link';
9
+
10
+ # Web SDK 安装与配置
11
+
12
+ MeshStream Web SDK 在不替换现有播放器的前提下,为 HLS、DASH 播放增加 P2P 加速;MP4 和 MP3 的加速仅在 Service Worker 可用时启用。播放器继续负责清单解析、ABR、解码与渲染;SDK 负责播放会话和加速处理。
13
+
14
+ ## 接入前准备
15
+
16
+ - 控制台创建的 SDK Key;
17
+ - 一个可播放的 HLS `.m3u8`、DASH `.mpd`、支持 Range 的 MP4 或 MP3 地址;
18
+ - 页面中的 `<video>` 或 `<audio>` 元素。
19
+
20
+ 安装 SDK:
21
+
22
+ ```bash
23
+ npm install @meshstream/p2p-web
24
+ ```
25
+
26
+ ## 浏览器与播放器接入选择
27
+
28
+ 先按浏览器能力选择传输路径,再按播放器所有权选择接入 API。`getCapability()` 可用于展示接入提示;最终是否启用 P2P 仍由浏览器环境和服务端策略共同决定。
29
+
30
+ | 环境 | HLS / DASH 接入 | P2P 路径 | 注意事项 |
31
+ | --- | --- | --- | --- |
32
+ | Chrome、Edge 等 Chromium 浏览器 | 新页面使用 `attach`;已有实例见高级页的 `attachToHls`、Shaka、dash.js 等适配器 | 优先 MSE + WebRTC | 推荐的 Web P2P 接入环境。 |
33
+ | Firefox | 使用 `attach` 或对应播放器适配器 | 浏览器同时支持 MSE、WebRTC 时启用 P2P | 以运行时能力检测结果为准。 |
34
+ | macOS Safari | 使用 `attach`,并以运行时能力检测为准;DASH 取决于宿主播放器能力 | 支持 MSE 时走常规 MSE + WebRTC;也可强制 Service Worker 灰度 | 不要按浏览器名称静态判断,先检查 `getCapability()`。 |
35
+ | iPhone/iPad Safari | HLS 使用原生 `<video>`,并部署同源 Service Worker | 原生播放器 + Service Worker P2P | iOS/iPadOS Safari 没有 MSE HLS P2P 路径。Worker 激活并接管页面后可启用 P2P;否则自动使用 CDN。 |
36
+ | MP4 / MP3 直链播放 | 将同源 Worker 脚本部署到站点;可在高级页显式配置路径和 scope | 仅同源 Service Worker + Range P2P | SDK 默认尝试注册 Worker。Worker 未激活、非 HTTPS 或源站不支持 Range 时,继续通过 CDN 播放。 |
37
+
38
+ 已有播放器不需要迁移:hls.js 使用 `attachToHls`,Shaka 使用 `attachToShaka`,dash.js 使用 `attachToDashJs`,Video.js VHS 使用 `attachToVhs`,RxPlayer 使用 `attachToRxPlayer`。这些适配器的初始化顺序和能力边界见 [高级用法](./web-advanced.md#已有播放器适配)。
39
+
40
+ ## 下一步
41
+
42
+ 完成以上配置后,进入[快速接入](./web.md),创建会话、连接播放器,并在播放结束后释放资源。
@@ -0,0 +1,105 @@
1
+ ---
2
+ title: Web SDK 快速接入
3
+ sidebar_label: 快速接入
4
+ description: "Web SDK 快速接入指南:创建播放会话、连接播放器、查看状态并释放资源。"
5
+ pagination_label: "Web SDK 快速接入"
6
+ ---
7
+
8
+ import Link from '@docusaurus/Link';
9
+
10
+ # Web SDK 快速接入
11
+
12
+ MeshStream Web SDK 在不替换现有播放器的前提下,为 HLS、DASH 播放增加 P2P 加速;MP4 和 MP3 的加速仅在 Service Worker 可用时启用。播放器继续负责清单解析、ABR、解码与渲染;SDK 负责播放会话和加速处理。
13
+
14
+ 本页只覆盖一条可稳定上线的最小接入链路。使用已初始化播放器、动态鉴权、Service Worker 或运行时诊断时,请进入 [高级用法](./web-advanced.md)。
15
+
16
+ <span id="接入前准备" />
17
+ <span id="浏览器与播放器接入选择" />
18
+
19
+ 运行代码前,请先完成[安装与配置](./web-setup.md),准备 SDK Key 和可播放媒体地址,并配置应用网络策略。
20
+
21
+ ## 最小接入
22
+
23
+ `attach` 是标准入口。SDK 根据媒体地址自动识别 HLS、DASH、MP4 或 MP3,并在内部创建所需的会话与传输路径:
24
+
25
+ ```ts
26
+ import { attach } from "@meshstream/p2p-web";
27
+
28
+ const session = attach({
29
+ key: "your_sdk_key",
30
+ url: "https://cdn.example.com/video/master.m3u8",
31
+ video: document.querySelector("video")!,
32
+ });
33
+
34
+ const result = await session.start();
35
+ console.log(result.mode);
36
+
37
+ window.addEventListener("pagehide", () => session.dispose(), { once: true });
38
+ ```
39
+
40
+ `start()` 返回当前实际使用的传输模式。加速暂不可用时,会话仍通过既有媒体交付路径保持播放;不要把加速状态视为播放失败,也不要仅据此替换播放器地址。
41
+
42
+
43
+ ## 基础配置
44
+
45
+ | 字段 | 必填 | 说明 |
46
+ | --- | --- | --- |
47
+ | `key` | 是 | 控制台签发的 SDK Key。 |
48
+ | `url` | 是 | 原始播放地址。HLS/DASH 使用常规接入;MP4/MP3 加速需要 Service Worker。 |
49
+ | `video` | 是 | 目标 `<video>` 或 `<audio>` 元素。 |
50
+ | `contentId` | 否 | 稳定的内容标识。播放地址带签名参数或会变化时建议填写。 |
51
+ | `mimeType` | 否 | 媒体类型提示:`m3u8`、`mpd`、`mp4` 或 `mp3`。通常无需填写。 |
52
+ | `autoplay` | 否 | 是否在播放器初始化后尝试自动播放。浏览器自动播放策略仍然生效。 |
53
+ | `p2pEnabled` | 否 | 传入 `false` 时,关闭本会话加速。 |
54
+
55
+ 对于无扩展名且受鉴权保护的播放地址,请显式设置 `mimeType`;对于会变化的签名 URL,请传入稳定的 `contentId`。更多鉴权与动态地址配置见 [高级用法](./web-advanced.md#动态地址与源站鉴权)。
56
+
57
+ ## 直播与点播
58
+
59
+ 无需指定“直播”或“点播”参数。SDK 会自动识别:HLS 根据媒体清单中的 `#EXT-X-ENDLIST`,DASH 根据 MPD 的 `type="dynamic"`,MP4/MP3 按点播处理。URL 后缀无法判断时,SDK 会探测源站 `Content-Type`;受鉴权保护的无后缀地址可显式传入 `mimeType`。
60
+
61
+ 直播请使用稳定的频道 ID,点播请使用稳定的节目或资产 ID:
62
+
63
+ ```ts
64
+ const session = attach({
65
+ key: "your_sdk_key",
66
+ url: liveUrl,
67
+ contentId: "live-channel-123",
68
+ video: document.querySelector("video")!,
69
+ });
70
+ ```
71
+
72
+ 识别结果同时用于调度与用量统计。直播缓冲与低延迟参数只适用于 hls.js,详见 [HLS 与低延迟配置](./web-advanced.md#hls-与低延迟配置);DASH 由 Shaka、dash.js 或业务自己的播放器配置管理,MP4/MP3 使用 Service Worker Range 传输并固定按点播处理。
73
+
74
+ ## 生命周期与播放连续性
75
+
76
+ 每次播放对应一个独立会话。播放结束、切换内容或页面销毁时调用 `dispose()`;再次播放新内容时创建新会话。
77
+
78
+ | 场景 | SDK 行为 |
79
+ | --- | --- |
80
+ | 浏览器不支持加速 | 保持当前会话管理的播放器地址,正常播放。 |
81
+ | 加速暂时不可用 | 自动保持正常播放。 |
82
+ | 服务端关闭 Key、应用或额度不可用 | 新会话保持正常播放,并提供诊断原因。 |
83
+ | 业务调用 `setP2pEnabled(false)` | 关闭本会话加速,播放不中断。 |
84
+
85
+ 可通过 `result.fallbackReason` 记录接入诊断,但不要因该字段停止播放器:
86
+
87
+ ```ts
88
+ const result = await session.start();
89
+ if (result.fallbackReason) {
90
+ console.info("MeshStream acceleration unavailable", result.fallbackReason);
91
+ }
92
+ ```
93
+
94
+ ## 下一步
95
+
96
+ - [Web SDK 高级用法](./web-advanced.md):Service Worker、动态地址、鉴权、播放器适配与可观测性。
97
+ - [最佳实践](../best-practices.md):上线前检查与播放链路边界。
98
+ - [故障排查](../troubleshooting.md):定位配置、网络和 Peer 问题。
99
+
100
+ ## 场景与效果验证
101
+
102
+ - <Link to="/solutions/live-streaming">直播 P2P CDN 方案</Link>:先判断同内容并发、网络和延迟条件,再设计灰度与 CDN 回退验证。
103
+ - <Link to="/guides/reduce-video-cdn-cost">视频 CDN 成本优化与分流测量指南</Link>:区分分流字节与净成本,按可比业务窗口评估效果。
104
+
105
+ 相关文档:[安装与配置](./web-setup.md) · [高级用法](./web-advanced.md)。