AudioContext.sinkId — Eigenschaft · JavaScript-Referenz

Signatur

AudioContext.sinkId

Beschreibung

Die Eigenschaft sinkId eines AudioContext zeigt, auf welches Ausgabegerät (Lautsprecher, Kopfhörer, USB-Interface …) der Kontext sein Audiosignal gerade ausgibt. Sie ist schreibgeschützt. Ändern lässt sich das Ausgabegerät über die Methode AudioContext.prototype.setSinkId() oder schon beim Erzeugen über die Option sinkId im Konstruktor new AudioContext({ sinkId }).

Der Wert kann drei Formen haben:

Leerer String "": Der Kontext nutzt das Standard-Ausgabegerät des Systems bzw. des Browsers.
Nicht leerer String: die deviceId eines Ausgabegeräts, wie sie navigator.mediaDevices.enumerateDevices() für Einträge mit kind === "audiooutput" liefert.
AudioSinkInfo-Objekt: Wurde setSinkId({ type: "none" }) aufgerufen, rechnet der Kontext weiter, gibt aber nichts hörbar aus. sinkId ist dann ein Objekt mit type: "none".

Nützlich ist das vor allem für Anwendungen, in denen man das Ausgabegerät auswählen kann: Videokonferenz-Tools, DAWs im Browser, Spiele oder Streaming-Oberflächen. Mit sinkId zeigt man z. B. in einem Auswahlmenü das aktive Gerät an. Über das Ereignis sinkchange hält man die Oberfläche aktuell, wenn sich das Gerät ändert.

Rückgabewert

Typ

string | AudioSinkInfo

Beschreibung

Ein leerer String für das Standardgerät, eine Geräte-ID als String oder ein AudioSinkInfo-Objekt mit type: "none", wenn die Ausgabe stummgeschaltet ist.

Beispiele

Aktuelles Ausgabegerät auslesen

const ctx = new AudioContext();

const describeSink = (sinkId) => {
  if (typeof sinkId === 'object') return `Keine Ausgabe (type: ${sinkId.type})`;
  return sinkId === '' ? 'Standard-Ausgabegerät' : `Gerät mit ID ${sinkId}`;
};

console.log(describeSink(ctx.sinkId));

Standard-Ausgabegerät

Ausgabegerät wählen und sinkId prüfen

const ctx = new AudioContext();

const switchToFirstOutput = async () => {
  // Für echte Gerätenamen ist meist eine Mikrofon-Freigabe nötig
  await navigator.mediaDevices.getUserMedia({ audio: true });
  const devices = await navigator.mediaDevices.enumerateDevices();
  const outputs = devices.filter((d) => d.kind === 'audiooutput' && d.deviceId !== 'default');

  if (outputs.length === 0) return console.log('Kein weiteres Ausgabegerät gefunden');

  await ctx.setSinkId(outputs[0].deviceId);
  console.log(`Aktiv: ${outputs[0].label} (${ctx.sinkId})`);
};

document.querySelector('#switch').addEventListener('click', switchToFirstOutput);

Aktiv: USB-Kopfhörer (3f9a1c…)

Auf Gerätewechsel reagieren (sinkchange)

const ctx = new AudioContext({ sinkId: { type: 'none' } });

ctx.addEventListener('sinkchange', () => {
  const id = ctx.sinkId;
  const label = typeof id === 'object' ? 'stumm' : id || 'Standard';
  console.log('Neue Ausgabe:', label);
});

// Später: wieder auf das Standardgerät umschalten
await ctx.setSinkId('');

Neue Ausgabe: Standard

Feature-Erkennung

const supportsSinkSelection = 'sinkId' in AudioContext.prototype;

if (!supportsSinkSelection) {
  console.warn('Auswahl des Ausgabegeräts wird nicht unterstützt – Standardgerät wird genutzt.');
  document.querySelector('#output-select')?.setAttribute('hidden', '');
}

// Wichtig · Fallstricke

Browser-Unterstützung: Die Eigenschaft ist experimentell. Unterstützt wird sie nur in Chromium-Browsern (Chrome/Edge ab 110). Firefox und Safari kennen sie nicht. Prüfen Sie vor der Nutzung mit 'sinkId' in AudioContext.prototype.
Typ prüfen: sinkId ist nicht immer ein String. Nach setSinkId({ type: "none" }) ist es ein AudioSinkInfo-Objekt. Stringvergleiche wie ctx.sinkId === deviceId sollten das berücksichtigen.
Kein direktes Setzen: Eine Zuweisung wie ctx.sinkId = "…" wirkt nicht. Verwenden Sie setSinkId(). Die Methode gibt ein Promise zurück, und sinkId ändert sich erst, wenn das Promise erfüllt ist.
Berechtigungen und Datenschutz: Geräte-IDs sind je Ursprung (Origin) verschieden und können sich ändern, wenn Cookies gelöscht werden. Ohne Medienfreigabe liefert enumerateDevices() oft leere Labels. Der Zugriff kann über die Permissions-Policy speaker-selection eingeschränkt sein. Außerdem ist ein sicherer Kontext (HTTPS) nötig.
Wird ein gewähltes Gerät getrennt, kann der Browser auf das Standardgerät zurückfallen. Hören Sie deshalb auf sinkchange und auf devicechange von navigator.mediaDevices.

Siehe auch

AudioContext.setSinkId() AudioContext MediaDevices.enumerateDevices() HTMLMediaElement.sinkId AbortController.signal GPUCanvasContext.canvas