集成 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，因为这些标志采取按位异或运算。
AkPlayingID AK::SoundEngine::PostEvent( 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 的回调信息结构。 struct AkMarkerCallbackInfo : public AkEventCallbackInfo { 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 复选框。
- 参见:
- 集成详情——事件