The connect()
method of the AudioNode
interface lets you connect one of the node's outputs to a target, which may be either another AudioNode
(thereby directing the sound data to the specified node) or an AudioParam
, so that the node's output data is automatically used to change the value of that parameter over time.
Syntax
var destinationNode = AudioNode.connect(destination, outputIndex, inputIndex); AudioNode.connect(destination, outputIndex);
Parameters
destination
- The
AudioNode
orAudioParam
to which to connect. outputIndex
Optional- An index specifying which output of the current
AudioNode
to connect to the destination. The index numbers are defined according to the number of output channels (see Audio channels). While you can only connect a given output to a given input once (repeated attempts are ignored), you can connect an output to multiple inputs by callingconnect()
repeatedly. This makes fan-out possible. The default value is 0. inputIndex
Optional- An index describing which input of the destination you want to connect the current
AudioNode
to; the default is 0. The index numbers are defined according to the number of input channels (see Audio channels). It is possible to connect anAudioNode
to anotherAudioNode
, which in turn connects back to the firstAudioNode
, creating a cycle. This is allowed only if there is at least oneDelayNode
in the cycle. Otherwise, aNotSupportedError
exception is thrown. This parameter is not allowed if the destination is anAudioParam
.
Return value
If the destination is a node, connect()
returns a reference to the destination AudioNode
object. In some browsers, older implementations of this interface return undefined
.
If the destination is an AudioParam
, connect()
returns undefined
.
Exceptions
IndexSizeError
- The value specified as
outputIndex
orinputIndex
doesn't correspond to an existing input or output. InvalidAccessError
- The destination node is not part of the same audio context as the source node.
NotSupportedError
- The specified connection would create a cycle (in which the audio loops back through the same nodes repeatedly) and there are no
DelayNode
s in the cycle to prevent the resulting waveform from getting stuck constructing the same audio frame indefinitely.
Connecting to an audio input
The most obvious use of the connect()
method is to direct the audio output from one node into the audio input of another node for further processing. For example, you might send the audio from a MediaElementAudioSourceNode
—that is, the audio from an HTML5 media element such as <audio>
—through a band pass filter implemented using a BiquadFilterNode
to reduce noise before then sending the audio along to the speakers.
Example
This example creates an oscillator, then links it to a gain node, so that the gain node controls the volume of the oscillator node.
var AudioContext = window.AudioContext || window.webkitAudioContext; var audioCtx = new AudioContext(); var oscillator = audioCtx.createOscillator(); var gainNode = audioCtx.createGain(); oscillator.connect(gainNode); gainNode.connect(audioCtx.destination);
Connecting to a parameter input
You can also connect the output of a node to a single input of an AudioParam
(this is known as fan-in). This lets you easily use an audio signal to change the value of one or more parameters. A node's output can be connected to multiple AudioParam
s (allowing the node's output to control the value of multiple parameters—a technique known as fan-out), and multiple nodes can output their signal to a single AudioParam
, too. Both of those scenarios are achieved through multiple calls to connect()
, one for each node output to parameter pair.
Specifications
Specification | Status | Comment |
---|---|---|
Web Audio API The definition of 'connect() to an AudioNode' in that specification. |
Working Draft | |
Web Audio API The definition of 'connect() to an AudioParam' in that specification. |
Working Draft |
Browser compatibility
Feature | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|---|
Basic support | 10.0webkit | (Yes) | 25.0 (25.0) | No support | 15.0webkit | (Yes) |
Unprefixed | (Yes) | ? | ? | 22 | ? |
Feature | Android | Android Webview | Edge | Firefox Mobile (Gecko) | Firefox OS (Gecko) | IE Phone | Opera Mobile | Safari Mobile | Chrome for Android |
---|---|---|---|---|---|---|---|---|---|
Basic support | ? | ? | (Yes) | 26.0 | 1.2 | ? | ? | ? | ? |
Unprefixed | ? | (Yes) | ? | ? | ? | ? | ? | ? | (Yes) |