客户端实现（iOS）

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

技术原理

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

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

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

前提条件

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

• Xcode 12.0 或以上版本。
• iOS 11.0 或以上版本的真机。部分模拟机可能无法支持本项目的全部功能。

项目配置

开通元语聊

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

1. 获取 App ID。详情请参考开始使用 Agora 平台。
2. 联系销售并提供你的 App ID。

集成 SDK

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

参考以下步骤集成 Agora RTC 4.0.0 元语聊特殊版 SDK：

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

2. 打开解压文件，将 libs 路径下的所有文件拷贝到你的项目路径下。

3. 打开 Xcode，添加对应动态库，确保添加的动态库 Embed 属性设置为 Embed & Sign。

   • 根据 Apple 官方要求，app 的 Extension 中不允许包含动态库。如果项目中的 Extension 需要集成 SDK，则添加动态库时需将文件状态改为 Do Not Embed。
   • Agora SDK 默认使用 libc++ (LLVM)，如需使用 libstdc++ (GNU)，请联系 sales@agora.io。SDK 提供的库是 FAT Image，包含 32/64 位模拟器、32/64 位真机版本。

实现方法

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

• 实时音频互动
• 3D 场景管理
• 麦位管理
• 空间音效

实时音频互动

在搭建元语聊场景之前，建议你先参考官网 Agora RTC SDK 4.0.0 的快速开始，实现一个基础的语音通话。

3D 场景管理

3D 场景管理需要用到 Agora SDK 的以下类：

• AgoraMetaViewController、AgoraMetachatKit 和 AgoraMetachatScene 类：提供元语聊的核心功能。
• AgoraRtcEngineKit 类：提供实时音视频功能。

具体的 API 调用时序如下，你还可以同时参考示例项目 Agora-MetaChat 中的源码。

麦位管理

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

上麦的 API 调用时序如下：

空间音效

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

参考信息

示例项目

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

API 参考

• 3D 场景管理相关 API 详见元语聊 API 参考。
• 实时音频互动、空间音效功能的核心 API 如下：

  API	实现功能
  sharedEngineWithAppId	创建并初始化 RtcEngine。
  setChannelProfile	将频道场景设为直播（LiveBroadcasting） 。 该场景下有两种用户角色，可以通过 setClientRole 设置。
  setAudioProfile	将音频编码属性设为 Default，音频场景设为 GameStreaming。
  setClientRole	设置用户角色。进入场景时，需要将语聊者的用户角色设为 Broadcaster、游客的用户角色设为 Audience。 游客上麦后，需要先调用该方法将用户角色切换为 Broadcaster，才能在房间里发布音频流。
  joinChannelByToken	加入 RTC 频道。用户加入 RTC 频道后才能接收或发布音频流。你也可以通过 mediaOptions 参数设置频道场景和用户角色。
  leaveChannel	离开 RTC 频道。
  muteAllRemoteAudioStreams	取消或恢复订阅所有远端用户的音频流。
  AgoraLocalSpatialAudioKit	使用本地直角坐标系计算方案实现空间音效。