Audio Output Devices API

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, which may provide a better user experience.

Setting a particular audio output device requires explicit user permission, as the user may be in a location where playing audio is not appropriate through some output devices. For more information see Security requirements below.

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.

The Audio Output Devices API extends the following APIs, adding the listed features:

MediaDevices.selectAudioOutput()

This method prompts the user to select a specific audio output device, for example a speaker or headset.

HTMLMediaElement.setSinkId()

This method sets the ID of the audio device to use for output, which will be used if permitted.

HTMLMediaElement.sinkId

This property returns the unique ID of the audio device being used for output, or an empty string if the default user agent device is being used.

Access to MediaDevices.selectAudioOutput() is subject to the following constraints:

• It may only be used in a secure context.
• Access may be gated by the speaker-selection HTTP Permission Policy.
• Transient user activation is required. The user has to interact with the page or a UI element for this feature to work.
• The user must explicitly grant permission to use the audio output device through a user-agent specific mechanism, or have previously granted permission. Note that if access is denied by a permission policy it cannot be granted by a user permission.

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, using MediaDevices.getUserMedia().

Other methods/properties also require a secure context and the speaker-selection 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.