目录

Wwise SDK 2018.1.11
集成 Marker

简介

Marker(标记)是插入 WAV 文件并用在波形中标示位置的标识符。通常可以在 WAV 编辑器应用程序(例如 SoundForge®、Adobe® Audition® 或 CueTool)中创建这些标记。

当播放到特定位置时,应用程序可使用这些标记来获得通知。例如,您可以使用此信息将视觉内容的绘制与正在播放的音频同步,或者了解随机容器正在播放哪个文件,以便在游戏中显示正确的字幕。

Note: 使用 Wwise 标记通知(Marker Notification)功能通常是集成对口型或字幕解决方案最高效的方式。

使用 .wav 文件格式

块(chunk)是用于存储提示点(cue point)或有关提示点的数据的数据存储单元。提示点是 .wav 格式文件中标示的兴趣点。

提示块

提示块(cue chunk)格式用于存储标记位置,标记位置用于提示 .wav 文件中的兴趣点。

偏移量 字节 说明 值
0x00 4 块 ID "cue " (0x63756520)
0x04 4 块数据大小 取决于提示点数量
0x08 4 提示点数量 列中提示点的数量
0x0c 提示点从此开始
#define CueID 'cue ' /* 提示块的块 ID*/
typedef struct {
ID chunkID;
long chunkSize;
long dwCuePoints;
CuePoint points[];
} CueChunk;
typedef struct {
long dwIdentifier;
long dwPosition;
ID fccChunk;
long dwChunkStart;
long dwBlockStart;
long dwSampleOffset;
} CuePoint;

列表块

列表块(list chunk)是包 .wav 文件内部的容器,其中包含子块。相关数据列表块(associated data list chunk,adtl)格式用于存储标签、注释以及与提示点的关联文本。

偏移量 字节 说明 值
0x00 4 块 ID "list" (0x6C696E74)
0x04 4 块数据大小 取决于包含的子块
0x08 4 类型 ID "adtl" (0x6164746C)
0x0c 子块从此开始

标签子块

标签子块(label sub-chunk)格式用于存储提示点的关联字符串。它应该位于关联数据列表块内。

偏移量 字节 说明 值
0x00 4 块 ID "labl" (0x6C61626C)
0x04 4 块数据大小 取决于文本大小
0x08 4 提示点 ID 参阅提示块 dwIdentifier
0x0c 标签(大小可变的文本)

如何使用标记通知

以下是有关如何设置应用程序,以使它能够接收标记通知的说明:

  • 在发送播放事件时,应将 AK_Marker 标识添加到 in_uiFlags 。如果您还想收到End of Event(事件结束)通知,则应使用 AK_EndOfEvent | AK_Marker ,因为这些标志采取按位异或运算。
AkUniqueID in_eventID, // 唯一的事件 ID
AkGameObjectID in_gameObjectID, // 相关游戏对象 ID
AkUInt32 in_uFlags = 0, // 位掩码:见 AkCallbackType
AkCallbackFunc in_pfnCallback = NULL, // 回调函数
void * in_pCookie = NULL // 回调的 cookie 将与其他信息一起
// 发送到回调函数
);
  • 您的回调函数必须采用以下格式:
static void MarkersCallback(
AkCallbackType in_eType, // 回调原因的类型,在本例中,类型为接收到
// 标记事件时的 AK_Marker。
AkCallbackInfo* in_pCallbackInfo // 指向回调信息结构的指针,在本例中为
// AkMarkerCallbackInfo*。
  • 当您调用回调函数时,您首先需要检查传入的是哪种通知。例如,如果您只想处理AK_Marker 通知,则在收到任何其他事件类型时应返回。
  • 根据通知的类型,您可以将in_pCallbackInfo 类型转换(typecast)为相应的信息结构类型。对于 AK_Marker 通知,相应的信息结构类型为 AkMarkerCallbackInfo。
// 对应于 AK_Marker 的回调信息结构。
{
AkUInt32 uIdentifier; // 提示点标识符
AkUInt32 uPosition; // 提示点中的位置(单位:采样帧)
const char * strLabel; // 标记的标签,从文件中读取
};
  • 如果之后您打算引用标签,则一定要复制strLabel 字符串成员的内容,因为在回调返回后,指针可能会被作废。
参见
快速入门示例集成——事件

通知延迟

目前当缓冲区向下传递到硬件时发送通知。这意味着,发送通知与遇到标记之间存在一定延时。这样在真正播放与标记关联的声音之前,应用程序有足够的时间来收集并处理标记中的信息。

注意这个延时取决于平台。

回调线程

Marker 回调和 End of Event 回调从声音引擎的主线程完成。这意味着您的应用程序应从通知中收集它所需的全部信息,并立即返回。如果需要进行任何处理,则应当从通知中复制相关信息后,使用单独的线程来执行。

如果应用程序占用线程太久,声音引擎可能掉入 underrun(欠载运行)状态,导致输出停止播放。

注解
在回调函数返回后,声音引擎将释放被引用的数据,因此应复制来自回调函数的标签字符串。

Wwise 捕获日志和标记

Wwise Profiler 可以显示来自声音引擎的标记通知。为此,必须确保启用 Profiler Settings 对话框中的 Markers Notification Data 选项。当播放到达标记处并已请求通知时,Capture Log 中将在新的一行中显示相关信息。注意,如果需要可以过滤掉这些通知,方法是取消选择 Capture Log Filter 对话框中的 Markers Notification Data 复选框。

参见
集成详情——事件