HTMLMediaElement.setSinkId() — Methode · JavaScript-Referenz

Signatur

HTMLMediaElement.prototype.setSinkId(sinkId)

Beschreibung

Mit setSinkId() leiten Sie den Ton eines Medienelements auf ein bestimmtes Audio-Ausgabegerät um. Das Gerät heißt in der Spezifikation „Sink“. Typische Einsatzfälle sind Videokonferenz-Apps, in denen Nutzer zwischen Headset und Lautsprechern wählen, DJ- und Vorhör-Anwendungen oder Kiosk-Systeme mit fest zugeordneten Ausgängen.

Die benötigte Geräte-ID stammt aus navigator.mediaDevices.enumerateDevices(). Dort liefern Einträge mit kind === "audiooutput" eine deviceId. Alternativ öffnet navigator.mediaDevices.selectAudioOutput() einen Auswahldialog des Browsers und gibt das gewählte Gerät zurück. Übergeben Sie den leeren String "", nutzt das Element wieder das Standardgerät des Systems.

Die Methode arbeitet asynchron und gibt ein Promise zurück. Es wird erfüllt, sobald die Umschaltung wirksam ist. Die aktuell verwendete ID können Sie jederzeit über die Eigenschaft sinkId auslesen. Der Aufruf ist nur in einem sicheren Kontext (HTTPS) möglich und kann durch die Permissions-Policy speaker-selection eingeschränkt sein.

Parameter

Name	Typ	Default	Beschreibung
$sinkId Pflicht	string		Die `deviceId` eines Audio-Ausgabegeräts aus `enumerateDevices()` oder `selectAudioOutput()`. Der leere String `""` steht für das Standardgerät des Systems.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Ausgabe umgeschaltet ist. Es wird abgelehnt mit NotAllowedError, wenn die Berechtigung oder die Permissions-Policy fehlt, mit NotFoundError, wenn kein Gerät mit dieser ID existiert, und mit AbortError, wenn das Umschalten fehlschlägt.

Beispiele

Ausgabegeräte auflisten und umschalten

const audio = document.querySelector('audio');

const switchOutput = async () => {
  // Ohne Mikrofon-Freigabe liefern manche Browser keine Gerätenamen und IDs
  await navigator.mediaDevices.getUserMedia({ audio: true });

  const devices = await navigator.mediaDevices.enumerateDevices();
  const outputs = devices.filter((d) => d.kind === 'audiooutput');
  console.log(outputs.map((d) => d.label));

  // Das erste Gerät nehmen, das nicht das Standardgerät ist
  const target = outputs.find((d) => d.deviceId !== 'default') ?? outputs[0];
  await audio.setSinkId(target.deviceId);
  console.log('Aktive Ausgabe:', audio.sinkId);
};

switchOutput().catch((err) => console.error(err.name, err.message));

["Standard - Lautsprecher", "Headset (USB)"] Aktive Ausgabe: 3f2a…

Auswahlmenü für das Ausgabegerät mit Feature-Erkennung

const video = document.querySelector('video');
const select = document.querySelector('#speaker-select');

if (!('setSinkId' in HTMLMediaElement.prototype)) {
  select.disabled = true;
  select.title = 'Ihr Browser unterstützt keine Wahl des Ausgabegeräts';
} else {
  const devices = await navigator.mediaDevices.enumerateDevices();
  for (const d of devices.filter((d) => d.kind === 'audiooutput')) {
    select.append(new Option(d.label || 'Unbenanntes Gerät', d.deviceId));
  }

  select.addEventListener('change', async () => {
    try {
      await video.setSinkId(select.value);
    } catch (err) {
      alert(`Umschalten fehlgeschlagen: ${err.name}`);
    }
  });
}

Auswahldialog des Browsers nutzen und zum Standard zurückkehren

const audio = document.querySelector('#ringtone');

document.querySelector('#choose').addEventListener('click', async () => {
  // selectAudioOutput() braucht eine Nutzeraktion, z. B. einen Klick
  const device = await navigator.mediaDevices.selectAudioOutput();
  await audio.setSinkId(device.deviceId);
  console.log(`Ausgabe: ${device.label}`);
});

document.querySelector('#reset').addEventListener('click', async () => {
  await audio.setSinkId(''); // zurück zum Standardgerät des Systems
  console.log('Standardgerät aktiv:', audio.sinkId === '');
});

Ausgabe: Headset (USB) Standardgerät aktiv: true

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser unterstützen die Methode schon lange. Firefox kann sie seit Version 116, Safari erst seit 18.4. Prüfen Sie daher immer vorher mit 'setSinkId' in HTMLMediaElement.prototype, ob sie verfügbar ist.
Berechtigungen: Ohne vorherige Freigabe über getUserMedia() oder selectAudioOutput() liefert enumerateDevices() oft leere label-Werte und nur das Standardgerät. Ein Aufruf mit einer fremden oder nicht freigegebenen ID wird mit NotAllowedError oder NotFoundError abgelehnt.
Sicherer Kontext und iframes: Die Methode funktioniert nur über HTTPS (oder localhost). In iframes muss die Permissions-Policy speaker-selection erlaubt sein, z. B. mit allow=\"speaker-selection\".
IDs sind nicht dauerhaft gültig: Geräte-IDs gelten nur für den jeweiligen Ursprung und können sich ändern, etwa nach dem Löschen von Cookies. Wird ein Gerät abgezogen, fällt die Wiedergabe je nach Browser auf das Standardgerät zurück. Reagieren Sie deshalb auf das Ereignis devicechange von navigator.mediaDevices.
Die Methode wirkt nur auf das einzelne Medienelement. Für den Web Audio API gibt es das eigene Gegenstück AudioContext.setSinkId(), das derzeit nur Chromium unterstützt.

Siehe auch

HTMLMediaElement.sinkId MediaDevices.enumerateDevices() MediaDevices.selectAudioOutput() MediaDevices.getUserMedia() AudioContext.setSinkId() HTMLMediaElement