マーカーの統合

イントロダクション

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

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

info

Note: 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 文字列メンバの内容を後ほど参照する場合は、これを必ずコピーするようにしてください。

参照:: クイックスタートサンプル統合 - イベント

通知の遅延

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

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

コールバックスレッド

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

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

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

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

参照:: 統合の詳細 - イベント

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

サポートは必要ですか？

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

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

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

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

Wwiseからはじめよう

Wwise SDK 2017.1.9