MediaDevices: selectAudioOutput()-Methode

options Optional

Ein Objekt, das konfiguriert, welches Gerät(e) im Benutzerabfragefenster angeboten werden können.

deviceId Optional

Ein String, der die ID eines einzelnen, zuvor offenbarten/erlaubten Geräts darstellt. Wenn nicht festgelegt, wird eine Eingabeaufforderung mit allen verfügbaren Audioausgabegeräten angezeigt.

Diese Option ist für Anwendungen gedacht, die eine Geräte-ID speichern möchten, sodass 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() geleitet werden müssen, bevor sie mit setSinkId() funktionieren.

Hinweis: Ein Benutzeragent kann sich entscheiden, die Benutzerabfrage zu überspringen, wenn eine angegebene, nicht null Id zuvor vom Benutzer durch selectAudioOutput() in einer früheren Sitzung offenbart wurde. In diesem Fall kann der Benutzeragent einfach mit dieser Geräte-ID auflösen oder mit einer neuen ID für dasselbe Gerät, wenn sie geändert wurde. Wenn die Berechtigung für das angegebene Gerät zuvor erteilt, aber später widerrufen wurde, könnte der Benutzeragent alle erlaubten Geräte anzeigen und dasjenige 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 Berechtigungsrichtlinie verwendet wird, um die Verwendung von Audioausgängen zu blockieren (zusätzlich wird das Popup zur Auswahl eines Audioausgangs nicht angezeigt), oder der Benutzer das Auswahlfenster schloss, 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 diese von einer Art 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 Berechtigungsrichtlinie gesteuert werden.

Der Berechtigungsstatus kann mit der Permissions API-Methode navigator.permissions.query() abgefragt werden, indem ein Berechtigungsdeskriptor mit der speaker-selection-Berechtigung ü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 Auswahl einer Ausgabe könnte dies produzieren:

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

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