DEMO/SellyCloudSDK_demo

Fork 0

Files

Caleb a9e97d56cb initial commit

2026-03-01 15:59:27 +08:00

7.6 KiB

Raw Permalink Blame History

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

#import <SellyCloudSDK/SellyCloudManager.h>

3.2 权限配置（Info.plist）

推流场景必须配置以下权限：

<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 过期,推荐流程：

业务侧向服务端获取新 Token
调用 pusher.token = newToken / player.token = newToken
停止并重新开始推流 / 拉流流程

4.5 Token 失效表现

场景	表现
Token 无效	建立连接失败，触发错误回调
Token 过期	推 / 拉中断，进入 Failed 状态
鉴权失败	`onError:` 回调

5. 推流接入详解

5.1 创建推流实例

SellyLiveVideoPusher *pusher =
[[SellyLiveVideoPusher alloc] initWithLiveMode:SellyLiveMode_RTMP];
pusher.delegate = self;

必须使用 initWithLiveMode: 初始化。

5.2 设置推流 Token（必须）

pusher.token = pushToken;

5.3 视频参数配置

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 开始采集

[pusher startRunning:AVCaptureDevicePositionFront
         videoConfig:videoConfig
         audioConfig:nil];

采集能力说明：

摄像头控制：startCamera / stopCamera
麦克风控制：startMicrophone / stopMicrophone
摄像头切换：switchCameraPosition:

5.5 开始推流

NSError *error = [pusher startLiveWithUrl:pushUrl];
if (error) {
    NSLog(@"推流失败: %@", error);
}

或：

[pusher startLiveWithStreamId:streamId];

5.6 停止推流

[pusher stopLive:^(NSError * _Nullable error) {
    NSLog(@"推流已停止");
}];

5.7 推流回调说明

状态回调

- (void)pusher:(SellyLiveVideoPusher *)pusher
liveStatusDidChanged:(SellyLiveStatus)status;

状态枚举说明：

Idle：未开始
Connecting：连接中
Publishing：推流中
Reconnecting：重连中
Stopped：已停止
Failed：失败

错误回调

- (void)pusher:(SellyLiveVideoPusher *)pusher
        onError:(NSError *)error;

推流统计回调

- (void)pusher:(SellyLiveVideoPusher *)pusher
onStatisticsUpdate:(SellyLivePusherStats *)stats;

统计字段包括：

fps
videoBitrate / audioBitrate
rtt
netSpeed
cpu 使用率

5.8 视频帧回调（美颜 / 滤镜）

- (CVPixelBufferRef)pusher:(SellyLiveVideoPusher *)pusher
      onCaptureVideoFrame:(CVPixelBufferRef)pixelBuffer;

返回值为最终用于推流的视频帧。

6. 拉流接入详解

6.1 创建播放器

SellyLiveVideoPlayer *player =
[[SellyLiveVideoPlayer alloc] initWithUrl:playUrl];
player.delegate = self;

6.2 设置拉流 Token（必须）

player.token = playToken;

6.3 播放流程

[player prepareToPlay];
[player play];

控制接口：

pause
stop
isPlaying

6.4 播放回调

- (void)player:(SellyLiveVideoPlayer *)player
playbackStateChanged:(SellyPlayerState)state;

- (void)player:(SellyLiveVideoPlayer *)player
        onError:(NSError *)error;

状态枚举：

Idle
Connecting
Playing
Paused
Stopped
Failed

7. 错误处理与重试建议

Token 错误

停止当前推 / 拉
获取新 Token
重新设置 Token
重启流程

网络错误

根据 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：
通过设置视频输出方向即可：

videoConfig.outputImageOrientation = UIInterfaceOrientationLandscapeRight;

---

**文档版本：** v2.0  
**最后更新：** 2025-12

7.6 KiB Raw Permalink Blame History Unescape Escape