AudioNode.connect() — Methode · JavaScript-Referenz

Signatur

AudioNode.prototype.connect(destination, outputIndex, inputIndex)

Beschreibung

Mit connect() baust du in der Web Audio API den Audiograph auf: Quellen wie OscillatorNode oder AudioBufferSourceNode werden über Bearbeitungsknoten (z. B. GainNode, BiquadFilterNode) bis zum Ziel AudioContext.destination (den Lautsprechern) verkettet. Ohne Verbindung zum Ziel bleibt ein Knoten stumm.

Es gibt zwei Formen: Ist das Ziel ein AudioNode, fließen die Audiodaten in dessen Eingang, und die Methode gibt den Zielknoten zurück – dadurch lassen sich Aufrufe verketten (source.connect(gain).connect(ctx.destination)). Ist das Ziel ein AudioParam (z. B. gain.gain oder osc.frequency), steuert das Signal diesen Parameter mit Audiorate – ideal für LFOs, Tremolo oder Vibrato. In diesem Fall ist der Rückgabewert undefined.

Ein Ausgang darf mit mehreren Zielen verbunden werden (Fan-out), und ein Eingang kann mehrere Quellen aufnehmen (die Signale werden summiert). Mehrfaches Verbinden derselben Kombination wird ignoriert. Mit outputIndex und inputIndex wählst du bei Knoten mit mehreren Ein-/Ausgängen – etwa ChannelSplitterNode oder ChannelMergerNode – den konkreten Anschluss.

Parameter

Name	Typ	Default	Beschreibung
$destination Pflicht	AudioNode \| AudioParam		Ziel der Verbindung: ein anderer `AudioNode` oder ein `AudioParam`, der moduliert werden soll.
$outputIndex	number	0	Index des Ausgangs des aktuellen Knotens. Ungültige Werte lösen einen `IndexSizeError` aus.
$inputIndex	number	0	Index des Eingangs am Zielknoten. Nur bei `AudioNode`-Zielen erlaubt; bei `AudioParam` entfällt der Parameter.

Rückgabewert

Typ

AudioNode | undefined

Beschreibung

Bei einem AudioNode-Ziel wird dieses Ziel zurückgegeben (Verkettung möglich); bei einem AudioParam-Ziel undefined.

Beispiele

Einfache Kette: Oszillator → Lautstärke → Lautsprecher

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { type: 'sine', frequency: 440 });
const gain = new GainNode(ctx, { gain: 0.2 });

// connect() gibt den Zielknoten zurück – daher verkettbar
const result = osc.connect(gain).connect(ctx.destination);
console.log(result === ctx.destination);

osc.start();
osc.stop(ctx.currentTime + 1); // eine Sekunde Ton

true

Tremolo mit LFO: Verbindung zu einem AudioParam

const ctx = new AudioContext();
const carrier = new OscillatorNode(ctx, { frequency: 330 });
const amp = new GainNode(ctx, { gain: 0.5 });

// Niederfrequenter Oszillator moduliert die Lautstärke
const lfo = new OscillatorNode(ctx, { frequency: 5 });
const lfoDepth = new GainNode(ctx, { gain: 0.3 });

lfo.connect(lfoDepth);
const ret = lfoDepth.connect(amp.gain); // AudioParam-Ziel
console.log(ret);

carrier.connect(amp).connect(ctx.destination);
carrier.start();
lfo.start();

undefined

Stereokanäle vertauschen mit outputIndex und inputIndex

const ctx = new AudioContext();
const audio = document.querySelector('audio');
const source = ctx.createMediaElementSource(audio);

const splitter = ctx.createChannelSplitter(2);
const merger = ctx.createChannelMerger(2);

source.connect(splitter);
// linker Ausgang (0) → rechter Eingang (1) und umgekehrt
splitter.connect(merger, 0, 1);
splitter.connect(merger, 1, 0);
merger.connect(ctx.destination);

document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume(); // Autoplay-Richtlinie beachten
  audio.play();
});

// Wichtig · Fallstricke

Gleicher Kontext: Quelle und Ziel müssen zum selben BaseAudioContext gehören, sonst wird ein InvalidAccessError geworfen.
Indexfehler: Ein ungültiger outputIndex oder inputIndex führt zu einem IndexSizeError.
Zyklen: Rückkopplungsschleifen sind nur erlaubt, wenn ein DelayNode im Kreis liegt; sonst wird der Zyklus stummgeschaltet.
AudioParam-Modulation: Das verbundene Signal wird zum intrinsischen Wert (value) des Parameters addiert, nicht ersetzt. Setze den Grundwert entsprechend.
Verkettung: Nach connect(audioParam) ist keine Verkettung möglich, da undefined zurückkommt.
Autoplay: Browser starten einen AudioContext oft im Zustand suspended; rufe ctx.resume() nach einer Benutzeraktion auf.
Verbindungen löst du mit disconnect(). Die Web Audio API wird von allen modernen Browsern unterstützt; alte Safari-Versionen benötigten webkitAudioContext.

Siehe auch

AudioNode.disconnect() AudioNode AudioContext AudioParam GainNode OscillatorNode BaseAudioContext.destination