This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
While the specification is feature complete and is expected to be stable, it might evolve based on implementation feedback that will be gathered as its associated test suite evolves. This test suite will be used to build an implementation report of the API; to go into Proposed Recommendation status, the group expects to demonstrate implementation of each feature in at least two deployed browsers. This document will remain a Candidate Recommendation at least until 31 December 2017.
This document was published by the Web Real-Time Communications Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. Comments regarding this document are welcome. Please send them to firstname.lastname@example.org (subscribe, archives). W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 31 December 2017.
Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2017 W3C Process Document.
This section is non-normative.
This section specifies additions to the
HTMLMediaElement [HTML5] when the Audio Output Devices API is supported.
sinkIdof type DOMString, readonly
deviceIdattribute of one of the
MediaDeviceInfovalues returned from
MediaDevices.enumerateDevices()[ GETUSERMEDIA]. The value of this attribute is equal to the argument passed to the last successful execution of
setSinkId(), or the empty string if
setSinkId()has never been called.
When this method is invoked, the user agent must run the following steps:
sinkId is equal to the media element's
attribute, return a promise resolved with
Let promise be a new promise.
Run the following substeps in parallel:
sinkId does not match any audio output device identified by the result that would be provided by
reject promise with a new
DOMException whose name is
NotFoundError and abort these substeps.
If the application is not authorized to play audio through the device identified by
sinkId, reject promise with a new
whose name is
SecurityError and abort these substeps.
Switch the underlying output device for the media element to the device identified by
If the preceding substep failed, reject promise with a new
whose name is
AbortError and abort these substeps.
Update the internal state of the media element so that the value of its
New audio devices may become available to the user agent, or an audio device (identified by a media element's
attribute) that had previously become unavailable may become available again, for example, if it is unplugged and later plugged back in.
In this scenario, the user agent must run the following steps:
Let sinkId be the identifier for the newly available device.
For each media element whose
attribute is equal to
If the media element's
paused attribute is false, start rendering this object's audio out of the device represented by the
The following paragraph is non-normative.
If the application wishes to react to the device change, the application can listen to the
devicechange event and query
This document extends the Web platform with the ability to direct audio output to non-default devices, when authorization is given. Authorization is necessary because playing audio out of a non-default device may be unexpected behavior to the user, and may cause a nuisance. For example, suppose a user is in a library or other quiet public place where she is using a laptop with system audio directed to a USB headset. Her expectation is that the laptop’s audio is private and she will not disturb others. If any Web application can direct audio output through arbitrary output devices, a mischievous website may play loud audio out of the laptop’s external speakers without the user’s consent.
To prevent these kinds of nuisance scenarios, the user agent must acquire the user’s consent to access non-default audio output devices. This would prevent the library example outlined earlier, because the application would not be authorized to play out audio from the system speakers.
The default audio output device is always authorized.
The user agent may explicitly obtain user consent to play audio out of non-default output devices; the details of this process are left to the implementation. For example, one approach could be to add an explicit user prompt of the form "example.com wants to access all your sound output devices".
However, implementations MUST support implicit consent via the
getUserMedia() permission prompt; when an audio input device is authorized and opened via
getUserMedia(), this also authorizes access to any associated audio output devices (i.e., those with the same
groupId). This conveniently handles the common case of wanting to route both input and output audio through a headset or speakerphone device.
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.
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.