警告：あなたのメジャーリリース ( 2024.1.1.8691 ) に該当する最新ドキュメンテーションが表示されています。特定バージョンのドキュメンテーションにアクセスするには、Audiokinetic Launcherでオフラインドキュメンテーションをダウンロードし、Wwise AuthoringのOffline Documentationオプションにチェックを入れてください。

Wwise SDK 2024.1.1

イントロダクション

マーカーとは、.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)

ソースプラグインの活用

ソースプラグインでマーカー通知を生成することもできます。

ソースプラグイン内で、 AK::IAkPluginServiceMarkers::CreateMarkerNotificationService() を使って AK::IAkPluginServiceMarkers::IAkMarkerNotificationService のインスタンスを作成できます。次に、 AK::IAkPluginServiceMarkers::IAkMarkerNotificationService::SubmitMarkerNotifications() を通じて、 AkAudioMarker 構造体を使用してゲームにマーカー通知が送信されます。

struct AkAudioMarker
{
    AkUInt32        dwIdentifier;       ///< Identifier.
    AkUInt32        dwPosition;         ///< Position in the audio data in sample frames.
    const char*     strLabel;           ///< Label of the marker taken from the file.
    AkUInt32        dwLabelSize;        ///< Length of label read the from the file + terminating null character.
};

Marker Generatorソースプラグインの例

以下に、マーカー通知を生成するソースプラグインの例を示します。

class MyMarkerGeneratorSourcePlugin : public IAkSourcePlugin
{
private:
    IAkSourcePluginContext* m_pSourcePluginContext{};
    IAkPluginServiceMarkers::IAkMarkerNotificationService* m_pMarkerNotificationService{};
    AkUInt32 m_uElapsedSamples{};
 
    static constexpr AkUInt32 g_uPayloadSize{ 64 };
    char m_Payload[g_uPayloadSize]{};
 
    // ...
 
public:
    AKRESULT Init(
        IAkPluginMemAlloc *         in_pAllocator,                  ///< Interface to the memory allocator to be used by the plug-in
        IAkSourcePluginContext *    in_pSourcePluginContext,        ///< Interface to the source plug-in's context
        IAkPluginParam *            in_pParams,                     ///< Interface to the plug-in parameters
        AkAudioFormat &             io_rFormat                      ///< Audio format of the output data to be produced by the plug-in (mono native by default)
        ) override
    {
        m_pSourcePluginContext = in_pSourcePluginContext;
        m_pMarkerNotificationService = AK_GET_PLUGIN_SERVICE_MARKERS(m_pSourcePluginContext)->CreateMarkerNotificationService(m_pSourcePluginContext);
        return AK_Success;
    }
 
    AKRESULT Term(
        IAkPluginMemAlloc * in_pAllocator                           ///< Interface to memory allocator to be used by the plug-in
        ) override
    {
        AK_GET_PLUGIN_SERVICE_MARKERS(m_pSourcePluginContext)->TerminateMarkerNotificationService(m_pMarkerNotificationService);
        return AK_Success;
    }
 
    void Execute(
        AkAudioBuffer *             io_pBuffer                      ///< In/Out audio buffer data structure (in-place processing)
        ) override
    {
        static constexpr AkUInt32 uNumMarkers{ 1 };
 
        AkAudioMarker markers[uNumMarkers];
        markers[0].dwIdentifier = 'mrkr';
        markers[0].dwPosition = m_uElapsedSamples;
        markers[0].strLabel = m_Payload;
        markers[0].dwLabelSize = g_uPayloadSize;
 
        const AkUInt32 offsetsInBuffer[uNumMarkers]{ 0 };
 
        m_pMarkerNotificationService->SubmitMarkerNotifications(markers, offsetsInBuffer, uNumMarkers);
 
        // advance the position of the markers
        m_uElapsedSamples += io_pBuffer->MaxFrames();
    }
 
    // ...
};

マーカー通知の使用法

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

再生イベントをポストする時、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 (null-terminated)
    AkUInt32    uLabelSize;         // Size of the label string (including the terminating null character)
};

コールバックのリターン後はポインタが無効になるため、strLabel 文字列メンバの内容を後ほど参照する場合は、これを必ずコピーするようにしてください。

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

通知の遅延

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

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

コールバックスレッド

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

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

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

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

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

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

AkAudioMarker

Defines the parameters of a marker.

Definition: AkAudioMarker.h:16

AkMarkerCallbackInfo::strLabel

const char * strLabel

Label of the marker (null-terminated)

Definition: AkCallback.h:124

AkEventCallbackInfo

Definition: AkCallback.h:100

AkAudioMarker::dwIdentifier

AkUInt32 dwIdentifier

Identifier.

Definition: AkAudioMarker.h:17

AkMarkerCallbackInfo

Definition: AkCallback.h:121

AkCallbackInfo

Definition: AkCallback.h:90

AkGameObjectID

AkUInt64 AkGameObjectID

Game object ID

Definition: AkTypes.h:60

AKRESULT

Standard function call result.

Definition: AkTypes.h:134

AkAudioMarker::dwLabelSize

AkUInt32 dwLabelSize

Length of label read the from the file + terminating null character.

Definition: AkAudioMarker.h:20

AkCallbackType

Type of callback. Used as a bitfield in methods AK::SoundEngine::PostEvent() and AK::SoundEngine::Dyn...

Definition: AkCallback.h:48

AK::Comm::Init

AKSOUNDENGINE_API AKRESULT Init(const AkCommSettings &in_settings)

NULL

#define NULL

Definition: AkTypes.h:46

AK_Success

@ AK_Success

The operation was successful.

Definition: AkTypes.h:136

AK::Comm::Term

AKSOUNDENGINE_API void Term()

AkMarkerCallbackInfo::uIdentifier

AkUInt32 uIdentifier

Cue point identifier

Definition: AkCallback.h:122

AkUniqueID

AkUInt32 AkUniqueID

Unique 32-bit ID

Definition: AkTypes.h:52

AkMarkerCallbackInfo::uLabelSize

AkUInt32 uLabelSize

Size of the label string (including the terminating null character)

Definition: AkCallback.h:125

AkMarkerCallbackInfo::uPosition

AkUInt32 uPosition

Position in the cue point (unit: sample frames)

Definition: AkCallback.h:123

AK::TempAlloc::Type

Type

IDs of temporary memory pools used by the sound engine.

Definition: AkTempAllocDefs.h:63

AK::ProfilingID::Num

@ Num

Definition: AkProfilingID.h:83

AkCallbackFunc

void(* AkCallbackFunc)(AkCallbackType in_eType, AkCallbackInfo *in_pCallbackInfo)

Definition: AkCallback.h:272

AkAudioMarker::strLabel

const char * strLabel

Label of the marker taken from the file.

Definition: AkAudioMarker.h:19

AK_GET_PLUGIN_SERVICE_MARKERS

#define AK_GET_PLUGIN_SERVICE_MARKERS(plugin_ctx)

Definition: IAkPlugin.h:1911

AkUInt32

uint32_t AkUInt32

Unsigned 32-bit integer

Definition: AkNumeralTypes.h:38

AkAudioBuffer

Definition: AkCommonDefs.h:321

AkAudioMarker::dwPosition

AkUInt32 dwPosition

Position in the audio data in sample frames.

Definition: AkAudioMarker.h:18

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)

AkAudioFormat

Defines the parameters of an audio buffer format.

Definition: AkCommonDefs.h:60

AkPlayingID

AkUInt32 AkPlayingID

Playing ID

Definition: AkTypes.h:55

AkAudioBuffer::MaxFrames

AkForceInline AkUInt16 MaxFrames() const

Definition: AkCommonDefs.h:500