263 lines
5.2 KiB
Markdown
263 lines
5.2 KiB
Markdown
# 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
|
||
<key>NSCameraUsageDescription</key>
|
||
<string>需要访问摄像头用于视频通话</string>
|
||
<key>NSMicrophoneUsageDescription</key>
|
||
<string>需要访问麦克风用于语音通话</string>
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 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` 回调后需结束通话重新发起
|
||
- 视频处理回调避免耗时操作
|