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 を用いる (ノードの出力データにより時間経過とともに自動的にパラメーターの値を変える) こともできます。

構文

js
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 に接続することで、閉路を作ることもできます。

返値

接続先がノードの場合は、connect() は接続先の AudioNode オブジェクトを返すので、複数の connect() の呼び出しを連続させることができます。このインターフェイスの実装が古く、undefined を返すブラウザーもあります。

接続先が AudioParam の場合は、connect()undefined を返します。

例外

  • IndexSizeError DOMException
    • : outputIndex または inputIndex として指定された値が存在する入力や出力に対応しないとき投げられます。
  • InvalidAccessError DOMException
    • : 接続先のノードが接続元のノードと同じ音声コンテキストにないとき投げられます。
  • NotSupportedError DOMException
    • :指定された接続により (音声が同じノードを繰り返し流れる) 閉路が作られ、この閉路の中に同じ音声フレームを無限に参照して処理結果の波形が詰まるのを防ぐ DelayNode オブジェクトがないとき投げられます。接続先を AudioParam として引数 inputIndex が使われたときも投げられます。

音声入力への接続

connect() メソッドの最もわかりやすい使い方は、次の処理のためにあるノードの音声出力を別のノードの音声入力に接続することです。たとえば、MediaElementAudioSourceNode が出力する音声 (<audio> などの HTML メディア要素が出力する音声) を BiquadFilterNode を用いて実装されたバンドパスフィルターに通し、音声をスピーカーに送る前にノイズを減らすことができます。

この例では発振器を作成し、ゲインノードに接続することで、ゲインノードが発振器ノードの音量を制御できるようにします。

js
const audioCtx = new AudioContext();

const oscillator = audioCtx.createOscillator();
const gainNode = audioCtx.createGain();

oscillator.connect(gainNode);
gainNode.connect(audioCtx.destination);

AudioParam の例

この例では、GainNode のゲインの値を遅い周波数を設定した OscillatorNode を用いて変えます。この手法は、LFO により制御されたパラメーターと呼ばれます。

js
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

関連情報