AudioDestinationNode — Schnittstelle · JavaScript-Referenz

Signatur

interface AudioDestinationNode extends AudioNode

Beschreibung

AudioDestinationNode ist der letzte Knoten jedes Audiografen der Web Audio API. Sie erzeugen ihn nicht selbst, sondern greifen über context.destination auf ihn zu. Jeder BaseAudioContext hat genau einen solchen Knoten. Alle Signale, die hörbar sein oder in einem OfflineAudioContext gerendert werden sollen, müssen (direkt oder über Zwischenknoten) mit ihm verbunden sein.

Der Knoten hat einen Eingang und keinen Ausgang (numberOfInputs = 1, numberOfOutputs = 0). Ihn mit connect() weiterzuverbinden, ist also nicht möglich. Bei einem AudioContext entspricht er dem Standard-Ausgabegerät des Systems. Bei einem OfflineAudioContext landet das Signal im AudioBuffer, den startRendering() liefert.

Die einzige eigene Eigenschaft ist maxChannelCount. Sie gibt an, wie viele Kanäle die Hardware höchstens unterstützt. Über die geerbte Eigenschaft channelCount können Sie z. B. auf Mehrkanal-Ausgabe (5.1) umschalten, solange der Wert maxChannelCount nicht übersteigt.

maxChannelCount (number, nur lesbar): Höchstzahl der Kanäle, die das Ausgabegerät unterstützt.
Geerbt von AudioNode: context, numberOfInputs, numberOfOutputs, channelCount, channelCountMode, channelInterpretation.

Parameter

Name	Typ	Default	Beschreibung
$maxChannelCount	number		Nur lesbare Eigenschaft: Höchstzahl der Kanäle des physischen Ausgabegeräts. Bei `OfflineAudioContext` entspricht sie der Kanalzahl, die beim Erzeugen des Kontexts angegeben wurde.
$channelCount	number	2	Geerbte Eigenschaft: Anzahl der Ausgabekanäle. Sie darf zwischen 1 und `maxChannelCount` liegen, sonst wird ein `IndexSizeError` ausgelöst.

Rückgabewert

Typ

AudioDestinationNode

Beschreibung

Wird über BaseAudioContext.destination abgerufen. Es gibt keinen öffentlichen Konstruktor.

Beispiele

Oszillator an die Lautsprecher anschließen

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

button.addEventListener('click', async () => {
  const ctx = new AudioContext();
  await ctx.resume(); // Autoplay-Richtlinie: erst nach Nutzerinteraktion

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

  // Graph: Oszillator -> Lautstärke -> Lautsprecher
  osc.connect(gain).connect(ctx.destination);
  osc.start();
  osc.stop(ctx.currentTime + 1);

  console.log(ctx.destination instanceof AudioDestinationNode);
});

true

Kanal-Fähigkeiten des Ausgabegeräts abfragen

const ctx = new AudioContext();
const dest = ctx.destination;

console.log('Eingänge:', dest.numberOfInputs);
console.log('Ausgänge:', dest.numberOfOutputs);
console.log('Max. Kanäle:', dest.maxChannelCount);

// Auf 5.1-Surround umschalten, falls die Hardware das unterstützt
if (dest.maxChannelCount >= 6) {
  dest.channelCount = 6;
  dest.channelInterpretation = 'speakers';
}
console.log('Aktive Kanäle:', dest.channelCount);

Eingänge: 1 Ausgänge: 0 Max. Kanäle: 2 Aktive Kanäle: 2

Offline-Rendering in einen AudioBuffer

const render = async () => {
  // 2 Kanäle, 1 Sekunde bei 44,1 kHz
  const offline = new OfflineAudioContext(2, 44100, 44100);
  const osc = new OscillatorNode(offline, { frequency: 220 });
  osc.connect(offline.destination);
  osc.start();

  console.log('Max. Kanäle:', offline.destination.maxChannelCount);
  const buffer = await offline.startRendering();
  console.log('Gerenderte Samples:', buffer.length);
};

render();

Max. Kanäle: 2 Gerenderte Samples: 44100

// Wichtig · Fallstricke

Kein Konstruktor: new AudioDestinationNode() löst einen TypeError aus. Verwenden Sie immer context.destination.
Keine Ausgänge: ctx.destination.connect(...) löst einen IndexSizeError aus. Wenn Sie aufnehmen oder analysieren wollen, zweigen Sie das Signal vorher ab, z. B. mit AnalyserNode oder MediaStreamAudioDestinationNode.
Autoplay: Browser starten einen AudioContext oft im Zustand "suspended". Bis resume() nach einer Nutzerinteraktion aufgerufen wird, ist am Ziel nichts zu hören.
maxChannelCount gibt häufig nur 2 zurück, selbst bei Mehrkanal-Hardware. Das hängt von Browser und Betriebssystem ab. Ein channelCount größer als maxChannelCount löst einen IndexSizeError aus.
Das Ausgabegerät wählen Sie nicht über diesen Knoten aus. In Chromium-Browsern geht das mit AudioContext.setSinkId(), die Unterstützung ist aber noch nicht überall vorhanden.
Kompatibilität: Der Knoten wird in allen modernen Browsern unterstützt. Sehr alte Safari-Versionen brauchen webkitAudioContext.

Siehe auch

AudioSinkInfo AudioSession AudioWorkletNode AudioDecoder AudioEncoder