2. HTMLMediaElement Extensions

This section specifies additions to the HTMLMediaElement [HTML5] when the Audio Output Devices API is supported.

partial interface HTMLMediaElement {
    readonly attribute DOMString sinkId;
    Promise<void> setSinkId(DOMString sinkId);
};

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

1. If sinkId is equal to the media element's sinkId attribute, return a promise resolved with undefined.

2. Let promise be a new promise.

3. Run the following substeps in parallel:

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

   2. If the application is not authorized to play audio through the device identified by sinkId, reject promise with a new DOMException whose name is SecurityError and abort these substeps.

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

      Note

      If this substep is successful and the media element's paused attribute is false, audio will 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 promise with a new DOMException whose name is AbortError and abort these substeps.

   5. Update the internal state of the media element so that the value of its sinkId attribute corresponds to sinkId.

   6. Resolve promise.

4. Return promise.

3. Privacy Considerations

4. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key word MUST is to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

5. Acknowledgments

The following people have contributed directly to the development of this specification: Harald Alvestrand, Rick Byers, Dominique Hazael-Massieux (via the HTML5Apps project), Philip Jägenstedt, Victoria Kirst, Shijun Sun, Martin Thomson, Chris Wilson.