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 http://www.w3.org/TR/.

This is the First Public Working Draft of the Audio Output Devices API, describing an early proposal on how to bring audio output device management to existing media producing APIs on the Web. This document is not complete. It is subject to major changes and, while early experimentations are encouraged, it is therefore not intended for implementation.

This document was published by the Web Real-Time Communication Working Group and Device APIs Working Group as a First Public 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 First Public 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 a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (Web Real-Time Communication Working Group, Device APIs Working Group) 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 August 2014 W3C Process Document.

Table of Contents

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 : EventTarget {
    readonly    attribute DOMString sinkId;
    Promise<void> setSinkId (DOMString sinkId);

2.1 Attributes

sinkId of type DOMString, readonly
The unique ID of the audio device through which output is being delivered, or empty string if it is using the user agent default. This ID should be one of the MediaDeviceInfo.deviceId values returned from MediaDevices.enumerateDevices() [GETUSERMEDIA], or one of the predefined IDs listed below.

2.2 Methods

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.
sinkIdDOMString The id corresponding to the audio output device.
Return type: Promise<void>

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

  1. If sinkId and the sinkId attribute are the same object, return a resolved promise.

  2. If the sinkId does not match any audio output device identified by enumerateDevices(), return a promise rejected with a new DOMException whose name is NotFoundError.

  3. If application is not authorized to play audio through the device identified by the given sinkId, return a promise rejected with a new DOMException whose name is SecurityError.

  4. Let promise be a new promise.

  5. Run the following steps asynchronously:

    1. Associate the audio output device represented by sinkId with this object for playout.

    2. If the preceding step failed, return a rejected promise.

    3. If the media element's paused attribute is false, stop playing this object's audio out of the device represented by the sinkId attribute.

    4. Set the sinkId attribute to sinkId.

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

    6. Resolve promise.

  6. Return promise.

2.3 Algorithms

2.3.1 Sink no longer available

The audio device associated with HTMLMediaElement.sinkId 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. Of course, 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 HTMLMediaElement.sinkId is no longer present in the list of MediaDeviceInfo.deviceIds returned, the device is no longer available and the application can choose to react accordingly.

2.3.2 New sink available

New audio devices may become available to the user agent, or an audio device (identified by HTMLMediaElement.sinkId) 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 sinkId whose value 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. Web Audio API Extensions

This is a work in progress. The following section discusses the options for additions to and modifications of the Web Audio API [WEBAUDIO] when the Audio Output Devices API is supported.

3.1 Implementation Options

There are many ways that this functionality could be extended to Web Audio. This section lists several different options and is open for discussion.

See also this issue in the Web Audio issue tracker regarding the handling of output devices by Web Audio.

3.1.1 Constructor argument

Option 1: AudioContext constructor argument

  • The sink ID is passed as an argument to the AudioContext constructor, e.g.

    new AudioContext({ sinkId: requestedSinkId });

    By requiring the sink ID to be set at construction time, this simplifies the implementation, since the output sample rate is fixed.
  • Limitation: this implies the graph must be recreated if the output device changes.
  • Limitation: can’t play audio out of multiple devices at once (assuming application is written with a standard single AudioContext).

3.1.2 setSinkId()

Option 2a: AudioContext.setSinkId()

Option 2b: AudioDestinationNode.setSinkId()

3.1.3 addSinkId()/removeSinkId()

Option 3a: AudioContext.addSinkId()/removeSinkId()

  • Benefit over setSinkId: Audio can be piped through multiple devices.

Option 3b: AudioDestinationNode.addSinkId()/removeSinkId()

3.1.4 No change to spec

4. Predefined Device IDs

User agents must also support the following predefined pseudo-identifiers which reference an abstract device. For example, if the application wants to route audio to a headset, but doesn't care exactly which headset, it can use the predefined id for the system communications device.

4.1 MediaDeviceId Enum

enum MediaDeviceId {
Enumeration description
id-multimediaIndicates the system multimedia playout device. This is the default, i.e., equivalent to not setting the sink id, or setting it to "".
id-communicationsIndicates the system audio communications device, if one exists, typically a headset of some sort. [NOTE: what should happen if the system does not support this concept, but does know about headsets?]

5. Privacy Considerations

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

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.

A. References

A.1 Normative references

Daniel Burnett; Adam Bergkvist; Cullen Jennings; Anant Narayanan. Media Capture and Streams. 3 September 2013. W3C Working Draft. URL: http://www.w3.org/TR/mediacapture-streams/
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
Paul Adenot; Chris Wilson; Chris Rogers. Web Audio API. 10 October 2013. W3C Working Draft. URL: http://www.w3.org/TR/webaudio/
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/