MediaDevices.selectAudioOutput()

The MediaDevices method selectAudioOutput() prompts the user to select a specific audio output device, for example a speaker or headset. On success, the returned Promise is resolved with a MediaDeviceInfo describing the selected device.

The method must be triggered from some UI interaction like a button click (more precisely, it requires transient activation).

Access to audio output devices is gated by the Permissions API. The prompt will not be displayed if the speaker-selection permission has not been granted.

Syntax

navigator.mediaDevices.selectAudioOutput()
navigator.mediaDevices.selectAudioOutput(options)

Parameters

options Optional

An object that configures what device(s) may be offered in the user prompt.

deviceId Optional

A DOMString representing the id of the (only) device to display in the prompt (with default value: "").

Note: A user agent may choose to skip prompting the user if a specified non-null id was previously exposed to the user by selectAudioOutput() in an earlier session. In this case the user agent may simply resolve with this device id, or a new id for the same device if it has changed.

This is intended for applications that want to use persisted device ids. The ids must be passed through selectAudioOutput() successfully before they will work with setSinkId().

Return value

A Promise that receives a MediaDeviceInfo object when the promise is fulfilled. The object describes the user-selected audio output device.

Exceptions

NotAllowedError DOMException

Thrown if the current page has not been granted the speaker-selection permission or the user closed the selection prompt without choosing a device.

NotFoundError DOMException

Thrown if there are no available audio output devices.

InvalidStateError DOMException

Thrown if there hasn't been a transient activation (you must trigger it from some kind of UI event).

Example

Here's an example of using selectAudioOutput(), which you might call within a function that is triggered by a button click. It outputs the selected device IDs and labels (if available) or an error message.

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(function(err) {
  console.log(err.name + ": " + err.message);
});

On selection of an output this might produce:

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

Specifications

Browser compatibility

See also

• WebRTC - the introductory page to the API