Audio Output Devices API

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 Audio Output Devices API ermöglicht es Webanwendungen, Nutzer darüber zu befragen, welches Ausgabegerät für die Audio-Wiedergabe verwendet werden soll.

Konzepte und Nutzung

Betriebssysteme erlauben es üblicherweise Benutzern, festzulegen, dass Audio über Lautsprecher, ein Bluetooth-Headset oder ein anderes Audioausgabegerät abgespielt werden soll. Diese API ermöglicht Anwendungen, diese Funktionalität innerhalb einer Webseite bereitzustellen.

Selbst wenn es durch eine Berechtigungspolitik erlaubt ist, erfordert der Zugriff auf ein bestimmtes Audioausgabegerät dennoch die ausdrückliche Zustimmung des Benutzers, da dieser sich an einem Ort befinden könnte, an dem das Abspielen von Audio über einige Ausgabegeräte unangebracht ist.

Die API stellt die Methode MediaDevices.selectAudioOutput() bereit, die es Nutzern ermöglicht, das gewünschte Audioausgabegerät aus denen, die durch die speaker-selection Direktive des Permissions-Policy HTTP-Headers für das Dokument zugelassen sind, auszuwählen. Das ausgewählte Gerät hat dann die Nutzerberechtigung, sodass es mit MediaDevices.enumerateDevices() aufgelistet und als Audioausgabegerät mit HTMLMediaElement.setSinkId() festgelegt werden kann.

Audiogeräte können beliebig verbunden und getrennt werden. Anwendungen, die auf diese Art von Änderungen reagieren möchten, können das devicechange Ereignis abhören und enumerateDevices() verwenden, um festzustellen, ob sinkId in den zurückgegebenen Geräten vorhanden ist. Dies könnte zum Beispiel das Anhalten oder Fortsetzen der Wiedergabe auslösen.

Schnittstellen

Erweiterungen zu anderen Schnittstellen

Die Audio Output Devices API erweitert die folgenden APIs, indem sie die aufgelisteten Funktionen hinzufügt:

MediaDevices

MediaDevices.selectAudioOutput()

Diese Methode fordert den Benutzer auf, ein spezifisches Audioausgabegerät auszuwählen, zum Beispiel einen Lautsprecher oder ein Headset. Die Auswahl eines Geräts gewährt die Benutzerberechtigung zur Nutzung dieses Geräts und liefert Informationen über das Gerät, einschließlich seiner ID.

HTMLMediaElement

HTMLMediaElement.setSinkId()

Diese Methode setzt die ID des Audiogeräts, das für die Ausgabe verwendet werden soll, sofern dies erlaubt ist.

HTMLMediaElement.sinkId

Diese Eigenschaft gibt die eindeutige ID des Audiogeräts zurück, das für die Ausgabe verwendet wird, oder einen leeren String, wenn das Standard-User-Agent-Gerät verwendet wird.

Sicherheitsanforderungen

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

  • Alle Methoden und Eigenschaften dürfen nur in einem sicheren Kontext aufgerufen werden.

  • MediaDevices.selectAudioOutput() gewährt die Benutzerberechtigung für ein ausgewähltes Gerät als Audioausgabesenke:

  • HTMLMediaElement.setSinkId() setzt eine erlaubte ID als Audioausgang:

    • Der Zugriff kann durch die speaker-selection HTTP Berechtigungspolitik geregelt sein.
    • Benutzerberechtigung ist erforderlich, um eine nicht-standardmäßige Geräte-ID festzulegen.
      • Diese kann aus der Auswahl in der durch MediaDevices.selectAudioOutput() gestarteten Eingabeaufforderung stammen
      • Die Benutzerberechtigung zur Festlegung des Ausgabegeräts wird auch implizit erteilt, wenn der Benutzer bereits die Berechtigung zur Verwendung eines Medieneingabegeräts in derselben Gruppe mit MediaDevices.getUserMedia() erteilt hat.

Beispiele

Hier ist ein Beispiel für die Verwendung von selectAudioOutput(), innerhalb einer Funktion, die durch einen Klick auf eine Schaltfläche ausgelöst wird, und dann das ausgewählte Gerät als Audioausgang festlegt.

Der Code überprüft zuerst, ob selectAudioOutput() unterstützt wird, und verwendet es, um eine Ausgabe auszuwählen und eine Geräte-ID zurückzugeben. Wir spielen dann etwas Audio mit der Standardausgabe ab und rufen anschließend setSinkId() auf, um zum ausgewählten Ausgabegerät zu wechseln.

js
document.querySelector("#myButton").addEventListener("click", async () => {
  if (!navigator.mediaDevices.selectAudioOutput) {
    console.log("selectAudioOutput() not supported or not in secure context.");
    return;
  }

  // Display prompt to select device
  const audioDevice = await navigator.mediaDevices.selectAudioOutput();

  // Create an audio element and start playing audio on the default device
  const audio = document.createElement("audio");
  audio.src = "https://example.com/audio.mp3";
  audio.play();

  // Change the sink to the selected audio output device.
  audio.setSinkId(audioDevice.deviceId);
});

Beachten Sie, dass, wenn Sie die Ausgabendetails protokollieren, diese möglicherweise wie folgt aussehen:

js
console.log(
  `${audioDevice.kind}: ${audioDevice.label} id = ${audioDevice.deviceId}`,
);
// audiooutput: Realtek Digital Output (Realtek(R) Audio) id = 0wE6fURSZ20H0N2NbxqgowQJLWbwo+5ablCVVJwRM3k=

Spezifikationen

Specification
Audio Output Devices API

Browser-Kompatibilität

api.MediaDevices.selectAudioOutput

BCD tables only load in the browser

api.HTMLMediaElement.setSinkId

BCD tables only load in the browser

api.HTMLMediaElement.sinkId

BCD tables only load in the browser

http.headers.Permissions-Policy.speaker-selection

BCD tables only load in the browser