# SellyRTC iOS SDK 接入文档
本文档用于指导 **App 开发者** 快速接入 SellyRTC iOS SDK，实现一对一或多人实时音视频通话能力。
SDK 核心以 `SellyRTCSession` 为中心，通过 `SellyRTCSessionDelegate` 回调通话状态、用户事件、音视频状态及异常。
---
## 📑 目录
1. [准备工作](#准备工作)
2. [快速开始](#快速开始)
3. [基础通话流程](#基础通话流程)
4. [常用功能](#常用功能)
5. [屏幕分享与外部视频源](#屏幕分享与外部视频源)
6. [视频帧前后处理](#视频帧前后处理)
7. [事件回调（Delegate）](#事件回调delegate)
8. [通话统计](#通话统计)
9. [Token 机制](#token-机制)
10. [常见问题（FAQ）](#常见问题faq)
---
## 🔧 准备工作
### 1. 环境要求
- iOS 13 及以上
- 真机运行（需摄像头 / 麦克风）
### 2. 权限配置（Info.plist）
```xml
NSCameraUsageDescription
需要访问摄像头用于视频通话
NSMicrophoneUsageDescription
需要访问麦克风用于语音通话
```
---
## 🚀 快速开始
### 1. 创建 Session
```objc
/// isP2p = YES：一对一通话（P2P）
/// isP2p = NO ：多人会议
self.session = [[SellyRTCSession alloc] initWithType:YES];
self.session.delegate = self;
```
> ⚠️ 注意：必须使用 `initWithType:`，`init/new` 不可用。
---
### 2. 配置视频参数（必须在 start 前）
```objc
SellyRTCVideoConfiguration *config = [SellyRTCVideoConfiguration defaultConfig];
config.maxBitrate = 800000;
config.minBitrate = 300000;
config.preferPosition = AVCaptureDevicePositionFront;
self.session.videoConfig = config;
```
---
### 3. 设置本地 / 远端画布
```objc
SellyRTCVideoCanvas *local = [SellyRTCVideoCanvas new];
local.view = self.localView;
local.userId = @"local";
[self.session setLocalCanvas:local];
```
```objc
SellyRTCVideoCanvas *remote = [SellyRTCVideoCanvas new];
remote.view = self.remoteView;
remote.userId = @"remoteUserId";
[self.session setRemoteCanvas:remote];
```
> 建议在 `onUserJoined:` 回调后再绑定远端画布。
---
### 4. 本地预览（可选）
```objc
[self.session startPreview];
```
---
### 5. 加入通话
```objc
[self.session startWithChannelId:@"room_id" token:@"token"];
```
结束通话：
```objc
[self.session end];
```
---
## 🔄 基础通话流程
1. 创建 `SellyRTCSession`
2. 设置 `delegate`
3. 配置 `videoConfig`
4. 设置本地画布
5. `startPreview`（可选）
6. `startWithChannelId:token:`
7. `onUserJoined` → 设置远端画布
8. 通话中控制音视频
9. `end` 结束并释放
---
## 🎛 常用功能
### 本地音视频控制
```objc
[self.session enableLocalVideo:YES];
[self.session enableLocalAudio:NO];
```
### 切换摄像头
```objc
[self.session switchCamera];
```
### 静音远端音频
```objc
[self.session muteRemoteAudioStream:@"remoteUserId" mute:YES];
```
### 音频输出（听筒 / 扬声器）
```objc
[self.session setAudioOutput:AVAudioSessionPortOverrideSpeaker];
```
> 若存在蓝牙/耳机，建议使用系统音频路由控件。
---
### 自定义消息
```objc
[self.session sendMessage:@"hello" completion:^(NSError *error) {}];
```
---
## 🖥 屏幕分享与外部视频源
### 开启屏幕分享
```objc
[self.session startScreenCapture];
```
```objc
- (void)rtcSession:(SellyRTCSession *)session
onScreenShareStatusChanged:(SellyScreenShareState)state;
```
---
### 外部视频源推送
```objc
[self.session enableLocalVideo:YES];
[self.session pushExternalVideoFrame:pixelBuffer];
```
---
## 🎥 视频帧前后处理
### 本地采集前处理（美颜/滤镜）
```objc
- (CVPixelBufferRef)rtcSession:(SellyRTCSession *)session
onCaptureVideoFrame:(CVPixelBufferRef)pixelBuffer {
return pixelBuffer;
}
```
### 远端渲染回调
```objc
- (BOOL)rtcSession:(SellyRTCSession *)session
onRenderVideoFrame:(SellyRTCVideoFrame *)videoFrame
userId:(NSString *)userId {
return YES;
}
```
---
## 📡 事件回调（Delegate）
```objc
- (void)rtcSession:(SellyRTCSession *)session onError:(NSError *)error;
- (void)rtcSession:(SellyRTCSession *)session onUserJoined:(NSString *)userId;
- (void)rtcSession:(SellyRTCSession *)session onUserLeave:(NSString *)userId;
- (void)rtcSession:(SellyRTCSession *)session didReceiveMessage:(NSString *)msg userId:(NSString *)uid;
```
---
## 📊 通话统计
```objc
- (void)rtcSession:(SellyRTCSession *)session
onStats:(SellyRTCStats *)stats
userId:(NSString *)userId;
```
---
## 🔑 Token 机制
```objc
- (void)rtcSession:(SellyRTCSession *)session tokenWillExpire:(NSString *)token;
- (void)rtcSession:(SellyRTCSession *)session tokenExpired:(NSString *)token;
```
```objc
[self.session renewToken:newToken];
```
---
## ❓ 常见问题（FAQ）
### Q：远端画面不显示？
1. 是否设置了正确的 `remoteCanvas.userId`
2. 是否在 `onUserJoined` 后调用
3. 是否正确 addSubview
### Q：屏幕分享如何与摄像头切换？
- 开启屏幕分享：`startScreenCapture`
- 屏幕分享结束后重新 `enableLocalVideo:YES`
---
## 📌 注意事项
- `videoConfig` **必须在 start 前设置**
- `onError` 回调后需结束通话重新发起
- 视频处理回调避免耗时操作