WaveSoundBuffer¶
WaveSoundBuffer クラスは、PCMの再生を管理するクラスです。
WaveSoundBuffer クラスでは、ループチューナ で作成した .sli ファイルを読み込み、処理することができます。詳しくはループチューナの説明をご覧ください。
メンバー一覧¶
コンストラクタ¶
プロパティ¶
- position
- paused
- totalTime
- looping
- volume
- volume2
- status
- bits
- channels
- filters
- flags
- frequency
- globalFocusMode
- globalVolume
- labels
- pan
- posX
- posY
- posZ
- samplePosition
- useVisBuffer
- use3D
- minDistance
- maxDistance
- rolloffFactor
- dopplerFactor
- attenuationModel
メソッド¶
- open
- play
- stop
- fade
- stopFade
- freeDirectSound
- getVisBuffer
- getSoundLevel
- getSoundSpectrum
- getVowel
- setPos
- set3DPosition
- set3DVelocity
- set3DConeDirection
- set3DCone
- setGainQueryCallback
イベント¶
WaveSoundBuffer¶
コンストラクタ
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
owner |
|
イベントの発生先を指定します。 |
解説
WaveSoundBuffer オブジェクトの構築
WaveSoundBuffer クラスのオブジェクトを構築します。
イベントが発生すると owner で指定したオブジェクトの action メソッドを呼び出します。owner に null を指定すると action メソッドは呼ばれません。通常は Window クラスのオブジェクトを owner に指定します。
position¶
プロパティ \ アクセス: r/w
解説
再生位置
再生位置を ms 単位で表します。値を設定するとその位置に移動します。
paused¶
プロパティ \ アクセス: r/w
解説
一時停止状態かどうか
一時停止状態かどうかを表します。値を設定することもできます。
真の場合は一時停止状態です。
totalTime¶
プロパティ \ アクセス: r
解説
メディアの再生時間
メディアの総再生時間を ms 単位で表します。
looping¶
プロパティ \ アクセス: r/w
解説
ループ再生を行うかどうか
ループ再生を行うかどうかを表します。値を設定することもできます。
真を指定するとループ再生がされます。
偽を指定しても、再生しているメディアにループ情報があれば、ループ情報が利用されます。
volume¶
プロパティ \ アクセス: r/w
解説
音量
再生する音量を表します。値を設定することもできます。
0 ~ 100000 の数値で指定し、 0 が完全ミュート、100000 が 100% の音量となります。
volume2¶
プロパティ \ アクセス: r/w
解説
第2音量
再生する音量を表します。値を設定することができます。
WaveSoundBuffer.volume プロパティと違うのは、このプロパティは WaveSoundBuffer.fade メソッドでも変化しないということです。
最終的な音量は、volume プロパティとこのプロパティの積で決定されます。volume プロパティが 100000 ( 100% ) で volume2 プロパティも 100000 ( 100% ) ならば 100% × 100% = 100% で 100% の音量で再生されます。volume プロパティが 50000 ( 50% ) で volume2 プロパティが 75000 ( 75% ) ならば 50% × 75% = 37.5% で 37.5 % の音量で再生されます。
status¶
プロパティ \ アクセス: r
解説
ステータス
現在の状態を表します。
状態は文字列で表され、以下の値をとります。
"**unload**" : メディアが開かれてない
"**play**" : メディアは再生中である
"**stop**" : メディアは停止中である
bits¶
プロパティ \ アクセス: r
解説
量子化ビット数
現在再生中のサウンドの量子化ビット数を表します。 CD と同じ量子化ビット数の場合は 16 になります。 メディアが開かれていない状態では正常な値を返さない可能性があります。
channels¶
プロパティ \ アクセス: r
解説
チャンネル数
現在再生中のサウンドのチャンネル数を表します。 モノラルの場合は 1、ステレオの場合は 2 になります。 メディアが開かれていない状態では正常な値を返さない可能性があります。
filters¶
プロパティ \ アクセス: r
解説
フィルタ配列
インサーションフィルタオブジェクトを保持している配列(Arrayクラスのインスタンス)です。 この配列にフィルタオブジェクトを登録することにより、再生中にリアルタイムで音声に対して様々な効果をかけることができます。 フィルタ配列への変更が反映されるのは、WaveSoundBuffer.openメソッドが実行された時だけです。 それまでは、この配列への変更を行っても反映はされません。 例:
var buf = new WaveSoundBuffer(window);
(略)
buf.filters.clear();
// フィルタ配列をクリア
buf.filters.add(new WaveSoundBuffer.PhaseVocoder());
// PhaseVocoderフィルタを追加
buf.filters[0].time = 0.5;
// 倍速再生
flags¶
プロパティ \ アクセス: r
解説
フラグ
フラグを表すオブジェクトを得ることができます。 このオブジェクトには 0 ~ 15 のプロパティがあり、それぞれ各フラグの値を表しています。 プロパティには間接メンバ選択演算子 ('[ ]' 演算子) を用いてアクセスすることができます。 これらのプロパティには値を設定することもできます。 値は 0 ~ 9999 の範囲であり、これを下回ったり、上回ることはできません。 このオブジェクトの count プロパティは常に 16 を返します。 このオブジェクトには reset メソッドがあり、このメソッドを実行すると、全てのフラグが 0 にリセットされます。 メディアを開いていない場合は、このオブジェクトのプロパティに値を設定しても無視されます。 このオブジェクトは一見配列オブジェクトにも見えますが、いわゆるTJSの配列オブジェクト('Array' クラスのオブジェクト) ではありません。 フラグは WaveSoundBuffer.open メソッドで全て 0 にリセットされます。 例:
var buf = new WaveSoundBuffer(window);
(略)
buf.flags.reset();
// 全てのフラグを 0 にリセット
var cnt = buf.flags.count;
// cnt には 16 が入る
buf.flags[4] = 34;
// 4番のフラグに34を代入
frequency¶
プロパティ \ アクセス: r/w
解説
サンプリング周波数
現在再生中のサウンドのサンプリング周波数を表します。 値を設定することもできます。 CD と同じサンプリング周波数の場合は 44100 になります。 メディアが開かれていない状態では正常な値を返さない可能性があります。 値を設定すると、その周波数で再生します。
globalFocusMode¶
プロパティ \ アクセス: r/w
解説
フォーカスモード
フォーカスモードを表します。 値を設定することもできます。 フォーカスモードは、アプリケーションが最小化したときや非アクティブになったときにミュートするモードです。
- sgfmNeverMuteを指定すると、アプリケーションがどのような状態でもミュートはしません。
- sgfmMuteOnMinimizeを指定すると、アプリケーションが最小化時にミュートします。
- sgfmMuteOnDeactivateを指定すると、アプリケーションが非アクティブ化したときにミュートします。
このプロパティは WaveSoundBuffer クラス上にしか存在しません (WaveSoundBufferから作られたオブジェクト上にこのプロパティはありません)。 使用する際は WaveSoundBuffer.globalFocusMode としてください。
globalVolume¶
プロパティ \ アクセス: r/w
解説
大域音量
大域音量 (マスターボリューム)を表します。 値を設定することもできます。 この音量は、すべての WaveSoundBuffer に影響します。 0 ~ 100000 の数値で指定し、 0 が完全ミュート、100000 が 100% の音量となります。 デフォルトの値は 100000 です。 このプロパティは WaveSoundBuffer クラス上にしか存在しません (WaveSoundBufferから作られたオブジェクト上にこのプロパティはありません)。 使用する際は WaveSoundBuffer.globalVolume としてください。
labels¶
プロパティ \ アクセス: r
解説
ラベル
ラベルを表すオブジェクトを得ることができます。 このオブジェクトは辞書配列で、それぞれ、ループ情報中のラベルの名前をメンバ名とした要素が入っています。 それぞれの要素も辞書配列で、name メンバはラベルの名前を表し、position メンバはミリ秒単位でのラベルの位置を表し、samplePosition はサンプル数単位でのラベルの位置を表しています。 この辞書配列は読み出し専用であると考えてください。 値を代入したり、新しいメンバを作成しても反映されることはありません。 例:
var buf = new WaveSoundBuffer(window);
(略)
debug.message(buf.labels['start'].position);
// 'start' というラベル名の位置をミリ秒単位で
debug.message(buf.labels['start'].samplePosition);
// 'start' というラベル名の位置をサンプル数単位で
pan¶
プロパティ \ アクセス: r/w
解説
パン
パン (音像位置) を表します。 値を設定することもできます。 音の聞こえる左右の位置を指定することができます。 -100000 ~ 0 ~ 100000 の数値で指定し、 -100000 が 完全に左、0 が中央、100000 が完全に右になります。
posX¶
プロパティ \ アクセス: r/w
型: Real
解説
3D 音源位置 ( X 座標 )
3D サウンド再生時の音源位置の X 座標を取得 / 設定します。
WaveSoundBuffer.setPos で 3 軸まとめて設定することもできます。
posY¶
プロパティ \ アクセス: r/w
型: Real
解説
3D 音源位置 ( Y 座標 )
3D サウンド再生時の音源位置の Y 座標を取得 / 設定します。
posZ¶
プロパティ \ アクセス: r/w
型: Real
解説
3D 音源位置 ( Z 座標 )
3D サウンド再生時の音源位置の Z 座標を取得 / 設定します。
samplePosition¶
プロパティ \ アクセス: r/w
解説
再生位置
再生位置をサンプル数単位で表します。 値を設定するとその位置に移動します。
useVisBuffer¶
プロパティ \ アクセス: r/w
解説
視覚化用バッファを使用するかどうか
視覚化用バッファを使用するかどうか表します。 値を設定することもできます。 真を指定すると視覚化用バッファが利用可能になり、WaveSoundBuffer.getVisBuffer メソッドが利用可能になります。 デフォルトでは偽になっています。 真を指定すると偽を指定したときよりも多くのメモリと CPU 時間を消費するようになるので注意してください。
use3D¶
プロパティ \ アクセス: r/w
解説
3D 定位 ( スペーシャライザ ) の有効/無効
この WaveSoundBuffer に対して miniaudio ベースの 3D 定位 ( 距離減衰・パンニング・ ドップラー・指向性コーン ) を有効にするかどうかを表します。有効時は set3DPosition 等で音源位置を与えます。
minDistance¶
プロパティ \ アクセス: r/w
解説
最小距離
この距離以内では距離減衰しません ( 音量最大 )。
関連: WaveSoundBuffer.maxDistance
maxDistance¶
プロパティ \ アクセス: r/w
解説
最大距離
この距離を超えると距離減衰が頭打ちになります。
関連: WaveSoundBuffer.minDistance
rolloffFactor¶
プロパティ \ アクセス: r/w
解説
距離減衰の強さ
距離減衰の強さ ( ロールオフ係数 ) です。大きいほど急激に減衰します。
dopplerFactor¶
プロパティ \ アクセス: r/w
解説
ドップラー効果の強度
ドップラー効果の強度です ( 0 で無効、1 で標準 )。
関連: WaveSoundBuffer.set3DVelocity
attenuationModel¶
プロパティ \ アクセス: r/w
解説
距離減衰モデル
距離減衰モデルを表す整数です。0 = なし、1 = 逆二乗 ( inverse )、2 = 線形 ( linear )、 3 = 指数 ( exponential ) に対応します。
open¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
storage |
|
再生したいストレージを指定します。 |
解説
メディアを開く
指定されたメディアを開きます。このメソッドは再生を開始しません。
指定されたストレージ名に .sli を付加したファイル名があれば、サウンドループ情報として読み込みます。
play¶
メソッド
解説
メディアを再生する
メディアの再生を開始します。
stop¶
メソッド
解説
メディアを停止する
メディアを停止します。
fade¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
to |
|
到達させる音量を指定します。 音量の指定については WaveSoundBuffer.volume プロパティを参照して ください。 |
time |
|
フェードにかける時間を ms 単位で指定します。 |
delay |
0 |
フェード開始までの待ち時間を ms 単位で指定します。 |
解説
フェードを開始する
フェード ( 連続的な音量の変化 ) を開始します。
stopFade¶
メソッド
解説
フェードを停止する
WaveSoundBuffer.fade メソッドで開始したフェードを強制的に停止します。
音量は停止させた時点のままになります。
freeDirectSound¶
メソッド
解説
DirectSound の解放 ( 互換用・何もしません )
旧 DirectSound 実装向けに用意されていたメソッドです。 現在の吉里吉里Z の音声出力は miniaudio ( WASAPI 共有モード ) を使用しており DirectSound は使用しないため、このメソッドは呼び出しても何も行いません。 過去のスクリプトとの互換性のためにのみ残されています。 このメソッドは WaveSoundBuffer クラス上にしか存在しません (WaveSoundBufferから作られたオブジェクト上にこのメソッドはありません)。 使用する際は WaveSoundBuffer.freeDirectSound(); としてください。
getVisBuffer¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
buffer |
|
出力データを書き込むバッファを指定します。 バッファは 16bit 符号付き整数の配列で、numsamples 引数および channels 引数で指定したサンプルが書き込まれるのに十分な個数 ( numsamples * channels 以上 )である必要があります。 channels に 1 以外を指定した場合は、各チャネルのサンプルはインターリーブされて( ステレオならば 右 左 右 左 ・・・・の順に ) 格納されます。 配列の先頭要素へのポインタを指定する必要がありますが、整数型にキャストして渡してください。 |
numsamples |
|
取得するサンプル数を指定します。 |
channel |
|
取得するチャンネル数を指定します。 1 を指定すると、モノラルの場合はそのまま、そうでない場合は 1チャンネルにダウンミックスされたデータを得ることができます。 1 以外の数値を指定する場合は、再生中のサウンドと同じチャンネル数を指定する必要があります。 このばあいは、そのままのデータを得ることができます。 |
ahead |
0 |
先読みするサンプル数を指定します。 現在の再生位置から、この引数で指定したサンプル数だけ先にあるサンプルから取得することができます。 0 を指定するか、この引数を省略すると、現在の再生位置からの取得になります。 |
戻り値
取得できたサンプル数が戻ります。
解説
視覚化用データの取得
視覚化用に PCM データを取得します。 現在の再生位置から PCM データを読み込み、buffer 引数で指定した配列に書き込みます。 ただし、バッファの状態や再生形式によっては正常にデータを読み込めない可能性もあります。 このメソッドは C や C++ 等で書かれたプラグインから利用されることを想定してますので、たとえばbuffer 引数に TJS の配列を指定する、などのようなことはできません。 このメソッドを使用するには WaveSoundBuffer.useVisBuffer プロパティを真に指定する必要があります。
getSoundLevel¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
ahead |
0 |
先読みするサンプル数を指定します ( 既定 0 = 現在の再生位置 )。 描画のレイテンシに合わせて口パクを前後させたい場合に使います。 |
windowSamples |
0 |
音量を計算する窓のサンプル数を指定します ( 既定 0 = エンジン既定 )。 |
戻り値
%[ rms:実効値, peak:ピーク値 ] の辞書を返します。いずれも 0.0〜1.0 で、
rms は口の開き量にそのまま使えます。
解説
音量レベルの取得 ( リップシンク用 )
現在の再生位置付近の音量を取得します。getVisBuffer のように生の
PCM を取り出して TJS 側で計算する必要はなく、エンジンが C++ 側で計算して返します。
使用するには WaveSoundBuffer.useVisBuffer を真にする必要があります ( 未設定の
場合は自動的に有効化され、その回は 0 が返ります )。
関連: WaveSoundBuffer.getVowel / WaveSoundBuffer.getSoundSpectrum
getSoundSpectrum¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
numbands |
|
取得するバンド数を指定します ( 1〜256 )。 |
ahead |
0 |
先読みするサンプル数を指定します ( 既定 0 )。 |
戻り値
各バンドのエネルギーを格納した配列 ( 要素数 numbands ) を返します。 バンドは対数配置 ( 低域から高域 ) です。
解説
スペクトルの取得 ( リップシンク用 )
現在の再生位置付近のスペクトルを FFT で解析し、対数配置の
バンドエネルギーとして返します。母音判定やイコライザ表示などに利用できます。
WaveSoundBuffer.useVisBuffer を真にする必要があります。
getVowel¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
ahead |
0 |
先読みするサンプル数を指定します ( 既定 0 )。 |
戻り値
%[ a:, i:, u:, e:, o:, voiced: ] の辞書を返します。a〜o は各母音の
推定重み ( 合計がおよそ 1.0 )、voiced は有声 ( 母音帯域にエネルギーあり ) なら 1、
無音なら 0 です。
解説
母音推定の取得 ( リップシンク用 )
現在の再生位置付近のスペクトルを解析し、日本語 5 母音 ( あいうえお )
らしさをフォルマント帯域のエネルギー比から推定して返します。口の形
( viseme ) のブレンド重みとして利用できます。あくまで簡易推定である点に
注意してください。
WaveSoundBuffer.useVisBuffer を真にする必要があります。
関連: WaveSoundBuffer.getSoundLevel
setPos¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
x |
|
X 座標を指定します。 |
y |
|
Y 座標を指定します。 |
z |
|
Z 座標を指定します。 |
解説
3D 音源位置のまとめ設定
3D サウンド再生時の音源位置 ( X / Y / Z ) を一括で設定します。
関連: WaveSoundBuffer.posX / WaveSoundBuffer.posY / WaveSoundBuffer.posZ
set3DPosition¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
x |
|
X 座標。 |
y |
|
Y 座標。 |
z |
|
Z 座標。 |
解説
3D 音源位置を設定する
3D 定位の音源位置を設定します ( use3D が有効なときに作用 )。
set3DVelocity¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
vx |
|
X 方向の速度。 |
vy |
|
Y 方向の速度。 |
vz |
|
Z 方向の速度。 |
解説
3D 音源の速度ベクトルを設定する
ドップラー計算に使う音源の速度ベクトルを設定します。
関連: WaveSoundBuffer.dopplerFactor
set3DConeDirection¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
dx |
|
向きの X 成分。 |
dy |
|
向きの Y 成分。 |
dz |
|
向きの Z 成分。 |
解説
指向性コーンの向きを設定する
指向性コーン ( set3DCone ) の向きベクトルを設定します。
set3DCone¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
innerAngleRad |
|
内側コーンの全角 ( ラジアン )。この内側では減衰しません。 |
outerAngleRad |
|
外側コーンの全角 ( ラジアン )。 |
outerGain |
|
外側での減衰ゲイン ( 0.0 〜 1.0 )。 |
解説
指向性コーンを設定する
音源の指向性コーンを設定します。角度はラジアンで、コーン外側では outerGain の ゲインまで減衰します。全方位 ( 無指向 ) にしたい場合は inner = outer = 2*PI とします。
関連: WaveSoundBuffer.set3DConeDirection
setGainQueryCallback¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
callback |
|
URL ( ストレージ名 ) を 1 引数で受け取り、適用する追加 ゲインを dB で返す関数を指定します。null を指定すると解除します。 |
解説
曲別ゲイン取得コールバックの設定 ( クラスメソッド )
ogg ( Vorbis ) / opus ファイルのデコード時に、ファイルごとに適用する 追加ゲイン ( dB ) を返すコールバック関数を登録します。これはクラス メソッドで、登録は全 WaveSoundBuffer で共有されます。旧 wuvorbis / wuopus プラグインの同名 API を本体内蔵デコーダへ統合したものです。 コールバックはファイルを開くとき ( open 時、スクリプトスレッド ) に 1 回 呼ばれ、戻り値の dB がデコード出力に適用されます。曲ごとに音量を揃える ( ラウドネス正規化 ) 用途などに使います。
例 :
WaveSoundBuffer.setGainQueryCallback(function(url) {
return url.indexOf("loud_") != -1 ? -6.0 : 0.0; // 特定曲だけ -6dB
});
ゲインには他に、起動時コマンドラインオプションによる全体ゲインや ReplayGain タグ対応もあります ( コマンドライン の「サウンドのゲイン」参照 )。
コーデックによる差異 / 推奨
opus は仕様上ヘッダに出力ゲイン ( R128 ) を持ち、デコーダ内部で正確・ 低コストに適用されます ( CLI / コールバックのゲインもこれに加算 )。一方 Vorbis はフォーマットにゲイン概念が無いため、本体は出力 PCM を float 域で スケールして適用します ( 実用上の性能差はほぼありません )。ゲインや ラウドネスを積極的に扱う場合は opus の利用を推奨します。
onStatusChanged¶
イベント
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
status |
|
新しいステータスです。 WaveSoundBuffer.status プロパティを参照してください。 |
解説
ステータスが変更された
再生のステータス ( 状態 ) が変わった時に発生します。
onFadeCompleted¶
イベント
解説
フェードが終了した
WaveSoundBuffer.fade メソッドで開始したフェードが終了したときに発生します。
onLabel¶
イベント
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
name |
|
通過したラベル名です。 |
解説
ラベルを通過した
再生位置がラベルを通過した際に発生します。
プラグイン拡張: getSample¶
擬似コードによるマニュアル
メンバー一覧¶
プロパティ¶
メソッド¶
sampleValue¶
プロパティ \ アクセス: r
解説
サンプル値の取得(新方式)
getVisBuffer(buf, sampleCount, 1, sampleAhead)でサンプルを取得し, (value/32768)^2の最大値を取得します。(0~1の実数で返ります) ※このプロパティを読み出すと暗黙でuseVisBuffer=trueに設定されます
sampleCount¶
プロパティ \ アクセス: r/w
解説
新方式のバッファ取得用パラメータプロパティ(sampleValueを参照)
デフォルトはsetDefaultCounts/setDefaultAheadsで決定されます ※このプロパティを読み書きする暗黙でuseVisBuffer=trueに設定されます
sampleAhead¶
プロパティ \ アクセス: r/w
getSample¶
メソッド
引数
| 引数 | 既定値 | 説明 |
|---|---|---|
n |
|
取得するサンプルの数。省略すると 100 |
戻り値
平均値 ※ 予めuseVisBuffer=trueにしておくこと
解説
サンプル値の取得(旧方式)
現在の再生位置から指定数のサンプルを取得してその平均値を返します。 値が負のサンプル値は無視されます。