SellyCloudSDK

📘 SellyRTC iOS SDK 接入文档

本文档介绍如何使用 SellyRTCSession 快速集成一对一或多人音视频通话功能，包括基本接入、音视频控制、数据处理、事件回调、统计与 Token 更新机制。

---

📑 目录

1. 准备工作
2. 快速开始
   • 创建 Session
   • 设置本地/远端画面
   • 配置视频参数
   • 加入频道
   • 结束通话
3. 常用功能
   • 开关音视频
   • 切换摄像头
   • 静音远端
   • 音频输出控制
   • 发送自定义消息
   • Token 更新
4. 视频/音频帧处理
5. 事件回调 (Delegate)
6. 通话统计
7. Token 过期机制
8. 常见问题

---

🔧 准备工作

确保已正确集成 SellyRTC.framework 并导入头文件：

#import <SellyRTC/SellyRTC.h>

---

🚀 快速开始

1. 创建 Session

// YES = 单聊（P2P）  NO = 多人会议
self.session = [[SellyRTCSession alloc] initWithType:YES];
self.session.delegate = self;

⚠️ init 和 new 已禁用，必须使用 initWithType:。

---

2. 设置本地 & 远端画布

// 本地视频
SellyRtcVideoCanvas *local = [SellyRtcVideoCanvas new];
local.view = self.localView;
[self.session setLocalCanvas:local];

// 远端视频（多人时 userId 必填）
SellyRtcVideoCanvas *remote = [SellyRtcVideoCanvas new];
remote.view = self.remoteView;
remote.userId = @"remoteUser";
[self.session setRemoteCanvas:remote];

多人会议：可多次调用 setRemoteCanvas:。
SDK 根据 canvas.userId 将对应远端视频渲染到指定 view。

---

3. 配置视频参数（可选）

必须在加入频道前配置：

SellyRTCVideoConfiguration *config = [SellyRTCVideoConfiguration defaultConfig];
config.width = 720;
config.height = 1280;
config.frameRate = 24;

self.session.videoConfig = config;

---

4. 加入频道 / 发起通话

[self.session startWithChannelId:@"room123" token:@"xxxx-token"];

---

5. 结束通话

[self.session end];

---

🎛 常用功能

开/关本地视频

[self.session enableLocalVideo:NO];
[self.session enableLocalVideo:YES];

开/关本地音频采集

[self.session enableLocalAudio:NO];
[self.session enableLocalAudio:YES];

切换前后摄像头

[self.session switchCamera];

静音远端音频

// P2P 模式 userId 可传 nil
[self.session muteRemoteAudioStream:nil mute:YES];

控制音频输出（扬声器/听筒）

[self.session setAudioOutput:AVAudioSessionPortOverrideSpeaker];

如有耳机 / 蓝牙设备，建议外部使用 AVRoutePickerView。

发送自定义消息

[self.session sendMessage:@"Hello World"
               completion:^(NSError *error) {
    if (error) NSLog(@"发送失败: %@", error);
}];

更新 Token

[self.session renewToken:newToken];

---

🎥 视频 / 音频帧处理

视频采集前处理（美颜、滤镜、自定义 GPU）

- (CVPixelBufferRef)rtcSession:(SellyRTCSession *)session
          onCaptureVideoFrame:(CVPixelBufferRef)pixelBuffer {

    // 1. 执行美颜、贴纸、旋转等处理
    // 2. 返回处理后的 pixelBuffer

    return pixelBuffer;
}

远端视频解码后回调（AI 分析、自定义渲染）

- (BOOL)rtcSession:(SellyRTCSession *)session
  onRenderVideoFrame:(SellyRTCVideoFrame *)videoFrame
              userId:(NSString *)userId {

    // 返回 YES：继续渲染
    // 返回 NO：丢弃该帧
    return YES;
}

---

📡 事件回调 (Delegate)

#pragma mark - SellyRTCSessionDelegate

通话错误（不可恢复）

- (void)rtcSession:(SellyRTCSession *)session onError:(NSError *)error;

远端启用/关闭音视频

- (void)rtcSession:(SellyRTCSession *)session
      videoEnabled:(BOOL)enabled
            userId:(NSString *)userId;

- (void)rtcSession:(SellyRTCSession *)session
      audioEnabled:(BOOL)enabled
            userId:(NSString *)userId;

收到消息

- (void)rtcSession:(SellyRTCSession *)session
  didReceiveMessage:(NSString *)message
             userId:(NSString *)userId;

连接状态变化

- (void)rtcSession:(SellyRTCSession *)session
connectionStateChanged:(SellyRTCConnectState)state
            userId:(NSString *)userId;

连接状态包括：

Disconnected
Connecting
Connected
Reconnecting
Failed

用户加入/离开

- (void)rtcSession:(SellyRTCSession *)session onUserJoined:(NSString *)userId;

- (void)rtcSession:(SellyRTCSession *)session onUserLeave:(NSString *)userId;

通话时长

- (void)rtcSession:(SellyRTCSession *)session onDuration:(NSInteger)duration;

---

📊 通话统计信息

- (void)rtcSession:(SellyRTCSession *)session
           onStats:(SellyRTCP2pStats *)stats
            userId:(NSString *)userId;

可获取：

• 上下行码率
• 帧率
• 丢包率
• RTT
• 解码帧数等

---

🔑 Token 过期机制

Token 即将过期

- (void)rtcSession:(SellyRTCSession *)session tokenWillExpire:(NSString *)token;

业务应立即向服务器请求新 Token：

[self.session renewToken:newToken];

Token 已过期（通话仍继续）

- (void)rtcSession:(SellyRTCSession *)session tokenExpired:(NSString *)token;

⚠️ 过期后通话不受影响，但断网重连会失败，务必及时更新 Token。

---

❓ 常见问题

Q1：多人远端画面如何渲染？

重复调用：

SellyRtcVideoCanvas *canvas = [SellyRtcVideoCanvas new];
canvas.view = remoteViewX;
canvas.userId = @"userX";

[self.session setRemoteCanvas:canvas];

SDK 会根据 userId 做路由。

---

Q2：远端画面不显示？

检查：

• remoteCanvas.view 是否正确添加
• remoteCanvas.userId 是否一致
• 是否重复 addSubview 覆盖
• 是否调用了 setRemoteCanvas:

---

Q3：如何做画中画 (PiP)？

将本地 + 远端视频放入一个 containerView：

[container addSubview:remoteView]
[container addSubview:localView] // 小窗

并使用：

AVPictureInPictureControllerContentSource *source =
    [[AVPictureInPictureControllerContentSource alloc] initWithActiveVideoCallSource:sampleBufferLayer
                                                                          contentView:container];

---

🎉 完成

您已完成 SellyRTC 的全部集成内容。
如需更多帮助，可继续咨询：""

Author

Caleb, liaoqiang1123@gmail.com

License

SellyCloudSDK is available under the MIT license. See the LICENSE file for more info.