文档中心





元语聊

Console 官网社区技术支持





客户端实现（iOS）

更新时间 2023/04/21 07:16:57

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

技术原理

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

	语聊者	游客
发布音频流	✔	✘
订阅远端用户的音频流	✔	✔
本地渲染虚拟形象	✔	✔
同步虚拟形象给远端用户	✔	✘
互动（占座）	✔	✘

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

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

前提条件

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

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

项目配置

开通元语聊

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

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

集成 SDK

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

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

联系销售获取声网 RTC 4.0.1 元语聊特殊版 SDK，并解压。
打开解压文件，将 libs 路径下的所有文件拷贝到你的项目路径下。
打开 Xcode，添加对应动态库，确保添加的动态库 Embed 属性设置为 Embed & Sign。
- 根据 Apple 官方要求，app 的 Extension 中不允许包含动态库。如果项目中的 Extension 需要集成 SDK，则添加动态库时需将文件状态改为 Do Not Embed。
- 声网 SDK 默认使用 libc++ (LLVM)，如需使用 libstdc++ (GNU)，请联系 sales@agora.io。SDK 提供的库是 FAT Image，包含 32/64 位模拟器、32/64 位真机版本。

实现流程

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

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

AgoraRtcEngineKit 类：提供实时音视频功能。
AgoraMetachatKit、AgoraMetachatScene 和 AgoraLocalUserAvatar 类：提供元语聊的核心功能相关方法。
AgoraMetachatEventDelegate 和 AgoraMetachatSceneEventDelegate 类：提供元语聊的核心功能相关回调。

初始化

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

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

初始化

// Objective-c
// 创建并初始化 AgoraRtcEngineKit
AgoraRtcEngineConfig *rtcEngineConfig = [[AgoraRtcEngineConfig alloc] init];
rtcEngineConfig.appId = @"";
rtcEngineConfig.areaCode = AgoraAreaCodeTypeGlobal;
AgoraRtcEngineKit *rtcEngine = [AgoraRtcEngineKit sharedEngineWithConfig:_rtcEngineConfig
                                                                delegate:self];
[rtcEngine enableAudio];
[rtcEngine enableVideo];
[rtcEngine setChannelProfile:AgoraChannelProfileLiveBroadcasting];
[rtcEngine setClientRole:AgoraClientRoleBroadcaster];

// 创建并初始化 AgoraMetachatKit
NSString *cachesPath = NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, YES).firstObject;
metachatConfig.localDownloadPath = cachesPath;
metachatConfig.rtcEngine = rtcEngine;
AgoraMetachatKit *metachatKit = [AgoraMetachatKit sharedMetachatWithConfig:metachatConfig];

// Swift
// 创建并初始化 AgoraRtcEngineKit
let rtcEngineConfig = AgoraRtcEngineConfig()
rtcEngineConfig.appId = ""
rtcEngineConfig.areaCode = .global
rtcEngine = AgoraRtcEngineKit.sharedEngine(with: rtcEngineConfig, delegate: self)
rtcEngine?.setChannelProfile(.liveBroadcasting)
rtcEngine?.setClientRole(.broadcaster)

// 创建并初始化 AgoraMetachatKit
let metachatConfig = AgoraMetachatConfig()
metachatConfig.appId = ""
metachatConfig.rtmToken = ""
metachatConfig.userId = ""
metachatConfig.delegate = self
let paths = NSSearchPathForDirectoriesInDomains(.cachesDirectory, .userDomainMask, true)
metachatConfig.localDownloadPath = paths.first!
metachatConfig.rtcEngine = rtcEngine
let metachatKit = AgoraMetachatKit.sharedMetachatWithConfig(_: metachatConfig)

下载场景资源

// Objective-c
// 获取场景资源列表
[metachatKit getSceneInfos];
// 获取场景资源列表回调
- (void)onGetSceneInfosResult:(NSMutableArray* _Nonnull)sceneInfos errorCode:(NSInteger)errorCode;
// 判断资源是否需要下载（本地没有资源或者资源有更新则需要下载）
[metachatKit isSceneDownloaded:sceneId];
// 下载资源
[metachatKit downloadScene:sceneId];
// 资源下载进度回调
- (void)onDownloadSceneProgress:(NSInteger)sceneId
                       progress:(NSInteger)progress
                          state:(AgoraMetachatDownloadStateType)state;
// 取消下载
[metachatKit cancelDownloadScene:sceneId];

// Swift
// 获取场景资源列表
metachatKit?.getSceneInfos()
// 获取场景资源列表回调
func onGetSceneInfosResult(_ scenes: NSMutableArray, errorCode: Int)
// 判断资源是否需要下载（本地没有资源或者资源有更新则需要下载）
metachatKit?.isSceneDownloaded(sceneId)
// 下载资源
metachatKit?.downloadScene(sceneId)
// 资源下载进度回调
func onDownloadSceneProgress(_ sceneId: Int, progress: Int, state: AgoraMetachatDownloadStateType)
// 取消下载
metachatKit?.cancelDownloadScene(sceneId)

创建 3D 场景

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

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

// Objective-c
// 创建场景
AgoraMetachatSceneConfig *config = [[AgoraMetachatSceneConfig alloc] init];
config.delegate = self;
[metachatKit createScene:config];
// createScene 结果回调，metaChatScene 对象的值为回调获取
- (void)onCreateSceneResult:(AgoraMetachatScene *_Nullable)scene
                  errorCode:(NSInteger)errorCode;

// Swift
// 创建场景
let config = AgoraMetachatSceneConfig()
config.delegate = self
metachatKit?.createScene(config)
// createScene 结果回调，metaChatScene 对象的值为回调获取
func onCreateSceneResult(_ scene: AgoraMetachatScene?, errorCode: Int)

进入 3D 场景

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

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

进入场景

// Objective-c
// 创建场景渲染所需的视图
UIView<AgoraMetaViewProtocol> *renderView = [metachatScene createRenderView:AgoraMetachatVenderTypeUnity
                                                                     region:CGRectMake(0, 0, SCREEN_WIDTH, SCREEN_HEIGHT)];
renderView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
// user 信息
AgoraMetachatUserInfo *userInfo = [[AgoraMetachatUserInfo alloc] init];
userInfo.userId = @"";
userInfo.userName = @"";
userInfo.userIconUrl = @"";
// avatar 信息
AgoraMetachatAvatarModelInfo *avatarInfo = [[AgoraMetachatAvatarModelInfo alloc] init];
for (AgoraMetachatBundleInfo *info in sceneInfo.bundles) {
        if (info.bundleType == AgoraMetachatBundleTypeAvatar) {
                avatarInfo.bundleCode = info.bundleCode;
                break;           
    }
}
avatarInfo.localVisible = true;
avatarInfo.remoteVisible = true;
avatarInfo.syncPosition = true;
// 换装信息
AgoraMetachatDressInfo *dressInfo = [[AgoraMetachatDressInfo alloc] init];
dressInfo.extraCustomInfo = [dressStr dataUsingEncoding:NSUTF8StringEncoding];
// 设置 userInfo(用户信息)、modelInfo(模型信息)、dressInfo(换装信息)
AgoraMetachatLocalUserAvatar *localUserAvatar = [metachatScene getLocalUserAvatar];
[localUserAvatar setUserInfo:userInfo];
[localUserAvatar setModelInfo:avatarInfo];
[localUserAvatar setDressInfo:dressInfo];
// 进入场景所需信息
AgoraMetachatEnterSceneConfig *enterSceneConfig = [[AgoraMetachatEnterSceneConfig alloc] init];
enterSceneConfig.roomName = @"";
enterSceneConfig.sceneView = renderView;
enterSceneConfig.sceneId = sceneInfo.sceneId;
enterSceneConfig.extraCustomInfo = [extraInfo dataUsingEncoding:NSUTF8StringEncoding];
// 进入场景
[metachatScene enterScene:enterSceneConfig];
// enterScene结果回调
- (void)metachatScene:(AgoraMetachatScene *_Nonnull)scene onEnterSceneResult:(NSInteger)errorCode;

// Swift
// 创建场景渲染所需的视图
let renderView = metachatScene?.createRenderView(
  AgoraMetachatVenderType.unity,
  region: CGRect(x: 0, y: 0, width: SCREEN_WIDTH, height: SCREEN_HEIGHT))
renderView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
// user 信息
let userInfo = AgoraMetachatUserInfo.init()
userInfo?.userId = ""
userInfo?.userName = ""
userInfo?.userIconUrl = ""
// avatar 信息
let avatarInfo = AgoraMetachatAvatarModelInfo.init()
for info in sceneInfo.bundles {
      if info.bundleType == .avatar {
            avatarInfo.bundleCode = info.bundleCode
            break
  }
}
avatarInfo.localVisible = true
avatarInfo.remoteVisible = true
avatarInfo.syncPosition = true
// 换装信息
let dressInfo = AgoraMetachatDressInfo()
dressInfo.extraCustomInfo = dressStr!.data(using: String.Encoding.utf8)
// 设置 userInfo(用户信息)、modelInfo (模型信息)、dressInfo (换装信息)
localUserAvatar = metachatScene?.getLocalUserAvatar()
localUserAvatar?.setUserInfo(userInfo)
localUserAvatar?.setModelInfo(avatarInfo)
localUserAvatar?.setDressInfo(dressInfo)
// 设置进入场景所需要的配置信息
let enterSceneConfig = AgoraMetachatEnterSceneConfig()
enterSceneConfig.roomName = ""
enterSceneConfig.sceneView = renderView
enterSceneConfig.sceneId = sceneInfo.sceneId
enterSceneConfig.extraCustomInfo = extraInfo!.data(using: String.Encoding.utf8)
// 进入场景
metachatScene?.enter(enterSceneConfig)
// enterScene 结果回调
func metachatScene(_ scene: AgoraMetachatScene, onEnterSceneResult errorCode: Int)

更新用户角色

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

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

// Objective-c
// 是否为语聊者
BOOL isBroadcaster = (role == AgoraClientRole.broadcaster);
// 设置 avatar 信息
avatarInfo.localVisible = true;
avatarInfo.remoteVisible = isBroadcaster;
avatarInfo.syncPosition = isBroadcaster;
localUserAvatar = [metachatScene getLocalUserAvatar];
[localUserAvatar setModelInfo: avatarInfo];
[localUserAvatar applyInfo];

// Swift
// 是否为语聊者
var isBroadcaster = (role == AgoraClientRole.broadcaster)
// 设置 avatar 信息
avatarInfo.localVisible = true
avatarInfo.remoteVisible = isBroadcaster
avatarInfo.syncPosition = isBroadcaster
localUserAvatar = metachatScene?.getLocalUserAvatar()
localUserAvatar?.setModelInfo(avatarInfo)
localUserAvatar?.applyInfo()

自定义拓展功能

虚拟人换装

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

空间音效

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

实时共赏影音

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

退出 3D 场景

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

退出场景

// Objective-c
// 退出场景
[rtcEngine leaveChannel:nil];
[metachatScene leaveScene];
// 退出场景回调
- (void)metachatScene:(AgoraMetachatScene *_Nonnull)scene
   onLeaveSceneResult:(NSInteger)errorCode {
       dispatch_async(dispatch_get_main_queue(), ^{
           [metachatScene destroy];
           metachatScene = nil;   
       });
   }
// 销毁 AgoraMetachatScene 对象的回调
- (void)metachatScene:(AgoraMetachatScene *_Nonnull)scene
      onReleasedScene:(NSInteger)errorCode {
          dispatch_async(dispatch_get_main_queue(), ^{
              [AgoraMetachatKit destroy];
              metachatKit = nil;
              [AgoraRtcEngineKit destroy];
              rtcEngine = nil;
          });
      }

// Swift
// 退出场景
rtcEngine?.leaveChannel()
metachatScene?.leave()
// 退出场景回调
func metachatScene(_ scene: AgoraMetachatScene, onLeaveSceneResult errorCode: Int) {
    DispatchQueue.main.async {
        metachatScene?.destroy()
        metachatScene = nil
    }

}
// 销毁 AgoraMetachatScene 对象的回调
func metachatScene(_ scene: AgoraMetachatScene, onReleasedScene errorCode: Int) {
    DispatchQueue.main.async {
        AgoraMetachatKit.destroy()
        metachatKit = nil
        AgoraRtcEngineKit.destroy()
        rtcEngine = nil
    }

}

参考信息

示例项目

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

API 参考

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

开发注意事项

使用 3D 场景的过程中，不能销毁调用 createRenderView 创建的视图。该视图只有退出整个 app 时才能销毁。

这篇文章对你有帮助吗？

是

否