@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,268 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: iOS / macOS SDK 高级用法
|
|
3
|
+
sidebar_label: 高级用法
|
|
4
|
+
description: 配置 iOS 与 macOS 播放会话、媒体源鉴权、预加载及运行时控制。
|
|
5
|
+
pagination_label: "iOS / macOS SDK 高级用法"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# iOS / macOS SDK 高级用法
|
|
9
|
+
|
|
10
|
+
本文介绍播放会话管理、媒体源鉴权、预加载及运行时控制。首次接入请参阅[快速接入](./ios.md)。
|
|
11
|
+
|
|
12
|
+
示例代码在播放管理器的方法中执行,由 `self.client`、`self.session` 和 `self.player` 属性持有相关对象。替换当前播放会话前,先暂停播放器、解除旧媒体引用并关闭旧会话;仅在新会话创建成功后加载播放地址。
|
|
13
|
+
|
|
14
|
+
## 直播与点播接入策略
|
|
15
|
+
|
|
16
|
+
SDK 自动识别直播/点播,[基础接入方式相同](./ios.md)。播放期间可回传播放器状态,帮助 P2P 调度;不回传也可正常播放。
|
|
17
|
+
|
|
18
|
+
### 直播
|
|
19
|
+
|
|
20
|
+
<span id="直播回传缓冲余量" />
|
|
21
|
+
|
|
22
|
+
<span id="缓冲反馈" />
|
|
23
|
+
|
|
24
|
+
回传当前位置之后连续可播放的缓冲时长,帮助 SDK 调整 P2P 预取。例如播放到 60 秒、缓冲到 70 秒,应传 **10,000 毫秒**。直播起播位置与目标延迟由播放器设置。
|
|
25
|
+
|
|
26
|
+
```objc
|
|
27
|
+
[self.session updateBufferedDurationMs:bufferedMs];
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
### 点播(VOD)
|
|
31
|
+
|
|
32
|
+
<span id="点播另外回传播放位置" />
|
|
33
|
+
|
|
34
|
+
<span id="播放进度与缓冲反馈" />
|
|
35
|
+
|
|
36
|
+
除缓冲时长外,回传当前播放位置,帮助 SDK 在已连接且拥有目标分片的 Peer 中优先选择进度接近的节点。Seek 完成后立即更新位置。
|
|
37
|
+
|
|
38
|
+
```objc
|
|
39
|
+
[self.session updateCurrentPositionMs:positionMs];
|
|
40
|
+
[self.session updateBufferedDurationMs:bufferedMs];
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
数值均为非负毫秒,缓冲时长不能跨越断档。播放器状态有效后通常每秒回传一次;关闭会话前停止回传并等待在途调用结束。
|
|
44
|
+
|
|
45
|
+
<span id="直播与点播" />
|
|
46
|
+
|
|
47
|
+
<span id="播放器状态回传" />
|
|
48
|
+
|
|
49
|
+
<span id="接入示例" />
|
|
50
|
+
|
|
51
|
+
<span id="播放器状态回传示例" />
|
|
52
|
+
|
|
53
|
+
<span id="同步播放状态" />
|
|
54
|
+
|
|
55
|
+
<details>
|
|
56
|
+
<summary>完整播放器状态回传示例</summary>
|
|
57
|
+
|
|
58
|
+
在播放管理器中添加此方法。直播传 `YES`,点播传 `NO`;AVPlayer 的秒值在方法内转换为毫秒。
|
|
59
|
+
|
|
60
|
+
```objc
|
|
61
|
+
#include <math.h>
|
|
62
|
+
|
|
63
|
+
- (void)syncPlaybackStateForLiveStream:(BOOL)isLive {
|
|
64
|
+
if (!self.session || !self.player.currentItem) return;
|
|
65
|
+
CMTime currentTime = self.player.currentTime;
|
|
66
|
+
double positionSeconds = CMTimeGetSeconds(currentTime);
|
|
67
|
+
if (!isfinite(positionSeconds) || positionSeconds < 0) return;
|
|
68
|
+
|
|
69
|
+
int64_t bufferedMs = 0;
|
|
70
|
+
for (NSValue *value in self.player.currentItem.loadedTimeRanges) {
|
|
71
|
+
CMTimeRange range = value.CMTimeRangeValue;
|
|
72
|
+
if (CMTimeRangeContainsTime(range, currentTime)) {
|
|
73
|
+
double seconds = CMTimeGetSeconds(
|
|
74
|
+
CMTimeSubtract(CMTimeRangeGetEnd(range), currentTime));
|
|
75
|
+
if (isfinite(seconds) && seconds >= 0) {
|
|
76
|
+
bufferedMs = (int64_t)(seconds * 1000.0);
|
|
77
|
+
}
|
|
78
|
+
break;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
[self.session updateBufferedDurationMs:bufferedMs];
|
|
82
|
+
if (!isLive) {
|
|
83
|
+
[self.session updateCurrentPositionMs:(int64_t)(positionSeconds * 1000.0)];
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
</details>
|
|
89
|
+
|
|
90
|
+
## MP4 / MP3 文件播放
|
|
91
|
+
|
|
92
|
+
MP4 和 MP3 使用媒体文件地址接入。为同一媒体资源设置稳定的 `contentId`;地址不包含文件扩展名时,通过 `mimeType` 指定媒体类型。
|
|
93
|
+
|
|
94
|
+
```objc
|
|
95
|
+
P2PPlaybackOptions *options = [[P2PPlaybackOptions alloc] init];
|
|
96
|
+
options.contentId = @"trailer-2026";
|
|
97
|
+
options.mimeType = @"mp4";
|
|
98
|
+
|
|
99
|
+
NSError *error = nil;
|
|
100
|
+
self.session = [self.client createPlaybackSessionWithURL:
|
|
101
|
+
[NSURL URLWithString:@"https://cdn.example.com/video/trailer.mp4"]
|
|
102
|
+
options:options
|
|
103
|
+
error:&error];
|
|
104
|
+
if (self.session != nil) {
|
|
105
|
+
AVPlayerItem *item = [AVPlayerItem playerItemWithURL:self.session.playbackUrl];
|
|
106
|
+
self.player = [AVPlayer playerWithPlayerItem:item];
|
|
107
|
+
[self.player play];
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
MP3 接入时,将示例地址替换为 MP3 文件地址,并设置 `mimeType = @"mp3"`。
|
|
112
|
+
|
|
113
|
+
文件加速要求媒体源支持单区间 HTTP Range 请求,并返回有效的 `Content-Range`。媒体源不满足该条件时不启用加速,实际播放结果仍取决于媒体源与播放器。
|
|
114
|
+
|
|
115
|
+
## 多会话管理
|
|
116
|
+
|
|
117
|
+
一个 `P2PClient` 可管理多个独立的 `PlaybackSession`。每个播放器实例使用独立会话,切换内容时释放旧会话并创建新会话;已预加载的内容可直接使用对应的候选会话。
|
|
118
|
+
|
|
119
|
+
## 媒体源鉴权
|
|
120
|
+
|
|
121
|
+
媒体地址包含临时签名时,通过稳定的 `contentId` 标识同一资源。需要请求头鉴权的媒体源可使用 `originHeaders` 传入凭据;这些请求头仅用于访问媒体源,不发送至其他对等节点。
|
|
122
|
+
|
|
123
|
+
```objc
|
|
124
|
+
P2PPlaybackOptions *options = [[P2PPlaybackOptions alloc] init];
|
|
125
|
+
options.contentId = @"movie-2026-001";
|
|
126
|
+
options.mimeType = @"m3u8";
|
|
127
|
+
options.originHeaders = @{ @"Authorization": [NSString stringWithFormat:@"Bearer %@", originToken] };
|
|
128
|
+
|
|
129
|
+
NSError *error = nil;
|
|
130
|
+
self.session = [self.client createPlaybackSessionWithURL:signedOriginURL
|
|
131
|
+
options:options
|
|
132
|
+
error:&error];
|
|
133
|
+
if (self.session != nil) {
|
|
134
|
+
AVPlayerItem *item = [AVPlayerItem playerItemWithURL:self.session.playbackUrl];
|
|
135
|
+
[self.player replaceCurrentItemWithPlayerItem:item];
|
|
136
|
+
[self.player play];
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Token、Cookie 及完整签名 URL 按应用安全策略管理,日志与分析数据中应移除相关敏感信息。
|
|
141
|
+
|
|
142
|
+
## 预加载与内容切换
|
|
143
|
+
|
|
144
|
+
显式 `preload` 是可选的 HLS/DASH 预热:后台获取清单与首个媒体分片,不会下载整部视频。它也可提前启动 Tracker/Peer 连接,但排队成功不保证 Peer 已连接或媒体已就绪。尚未播放的候选会话不会向 Peer 上传媒体。MP4/MP3 直链不使用这条显式预加载流程。
|
|
145
|
+
|
|
146
|
+
保存候选会话,选中时复用其播放地址。关闭任一会话前,先停止状态回传、等待在途调用结束并取消其事件订阅,避免回调访问已关闭的会话。预加载不负责解码器准备,也不会渲染首帧。
|
|
147
|
+
|
|
148
|
+
预加载为可选能力,适用于信息流及连续播放等场景。将候选会话保存至 `PlaybackSession *nextSession` 属性,开始播放时直接复用该会话。
|
|
149
|
+
|
|
150
|
+
### 准备候选内容
|
|
151
|
+
|
|
152
|
+
```objc
|
|
153
|
+
[self.nextSession close];
|
|
154
|
+
NSError *error = nil;
|
|
155
|
+
self.nextSession = [self.client createPlaybackSessionWithURL:nextURL error:&error];
|
|
156
|
+
if (self.nextSession != nil) {
|
|
157
|
+
[self.nextSession preload];
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### 切换至候选内容
|
|
162
|
+
|
|
163
|
+
释放当前媒体引用及会话后,将候选会话设为当前会话,再加载其播放地址:
|
|
164
|
+
|
|
165
|
+
```objc
|
|
166
|
+
if (!self.nextSession) {
|
|
167
|
+
return;
|
|
168
|
+
}
|
|
169
|
+
[self.player pause];
|
|
170
|
+
[self.player replaceCurrentItemWithPlayerItem:nil];
|
|
171
|
+
[self.session close];
|
|
172
|
+
self.session = self.nextSession;
|
|
173
|
+
self.nextSession = nil;
|
|
174
|
+
AVPlayerItem *item = [AVPlayerItem playerItemWithURL:self.session.playbackUrl];
|
|
175
|
+
[self.player replaceCurrentItemWithPlayerItem:item];
|
|
176
|
+
[self.player play];
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### 取消候选内容
|
|
180
|
+
|
|
181
|
+
候选内容不再需要时,关闭其会话并释放引用:
|
|
182
|
+
|
|
183
|
+
```objc
|
|
184
|
+
[self.nextSession close];
|
|
185
|
+
self.nextSession = nil;
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
预加载会产生网络流量。`preload` 返回成功表示请求已接受,不代表媒体下载完成或首帧已渲染。
|
|
189
|
+
|
|
190
|
+
## 运行时控制
|
|
191
|
+
|
|
192
|
+
### 调整加速状态与读取统计
|
|
193
|
+
|
|
194
|
+
```objc
|
|
195
|
+
[self.session setP2PEnabled:NO]; // 临时关闭加速
|
|
196
|
+
[self.session setP2PEnabled:YES];
|
|
197
|
+
P2PStats *stats = [self.session statistics];
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
`setP2PEnabled:` 用于调整当前会话的 P2P 开关,实际加速能力仍受控制台策略约束。
|
|
201
|
+
|
|
202
|
+
## 事件与监控
|
|
203
|
+
|
|
204
|
+
```objc
|
|
205
|
+
@interface PlaybackObserver : NSObject <P2PEventListener>
|
|
206
|
+
@end
|
|
207
|
+
|
|
208
|
+
@implementation PlaybackObserver
|
|
209
|
+
- (void)onP2PReady { }
|
|
210
|
+
- (void)onP2PUnavailable:(P2PUnavailableReason)reason { }
|
|
211
|
+
- (void)onPeerCountChanged:(NSInteger)peerCount { }
|
|
212
|
+
- (void)onCdnFallbackWithBytes:(int64_t)bytes { }
|
|
213
|
+
- (void)onStatistics:(P2PStats *)stats { }
|
|
214
|
+
@end
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
将事件监听器保存至 `PlaybackObserver *observer` 属性,并在播放管理器中注册:
|
|
218
|
+
|
|
219
|
+
```objc
|
|
220
|
+
self.observer = [[PlaybackObserver alloc] init];
|
|
221
|
+
[self.client addEventListener:self.observer];
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
结束监听时,移除已注册的同一实例并释放引用:
|
|
225
|
+
|
|
226
|
+
```objc
|
|
227
|
+
[self.client removeEventListener:self.observer];
|
|
228
|
+
self.observer = nil;
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
加速事件和统计用于观测 SDK 运行状态;播放状态及播放控制由应用通过播放器接口管理。
|
|
232
|
+
|
|
233
|
+
<span id="接入验证" />
|
|
234
|
+
|
|
235
|
+
<details>
|
|
236
|
+
<summary>验证 P2P 效果</summary>
|
|
237
|
+
|
|
238
|
+
1. 先用单设备确认正常播放、点播拖动,以及关闭 P2P 后仍能播放。
|
|
239
|
+
2. 用两个设备播放同一内容,保持 `contentId` 一致;点播选择有重叠的播放进度,直播选择同一频道。媒体字节和时间轴应保持一致,不同资产或个性化清单不要复用同一个 ID。
|
|
240
|
+
3. 检查回传单位为毫秒,并在媒体清单加载后持续更新。当前位置 60 秒、连续缓冲到 70 秒时,缓冲值应为 10,000 毫秒;点播 Seek 完成后立即更新位置。
|
|
241
|
+
4. 在一段播放时间内观察 P2P 下载字节数与下载分担率的变化。仅有 Peer 连接不代表实际通过 P2P 下载了媒体;分片可用性、网络环境和平台策略都会影响结果。
|
|
242
|
+
5. 关闭 P2P,确认播放器继续通过 CDN 播放。随后停止状态回传并取消事件订阅,再关闭会话,确认切换内容后没有继续调用已关闭的会话。
|
|
243
|
+
|
|
244
|
+
</details>
|
|
245
|
+
|
|
246
|
+
## 应用与授权配置
|
|
247
|
+
|
|
248
|
+
使用对应平台的 SDK Key,并确保应用 Bundle ID 与控制台登记信息一致。SDK 自动读取 Bundle ID,无需额外配置服务地址。客户端及会话的 P2P 开关均受控制台策略约束;媒体源鉴权凭据由应用管理。
|
|
249
|
+
|
|
250
|
+
## 生命周期管理
|
|
251
|
+
|
|
252
|
+
### 资源释放
|
|
253
|
+
|
|
254
|
+
- 每个播放器使用独立的播放会话,每个会话对应一个媒体资源。
|
|
255
|
+
- 结束播放时,先暂停播放器并解除媒体引用,再关闭当前会话及不再需要的候选会话。
|
|
256
|
+
- 应用不再使用任何 SDK 客户端或会话时,调用 `+[P2PSDK shutdown]` 释放全局资源。
|
|
257
|
+
|
|
258
|
+
### 后台播放与画中画
|
|
259
|
+
|
|
260
|
+
后台播放与画中画需在应用及播放器中配置相应能力。应用自行管理画中画时,在实际开始和结束的回调中调用 `[session setPictureInPictureActive:YES]` 或 `NO` 同步状态。
|
|
261
|
+
|
|
262
|
+
后台或画中画播放继续期间,应保留相应播放器与会话。SDK 会话状态不替代操作系统要求的后台权限或音频会话配置。
|
|
263
|
+
|
|
264
|
+
## 兼容性与错误处理
|
|
265
|
+
|
|
266
|
+
SDK 负责媒体分发加速,播放器负责解码、渲染、缓冲及播放错误处理。第三方播放器使用会话返回的 `playbackUrl`,媒体格式、DRM 及后台能力由播放器、操作系统与应用配置共同决定。
|
|
267
|
+
|
|
268
|
+
`P2PUnavailableReason` 表示加速能力不可用,不是媒体播放错误。会话仍有效时继续使用其播放地址;播放是否需要重试或终止,应根据播放器错误及媒体源状态判断。SDK Key 鉴权与媒体源鉴权分别处理,后者失败时需按业务流程更新凭据或提示错误。
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: iOS / macOS SDK 安装与配置
|
|
3
|
+
sidebar_label: 安装与配置
|
|
4
|
+
description: "iOS / macOS SDK 安装与配置指南:平台要求、依赖安装和应用设置。"
|
|
5
|
+
pagination_label: "iOS / macOS SDK 安装与配置"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# iOS / macOS SDK 安装与配置
|
|
9
|
+
|
|
10
|
+
MeshStreamKit 为 iOS 和 macOS 应用提供 P2P 媒体分发加速能力。SDK 提供 Objective-C 接口,可与 AVPlayer 或兼容的第三方播放器集成。
|
|
11
|
+
|
|
12
|
+
当前发布版本为 `MeshStreamKit 1.0.10`,同一发行包包含 iOS 真机、iOS 模拟器及 macOS 双架构组件。
|
|
13
|
+
|
|
14
|
+
官方发布包、示例工程及更新说明见 [SDK 仓库](https://github.com/Mesh-Stream/meshstream-p2p-ios-sdk)。
|
|
15
|
+
|
|
16
|
+
## 环境要求
|
|
17
|
+
|
|
18
|
+
| 环境 | 最低系统版本 |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| iOS 真机 | iOS 15 |
|
|
21
|
+
| iOS 模拟器(Intel / Apple Silicon) | iOS 15 |
|
|
22
|
+
| macOS(Intel / Apple Silicon) | macOS 12 |
|
|
23
|
+
|
|
24
|
+
通过 Swift Package Manager 集成时,Xcode 需支持 Swift Tools 5.9。
|
|
25
|
+
|
|
26
|
+
## 接入准备
|
|
27
|
+
|
|
28
|
+
- 在[控制台](https://console.meshstream.net)创建应用,获取对应平台的 SDK Key。
|
|
29
|
+
- 确认应用的 Bundle ID 与控制台登记信息一致。
|
|
30
|
+
- 一个可播放的 HLS `.m3u8`、DASH `.mpd`、支持 Range 的 MP4 或 MP3 地址;
|
|
31
|
+
|
|
32
|
+
## 安装 SDK
|
|
33
|
+
|
|
34
|
+
支持 CocoaPods、Swift Package Manager 和手动集成。同一应用 Target 使用一种安装方式。
|
|
35
|
+
|
|
36
|
+
### CocoaPods
|
|
37
|
+
|
|
38
|
+
在 `Podfile` 中添加依赖:
|
|
39
|
+
|
|
40
|
+
```ruby
|
|
41
|
+
platform :ios, '15.0'
|
|
42
|
+
|
|
43
|
+
target 'YourApp' do
|
|
44
|
+
pod 'MeshStreamKit', '1.0.10'
|
|
45
|
+
end
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
安装依赖:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pod install --repo-update
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
安装完成后,使用生成的 `.xcworkspace` 打开项目。macOS 项目将平台声明调整为 `platform :osx, '12.0'`。
|
|
55
|
+
|
|
56
|
+
### Swift Package Manager
|
|
57
|
+
|
|
58
|
+
在 Xcode 中选择 **File → Add Package Dependencies**,输入:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
https://github.com/Mesh-Stream/meshstream-p2p-ios-sdk.git
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
选择精确版本 `1.0.10`,并将 `MeshStreamKit` 添加至应用 Target。
|
|
65
|
+
|
|
66
|
+
### 手动集成
|
|
67
|
+
|
|
68
|
+
从 [SDK 仓库](https://github.com/Mesh-Stream/meshstream-p2p-ios-sdk)下载最新稳定版本的发布包。解压后,将 `MeshStreamKit.xcframework` 添加至应用 Target 的 **Frameworks, Libraries, and Embedded Content**,并选择 **Embed & Sign**。
|
|
69
|
+
|
|
70
|
+
使用对应[版本清单](https://github.com/Mesh-Stream/meshstream-p2p-ios-sdk/tree/main/releases)中的 SHA-256 校验下载包的完整性。
|
|
71
|
+
|
|
72
|
+
### 更新 SDK
|
|
73
|
+
|
|
74
|
+
CocoaPods 首次安装时解析满足项目依赖约束的版本,后续安装使用 `Podfile.lock` 锁定的版本。上面的示例将版本精确锁定为 `1.0.10`。升级时先将 `Podfile` 中的版本改为目标已发布版本,再执行:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
pod update MeshStreamKit --repo-update
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Swift Package Manager 项目需先在 Xcode 的 Package Dependencies 中将 Exact Version 规则改为目标已发布版本,再更新包依赖。版本约束不变时,更新命令不会将精确锁定的依赖升级到其他版本。手动集成项目替换完整的 XCFramework,并核对新版本的校验和。
|
|
81
|
+
|
|
82
|
+
建议将 `Podfile.lock` 或 `Package.resolved` 纳入版本管理,并在发布应用前完成升级验证。
|
|
83
|
+
|
|
84
|
+
## 应用配置
|
|
85
|
+
|
|
86
|
+
SDK 自动读取应用的 Bundle ID,无需额外配置服务地址。各平台需完成以下权限配置。
|
|
87
|
+
|
|
88
|
+
### iOS
|
|
89
|
+
|
|
90
|
+
SDK 返回的播放地址使用本机 HTTP 回环代理,即使媒体源为 HTTPS,也需允许播放器访问本地代理。在应用 Target 的 `Info.plist` 中合并以下设置:
|
|
91
|
+
|
|
92
|
+
```xml
|
|
93
|
+
<key>NSAppTransportSecurity</key>
|
|
94
|
+
<dict>
|
|
95
|
+
<key>NSAllowsLocalNetworking</key>
|
|
96
|
+
<true/>
|
|
97
|
+
</dict>
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
已有 `NSAppTransportSecurity` 字典时合并该键,保留其余 ATS 限制。媒体源需要其他 ATS 例外时,仅添加必要配置。
|
|
101
|
+
|
|
102
|
+
### macOS
|
|
103
|
+
|
|
104
|
+
macOS 应用同样通过本机 HTTP 代理播放,需在应用的 `Info.plist` 中合并上面的 ATS 本地网络设置。
|
|
105
|
+
|
|
106
|
+
启用 App Sandbox 的应用需添加以下网络权限:
|
|
107
|
+
|
|
108
|
+
- `com.apple.security.network.client`
|
|
109
|
+
- `com.apple.security.network.server`
|
|
110
|
+
|
|
111
|
+
## 下一步
|
|
112
|
+
|
|
113
|
+
完成以上配置后,进入[快速接入](./ios.md),创建会话、连接播放器,并在播放结束后释放资源。
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: iOS / macOS SDK 快速接入
|
|
3
|
+
sidebar_label: 快速接入
|
|
4
|
+
description: "iOS / macOS SDK 快速接入指南:创建播放会话、连接播放器、查看状态并释放资源。"
|
|
5
|
+
pagination_label: "iOS / macOS SDK 快速接入"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# iOS / macOS SDK 快速接入
|
|
9
|
+
|
|
10
|
+
MeshStreamKit 为 iOS 和 macOS 应用提供 P2P 媒体分发加速能力。SDK 提供 Objective-C 接口,可与 AVPlayer 或兼容的第三方播放器集成。
|
|
11
|
+
|
|
12
|
+
当前发布版本为 `MeshStreamKit 1.0.10`,同一发行包包含 iOS 真机、iOS 模拟器及 macOS 双架构组件。
|
|
13
|
+
|
|
14
|
+
官方发布包、示例工程及更新说明见 [SDK 仓库](https://github.com/Mesh-Stream/meshstream-p2p-ios-sdk)。
|
|
15
|
+
|
|
16
|
+
<span id="环境要求" />
|
|
17
|
+
<span id="接入准备" />
|
|
18
|
+
<span id="安装-sdk" />
|
|
19
|
+
<span id="cocoapods" />
|
|
20
|
+
<span id="swift-package-manager" />
|
|
21
|
+
<span id="手动集成" />
|
|
22
|
+
<span id="更新-sdk" />
|
|
23
|
+
<span id="应用配置" />
|
|
24
|
+
<span id="ios" />
|
|
25
|
+
<span id="macos" />
|
|
26
|
+
|
|
27
|
+
运行代码前,请先完成[安装与配置](./ios-setup.md),准备 SDK Key 和可播放媒体地址,并配置应用网络策略。
|
|
28
|
+
|
|
29
|
+
## 开始播放
|
|
30
|
+
|
|
31
|
+
### 持有播放对象
|
|
32
|
+
|
|
33
|
+
在播放管理器或页面控制器中持有客户端、播放会话和播放器,确保其生命周期覆盖整个播放过程:
|
|
34
|
+
|
|
35
|
+
```objc
|
|
36
|
+
@property(nonatomic, strong) P2PClient *client;
|
|
37
|
+
@property(nonatomic, strong) PlaybackSession *session;
|
|
38
|
+
@property(nonatomic, strong) AVPlayer *player;
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### 创建播放会话
|
|
42
|
+
|
|
43
|
+
使用 SDK Key 初始化客户端,为媒体地址创建播放会话,再将 `playbackUrl` 传入播放器。示例中的 `originURL` 为原始媒体地址:
|
|
44
|
+
|
|
45
|
+
```objc
|
|
46
|
+
#import <AVFoundation/AVFoundation.h>
|
|
47
|
+
#import <MeshStreamKit/MeshStreamKit.h>
|
|
48
|
+
|
|
49
|
+
P2PConfig *config = [[P2PConfig alloc] initWithKey:@"YOUR_IOS_SDK_KEY"];
|
|
50
|
+
NSError *error = nil;
|
|
51
|
+
self.client = [P2PSDK clientWithConfig:config error:&error];
|
|
52
|
+
if (!self.client) {
|
|
53
|
+
NSLog(@"SDK initialization failed: %@", error);
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
self.session = [self.client createPlaybackSessionWithURL:originURL error:&error];
|
|
58
|
+
if (!self.session) {
|
|
59
|
+
NSLog(@"Playback session creation failed: %@", error);
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
self.player = [AVPlayer playerWithURL:self.session.playbackUrl];
|
|
64
|
+
[self.player play];
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
将 `self.player` 关联至应用的播放视图。第三方播放器使用同一会话返回的 `playbackUrl`。
|
|
68
|
+
|
|
69
|
+
客户端或会话创建失败时,依据返回的 `NSError` 处理异常;仅在会话创建成功后初始化播放器。
|
|
70
|
+
|
|
71
|
+
### 释放播放资源
|
|
72
|
+
|
|
73
|
+
切换内容或结束播放时,先暂停播放器并解除媒体引用,再关闭对应会话:
|
|
74
|
+
|
|
75
|
+
```objc
|
|
76
|
+
[self.player pause];
|
|
77
|
+
[self.player replaceCurrentItemWithPlayerItem:nil];
|
|
78
|
+
[self.session close];
|
|
79
|
+
self.session = nil;
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`[P2PSDK shutdown]` 用于全局资源释放,仅在应用不再使用任何 SDK 客户端或会话时调用。单个播放页面退出时关闭对应会话即可;画中画或后台播放仍在继续时,应保留所需的播放对象。
|
|
83
|
+
|
|
84
|
+
## 常用配置
|
|
85
|
+
|
|
86
|
+
通过 `P2PConfig` 设置客户端配置,配置在创建客户端时生效。
|
|
87
|
+
|
|
88
|
+
| 属性 | 默认值 | 说明 |
|
|
89
|
+
| --- | --- | --- |
|
|
90
|
+
| `sdkKey` | 必填 | 通过 `initWithKey:` 传入对应平台的 SDK Key |
|
|
91
|
+
| `p2pEnabled` | `YES` | P2P 加速开关,受控制台策略约束 |
|
|
92
|
+
| `maxPeerConnections` | `12` | 最大对等节点连接数 |
|
|
93
|
+
| `maxUploadPeers` | `4` | 最大并发上传节点数 |
|
|
94
|
+
| `maxDownloadPeers` | `5` | 最大并发下载节点数 |
|
|
95
|
+
| `maxMemoryBytes` | `64 MiB` | SDK 媒体缓存容量上限 |
|
|
96
|
+
| `requestTimeoutMs` | `8000` | P2P 媒体请求超时,单位为毫秒 |
|
|
97
|
+
| `logLevel` | `P2PLogLevelNone` | 日志级别:`None / Error / Info / Debug` |
|
|
98
|
+
| `fileLoggingEnabled` | `NO` | 是否保存本地诊断日志 |
|
|
99
|
+
|
|
100
|
+
`maxMemoryBytes` 仅限制 SDK 媒体缓存,不包含播放器及应用的其他内存占用。`requestTimeoutMs` 不控制播放器启动超时。
|
|
101
|
+
|
|
102
|
+
## 预加载
|
|
103
|
+
|
|
104
|
+
预加载为可选能力,适用于提前准备下一条播放内容。创建独立会话后调用 `[session preload]`;开始播放时复用该会话的 `playbackUrl`,取消预加载时调用 `[session close]`。
|
|
105
|
+
|
|
106
|
+
预加载会产生网络流量。方法返回成功表示预加载请求已接受,不代表媒体下载完成或首帧已渲染。会话管理与内容切换示例见[高级用法](./ios-advanced.md)。
|
|
107
|
+
|
|
108
|
+
## 事件与统计
|
|
109
|
+
|
|
110
|
+
通过 `P2PEventListener` 订阅加速事件,或调用 `[session statistics]` 获取当前会话统计。
|
|
111
|
+
|
|
112
|
+
| 字段 | 说明 | 单位 |
|
|
113
|
+
| --- | --- | --- |
|
|
114
|
+
| `httpDownloaded` | HTTP 下载流量 | 字节 |
|
|
115
|
+
| `p2pDownloaded` | P2P 下载流量 | 字节 |
|
|
116
|
+
| `p2pUploaded` | P2P 上传流量 | 字节 |
|
|
117
|
+
| `connectedPeers` | 已连接的对等节点数 | 个 |
|
|
118
|
+
|
|
119
|
+
## 诊断日志
|
|
120
|
+
|
|
121
|
+
日志默认关闭。需要诊断时,在创建客户端前设置日志级别及文件记录选项:
|
|
122
|
+
|
|
123
|
+
```objc
|
|
124
|
+
config.logLevel = P2PLogLevelInfo;
|
|
125
|
+
config.fileLoggingEnabled = YES;
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
日志文件保存在应用的 Caches 目录,采用滚动清理机制,不自动上传。生产环境建议按需启用,并在共享诊断资料前移除 SDK Key、访问凭据及敏感媒体地址。
|
|
129
|
+
|
|
130
|
+
## 兼容性与常见问题
|
|
131
|
+
|
|
132
|
+
### 支持哪些播放器与媒体格式?
|
|
133
|
+
|
|
134
|
+
播放器需支持加载 SDK 返回的播放地址。媒体格式、解码、DRM、后台播放及画中画的支持范围由所选播放器、操作系统及应用配置决定。音频会话与后台能力按播放器文档配置。
|
|
135
|
+
|
|
136
|
+
### 节点数为 0 是否表示播放异常?
|
|
137
|
+
|
|
138
|
+
`connectedPeers` 表示当前已连接的对等节点数,不是播放器状态。P2P 暂不可用时,应用仍应依据播放器错误及媒体源状态判断播放结果。更多诊断步骤见[故障排查](../troubleshooting.md)。
|
|
139
|
+
|
|
140
|
+
### CocoaPods 无法解析依赖时如何处理?
|
|
141
|
+
|
|
142
|
+
确认 Pod 名称为 `MeshStreamKit`,并执行 `pod install --repo-update`。新版本发布后,公共索引可能存在同步延迟;可使用 [SDK 仓库](https://github.com/Mesh-Stream/meshstream-p2p-ios-sdk)提供的版本化远程 podspec 方式安装。CocoaPods 集成请使用官方发布的 Pod,而非 `:git` 源码依赖。
|
|
143
|
+
|
|
144
|
+
## 示例与支持
|
|
145
|
+
|
|
146
|
+
- iOS:[示例工程](https://github.com/Mesh-Stream/meshstream-p2p-ios-sdk/tree/main/Examples/iOS)。运行前配置签名团队、Bundle ID 和 SDK Key。
|
|
147
|
+
- macOS:[示例工程](https://github.com/Mesh-Stream/meshstream-p2p-ios-sdk/tree/main/Examples/macOS)。
|
|
148
|
+
- 商务与技术支持:[support@meshstream.net](mailto:support@meshstream.net)。
|
|
149
|
+
|
|
150
|
+
SDK 的使用与分发遵循适用的商业授权协议。应用分发时需保留[第三方许可声明](https://github.com/Mesh-Stream/meshstream-p2p-ios-sdk/blob/main/THIRD_PARTY_NOTICES.md),并按业务要求完成隐私披露与设备兼容性验证。
|
|
151
|
+
|
|
152
|
+
## 下一步
|
|
153
|
+
|
|
154
|
+
[高级用法](./ios-advanced.md) · [快速开始](../quickstart.md) · [故障排查](../troubleshooting.md)
|
|
155
|
+
|
|
156
|
+
相关文档:[安装与配置](./ios-setup.md) · [高级用法](./ios-advanced.md)。
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 选择 SDK
|
|
3
|
+
sidebar_label: 选择 SDK
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 选择 SDK
|
|
7
|
+
|
|
8
|
+
根据应用使用的技术栈选择 SDK。各端文档按同一顺序组织:**安装与配置 → 快速接入 → 高级用法**。
|
|
9
|
+
|
|
10
|
+
| 应用 / 技术栈 | 安装与配置 | 快速接入 | 高级用法 |
|
|
11
|
+
| --- | --- | --- | --- |
|
|
12
|
+
| Web | [安装配置](./web-setup.md) | [接入代码](./web.md) | [进阶功能](./web-advanced.md) |
|
|
13
|
+
| Android | [安装配置](./android-setup.md) | [接入代码](./android.md) | [进阶功能](./android-advanced.md) |
|
|
14
|
+
| iOS / macOS | [安装配置](./ios-setup.md) | [接入代码](./ios.md) | [进阶功能](./ios-advanced.md) |
|
|
15
|
+
| Windows | [安装配置](./windows-setup.md) | [接入代码](./windows.md) | [进阶功能](./windows-advanced.md) |
|
|
16
|
+
| Flutter | [安装配置](./flutter-setup.md) | [接入代码](./flutter.md) | [进阶功能](./flutter-advanced.md) |
|
|
17
|
+
| React Native | [安装配置](./react-native-setup.md) | [接入代码](./react-native.md) | [进阶功能](./react-native-advanced.md) |
|
|
18
|
+
| Uniapp | [安装配置](./uniapp-setup.md) | [接入代码](./uniapp.md) | [进阶功能](./uniapp-advanced.md) |
|
|
19
|
+
|
|
20
|
+
## 阅读顺序
|
|
21
|
+
|
|
22
|
+
1. **安装与配置**:确认系统要求,安装依赖,配置权限与网络。
|
|
23
|
+
2. **快速接入**:创建会话,将播放地址交给播放器,验证播放并释放资源。
|
|
24
|
+
3. **高级用法**:按需接入源站鉴权、预加载、多会话、运行时控制和诊断。
|
|
25
|
+
|
|
26
|
+
首次接入可从[快速开始](../quickstart.md)了解完整流程。播放或 P2P 异常时,进入[故障排查](../troubleshooting.md)。
|
|
27
|
+
|
|
28
|
+
## 原生与跨平台 SDK 版本对照
|
|
29
|
+
|
|
30
|
+
| SDK | 当前版本 | Android 原生依赖 | Apple 原生依赖 |
|
|
31
|
+
| --- | --- | --- | --- |
|
|
32
|
+
| [Android](./android.md) | 1.0.9 | — | — |
|
|
33
|
+
| [iOS / macOS](./ios.md) | 1.0.8 | — | — |
|
|
34
|
+
| [Flutter](./flutter.md) | 1.0.8 | 1.0.9 | 1.0.8 |
|
|
35
|
+
| [React Native](./react-native.md) | 1.0.5 | 1.0.9 | 1.0.8 |
|
|
36
|
+
| [Uniapp](./uniapp.md) | 1.0.6 | 1.0.9 | 1.0.8 |
|
|
37
|
+
|
|
38
|
+
跨平台插件与原生 SDK 的版本号独立管理。建议固定依赖版本,并将包管理器锁文件纳入版本管理。
|
|
39
|
+
|
|
40
|
+
Android/iOS 播放地址使用本机 HTTP 代理;即使原始媒体地址为 HTTPS,也需按对应集成指南完成应用网络配置,并确保 Release 包同样生效。
|