AudioNode: connect() 方法

基线 广泛可用

此功能已得到良好确立,并且可在许多设备和浏览器版本中使用。它已在浏览器中可用,自 2021 年 4 月.

AudioNode 接口的 connect() 方法允许您将节点的其中一个输出连接到目标,目标可以是另一个 AudioNode(从而将声音数据定向到指定的节点)或一个 AudioParam,以便节点的输出数据自动用于随时间推移更改该参数的值。

语法

js
connect(destination)
connect(destination, outputIndex)
connect(destination, outputIndex, inputIndex)

参数

destination

要连接到的 AudioNodeAudioParam

outputIndex 可选

指定要连接到目标的当前 AudioNode 的哪个输出的索引。索引号根据输出通道的数量定义(请参阅音频通道)。虽然您只能将给定的输出连接到给定的输入一次(重复尝试将被忽略),但您可以通过重复调用 connect() 将输出连接到多个输入。这使得扇出成为可能。默认值为 0。

inputIndex 可选

描述您希望将当前 AudioNode 连接到的目标的哪个输入的索引;默认为 0。索引号根据输入通道的数量定义(请参阅音频通道)。可以将一个 AudioNode 连接到另一个 AudioNode,后者又连接回第一个 AudioNode,从而创建一个循环。

返回值

如果目标是节点,则 connect() 返回对目标 AudioNode 对象的引用,允许您链接多个 connect() 调用。在某些浏览器中,此接口的旧版实现返回undefined

如果目标是 AudioParam,则 connect() 返回 undefined

异常

IndexSizeError DOMException

如果作为 outputIndexinputIndex 指定的值与不存在的输入或输出相对应,则抛出此异常。

InvalidAccessError DOMException

如果目标节点不是与源节点相同的音频上下文的一部分,则抛出此异常。

NotSupportedError DOMException

如果指定的连接将创建一个循环(其中音频重复循环通过相同的节点),并且循环中没有DelayNode 对象来防止生成的波形无限期地停留在构建相同的音频帧上,则抛出此异常。如果在目标是AudioParam 时使用 inputIndex 参数,则也会抛出此异常。

示例

连接到音频输入

connect() 方法最明显的用途是将一个节点的音频输出定向到另一个节点的音频输入以进行进一步处理。例如,您可能将来自MediaElementAudioSourceNode 的音频(即,来自 HTML 媒体元素(如<audio>)的音频)通过使用BiquadFilterNode 实现的带通滤波器来减少噪声,然后再将音频发送到扬声器。

此示例创建了一个振荡器,然后将其链接到一个增益节点,以便增益节点控制振荡器节点的音量。

js
const audioCtx = new AudioContext();

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

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

AudioParam 示例

在此示例中,我们将使用具有慢频率值的OscillatorNode 更改GainNode 的增益值。此技术称为LFO控制参数。

js
const audioCtx = new AudioContext();

// create an normal oscillator to make sound
const oscillator = audioCtx.createOscillator();

// create a second oscillator that will be used as an LFO (Low-frequency
// oscillator), and will control a parameter
const lfo = audioCtx.createOscillator();

// set the frequency of the second oscillator to a low number
lfo.frequency.value = 2.0; // 2Hz: two oscillations per second

// create a gain whose gain AudioParam will be controlled by the LFO
const 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();

AudioParam 注释

可以使用多次 connect() 调用将 AudioNode 输出连接到多个AudioParam,并将多个 AudioNode 输出连接到单个AudioParam扇入和扇出因此得到支持。

AudioParam 将获取连接到它的任何 AudioNode 输出的渲染音频数据,并通过下混(如果它不是单声道)将其转换为单声道。接下来,它会将其与任何其他此类输出混合,以及内在参数值(AudioParam 在没有任何音频连接的情况下通常具有的值),包括为参数计划的任何时间轴更改。

因此,可以通过将AudioParam 的值设置为中心频率来选择AudioParam 将发生变化的范围,并使用音频源和AudioParam 之间的GainNode 来调整AudioParam 变化的范围。

规范

规范
Web 音频 API
# dom-audionode-connect
Web 音频 API
# dom-audionode-connect-destinationparam-output

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅