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:- Der Zugriff kann durch die
speaker-selection
HTTP Berechtigungspolitik geregelt sein. - Transiente Benutzeraktivierung ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit die Methode aufgerufen werden kann.
- Der Zugriff kann durch die
-
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.
- Diese kann aus der Auswahl in der durch
- Der Zugriff kann durch die
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.
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:
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