Wwise SDK 2024.1.4

Wwise Authoring APIは、Wwiseプロジェクトの最も重要な要素を取得するための包括的なクエリシステムを提供します。具体的には、プロジェクト内の任意のオブジェクトを取得できます。

クエリシステムは ak.wwise.core.object.get 関数に組み込まれています。詳細については、参照ドキュメントを参照してください。

以下の2種類のクエリがあります:

WAQL: 'waql'文でWwise Authoring Query Languageを使い、テキストクエリを定義します。 Wwise Authoring Query Language (WAQL) を使用すると WAQLを使ってみるを参照してください。
JSON: JSONフォーマットの'from'文と'transform'文を使い、クエリを定義します。

info

注釈: JSONクエリフォーマットでなくWAQLを使うことを推奨します。WAQLの方が機能性に優れ、範囲も広く、エラー対応が良く、使い方も簡単です。

WAQLクエリ

WAQLクエリは、固有のテキスト1行で、クエリ全体を指定できます。

check_circle

Tip: WAQLクエリをテストするために、Wwiseオーサリング内で直接使うこともできます。あなたのWAAPIプログラムやスクリプトにクエリを実装する前に、クエリ構文や結果を確認するのに特に便利です。例えば、以下のWAQLクエリをWwiseのツールバーやリストビューのサーチフィールドに入力してみてください:

$ from type Event

WAQLについて、さらに知りたい場合は:

JSONクエリ

info

注釈: JSONクエリは推奨されません。代わりにWAQLクエリを使うことを推奨します。 Wwise Authoring Query Language (WAQL) を使用すると WAQLを使ってみるを参照してください。

JSONクエリは、2つの部分で構成されています:

from：クエリの開始点を指定します。これはデータの取得元です。
transform：オブジェクトに適用する一連の変換を指定します。変換は順番に追加できます。

さらに、クエリには次のようなオプションがあります：

return：オブジェクトから何を返すかを指定します。指定しない場合、デフォルトは['id', 'name']です。
platform：クエリに使用するプラットフォームを指定します。指定しない場合、デフォルトは現在のプラットフォームです。

from

from 文は、クエリを開始するためのいくつかのポイントを提供します。

id：オブジェクトID（GUID）の配列を指定します。IDをすでに持っているとき、オブジェクトを検索するのに便利です。
name： タイプでqualifyしたオブジェクト名の配列を、type:nameという形式で指定します。サポートされるのは、名前がグローバルに固有なオブジェクトタイプのみです。使用可能なタイプについては、 Wwiseオブジェクトリファレンスを参照してください。
search：Wwiseオブジェクトの名前と注釈で、検索するテキストを指定します。これは、Wwise検索と同じ検索エンジンを使用します。
path：検索するパスの配列を指定します。パスは絶対パスでなければならず、物理フォルダ名と同じカテゴリ名で始まる必要があります。. 例： \Actor-Mixer Hierarchy\Default Work Unit\MySound。
ofType：Wwiseオブジェクトタイプの配列を指定します。これは、すべてのGame Parameter を取得するなど、特定オブジェクトタイプのすべてのオブジェクトを取得する場合に便利です。使用可能なタイプについては、 Wwiseオブジェクトリファレンスを参照してください。

transform

transform 文には、選択中のオブジェクトを変換するために使用できるいくつかの変換関数が用意されています。最初の変換は、 from 文によって選択されたオブジェクトに適用されます。他の変換は、前の変換の結果に適用されます。

複数の変換を順番に追加できます。

select parent： すべてのオブジェクトに対して、オブジェクトの親を選択します。
select children： すべてのオブジェクトに対して、オブジェクトの子のリストを選択します
select descendants： すべてのオブジェクトに対して、すべての子を再帰的に選択します。
select ancestors： すべてのオブジェクトに対して、すべての親を再帰的に選択します。
select referencesTo: すべてのオブジェクトに関して、そのオブジェクトを参照するすべてのオブジェクトを選択します。
where： 以前のイテレータの結果をフィルタリングすることができます。可能な基準は次のとおりです：
- name:contains：オブジェクト名の大文字小文字を区別しないテキストの検索。
- name:matches：オブジェクト名の大文字と小文字を区別しない正規表現の検索。
- type:isIn：特定オブジェクトタイプのオブジェクトのみを保持することで、以前のイテレータの結果をフィルタリングします。オブジェクトタイプのリストを見るには、 Wwiseオブジェクトリファレンスを参照してください。
- category:isIn: 特定オブジェクトカテゴリのオブジェクトのみを保持することで、以前のイテレータの結果をフィルタリングします。
distinct: ユニークオブジェクトのみを保持することで、以前のイテレータの結果をフィルタリングします。

Returnオプション

return 式で、Wwiseオブジェクトの要素のうち、どれを返すのかを指定します。任意の数の要素を返すことができます。

return式に以下を入れることができます:

コアプロパティ: Wwise Authoring Query Language (WAQL) リファレンスの OBJECT_EXPRESSION 、 VALUE_EXPRESSION を参照してください。
オブジェクトプロパティとリファレンス: Wwiseオブジェクトリファレンスを参照してください。

プロパティ名やリファレンス名のために使うことができるプレフィックスが、2つ存在します:

'@PROPERTYNAME': オブジェクトに直接設定されている値を返します。オーバーライドシステムを無視し、場合によっては使われていないhiddenの値を返します。
'@@PROPERTYNAME': オーバーライドシステムによって解決（resolve）された値を返します。親から継承した値を返したり、もしオブジェクトがプロパティをオーバーライドする場合は、オブジェクトの値を直接返したりします。

プレフィックスを使わないと、オーバーライドシステムによって解決（resolve）された値を返します。これは、 @@ プレフィックスを使うことに相当します。プレフィックスを使わないことを推奨します。

例：

'volume', 'Volume', '@Volume', '@@Volume': オブジェクトのボリュームを返します。ボリュームはオーバーライドできないので、これらはすべて等しいです。プロパティ名は、大文字小文字の区別がないことに注意してください。
'OutputBus', 'outputbus', '@@OutputBus': オーバーライドシステムによって解決（resolve）されたOutput Busを返します。これが、再生用に使われている値です。リファレンス名は、大文字小文字の区別がないことに注意してください。
'@OutputBus': オブジェクトに直接設定されているOutput Busを返します。これは、このオブジェクトのWork Unitで永続している値でもあります。オブジェクトのOverride Parentオプションがチェックされていない場合は、この値が使われない可能性があり、hiddenの場合があります。

式の解が有効な参照先であれば、さらにクエリをかけ、参照オブジェクトのプロパティを求めることができます。例えば、Soundオブジェクトのリファレンス'UserAuxSend0'が既存のAuxiliary Busを参照している場合は、ドット ('.') のあとにプロパティ記述子を付けて、このAuxiliary Busのプロパティをクエリすることができます。つまり、参照先のAuxiliary BusのAttenuationのクエリは、単純に'UserAuxSend0.Attenuation'となります。

例：

OutputBus.name: アウトプットバス名を返します。
parent.name: 親オブジェクト名を返します。
parent.parent.type: 祖父母オブジェクトのタイプを返します。
OutputBus.Volume: アウトプットバスのボリュームを返します。
OutputBus.Attenuation.name: アウトプットバス名を返します。
Attenuation.path: アウトプットバスのパスを返します。
Effects.first.effect.id: returns the ID of the first Effect.

オブジェクトによっては、ランダム化（randomization）などの特定機能が設定されたプロパティがあります。これらの機能に関連する値を取得するには、そのプロパティに紐づけられた特別なオブジェクトを、数式のようなアクセサー（accessors）を通してクエリできます。例えば、ランダム化機能は、オブジェクトの特定の機能にリンクしたModifierオブジェクトによって記述されています。このオブジェクトは 'randomizer("PropertyName")' でクエリすることができ、ここでPropertyNameには、プロパティの名前、例えば 'Volume'などを入れます。アクセサーが有効な参照先を提供すれば、前述の方法で、返されたオブジェクトをさらにクエリできます。例えば、Volumeランダマイザーの 'Max' プロパティを取得するには、'randomizer("Volume").@Max' とします。

可能なアクセサーのリストを以下に示します:

ランダマイザー（randomizer）

return 式の項目が互換性がないか、返されたオブジェクトに存在しない場合、結果の一部にはなりません。

可能なアクセサーのすべてのリストについては、 ak.wwise.core.object.get を参照してください。
使用可能なプロパティと参照の詳細については、 Wwiseオブジェクトリファレンスを参照してください。

その他のオプション

ak.wwise.core.object.get ファンクションやその他のファンクションは、オプションオブジェクトを使いますが、以下が定義されます:

return式（上記セクションを参照）
プラットフォーム: プラットフォームのID (guid) または名前。
ランゲージ: ランゲージのID (guid) または名前。

一部のアクセサーはオプションに左右されます。例えば、プロパティ値やレファレンス値を取得するときに、アンリンクされた値を入手するためにプラットフォームを指定できます。プラットフォームが指定されない場合は、現在のプラットフォームが使われます。ランゲージ特有の情報、例えばサウンドオブジェクトのオーディオソースデータを取得するために、ランゲージを指定することもできます。指定されない場合は、現在のランゲージが使われます。

例

初期化についてはプロジェクトコードを参照してください。

ak.wwise.core.object.get にほかの例があります。

オブジェクトのリストのID、名前、音声ボリュームをリターンします。

from waapi import WaapiClient
import pprint
 
# Connect (default URL)
client = WaapiClient()
 
# Return two objects
args = {
    'waql': '$ "\\Audio Devices\\Default Work Unit\\System", "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}"'
}
 
options = {
    'return': ['id', 'name', 'Volume']
}
result = client.call("ak.wwise.core.object.get", args, options=options)
pprint.pprint(result)
 
# Disconnect
client.disconnect()

'My' で始まるActor-Mixer Hierarchy のすべてのオブジェクトのIDと名前を正規表現で返します。

from waapi import WaapiClient
import pprint
 
# Connect (default URL)
client = WaapiClient()
 
# Return all objects under the actor-mixer hierarchy with a name that starts with "My"
args = {
    'waql': '$ "\Actor-Mixer Hierarchy" select descendants where name = /^My/'
}
 
options = {
    'return': ['name', 'id']
}
result = client.call("ak.wwise.core.object.get", args, options=options)
pprint.pprint(result)
 
# Disconnect
client.disconnect()

WAQLについてさらに詳しく知るには、 Wwise Authoring Query Language (WAQL) を使用するを参照してください

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

サポートは必要ですか？

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

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

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

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

Wwiseからはじめよう

Wwise SDK

Wwise Project のクエリ