2024/09/18 12:08:38

使用 Wwise 插件实现空间音频

声网支持你通过 SDK 或 Wwise 插件实现空间音效，两种方案的选型详见适用场景。本文介绍如何通过声网 Wwise 插件在你的 Unreal Engine 项目中实现空间音频。

Wwise 插件概述

声网提供的 Wwise 插件主要用于数据流传输，可与声网 RTC SDK 结合使用，增强 RTC SDK 使用时的灵活性。

声网插件名称	插件类别	插件用途
AgoraAudioInputSource	Wwise Source 插件	将 RTC SDK 采集的本地用户音频数据传输给 Wwise
AgoraReceiveSource	Wwise Source 插件	将 RTC SDK 接收到的远端用户音频数据传输给 Wwise
AgoraSendEffect	Wwise Effect 插件	将用户音频数据发送给声网服务器
AgoraAudioSessionEffect	Wwise Effect 插件	用于在总线上获取参考信号以进行回声消除

声网 Wwise 插件当前支持如下架构：

Android：arm64-v8a、armeabi-v7a、x86、x86_64
iOS
Windows：vc160、vc170

声网 Wwise 插件里已经注册了音频观测器对象（IAudioObserverObserver），因此使用该插件后，你将无法再注册额外的音频观测器对象。

1. 准备 Wwise 环境

下载 Audiokinetic Launcher（也被称为 Wwise Launcher）。
在 Audiokinetic Launcher 中安装 Wwise，版本号为 2022.1.13.8454。如果你需要使用其他版本，可以联系技术支持。

安装完成的效果

2. 安装 Wwise 插件

下载声网的 Wwise 插件。解压后会出现 AgoraAuthoringPlugin_Win 文件夹。
打开 Audiokinetic Launcher 软件，在 Plug-ins 页面，点击灰色的 Add from directory，选择 AgoraAuthoringPlugin 文件夹，点击 Install 完成安装。

安装完成后，你会在 Plug-ins 页面看到 AgoraWwiseRTCSDK 插件。

3. 集成 Wwise 至 UE 项目

打开 Audiokinetic Launcher 软件，在 Unreal-Engine 页面，集成 Wwise 到你的 Unreal Engine 项目。

集成具体步骤

点击 Integrate Wwise in Project... 按钮。
设置如下选项，再点击 Integrate 按钮：
- Integration version：选择 All，版本为 2022.1.13.8454。
- Wwise SDK：选择 SDK（版本号为 2022.1.13.8454）的安装路径。
- Wwise Project：选择 Wwise 项目文件的安装路径。

4. 在 Wwise 项目中配置插件

参考本节在 Wwise 项目中配置插件：

打开你已安装的 Wwise 软件并进入你的 Wwise 项目。
在 Master Audio Bus 中添加 AgoraAudioSessionEffect 插件，用于获取参考信号以进行回声消除。
在 Actor-Mixer Hierarchy 下的 Default Work Unit 中添加 AgoraAudioInputSource 插件，用于将本地用户音频数据传输给 Wwise。

添加后，Default Work Unit 下会出现一个名为 New Sound SFX 的节点。为方便后续使用，建议节点改名，例如改成 Audio Input Source。
在 Actor-Mixer Hierarchy 下的 Default Work Unit 中添加 AgoraReceiveSource 插件，用于将远端用户音频数据传输给 Wwise。

添加后，Default Work Unit 下会出现一个名为 New Sound SFX 的节点。为方便后续使用，建议节点改名，例如改成 Audio Receive Source。
在第 3 步添加的 Audio Input Source 节点中，添加 AgoraSendEffect 插件，用于将用户音频数据发送给声网服务器。
为第 3、4 步添加的 Audio Input Source 和 Audio Receive Source 创建 Event，例如播放（Play）和停止（Stop）事件。

以创建 Audio Input Source 的播放事件为例

所有事件创建完成后，效果如下图：

配置插件后，请注意当前插件暂不支持你在 Wwise 软件中进行音频调试播放。

5. 在 UE 项目中使用插件

本节介绍如何在 Unreal Engine 项目中使用 Wwise 插件。

修改 UE 项目

参考如下步骤修改你的 Unreal Engine 项目：

将项目中集成的声网 Unreal SDK 替换成带 Wwise 模块的 Unreal SDK。Wwise 模块对应 SDK 中的 AgoraWwiseCommHandler 和 WwiseHeaderFiles 文件夹。

替换前	替换后
SDK 来源：从下载页获取 SDK 文件夹名称：AgoraPlugin SDK 区别：不含 Wwise 模块	SDK 来源：从本节获取 SDK 文件夹名称：AgoraPlugin SDK 区别：含有 Wwise 模块

打开 Unreal Engine 项目，对 API 进行如下修改：

在初始化的步骤中，需要添加如下代码，以创建并初始化声网 RTC 引擎，以及初始化声网 Wwise 插件。

C++
// 创建并初始化 RtcEngineProxy
RtcEngineProxy = agora::rtc::ue::createAgoraRtcEngineEx();
int ret = RtcEngineProxy->initialize(RtcEngineContext);

// 初始化 Wwise 插件
// 将 RtcEngineProxy 的指针传给 AgoraWwiseCommHandler
// 创建并指定你的 Track ID，可以将 ID 填写为类似于 0、1、2 这样的整数
FAgoraWwiseCommHandlerAgoraInterface::InitAgoraWwisePlugin(RtcEngineProxy, m_SendTrackId);

在销毁的步骤中，需要添加如下代码，以释放卸载声网 Wwise 插件并释放 RTC 引擎资源。

C++
// 卸载 Wwise 插件
FAgoraWwiseCommHandlerAgoraInterface::UninitAgoraWwisePlugin();

if (RtcEngineProxy != nullptr) {
    // 离开频道
    RtcEngineProxy->leaveChannel();
    // 注销事件
    RtcEngineProxy->unregisterEventHandler(UserRtcEventHandlerEx.Get());
    // 释放 RTC 引擎资源
    RtcEngineProxy->release();
    // 将 RtcEngineProxy 的指针设为空
    RtcEngineProxy = nullptr;
}

修改加入频道的代码为如下：

C++
RtcEngineProxy->setClientRole(CLIENT_ROLE_BROADCASTER);
RtcEngineProxy->enableAudio();

agora::rtc::ChannelMediaOptions ChannelMediaOptions;
ChannelMediaOptions.publishMicrophoneTrack = true;
ChannelMediaOptions.autoSubscribeAudio = true;
ChannelMediaOptions.autoSubscribeVideo = true;
ChannelMediaOptions.clientRoleType = CLIENT_ROLE_TYPE::CLIENT_ROLE_BROADCASTER;
ChannelMediaOptions.publishCustomAudioTrack = true;
ChannelMediaOptions.publishCustomAudioTrackId = m_SendTrackId;

LocalUID = GenLocalUID();

// 加入频道
int ret = RtcEngineProxy->joinChannel(TCHAR_TO_UTF8(*Token), TCHAR_TO_UTF8(*ChannelNameVal),
                                      LocalUID, ChannelMediaOptions);

在开麦（即频道内发布用户音频流）的步骤中，修改代码为如下：

C++
FString ChannelName = "ChannelId";
agora::rtc::uid_t uid = 123;

// 开启本地音频模块
RtcEngineProxy->enableLocalAudio(true);

agora::rtc::ChannelMediaOptions Options;
// 发布麦克风采集到的音频
Options.publishMicrophoneTrack = true;
// 发布自定义音频
Options.publishCustomAudioTrack = true;
Options.publishCustomAudioTrackId = m_SendTrackId;
// 设置用户为主播角色，主播才有发布音频流的权限
Options.clientRoleType = CLIENT_ROLE_TYPE::CLIENT_ROLE_BROADCASTER;

agora::rtc::RtcConnection Connection;
std::string StdStrChannelName = TCHAR_TO_UTF8(*ChannelName);
Connection.channelId = StdStrChannelName.c_str();
Connection.localUid = uid;

// 频道内更新媒体选项
int ret = RtcEngineProxy->updateChannelMediaOptionsEx(Options, Connection);

在闭麦（即频道内停止发布用户音频流）的步骤中，修改代码为如下：

C++
FString ChannelName = "ChannelId";
agora::rtc::uid_t uid = 123;

// 关闭本地音频模块
RtcEngineProxy->enableLocalAudio(false);

agora::rtc::ChannelMediaOptions Options;
// 禁止发布麦克风采集到的音频
Options.publishMicrophoneTrack = false;
// 禁止发布自定义音频
Options.publishCustomAudioTrack = false;
Options.publishCustomAudioTrackId = m_SendTrackId;
Options.clientRoleType = CLIENT_ROLE_TYPE::CLIENT_ROLE_BROADCASTER;

agora::rtc::RtcConnection Connection;
std::string StdStrChannelName = TCHAR_TO_UTF8(*ChannelName);
Connection.channelId = StdStrChannelName.c_str();
Connection.localUid = uid;

// 频道内更新媒体选项
int ret = RtcEngineProxy->updateChannelMediaOptionsEx(Options, Connection);

插件使用注意事项

如果你的 UE 项目会编译运行到如下平台，使用 Wwise 插件时你需注意如下：

运行平台注意事项

Android 根据 Wwise 官网声明的 Android 注意事项，Wwise 自 2022.1.5 版本起，与 Unreal Engine 4.27 和 5.0 不兼容。本文使用的 Wwise 版本为 2022.1.13.8454，因此你需要使用高于 5.0 版的 Unreal Engine。

iOS

运行平台	注意事项
Android	根据 Wwise 官网声明的 Android 注意事项，Wwise 自 2022.1.5 版本起，与 Unreal Engine 4.27 和 5.0 不兼容。本文使用的 Wwise 版本为 2022.1.13.8454，因此你需要使用高于 5.0 版的 Unreal Engine。
iOS	确保完成如下步骤，如果系统已自动完成，请跳过：将 Unreal SDK 中 `AgoraPlugin/Resources/WwiseHeaderFiles/.h` 文件复制到 UE 项目中 `<project_name>/Plugins/Wwise/ThirdParty/include/AK/Plugin/.h` 文件。打开 UE 项目中 `<project_name>/Plugins/Wwise\Source\WwiseSoundEngine\Public\Generated\AkiOSPlugins.h` 文件，添加对 `AgoraWwiseRTCSDKSourceFactory.h` 的引用，示例代码如下： C++ `#if PLATFORM_IOS #include <AK/Plugin/AkToneSourceFactory.h> ... #include <AK/Plugin/AgoraWwiseRTCSDKSourceFactory.h> #endif`
Windows	声网 Unreal SDK 中 ThirdParty 目录下的 `AgoraWwiseRTCSDK.dll` 和 `AgoraWwiseRTCSDK.lib` 文件会复制到你的 UE 项目中 Wwise 的 ThirdParty 目录下。最终 SDK 和 UE 项目都会依赖 Wwise 的 ThirdParty 目录下这两个文件。

确保完成如下步骤，如果系统已自动完成，请跳过：

将 Unreal SDK 中 AgoraPlugin/Resources/WwiseHeaderFiles/*.h 文件复制到 UE 项目中 <project_name>/Plugins/Wwise/ThirdParty/include/AK/Plugin/*.h 文件。
打开 UE 项目中 <project_name>/Plugins/Wwise\Source\WwiseSoundEngine\Public\Generated\AkiOSPlugins.h 文件，添加对 AgoraWwiseRTCSDKSourceFactory.h 的引用，示例代码如下：
C++
```
#if PLATFORM_IOS
#include <AK/Plugin/AkToneSourceFactory.h>
...
#include <AK/Plugin/AgoraWwiseRTCSDKSourceFactory.h>
#endif
```

Windows 声网 Unreal SDK 中 ThirdParty 目录下的 AgoraWwiseRTCSDK.dll 和 AgoraWwiseRTCSDK.lib 文件会复制到你的 UE 项目中 Wwise 的 ThirdParty 目录下。最终 SDK 和 UE 项目都会依赖 Wwise 的 ThirdParty 目录下这两个文件。

插件日志路径

Android：/storage/emulated/0/AgoraAudio/agora_wwise_log.txt
iOS：App Sandbox/agora_wwise_log.txt
Windows：C:\Users\<user_name>\AppData\Local\Agora\agora_wwise_log.txt。如果你使用 UE4 和低于 C++17 的 C++ 语言开发，那么当前日志路径依赖于 Windows 的函数。如果遇到路径冲突或编译错误，你可以在 AgoraCommLog.cpp 文件中手动修改日志路径。

API 参考

Unreal SDK 中 Wwise 模块提供如下 API，你可以按需调用：

C++
// 获取 Wwise 插件版本号
static std::string GetAgoraWwiseVersion();

// 初始化 Wwise 插件
static int InitAgoraWwisePlugin(agora::rtc::IRtcEngine* AgoraRtcEngineInstance,
                                int& OutDefaultCustomAudioTrackId);

// 卸载 Wwise 插件
static int UninitAgoraWwisePlugin();

// 设置 ID 之间的映射关系
// 将 Unreal SDK 中的频道 ID 和用户 ID 映射到 Wwise 的 Game Object ID
static void AWPlugin_Receive_SetUidToGameObjectIDMapping(AkGameObjectID gameObjectID,
                                                         const std::string& channelID,
                                                         const rtc::uid_t& userID);

// 获取 ID 之间的映射关系
static bool AWPlugin_Receive_GetUidByGameObjectID(AkGameObjectID gameObjectID,
                                                  std::string& channelID, rtc::uid_t& userID);

// 清除 ID 之间的映射关系
static bool AWPlugin_Receive_ClearReceiveOpenID(const std::string& channelID,
                                                const rtc::uid_t& userID);

GetAgoraWwiseVersion：获取 Wwise 插件版本号。
InitAgoraWwisePlugin：初始化 Wwise 插件。
UninitAgoraWwisePlugin：卸载 Wwise 插件。
AWPlugin_Receive_SetUidToGameObjectIDMapping：设置 ID 之间的映射关系。
AWPlugin_Receive_GetUidByGameObjectID：获取 ID 之间的映射关系。
AWPlugin_Receive_ClearReceiveOpenID：清除 ID 之间的映射关系。

ID 之间的映射关系指将 Unreal SDK 中频道 ID、用户 ID 映射到 Wwise 的 Game Object ID 的关系。开发过程中，你无需管理 Unreal SDK 与 Wwise 之间的 ID 关系，因此不推荐你调用这些方法。你只需要将 SDK 中频道 ID、用户 ID 与 UE 项目中 Actor 进行绑定。绑定示例如下：

6. 实现空间音频

完成上述步骤后，你可以利用 Wwise 的基础功能构建空间音频效果，详见 Wwise 官方社区博文。

Wwise 插件概述​

1. 准备 Wwise 环境​

2. 安装 Wwise 插件​

3. 集成 Wwise 至 UE 项目​

4. 在 Wwise 项目中配置插件​

5. 在 UE 项目中使用插件​

修改 UE 项目​

插件使用注意事项​

插件日志路径​

API 参考​

6. 实现空间音频​