Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This document defines a set of JavaScript APIs that let a Web application manage how audio is rendered on the user audio output devices.
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 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 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.
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.
HTMLMediaElement ExtensionsThis 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);
};
sinkId of type DOMString, readonly MediaDeviceInfo.deviceIdMediaDevices.enumerateDevices()GETUSERMEDIAsetSinkId| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| sinkId | DOMString |
✘ | ✘ | The id corresponding to the audio output device. |
Promise<void>When this method is invoked, the user agent must run the following steps:
If sinkId and the sinkId attribute are the same object, return a resolved promise.
Let promise be a new promise.
Run the following steps asynchronously:
If sinkId does not match any audio output device identified by enumerateDevices(), reject promise with a new DOMException whose name is NotFoundError.
If application is not authorized to play audio through the device identified by sinkId, reject promise with a new DOMException whose name is SecurityError.
Associate the audio output device represented by sinkId with this object for playout.
If the preceding step failed, reject promise with a new DOMException whose name is AbortError.
If the media element's paused attribute is false, stop playing this object's audio out of the device represented by the sinkId attribute.
Set the sinkId attribute to sinkId.
If the media element's paused attribute is false, start playing this object's audio out of the device represented by sinkId.
Resolve promise.
Return promise.
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:
Let sinkId be the identifier for the newly available device.
For each sinkId whose value is equal to sinkId:
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.
This is a work in progress. This section discusses modifications of the Web Audio API [WEBAUDIO] when the Audio Output Devices API is supported.
AudioContext constructor argumentAudioContext constructor, e.g., new AudioContext({ sinkId: requestedSinkId });sinkId is provided, use the default device of the user agent.sinkId is the empty string, use the default device of the user agent.sinkId does not match any audio output device identified by enumerateDevices(), throw a DOMException whose name is NotFoundError.sinkId, throw a DOMException whose name is SecurityError.sinkId cannot be used due to a unspecified error, throw a DOMException whose name is AbortError.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.
enum MediaDeviceId {
"id-multimedia",
"id-communications"
};
| Enumeration description | |
|---|---|
id-multimedia |
Indicates the system multimedia playout device. This is the default, i.e., equivalent to not setting the sink id, or setting it to "". |
id-communications |
Indicates 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?] |
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 MediaDeviceInfo.groupId). This conviently 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.
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 developmment 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.