@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,228 @@
1
+ ---
2
+ title: Android 高级用法
3
+ sidebar_label: 高级用法
4
+ pagination_label: "Android 高级用法"
5
+ ---
6
+
7
+ # Android 高级用法
8
+
9
+ 基础接入只需将 SDK 返回的 `playbackUrl` 交给 Media3 或 ExoPlayer。本页介绍多路播放、鉴权和运行时控制。
10
+
11
+ ## 直播与点播接入策略
12
+
13
+ SDK 自动识别直播/点播,[基础接入方式相同](./android.md)。播放期间可回传播放器状态,帮助 P2P 调度;不回传也可正常播放。
14
+
15
+ ### 直播
16
+
17
+ <span id="直播回传缓冲余量" />
18
+
19
+ <span id="缓冲反馈" />
20
+
21
+ 回传当前位置之后连续可播放的缓冲时长,帮助 SDK 调整 P2P 预取。例如播放到 60 秒、缓冲到 70 秒,应传 **10,000 毫秒**。直播起播位置与目标延迟由播放器设置。
22
+
23
+ ```kotlin
24
+ session.updateBufferedDurationMs(bufferedDurationMs)
25
+ ```
26
+
27
+ ### 点播(VOD)
28
+
29
+ <span id="点播另外回传播放位置" />
30
+
31
+ <span id="播放进度与缓冲反馈" />
32
+
33
+ 除缓冲时长外,回传当前播放位置,帮助 SDK 在已连接且拥有目标分片的 Peer 中优先选择进度接近的节点。Seek 完成后立即更新位置。
34
+
35
+ ```kotlin
36
+ session.updateCurrentPositionMs(positionMs)
37
+ session.updateBufferedDurationMs(bufferedDurationMs)
38
+ ```
39
+
40
+ 数值均为非负毫秒,缓冲时长不能跨越断档。播放器状态有效后通常每秒回传一次;关闭会话前停止回传并等待在途调用结束。
41
+
42
+ <span id="播放器状态回传" />
43
+
44
+ <span id="接入示例" />
45
+
46
+ <span id="播放器状态回传示例" />
47
+
48
+ <details>
49
+ <summary>完整播放器状态回传示例</summary>
50
+
51
+ 示例使用 `io.meshstream.sdk.PlaybackSession` 和 Media3 `Player`;`isLive` 是业务播放状态。
52
+
53
+ ```kotlin
54
+ fun syncPlaybackState(session: PlaybackSession, player: Player, isLive: Boolean) {
55
+ val positionMs = player.currentPosition
56
+ val bufferedEndMs = player.bufferedPosition
57
+ if (positionMs >= 0L && bufferedEndMs >= 0L) {
58
+ val bufferedMs = (bufferedEndMs - positionMs).coerceAtLeast(0L)
59
+ session.updateBufferedDurationMs(bufferedMs)
60
+ }
61
+ if (!isLive && positionMs >= 0L) {
62
+ session.updateCurrentPositionMs(positionMs)
63
+ }
64
+ }
65
+ ```
66
+
67
+ </details>
68
+
69
+ ## MP4 / MP3 直链播放
70
+
71
+ MP4 和 MP3 属于点播直链:播放器直接加载文件地址,而不是 HLS `.m3u8` 或 DASH `.mpd` 清单。为同一视频或音频设置稳定的 `contentId`;地址不带扩展名时,显式填写 `mimeType`。
72
+
73
+ ```kotlin
74
+ val session = client.createPlaybackSession(
75
+ "https://cdn.example.com/video/trailer.mp4",
76
+ PlaybackOptions(
77
+ contentId = "trailer-2026",
78
+ mimeType = "mp4",
79
+ ),
80
+ )
81
+
82
+ player.setMediaItem(MediaItem.fromUri(session.playbackUrl))
83
+ player.prepare()
84
+ player.play()
85
+ ```
86
+
87
+ MP3 只需将地址和 `mimeType` 分别替换为 `.mp3` 和 `"mp3"`,并使用支持音频播放的 Media3/ExoPlayer 实例。媒体源需要支持单 Range 请求并返回有效的 `Content-Range`。不满足该条件时,文件仍按原有方式播放,但不会启用加速。
88
+
89
+ ## 为每路播放单独配置
90
+
91
+ 一个 `P2pClient` 可以管理多个独立会话。动态签名地址请传入稳定的 `contentId`。
92
+
93
+ ```kotlin
94
+ val session = client.createPlaybackSession(
95
+ signedUrl,
96
+ PlaybackOptions(
97
+ contentId = "movie-2026-001",
98
+ mimeType = "m3u8",
99
+ originHeaders = mapOf("Authorization" to "Bearer $originToken"),
100
+ ),
101
+ )
102
+
103
+ player.setMediaItem(MediaItem.fromUri(session.playbackUrl))
104
+ player.prepare()
105
+ player.play()
106
+ ```
107
+
108
+ `originHeaders` 只用于请求客户媒体源,不会发送给其他观看设备。切换内容时先关闭旧会话,再创建新会话。
109
+
110
+ 码率和清晰度由 Media3 / ExoPlayer 管理,不需要业务代码传入表示层标识。
111
+
112
+ ## 预加载与内容切换
113
+
114
+ 显式 `preload` 是可选的 HLS/DASH 预热:后台获取清单与首个媒体分片,不会下载整部视频。它也可提前启动 Tracker/Peer 连接,但排队成功不保证 Peer 已连接或媒体已就绪。尚未播放的候选会话不会向 Peer 上传媒体。MP4/MP3 直链不使用这条显式预加载流程。
115
+
116
+ 保存候选会话,选中时复用其播放地址。关闭任一会话前,先停止状态回传、等待在途调用结束并取消其事件订阅,避免回调访问已关闭的会话。预加载不负责解码器准备,也不会渲染首帧。
117
+
118
+ 播放管理器持有可空的 `currentSession`、`nextSession` 字段,类型均为 `PlaybackSession?`。每个播放器独立管理自己的会话,以下步骤在播放器线程执行。
119
+
120
+ ### 准备候选内容
121
+
122
+ ```kotlin
123
+ val candidate = client.createPlaybackSession(
124
+ nextUrl,
125
+ PlaybackOptions(contentId = nextContentId, mimeType = "m3u8"),
126
+ )
127
+ val previous = nextSession
128
+ nextSession = candidate
129
+ previous?.close()
130
+ val queued = candidate.preload()
131
+ ```
132
+
133
+ `queued == true` 只表示预热已排队,不代表已完成。返回 `false` 本身不表示会话无法播放,仍可将其播放地址交给播放器。
134
+
135
+ ### 切换至候选内容
136
+
137
+ 先停止旧会话的状态回传与事件订阅,再停止并解除旧媒体,关闭旧会话并启用候选会话:
138
+
139
+ ```kotlin
140
+ val candidate = nextSession
141
+ if (candidate != null) {
142
+ player.stop()
143
+ player.clearMediaItems()
144
+ currentSession?.close()
145
+ currentSession = candidate
146
+ nextSession = null
147
+ player.setMediaItem(MediaItem.fromUri(candidate.playbackUrl))
148
+ player.prepare()
149
+ player.play()
150
+ }
151
+ ```
152
+
153
+ ### 取消候选内容
154
+
155
+ 仅关闭已丢弃的候选会话,当前播放不受影响:
156
+
157
+ ```kotlin
158
+ nextSession?.close()
159
+ nextSession = null
160
+ ```
161
+
162
+ ## 运行时控制
163
+
164
+ ```kotlin
165
+ // 临时关闭当前会话 P2P,播放器继续使用同一个播放地址。
166
+ session.setP2pEnabled(false)
167
+ session.setP2pEnabled(true)
168
+ ```
169
+
170
+ ## 事件与监控
171
+
172
+ ```kotlin
173
+ client.addEventListener(object : P2pEventListener {
174
+ override fun onP2pReady(sessionId: Long) = log("P2P ready: $sessionId")
175
+ override fun onP2pUnavailable(sessionId: Long, reason: P2pUnavailableReason) =
176
+ log("P2P unavailable: $sessionId, $reason")
177
+ override fun onCdnFallback(sessionId: Long, bytes: Long) =
178
+ log("CDN fallback: $bytes bytes")
179
+ override fun onPeerCountChanged(sessionId: Long, peerCount: Int) =
180
+ updatePeerCount(sessionId, peerCount)
181
+ })
182
+
183
+ val stats = session.statistics()
184
+ val offload = stats.downloadOffloadRatio
185
+ ```
186
+
187
+ `onP2pUnavailable` 只表示加速暂不可用。不要因该状态停止播放器。
188
+
189
+ <span id="接入验证" />
190
+
191
+ <details>
192
+ <summary>验证 P2P 效果</summary>
193
+
194
+ 1. 先用单设备确认正常播放、点播拖动,以及关闭 P2P 后仍能播放。
195
+ 2. 用两个设备播放同一内容,保持 `contentId` 一致;点播选择有重叠的播放进度,直播选择同一频道。媒体字节和时间轴应保持一致,不同资产或个性化清单不要复用同一个 ID。
196
+ 3. 检查回传单位为毫秒,并在媒体清单加载后持续更新。当前位置 60 秒、连续缓冲到 70 秒时,缓冲值应为 10,000 毫秒;点播 Seek 完成后立即更新位置。
197
+ 4. 在一段播放时间内观察 P2P 下载字节数与下载分担率的变化。仅有 Peer 连接不代表实际通过 P2P 下载了媒体;分片可用性、网络环境和平台策略都会影响结果。
198
+ 5. 关闭 P2P,确认播放器继续通过 CDN 播放。随后停止状态回传并取消事件订阅,再关闭会话,确认切换内容后没有继续调用已关闭的会话。
199
+
200
+ </details>
201
+
202
+ ## 网络与平台策略
203
+
204
+ SDK 不接受客户端区域参数。SDK 会自动识别 Wi-Fi、蜂窝网络和以太网,并由服务端结合请求网络
205
+ 和控制台策略决定是否启用加速。`p2pEnabled`、连接数量和超时是本地上限,
206
+ 服务端策略优先级更高。
207
+
208
+ ```kotlin
209
+ P2pConfig(
210
+ key = "your_sdk_key",
211
+ p2pEnabled = true,
212
+ maxPeerConnections = 12,
213
+ maxUploadPeers = 4,
214
+ maxDownloadPeers = 5,
215
+ requestTimeoutMs = 8_000,
216
+ )
217
+ ```
218
+
219
+ ## 生命周期与兜底
220
+
221
+ - 播放结束、切换媒体或页面销毁时调用 `session.close()`。
222
+ - 应用不再使用 SDK 时调用 `P2pSdk.shutdown()`。
223
+ - 加速初始化或媒体请求暂时不可用时,播放器继续使用会话的 `playbackUrl`;不要仅因加速状态变化而替换播放地址。
224
+ - 不要把 Key、源站 Token 或 `originHeaders` 写入日志。
225
+
226
+ ## 能力边界
227
+
228
+ SDK 负责播放会话和加速处理;Media3/ExoPlayer 负责清单解析、ABR、解码、渲染和播放器缓存。SDK 不替换播放器,也不承诺后台持续分享。
@@ -0,0 +1,139 @@
1
+ ---
2
+ title: Android SDK 安装与配置
3
+ sidebar_label: 安装与配置
4
+ description: "Android SDK 安装与配置指南:平台要求、依赖安装和应用设置。"
5
+ pagination_label: "Android SDK 安装与配置"
6
+ ---
7
+
8
+ # Android SDK 安装与配置
9
+
10
+ MeshStream Android SDK 为 Android 播放器增加 P2P 加速能力。应用继续使用自己的播放器,SDK 负责播放会话和加速处理。
11
+
12
+ ## 平台与最低版本
13
+
14
+ | 项目 | 当前发布支持 |
15
+ | --- | --- |
16
+ | Android 系统 | ARM32 / x86:Android 4.2(API 17)及以上;ARM64 / x86_64:Android 5.0(API 21)及以上 |
17
+ | CPU 架构 | `armeabi-v7a`、`arm64-v8a`、`x86`、`x86_64`(同一 universal AAR) |
18
+ | Java / Kotlin | Java 8 或 Kotlin 项目 |
19
+ | 示例播放器 | Media3 / ExoPlayer;由业务自行选择并管理 |
20
+
21
+ :::note 当前发布支持
22
+
23
+ `1.0.10` 在同一 Maven 包中提供四种 ABI,覆盖 ARM 真机及 ARM64、x86、x86_64 模拟器。历史 `1.0.8` 为 ARM32 / ARM64 包,`1.0.7` 为 ARM64 包,保持不变。
24
+
25
+ ARM32 / x86 构建目标为 API 17,ARM64 / x86_64 为 API 21;播放器可能有更高的系统要求,当前 Media3 Demo 需要 API 24。
26
+
27
+ :::
28
+
29
+ ## 接入前准备
30
+
31
+ 开始接入前,请准备:
32
+
33
+ - 控制台创建的 SDK Key;
34
+ - 一个支持目标媒体格式的播放器,例如 Media3/ExoPlayer;
35
+ - 一个可播放的 HLS `.m3u8`、DASH `.mpd`、支持 Range 的 MP4 或 MP3 地址;
36
+
37
+ 播放器仍负责清单解析、ABR、解码和渲染。SDK 不会替换播放器,也不会改变播放器的清晰度策略。
38
+
39
+ ## 工程配置
40
+
41
+ ### Java / Kotlin 编译目标
42
+
43
+ SDK 使用 Java 8 字节码。宿主工程需支持 Java 8 或更高版本;例如 Java 8 工程可在应用模块的 `build.gradle.kts` 中设置:
44
+
45
+ ```kotlin
46
+ android {
47
+ compileOptions {
48
+ sourceCompatibility = JavaVersion.VERSION_1_8
49
+ targetCompatibility = JavaVersion.VERSION_1_8
50
+ }
51
+ }
52
+ ```
53
+
54
+ 已使用 Java 11/17 或更高目标的项目保留原有设置,并使 Kotlin JVM 目标与 Java 编译目标一致。Flutter、React Native 和 Uniapp 工程还需满足对应框架的 JDK 要求。
55
+
56
+ ### 网络权限
57
+
58
+ Maven 发布包已声明以下权限,Gradle 会将其合并到应用 Manifest,无需动态申请:
59
+
60
+ | 权限 | 用途 |
61
+ | --- | --- |
62
+ | `android.permission.INTERNET` | 访问媒体源、加速服务和 Peer |
63
+ | `android.permission.ACCESS_NETWORK_STATE` | 检测网络类型及连接变化 |
64
+
65
+ SDK 接入不要求额外申请外部存储读写或 `ACCESS_WIFI_STATE` 权限。播放器、下载或其他业务功能需要的权限由应用单独配置。发布前可在 Android Studio 的 **Merged Manifest** 中确认上述网络权限未被宿主规则移除。
66
+
67
+ ## 添加依赖
68
+
69
+ MeshStream Android SDK 通过 Maven 发布。在项目的仓库配置中添加以下仓库,并在应用模块中声明依赖。以下示例使用 Kotlin DSL:
70
+
71
+ ```kotlin
72
+ repositories {
73
+ google()
74
+ mavenCentral()
75
+ maven {
76
+ url = uri("https://sdk.meshstream.net/maven")
77
+ content { includeGroup("io.meshstream") }
78
+ }
79
+ }
80
+
81
+ dependencies {
82
+ implementation("io.meshstream:meshstream-android-sdk:1.0.10")
83
+ }
84
+ ```
85
+
86
+ Gradle 会自动解析并下载 SDK 及其原生依赖,无需手工下载或复制 AAR。`1.0.10` 同时提供
87
+ `armeabi-v7a`、`arm64-v8a`、`x86` 和 `x86_64`,真机与模拟器使用同一 Maven 依赖。
88
+
89
+ 建议在生产项目中固定 SDK 版本,并将仓库地址集中配置在项目级构建文件中,便于统一维护。SDK 依赖坐标为
90
+ `io.meshstream:meshstream-android-sdk`,后续版本升级仅需调整版本号。
91
+
92
+ ### 允许本地播放代理
93
+
94
+ `session.playbackUrl` 使用设备本地的 `http://127.0.0.1:<port>/` 代理。Android 9 及以上的默认明文网络限制可能拦截该地址;即使源视频是 HTTPS,也需要允许播放器访问本地代理。
95
+
96
+ Android 7.0(API 24)及以上可在应用模块的 `src/main/res/xml/network_security_config.xml` 中仅放行回环地址,使 Debug 和 Release 均生效:
97
+
98
+ ```xml
99
+ <?xml version="1.0" encoding="utf-8"?>
100
+ <network-security-config>
101
+ <base-config cleartextTrafficPermitted="false" />
102
+ <domain-config cleartextTrafficPermitted="true">
103
+ <domain includeSubdomains="false">127.0.0.1</domain>
104
+ <domain includeSubdomains="false">localhost</domain>
105
+ </domain-config>
106
+ </network-security-config>
107
+ ```
108
+
109
+ 在 `AndroidManifest.xml` 的 `<application>` 中引用 `android:networkSecurityConfig="@xml/network_security_config"`。已有网络策略的项目请合并本地地址规则,保留业务原有配置。需要兼容 Android 6.0(API 23)时,该系统不支持按域名放行,需根据应用网络策略设置 `android:usesCleartextTraffic="true"`;API 24 及以上以网络安全配置为准。公网 HTTP 媒体源需要另行配置,HTTPS 媒体源无需为源站放行明文流量。
110
+
111
+ ## 混淆与内存
112
+
113
+ ### R8 / ProGuard
114
+
115
+ 正式 AAR 已包含 consumer ProGuard 规则,保护 SDK 公开 API 和 JNI 桥接。通过 Maven 集成并启用 R8 时,Gradle 会自动应用这些规则,无需复制其他 SDK 的保留规则。
116
+
117
+ 应用和播放器自身的混淆配置仍按各自要求设置。发布前使用实际开启压缩与混淆的 Release 包验证初始化、播放、统计和关闭流程。
118
+
119
+ ### 媒体缓存预算
120
+
121
+ 接入 SDK 默认无需设置 `android:largeHeap="true"`。该选项主要影响 Java/ART 堆,不能代替 native 内存控制,也不保证避免内存不足。
122
+
123
+ 通过 `P2pConfig.maxMemoryBytes` 设置每个客户端的媒体缓存预算,默认 `64 MiB`。内存敏感的应用可根据设备和业务需求调整,例如:
124
+
125
+ ```kotlin
126
+ val client = P2pSdk.create(
127
+ applicationContext,
128
+ P2pConfig(
129
+ key = "your_sdk_key",
130
+ maxMemoryBytes = 16L * 1024 * 1024,
131
+ ),
132
+ )
133
+ ```
134
+
135
+ 此预算仅约束 SDK 媒体缓存,不代表整个进程的内存上限;播放器、解码器、连接和临时请求仍有其他开销。多客户端的缓存预算需合并考虑,较小的预算也可能减少可供 P2P 复用的分片。切换播放内容或退出页面时及时关闭会话,并在不再使用时关闭客户端。
136
+
137
+ ## 下一步
138
+
139
+ 完成以上配置后,进入[快速接入](./android.md),创建会话、连接播放器,并在播放结束后释放资源。
@@ -0,0 +1,190 @@
1
+ ---
2
+ title: Android SDK 快速接入
3
+ sidebar_label: 快速接入
4
+ description: "Android SDK 快速接入指南:创建播放会话、连接播放器、查看状态并释放资源。"
5
+ pagination_label: "Android SDK 快速接入"
6
+ ---
7
+
8
+ # Android SDK 快速接入
9
+
10
+ MeshStream Android SDK 为 Android 播放器增加 P2P 加速能力。应用继续使用自己的播放器,SDK 负责播放会话和加速处理。
11
+
12
+ <span id="平台与最低版本" />
13
+ <span id="接入前准备" />
14
+ <span id="工程配置" />
15
+ <span id="java--kotlin-编译目标" />
16
+ <span id="网络权限" />
17
+ <span id="添加依赖" />
18
+ <span id="允许本地播放代理" />
19
+ <span id="混淆与内存" />
20
+ <span id="r8--proguard" />
21
+ <span id="媒体缓存预算" />
22
+
23
+ 运行代码前,请先完成[安装与配置](./android-setup.md),准备 SDK Key 和可播放媒体地址,并配置应用网络策略。
24
+
25
+ ## 快速开始
26
+
27
+ 按以下四步接入:初始化 Client、创建播放会话、将会话返回的播放地址交给播放器、播放结束后释放会话。
28
+
29
+ ### 1. 初始化 Client
30
+
31
+ ```kotlin
32
+ val client = P2pSdk.create(
33
+ applicationContext,
34
+ P2pConfig(key = "your_sdk_key"),
35
+ )
36
+ ```
37
+
38
+ ### 2. 创建会话并交给播放器
39
+
40
+ `originUrl` 是原始媒体地址。每次播放创建一个会话,并始终将 `session.playbackUrl` 交给播放器。会话地址会保留现有媒体播放链路;P2P 是否可用只影响加速状态,不决定是否使用该地址。
41
+
42
+ ```kotlin
43
+ val session = client.createPlaybackSession(
44
+ originUrl,
45
+ PlaybackOptions(contentId = "movie-2026-001"),
46
+ )
47
+
48
+ player.setMediaItem(MediaItem.fromUri(session.playbackUrl))
49
+ player.prepare()
50
+ player.play()
51
+ ```
52
+
53
+ ### 3. 播放结束时释放会话
54
+
55
+ ```kotlin
56
+ session?.close()
57
+ ```
58
+
59
+ ### 4. 应用不再使用 SDK 时释放 Client
60
+
61
+ ```kotlin
62
+ P2pSdk.shutdown()
63
+ ```
64
+
65
+ 加速暂不可用不会阻断播放,播放器仍使用会话返回的 `playbackUrl`。只有 SDK 初始化或会话创建因本地配置、资源或编程错误而抛出异常时,业务才可自行选择记录错误并直接播放 `originUrl`;这属于业务降级,不经过 SDK,也不会计入 SDK 用量统计。
66
+
67
+ ## 预加载下一条内容
68
+
69
+ 推荐流式内容列表为下一条候选内容先创建会话并调用 `preload()`。它只在后台预热 HLS/DASH 清单与首个分片,不等待网络,也不创建或驱动播放器。用户切换时复用同一个会话;候选内容不再需要时关闭它:
70
+
71
+ ```kotlin
72
+ val nextSession = client.createPlaybackSession(nextOriginUrl)
73
+ nextSession.preload()
74
+
75
+ // 用户切换到下一条时
76
+ player.setMediaItem(MediaItem.fromUri(nextSession.playbackUrl))
77
+ player.prepare()
78
+ player.play()
79
+
80
+ // 候选内容取消时
81
+ nextSession.close()
82
+ ```
83
+
84
+ ## 配置项
85
+
86
+ | 字段 | 默认值 | 说明 |
87
+ | --- | --- | --- |
88
+ | `key` | 必填 | 控制台签发的 SDK Key |
89
+ | `playbackUrl` | 空 | 仅作为旧兼容配置的 bootstrap 身份提示,不创建会话也不决定播放器地址;新接入请使用 `createPlaybackSession(originUrl)` 并设置稳定的 `contentId` |
90
+ | `contentId` | 空 | 稳定内容标识;动态签名地址建议显式设置 |
91
+ | `mimeType` | 空 | `m3u8`、`mpd`、`mp4` 或 `mp3`;扩展名不明显时可以指定 |
92
+ | `originHeaders` | 空 Map | 发往源站媒体请求的请求头,不会发送给其他设备 |
93
+ | `p2pEnabled` | `true` | 本地 P2P 开关;平台策略优先级更高 |
94
+ | `maxPeerConnections` | `12` | 同时连接的 Peer 数量上限 |
95
+ | `maxUploadPeers` | `4` | 本设备同时向其他设备分享内容的数量上限 |
96
+ | `maxDownloadPeers` | `5` | 本设备同时从其他设备获取内容的数量上限 |
97
+ | `requestTimeoutMs` | `8000` | 单个加速媒体请求的最长等待时间;超过后保持正常播放 |
98
+ | `maxMemoryBytes` | `64 MiB` | SDK 使用的媒体缓存上限 |
99
+ | `logLevel` | `NONE` | 日志级别:`NONE / ERROR / INFO / DEBUG` |
100
+
101
+ 移动端包名和签名信息由 SDK 自动读取,业务代码不需要配置。服务发现地址也由 SDK 内置。
102
+
103
+ SDK 不接受客户端区域参数。服务端从 SDK Key 解析租户 `homeRegion`,并根据可信请求网络信号确定访问侧 `edgeRegion` 用于 Tracker/ICE 调度;这不是数据驻留配置。不要在客户端添加 `areaCode`、`area_code` 或 `region`。严格多中心模式下,无法解析租户归属区域会返回 `503 HOME_REGION_UNRESOLVED`,请求到错误中心会返回 `421`;SDK 不会自行跨中心切换,所有加速失败仍保留会话播放链路。
104
+
105
+ ## 动态地址与源站请求头
106
+
107
+ 播放地址如果每次都带短期签名参数,建议传入稳定的 `contentId`:
108
+
109
+ ```kotlin
110
+ P2pConfig(
111
+ key = "your_sdk_key",
112
+ contentId = "asset-12345",
113
+ mimeType = "m3u8",
114
+ originHeaders = mapOf(
115
+ "Authorization" to "Bearer $originToken",
116
+ ),
117
+ )
118
+ ```
119
+
120
+ `originHeaders` 只用于访问客户源站,不会发送给其他设备。源站鉴权仍由客户自己的签名 URL、Cookie 或请求头策略负责。
121
+
122
+ ## 播放会话 API
123
+
124
+ | 方法 | 说明 |
125
+ | --- | --- |
126
+ | `createPlaybackSession(originUrl)` | 创建一个播放会话并返回 SDK 播放地址 |
127
+ | `preload()` | 异步预热 HLS/DASH 清单与首个分片;只用于候选会话,不会播放媒体。仅在本次成功排队时返回 `true` |
128
+ | `setP2pEnabled(enabled)` | 运行时开关 P2P,不影响 CDN 播放 |
129
+ | `updateBufferedDurationMs(value)` | 上报当前播放时间到缓冲前沿的时长,用于调整后台 P2P 预取 |
130
+ | `updateCurrentPositionMs(value)` | 上报当前播放位置;点播用于匹配进度接近的节点,seek 后应立即调用 |
131
+ | `statistics()` | 返回当前会话的流量和 Peer 数量快照 |
132
+ | `close()` | 结束会话并释放相关资源 |
133
+
134
+ 一个 `P2pClient` 可以管理多个独立播放会话。应用不再需要 SDK 时调用 `P2pSdk.shutdown()`。
135
+
136
+ ## 事件与统计
137
+
138
+ 初始化完成后可以读取服务端策略快照。该状态只用于展示和诊断,不能作为停止播放器的条件:
139
+
140
+ ```kotlin
141
+ val status = client.status
142
+ println(status.effectiveP2pEnabled)
143
+ println(status.reason)
144
+ println(status.configVersion)
145
+ println(status.trackerPoolReady)
146
+ ```
147
+
148
+ `accountEnabled`、`applicationEnabled`、`keyEnabled`、`platformEnabled` 和
149
+ `effectiveP2pEnabled` 分别表示账号、应用、Key、平台及最终 P2P 策略。
150
+ `trackerPoolReady` 表示服务端是否已准备好加速连接;为 `false` 时本次播放不启用加速。
151
+ 额度耗尽时
152
+ `quotaStatus` 会返回服务端状态,播放仍然保留 CDN 路径。
153
+
154
+ ```kotlin
155
+ client.addEventListener(object : P2pEventListener {
156
+ override fun onP2pReady(sessionId: Long) {}
157
+ override fun onPeerCountChanged(sessionId: Long, peerCount: Int) {}
158
+ override fun onStatistics(sessionId: Long, stats: P2pStats) {}
159
+ override fun onP2pUnavailable(sessionId: Long, reason: P2pUnavailableReason) {}
160
+ override fun onCdnFallback(sessionId: Long, bytes: Long) {}
161
+ })
162
+ ```
163
+
164
+ 所有回调都带 `sessionId`,方便一个 client 管理多个播放器时区分会话。P2P 状态事件只表示加速状态,不应作为停止播放的条件。
165
+
166
+ ## HLS、DASH 与 MP4/MP3 直链播放
167
+
168
+ - SDK 支持 HLS、DASH,以及带 Range 的 MP4/MP3 直链播放请求,但不负责格式解码。
169
+ - MP4/MP3 需要源站支持单 Range,并返回有效的 `Content-Range`;不满足条件时保持正常播放但不启用加速。
170
+ - 直链媒体地址没有 `.mp4` 或 `.mp3` 后缀时,请在 `PlaybackOptions` 中显式传入 `mimeType = "mp4"` 或 `mimeType = "mp3"`;播放器仍需支持对应格式。
171
+ - Android 应用需要使用支持对应格式的播放器,例如 Media3 HLS 或 Media3 DASH。
172
+ - Maven `1.0.10` 为四 ABI universal AAR:`armeabi-v7a` / `x86` 构建目标 API 17、`arm64-v8a` / `x86_64` 构建目标 API 21。
173
+ - 目标设备必须满足所选 ABI 的最低系统要求;播放器的系统下限需另行满足。
174
+ - `INTERNET` 和 `ACCESS_NETWORK_STATE` 权限由 SDK 包声明;应用仍应按自身工程规范确认网络权限。
175
+
176
+ ## 播放容错
177
+
178
+ 以下情况都只会关闭或降低 P2P 加速,不会阻断媒体播放:
179
+
180
+ - SDK Key 或应用校验失败;
181
+ - 当前没有可用 Peer;
182
+ - 网络条件不满足 P2P;
183
+ - P2P 分片请求超时或失败;
184
+ - 服务暂时不可用。
185
+
186
+ ## 下一步
187
+
188
+ [快速开始](../quickstart.md) · [最佳实践](../best-practices.md) · [故障排查](../troubleshooting.md)
189
+
190
+ 相关文档:[安装与配置](./android-setup.md) · [高级用法](./android-advanced.md)。