MediaDevices: selectAudioOutput() method
========================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`MediaDevices.selectAudioOutput()`** method of the Audio Output Devices API prompts the user to select an audio output device, such as a speaker or headset. If the user selects a device, the method grants user permission to use the selected device as an audio output sink.

Following selection, if the device is available it can be enumerated using `MediaDevices.enumerateDevices()` and set as the audio output sink using `HTMLMediaElement.setSinkId()`.

On success, the returned `Promise` is resolved with a `MediaDeviceInfo` describing the selected device.

Syntax
------


```js
selectAudioOutput()
selectAudioOutput(options)
```

### Parameters

`options` Optional

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

`deviceId` Optional

 A string representing the ID of a single previously exposed/permitted device.
 If not set, a prompt with all available audio output devices will be displayed.


 The option is intended for applications that want to store a device id so that the same device can be used by default in future sessions.
 Note that the method may return a new ID for the same device, and that persisted ids *must be passed* through `selectAudioOutput()` successfully before they will work with `setSinkId()`.


**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.
 If permission for the specified device was previously granted but has since been revoked, the user-agent might display all allowed devices, highlighting the one with the specified ID.




### Return value

A `Promise` that is fulfilled with a `MediaDeviceInfo` object that describes the audio output device selected by the user.

### Exceptions

`NotAllowedError` `DOMException`

Returned if a `speaker-selection` Permissions Policy is used to block use of audio outputs (in addition the popup for selecting an audio output won't be displayed), or the user closed the selection prompt without choosing a device.

`NotFoundError` `DOMException`

Returned if there are no available audio output devices.

`InvalidStateError` `DOMException`

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

Security requirements
---------------------

Access to the API is subject to the following constraints:

* The method must be called in a secure context.
* Transient user activation is required.
 The user has to interact with the page or a UI element for this feature to work.
* Access may be gated by the `speaker-selection` HTTP Permission Policy.

The permission status can be queried using the Permissions API method `navigator.permissions.query()`, passing a permission descriptor with the `speaker-selection` permission.

Examples
--------

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


```js
document.querySelector("#myButton").addEventListener("click", () => {
  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((err) => {
      console.error(`${err.name}: ${err.message}`);
    });
});
```


On selection of an output this might produce:


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

Specifications
--------------

| Specification |
| --- |
| Audio Output Devices API # dom-mediadevices-selectaudiooutput |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `HTMLMediaElement.setSinkId()`
* `HTMLMediaElement.sinkId`
* WebRTC - the introductory page to the API