AudioNode: connect() メソッド
=========================

`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` (en-US) を用いて実装されたバンドパスフィルターに通し、音声をスピーカーに送る前にノイズを減らすことができます。

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


```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 with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* Web Audio API の使用