# SellyRTC iOS SDK 接入文档

本文档介绍如何使用 **SellyRTCSession** 快速集成一对一或多人音视频通话功能，包括：

- Session 创建与基础通话流程  
- 本地 / 远端画面渲染  
- 音视频控制与通话路由  
- 屏幕分享与外部视频源推流  
- 自定义消息、统计与 Token 机制  
- 连接状态与事件回调

---

## 📑 目录

1. [准备工作](#准备工作)  
2. [快速开始](#快速开始)  
3. [常用功能](#常用功能)  
4. [屏幕分享与外部视频源](#屏幕分享与外部视频源)  
5. [视频帧前后处理](#视频帧前后处理)  
6. [事件回调（Delegate）](#事件回调delegate)  
7. [通话统计](#通话统计)  
8. [Token 过期机制](#token-过期机制)  
9. [连接状态说明](#连接状态说明)  
10. [常见问题](#常见问题)

---

# 🔧 准备工作

1. 集成 SellyRTC.framework  
2. 引入头文件：

```objc
#import <SellyRTC/SellyRTC.h>
```

3. 在真机运行（摄像头/麦克风需要硬件支持）

---

# 🚀 快速开始

## 1. 创建 Session

```objc
/// @param isP2p YES 表示一对一通话（P2P 直连），NO 表示多人通话（房间 / 会议模式）
///
/// P2P 模式（YES）：
///   - 点对点直连，端到端延迟更低
///   - 适合普通一对一音视频通话
self.session = [[SellyRTCSession alloc] initWithType:YES];
self.session.delegate = self;
```

---

## 2. 设置本地和远端画布

```objc
SellyRtcVideoCanvas *local = [SellyRtcVideoCanvas new];
local.view = self.localView;
[self.session setLocalCanvas:local];

SellyRtcVideoCanvas *remote = [SellyRtcVideoCanvas new];
remote.view = self.remoteView;
remote.userId = @"remoteUserId";
[self.session setRemoteCanvas:remote];
```

---

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

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

self.session.videoConfig = config;
```

---

## 4. 打开本地预览

```objc
[self.session startPreview];
```

关闭：

```objc
[self.session stopPreview];
```

---

## 5. 加入频道（开始通话）

```objc
[self.session startWithChannelId:@"room_123" token:@"your-token"];
```

---

## 6. 结束通话

```objc
[self.session end];
```

---

# 🎛 常用功能

## 开关本地视频

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

## 开关本地音频

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

## 切换摄像头

```objc
[self.session switchCamera];
```

## 静音远端

```objc
[self.session muteRemoteAudioStream:@"remoteUser" mute:YES];
```

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

```objc
[self.session setAudioOutput:AVAudioSessionPortOverrideSpeaker];
```

## 发送自定义消息

```objc
[self.session sendMessage:@"hello" completion:^(NSError *error) {}];
```

## 更新 Token

```objc
[self.session renewToken:newToken];
```

---

# 🖥 屏幕分享与外部视频源

## 开启屏幕分享

```objc
[self.session startScreenCapture];
```

屏幕分享状态回调：

```objc
- (void)rtcSession:(SellyRTCSession *)session onScreenShareStatusChanged:(SellyScreenShareState)state {}
```

---

## 外部推流（自定义采集）

```objc
[self.session enableLocalVideo:YES];
[self.session pushExternalVideoFrame:pixelBuffer];
```

常用于游戏画面/ReplayKit 输出/第三方渲染等。

---

# 🎥 视频帧前后处理

## 本地采集前处理（美颜/滤镜等）

```objc
- (CVPixelBufferRef)rtcSession:(SellyRTCSession *)session onCaptureVideoFrame:(CVPixelBufferRef)pixelBuffer {
    return pixelBuffer;
}
```

## 远端渲染前处理（做 AI/贴纸/录像）

```objc
- (BOOL)rtcSession:(SellyRTCSession *)session onRenderVideoFrame:(SellyRTCVideoFrame *)videoFrame userId:(NSString *)userId {
    return YES;
}
```

---

# 📡 事件回调（Delegate）

## 通话严重错误

```objc
- (void)rtcSession:(SellyRTCSession *)session onError:(NSError *)error {}
```

## 远端音视频开关

```objc
- (void)rtcSession:(SellyRTCSession *)s videoEnabled:(BOOL)enabled userId:(NSString *)userId {}
```

## 自定义消息

```objc
- (void)rtcSession:(SellyRTCSession *)s didReceiveMessage:(NSString *)msg userId:(NSString *)uid {}
```

## 流级连接状态

```objc
- (void)rtcSession:(SellyRTCSession *)s connectionStateChanged:(SellyRTCConnectState)state userId:(NSString *)uid {}
```

## 会话级连接状态

```objc
- (void)rtcSession:(SellyRTCSession *)s onRoomConnectionStateChanged:(SellyRoomConnectionState)state {}
```

## 用户加入/离开

```objc
- (void)rtcSession:(SellyRTCSession *)s onUserJoined:(NSString *)uid {}
- (void)rtcSession:(SellyRTCSession *)s onUserLeave:(NSString *)uid {}
```

## 通话时长

```objc
- (void)rtcSession:(SellyRTCSession *)s onDuration:(NSInteger)duration {}
```

## Token 回调

```objc
- (void)rtcSession:(SellyRTCSession *)s tokenWillExpire:(NSString *)token {}
- (void)rtcSession:(SellyRTCSession *)s tokenExpired:(NSString *)token {}
```

## 屏幕分享状态

```objc
- (void)rtcSession:(SellyRTCSession *)s onScreenShareStatusChanged:(SellyScreenShareState)state {}
```

---

# 📊 通话统计

```objc
- (void)rtcSession:(SellyRTCSession *)s onStats:(SellyRTCP2pStats *)stats userId:(NSString *)uid {}
```

---

# 🔑 Token 过期机制

- Token 将在 **60 秒前** 触发 `tokenWillExpire`
- Token 过期后通话继续，但重连会失败
- 请及时调用 `renewToken:`

---

# 🌐 连接状态说明

`connectionState` 可读取当前房间状态：

- Disconnected  
- Connecting  
- Connected  
- Reconnecting  

---

# ❓ 常见问题 FAQ

### Q：远端画面不显示怎么办？

检查：

1. 是否设置了正确的 `remoteCanvas.userId`  
2. 是否 addSubview 到界面  
3. 是否在 onUserJoined 后调用 setRemoteCanvas  

### Q：如何实现摄像头与屏幕分享切换？

1. 开启摄像头 → enableLocalVideo:YES  
2. 开启屏幕分享 → startScreenCapture  
3. 收到屏幕分享结束 → 恢复摄像头  

---