Audio Output Devices API

Betriebssysteme erlauben es Benutzern häufig, festzulegen, dass Audio von Lautsprechern, einem Bluetooth-Headset oder einem anderen Audioausgabegerät abgespielt werden soll. Diese API erlaubt es Anwendungen, diese Funktion auch innerhalb einer Webseite bereitzustellen.

Auch wenn es durch eine Berechtigungsrichtlinie erlaubt ist, erfordert der Zugriff auf ein bestimmtes Audioausgabegerät dennoch eine explizite Benutzererlaubnis, da sich der Benutzer an einem Ort befinden kann, an dem das Abspielen von Audio über bestimmte Ausgabegeräte nicht angemessen ist.

Die API bietet die Methode MediaDevices.selectAudioOutput(), die es Benutzern ermöglicht, ihre gewünschte Audioausgabe aus den durch die speaker-selection-Direktive des Permissions-Policy HTTP-Headers für das Dokument erlaubten Möglichkeiten zu wählen. Das ausgewählte Gerät hat dann die Benutzererlaubnis, was es ermöglicht, es mit MediaDevices.enumerateDevices() aufzulisten und als Audioausgabegerät mit HTMLMediaElement.setSinkId() festzulegen.

Audiogeräte können zufällig verbunden und getrennt werden. Anwendungen, die auf solche Ä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 beispielsweise dazu führen, dass die Wiedergabe pausiert oder fortgesetzt wird.

Die Audio Output Devices API erweitert die folgenden APIs und fügt die aufgelisteten Funktionen hinzu:

MediaDevices

MediaDevices.selectAudioOutput()

Diese Methode fordert den Benutzer auf, ein bestimmtes Audioausgabegerät auszuwählen, beispielsweise einen Lautsprecher oder ein Headset. Das Auswählen eines Geräts erteilt die Benutzererlaubnis zur Verwendung dieses Geräts und gibt Informationen über das Gerät zurück, einschließlich seiner ID.

HTMLMediaElement

HTMLMediaElement.setSinkId()

Diese Methode legt die ID des zu verwendenden Audiogeräts für die Ausgabe fest, sofern dies erlaubt ist.

HTMLMediaElement.sinkId

Diese Eigenschaft gibt die eindeutige ID des für die Ausgabe verwendeten Audiogeräts zurück oder einen leeren String, wenn das standardmäßige Benutzeragentengerät verwendet wird.

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() erteilt die Benutzererlaubnis, dass ein ausgewähltes Gerät als Audioausgabesenke verwendet werden darf:

  • Der Zugriff kann durch die speaker-selection HTTP-Berechtigungsrichtlinie beschränkt werden.
  • Eine transient user activation ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit die Methode aufgerufen wird.

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

  • Der Zugriff kann durch die speaker-selection HTTP-Berechtigungsrichtlinie beschränkt werden.
  • Es ist eine Benutzererlaubnis erforderlich, um eine nicht standardmäßige Geräte-ID festzulegen.
    • Diese erfolgt möglicherweise durch die Auswahl in der von MediaDevices.selectAudioOutput() ausgelösten Aufforderung.
    • Die Benutzererlaubnis zur Festlegung des Ausgabegeräts wird auch implizit erteilt, wenn der Benutzer bereits die Erlaubnis erteilt hat, ein Medieneingabegerät in derselben Gruppe mit MediaDevices.getUserMedia() zu verwenden.

Hier ist ein Beispiel zur Nutzung von selectAudioOutput(), innerhalb einer Funktion, die durch einen Buttonklick ausgelöst wird, und dann das ausgewählte Gerät als Audioausgabe festlegt.

Der Code prüft zuerst, ob selectAudioOutput() unterstützt wird und nutzt es, um eine Ausgabe auszuwählen und eine device ID zurückzugeben. Wir spielen dann etwas Audio mit der standardmäßigen Ausgabe ab und rufen dann setSinkId() auf, um zum ausgewählten Ausgabegerät zu wechseln.

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 beim Protokollieren der Ausgabedetails diese möglicherweise folgendermaßen aussehen:

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