Audio Output Devices API

sinkId of type DOMString, readonly

This attribute contains the ID of the audio device through which output is being delivered, or the empty string if output is delivered through the user-agent default device. If nonempty, this ID should be equal to the deviceId attribute of one of the MediaDeviceInfo values returned from enumerateDevices().

On getting, the attribute MUST return the value of the [[SinkId]] slot.

setSinkId

Sets the ID of the audio device through which audio output should be rendered if the application is permitted to play out of a given device.

When this method is invoked, the user agent must run the following steps:

1. Let document be the current settings object's relevant global object's associated Document.

2. If document is not allowed to use the feature identified by "speaker-selection", return a promise rejected with a new DOMException whose name is NotAllowedError.

3. Let element be the HTMLMediaElement object on which this method was invoked.

4. Let sinkId be the method's first argument.

5. If sinkId is equal to element's [[SinkId]], return a promise resolved with undefined.

6. Let p be a new promise.

7. Run the following substeps in parallel:

   1. If sinkId is not the empty string and does not match any audio output device identified by the result that would be provided by enumerateDevices(), reject p with a new DOMException whose name is NotFoundError and abort these substeps.

   2. If sinkId is not the empty string, and the application would not be permitted to play audio through the device identified by sinkId if it weren't the current user agent default device, reject p with a new DOMException whose name is NotAllowedError and abort these substeps.

   3. Switch the underlying audio output device for element to the audio device identified by sinkId.

      Note

      If this substep is successful and the media element's paused attribute is false, audio MUST stop playing out of the device represented by the element's sinkId attribute and will start playing out of the device identified by sinkId

   4. If the preceding substep failed, reject p with a new DOMException whose name is AbortError, and abort these substeps.

   5. Queue a task that runs the following steps:

      1. Set element's [[SinkId]] to sinkId.

      2. Resolve p.

8. Return p.

selectAudioOutput

Prompts the user to select a specific audio output device.

When the selectAudioOutput method is called, the user agent MUST run the following steps:

1. If the relevant global object of this does not have transient activation, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.

2. Let options be the method's first argument.

3. Let deviceId be options.deviceId.

4. Let mediaDevices be this.

5. Let p be a new promise.

6. Run the following steps in parallel:

   1. Let descriptor be a PermissionDescriptor with its name set to "speaker-selection"

   2. If descriptor's permission state is "denied", reject p with a new DOMException whose name attribute has the value NotAllowedError, and abort these steps.

   3. Probe the user agent for available audio output devices.

   4. If there is no audio output device, reject p with a new DOMException whose name attribute has the value NotFoundError and abort these steps.

   5. If deviceId is not "" run the following sub steps:

      1. If deviceId matches a a device id previously exposed by selectAudioOutput in this or an earlier browsing session, or matches a device id of an audio output device with the same groupId as an audio input device previously exposed by getUserMedia() in this or an earlier browsing session, the user agent MAY decide, based on its previous decision of whether to persist this id or not for this set of origins, to run the following sub steps:

         1. Let device be the device identified by deviceId, if available.

         2. If device is available, resolve p with either deviceId or a freshly rotated device id for device, and abort the in-parallel steps.

   6. Prompt the user to choose an audio output device, with descriptor.

   7. If the result of the request is "denied", reject p with a new DOMException whose name attribute has the value NotAllowedError and abort these steps.

   8. Let selectedDevice be the user-selected audio output device.

   9. Let deviceInfo be the result of creating a device info object to represent selectedDevice, with mediaDevices.

   10. Add deviceInfo.deviceId to [[explicitlyGrantedAudioOutputDevices]].

   11. Resolve p with deviceInfo.

7. Return p.

Once a device is exposed after a call to selectAudioOutput, it MUST be listed by enumerateDevices() for the current browsing context.

If the promise returned by selectAudioOutput is resolved, then the user agent MUST ensure the document is both immediately allowed to play media in an HTMLMediaElement, and immediately allowed to start an AudioContext, without needing any additional user gesture.

Note

This is imprecise due to the current lack of standardization of autoplay in browsers.

This dictionary describes the options that can be used to obtain access to an audio output device.

WebIDLdictionary AudioOutputOptions {
  DOMString deviceId = "";
};