AudioNode: connect() 方法
AudioNode
接口的 connect()
方法允许您将节点的其中一个输出连接到目标,目标可以是另一个 AudioNode
(从而将声音数据定向到指定的节点)或一个 AudioParam
,以便节点的输出数据自动用于随时间推移更改该参数的值。
语法
connect(destination)
connect(destination, outputIndex)
connect(destination, outputIndex, inputIndex)
参数
destination
-
要连接到的
AudioNode
或AudioParam
。 outputIndex
可选-
指定要连接到目标的当前
AudioNode
的哪个输出的索引。索引号根据输出通道的数量定义(请参阅音频通道)。虽然您只能将给定的输出连接到给定的输入一次(重复尝试将被忽略),但您可以通过重复调用connect()
将输出连接到多个输入。这使得扇出成为可能。默认值为 0。 inputIndex
可选-
描述您希望将当前
AudioNode
连接到的目标的哪个输入的索引;默认为 0。索引号根据输入通道的数量定义(请参阅音频通道)。可以将一个AudioNode
连接到另一个AudioNode
,后者又连接回第一个AudioNode
,从而创建一个循环。
返回值
如果目标是节点,则 connect()
返回对目标 AudioNode
对象的引用,允许您链接多个 connect()
调用。在某些浏览器中,此接口的旧版实现返回undefined
。
如果目标是 AudioParam
,则 connect()
返回 undefined
。
异常
IndexSizeError
DOMException
-
如果作为
outputIndex
或inputIndex
指定的值与不存在的输入或输出相对应,则抛出此异常。 InvalidAccessError
DOMException
-
如果目标节点不是与源节点相同的音频上下文的一部分,则抛出此异常。
NotSupportedError
DOMException
-
如果指定的连接将创建一个循环(其中音频重复循环通过相同的节点),并且循环中没有
DelayNode
对象来防止生成的波形无限期地停留在构建相同的音频帧上,则抛出此异常。如果在目标是AudioParam
时使用inputIndex
参数,则也会抛出此异常。
示例
连接到音频输入
connect()
方法最明显的用途是将一个节点的音频输出定向到另一个节点的音频输入以进行进一步处理。例如,您可能将来自MediaElementAudioSourceNode
的音频(即,来自 HTML 媒体元素(如<audio>
)的音频)通过使用BiquadFilterNode
实现的带通滤波器来减少噪声,然后再将音频发送到扬声器。
此示例创建了一个振荡器,然后将其链接到一个增益节点,以便增益节点控制振荡器节点的音量。
const audioCtx = new AudioContext();
const oscillator = audioCtx.createOscillator();
const gainNode = audioCtx.createGain();
oscillator.connect(gainNode);
gainNode.connect(audioCtx.destination);
AudioParam 示例
在此示例中,我们将使用具有慢频率值的OscillatorNode
更改GainNode
的增益值。此技术称为LFO控制参数。
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 的浏览器中加载。