315 lines
5.9 KiB
Markdown
315 lines
5.9 KiB
Markdown
# 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. 收到屏幕分享结束 → 恢复摄像头
|
||
|
||
---
|