BaseAudioContext.destination — Eigenschaft · JavaScript-Referenz

Signatur

BaseAudioContext.destination

Beschreibung

Die schreibgeschützte Eigenschaft destination eines BaseAudioContext (also eines AudioContext oder OfflineAudioContext) gibt einen AudioDestinationNode zurück. Dieser Knoten ist das endgültige Ziel aller Audiosignale im Kontext. Bei einem AudioContext ist das in der Regel das Standard-Ausgabegerät (Lautsprecher, Kopfhörer). Bei einem OfflineAudioContext landet das Signal stattdessen in einem AudioBuffer, der beim Aufruf von startRendering() zurückgegeben wird.

Man braucht destination immer dann, wenn ein Audio-Graph tatsächlich hörbar oder renderbar werden soll: Quellen wie OscillatorNode, AudioBufferSourceNode oder MediaElementAudioSourceNode werden – oft über Effektknoten wie GainNode oder BiquadFilterNode – per connect(ctx.destination) mit dem Ziel verbunden. Ein Knoten, der nicht (direkt oder indirekt) mit destination verbunden ist, bleibt stumm.

Pro Kontext gibt es genau einen AudioDestinationNode; die Eigenschaft liefert bei jedem Zugriff dasselbe Objekt. Über destination.maxChannelCount lässt sich abfragen, wie viele Kanäle die Hardware unterstützt, und über channelCount kann man – innerhalb dieser Grenze – die Ausgabekanäle einstellen, etwa für Mehrkanal-Audio.

Rückgabewert

Typ

AudioDestinationNode

Beschreibung

Der einzige Ausgabeknoten des Kontexts. Er hat einen Eingang und keinen Ausgang; die Eigenschaft ist schreibgeschützt.

Beispiele

Oszillator hörbar machen

const ctx = new AudioContext();

const button = document.querySelector('#play');
button.addEventListener('click', async () => {
  // Autoplay-Regeln: Kontext erst nach einer Nutzeraktion fortsetzen
  await ctx.resume();

  const osc = ctx.createOscillator();
  osc.frequency.value = 440; // Kammerton A
  osc.connect(ctx.destination);
  osc.start();
  osc.stop(ctx.currentTime + 1); // eine Sekunde lang
});

Lautstärkeregler vor die Ausgabe schalten

const ctx = new AudioContext();
const audioEl = document.querySelector('audio');
const slider = document.querySelector('#volume');

const source = ctx.createMediaElementSource(audioEl);
const gain = ctx.createGain();

// Quelle -> Gain -> Lautsprecher
source.connect(gain).connect(ctx.destination);

slider.addEventListener('input', () => {
  gain.gain.setTargetAtTime(Number(slider.value), ctx.currentTime, 0.01);
});

Kanäle abfragen und offline rendern

const live = new AudioContext();
console.log('Max. Kanäle:', live.destination.maxChannelCount);
console.log('Aktiv:', live.destination.channelCount);

// Offline: destination schreibt in einen AudioBuffer
const offline = new OfflineAudioContext(2, 44100, 44100);
const osc = offline.createOscillator();
osc.connect(offline.destination);
osc.start();

const buffer = await offline.startRendering();
console.log(buffer.duration, buffer.numberOfChannels);

Max. Kanäle: 2 Aktiv: 2 1 2

// Wichtig · Fallstricke

Autoplay-Sperre: Ein AudioContext startet in vielen Browsern im Zustand "suspended". Selbst korrekt mit destination verbundene Knoten bleiben stumm, bis nach einer Nutzeraktion ctx.resume() aufgerufen wurde.
Schreibgeschützt: destination kann nicht ersetzt werden. Um das Ausgabegerät zu wechseln, verwendet man AudioContext.setSinkId() (derzeit nur in Chromium-basierten Browsern) oder leitet über createMediaStreamDestination() in einen MediaStream um, etwa für Aufnahme oder WebRTC.
Kanalanzahl: Wird channelCount höher als maxChannelCount gesetzt, wird ein IndexSizeError ausgelöst. Beim OfflineAudioContext ist die Kanalanzahl durch den Konstruktor festgelegt.
Übersteuerung: Mehrere Quellen an destination werden aufsummiert; Werte außerhalb von -1 bis 1 führen zu Clipping. Ein GainNode oder DynamicsCompressorNode davor hilft.
Die Eigenschaft wird in allen aktuellen Browsern unterstützt; ältere Safari-Versionen brauchen webkitAudioContext.

Siehe auch

MediaTrackSupportedConstraints.restrictOwnAudio BaseAudioContext.state BaseAudioContext.currentTime BaseAudioContext.listener BaseAudioContext.sampleRate