MediaDevices.selectAudioOutput() — Methode · JavaScript-Referenz

Signatur

MediaDevices.prototype.selectAudioOutput(options)

Beschreibung

navigator.mediaDevices.selectAudioOutput() zeigt einen vom Browser gesteuerten Auswahldialog mit den verfügbaren Audioausgabegeräten an. Wählt der Benutzer ein Gerät aus, wird das Promise mit einem MediaDeviceInfo-Objekt erfüllt, dessen kind den Wert "audiooutput" hat. Die enthaltene deviceId kann anschließend an HTMLMediaElement.setSinkId() übergeben werden, um Audio gezielt über dieses Gerät auszugeben.

Die Methode ist vor allem für Webanwendungen gedacht, die ihre Tonausgabe umleiten müssen, etwa Videokonferenz-Tools, Musik- oder Streaming-Player und Kommunikationsanwendungen. Anders als bei enumerateDevices() erhält die Seite hier nur Zugriff auf das eine Gerät, das der Benutzer ausdrücklich ausgewählt hat. Die Methode braucht außerdem keine vorherige Mikrofonfreigabe über getUserMedia(). Das schützt die Privatsphäre, weil die Seite keine vollständige Geräteliste auslesen kann.

Der Aufruf ist nur in einem sicheren Kontext (HTTPS) erlaubt und braucht eine vorübergehende Benutzeraktivierung (transient user activation). Er muss also direkt aus einem Klick- oder Tastatur-Handler heraus erfolgen. Außerdem muss die Permissions Policy speaker-selection den Zugriff erlauben.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Konfigurationsobjekt.
$options.deviceId	string		Die `deviceId` eines Geräts, für das der Benutzer bereits früher eine Freigabe erteilt hat (z. B. in einer früheren Sitzung gespeichert). Der Browser darf dann ohne erneuten Dialog auflösen, sofern die Freigabe noch gilt und das Gerät verfügbar ist.

Rückgabewert

Typ

Promise<MediaDeviceInfo>

Beschreibung

Ein Promise, das mit einem MediaDeviceInfo-Objekt (kind: "audiooutput", deviceId, label, groupId) des gewählten Geräts erfüllt wird. Das Promise wird abgelehnt mit NotAllowedError (keine Benutzeraktivierung, durch die Permissions Policy blockiert oder vom Benutzer abgebrochen), NotFoundError (keine Ausgabegeräte vorhanden) oder InvalidStateError (Dokument nicht vollständig aktiv).

Beispiele

Ausgabegerät per Button auswählen und einem Audio-Element zuweisen

const button = document.querySelector('#speaker-btn');
const audio = document.querySelector('audio');

button.addEventListener('click', async () => {
  // Funktionsprüfung: Methode wird nicht überall unterstützt
  if (!navigator.mediaDevices?.selectAudioOutput) {
    console.warn('selectAudioOutput() wird nicht unterstützt');
    return;
  }
  try {
    const device = await navigator.mediaDevices.selectAudioOutput();
    await audio.setSinkId(device.deviceId);
    console.log(`Ausgabe über: ${device.label}`);
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
});

Ausgabe über: USB Headset

Frühere Auswahl merken und wiederverwenden

const STORAGE_KEY = 'preferredSpeaker';
const video = document.querySelector('video');

document.querySelector('#restore-btn').addEventListener('click', async () => {
  const savedId = localStorage.getItem(STORAGE_KEY) ?? undefined;
  try {
    // Mit gespeicherter deviceId kann der Dialog entfallen
    const device = await navigator.mediaDevices.selectAudioOutput(
      savedId ? { deviceId: savedId } : {}
    );
    localStorage.setItem(STORAGE_KEY, device.deviceId);
    await video.setSinkId(device.deviceId);
    console.log('Gerät aktiv:', device.label);
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      console.log('Auswahl abgebrochen oder nicht erlaubt');
    } else if (err.name === 'NotFoundError') {
      console.log('Keine Audioausgabegeräte gefunden');
    }
  }
});

Gerät aktiv: Lautsprecher (Realtek Audio)

Fehlerfall: Aufruf ohne Benutzeraktivierung

// Direkt beim Laden aufgerufen, also ohne Klick
navigator.mediaDevices.selectAudioOutput()
  .then((device) => console.log(device.label))
  .catch((err) => console.log(err.name));

NotAllowedError

// Wichtig · Fallstricke

Browser-Kompatibilität: Derzeit nur in Firefox (ab Version 116) verfügbar. Chrome, Edge und Safari unterstützen die Methode nicht. Prüfen Sie deshalb immer vorher mit 'selectAudioOutput' in navigator.mediaDevices. Als Ausweichlösung bieten sich enumerateDevices() plus eine eigene Geräteauswahl an; dafür ist in Chromium-Browsern meist eine vorherige getUserMedia()-Freigabe nötig.
Benutzeraktivierung: Ohne vorausgehende Benutzerinteraktion (Klick, Tastendruck) wird das Promise sofort mit NotAllowedError abgelehnt. Ein await auf eine andere langsame Operation vor dem Aufruf kann die Aktivierung verfallen lassen.
Sicherer Kontext und Permissions Policy: Die Methode funktioniert nur über HTTPS bzw. localhost. In iframes muss sie mit allow="speaker-selection" freigegeben sein.
Abhängigkeit von setSinkId(): Die Auswahl allein ändert die Ausgabe nicht. Erst HTMLMediaElement.setSinkId() bzw. AudioContext.setSinkId() leitet den Ton um. Auch deren Unterstützung sollten Sie prüfen.
Die deviceId gilt nur für den jeweiligen Ursprung (Origin) und kann sich ändern, wenn der Benutzer Cookies oder Website-Daten löscht.

Siehe auch

MediaDevices MediaDevices.enumerateDevices() MediaDevices.getUserMedia() MediaDeviceInfo HTMLMediaElement.setSinkId() AudioContext.setSinkId()