AudioNode — Schnittstelle · JavaScript-Referenz

Signatur

interface AudioNode extends EventTarget

Beschreibung

AudioNode ist die gemeinsame Basis aller Bausteine eines Audio-Routing-Graphen in der Web Audio API. Jeder Knoten hat Eingänge und/oder Ausgänge: Quellknoten (z. B. OscillatorNode, AudioBufferSourceNode, MediaElementAudioSourceNode) haben keine Eingänge, Zielknoten (AudioDestinationNode) haben keinen Ausgang, und Verarbeitungsknoten wie GainNode, BiquadFilterNode oder AnalyserNode liegen dazwischen.

Man instanziiert AudioNode nie direkt – es gibt keinen öffentlichen Konstruktor. Stattdessen erzeugt man konkrete Unterklassen über Fabrikmethoden des AudioContext (z. B. ctx.createGain()) oder über deren eigene Konstruktoren (z. B. new GainNode(ctx, { gain: 0.5 })). Jeder Knoten gehört fest zu genau einem BaseAudioContext.

Wichtige Mitglieder:

connect(destination, outputIndex?, inputIndex?) – verbindet einen Ausgang mit einem anderen AudioNode (Rückgabe: Zielknoten, daher verkettbar) oder mit einem AudioParam (Rückgabe: undefined).
disconnect(...) – trennt alle oder gezielte Verbindungen.
context, numberOfInputs, numberOfOutputs – schreibgeschützte Informationen.
channelCount, channelCountMode ("max", "clamped-max", "explicit"), channelInterpretation ("speakers", "discrete") – steuern das Up-/Down-Mixing der Kanäle an den Eingängen.

Parameter

Name	Typ	Default	Beschreibung
$destination Pflicht	AudioNode \| AudioParam		Parameter von `connect()`: Zielknoten oder zu modulierender `AudioParam`.
$outputIndex	number	0	Index des Ausgangs dieses Knotens, der verbunden bzw. getrennt werden soll. Ungültige Werte werfen `IndexSizeError`.
$inputIndex	number	0	Index des Eingangs am Zielknoten (nur bei `AudioNode`-Zielen).

Rückgabewert

Typ

AudioNode | undefined

Beschreibung

connect() gibt bei einem AudioNode-Ziel den Zielknoten zurück (ermöglicht Verkettung), bei einem AudioParam undefined. disconnect() gibt undefined zurück.

Beispiele

Knoten erzeugen und verkettet verbinden

const ctx = new AudioContext();

// Konkrete AudioNode-Unterklassen erzeugen
const osc = new OscillatorNode(ctx, { type: 'sine', frequency: 440 });
const gain = ctx.createGain();
gain.gain.value = 0.2;

// connect() liefert den Zielknoten -> verkettbar
osc.connect(gain).connect(ctx.destination);

console.log(osc instanceof AudioNode);
console.log(osc.numberOfInputs, osc.numberOfOutputs);
console.log(gain.channelCountMode);

osc.start();
osc.stop(ctx.currentTime + 1);

true 0 1 max

Audio-Element durch Filter leiten (nach Nutzerklick)

const audioEl = document.querySelector('audio');
const button = document.querySelector('#play');

button.addEventListener('click', async () => {
  const ctx = new AudioContext();
  const source = ctx.createMediaElementSource(audioEl);
  const filter = new BiquadFilterNode(ctx, { type: 'lowpass', frequency: 800 });

  source.connect(filter).connect(ctx.destination);
  await ctx.resume();
  await audioEl.play();
});

LFO moduliert einen AudioParam (Tremolo)

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

const lfo = new OscillatorNode(ctx, { frequency: 5 });
const lfoDepth = new GainNode(ctx, { gain: 0.3 });

// Verbindung zu einem AudioParam -> Rückgabe undefined
const result = lfo.connect(lfoDepth).connect(amp.gain);
console.log(result);

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

undefined

Verbindungen gezielt trennen

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx);
const dry = new GainNode(ctx);
const wet = new GainNode(ctx);

osc.connect(dry).connect(ctx.destination);
osc.connect(wet).connect(ctx.destination);
osc.start();

// Nach 2 s nur den Effektzweig trennen
setTimeout(() => {
  osc.disconnect(wet);
  console.log('Effektzweig getrennt');
}, 2000);

Effektzweig getrennt

// Wichtig · Fallstricke

Kein Konstruktor: new AudioNode() wirft einen TypeError – immer konkrete Unterklassen verwenden.
Autoplay-Richtlinien: Ein AudioContext startet in vielen Browsern im Zustand "suspended". Erst nach einer Nutzerinteraktion mit ctx.resume() ist etwas zu hören.
Kontextgrenzen: Knoten aus verschiedenen Kontexten lassen sich nicht verbinden (InvalidAccessError).
Einmal-Quellen: OscillatorNode und AudioBufferSourceNode können nur einmal gestartet werden; für erneutes Abspielen einen neuen Knoten erzeugen (das ist günstig).
Zyklen: Rückkopplungsschleifen sind nur erlaubt, wenn ein DelayNode im Zyklus liegt – sonst wird der Zyklus stummgeschaltet.
createMediaElementSource() darf pro <audio>-Element nur einmal aufgerufen werden; bei fremden Quellen ohne CORS-Header liefert der Knoten nur Stille.
Ältere Safari-Versionen benötigten webkitAudioContext; die Knoten-Konstruktoren (new GainNode(ctx)) werden erst seit Safari 14.1 unterstützt – Fabrikmethoden (createGain()) sind am breitesten kompatibel.
Nicht mehr benötigte Knoten mit disconnect() trennen, damit sie vom Garbage Collector freigegeben werden können.

Siehe auch

AudioEncoder AudioData AudioDecoder GainNode AudioBuffer