The Audio Output Devices API allows web applications to prompt users about what output device should be used for audio playback.
Concepts and usage
Operating systems commonly allow users to specify that audio should be played from speakers, a Bluetooth headset, or some other audio output device. This API allows applications to provide this same functionality from within a web page.
Even if allowed by a permission policy, access to a particular audio output device still requires explicit user permission, as the user may be in a location where playing audio through some output devices is not appropriate.
Audio devices may arbitrarily connect and disconnect. Applications that wish to react to this kind of change can listen to the devicechange event and use enumerateDevices() to determine if sinkId is present in the returned devices. This might trigger, for example, pausing or unpausing playback.
Interfaces
Extensions to interfaces
The Audio Output Devices API extends the following APIs, adding the listed features:
This method prompts the user to select a specific audio output device, for example a speaker or headset. Selecting a device grants user permission to use that device and returns information about the device, including its ID.
User permission is required to set a non-default device ID.
This can come from selection in the prompt launched by MediaDevices.selectAudioOutput()
User permission to set the output device is also implicitly granted if the user has already granted permission to use a media input device in the same group with MediaDevices.getUserMedia().
Here's an example of using selectAudioOutput(), within a function that is triggered by a button click, and then setting the selected device as the audio output.
The code first checks if selectAudioOutput() is supported, and if it is, uses it to select an output and return a device ID. We then play some audio using the default output, and then call setSinkId() in order to switch to the selected output device.
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 deviceconst audioDevice =await navigator.mediaDevices.selectAudioOutput();// Create an audio element and start playing audio on the default deviceconst 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);});
Note that if you log the output details, they might look something like this:
js
console.log(`${audioDevice.kind}: ${audioDevice.label} id = ${audioDevice.deviceId}`,);// audiooutput: Realtek Digital Output (Realtek(R) Audio) id = 0wE6fURSZ20H0N2NbxqgowQJLWbwo+5ablCVVJwRM3k=