客户端实现（Android）

本文介绍如何在你的 Android app 里实现元语聊的重要功能。

技术原理

元语聊场景提供语聊者和游客两种默认角色，角色权限说明如下：

实现元语聊的总体流程如下：

1. 设置角色为语聊者或游客。
2. 初始化并进入 3D 场景。
3. 发布和订阅音频流。
4. 语聊者之间进行互动。

前提条件

开始前，请确保你的开发环境满足以下条件：

• Android Studio 4.1 以上版本。
• Android API 级别 22 或以上。
• 运行 Android 5.1 或以上版本的真机。部分模拟机可能无法支持本项目的全部功能。
• 可以访问互联网的计算机。请确保你的网络环境没有部署防火墙，否则无法正常使用声网服务。
• 有效的声网账户和声网项目，请参考开始使用声网平台，从声网控制台获取以下信息：
  • App ID：声网随机生成的字符串，用于识别你的声网项目。
  • RTC 临时 Token：Token 也称为动态密钥，用于客户端在加入频道时对用户鉴权。RTC 临时 Token 的有效期为 24 小时，仅用于测试。
  • RTM Token：用于客户端在登录 RTM 系统时对用户鉴权。该 Token 由声网服务器签发，有效期为 24 小时，仅用于测试。

项目配置

开通元语聊

参考以下步骤开通元语聊服务：

1. 获取 App ID。详情请参考开始使用声网平台。
2. 联系销售并提供你的 App ID，用于开通声网内容中心的权限。

集成 SDK

搭建元语聊场景需要使用声网 RTC 4.0.1 元语聊特殊版 SDK。该版本是官网声网 RTC SDK 4.0.1 的分支版本，主要新增了一些为元语聊场景定制的功能。

参考以下步骤集成声网 RTC 4.0.1 元语聊特殊版 SDK：

1. 联系销售获取声网 RTC 4.0.1 元语聊特殊版 SDK，并解压。

2. 打开解压文件，将以下文件或子文件夹复制到你的项目路径中。

   文件或子文件夹	项目路径
   agora-rtc-sdk.jar 文件	/app/libs/
   AgoraUnityEngineRelease.aar 文件	/app/libs/
   arm64-v8a 文件夹	/app/src/main/jniLibs/
   armeabi-v7a 文件夹	/app/src/main/jniLibs/
   x86 文件夹	/app/src/main/jniLibs/
   x86_64 文件夹	/app/src/main/jniLibs/

3. 在 Android Studio 的导航栏上选择 Project Files/app/libs/agora-rtc-sdk.jar 文件，右键单击，选择 add as a library。

实现流程

本节介绍在集成声网 RTC 4.0.1 元语聊特殊版 SDK 后，如何实现元语聊核心业务模块的功能。

实现流程中需要用到声网 SDK 的以下类：

• RtcEngine 类：提供实时音视频功能。
• IMetachatService、IMetachatScene 和 ILocalUserAvatar 类：提供元语聊的核心功能相关方法。
• IMetachatEventhandler 和 IMetachatSceneEventhandler 类：提供元语聊的核心功能相关回调。

初始化

创建 3D 场景之前，你需要进行初始化、下载场景资源。

你可以参考以下示例代码：

//创建并初始化 RtcEngine
RtcEngine rtcEngine = RtcEngine.create(context, KeyCenter.APP_ID, new IRtcEngineEventHandler());
rtcEngine.enableAudio();
rtcEngine.disableVideo();
rtcEngine.setChannelProfile(Constants.CHANNEL_PROFILE_LIVE_BROADCASTING);
rtcEngine.setAudioProfile(Constants.AUDIO_PROFILE_DEFAULT, Constants.AUDIO_SCENARIO_GAME_STREAMING);
//创建并初始化 IMetachatService
IMetachatService metaChatService = IMetachatService.create();
MetachatConfig config = new MetachatConfig() {
    {
        mRtcEngine = rtcEngine;
        mAppId = KeyCenter.APP_ID;
        mRtmToken = KeyCenter.RTM_TOKEN;
        mLocalDownloadPath = context.getExternalCacheDir().getPath();
        mUserId = KeyCenter.RTM_UID;
        mEventHandler = MetaChatContext.this;
    }
};
int ret = metaChatService.initialize(config);

//获取场景资源列表
metaChatService.getSceneInfos();
public void onGetSceneInfosResult(MetachatSceneInfo[] scenes, int errorCode) {
    //保存获取到的场景资源列表
};
//判断资源是否需要下载（本地没有资源或者资源有更新则需要下载）
metaChatService.isSceneDownloaded(sceneInfo.mSceneId);
//下载资源
metaChatService.downloadScene(sceneInfo.mSceneId);
public void onDownloadSceneProgress(long mSceneId, int progress, int state) {
    //根据 state 和 progress 判断是否可以加载场景
}

创建 3D 场景

搭建元语聊首先需要创建 3D 场景。

你可以参考以下示例代码：

MetachatSceneConfig sceneConfig = new MetachatSceneConfig();
//mActivityContext 为显示场景的 Activity 对象（非 context 对象）
sceneConfig.mActivityContext = activityContext;
int ret = = metaChatService.createScene(sceneConfig);

public void onCreateSceneResult(IMetachatScene scene, int errorCode) {
    metaChatScene = scene;
    ILocalUserAvatar localUserAvatar = metaChatScene.getLocalUserAvatar();
}

进入 3D 场景

进入 3D 场景之前，你可以先设置好用户的基本信息、模型信息、装扮信息、捏脸信息等。

你可以参考以下示例代码：

if(null != localUserAvatar) {
    localUserAvatar.setUserInfo(userInfo);
    //该模型的 mBundleType 为 MetachatBundleInfo.BundleType.BUNDLE_TYPE_AVATAR 类型
    localUserAvatar.setModelInfo(modelInfo);
    if(null != roleInfo) {
        //设置服装信息，具体协议格式依据项目而定
        DressInfo dressInfo = new DressInfo();
        dressInfo.mExtraCustomInfo = (JSONObject.toJSONString(getUnityRoleInfo())).getBytes();
        localUserAvatar.setDressInfo(dressInfo);
    }
}
if(null != metaChatScene) {
    //开启位置信息回调
    metaChatScene.enableUserPositionNotification(true);
    //设置回调接口
    metaChatScene.addEventHandler(MetaChatContext.getInstance());
    EnterSceneConfig config = new EnterSceneConfig();
    //sceneView 必须为 Texture 类型，以渲染 Unity 的显示视图
    config.mSceneView = this.sceneView;
    config.mRoomName = this.roomName;
    config.mSceneId = this.sceneInfo.mSceneId;
    /*
     * 仅为示例格式，具体格式以项目实际为准
     * "extraCustomInfo":
     *     {
     *          "sceneIndex":0  //0 为默认场景，在这里指咖啡厅，1 为换装设置场景
     *     }
     */
    EnterSceneExtraInfo extraInfo = new EnterSceneExtraInfo();
    extraInfo.setSceneIndex(1);
    //加载的场景 index
    config.mExtraCustomInfo = JSONObject.toJSONString(extraInfo).getBytes();
    metaChatScene.enterScene(config);
}

public void onEnterSceneResult(int errorCode) {
    //根据回调的 errorCode 判断实现相应逻辑
}

更新用户角色

游客可以上麦成为语聊者，从而发布音频流、向所有人展示自己的虚拟形象。

你可以参考以下示例代码：

boolean isBroadcaster = role == Constants.CLIENT_ROLE_BROADCASTER;
int ret = rtcEngine.updateChannelMediaOptions(new ChannelMediaOptions() {
    {
        publishMicrophoneTrack = isBroadcaster;
        clientRoleType = role;
    }
});
modelInfo.mLocalVisible = true;
modelInfo.mRemoteVisible = isBroadcaster;
modelInfo.mSyncPosition = isBroadcaster;
if(Constants.ERR_OK == localUserAvatar.setModelInfo(modelInfo)) {
    ret += localUserAvatar.applyInfo();
}

自定义拓展功能

虚拟人换装

在 3D 场景中，游客和语聊者都可以对自己的虚拟形象实时换装。详见换装和捏脸。

空间音效

为用户的音频流和背景音乐添加空间音效，目前仅支持本地直角坐标系计算方案，实现方法详见空间音效。

实时共赏影音

为 3D 场景添加视频播放功能，可以实现一起看视频、一起 KTV 等玩法。目前仅支持播放本地视频文件，实现方法详见实时共赏影音。

退出 3D 场景

切换场景时，必须先退出当前的 3D 场景，然后创建新的 3D 场景。

示例代码如下：

rtcEngine.leaveChannel();
metaChatScene.leaveScene();
//在收到 onLeaveSceneResult 回调后执行以下步骤
public void onLeaveSceneResult(int errorCode) {
    metaChatScene.release();
};
//在收到 onReleasedScene 回调后执行以下步骤
public void onReleasedScene(int status) {
    IMetachatService.destroy();
    metaChatService = null;
    RtcEngine.destroy();
    rtcEngine = null;
}

参考信息

示例项目

联系声网销售获取元语聊场景的示例项目，查看其中的源代码。

API 参考

所有 API 的参数描述详见元语聊 API 参考。

开发注意事项

• 使用 3D 场景的过程中，不能销毁 Activity。如果场景所在的 Activity 需要置于后台，可以添加 Intent 的 Flags 为 Intent.FLAG_ACTIVITY_REORDER_TO_FRONT。
• 使用 3D 场景的过程中，不能销毁 Texture。如果 Texture 尺寸大小发生变化，例如切换场景时需要切换显示横竖屏，你需要在setSurfaceTextureListener 的回调方法 onSurfaceTextureSizeChanged 中再次调用 createScene 和 enterScene 等方法，从创建和进入场景重新开始。