使用 Wwise 插件实现空间音频

声网支持你通过 SDK 或 Wwise 插件实现空间音效，两种方案的选型详见适用场景。本文介绍如何通过声网 Wwise 插件在你的 Unity 项目中实现空间音频，增强游戏体验。在多人在线语音视频聊天场景中，空间音效可以实现多人语音的空间感及后期效果处理，大大增强产品的竞争力。

插件概述Copy Anchor Link

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

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

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

前提条件Copy Anchor Link

开始前，请确保你的本地有一个 Unity 项目。相关步骤可以参考 RTC 快速开始。

准备开发环境Copy Anchor Link

下载 Wwise 编辑器Copy Anchor Link

1. 下载 Audiokinetic Launcher（也被称为 Wwise Launcher）。
2. 在 Audiokinetic Launcher 中安装 Wwise 编辑器 2023.1.6.8555。

下载 SDK 与插件Copy Anchor Link

声网 Unity 平台 Wwise 解决方案由 Wwise 编辑器插件、RTC Unity SDK 和 Wwise Plugin SDK 共同搭建实现，对各模块的兼容版本号有明确要求。在准备开发环境时，请确保下载并安装指定版本的 SDK 和插件：

• 点击下载声网 Wwise 编辑器插件 2023.1.6.8555。该插件兼容 Wwise 编辑器 2023.1.6.8555。
• 下载声网 RTC Unity SDK v4.3.2.14。
• 下载 声网 Wwise Plugin SDK 2023.1.6.8555_v4.3.2.14。

导入 SDKCopy Anchor Link

1. 将下载下来的 RTC SDK 添加到你的 Unity 项目中。
2. 解压下载后的 Agora-Wwise-Plugin 插件，将解压后的 Agora-Wwise-Plugin 文件夹拷贝到你的 Unity 项目的 Assets 文件夹下。
3. 解压下载后的 Wwise 编辑器插件，会得到一个 AG_Plugin_FULL 文件。在 Wwise Launcher 中，点击左侧的 Plug-ins，然后点击 Add from directory。选中 AG_Plugin_FULL 进行添加。安装完成后，你会在 Plug-ins 界面的 INSTALLED PLUG-INS 区域内看到安装完成的 AgoraWwiseRTCSDK：

集成 Wwise 插件至 Unity 项目Copy Anchor Link

1. 在 Wwise Launcher 中，点击左侧的 Unity，你应该能看到你创建的 Unity 项目名称，例如 My Project：

2. 点击项目名右侧的 Integrate Wwise in Project，然后根据屏幕指引，勾选你想要下载包、部署平台，然后点击 Integrate，开始集成。

   注意

   确保你在该步骤中将 Integration version 设置为 2023.1.6.8555。

集成成功后，根据你勾选的部署平台，你应当在你的 Unity 项目路径下找到如下文件。如果没有找到，可以参考手动拷贝 Wwise 插件文件。

在 Wwise 中配置插件Copy Anchor Link

1. 在 Wwise 中打开你的 Unity 项目。你可以直接从 Wwise Launcher 中 Unity 项目右侧的 Open in Wwise 按钮打开。

2. 在 Actor-Mixer Hierarchy 下的任意节点单击右键，选择 New Child > AgoraAudioInputSource，创建一个新的 Sound SFX，用于将本地用户音频数据传输给 Wwise。将其重命名，例如 AudioInputSource。

3. 点击刚刚创建好的 AudioInputSource，在 Effects 面板上点击 + 按钮，新增 AgoraSendEffect，用于将用户音频数据发送给声网服务器。

4. 在 Actor-Mixer Hierarchy 下的任意节点单击右键，选择 New Child > AgoraReceiveSource，创建一个新的 SoundSFX，用于将远端用户音频数据传输给 Wwise。这里我们可以命名为 AgoraRecevieSource。

5. 在 Master-Mixer Hierarchy > Default Work Unit > Master Audio Bus 的 Effects 面板下添加 AgoraAudioSessionEffect，用于将本地用户音频数据传输给 Wwise。

6. 为刚刚创建的 AgoraInputSource 和 AgoraReceiveSource 分别添加 Play 和 Stop 事件。

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

7. 将刚才创建的所有 Event，Sound SFX 和 Master Audio Bus 加入到 SoundBank 中，并 Generate SoundBank。

在 Unity 项目中使用插件Copy Anchor Link

初始化设置Copy Anchor Link

你需要在该步骤中初始化 RtcEngine 和 Agora Wwise Plugin，并参考如下代码设置相关的私有参数：

using Agora.Rtc;
 
private IRtcEngineEx _rtcEngineEx = null;
private int _sendTrackId = 0;
 
 
// 初始化 RtcEngine
_rtcEngineEx = RtcEngine.CreateAgoraRtcEngineEx();
RtcEngineContext rtcEngineContext = new RtcEngineContext();
rtcEngineContext.appId = appId;
rtcEngineContext.areaCode = AREA_CODE.AREA_CODE_GLOB;
var nRet = _rtcEngineEx.Initialize(rtcEngineContext);
_rtcEngineEx.SetClientRole(CLIENT_ROLE_TYPE.CLIENT_ROLE_BROADCASTER);
Debug.Log("RtcEngine Initialize: " + nRet);
_rtcEngineEx.InitEventHandler(new RtcEngineEventHandler());
_rtcEngineEx.EnableAudio();
_rtcEngineEx.DisableVideo();
           
 
// 初始化 Agora-Wwise-Plugin
IntPtr nativeHandler = IntPtr.Zero;
_rtcEngineEx.GetNativeHandler(ref nativeHandler);
AgoraWwiseWrapper.InitAgoraWwisePlugin(nativeHandler, ref _sendTrackId);
Debug.Log("_sendTrackId :" + _sendTrackId);
 
// 设置私参
_rtcEngineEx.SetParameters("{\"che.audio.mute_playout_signal\":true}");
 
// Audio Profile
_rtcEngineEx.SetParameters("{\"che.audio.custom_payload_type\":122}");
_rtcEngineEx.SetParameters("{\"che.audio.custom_bitrate\":24000}");
_rtcEngineEx.SetParameters("{\"che.audio.bitrate_level\":1}");
_rtcEngineEx.SetParameters("{\"che.audio.force_bluetooth_a2dp\":true}");
_rtcEngineEx.SetParameters("{\"che.audio.opensl.sync_downlink_process\":false}");
 
// Module Related
_rtcEngineEx.SetParameters("{\"che.audio.use_media_volume_in_headset\":1}");
_rtcEngineEx.SetParameters("{\"che.audio.use_media_volume_in_bluetooth\":1}");
_rtcEngineEx.SetParameters("{\"che.audio.ans.noise_gate\":200}");
_rtcEngineEx.SetAudioScenario(AUDIO_SCENARIO_TYPE.AUDIO_SCENARIO_GAME_STREAMING);
 
#if UNITY_IPHONE
_rtcEngineEx.SetParameters("{\"che.audio.keep.audiosession\":true}");
#endif
 
_rtcEngineEx.SetParameters("{\"che.audio.ps.mode\":0}");
_rtcEngineEx.SetParameters("{\"che.audio.sf.statNsFastNsSpeechTrigThreshold\":0}");

加入频道并收、发流Copy Anchor Link

调用 RTC SDK 的 JoinChannel 方法加入 RTC 频道，并设置订阅和发布选项。

然后将我们在 Wwise 编辑器中创建的 SoungSFX 绑定到用于发流或者收流的 GameObject，实现 RTC SDK 和 Wwise 之间的音频传输。完整的实现逻辑和示例代码如下：

// 加入频道
var options = new ChannelMediaOptions();
options.publishCameraTrack.SetValue(true);
options.publishMicrophoneTrack.SetValue(true);
options.autoSubscribeAudio.SetValue(true);
options.autoSubscribeVideo.SetValue(true);
options.publishCustomAudioTrack.SetValue(true);
options.publishCustomAudioTrackId.SetValue(_sendTrackId);
_rtcEngineEx.JoinChannel("", channelId, uint.Parse(userId), options);
 
// 想要正常发流，必须在场景内创建一个用于发流的 GameObject（比如 3D游戏中常见的小人，或者是一个麦克风都可以)
// 并且在这个 GameObject 上绑定一个组件，在组件内填写如下代码
public void Start()
{
    // 这段代码用于在我们当前的 GameObject 添加一个我们在 Wwise 编辑器里创建的 Sound SFX
    // 该 Sound SFX 会持续的从 RTC SDK 中传输麦克风音频到 Wwise 中
    this.gameObject.AddComponent<AkGameObj>();
    AkSoundEngine.PostEvent("Play_AudioInputSource", this.gameObject);
}
 
 
private void OnDestroy()
{  
    AkSoundEngine.PostEvent("Stop_AudioInputSource", this.gameObject);
}
 
 
// 当远端用户加入 RTC 频道后，需要在当前场景内创建一个用于收流的 GameObject，并且在这个 GameObject 上绑定一个组件，在组件内填写如下代码
public void Start()
{
    // remoteUid: 远端用户的 UID
    // channelId: RTC 频道的 ID
    this.gameObject.AddComponent<AkGameObj>();
    ulong gameObjId = AkSoundEngine.GetAkGameObjectID(this.gameObject);
    Agora.Rtc.AgoraWwiseWrapper.SetUidToGameObjectIDMapping(gameObjId, channelId, remoteUid);
    AkSoundEngine.PostEvent("Play_AgoraReceiveSource", this.gameObject);
}

// 在远端用户离开房间后，需要销毁 GameObject 并且触发其 OnDestroy 方法
private void OnDestroy()
{
    AkSoundEngine.PostEvent("Stop_AgoraReceiveSource", this.gameObject);
    Agora.Rtc.AgoraWwiseWrapper.ClearReceiveOpenID(channelId, remoteUid);
}
 
// 在频道里下麦
public void MuteLocal()
{
    var options = new ChannelMediaOptions();
    options.publishCameraTrack.SetValue(false);
    options.publishMicrophoneTrack.SetValue(false);
    options.autoSubscribeAudio.SetValue(true);
    options.autoSubscribeVideo.SetValue(true);
    options.publishCustomAudioTrack.SetValue(false);
    options.publishCustomAudioTrackId.SetValue(_sendTrackId);
    _rtcEngineEx.UpdateChannelMediaOptions(options);
}
 
// 在频道上麦
public void UnmuteLocal()
{
    var options = new ChannelMediaOptions();
    options.publishCameraTrack.SetValue(true);
    options.publishMicrophoneTrack.SetValue(true);
    options.autoSubscribeAudio.SetValue(true);
    options.autoSubscribeVideo.SetValue(true);
    options.publishCustomAudioTrack.SetValue(true);
    options.publishCustomAudioTrackId.SetValue(_sendTrackId);
    _rtcEngineEx.UpdateChannelMediaOptions(options);
}

离开频道Copy Anchor Link

_rtcEngineEx.LeaveChannel();

销毁资源Copy Anchor Link

Agora.Rtc.AgoraWwiseWrapper.UninitAgoraWwisePlugin();
_rtcEngineEx.LeaveChannel();
_rtcEngineEx.Dispose();
_rtcEngineEx = null;

参考信息Copy Anchor Link

构建 App 注意事项Copy Anchor Link

导出 iOS 工程时，控制台会报错，提示 AgoraWwiseRTCSDKFX.a 找不到。此时需要打开你生成的 SoundBanks。默认情况下，SoundBanks 文件位于 Wwise 编辑器工程 /GeneratedSoundBanks/iOS 文件夹下。如果你设置了其他路径，请打开对应的目录。然后打开 PluginInfo.xml 文件，查找如下关键字：

StaticLib="AgoraWwiseRTCSDKFX"

应该可以在文件内查找到如下两处：

将其中的 StaticLib="AgoraWwiseRTCSDKFX" 修改为：

StaticLib="AgoraWwiseRTCSDKSource"

修改后如下所示，保存文件：

接着，我们在 Unity Editor 里导出 iOS 工程并用 Xcode 打开之后，可以在 Libraries/Wwise/API/Runtime/Plugins/iOS/iphoneos/DSP 文件下，看到如下三个文件，和 include "AgoraWwiseRTCSDKSourceFactory.h" 这句代码：

至此，iOS 的 App 构建得以顺利完成。

如果在 Xcode 目录下并没有 AkiOSPlugins 文件，请检查 Data/Raw/Audio/GeneratedSoundBanks/iOS/PluginInfo.xml 文件中内容是否为被修改后的内容：

如果发现该文件内的内容又恢复到了 StaticLib="AgoraWwiseRTCSDKFX"，则说明在构建过程中 SoundBanks 被重新生成了，导致之前的文本修改被重新覆盖。此时可以检查是否在 Unity Editor 里勾选了 Generate SoundBanks at pre-Build step：

手动拷贝 Wwise 插件文件Copy Anchor Link

在集成 Wwise 到 Unity 项目中之后，如果你发现缺失了上文中列出的部分的文件，可以手动将这些文件拷贝进入 Unity 项目中：

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

Wwise 插件概述Copy Anchor Link

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

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

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

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

1. 准备 Wwise 环境Copy Anchor Link

1. 下载 Audiokinetic Launcher（也被称为 Wwise Launcher）。

2. 在 Audiokinetic Launcher 中安装 Wwise，版本号为 2021.1.14.8108。如果你需要使用其他版本，可以联系技术支持。

2. 安装 Wwise 插件Copy Anchor Link

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

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

3. 集成 Wwise 至 UE 项目Copy Anchor Link

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

4. 在 Wwise 项目中配置插件Copy Anchor Link

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

1. 打开你已安装的 Wwise 软件并进入你的 Wwise 项目。

2. 在 Master Audio Bus 中添加 AgoraAudioSessionEffect 插件，用于获取参考信号以进行回声消除。

3. 在 Actor-Mixer Hierarchy 下的 Default Work Unit 中添加 AgoraAudioInputSource 插件，用于将本地用户音频数据传输给 Wwise。

添加后，Default Work Unit 下会出现一个名为 New Sound SFX 的节点。为方便后续使用，建议节点改名，例如改成 Audio Input Source。

4. 在 Actor-Mixer Hierarchy 下的 Default Work Unit 中添加 AgoraReceiveSource 插件，用于将远端用户音频数据传输给 Wwise。

添加后，Default Work Unit 下会出现一个名为 New Sound SFX 的节点。为方便后续使用，建议节点改名，例如改成 Audio Receive Source。

5. 在第 3 步添加的 Audio Input Source 节点中，添加 AgoraSendEffect 插件，用于将用户音频数据发送给声网服务器。

6. 为第 3、4 步添加的 Audio Input Source 和 Audio Receive Source 创建 Event，例如播放（Play）和停止（Stop）事件。

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

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

5. 在 UE 项目中使用插件Copy Anchor Link

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

修改 UE 项目Copy Anchor Link

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

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

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

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

     Copy Text

     // 创建并初始化 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 引擎资源。

     Copy Text

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

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

     Copy Text

     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);

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

     Copy Text

     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);

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

     Copy Text

     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);

插件使用注意事项Copy Anchor Link

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

插件日志路径Copy Anchor Link

• 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 参考Copy Anchor Link

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

// 获取 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. 实现空间音频Copy Anchor Link

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