MediaDevices: Methode selectAudioOutput()

Syntax

selectAudioOutput()
selectAudioOutput(options)

Parameter

options Optional

Ein Objekt, das konfiguriert, welche Geräte dem Benutzer angezeigt werden dürfen.

deviceId Optional

Ein String, der die ID eines zuvor freigegebenen/erlaubten Geräts darstellt. Wenn nicht gesetzt, wird ein Prompt mit allen verfügbaren Audioausgabegeräten angezeigt.

Diese Option ist für Anwendungen gedacht, die eine Geräte-ID speichern möchten, damit das gleiche 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 gespeicherte IDs müssen erfolgreich durch selectAudioOutput() übergeben werden, bevor sie mit setSinkId() funktionieren.

Hinweis: Ein Benutzeragent kann entscheiden, den Benutzer nicht zu befragen, wenn eine angegebene, nicht-null ID dem Benutzer zuvor durch selectAudioOutput() in einer früheren Sitzung angezeigt wurde. In diesem Fall kann der Benutzeragent einfach mit dieser Geräte-ID oder einer neuen ID für dasselbe Gerät auflösen, wenn sich diese geändert hat. Wenn die Berechtigung für das angegebene Gerät zuvor erteilt wurde, aber inzwischen 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 von dem Benutzer ausgewählte Audioausgabegerät beschreibt.

Ausnahmen

NotAllowedError DOMException

Wird zurückgegeben, wenn eine speaker-selection Berechtigungsrichtlinie verwendet wird, um die Nutzung von Audioausgaben zu blockieren (zusätzlich wird das Popup zur Auswahl einer Audioausgabe nicht angezeigt), oder der Benutzer das Auswahldialogfeld ohne Geräteauswahl schließt.

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 durch eine Art von UI-Ereignis auslösen).

Sicherheitsanforderungen

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

• Die Methode muss in einem sicheren Kontext aufgerufen werden.
• Eine transiente Benutzeraktivierung ist erforderlich. Der Benutzer muss für diese Funktion mit der Seite oder einem UI-Element interagieren.
• Der Zugriff kann durch die speaker-selection HTTP-Berechtigungsrichtlinie eingeschränkt sein.

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

Beispiele

Hier ist ein Beispiel für die Verwendung von selectAudioOutput(), innerhalb einer Funktion, die durch einen Button-Klick ausgelöst wird. Es gibt die ausgewählten Geräte-IDs und Labels (falls 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 Auswahl einer Ausgabe könnte dies folgendes erzeugen:

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

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