Abstract

This document defines a set of JavaScript APIs that let a Web application manage how audio is rendered on the user audio output devices.

Status of This Document

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/.

The WebRTC and Device and Sensors Working Group intend to publish this specification as a Candidate Recommendation soon. Consequently, this is a Request for wide review of this document.

This document was published by the Device and Sensors Working Group and the Web Real-Time Communications Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-media-capture@w3.org (subscribe, archives). All comments are welcome.

Publication as a Working Draft 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 groups operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (Device and Sensors Working Group) and a public list of any patent disclosures (Web Real-Time Communications Working Group) made in connection with the deliverables of each group; these pages also include 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 September 2015 W3C Process Document.

1. Introduction

This section is non-normative.

This proposal allows JavaScript to direct the audio output of a media element to authorized devices other than the system or user agent default. This can be helpful in a variety of real-time communication scenarios as well as general media applications. For example, an application can use this API to programmatically direct output to a device such as a Bluetooth headset or speakerphone.

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);
};

Attributes

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 . 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.

Methods

setSinkId
Sets the ID of the audio device through which audio output should be rendered if the application is authorized to play out of a given device.
Parameter Type Nullable Optional Description
sinkId DOMString The ID corresponding to the audio output device. The empty string represents the user agent default.
Return type: Promise<void>

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.

2.1 Algorithms

2.1.1 Sink no longer available

The audio device identified by a media element's sinkId attribute may become unavailable, for example if it is unplugged.

When the audio device identified by the sinkId attribute is no longer available, the user agent must take no action. For example, if the media element's paused attribute is false when the device identified by the sinkId is no longer available, then playback will continue as normal. In this case, audio will not be rendered because the device to which the media element is attached is unavailable.

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 enumerateDevices() for the list of updated devices. If the value of the media element's sinkId attribute is no longer present as the deviceId attribute in the returned list of MediaDeviceInfos, the device is no longer available and the application can choose to react accordingly.

2.1.2 New sink available

New audio devices may become available to the user agent, or an audio device (identified by a media element's sinkId 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:

  1. Let sinkId be the identifier for the newly available device.

  2. For each media element whose sinkId attribute is equal to sinkId:

    1. If the media element's paused attribute is false, start rendering this object's audio out of the device represented by the sinkId attribute.

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 enumerateDevices() for the list of updated devices.

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.

A. References

A.1 Normative references

[GETUSERMEDIA]
Daniel Burnett; Adam Bergkvist; Cullen Jennings; Anant Narayanan; Bernard Aboba. W3C. Media Capture and Streams. 19 May 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/mediacapture-streams/
[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. HTML5. 28 October 2014. W3C Recommendation. URL: https://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]
Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. Web IDL. 15 December 2016. W3C Working Draft. URL: https://www.w3.org/TR/WebIDL-1/