MediaDevices: selectAudioOutput()-Methode

options Optional

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

deviceId Optional

Eine Zeichenfolge, die die ID eines einzelnen zuvor bekannten/berechtigten Geräts darstellt. Wenn nicht festgelegt, wird ein Prompt mit allen verfügbaren Audioausgabegeräten angezeigt.

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

Hinweis: Ein Benutzeragent kann sich entscheiden, den Benutzer nicht aufzufordern, wenn eine nicht null-spezifizierte ID zuvor in einer früheren Sitzung durch selectAudioOutput() dem Benutzer 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 sie sich geändert hat. Wenn die Berechtigung für das angegebene Gerät zuvor erteilt, aber inzwischen widerrufen wurde, kann der Benutzeragent alle erlaubten Geräte anzeigen, wobei das mit der angegebenen ID hervorgehoben wird.

Ein Promise, der 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 (außerdem wird das Popup zur Auswahl eines Audioausgabegeräts nicht angezeigt) oder der Benutzer das Auswahlfenster geschlossen hat, ohne ein Gerät auszuwählen.

NotFoundError DOMException

Wird zurückgegeben, wenn keine verfügbaren Audioausgabegeräte vorhanden sind.

InvalidStateError DOMException

Wird zurückgegeben, wenn keine transiente Aktivierung erfolgt ist (Sie müssen sie aus einer Art von 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 begrenzt sein.

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

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 Bezeichnungen (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 der Auswahl einer Ausgabe könnte dies erzeugen:

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

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