SellyCloudSDK_demo/SellySDK_音视频通话接入文档.md

SellyRTC iOS SDK 接入文档

本文档用于指导 App 开发者 快速接入 SellyRTC iOS SDK，实现一对一或多人实时音视频通话能力。

SDK 核心以 SellyRTCSession 为中心，通过 SellyRTCSessionDelegate 回调通话状态、用户事件、音视频状态及异常。

---

📑 目录

1. 准备工作
2. 快速开始
3. 基础通话流程
4. 常用功能
5. 屏幕分享与外部视频源
6. 视频帧前后处理
7. 事件回调（Delegate）
8. 通话统计
9. Token 机制
10. 常见问题（FAQ）

---

🔧 准备工作

1. 环境要求

• iOS 13 及以上
• 真机运行（需摄像头 / 麦克风）

2. 权限配置（Info.plist）

<key>NSCameraUsageDescription</key>
<string>需要访问摄像头用于视频通话</string>
<key>NSMicrophoneUsageDescription</key>
<string>需要访问麦克风用于语音通话</string>

---

🚀 快速开始

1. 创建 Session

/// isP2p = YES：一对一通话（P2P）
/// isP2p = NO ：多人会议
self.session = [[SellyRTCSession alloc] initWithType:YES];
self.session.delegate = self;

⚠️ 注意：必须使用 initWithType:，init/new 不可用。

---

2. 配置视频参数（必须在 start 前）

SellyRTCVideoConfiguration *config = [SellyRTCVideoConfiguration defaultConfig];
config.maxBitrate = 800000;
config.minBitrate = 300000;
config.preferPosition = AVCaptureDevicePositionFront;

self.session.videoConfig = config;

---

3. 设置本地 / 远端画布

SellyRTCVideoCanvas *local = [SellyRTCVideoCanvas new];
local.view = self.localView;
local.userId = @"local";
[self.session setLocalCanvas:local];

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

建议在 onUserJoined: 回调后再绑定远端画布。

---

4. 本地预览（可选）

[self.session startPreview];

---

5. 加入通话

[self.session startWithChannelId:@"room_id" token:@"token"];

结束通话：

[self.session end];

---

🔄 基础通话流程

1. 创建 SellyRTCSession
2. 设置 delegate
3. 配置 videoConfig
4. 设置本地画布
5. startPreview（可选）
6. startWithChannelId:token:
7. onUserJoined → 设置远端画布
8. 通话中控制音视频
9. end 结束并释放

---

🎛 常用功能

本地音视频控制

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

切换摄像头

[self.session switchCamera];

静音远端音频

[self.session muteRemoteAudioStream:@"remoteUserId" mute:YES];

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

[self.session setAudioOutput:AVAudioSessionPortOverrideSpeaker];

若存在蓝牙/耳机，建议使用系统音频路由控件。

---

自定义消息

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

---

🖥 屏幕分享与外部视频源

开启屏幕分享

[self.session startScreenCapture];

- (void)rtcSession:(SellyRTCSession *)session
onScreenShareStatusChanged:(SellyScreenShareState)state;

---

外部视频源推送

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

---

🎥 视频帧前后处理

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

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

远端渲染回调

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

---

📡 事件回调（Delegate）

- (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;

---

📊 通话统计

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

---

🔑 Token 机制

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

[self.session renewToken:newToken];

---

❓ 常见问题（FAQ）

Q：远端画面不显示？

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

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

• 开启屏幕分享：startScreenCapture
• 屏幕分享结束后重新 enableLocalVideo:YES

---

📌 注意事项

• videoConfig 必须在 start 前设置
• onError 回调后需结束通话重新发起
• 视频处理回调避免耗时操作