MediaDevices: Methode selectAudioOutput()

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.

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

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).

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.

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:

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

• HTMLMediaElement.setSinkId()
• HTMLMediaElement.sinkId
• WebRTC - die Einführungsseite zur API