MediaDevices: selectAudioOutput()-Methode

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, bevor Sie diese produktiv verwenden.

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

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

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

Syntax

selectAudioOutput()
selectAudioOutput(options)

Parameter

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.

Rückgabewert

Ein Promise, der 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 (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).

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

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 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:

bash

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

Spezifikationen

Specification
Audio Output Devices API # dom-mediadevices-selectaudiooutput

Browser-Kompatibilität

BCD tables only load in the browser