initial commit

2026-03-01 15:59:27 +08:00
commit a9e97d56cb
1426 changed files with 172367 additions and 0 deletions
--- a/SellySDK_直播推拉流接入文档.md
+++ b/SellySDK_直播推拉流接入文档.md
@@ -0,0 +1,411 @@
+# Selly Live SDK 推拉流接入文档（iOS）
+
+> 统一 SDK 名称：**SellyCloudSDK**  
+> 本文档适用于 iOS 客户端，面向对外集成方与内部使用。
+
+---
+
+## 1. 概述
+
+Selly Live SDK 提供完整的音视频直播能力，支持 **推流（直播发布）** 与 **拉流（直播播放）** 两大核心场景，适用于泛直播、互动直播、实时音视频等业务。
+
+### 主要能力
+
+- 支持 **RTMP / RTC** 推流与播放模式
+- 高性能音视频采集与编码
+- 灵活的视频参数配置（分辨率 / 帧率 / 码率）
+- 推流状态与统计回调
+- 拉流播放状态与错误回调
+- 支持视频帧回调，便于接入美颜 / 滤镜 / 水印
+- 基于 **Token 的安全鉴权机制**
+
+---
+
+## 2. 系统要求
+
+- iOS 13.0 及以上
+- Xcode 11.0 及以上
+- 需在真机环境运行（音视频采集限制）
+
+---
+
+## 3. SDK 集成
+
+### 3.1 引入 SDK
+
+```objc
+#import <SellyCloudSDK/SellyCloudManager.h>
+```
+
+### 3.2 权限配置（Info.plist）
+
+推流场景必须配置以下权限：
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>需要访问摄像头用于直播</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>需要访问麦克风用于直播</string>
+```
+
+> 仅拉流播放场景不需要麦克风权限，请避免触发采集相关接口。
+
+---
+
+## 4. Token 鉴权机制（重点）
+
+### 4.1 Token 基本说明
+
+Selly Live SDK 的 **推流与拉流均采用 Token 鉴权机制**。  
+Token 由业务服务端生成并下发，SDK 仅负责使用 Token 建立连接。
+
+### 4.2 Token 注入方式
+
+Token 通过 **类属性** 注入：
+
+| 场景 | 设置位置 |
+|----|----|
+| 推流 | `SellyLiveVideoPusher.token` |
+| 拉流 | `SellyLiveVideoPlayer.token` |
+
+**说明：**
+
+- Token **不拼接到 URL**
+- Token **不绑定 streamId**
+- SDK 内部在建立连接时自动携带当前 Token
+
+---
+
+### 4.3 Token 设置时机（强约束）
+
+#### 推流
+
+必须在以下接口调用 **之前** 设置：
+
+- `startLiveWithUrl:`
+- `startLiveWithStreamId:`
+
+#### 拉流
+
+必须在以下接口调用 **之前** 设置：
+
+- `prepareToPlay`
+- `play`
+
+> ⚠️ 在连接建立后修改 Token，不会影响当前连接。
+
+---
+
+### 4.4 Token 刷新机制说明
+
+- SDK **不提供 Token 自动刷新机制**
+- SDK **不会主动请求或续期 Token**
+- 业务层可在任意时刻 **重新设置 token 属性**
+
+当 Token 过期,推荐流程：
+
+1. 业务侧向服务端获取新 Token
+2. 调用 `pusher.token = newToken` / `player.token = newToken`
+3. 停止并重新开始推流 / 拉流流程
+
+---
+
+### 4.5 Token 失效表现
+
+| 场景 | 表现 |
+|----|----|
+| Token 无效 | 建立连接失败，触发错误回调 |
+| Token 过期 | 推 / 拉中断，进入 Failed 状态 |
+| 鉴权失败 | `onError:` 回调 |
+
+---
+
+## 5. 推流接入详解
+
+### 5.1 创建推流实例
+
+```objc
+SellyLiveVideoPusher *pusher =
+[[SellyLiveVideoPusher alloc] initWithLiveMode:SellyLiveMode_RTMP];
+pusher.delegate = self;
+```
+
+> 必须使用 `initWithLiveMode:` 初始化。
+
+---
+
+### 5.2 设置推流 Token（必须）
+
+```objc
+pusher.token = pushToken;
+```
+
+---
+
+### 5.3 视频参数配置
+
+```objc
+SellyLiveVideoConfiguration *videoConfig =
+[SellyLiveVideoConfiguration defaultConfiguration];
+
+videoConfig.videoSize = SellyRTCVideoResolution1280x720;
+videoConfig.videoFrameRate = 25;
+videoConfig.videoMinFrameRate = 15;
+videoConfig.videoBitRate = 1000 * 1024;
+videoConfig.videoMinBitRate = 500 * 1024;
+videoConfig.videoMaxKeyframeInterval = 50;
+videoConfig.outputImageOrientation = UIInterfaceOrientationPortrait;
+```
+
+#### 分辨率枚举
+
+- 480x360
+- 640x480
+- 960x540
+- 1280x720
+
+---
+
+### 5.4 开始采集
+
+```objc
+[pusher startRunning:AVCaptureDevicePositionFront
+         videoConfig:videoConfig
+         audioConfig:nil];
+```
+
+采集能力说明：
+
+- 摄像头控制：`startCamera / stopCamera`
+- 麦克风控制：`startMicrophone / stopMicrophone`
+- 摄像头切换：`switchCameraPosition:`
+
+---
+
+### 5.5 开始推流
+
+```objc
+NSError *error = [pusher startLiveWithUrl:pushUrl];
+if (error) {
+    NSLog(@"推流失败: %@", error);
+}
+```
+
+或：
+
+```objc
+[pusher startLiveWithStreamId:streamId];
+```
+
+---
+
+### 5.6 停止推流
+
+```objc
+[pusher stopLive:^(NSError * _Nullable error) {
+    NSLog(@"推流已停止");
+}];
+```
+
+---
+
+### 5.7 推流回调说明
+
+#### 状态回调
+
+```objc
+- (void)pusher:(SellyLiveVideoPusher *)pusher
+liveStatusDidChanged:(SellyLiveStatus)status;
+```
+
+状态枚举说明：
+
+- Idle：未开始
+- Connecting：连接中
+- Publishing：推流中
+- Reconnecting：重连中
+- Stopped：已停止
+- Failed：失败
+
+---
+
+#### 错误回调
+
+```objc
+- (void)pusher:(SellyLiveVideoPusher *)pusher
+        onError:(NSError *)error;
+```
+
+---
+
+#### 推流统计回调
+
+```objc
+- (void)pusher:(SellyLiveVideoPusher *)pusher
+onStatisticsUpdate:(SellyLivePusherStats *)stats;
+```
+
+统计字段包括：
+
+- fps
+- videoBitrate / audioBitrate
+- rtt
+- netSpeed
+- cpu 使用率
+
+---
+
+### 5.8 视频帧回调（美颜 / 滤镜）
+
+```objc
+- (CVPixelBufferRef)pusher:(SellyLiveVideoPusher *)pusher
+      onCaptureVideoFrame:(CVPixelBufferRef)pixelBuffer;
+```
+
+> 返回值为最终用于推流的视频帧。
+
+---
+
+## 6. 拉流接入详解
+
+### 6.1 创建播放器
+
+```objc
+SellyLiveVideoPlayer *player =
+[[SellyLiveVideoPlayer alloc] initWithUrl:playUrl];
+player.delegate = self;
+```
+
+---
+
+### 6.2 设置拉流 Token（必须）
+
+```objc
+player.token = playToken;
+```
+
+---
+
+### 6.3 播放流程
+
+```objc
+[player prepareToPlay];
+[player play];
+```
+
+控制接口：
+
+- pause
+- stop
+- isPlaying
+
+---
+
+### 6.4 播放回调
+
+```objc
+- (void)player:(SellyLiveVideoPlayer *)player
+playbackStateChanged:(SellyPlayerState)state;
+
+- (void)player:(SellyLiveVideoPlayer *)player
+        onError:(NSError *)error;
+```
+
+状态枚举：
+
+- Idle
+- Connecting
+- Playing
+- Paused
+- Stopped
+- Failed
+
+---
+
+## 7. 错误处理与重试建议
+
+### Token 错误
+
+1. 停止当前推 / 拉
+2. 获取新 Token
+3. 重新设置 Token
+4. 重启流程
+
+### 网络错误
+
+- 根据 rtt / bitrate 判断弱网
+- 必要时重启连接
+
+---
+
+## 8. 最佳实践
+
+- 推流前先完成采集预览
+- Token 即将过期前提前刷新
+- 使用统计回调做质量监控
+- 拉流失败避免无限重试
+
+---
+
+## 9. 常见问题（FAQ）
+
+### Q1：Token 可以拼接到 URL 吗？
+**A：** 不可以。  
+SDK 不解析 URL 中的鉴权信息，所有鉴权均通过 SDK 实例的 `token` 属性完成。
+
+---
+
+### Q2：运行中修改 Token 是否生效？
+**A：**  
+运行中修改 Token **不会影响当前已建立的连接**，  
+**下次重连或重新启动推流 / 拉流时会使用新的 Token**。
+
+---
+
+### Q3：推流画面出现绿边？
+**A：**  
+请确保视频分辨率的 **宽和高均为 2 的倍数**。  
+建议直接使用 SDK 提供的预设分辨率枚举，避免手动配置导致的问题。
+
+---
+
+### Q4：如何降低推流延迟？
+**A：** 可以从以下几个方面优化：
+
+- 减小关键帧间隔（`videoMaxKeyframeInterval`）
+- 优先使用 **RTC 模式** 而非 RTMP
+- 适当降低视频分辨率和码率
+
+---
+
+### Q5：弱网环境下如何优化推流体验？
+**A：** 建议采取以下策略：
+
+- 启用自适应码率策略（如业务支持）
+- 降低初始分辨率和码率
+- 将帧率控制在 **15–20 fps**
+- 监听网络状态，动态调整推流配置
+
+---
+
+### Q6：播放器出现黑屏怎么办？
+**A：** 可按以下步骤排查：
+
+- 检查播放地址是否正确
+- 确认当前网络连接正常
+- 查看播放器回调中的错误信息
+- 确认视频流格式是否被 SDK 支持
+
+---
+
+### Q7：如何实现横屏推流？
+**A：**  
+通过设置视频输出方向即可：
+
+```objective-c
+videoConfig.outputImageOrientation = UIInterfaceOrientationLandscapeRight;
+
+---
+
+**文档版本：** v2.0  
+**最后更新：** 2025-12