MediaDevices: Methode selectAudioOutput()

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Die selectAudioOutput()-Methode des MediaDevices-Interfaces fordert den Benutzer auf, ein Audioausgabegerät auszuwählen, wie z.B. einen Lautsprecher oder ein Headset. Wenn der Benutzer ein Gerät auswählt, erteilt die Methode die Berechtigung, das ausgewählte Gerät als Audioausgabeseite zu verwenden.

Nach der Auswahl kann, wenn das Gerät verfügbar ist, es mit MediaDevices.enumerateDevices() aufgelistet und als Audioausgabe festgelegt werden, indem HTMLMediaElement.setSinkId() verwendet wird.

Bei Erfolg wird das zurückgegebene Promise mit einem MediaDeviceInfo gelöst, das das ausgewählte Gerät beschreibt.

Syntax

selectAudioOutput()
selectAudioOutput(options)

Parameter

options Optional

Ein Objekt, das konfiguriert, welche Geräte im Benutzerdialog angeboten werden dürfen.

deviceId Optional

Eine Zeichenkette, die die ID eines einzelnen zuvor freigegebenen/erlaubten Geräts darstellt. Wenn nicht gesetzt, wird ein Dialog mit allen verfügbaren Audioausgabegeräten angezeigt.

Diese Option ist für Anwendungen gedacht, die eine Geräte-ID speichern möchten, damit dasselbe Gerät standardmäßig in zukünftigen Sitzungen verwendet werden kann. Beachten Sie, dass die Methode möglicherweise eine neue ID für dasselbe Gerät zurückgibt, und dass persistente IDs durch selectAudioOutput() erfolgreich durchlaufen müssen, bevor sie mit setSinkId() funktionieren.

Hinweis: Ein Benutzeragent kann wählen, den Benutzer nicht um Erlaubnis zu fragen, wenn eine spezifische nicht-null ID zuvor dem Benutzer durch selectAudioOutput() in einer früheren Sitzung präsentiert wurde. In diesem Fall kann der Benutzeragent einfach diese Geräte-ID zurückgeben oder eine neue ID für dasselbe Gerät, wenn sie sich geändert hat. Wenn die Erlaubnis für das angegebene Gerät zuvor gewährt wurde, aber seitdem widerrufen wurde, könnte der Benutzeragent alle erlaubten Geräte anzeigen und das mit der angegebenen ID hervorheben.

Rückgabewert

Ein Promise das mit einem MediaDeviceInfo Objekt erfüllt wird, das das vom Benutzer ausgewählte Audioausgabegerät beschreibt.

Ausnahmen

NotAllowedError DOMException: Wird zurückgegeben, wenn eine speaker-selection Permissions-Policy verwendet wird, um die Nutzung von Audioausgaben zu blockieren (zusätzlich wird das Auswahl-Popup für Audioausgaben nicht angezeigt), oder der Benutzer das Auswahlfenster ohne Auswahl eines Geräts geschlossen hat.
NotFoundError DOMException: Wird zurückgegeben, wenn keine verfügbaren Audioausgabegeräte vorhanden sind.
InvalidStateError DOMException: Wird zurückgegeben, wenn keine transiente Aktivierung stattgefunden hat (Sie müssen sie von einem UI-Ereignis auslösen).

Sicherheitsanforderungen

Der Zugriff auf die API unterliegt den folgenden Einschränkungen:

Die Methode muss in einem sicheren Kontext aufgerufen werden.
Transiente Benutzeraktivierung ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion funktioniert.
Der Zugriff kann durch die speaker-selection HTTP Permission Policy gesteuert werden.

Der Berechtigungsstatus kann mithilfe der Permissions API-Methode navigator.permissions.query() abgefragt werden, wobei ein Berechtigungsdeskriptor mit der Berechtigung speaker-selection übergeben wird.

Beispiele

Hier ist ein Beispiel für die Nutzung von selectAudioOutput(), innerhalb einer Funktion, die durch einen Klick auf einen Button ausgelöst wird. Es gibt die ausgewählten Geräte-IDs und Bezeichnungen (wenn verfügbar) oder eine Fehlermeldung aus.

document.querySelector("#myButton").addEventListener("click", () => {
  if (!navigator.mediaDevices.selectAudioOutput) {
    console.log("selectAudioOutput() not supported.");
    return;
  }

  // Display prompt and log selected device or error
  navigator.mediaDevices
    .selectAudioOutput()
    .then((device) => {
      console.log(`${device.kind}: ${device.label} id = ${device.deviceId}`);
    })
    .catch((err) => {
      console.error(`${err.name}: ${err.message}`);
    });
});

Bei der Auswahl einer Ausgabe könnte dies produzieren:

bash

audiooutput: Realtek Digital Output (Realtek(R) Audio) id = 0wE6fURSZ20H0N2NbxqgowQJLWbwo+5ablCVVJwRM3k=

Spezifikationen

Specification
Audio Output Devices API # dom-mediadevices-selectaudiooutput