initial commit

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

@@ -0,0 +1,262 @@
+# 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` 回调后需结束通话重新发起
+- 视频处理回调避免耗时操作