AudioNode: connect() メソッド
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2021.
AudioNode
インターフェイスの connect()
メソッドは、ノードの出力のうち 1 個を接続先に接続できます。接続先は、別の AudioNode
を用いる (音声データを指定のノードに導く) こともできますし、AudioParam
を用いる (ノードの出力データにより時間経過とともに自動的にパラメーターの値を変える) こともできます。
構文
connect(destination)
connect(destination, outputIndex)
connect(destination, outputIndex, inputIndex)
引数
destination
-
接続する
AudioNode
またはAudioParam
です。 outputIndex
省略可-
この
AudioNode
のどの出力を接続先に接続するかを指定するインデックスです。インデックス番号は出力のチャンネル数に基づいて決められます。(オーディオチャンネルを参照してください) ある出力のある入力への接続は 1 回しかできません (2 回目以降は無視されます) が、connect()
を複数回呼ぶことで 1 個の出力を複数の入力に接続できます。これによりファンアウトを実現できます。デフォルト値は 0 です。 inputIndex
省略可-
接続先のどの入力をこの
AudioNode
に接続するかを指定するインデックスです。デフォルト値は 0 です。インデックス番号は入力のチャンネル数に基づいて決められます。(オーディオチャンネルを参照してください) あるAudioNode
を別のAudioNode
に接続し、このAudioNode
を再び最初のAudioNode
に接続することで、閉路を作ることもできます。
返値
例外
IndexSizeError
DOMException
- :
outputIndex
またはinputIndex
として指定された値が存在する入力や出力に対応しないとき投げられます。
- :
InvalidAccessError
DOMException
- : 接続先のノードが接続元のノードと同じ音声コンテキストにないとき投げられます。
NotSupportedError
DOMException
- :指定された接続により (音声が同じノードを繰り返し流れる) 閉路が作られ、この閉路の中に同じ音声フレームを無限に参照して処理結果の波形が詰まるのを防ぐ
DelayNode
オブジェクトがないとき投げられます。接続先をAudioParam
として引数inputIndex
が使われたときも投げられます。
- :指定された接続により (音声が同じノードを繰り返し流れる) 閉路が作られ、この閉路の中に同じ音声フレームを無限に参照して処理結果の波形が詰まるのを防ぐ
例
音声入力への接続
connect()
メソッドの最もわかりやすい使い方は、次の処理のためにあるノードの音声出力を別のノードの音声入力に接続することです。たとえば、MediaElementAudioSourceNode
が出力する音声 (<audio>
などの HTML メディア要素が出力する音声) を BiquadFilterNode
を用いて実装されたバンドパスフィルターに通し、音声をスピーカーに送る前にノイズを減らすことができます。
この例では発振器を作成し、ゲインノードに接続することで、ゲインノードが発振器ノードの音量を制御できるようにします。
const audioCtx = new AudioContext();
const oscillator = audioCtx.createOscillator();
const gainNode = audioCtx.createGain();
oscillator.connect(gainNode);
gainNode.connect(audioCtx.destination);
AudioParam の例
この例では、GainNode
のゲインの値を遅い周波数を設定した OscillatorNode
を用いて変えます。この手法は、LFO により制御されたパラメーターと呼ばれます。
const audioCtx = new AudioContext();
// 音を出すため通常の発振器を作成する
const oscillator = audioCtx.createOscillator();
// LFO (Low-frequency oscillator) として用い、
// パラメーターを制御する 2 個目の発振器を作成する
const lfo = audioCtx.createOscillator();
// 2 個目の発振器の周波数を低く設定する
lfo.frequency.value = 2.0; // 2Hz (1 秒あたり 2 回の振動)
// ゲインの AudioParam が LFO により制御されるゲインノードを作成する
const gain = audioCtx.createGain();
// LFO をゲインの AudioParam に接続する。これは、LFO の値は
// 音声は生成せず、かわりにゲインの値を変えるということである
lfo.connect(gain.gain);
// 音を出す発振器をゲインノードに接続する
oscillator.connect(gain);
// ゲインノードを出力先に接続し、音を聞けるようにする
gain.connect(audioCtx.destination);
// 音を出す発振器を起動する
oscillator.start();
// ゲインの値を変える発振器を起動する
lfo.start();
AudioParam のポイント
connect()
を複数回呼ぶことにより、1 個の AudioNode
の出力を複数の AudioParam
に接続したり、複数の AudioNode
の出力を 1 個の AudioParam
に接続したりできます。これにより、ファンインとファンアウトに対応しています。
AudioParam
は接続された任意の AudioNode
から計算された音声データを受け取り、(モノラルでなければ) ダウンミキシングによりモノラルに変換します。そして、それを同様の他の出力、およびスケジュールされた時間での変化を含むそのパラメーター本来の値 (音声の接続がないとき通常 AudioParam
が取るはずの値) とミックスします。
そのため、AudioParam
の値を中央の周波数に設定し、音源と AudioParam
の間で GainNode
を用いて AudioParam
の変化の幅を調整することで、AudioParam
が変化する範囲を設定できます。
仕様書
Specification |
---|
Web Audio API # dom-audionode-connect |
Web Audio API # dom-audionode-connect-destinationparam-output |
ブラウザーの互換性
BCD tables only load in the browser