AudioNode.connect(AudioParam)

The connect method of the AudioNode interface allows us to connect one output of the current node to one input of an audio parameter (AudioParam node), allowing us to control the parameter value with an audio signal.

It is possible to connect an AudioNode output to more than one AudioParam, and more than one AudioNode output to a single AudioParam, with multiple calls to connect(). Fan-in and fan-out are therefore supported.

An AudioParam will take the rendered audio data from any AudioNode output connected to it and convert it to mono by down-mixing (if it is not already mono). Next, it will mix it together with any other such outputs, and the intrinsic parameter value (the value the AudioParam would normally have without any audio connections), including any timeline changes scheduled for the parameter.

Therefore, it is possible to choose the range in which an AudioParam will change by setting the value of the AudioParam to the central frequency, and to use a GainNode between the audio source and the AudioParam to adjust the range of the AudioParam changes:

Syntax

var lfo = audioCtx.createOscillator();
lfo.frequency.value = 2.0; // Hz, two times per second
var lfoGain = audioCtx.createGain();
lfoGain.gain.value = 0.5;
// this is the parameter that is going to be modulated
var gain = audioCtx.createGain();
gain.gain.value = 0.5;
// Oscillators go from -1 to 1
// Make it go from -0.5 to +0.5 by connecting it to a GainNode with a gain value of 0.5
lfo.connect(lfoGain);
// because the value of the gain.gain AudioParam is originaly 0.5, the value is added, and it will go from 0.0 to 1.0
lfoGain.connect(gain.gain);
lfo.connect(gain.gain);

Note: There can only be one connection between an output from one specific AudioNode and an AudioParam. Multiple connections to the same termini are equivalent to a single such connection (the duplicates are ignored).

Returns

Void.

Example

In this example, we will be altering the gain value of a GainNode using an OscillatorNode with a slow frequency value. This technique is know as an LFO-controlled parameter.

var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
// create an normal oscillator to make sound
var oscillator = audioCtx.createOscillator();
// create a second oscillator that will be used as an LFO (Low-frequency
// oscillator), and will control a parameter
var lfo = audioCtx.createOscillator();
// set the frequency of the second oscillator to a low number
lfo.frequency.value = 2.0; // 2Hz: two oscillations par second
// create a gain whose gain AudioParam will be controlled by the LFO
var gain = audioCtx.createGain();
// connect the LFO to the gain AudioParam. This means the value of the LFO
// will not produce any audio, but will change the value of the gain instead
lfo.connect(gain.gain);
// connect the oscillator that will produce audio to the gain
oscillator.connect(gain);
// connect the gain to the destination so we hear sound
gain.connect(audioCtx.destination);
// start the oscillator that will produce audio
oscillator.start();
// start the oscillator that will modify the gain value
lfo.start();

Parameters

Destination
The AudioParam you are connecting to.
Output (optional)
An index describing which output of the current AudioNode you want to connect to the AudioParam. The index numbers are defined according to the number of output channels (see Audio channels.)  If this parameter is out-of-bound, an INDEX_SIZE_ERR exception is thrown.

Specifications

Specification Status Comment
Web Audio API
The definition of 'connect(AudioParam)' in that specification.
Working Draft  

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
connect(AudioParam) (Yes) webkit (Yes) No support (Yes) No support
Feature Android Firefox Mobile (Gecko) Firefox OS (Gecko) IE Phone Opera Mobile Safari Mobile
connect(AudioParam) No support (Yes) (Yes) No support No support No support

See also

Document Tags and Contributors

 Contributors to this page: terabaud, fscholz, padenot, chrisdavidmills
 Last updated by: terabaud,