バージョン
menu_open
Wwise SDK 2021.1.14
マーカーの統合

イントロダクション

マーカーとは、.wav ファイルに挿入される識別子のことで、波形でポジションをタグ付けするのに使用されるものです。通常これらのマーカーは、SoundForge®、Adobe® Audition®や CueTool などのような波形編集ソフトで作成されます。

アプリケーションは、これらのマーカーを使用し、再生中に特定のポジションに達した時に通知を受けることができます。例えば、この情報を使用して、コンテンツの描画と再生中のオーディオを同期させたり、ランダムコンテナがどのファイルを再生しているかを確認し、ゲーム内に適切な字幕が表示されるようにすることができます。

注釈: Wwiseのマーカー通知の使用は通常、リップシンクや字幕ソリューションを組み込むのに最も効率の良い方法です。

.wav ファイル形式での作業

チャンクは、キューポイントを格納するために使用されるデータ格納ユニットです。キューポイントとは、.wav 形式ファイルにフラグ設定される重要ポイントのことです。

キューチャンク

キューチャンク形式は、.wav ファイル内の重要ポイントを示すマーカーのポジションを格納するために使用されます。

Offset Bytes Description Value
0x00 4 Chunk ID "cue " (0x63756520)
0x04 4 Chunk Data Size Depends on the number of cue points
0x08 4 Num Cue Points Number of cue points in list
0x0c Cue Points
#define CueID 'cue ' /* chunk ID for cue chunk */
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;

リストチャンク

リストチャンクは、.wav ファイル内のコンテナのことで、サブチャンクを含んでいます。キューポイントに関連付けられたラベル、メモやテキストを格納するために関連データリストチャンク（adtl）形式が使用されます。

Offset Bytes Description Value
0x00 4 Chunk ID "list" (0x6C696E74)
0x04 4 Chunk Data Size Depends on contained sub-chunks
0x08 4 Type ID "adtl" (0x6164746C)
0x0c SubChunks start here

ラベルサブチャンク

ラベルサブチャンク形式は、キューポイントに関連付けられた文字列を格納するために使用されます。これは、関連データリストチャンク内に含まれます。

Offset Bytes Description Value
0x00 4 Chunk ID "labl" (0x6C61626C)
0x04 4 Chunk Data Size Depends on size of text
0x08 4 Cue Point ID Refers to cue chunk dwIdentifier
0x0c Label (variable-size text)

マーカー通知の使用法

以下は、アプリケーションが、マーカー通知を受信するように設定する方法です：

  • 再生イベントをポストする時、in_uiFlags に、AK_Marker フラグを追加する必要があります。フラグはビットごとの排他的論理和であるため、イベント終了通知を受信したい場合は、AK_EndOfEvent | AK_Marker を使用する必要があります。
AkPlayingID AK::SoundEngine::PostEvent(
AkUniqueID in_eventID, // Unique ID of the event
AkGameObjectID in_gameObjectID, // Associated game object ID
AkUInt32 in_uFlags = 0, // Bitmask: see AkCallbackType
AkCallbackFunc in_pfnCallback = NULL, // Callback function
void * in_pCookie = NULL // Callback cookie that will be sent to the callback function
// along with additional information
);
  • コールバック関数は、次の形式でなければなりません：
static void MarkersCallback(
AkCallbackType in_eType, // Type of callback reason, in this case AK_Marker on
// reception of a marker event.
AkCallbackInfo* in_pCallbackInfo // Pointer to callback information structure, in this case
// AkMarkerCallbackInfo*.
)
  • コールバック関数が呼び出された時、まずどのタイプの通知が渡されたのか確認する必要があります。例えば、AK_Marker 通知の処理のみを行いたい場合に、他のイベントタイプを受信した時には、リターンする必要があります。
  • 通知の種類に基づいて、適切な情報構造型に in_pCallbackInfo を型キャストすることができます。AK_Marker 通知の場合は、AkMarkerCallbackInfoとなります。
// Callback information structure corresponding to AK_Marker.
struct AkMarkerCallbackInfo : public AkEventCallbackInfo
{
AkUInt32 uIdentifier; // Cue point identifier
AkUInt32 uPosition; // Position in the cue point (unit: sample frames)
const char * strLabel; // Label of the marker, read from the file
};
  • コールバックのリターン後はポインタが無効になるため、strLabel 文字列メンバの内容を後ほど参照する場合は、これを必ずコピーするようにしてください。
参照
クイックスタートサンプル統合 - Event（イベント）

通知の遅延

通知は、バッファがハードウェアに引き継がれた時に送信されます。これはつまり、通知送信とマーカー検出の間に一定の遅延があることを意味します。この遅延により、アプリケーションは、マーカーに関する情報を収集し、マーカーと関連付けられたサウンドが実際に再生される前にこれを処理する余裕を得ることができます。

この遅延はプラットフォーム依存であることにご注意ください。

コールバックスレッド

マーカーへのコールバックおよびイベント終了通知へのコールバックは、サウンドエンジンのメインスレッドから実行されます。つまり、アプリケーションは、必要な情報を通知から収集し、即時に返さなければなりません。なんらかの処理が行われる必要がある場合は、通知から関連情報をコピー後、別のスレッドで実行されるべきです。

アプリケーションがスレッドを長く保持しすぎると、サウンドエンジンがアンダーラン状態に陥り、出力が再生を停止する可能性があります。

覚え書き
コールバック関数がリターンされると、サウンドエンジンは関連データを解放するので、コールバック関数のラベル文字列をコピーしておく必要があります。

Wwiseキャプチャログとマーカー

Wwise プロファイラで、サウンドエンジンからのマーカー通知を表示することができます。このためには、Profiler Settings ダイアログの Markers Notification Data オプションが有効になっている必要があります。マーカーに到達し、通知が要求されると、Capture Log に新しい行が表示されます。Capture Log Filter ダイアログの Markers Notification Data チェックボックスをクリアすることにより、これらの通知をフィルタリングすることができます。

参照
統合の詳細 - Event（イベント）
AkMarkerCallbackInfo::strLabel
const char * strLabel
Label of the marker, read from the file
Definition: AkCallback.h:120
AkGameObjectID
AkUInt64 AkGameObjectID
Game object ID
Definition: AkTypes.h:70
AkCallbackType
AkCallbackType
Type of callback. Used as a bitfield in methods AK::SoundEngine::PostEvent() and AK::SoundEngine::Dyn...
Definition: AkCallback.h:49
NULL
#define NULL
Definition: AkTypes.h:47
AkMarkerCallbackInfo::uIdentifier
AkUInt32 uIdentifier
Cue point identifier
Definition: AkCallback.h:118
AkUniqueID
AkUInt32 AkUniqueID
Unique 32-bit ID
Definition: AkTypes.h:62
AkMarkerCallbackInfo::uPosition
AkUInt32 uPosition
Position in the cue point (unit: sample frames)
Definition: AkCallback.h:119
AkCallbackFunc
void(* AkCallbackFunc)(AkCallbackType in_eType, AkCallbackInfo *in_pCallbackInfo)
Definition: AkCallback.h:267
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer
Definition: AkTypes.h:59
AK::SoundEngine::PostEvent
AKSOUNDENGINE_API AkPlayingID PostEvent(AkUniqueID in_eventID, AkGameObjectID in_gameObjectID, AkUInt32 in_uFlags=0, AkCallbackFunc in_pfnCallback=NULL, void *in_pCookie=NULL, AkUInt32 in_cExternals=0, AkExternalSourceInfo *in_pExternalSources=NULL, AkPlayingID in_PlayingID=AK_INVALID_PLAYING_ID)
AkPlayingID
AkUInt32 AkPlayingID
Playing ID
Definition: AkTypes.h:65

このページはお役に立ちましたか？

サポートは必要ですか？

ご質問や問題、ご不明点はございますか？お気軽にお問い合わせください。

サポートページをご確認ください

あなたのプロジェクトについて教えてください。ご不明な点はありませんか。

プロジェクトを登録していただくことで、ご利用開始のサポートをいたします。

Wwiseからはじめよう