tencent cloud

适用场景

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

原理解析

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

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

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

示例代码

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

说明：

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

操作步骤

步骤1：集成 SDK

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

方式一：自动加载（aar）

TRTC SDK 已发布到 mavenCentral 库，您可以通过配置 gradle 自动下载更新。
您只需用 Android Studio 打开待集成 SDK 的工程（TRTC-API-Example 已完成集成，示例代码可以供您参考），然后通过简单的步骤修改app/build.gradle文件，即可完成 SDK 集成：

1. 在 dependencies 中添加 TRTCSDK 的依赖。

   dependencies {
     compile 'com.tencent.liteav:LiteAVSDK_TRTC:latest.release'
   }
   

2. 在 defaultConfig 中，指定 App 使用的 CPU 架构。

   说明：

   目前 TRTC SDK 支持 armeabi-v7a 和 arm64-v8a。

   defaultConfig {
     ndk {
         abiFilters "armeabi-v7a", "arm64-v8a"
     }
   }
   

3. 单击【Sync Now】同步 SDK。
   如果您的网络连接 mavenCentral 没有问题，SDK 会自动下载集成到工程中。

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

您可以直接下载 ZIP 压缩包，并参考 快速集成(Android) 将 SDK 集成到您的工程中。

步骤2：配置 App 权限

在AndroidManifest.xml文件中添加摄像头、麦克风以及网络的申请权限。

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />

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

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

   // 创建 trtcCloud 实例
   mTRTCCloud = TRTCCloud.sharedInstance(getApplicationContext());
   mTRTCCloud.setListener(new TRTCCloudListener(){
   // 回调处理
   ...
   });
   

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

   // 错误通知监听，错误通知意味着 SDK 不能继续运行
   @Override
   public void onError(int errCode, String errMsg, Bundle extraInfo) {
   Log.d(TAG, "sdk callback onError");
   if (activity != null) {
       Toast.makeText(activity, "onError: " + errMsg + "[" + errCode+ "]" , Toast.LENGTH_SHORT).show();
       if (errCode == TXLiteAVCode.ERR_ROOM_ENTER_FAIL) {
           activity.exitRoom();
       }
   }
   }
   

步骤4：组装进房参数 TRTCParams

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

参数名称	字段类型	补充说明	填写示例
sdkAppId	数字	应用 ID，您可以在 实时音视频控制台 中查看 SDKAppID。	1400000123
userId	字符串	只允许包含大小写英文字母（a-z、A-Z）、数字（0-9）及下划线和连词符。建议结合业务实际账号体系自行设置。	test_user_001
userSig	字符串	基于 userId 可以计算出 userSig，计算方法请参见 [如何计算及使用 UserSig]](https://www.tencentcloud.com/document/product/647/35166)。	eJyrVareCeYrSy1SslI...
roomId	数字	数字类型的房间号。如果您想使用字符串形式的房间号，请使用 TRTCParams 中的 strRoomId。	29834

注意：

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

步骤5：创建并进入房间

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

• 视频通话，请设置为TRTC_APP_SCENE_VIDEOCALL。
• 语音通话，请设置为TRTC_APP_SCENE_AUDIOCALL。

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

public void enterRoom() {
  TRTCCloudDef.TRTCParams trtcParams = new TRTCCloudDef.TRTCParams();
  trtcParams.sdkAppId = sdkappid;
  trtcParams.userId = userid;
  trtcParams.roomId = 908;
  trtcParams.userSig = usersig;
  mTRTCCloud.enterRoom(trtcParams, TRTC_APP_SCENE_VIDEOCALL);
}
@Override
public void onEnterRoom(long result) {
  if (result > 0) {
      toastTip("进房成功，总计耗时[\(result)]ms")
  } else {
      toastTip("进房失败，错误码[\(result)]")
  }
}

注意：

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

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

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

自动订阅模式（默认）

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

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

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

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

@Override
public void onUserVideoAvailable(String userId, boolean available) {
  TXCloudVideoView remoteView = remoteViewDic[userId];
  if (available) {
      mTRTCCloud.startRemoteView(userId, remoteView);
      mTRTCCloud.setRemoteViewFillMode(userId, TRTC_VIDEO_RENDER_MODE_FIT);
  } else {
      mTRTCCloud.stopRemoteView(userId);
  }
}

说明：

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

手动订阅模式

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

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

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

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

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

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

   //示例代码：发布本地的音视频流
   mTRTCCloud.setLocalViewFillMode(TRTC_VIDEO_RENDER_MODE_FIT);
   mTRTCCloud.startLocalPreview(mIsFrontCamera, mLocalView);
   mTRTCCloud.startLocalAudio();
   

步骤8：退出当前房间

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

// 调用退房后请等待 onExitRoom 事件回调
mTRTCCloud.exitRoom()
@Override
public void onExitRoom(int reason) {
  Log.i(TAG, "onExitRoom: reason = " + reason);
}

注意：

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