WAAPI 和 Lua

在阅读接下来的章节之前，建议先对 WAAPI、Lua 和 ReaScript 做一个基本的了解。这里有一些学习资源，感兴趣的话不妨看下：

ReaWwise

要在 ReaScript 内运行 WAAPI 命令，必须安装 ReaWwise 。

The ReaScript Development Environment

要进入 ReaScript Development Environment，请先打开 REAPER。然后，在 REAPER 菜单中依次选择 Actions > Show action list... 。接着，在 Actions 对话框右下角依次单击 New action... > New ReaScript... 。这时会提示保存文件。对 ReaScript 文件进行命名，然后单击 Save 。在保存之后，便会打开 ReaScript Development Environment。我们将在此编写代码。

Hello World

-- Waapi Hello World.lua

if (reaper.AK_Waapi_Connect( "127.0.0.1" , 8080 )) then
reaper.ShowConsoleMsg( "Successfully connected to Wwise!" )

reaper.AK_Waapi_Disconnect()
end

在上面的代码段中，我们首先调用 AK_Waapi_Connect 。此函数会获取 WAAPI 与 Wwise 通信所用的 IP 和 PORT 。它会返回一个布尔值：若连接成功，则返回 true；否则，返回 false。在 if 语句末尾，确保通过调用 AK_Waapi_Disconnect 来终止连接。若脚本运行成功，REAPER console output 窗口会弹出以下消息：

基本示例 (Get Selected Objects)

在以下示例中，我们来看看如何在 Wwise 中查询当前选定的对象。

-- Get Selected Objects.lua

if (reaper.AK_Waapi_Connect( "127.0.0.1" , 8080 )) then
local fieldsToReturn = reaper.AK_AkJson_Array()

reaper.AK_AkJson_Array_Add(fieldsToReturn, reaper.AK_AkVariant_String( "path" ))

local options = reaper.AK_AkJson_Map()
reaper.AK_AkJson_Map_Set(options, "return" , fieldsToReturn)

local result = reaper.AK_Waapi_Call( "ak.wwise.ui.getSelectedObjects" ,
reaper.AK_AkJson_Map(), options)

local status = reaper.AK_AkJson_GetStatus(result)

if (status) then
local objects = reaper.AK_AkJson_Map_Get(result, "objects" )
local numObjects = reaper.AK_AkJson_Array_Size(objects)

for i= 0 , numObjects - 1 do
local item = reaper.AK_AkJson_Array_Get(objects, i)
local path = reaper.AK_AkJson_Map_Get(item, "path" )
local pathStr = reaper.AK_AkVariant_GetString(path)
reaper.ShowConsoleMsg(pathStr .. "\n" )
end
end

reaper.AK_AkJson_ClearAll()
reaper.AK_Waapi_Disconnect()
end

AkJson

为了方便创建 JSON 对象，ReaWwise 导出了各种辅助函数。藉此，ReaScript 可根据脚本编写者的需求动态创建 JSON 对象。

调用 WAAPI 需要三个元素：参数、选项和命令字符串。在本例中，命名字符串为 ak.wwise.ui.getSelectedObjects 。有关 WAAPI 命令的详尽列表，请参阅 WAAPI 参考。

对于这个命令，WAAPI 会将空映射作为参数。在此，我们只需设置 options 映射即可。

我们要创建的 options 映射就跟下面一样：

{
"return" : [
"path"
]
}

由于 REAPER 的 Lua 上下文和 ReaWwise 后端之间只能传递值类型和指针，所以需要分多个步骤来创建 options 映射。

首先，创建 fieldsToReturn 数组：

local fieldsToReturn = reaper.AK_AkJson_Array()

fieldsToReturn 变量会返回指向 ReaWwise 后端中数组的指针。利用该指针，我们可以对数组进行操作。

然后，将 path 字符串作为元素添加到 fieldsToReturn ：

reaper.AK_AkJson_Array_Add(fieldsToReturn, reaper
.AK_AkVariant_String( "path" ))

最后，创建 options 映射并将 fieldsToReturn 数组添加为键值为 return 的值：

local options = reaper.AK_AkJson_Map()
reaper.AK_AkJson_Map_Set(options, "return" , fieldsToReturn)

调用 WAAPI

在创建全部所需参数后，将其用作调用 WAAPI 时的输入：

local result = reaper.AK_Waapi_Call( "ak.wwise.ui.getSelectedObjects" ,
reaper.AK_AkJson_Map(), options)

然后，便可察看结果以确认对 WAAPI 的调用是否成功。注意，复杂的数据结构无法直接从 ReaWwise 后端传递到 Lua 上下文。在这里，结果变量是一个指针。

我们可以查询 status：

local status = reaper.AK_AkJson_GetStatus(result)

若 status 为 true，就可继续查询调用 WAAPI 时返回的实际数据：

local objects = reaper.AK_AkJson_Map_Get(result, "objects" )
local numObjects = reaper.AK_AkJson_Array_Size(objects)

然后，遍历 numObjects 并提取所需的数据：

for i= 0 , numObjects - 1 do
...
end

每个对象都表示为映射。要访问对象的特定属性，可使用 ReaWwise 后端提供的辅助函数。

要从 objects 数组获取单个对象，需要使用 objects 指针和索引值：

local item = reaper.AK_AkJson_Array_Get(objects, i)

变量 item 是指向映射对象的指针。该对象代表 objects 数组中的单个对象。然后，便可提取 path 变量：

local path = reaper.AK_AkJson_Map_Get(item, "path" )

映射和数组值在内部存储为变体对象。要提取最终值，得知道该值代表什么数据。在本例中，我们知道应该获取字符串。为此，使用以下辅助函数从变体数据类型获取字符串：

local pathStr = reaper.AK_AkVariant_GetString(path)

变量 pathStr 是个常规 Lua 字符串，在后续的脚本代码中都可以使用。脚本会直接将 pathStr 输出到 REAPER 控制台。

reaper.ShowConsoleMsg(pathStr .. "\n" )

由于 ReaWwise 后端需要追踪整个 Lua 代码中使用的引用类型对象，所以在不再需要这些对象时必须予以清除：

reaper.AK_AkJson_ClearAll()

Advanced Example (Import)

在下一示例中，我们会做一些更复杂的操作。比如，把音频文件从 REAPER 渲染目录传输到 Wwise 中。在此，每个音频文件都将作为 Sound SFX 导入到已在脚本中硬编码的导入目标下。此处要使用的底层 WAAPI 命令为 ak.wwise.core.audio.import 。

对于这个示例，我不会详细阐释每行代码的作用，因为有关 API 的大部分概念已经在上一示例中说过了。不过，我会大致介绍一下各段代码的作用。

第 3-13 行：连接到 WAAPI，设置 importDestination，然后得出渲染目录。在此脚本中，我们假定渲染目录与工程文件的父目录相同。

第 15-41 行：构建所有要作为输入传给 AK_Waapi_Call 函数的 AkJson 结构。

第 44-70 行：遍历渲染目录并将遇到的所有 WAV 文件添加到要导入的音频文件列表。

第 74-101 行：执行 AK_WAAPI_Call 函数并在 REAPER 控制台中显示结果。这些代码行还包含在遇到错误时从结果中提取错误信息的逻辑。

在本文中，我们查看了几个直接在 Lua ReaScript 中使用 WAAPI 的示例。从与 Wwise 的基本连接到查询 Wwise，再到导入音频文件等较为复杂的操作。希望此 API 能在工作流程当中给大家带来帮助。同时，期待看到各位在 ReaScript 中灵活运用 WAAPI。

Wwise Authoring Query Language 简介

“Wwise 不过是张电子表格”。作为用户体验团队成员，我们经常会听到有人这样说。事实上，Wwise 不仅是款声音设计工具，Wwise...

20.7.2021 - 作者：伯纳德罗德里格 (Bernard Rodrigue)

为 Wwise 2021.1 构建插件 | 第 1 部分：背景和目标

大家可能不知道，Wwise 生态系统其实具有很强的可扩展性。有时，各公司要为其项目构建定制的插件，供应商会将自研插件迁移到 Wwise。对此，我们必然要提供相应的支持。新的 Wwise...

27.9.2021 - 作者：米歇尔•多奈斯 (Michel Donais)

Wwise Spatial Audio 2023.1 新增功能 | Reverb Zone

Reverb Zone 简介在 Wwise 23.1 中，我们为 Wwise Spatial Audio 增添了一个名为 Reverb Zone 的工具。Reverb Zone 本质上来说是...

10.1.2024 - 作者：托马斯•汉森 (Thomas Hansen)

Wwise HDR：游戏混音概述及窍门

HDR (High Dynamic Range) 是 Wwise 中的一项功能。藉此，我们可以轻松管理工程的混音和输出动态范围。在多年的游戏音频从业生涯里，我在工作中经常会用到...

5.6.2025 - 作者：Alex Previty