tencent cloud

适用场景

TRTC 支持四种不同的进房模式，其中视频通话（VideoCall）和语音通话（AudioCall）统称为通话模式，视频互动直播（Live）和语音互动直播（VoiceChatRoom）统称为 直播模式。
通话模式下的 TRTC，支持单个房间最多300人同时在线，支持最多50人同时发言。适合1对1视频通话、300人视频会议、在线问诊、远程面试、视频客服、在线狼人杀等应用场景。

原理解析

TRTC 云服务由两种不同类型的服务器节点组成，分别是“接口机”和“代理机”：

• 接口机
  该类节点都采用最优质的线路和高性能的机器，善于处理端到端的低延时连麦通话，单位时长计费较高。
• 代理机
  该类节点都采用普通的线路和性能一般的机器，善于处理高并发的拉流观看需求，单位时长计费较低。

在通话模式下，TRTC 房间中的所有用户都会被分配到接口机上，相当于每个用户都是“主播”，每个用户随时都可以发言（最高的上行并发限制为50路），因此适合在线会议等场景，但单个房间的人数限制为300人。

示例代码

您可以登录 Github 获取本文档相关的示例代码。

说明：

如果访问 Github 较慢，您也可以直接下载 TXLiteAVSDK_TRTC_iOS_latest.zip。

操作步骤

步骤1：集成 SDK

您可以选择以下方式将 TRTC SDK 集成到项目中。

方式一：使用 CocoaPods 集成

1. 安装 CocoaPods ，具体操作请参考 CocoaPods 官网安装说明。

2. 打开您当前项目根目录下的Podfile文件，添加以下内容：

   说明：

   如果该目录下没有Podfile文件，请先执行pod init命令新建文件再添加以下内容。

   target 'Your Project' do
       pod 'TXLiteAVSDK_TRTC'
   end
   

3. 执行以下命令安装 TRTC SDK 。

   pod install
   

安装成功后当前项目根目录下会生成一个 xcworkspace 文件。
4. 打开新生成的 xcworkspace 文件即可。

方式二：下载 ZIP 包手动集成

如果您暂时不想安装 CocoaPods 环境，或者已经安装但是访问 CocoaPods 仓库比较慢，您可以直接下载 ZIP 压缩包，并参考 快速集成(iOS) 将 SDK 集成到您的工程中。

步骤2：添加媒体设备权限

在Info.plist文件中添加摄像头和麦克风的申请权限：

步骤3：初始化 SDK 实例并监听事件回调

1. 使用 sharedInstance() 接口创建TRTCCloud实例。

   // 创建 trtcCloud 实例
   _trtcCloud = [TRTCCloud sharedInstance];
   _trtcCloud.delegate = self;
   

2. 设置delegate属性注册事件回调，并监听相关事件和错误通知。

   // 错误通知是要监听的，需要捕获并通知用户
   - (void)onError:(TXLiteAVError)errCode errMsg:(NSString *)errMsg extInfo:(NSDictionary *)extInfo {
       if (ERR_ROOM_ENTER_FAIL == errCode) {
           [self toastTip:@"进房失败"];
           [self.trtcCloud exitRoom];
       }
   }

步骤4：组装进房参数 TRTCParams

在调用 enterRoom() 接口时需要填写一个关键参数 TRTCParams，该参数包含的必填字段如下表所示。

注意：

TRTC 同一时间不支持两个相同的 userId 进入房间，否则会相互干扰。

步骤5：创建并进入房间

1. 调用 enterRoom() 即可加入 TRTCParams 参数中roomId代指的音视频房间。如果该房间不存在，SDK 会自动创建一个以字段roomId的值为房间号的新房间。
2. 请根据应用场景设置合适的**appScene**参数，使用错误可能会导致卡顿率或画面清晰度不达预期。

• 视频通话，请设置为TRTCAppScene.videoCall。
• 语音通话，请设置为TRTCAppScene.audioCall。

3. 进房成功后，SDK 会回调onEnterRoom(result)事件。其中，参数result大于0时表示进房成功，具体数值为加入房间所消耗的时间，单位为毫秒（ms）；当result小于0时表示进房失败，具体数值为进房失败的错误码。

- (void)enterRoom() {
    TRTCParams *params = [TRTCParams new];
    params.sdkAppId = SDKAppID;
    params.roomId = _roomId;
    params.userId = _userId;
    params.role = TRTCRoleAnchor;
    params.userSig = [GenerateTestUserSig genTestUserSig:params.userId];
    [self.trtcCloud enterRoom:params appScene:TRTCAppSceneVideoCall];
}

- (void)onEnterRoom:(NSInteger)result {
    if (result > 0) {
        [self toastTip:@"进房成功"];
    } else {
        [self toastTip:@"进房失败"];
    }
}

注意：

• 如果进房失败，SDK 同时还会回调onError事件，并返回参数errCode（错误码）、errMsg（错误原因）以及extraInfo（保留参数）。
• 如果已在某一个房间中，则必须先调用exitRoom()退出当前房间，才能进入下一个房间。
• 每个端在应用场景 appScene 上必须要进行统一，否则会出现一些不可预料的问题。

步骤6：订阅远端的音视频流

SDK 支持自动订阅和手动订阅。

自动订阅模式（默认）

在自动订阅模式下，进入某个房间之后，SDK 会自动接收房间中其他用户的音频流，从而达到最佳的“秒开”效果：

1. 当房间中有其他用户在上行音频数据时，您会收到 onUserAudioAvailable() 事件通知，SDK 会自动播放这些远端用户的声音。
2. 您可以通过 muteRemoteAudio(userId, mute: true) 屏蔽某一个 userId 的音频数据，也可以通过 muteAllRemoteAudio(true) 屏蔽所有远端用户的音频数据，屏蔽后 SDK 不再继续拉取对应远端用户的音频数据。
3. 当房间中有其他用户在上行视频数据时，您会收到 onUserVideoAvailable() 事件通知，但此时 SDK 未收到该如何展示视频数据的指令，因此不会自动处理视频数据。您需要通过调用 startRemoteView(userId, view: view) 方法将远端用户的视频数据和显示view关联起来。
4. 您可以通过 setRemoteViewFillMode() 指定视频画面的显示模式：

• Fill 模式：表示填充，画面可能会等比放大和裁剪，但不会有黑边。
• Fit 模式：表示适应，画面可能会等比缩小以完全显示其内容，可能会有黑边。

5. 您可以通过 stopRemoteView(userId) 可以屏蔽某一个 userId 的视频数据，也可以通过 stopAllRemoteView() 屏蔽所有远端用户的视频数据，屏蔽后 SDK 不再继续拉取对应远端用户的视频数据。

// 实例代码：根据通知订阅（或取消订阅）远端用户的视频画面
- (void)onUserVideoAvailable:(NSString *)userId available:(BOOL)available {
    UIView* remoteView = remoteViewDic[userId];
    if (available) {
        [_trtcCloud startRemoteView:userId streamType:TRTCVideoStreamTypeSmall view:remoteView];
    } else {
        [_trtcCloud stopRemoteView:userId streamType:TRTCVideoStreamTypeSmall];
    }
}

说明：

如果您在收到onUserVideoAvailable()事件回调后没有立即调用startRemoteView()订阅视频流，SDK 将会在5s内停止接收来自远端的视频数据。

手动订阅模式

您可以通过 setDefaultStreamRecvMode() 接口将 SDK 指定为手动订阅模式。在手动订阅模式下，SDK 不会自动接收房间中其他用户的音视频数据，需要您手动通过 API 函数触发。

1. 在进房前调用 setDefaultStreamRecvMode(false, video: false) 接口将 SDK 设定为手动订阅模式。
2. 当房间中有其他用户在上行音频数据时，您会收到 onUserAudioAvailable() 事件通知。此时，您需要通过调用 muteRemoteAudio(userId, mute: false) 手动订阅该用户的音频数据，SDK 会在接收到该用户的音频数据后解码并播放。
3. 当房间中有其他用户在上行视频数据时，您会收到 onUserVideoAvailable() 事件通知。此时，您需要通过调用 startRemoteView(userId, view: view) 方法手动订阅该用户的视频数据，SDK 会在接收到该用户的视频数据后解码并播放。

步骤7：发布本地的音视频流

1. 调用 startLocalAudio() 可以开启本地的麦克风采集，并将采集到的声音编码并发送出去。
2. 调用 startLocalPreview() 可以开启本地的摄像头，并将采集到的画面编码并发送出去。
3. 调用 setLocalViewFillMode() 可以设定本地视频画面的显示模式：

• Fill 模式表示填充，画面可能会被等比放大和裁剪，但不会有黑边。
• Fit 模式表示适应，画面可能会等比缩小以完全显示其内容，可能会有黑边。

4. 调用 setVideoEncoderParam() 接口可以设定本地视频的编码参数，该参数将决定房间里其他用户观看您的画面时所感受到的 画面质量。

//示例代码：发布本地的音视频流
[self.trtcCloud startLocalPreview:_isFrontCamera view:self.view];
[self.trtcCloud startLocalAudio:TRTCAudioQualityMusic];

注意：

Mac 版 SDK 默认会使用当前系统默认的摄像头和麦克风。您可以通过调用 setCurrentCameraDevice() 和 setCurrentMicDevice() 选择其他摄像头和麦克风。

步骤8：退出当前房间

调用 exitRoom() 方法退出房间，SDK 在退房时需要关闭和释放摄像头、麦克风等硬件设备，因此退房动作并非瞬间完成的，需收到 onExitRoom() 回调后才算真正完成退房操作。

// 调用退房后请等待 onExitRoom 事件回调
[self.trtcCloud exitRoom];

- (void)onExitRoom:(NSInteger)reason {
    NSLog(@"离开房间: reason: %ld", reason)
}

注意：

如果您的 App 中同时集成了多个音视频 SDK，请在收到onExitRoom回调后再启动其它音视频 SDK，否则可能会遇到硬件占用问题。