TRTC 云助手 Android

三、步骤1：开通服务

语聊房场景通常需要依赖腾讯云 即时通信 IM 和 实时音视频 TRTC 两项付费 PaaS 服务构建。

1. 首先你需要登录 实时音视频 TRTC 控制台 创建应用，此时在 即时通信 IM 控制台 会同步自动创建一个与当前 TRTC 应用相同 SDKAppID 的 IM 体验版应用，二者账号与鉴权体系可复用。后续你可根据需要选择升级 TRTC 或 IM 应用版本，例如旗舰版可解锁更多增值功能服务。

注意：说明：

2. 创建应用完毕之后，你可以在应用管理-应用概览栏目看到该应用的基本信息，其中需要你保管好 SDKAppID、SDKSecretKey 便于后续使用，同时应避免密钥泄露造成流量盗刷。

四、步骤2：导入 SDK

TRTC SDK 和 IM SDK 已经发布到 mavenCentral 库，你可以通过配置 gradle 自动下载更新。

1. 在 dependencies 中添加合适版本 SDK 的依赖。

// TRTC 精简版 SDK, 包含 TRTC 和直播播放两项功能（推荐）dependencies { implementation 'com.tencent.liteav:LiteAVSDK_TRTC:latest.release'}// 全功能版 SDK, 包含 TRTC、直播、短视频、播放器等多项功能dependencies { implementation 'com.tencent.liteav:LiteAVSDK_Professional:latest.release'}// 基础版 IM SDK dependencies { api 'com.tencent.imsdk:imsdk:latest.release'}// 增强版 IM SDK（推荐）dependencies { api 'com.tencent.imsdk:imsdk-plus:latest.release'}

注意：说明：

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

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

注意：说明：

注意：TRTC SDK 和 IM SDK 都支持 armeabi-v7a/arm64-v8a/x86/x86_64 架构，为了缩减安装包体积，你可以选择只打包部分架构的 SO 文件。

五、步骤3：工程配置

1. 在 AndroidManifest.xml 中配置 App 权限，语聊场景下 TRTC SDK 及 IM SDK 需要以下权限：

<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.RECORD_AUDIO" /><uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" /><uses-permission android:name="android.permission.BLUETOOTH" />

2. 由于我们在 SDK 内部使用了 Java 的反射特性，需要你在 proguard-rules.pro 文件中将 TRTC SDK 相关类加入不混淆名单：

-keep class com.tencent.** { *; }

七、步骤1：生成鉴权凭证

UserSig 是腾讯云设计的一种安全保护签名，目的是为了阻止恶意攻击者盗用你的云服务使用权。腾讯云实时音视频（TRTC）、即时通信（IM）服务都采用了该套安全保护机制，TRTC 在进房时鉴权，IM 在登录时鉴权。

·调试跑通阶段：可以通过 客户端示例代码 和 控制台 两种方法计算生成 UserSig，仅用于调试测试。

·正式运行阶段：推荐安全等级更高的服务端计算 UserSig 方案，防止客户端被逆向破解泄露密钥。

具体实现流程如下：

1. 你的 App 在调用 SDK 的初始化函数之前，首先要向你的服务器请求 UserSig。

2. 你的服务器根据 SDKAppID 和 UserID 计算 UserSig。

3. 服务器将计算好的 UserSig 返回给你的 App。

4. 你的 App 将获得的 UserSig 通过特定 API 传递给 SDK。

5. SDK 将 SDKAppID + UserID + UserSig 提交给腾讯云服务器进行校验。

6. 腾讯云校验 UserSig，确认合法性。

7. 校验通过后，会向 IM SDK 提供即时通信服务、TRTC SDK 提供实时音视频服务。

九、时序图

1. IM SDK 初始化与添加事件监听器。

// 添加事件监听器V2TIMManager.getInstance().addIMSDKListener(imSdkListener);// 初始化 IM SDK，调用这个接口后，可以立即调用登录接口V2TIMManager.getInstance().initSDK(context, sdkAppID, null);// SDK 初始化后会抛出一些事件，例如连接状态、登录票据过期等private V2TIMSDKListener imSdkListener = new V2TIMSDKListener() { @Override public void onConnecting() { Log.d(TAG, "IM SDK 正在连接到腾讯云服务器"); } @Override public void onConnectSuccess() { Log.d(TAG, "IM SDK 已经成功连接到腾讯云服务器"); }};// 移除事件监听器V2TIMManager.getInstance().removeIMSDKListener(imSdkListener);// 反初始化 IM SDKV2TIMManager.getInstance().unInitSDK();

注意：说明：

注意：如果你的应用生命周期跟 SDK 生命周期一致，退出应用前可以不进行反初始化。若你只在进入特定界面后才初始化 SDK，退出界面后不再使用，可以对 SDK 进行反初始化。

2. TRTC SDK 创建实例与设置事件监听器。

// 创建 TRTC SDK 实例（单例模式）TRTCCloud mTRTCCloud = TRTCCloud.sharedInstance(context);// 设置事件监听器mTRTCCloud.setListener(trtcSdkListener);// 来自 SDK 的各类事件通知（比如：错误码，警告码，音视频状态参数等）private TRTCCloudListener trtcSdkListener = new TRTCCloudListener() { @Override public void onError(int errCode, String errMsg, Bundle extraInfo) { Log.d(TAG, errCode + errMsg); } @Override public void onWarning(int warningCode, String warningMsg, Bundle extraInfo) { Log.d(TAG, warningCode + warningMsg); }};// 移除事件监听器mTRTCCloud.setListener(null);// 销毁 TRTC SDK 实例（单例模式）TRTCCloud.destroySharedInstance();

注意：说明：

注意：建议监听 SDK 事件通知，对一些常见错误进行日志打印和处理，详见 错误码表。

十、步骤3：登录与登出

初始化 IM SDK 后，你需要调用 SDK 登录接口验证账号身份，获得账号的功能使用权限。因此在使用其他功能之前，请务必确保登录成功，否则可能导致功能异常或不可用。如你仅需使用 TRTC 音视频服务，可忽略此步骤。

十一、时序图

1. 登录。

// 登录：userID 可自定义，userSig 参考步骤一生成获取V2TIMManager.getInstance().login(userID, userSig, new V2TIMCallback() { @Override public void onSuccess() { Log.i("imsdk", "success"); } @Override public void onError(int code, String desc) { // 如果返回以下错误码，表示使用 UserSig 已过期，请你使用新签发的 UserSig 进行再次登录。 // 1. ERR_USER_SIG_EXPIRED（6206） // 2. ERR_SVR_ACCOUNT_USERSIG_EXPIRED（70001） // 注意：其他的错误码，请不要在这里调用登录接口，避免 IM SDK 登录进入死循环。 Log.i("imsdk", "failure, code:" + code + ", desc:" + desc); }});

2. 登出。

// 登出V2TIMManager.getInstance().logout(new V2TIMCallback() { @Override public void onSuccess() { Log.i("imsdk", "success"); } @Override public void onError(int code, String desc) { Log.i("imsdk", "failure, code:" + code + ", desc:" + desc); }});

注意：说明：

注意：如果你的应用生命周期跟 IM SDK 生命周期一致，退出应用前可以不登出。若你只在进入特定界面后才使用 IM SDK，退出界面后不再使用，可以进行登出操作和对 IM SDK 进行反初始化。

十三、时序图

1. 创建房间。主播（房主）开播时需要创建房间，这里的“房间”概念对应 IM 中的“群组”。本例仅展示客户端创建 IM 群组的方式，实际也可在 服务端创建群组。

V2TIMManager.getInstance().createGroup(V2TIMManager.GROUP_TYPE_AVCHATROOM, groupID, groupName, new V2TIMValueCallback<String>() { @Override public void onSuccess(String s) { // 创建群组成功 } @Override public void onError(int code, String desc) { // 创建群组失败 }});// 监听群组创建通知V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() { @Override public void onGroupCreated(String groupID) { // 群创建回调，groupID 为新创建群组的 ID }});

2. 加入房间。

·加入 IM 群组。

V2TIMManager.getInstance().joinGroup(groupID, message, new V2TIMCallback() { @Override public void onSuccess() { // 加入群组成功 } @Override public void onError(int code, String desc) { // 加入群组失败 }});// 监听加入群组事件V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() { @Override public void onMemberEnter(String groupID, List<V2TIMGroupMemberInfo> memberList) { // 有人加入群组 }});

·加入 TRTC 房间。

private void enterRoom(String roomId, String userId) { TRTCCloudDef.TRTCParams params = new TRTCCloudDef.TRTCParams(); // 以字符串房间号为例，建议和 IM 群组号保持一致 params.strRoomId = roomId; params.userId = userId; // 从业务后台获取到的 UserSig params.userSig = getUserSig(userId); // 替换成你的 SDKAppID params.sdkAppId = SDKAppID; // 语聊互动场景进房需指定用户角色 params.role = TRTCCloudDef.TRTCRoleAudience; // 以语聊互动进房场景为例 mTRTCCloud.enterRoom(params, TRTCCloudDef.TRTC_APP_SCENE_VOICE_CHATROOM);}// 进房结果事件回调@Overridepublic void onEnterRoom(long result) { if (result > 0) { // result 代表加入房间所消耗的时间(毫秒) Log.d(TAG, "Enter room succeed"); } else { // result 代表进房失败的错误码 Log.d(TAG, "Enter room failed"); }}

3. 退出房间。

·退出 IM 群组。

V2TIMManager.getInstance().quitGroup(groupID, new V2TIMCallback() { @Override public void onSuccess() { // 退出群组成功 } @Override public void onError(int code, String desc) { // 退出群组失败 }});V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() { @Override public void onMemberLeave(String groupID, V2TIMGroupMemberInfo member) { // 群成员离开回调 }});

注意：直播群（AVChatRoom）中，群主是不可以退群的，群主只能调用 dismissGroup 解散群组。

·退出 TRTC 房间。

private void exitRoom() { mTRTCCloud.stopLocalAudio(); mTRTCCloud.exitRoom();}// 离开房间事件回调@Overridepublic void onExitRoom(int reason) { if (reason == 0) { Log.d(TAG, "主动调用 exitRoom 退出房间"); } else if (reason == 1) { Log.d(TAG, "被服务器踢出当前房间"); } else if (reason == 2) { Log.d(TAG, "当前房间整个被解散"); }}

4. 解散房间。

·解散 IM 群组。本例仅展示客户端解散 IM 群组的方式，实际也可在 服务端解散群组。

V2TIMManager.getInstance().dismissGroup(groupID, new V2TIMCallback() { @Override public void onSuccess() { // 解散群组成功 } @Override public void onError(int code, String desc) { // 解散群组失败 }});V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() { @Override public void onGroupDismissed(String groupID, V2TIMGroupMemberInfo opUser) { // 群被解散回调 }});

·解散 TRTC 房间。

·服务端解散：TRTC 提供了 服务端解散房间 API DismissRoom（区分数字房间 ID 和字符串房间 ID），你可以调用此接口把房间所有用户从房间移出，并解散房间。

·客户端解散：通过各个客户端的退出房间 exitRoom 接口，将房间内的所有主播和听众完成退房，退房后，根据 TRTC 房间生命周期规则，房间将会自动解散，详情请参见 退出房间。

注意：建议当你的一次直播任务结束后，可以调用解散房间 API 确保房间解散，防止听众意外进房导致产生非期望的费用。

十五、时序图

首先，我们可以创建一个用于保存麦位信息的 JavaBean。

public class SeatInfo implements Serializable { public static final transient int STATUS_UNUSED = 0; public static final transient int STATUS_USED = 1; public static final transient int STATUS_LOCKED = 2; // 座位状态，对应三种状态 public int status; // 座位是否禁言 public boolean mute; // 座位占用时，存储用户信息 public String userId; @Override public String toString() { return "TXSeatInfo{" + "status=" + status + ", mute=" + mute + ", user='" + userId + '\\'' + '}'; }}

1. 主动上麦。

主动上麦是指麦下听众向房主或管理员发送上麦申请，待接收到同意信令后上麦。如为自由上麦模式，则可忽略信令请求部分。

·听众发送上麦请求。

// 听众发送上麦请求，userId 为主播 ID，data 可传入标识信令的 jsonprivate String sendInvitation(String userId, String data) { return V2TIMManager.getSignalingManager().invite(userId, data, true, null, 0, new V2TIMCallback() { @Override public void onError(int i, String s) { Log.e(TAG, "sendInvitation error " + i); } @Override public void onSuccess() { Log.i(TAG, "sendInvitation success "); } });}// 主播收到上麦请求, inviteID 为该条请求 ID，inviter 为请求者 IDV2TIMManager.getSignalingManager().addSignalingListener(new V2TIMSignalingListener() { @Override public void onReceiveNewInvitation(String inviteID, String inviter, String groupId, List<String> inviteeList, String data) { Log.i(TAG, "received invitation: " + inviteID + " from " + inviter); }});

·主播处理上麦请求。

// 同意上麦请求private void acceptInvitation(String inviteID, String data) { V2TIMManager.getSignalingManager().accept(inviteID, data, new V2TIMCallback() { @Override public void onError(int i, String s) { Log.e(TAG, "acceptInvitation error " + i); } @Override public void onSuccess() { Log.i(TAG, "acceptInvitation success "); } });}// 拒绝上麦请求private void rejectInvitation(String inviteID, String data) { V2TIMManager.getSignalingManager().reject(inviteID, data, new V2TIMCallback() { @Override public void onError(int i, String s) { Log.e(TAG, "rejectInvitation error " + i); } @Override public void onSuccess() { Log.i(TAG, "rejectInvitation success "); } });}

·听众上麦。

如果主播同意听众的上麦请求，听众可以通过修改群属性的方式添加麦位信息，其他用户会收到群属性变更回调，更新本地麦位信息。

// 本地保存的全量麦位信息列表private List<SeatInfo> mSeatInfoList;// 同意上麦请求的回调V2TIMManager.getSignalingManager().addSignalingListener(new V2TIMSignalingListener() { @Override public void onInviteeAccepted(String inviteID, String invitee, String data) { Log.i(TAG, "received accept invitation: " + inviteID + " from " + invitee); takeSeat(seatIndex); }});// 听众开始上麦private void takeSeat(int seatIndex) { // 创建麦位信息实例，存储修改后的麦位信息 SeatInfo localInfo = mSeatInfoList.get(seatIndex); SeatInfo seatInfo = new SeatInfo(); seatInfo.status = SeatInfo.STATUS_USED; seatInfo.mute = localInfo.mute; seatInfo.userId = mUserId; // 将麦位信息对象序列化为 JSON 格式 Gson gson = new Gson(); String json = gson.toJson(seatInfo, SeatInfo.class); HashMap<String, String> map = new HashMap<>(); map.put("seat" + seatIndex, json); // 设置群属性，已有该群属性则更新其 value 值，没有该群属性则添加该属性 V2TIMManager.getGroupManager().setGroupAttributes(groupId, map, new V2TIMCallback() { @Override public void onError(int code, String message) { // 修改群属性失败，上麦失败 } @Override public void onSuccess() { // 修改群属性成功，切换 TRTC 角色并开始推流 mTRTCCloud.switchRole(TRTCCloudDef.TRTCRoleAnchor); mTRTCCloud.startLocalAudio(TRTCCloudDef.TRTC_AUDIO_QUALITY_DEFAULT); } });}

2. 抱人上麦。

主播抱人上麦（无需听众同意），直接修改群属性保存的麦位信息，对应听众收到群属性变更回调后匹配 userId 成功即可切换 TRTC 角色并开始推流。如为邀请上麦模式，可参照主动上麦的实现逻辑，只需调换信令的发送方与接收方即可。

// 本地保存的全量麦位信息列表private List<SeatInfo> mSeatInfoList;// 主播端调用该接口修改群属性保存的麦位信息private void pickSeat(String userId, int seatIndex) { // 创建麦位信息实例，存储修改后的麦位信息 SeatInfo localInfo = mSeatInfoList.get(seatIndex); SeatInfo seatInfo = new SeatInfo(); seatInfo.status = SeatInfo.STATUS_USED; seatInfo.mute = localInfo.mute; seatInfo.userId = userId; // 将麦位信息对象序列化为 JSON 格式 Gson gson = new Gson(); String json = gson.toJson(seatInfo, SeatInfo.class); HashMap<String, String> map = new HashMap<>(); map.put("seat" + seatIndex, json); // 设置群属性，已有该群属性则更新其 value 值，没有该群属性则添加该属性 V2TIMManager.getGroupManager().setGroupAttributes(groupId, map, new V2TIMCallback() { @Override public void onError(int code, String message) { // 修改群属性失败，抱麦失败 } @Override public void onSuccess() { // 修改群属性成功，触发 onGroupAttributeChanged 回调 } });}// 听众端收到群属性变更回调，匹配自身信息成功后开始推流V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() { @Override public void onGroupAttributeChanged(String groupID, Map<String, String> groupAttributeMap) { // 上一次本地保存的全量麦位信息列表 final List<SeatInfo> oldSeatInfoList = mSeatInfoList; // 最新从 groupAttributeMap 中解析的全量麦位信息列表 final List<SeatInfo> newSeatInfoList = getSeatListFromAttr(groupAttributeMap, seatSize); // 遍历全量麦位信息列表，对比新旧麦位信息 for (int i = 0; i < seatSize; i++) { SeatInfo oldInfo = oldSeatInfoList.get(i); SeatInfo newInfo = newSeatInfoList.get(i); if (oldInfo.status != newInfo.status && newInfo.status == SeatInfo.STATUS_USED) { if (newInfo.userId.equals(mUserId)) { // 匹配自身信息成功，切换 TRTC 角色并开始推流 mTRTCCloud.switchRole(TRTCCloudDef.TRTCRoleAnchor); mTRTCCloud.startLocalAudio(TRTCCloudDef.TRTC_AUDIO_QUALITY_DEFAULT); } else { // 更新本地麦位列表，渲染本地麦位视图 } } } }});

3. 主动下麦。

连麦听众可以通过修改群属性的方式重置麦位信息，其他用户会收到群属性变更回调，更新本地麦位信息。

// 本地保存的全量麦位信息列表private List<SeatInfo> mSeatInfoList;private void leaveSeat(int seatIndex) { // 创建麦位信息实例，存储修改后的麦位信息 SeatInfo localInfo = mSeatInfoList.get(seatIndex); SeatInfo seatInfo = new SeatInfo(); seatInfo.status = SeatInfo.STATUS_UNUSED; seatInfo.mute = localInfo.mute; seatInfo.userId = ""; // 将麦位信息对象序列化为 JSON 格式 Gson gson = new Gson(); String json = gson.toJson(seatInfo, SeatInfo.class); HashMap<String, String> map = new HashMap<>(); map.put("seat" + seatIndex, json); // 设置群属性，已有该群属性则更新其 value 值，没有该群属性则添加该属性 V2TIMManager.getGroupManager().setGroupAttributes(groupId, map, new V2TIMCallback() { @Override public void onError(int code, String message) { // 修改群属性失败，下麦失败 } @Override public void onSuccess() { // 修改群属性成功，切换 TRTC 角色并停止推流 mTRTCCloud.switchRole(TRTCCloudDef.TRTCRoleAudience); mTRTCCloud.stopLocalAudio(); } });}

4. 踢人下麦。

主播踢人下麦，直接修改群属性保存的麦位信息，对应连麦听众收到群属性变更回调后匹配 userId 成功即可切换 TRTC 角色并停止推流。

// 本地保存的全量麦位信息列表private List<SeatInfo> mSeatInfoList;// 主播端调用该接口修改群属性保存的麦位信息private void kickSeat(int seatIndex) { // 创建麦位信息实例，存储修改后的麦位信息 SeatInfo localInfo = mSeatInfoList.get(seatIndex); SeatInfo seatInfo = new SeatInfo(); seatInfo.status = SeatInfo.STATUS_UNUSED; seatInfo.mute = localInfo.mute; seatInfo.userId = ""; // 将麦位信息对象序列化为 JSON 格式 Gson gson = new Gson(); String json = gson.toJson(seatInfo, SeatInfo.class); HashMap<String, String> map = new HashMap<>(); map.put("seat" + seatIndex, json); // 设置群属性，已有该群属性则更新其 value 值，没有该群属性则添加该属性 V2TIMManager.getGroupManager().setGroupAttributes(groupId, map, new V2TIMCallback() { @Override public void onError(int code, String message) { // 修改群属性失败，踢麦失败 } @Override public void onSuccess() { // 修改群属性成功，触发 onGroupAttributeChanged 回调 } });}// 连麦听众端收到群属性变更回调，匹配自身信息成功后停止推流V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() { @Override public void onGroupAttributeChanged(String groupID, Map<String, String> groupAttributeMap) { // 上一次本地保存的全量麦位信息列表 final List<SeatInfo> oldSeatInfoList = mSeatInfoList; // 最新从 groupAttributeMap 中解析的全量麦位信息列表 final List<SeatInfo> newSeatInfoList = getSeatListFromAttr(groupAttributeMap, seatSize); // 遍历全量麦位信息列表，对比新旧麦位信息 for (int i = 0; i < seatSize; i++) { SeatInfo oldInfo = oldSeatInfoList.get(i); SeatInfo newInfo = newSeatInfoList.get(i); if (oldInfo.status != newInfo.status && newInfo.status == SeatInfo.STATUS_UNUSED) { if (oldInfo.userId.equals(mUserId)) { // 匹配自身信息成功，切换 TRTC 角色并停止推流 mTRTCCloud.switchRole(TRTCCloudDef.TRTCRoleAudience); mTRTCCloud.stopLocalAudio(); } else { // 更新本地麦位列表，渲染本地麦位视图 } } } }});

5. 麦位禁音。

主播禁音/解禁某个麦位，直接修改群属性保存的麦位信息，对应连麦听众收到群属性变更回调后匹配 userId 成功即可暂停/恢复本地推流。

// 本地保存的全量麦位信息列表private List<SeatInfo> mSeatInfoList;// 主播端调用该接口修改群属性保存的麦位信息private void muteSeat(int seatIndex, boolean mute) { // 创建麦位信息实例，存储修改后的麦位信息 SeatInfo localInfo = mSeatInfoList.get(seatIndex); SeatInfo seatInfo = new SeatInfo(); seatInfo.status = localInfo.status; seatInfo.mute = mute; seatInfo.userId = localInfo.userId; // 将麦位信息对象序列化为 JSON 格式 Gson gson = new Gson(); String json = gson.toJson(seatInfo, SeatInfo.class); HashMap<String, String> map = new HashMap<>(); map.put("seat" + seatIndex, json); // 设置群属性，已有该群属性则更新其 value 值，没有该群属性则添加该属性 V2TIMManager.getGroupManager().setGroupAttributes(groupId, map, new V2TIMCallback() { @Override public void onError(int code, String message) { // 修改群属性失败，禁麦失败 } @Override public void onSuccess() { // 修改群属性成功，触发 onGroupAttributeChanged 回调 } });}// 连麦听众端收到群属性变更回调，匹配自身信息成功后暂停/恢复推流V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() { @Override public void onGroupAttributeChanged(String groupID, Map<String, String> groupAttributeMap) { // 上一次本地保存的全量麦位信息列表 final List<SeatInfo> oldSeatInfoList = mSeatInfoList; // 最新从 groupAttributeMap 中解析的全量麦位信息列表 final List<SeatInfo> newSeatInfoList = getSeatListFromAttr(groupAttributeMap, seatSize); // 遍历全量麦位信息列表，对比新旧麦位信息 for (int i = 0; i < seatSize; i++) { SeatInfo oldInfo = oldSeatInfoList.get(i); SeatInfo newInfo = newSeatInfoList.get(i); if (oldInfo.mute != newInfo.mute) { if (oldInfo.userId.equals(mUserId)) { // 匹配自身信息成功，暂停/恢复本地推流 mTRTCCloud.muteLocalAudio(newInfo.mute); } else { // 更新本地麦位列表，渲染本地麦位视图 } } } }});

6. 麦位锁定。

主播锁定/解锁某个麦位，直接修改群属性保存的麦位信息，听众收到群属性变更回调后更新对应麦位视图。

// 本地保存的全量麦位信息列表private List<SeatInfo> mSeatInfoList;// 主播端调用该接口修改群属性保存的麦位信息private void lockSeat(int seatIndex, boolean isLock) { // 创建麦位信息实例，存储修改后的麦位信息 SeatInfo localInfo = mSeatInfoList.get(seatIndex); SeatInfo seatInfo = new SeatInfo(); seatInfo.status = isLock ? SeatInfo.STATUS_LOCKED : SeatInfo.STATUS_UNUSED; seatInfo.mute = localInfo.mute; seatInfo.userId = ""; // 将麦位信息对象序列化为 JSON 格式 Gson gson = new Gson(); String json = gson.toJson(seatInfo, SeatInfo.class); HashMap<String, String> map = new HashMap<>(); map.put("seat" + seatIndex, json); // 设置群属性，已有该群属性则更新其 value 值，没有该群属性则添加该属性 V2TIMManager.getGroupManager().setGroupAttributes(groupId, map, new V2TIMCallback() { @Override public void onError(int code, String message) { // 修改群属性失败，锁麦失败 } @Override public void onSuccess() { // 修改群属性成功，触发 onGroupAttributeChanged 回调 } });}// 听众端收到群属性变更回调，更新对应麦位视图V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() { @Override public void onGroupAttributeChanged(String groupID, Map<String, String> groupAttributeMap) { // 上一次本地保存的全量麦位信息列表 final List<SeatInfo> oldSeatInfoList = mSeatInfoList; // 最新从 groupAttributeMap 中解析的全量麦位信息列表 final List<SeatInfo> newSeatInfoList = getSeatListFromAttr(groupAttributeMap, seatSize); // 遍历全量麦位信息列表，对比新旧麦位信息 for (int i = 0; i < seatSize; i++) { SeatInfo oldInfo = oldSeatInfoList.get(i); SeatInfo newInfo = newSeatInfoList.get(i); if (oldInfo.status == SeatInfo.STATUS_LOCKED && newInfo.status == SeatInfo.STATUS_UNUSED) { // 解锁麦位 } else if (oldInfo.status != newInfo.status && newInfo.status == SeatInfo.STATUS_LOCKED) { // 锁定麦位 } } }});

7. 麦位移动。

麦上主播移动麦位，需要分别修改群属性保存的源和目标麦位信息，听众收到群属性变更回调后更新对应麦位视图。

// 本地保存的全量麦位信息列表private List<SeatInfo> mSeatInfoList;// 麦上主播调用该接口修改群属性保存的麦位信息private void moveSeat(int dstIndex) { // 根据 userId 获取源麦位编号 int srcIndex = -1; for (int i = 0; i < mSeatInfoList.size(); i++) { SeatInfo seatInfo = mSeatInfoList.get(i); if (seatInfo != null && mUserId.equals(seatInfo.userId)) { srcIndex = i; break; } } // 根据麦位编号获取对应麦位信息 SeatInfo srcSeatInfo = mSeatInfoList.get(srcIndex); SeatInfo dstSeatInfo = mSeatInfoList.get(dstIndex); // 创建麦位信息实例，存储修改后的源麦位信息 SeatInfo srcChangeInfo = new SeatInfo(); srcChangeInfo.status = SeatInfo.STATUS_UNUSED; srcChangeInfo.mute = srcSeatInfo.mute; srcChangeInfo.userId = ""; // 创建麦位信息实例，存储修改后的目标麦位信息 SeatInfo dstChangeInfo = new SeatInfo(); dstChangeInfo.status = SeatInfo.STATUS_USED; dstChangeInfo.mute = dstSeatInfo.mute; dstChangeInfo.userId = mUserId; // 将麦位信息对象序列化为 JSON 格式 Gson gson = new Gson(); HashMap<String, String> map = new HashMap<>(); String json = gson.toJson(srcChangeInfo, SeatInfo.class); map.put("seat" + srcIndex, json); json = gson.toJson(dstChangeInfo, SeatInfo.class); map.put("seat" + dstIndex, json); // 设置群属性，已有该群属性则更新其 value 值，没有该群属性则添加该属性 V2TIMManager.getGroupManager().setGroupAttributes(groupId, map, new V2TIMCallback() { @Override public void onError(int code, String message) { // 修改群属性失败，移麦失败 } @Override public void onSuccess() { // 修改群属性成功，移麦成功 } });}

十七、时序图

1. 订阅模式。

TRTC SDK 默认为自动订阅音频流逻辑，用户进房会自动开始播放远端用户的声音。如有手动订阅音频流的需求，需要额外调用 muteRemoteAudio(userId, mute) 来订阅和播放远端用户音频流。

// 自动订阅模式（默认）mTRTCCloud.setDefaultStreamRecvMode(true, true);// 手动订阅模式（自定义）mTRTCCloud.setDefaultStreamRecvMode(false, false);

注意：设置订阅模式 setDefaultStreamRecvMode 必须在进房 enterRoom 之前调用才会生效。

2. 采集与发布。

// 开启本地音频的采集和发布mTRTCCloud.startLocalAudio(TRTCCloudDef.TRTC_AUDIO_QUALITY_DEFAULT)// 停止本地音频的采集和发布mTRTCCloud.stopLocalAudio();

注意：说明：

注意：startLocalAudio 会申请麦克风使用权限，stopLocalAudio 会释放麦克风使用权限。

3. 闭麦与开麦。

// 暂停发布本地音频流（闭麦）mTRTCCloud.muteLocalAudio(true);// 恢复发布本地音频流（开麦）mTRTCCloud.muteLocalAudio(false);// 暂停订阅和播放某远端用户的音频流mTRTCCloud.muteRemoteAudio(userId, true);// 恢复订阅和播放某远端用户的音频流mTRTCCloud.muteRemoteAudio(userId, false);// 暂停订阅和播放所有远端用户的音频流mTRTCCloud.muteAllRemoteAudio(true);// 恢复订阅和播放所有远端用户的音频流mTRTCCloud.muteAllRemoteAudio(false);

注意：说明：

注意：相比之下，muteLocalAudio 只需要在软件层面对数据流进行暂停或者放行即可，因此效率更高更平滑，也更适合需要频繁开闭麦的场景。

4. 音质及音量类型。

·音质设置。

// 本地音频采集和发布时设置音质mTRTCCloud.startLocalAudio(TRTCCloudDef.TRTC_AUDIO_QUALITY_DEFAULT);// 音频推流过程中动态设置音质mTRTCCloud.setAudioQuality(TRTCCloudDef.TRTC_AUDIO_QUALITY_DEFAULT);

注意：说明：

注意：TRTC 预设音质共分为三档（Speech/Default/Music）分别对应不同的音频参数，详见 音频音质。

·音量类型设置。

TRTC 每档音质都对应有默认的音量类型，如需强制指定音量类型可以使用如下接口。

// 设置音量类型mTRTCCloud.setSystemVolumeType(TRTCCloudDef.TRTCSystemVolumeTypeAuto);

注意：说明：

注意：TRTC 音量类型共分为三档（VOIP/Auto/Media）分别对应不同的音量通道，详见 音量类型。

·音频路由设置。

移动端设备上通常有扬声器和听筒两个播放位置，如需强制指定音频路由可以使用如下接口。

// 设置音频路由mTRTCCloud.setAudioRoute(TRTCCloudDef.TRTC_AUDIO_ROUTE_SPEAKER);

注意：音频路由仅支持在通话音量模式（VOIP）下手动切换，媒体音量模式（Media）下默认扬声器输出。

十九、弹幕消息互动

语聊直播间通常会有文本形式的弹幕消息互动，这里可以通过 IM 的发送及接收群聊普通文本消息来实现。

// 发送公屏弹幕消息V2TIMManager.getInstance().sendGroupTextMessage(text, groupID, V2TIMMessage.V2TIM_PRIORITY_NORMAL, new V2TIMValueCallback<V2TIMMessage>() { @Override public void onError(int i, String s) { // 发送弹幕消息失败 } @Override public void onSuccess(V2TIMMessage v2TIMMessage) { // 发送弹幕消息成功 }});// 接收公屏弹幕消息V2TIMManager.getInstance().addSimpleMsgListener(new V2TIMSimpleMsgListener() { @Override public void onRecvGroupTextMessage(String msgID, String groupID, V2TIMGroupMemberInfo sender, String text) { Log.i(TAG, sender.getNickName + ": " + text); }});

20、音量大小回调

TRTC 可以按照固定频率回调麦上主播的音量大小，通常用于展示音波音浪，提示正在发言的主播。

// 启用音量大小回调，建议在进房成功后即开启// interval: 回调间隔(ms); enable_vad: 是否开启人声检测mTRTCCloud.enableAudioVolumeEvaluation(int interval, boolean enable_vad);private class TRTCCloudImplListener extends TRTCCloudListener { public void onUserVoiceVolume(ArrayList<TRTCCloudDef.TRTCVolumeInfo> userVolumes, int totalVolume) { super.onUserVoiceVolume(userVolumes, totalVolume); // userVolumes 用于承载所有正在说话的用户的音量大小，包括本地用户和远端推流用户 // totalVolume 用于反馈远端推流用户中的最大音量值 … // 根据音量大小在 UI 上做出相应的音浪展示 … }}

21、音乐及音效播放

播放背景音乐及音效是语聊房场景中的高频需求，下面将对常用的背景音乐相关接口的使用及注意事项进行说明。

1. 开始/停止/暂停/恢复播放。

// 获取用于对背景音乐、短音效和人声特效进行设置的管理类TXAudioEffectManager mTXAudioEffectManager = mTRTCCloud.getAudioEffectManager();TXAudioEffectManager.AudioMusicParam param = new TXAudioEffectManager.AudioMusicParam(musicID, musicPath);// 是否将音乐发布到远端(否则仅本地播放)param.publish = true;// 播放的是否为短音效文件param.isShortFile = false;// 开始播放背景音乐mTXAudioEffectManager.startPlayMusic(param);// 停止播放背景音乐mTXAudioEffectManager.stopPlayMusic(musicID);// 暂停播放背景音乐mTXAudioEffectManager.pausePlayMusic(musicID);// 恢复播放背景音乐mTXAudioEffectManager.resumePlayMusic(musicID);

2. 调节音乐及人声音量占比。

// 设置某一首背景音乐的本地播放音量的大小mTXAudioEffectManager.setMusicPlayoutVolume(musicID, volume);// 设置某一首背景音乐的远端播放音量的大小mTXAudioEffectManager.setMusicPublishVolume(musicID, volume);// 设置所有背景音乐的本地音量和远端音量的大小mTXAudioEffectManager.setAllMusicVolume(volume);// 设置人声采集音量的大小mTXAudioEffectManager.setVoiceCaptureVolume(volume);

3. 设置音乐播放的事件回调。

mTXAudioEffectManager.setMusicObserver(mCurPlayMusicId, new TXAudioEffectManager.TXMusicPlayObserver() { @Override // 背景音乐开始播放 public void onStart(int id, int errCode) { // -4001: 路径打开失败 // -4002: 解码失败 // -4003: URL地址无效 // -4004: 播放未停止 if (errCode < 0) { // 播放失败后重新播放前需要先停止播放当前音乐 mTXAudioEffectManager.stopPlayMusic(id); } } @Override // 背景音乐的播放进度 public void onPlayProgress(int id, long curPtsMs, long durationMs) { // curPtsMS 当前播放时长（毫秒） // durationMs 当前音乐总时长（毫秒） } @Override // 背景音乐已经播放完毕 public void onComplete(int id, int errCode) { // 播放中途因弱网导致的播放失败也会抛出此回调，此时 errCode < 0 // 中途暂停播放或停止播放不会触发 onComplete 回调 }});

4. 循环播放背景音乐及音效。

·方案一：使用 AudioMusicParam 中的 loopCount 参数设置循环播放次数。

取值范围为0 – 任意正整数，默认值：0。0 表示播放音乐一次；1 表示播放音乐两次；以此类推。

private void startPlayMusic(int id, String path, int loopCount) { TXAudioEffectManager.AudioMusicParam param = new TXAudioEffectManager.AudioMusicParam(id, path); // 是否将音乐发布到远端 param.publish = true; // 播放的是否为短音效文件 param.isShortFile = true; // 设定循环播放次数，负数表示无限循环 param.loopCount = loopCount < 0 ? Integer.MAX_VALUE : loopCount; mTRTCCloud.getAudioEffectManager().startPlayMusic(param);}

注意：方案一每次循环播放完毕并不会触发 onComplete 回调，只有等设置的循环次数全部播放完毕才会触发该回调。

·方案二：通过“背景音乐已经播放完毕”的事件回调 onComplete 来实现循环播放，通常用于列表循环或单曲循环。

// 标识是否循环播放的成员变量private boolean loopPlay;private void startPlayMusic(int id, String path) { TXAudioEffectManager.AudioMusicParam param = new TXAudioEffectManager.AudioMusicParam(id, path); mTXAudioEffectManager.setMusicObserver(id, new MusicPlayObserver(id, path)); mTXAudioEffectManager.startPlayMusic(param);}private class MusicPlayObserver implements TXAudioEffectManager.TXMusicPlayObserver { private final int mId; private final String mPath; public MusicPlayObserver(int id, String path) { mId = id; mPath = path; } @Override public void onStart(int i, int i1) { } @Override public void onPlayProgress(int i, long l, long l1) { } @Override public void onComplete(int i, int i1) { mTXAudioEffectManager.stopPlayMusic(i); if (i1 >= 0 && loopPlay) { // 这里可替换循环列表音乐的 ID、Path startPlayMusic(mId, mPath); } }}

22、混流转推及回推

1. 混流转推直播 CDN。

private void startPublishMediaToCDN(String streamName) { // 推流地址的过期时间，默认一天 long txTime = (System.currentTimeMillis() / 1000) + (24 * 60 * 60); // LIVE_URL_KEY 鉴权密钥请在控制台推流地址配置页面获取 String secretParam = UrlHelper.getSafeUrl(LIVE_URL_KEY, streamName, txTime); // 媒体流发布的目标地址 TRTCCloudDef.TRTCPublishTarget target = new TRTCCloudDef.TRTCPublishTarget(); // 混流后发布到 CDN target.mode = TRTCCloudDef.TRTC_PublishMixStream_ToCdn; TRTCCloudDef.TRTCPublishCdnUrl cdnUrl = new TRTCCloudDef.TRTCPublishCdnUrl(); // 推流地址必须带参数，否则推流不成功 cdnUrl.rtmpUrl = "rtmp://" + PUSH_DOMAIN + "/live/" + streamName + "?" + secretParam; // 腾讯云直播推流地址为 true，第三方为 false cdnUrl.isInternalLine = true; // 可以添加多个 CDN 推流地址 target.cdnUrlList.add(cdnUrl); // 设置转码后的音频流的编码参数(可自定义) TRTCCloudDef.TRTCStreamEncoderParam trtcStreamEncoderParam = new TRTCCloudDef.TRTCStreamEncoderParam(); trtcStreamEncoderParam.audioEncodedChannelNum = 1; trtcStreamEncoderParam.audioEncodedKbps = 50; trtcStreamEncoderParam.audioEncodedCodecType = 0; trtcStreamEncoderParam.audioEncodedSampleRate = 48000; // 设置转码后的视频流的编码参数(若需混入黑帧则必填，纯音频混流可忽略) trtcStreamEncoderParam.videoEncodedFPS = 15; trtcStreamEncoderParam.videoEncodedGOP = 3; trtcStreamEncoderParam.videoEncodedKbps = 30; trtcStreamEncoderParam.videoEncodedWidth = 64; trtcStreamEncoderParam.videoEncodedHeight = 64; // 媒体流转码配置参数 TRTCCloudDef.TRTCStreamMixingConfig trtcStreamMixingConfig = new TRTCCloudDef.TRTCStreamMixingConfig(); // 默认情况下填空值即可，代表会混合房间中的所有音频 trtcStreamMixingConfig.audioMixUserList = null; // 若需混入黑帧则必须携带 TRTCVideoLayout 参数(纯音频混流可忽略) TRTCCloudDef.TRTCVideoLayout videoLayout = new TRTCCloudDef.TRTCVideoLayout(); trtcStreamMixingConfig.videoLayoutList.add(videoLayout); // 开始混流转推 mTRTCCloud.startPublishMediaStream(target, trtcStreamEncoderParam, trtcStreamMixingConfig);}

2. 混流回推 TRTC 房间。

private void startPublishMediaToRoom(String roomId, String userId) { // 创建 TRTCPublishTarget 对象 TRTCCloudDef.TRTCPublishTarget target = new TRTCCloudDef.TRTCPublishTarget(); // 混流后回推到房间 target.mode = TRTCCloudDef.TRTC_PublishMixStream_ToRoom; target.mixStreamIdentity.strRoomId = roomId; // 混流机器人的 userid，不能和房间内其他用户的 userid 重复 target.mixStreamIdentity.userId = userId + MIX_ROBOT; // 设置转码后的音频流的编码参数(可自定义) TRTCCloudDef.TRTCStreamEncoderParam trtcStreamEncoderParam = new TRTCCloudDef.TRTCStreamEncoderParam(); trtcStreamEncoderParam.audioEncodedChannelNum = 2; trtcStreamEncoderParam.audioEncodedKbps = 64; trtcStreamEncoderParam.audioEncodedCodecType = 2; trtcStreamEncoderParam.audioEncodedSampleRate = 48000; // 设置转码后的视频流的编码参数(纯音频混流可忽略) trtcStreamEncoderParam.videoEncodedFPS = 15; trtcStreamEncoderParam.videoEncodedGOP = 3; trtcStreamEncoderParam.videoEncodedKbps = 30; trtcStreamEncoderParam.videoEncodedWidth = 64; trtcStreamEncoderParam.videoEncodedHeight = 64; // 设置音频混流参数 TRTCCloudDef.TRTCStreamMixingConfig trtcStreamMixingConfig = new TRTCCloudDef.TRTCStreamMixingConfig(); // 默认情况下填空值即可，代表会混合房间中的所有音频 trtcStreamMixingConfig.audioMixUserList = null; // 配置视频混流模板(纯音频混流可忽略) TRTCCloudDef.TRTCVideoLayout videoLayout = new TRTCCloudDef.TRTCVideoLayout(); trtcStreamMixingConfig.videoLayoutList.add(videoLayout); // 开始混流回推 mTRTCCloud.startPublishMediaStream(target, trtcStreamEncoderParam, trtcStreamMixingConfig);}

3. 事件回调及更新停止任务。

·任务结果事件回调。

private class TRTCCloudImplListener extends TRTCCloudListener { @Override public void onStartPublishMediaStream(String taskId, int code, String message, Bundle extraInfo) { // taskId: 当请求成功时，TRTC 后台会在回调中提供给你这项任务的 taskId，后续你可以通过该 taskId 结合 updatePublishMediaStream 和 stopPublishMediaStream 进行更新和停止 // code: 回调结果，0 表示成功，其余值表示失败 } @Override public void onUpdatePublishMediaStream(String taskId, int code, String message, Bundle extraInfo) { // 你调用媒体流发布接口 (updatePublishMediaStream) 时传入的 taskId，会通过此回调再带回给你，用于标识该回调属于哪一次更新请求 // code: 回调结果，0 表示成功，其余值表示失败 } @Override public void onStopPublishMediaStream(String taskId, int code, String message, Bundle extraInfo) { // 你调用停止发布媒体流 (stopPublishMediaStream) 时传入的 taskId，会通过此回调再带回给你，用于标识该回调属于哪一次停止请求 // code: 回调结果，0 表示成功，其余值表示失败 }}

·更新发布媒体流。

该接口会向 TRTC 服务器发送指令，更新通过 startPublishMediaStream 启动的媒体流。

// taskId: 通过 onStartPublishMediaStream 回调的任务 ID// target: 例如增删发布的 CDN URL// params: 建议保持媒体流编码输出参数一致，避免播放侧断流// config: 更新参与混流转码的用户列表，例如跨房 PKmTRTCCloud.updatePublishMediaStream(taskId, target, trtcStreamEncoderParam, trtcStreamMixingConfig);

注意：同一个任务不支持纯音频、音视频、纯视频之间的切换。

·停止发布媒体流。

该接口会向 TRTC 服务器发送指令，停止通过 startPublishMediaStream 启动的媒体流。

// taskId: 通过 onStartPublishMediaStream 回调的任务 IDmTRTCCloud.stopPublishMediaStream(taskId);

注意：若 taskId 填空字符串，将会停止该用户所有通过 startPublishMediaStream 启动的媒体流，如果你只启动了一个媒体流或者想停止所有通过你启动的媒体流，推荐使用这种方式。

23、网络质量实时回调

可以通过监听 onNetworkQuality 来实时统计本地及远端用户的网络质量，该回调每隔2秒抛出一次。

private class TRTCCloudImplListener extends TRTCCloudListener { @Override public void onNetworkQuality(TRTCCloudDef.TRTCQuality localQuality, ArrayList<TRTCCloudDef.TRTCQuality> remoteQuality) { // localQuality userId 为空，代表本地用户网络质量评估结果 // remoteQuality 代表远端用户网络质量评估结果，其结果受远端和本地共同影响 switch (localQuality.quality) { case TRTCCloudDef.TRTC_QUALITY_Excellent: Log.i(TAG, "当前网络非常好"); break; case TRTCCloudDef.TRTC_QUALITY_Good: Log.i(TAG, "当前网络比较好"); break; case TRTCCloudDef.TRTC_QUALITY_Poor: Log.i(TAG, "当前网络一般"); break; case TRTCCloudDef.TRTC_QUALITY_Bad: Log.i(TAG, "当前网络较差"); break; case TRTCCloudDef.TRTC_QUALITY_Vbad: Log.i(TAG, "当前网络很差"); break; case TRTCCloudDef.TRTC_QUALITY_Down: Log.i(TAG, "当前网络不满足 TRTC 最低要求"); break; default: Log.i(TAG, "未定义"); break; } }}

24、高级权限控制

TRTC 高级权限控制可用于对不同房间设置不同进入权限，例如高级 VIP 房；也可用于控制听众上麦权限，例如处理幽灵麦。

步骤1：在 TRTC 控制台 应用的功能配置页面打开高级权限控制开关。

步骤2：在业务后台生成 PrivateMapKey，代码示例参考 PrivateMapKey 计算源码。

步骤3：进房校验&上麦校验 PrivateMapKey。

·进房校验。

TRTCCloudDef.TRTCParams mTRTCParams = new TRTCCloudDef.TRTCParams();mTRTCParams.sdkAppId = SDKAPPID;mTRTCParams.userId = mUserId;mTRTCParams.strRoomId = mRoomId;// 从业务后台获取到的 UserSigmTRTCParams.userSig = getUserSig();// 从业务后台获取到的 PrivateMapKeymTRTCParams.privateMapKey = getPrivateMapKey();mTRTCParams.role = TRTCCloudDef.TRTCRoleAudience;mTRTCCloud.enterRoom(mTRTCParams, TRTCCloudDef.TRTC_APP_SCENE_VOICE_CHATROOM);

·上麦校验。

// 从业务后台获取到最新的 PrivateMapKey 传入切换角色接口mTRTCCloud.switchRole(TRTCCloudDef.TRTCRoleAnchor, getPrivateMapKey());

26、异常错误处理

TRTC SDK 遇到不可恢复的错误会在 onError 回调中抛出，详见 TRTC 错误码表。

·UserSig 相关。UserSig 校验失败会导致进房失败，你可参考 UserSig 生成与校验 进行校验。

·进退房相关。进房失败请先检查进房参数是否正确，且进退房接口必须成对调用，即便进房失败也需要调用退房接口。

·设备相关。可监听设备相关错误，在出现相关错误时 UI 提示用户。

27、异常退出处理

1. 断网感知与超时退房。

可以通过以下回调监听 TRTC 断网和重连事件通知。

收到 onConnectionLost 回调后可在本地麦位 UI 展示断网标识提醒用户，同时本地启动一个计时器，当超过设定时间阈值后仍然没有收到 onConnectionRecovery 回调，即网络持续处于断连状态，此时可本地启动下麦和退房流程，同时弹窗提醒用户已退出房间并销毁页面。若断网超过90秒（默认）会触发超时退房，TRTC 服务端会将该用户踢出房间，如果该用户为主播角色，则房间内其他用户会收到 onRemoteUserLeaveRoom 回调。

private class TRTCCloudImplListener extends TRTCCloudListener { @Override public void onConnectionLost() { // SDK 与云端的连接已经断开 } @Override public void onTryToReconnect() { // SDK 正在尝试重新连接到云端 } @Override public void onConnectionRecovery() { // SDK 与云端的连接已经恢复 }}

2. 离线状态下自动下麦。

IM 用户的普通状态分为在线（ONLINE）、离线（OFFLINE）、未登录（UNLOGINED），其中离线状态通常是由于用户强杀进程或网络异常中断导致的。你可以通过主播订阅连麦听众用户状态来检测离线连麦听众，从而将其踢下麦。

// 主播订阅连麦听众用户状态V2TIMManager.getInstance().subscribeUserStatus(userList, new V2TIMCallback() { @Override public void onSuccess() { // 订阅用户状态成功 } @Override public void onError(int code, String message) { // 订阅用户状态失败 }});// 主播取消订阅下麦听众用户状态V2TIMManager.getInstance().unsubscribeUserStatus(userList, new V2TIMCallback() { @Override public void onSuccess() { // 取消订阅用户状态成功 } @Override public void onError(int code, String message) { // 取消订阅用户状态失败 }});// 用户状态变更通知与处理V2TIMManager.getInstance().addIMSDKListener(new V2TIMSDKListener() { @Override public void onUserStatusChanged(List<V2TIMUserStatus> userStatusList) { for (V2TIMUserStatus userStatus : userStatusList) { final String userId = userStatus.getUserID(); int status = userStatus.getStatusType(); if (status == V2TIMUserStatus.V2TIM_USER_STATUS_OFFLINE) { // 离线状态执行踢麦 kickSeat(getSeatIndexFromUserId(userId)); } } }});

28、服务端踢人及解散房间

1. 服务端踢人。

首先调用 TRTC 服务端踢人接口 RemoveUser（整型房间号）或 RemoveUserByStrRoomId（字符串房间号）将目标用户踢出 TRTC 房间，输入示例如下：

https://trtc.tencentcloudapi.com/?Action=RemoveUser&SdkAppId=1400000001&RoomId=1234&UserIds.0=test1&UserIds.1=test2&<公共请求参数>

执行踢人成功后，目标用户在客户端会收到 onExitRoom() 回调，且 reason 值为1。此时你可以在该回调中处理下麦、退出 IM 群组等操作。

// 离开 TRTC 房间事件回调@Overridepublic void onExitRoom(int reason) { if (reason == 0) { Log.d(TAG, "主动调用 exitRoom 退出房间"); } else { // reason 1: 被服务器踢出当前房间 // reason 2: 当前房间被整个解散 Log.d(TAG, "被服务器踢出房间，或当前房间被解散"); // 下麦 leaveSeat(seatIndex); // 退出 IM 群组 quitGroup(groupID, new V2TIMCallback() {}); }}

2. 服务端解散房间。

首先调用 IM 服务端解散群组接口 destroy_group 解散目标群组，请求 URL 示例如下：

https://xxxxxx/v4/group_open_http_svc/destroy_group?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

执行解散群组成功后，目标群组内的全部成员在客户端均会收到 onGroupDismissed() 回调。此时你可以在该回调中处理退出 TRTC 房间等操作。

// 群组被解散回调V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() { @Override public void onGroupDismissed(String groupID, V2TIMGroupMemberInfo opUser) { // 退出 TRTC 房间 mTRTCCloud.stopLocalAudio(); mTRTCCloud.exitRoom(); }});

注意：说明：

注意：当房间内所有用户调用 exitRoom() 完成退房后，TRTC 房间会自动解散。当然，你也可以调用服务端接口 DismissRoom（整型房间号）或 DismissRoomByStrRoomId（字符串房间号）强制解散 TRTC 房间。

29、进房查看直播间历史消息

使用 AVChatRoom 默认不存储直播间历史消息，当新用户进入直播间后，只能看到进入直播间后用户发送的消息。为了优化新进群用户的体验，可在 即时通信 IM 控制台 配置直播群新成员查看入群前消息量：

开启后会在加入直播群成功后，在 onRecvNewMessage 回调中获得入群前消息。

V2TIMManager.getMessageManager().addAdvancedMsgListener(new V2TIMAdvancedMsgListener() {
@Override
public void onRecvNewMessage(V2TIMMessage msg) {
super.onRecvNewMessage(msg);
if (msg.getElemType() == V2TIM_ELEM_TYPE_TEXT) {
String sender = msg.getSender();
String msgText = msg.getTextElem().getText();
Log.i("imsdk", "onRecvNewMessage, sender:" + sender + ", msg:" + msgText);
}
}
});

注意：此功能仅旗舰版用户才可开通，且仅支持新入群成员查看入群前 24h 产生的消息，最多可查看 20 条。

30、进房感知麦上主播禁音状态

方案一：进房时默认所有主播为禁音状态，然后根据 onUserAudioAvailable(userId, true) 回调解除对应主播禁音状态。

private class TRTCCloudImplListener extends TRTCCloudListener { @Override public void onUserAudioAvailable(String userId, boolean available) { if (available) { // 解除对应主播的禁音状态 } }}

方案二：把主播的禁音状态存储在 IM 群属性中，听众进房获取全量群属性，解析麦上主播禁音状态。

V2TIMManager.getGroupManager().getGroupAttributes(groupID, null, new V2TIMValueCallback<Map<String, String>>() { @Override public void onError(int i, String s) { // 获取群属性失败 } @Override public void onSuccess(Map<String, String> attrMap) { // 获取群属性成功，假设存储主播禁音状态的 key 为 muteStatus String muteStatus = attrMap.get("muteStatus"); // 解析 muteStatus，获取每个麦上主播的禁音状态 }});

31、蓝牙耳机的音频输入输出问题

手机已经成功连接蓝牙耳机，但 TRTC 应用的音频输入或输出仍然使用手机麦克风或扬声器。

1. 如果音频输出正常使用蓝牙耳机，只有音频输入仍旧使用手机麦克风，此时请检查音量类型的设置。只有通话音量模式下支持通过蓝牙耳机上的麦克风进行拾音，详情请参见 音频管理 – 音质及音量类型。

mTRTCCloud.setSystemVolumeType(TRTCCloudDef.TRTCSystemVolumeTypeVOIP);

2. 如果音频的输入及输出均无法使用蓝牙耳机，此时请检查 App 权限中是否配置了蓝牙权限。对于 Android 设备，Android 12 以下系统需至少配置 BLUETOOTH 权限，Android 12 及以上系统需至少配置 BLUETOOTH_CONNECT 权限且需在代码中动态申请权限。

在 AndroidManifest.xml 中配置蓝牙权限，为了兼容 Android 12 以下系统，建议声明方式如下：

<!–普通权限：基础蓝牙连接权限–><uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30"/><!–普通权限：蓝牙管理、扫描权限–><uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" /><!–运行时权限：Android 12 蓝牙权限 查找蓝牙设备–><uses-permission android:name="android.permission.BLUETOOTH_SCAN" /><!–运行时权限：Android 12 蓝牙权限 使当前设备可被其他蓝牙设备检测到–><uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" /><!–运行时权限：Android 12 蓝牙权限 与已配对的蓝牙设备通信或者获取当前手机蓝牙是否打开–><uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

对于 Android 12 及以上系统新增的蓝牙细分权限，动态申请方法如下：

private List<String> permissionList = new ArrayList<>();protected void initPermission() { // 判断 Android SDK 版本，大于等于 Android 12 if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { // 根据需求添加需要动态申请的权限 permissionList.add(Manifest.permission.BLUETOOTH_SCAN); permissionList.add(Manifest.permission.BLUETOOTH_ADVERTISE); permissionList.add(Manifest.permission.BLUETOOTH_CONNECT); } if (permissionList.size() != 0) { // 动态申请权限 ActivityCompat.requestPermissions(this, permissionList.toArray(new String[0]), REQ_PERMISSION_CODE); }}

32、音乐播放支持的资源路径问题

使用 TRTC SDK API startPlayMusic 播放背景音乐，其中音乐资源路径参数 path 不支持传入 Android 开发中的 assets/raw 等用来存储应用资源文件目录下的文件路径，因为这些目录下的文件会被打包到 APK 中，安装之后不会被解压到手机的文件系统中。目前只支持传入网络资源 URL、安卓设备外部存储及应用私有目录下资源文件的绝对路径。

你可以通过将 assets 目录下的资源文件提前拷贝到设备外部存储或应用私有目录下的方法规避这一问题，示例代码如下：

public static void copyAssetsToFile(Context context, String name) { // 应用程序自身目录下的 files 目录 String savePath = ContextCompat.getExternalFilesDirs(context, null)[0].getAbsolutePath(); // 应用程序自身目录下的 cache 目录 // String savePath = getApplication().getExternalCacheDir().getAbsolutePath(); // 应用程序私有存储目录下的 files 目录 // String savePath = getApplication().getFilesDir().getAbsolutePath(); String filename = savePath + "/" + name; File dir = new File(savePath); // 如果目录不存在，创建这个目录 if (!dir.exists()) { dir.mkdir(); } try { if (!(new File(filename)).exists()) { InputStream is = context.getResources().getAssets().open(name); FileOutputStream fos = new FileOutputStream(filename); byte[] buffer = new byte[1024]; int count = 0; while ((count = is.read(buffer)) > 0) { fos.write(buffer, 0, count); } fos.close(); is.close(); } } catch (Exception e) { e.printStackTrace(); }}

·应用私有存储 files 目录路径：/data/user/0/<package_name>/files/<file_name>

·应用外部存储 files 目录路径：/storage/emulated/0/Android/data/<package_name>/files/<file_name>

·应用外部存储 cache 目录路径：/storage/emulated/0/Android/data/<package_name>/cache/file_name>

注意：<manifest …> <!– This is the permission itself –> <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" /> <application …> … </application></manifest>

注意：if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) { if (!Environment.isExternalStorageManager()) { Intent intent = new Intent(Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION); Uri uri = Uri.fromParts("package", getPackageName(), null); intent.setData(uri); startActivity(intent); }} else { // For Android versions less than Android 11, you can use the old permissions model ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.WRITE_EXTERNAL_STORAGE}, REQUEST_CODE);}

33、主播闭麦状态下播放音乐，远端用户听不到

通常情况下，本地闭麦操作需要调用 muteLocalAudio 方法，但在播放背景音乐时调用此方法会暂停将音乐发布至远端，即远端用户听不到背景音乐了。如果希望在闭麦的同时能够正常播放和发布背景音乐，可以参考下述方案实现。

// 1. 获取当前的人声采集音量
int volume = mTRTCCloud.getAudioCaptureVolume();
// 2. 将人声采集音量设为0，达到闭麦效果
mTRTCCloud.setAudioCaptureVolume(0);
// 3. 解除闭麦时，恢复至原先的人声采集音量
mTRTCCloud.setAudioCaptureVolume(volume);