diff --git a/index.bs b/index.bs
new file mode 100644
index 0000000..6926d4b
--- /dev/null
+++ b/index.bs
@@ -0,0 +1,332 @@
+
+Title: Autoplay Policy Detection
+Shortname: autoplay-detection
+Level: 1
+Status: w3c/ED
+Group: mediawg
+URL: http://example.com/url-this-spec-will-live-at
+Editor: Alastor Wu, Mozilla https://www.mozilla.org, alwu@mozilla.com
+Editor: Paul Adenot, Mozilla https://www.mozilla.org, padenot@mozilla.com
+Abstract: This specification provides web developers the ability to detect if automatically starting the playback of a media file is allowed in different situations.
+Markup Shorthands: markdown on
+
+
+
+
+
Introduction
+ Most user-agents have their own mechanisms to block autoplaying media, and those
+ mechanisms are implementation-specific. Web developers need to have a way to
+ detect if autoplaying media is allowed or not in order to make actions, such
+ as selecting alternate content or improving the user experience while media
+ is not allowed to autoplay. For instance, if a user-agent only blocks audible
+ autoplay, then web developers can replace audible media with inaudible media
+ to keep media playing, instead of showing a blocked media which looks like a
+ still image to users. If the user-agent does not allow any autoplay media,
+ then web developers could stop loading media resources and related tasks to
+ save the bandwidth and CPU usage for users.
+
+ Currently, this specification only handles {{HTMLMediaElement}} (<{video}>
+ and <{audio}>) and does not handle [[webaudio inline]], [[speech-api inline]]
+ and animated <{image}> (GIF animation). Although the result from the document's
+ {{Document/autoplayPolicy}} can be used to detect whether web audio can be
+ started if user-agents block web audio from autoplaying.
+
+
The Autoplay Detection API
+ Autoplay detection can be performed on either the {{Document}} element or on
+ the {{HTMLMediaElement}}. The former provides a general idea to authors to
+ know if autoplay media is allowed on this document element. If the page
+ contains multiple documents, an implementation can decide to return different
+ results for each of them. The latter provides more accurate result for whether
+ the autoplay is allowed on a specific media element.
+
+
+ Inaudible media element are allowed to autoplay. An
+ inaudible media element is an {{HTMLMediaElement}}
+ that has any of the following conditions:
+
+ Note: The autoplay policy represents the current status of whether a
+ user-agent allows media to autoplay, which can **vary** in the future.
+ Therefore, it is **recommended** that authors check the result every time
+ they want to have an up-to-date result.
+
+
+
+ If a user-agent uses the user activation, described in
+ [[HTML#user-activation-data-model]], to determine if the autoplay media
+ are allowed or not, and it blocks all autoplay by default
+ ({{AutoplayPolicy/disallowed}}). Then the policy can change to
+ {{AutoplayPolicy/allowed}} or {{AutoplayPolicy/allowed-muted}} after a
+ user performs a supported user gesture on the page or the media.
+
+ This represents a rough status of whether media that belong to this
+ {{Document}} are allowed to autoplay or not.
+
+
+
If the value is {{allowed}}
+
+ All media that belong to this document are allowed to autoplay.
+
+
+
If the value is {{allowed-muted}}
+
+ All {{inaudible media element}} that belong to this document are allowed
+ to autoplay.
+
+
+
If the value is {{disallowed}}
+
+ **None** of media belongs to this document are allowed to autoplay.
+
+
+
+
+ Note: Depending on the implementation, it's still possible for some media
+ that exist on the same document to be allowed to autoplay when the
+ document {{Document/autoplayPolicy}} returns {{disallowed}}. It is
+ **recommended** that authors check each media element’s autoplayPolicy
+ in order to get a complete result when document’s autoplayPolicy is
+ disallowed, if authors want to use that as a result to determine whether
+ media can be started playing.
+
+
+
+ Some user-agents may not allow any media to autoplay by default, but allow
+ autoplay on those media elements which have been clicked by users. In this
+ case, at first, both the document's {{Document/autoplayPolicy}} and the
+ media element's {{HTMLMediaElement/autoplayPolicy}} will be {{disallowed}}.
+
+ However, after a user clicks on a media element, then this media element's
+ {{HTMLMediaElement/autoplayPolicy}} might become {{allowed}} if a
+ user-agent decides to bless this element because that seems intended by
+ users. In this case, the document's {{Document/autoplayPolicy}} and other
+ media elements' {{HTMLMediaElement/autoplayPolicy}} (if any), which
+ haven't been clicked yet and are on the same document, will still be
+ {{disallowed}}.
+
+
+
+ Note: If the document has child documents, then the result from child
+ documents could be different from the result of their parent documents
+ depending on the implementation.
+
+
+
+ Assume that the top level document A in `foo.com` returns {{allowed}} and
+ it has an embedded iframe, which has another document B from `bar.com`. A
+ user-agent could either make child document B return the same result that
+ is inherited from the top level document A. Or make the document B return
+ a different result, eg. {{disallowed}}.
+
+ Doing the former helps to lower the complexity and make the behavior of
+ blocking autoplay more consistent. The latter helps providing a
+ finer-grained autoplay control.
+
+
+
+ Note: In addition, document's {{Document/autoplayPolicy}} can also be
+ used to know whether [[webaudio inline]] can be allowed to start if a
+ user-agent blocks web audio by default.
+
+
+
+ [Web Audio](https://webaudio.github.io/web-audio-api/#allowed-to-start)
+ uses [=sticky activation=] to determine if {{AudioContext}} can be allowed
+ to start. If the document is allowed to autoplay, then {{AudioContext}}
+ should also be allowed to start.
+
+
+ var ac = new AudioContext;
+ if (document.autoplayPolicy === "allowed") {
+ ac.onstatechange = function() {
+ if (ac.state === "running") {
+ // Start running audio app
+ } else {
+ // Display a bit of UI to ask the user to start the audio app.
+ // Audio starts via calling ac.resume() from a handler, and
+ // 'onstatechange' allows knowing when the audio stack is ready.
+ }
+ }
+ }
+
+ This represents the current status of whether this {{HTMLMediaElement}} is
+ allowed to autoplay or not.
+
+
+
If the value is {{allowed}}
+
+ This media element is allowed to autoplay within the current execution
+ context.
+
+
+
If the value is {{allowed-muted}}
+
+ This media element will only be allowed to autoplay if it's an
+ {{inaudible media element}}. If authors make this media element audible
+ right after the media element started playing, then the user-agent
+ **MUST** pause this media element immediately because it's no longer
+ inaudible.
+
+
+
If the value is {{disallowed}}
+
+ This media element is not allowed to autoplay. If authors call its
+ {{HTMLMediaElement/play()}}, the returned promise from
+ {{HTMLMediaElement/play()}} will be rejected with {{NotAllowedError}}
+ exception.
+
+
+
+ If the media element's {{HTMLMediaElement/autoplayPolicy}} is different from
+ the document's {{Document/autoplayPolicy}}, the media element's
+ {{HTMLMediaElement/autoplayPolicy}} overrides the document's
+ {{Document/autoplayPolicy}}.
+
+
Examples
+
+ Example of using Document's {{Document/autoplayPolicy}}
+
+ Example of using HTMLMediaElement's {{HTMLMediaElement/autoplayPolicy}}
+
+ function handlePlaySucceeded() {
+ // Update the control UI to playing
+ }
+ function handlePlayFailed() {
+ // Show a button to allow users to explicitly start the video and
+ // display a image element as poster to replace the video
+ }
+
+ let video = document.getElementById("video");
+ switch (video.autoplayPolicy) {
+ case "allowed":
+ video.src = "video.webm";
+ video.play().then(handlePlaySucceeded, handlePlayFailed);
+ break;
+ case "allowed-muted":
+ video.src = "video.webm";
+ video.muted = true;
+ video.play().then(handlePlaySucceeded, handlePlayFailed);
+ break;
+ default:
+ // Autoplay is not allowed, no need to download the resource.
+ handlePlayFailed();
+ break;
+ }
+
+
+
+
Security and Privacy Considerations
+ Per the [[security-privacy-questionnaire#questions]].
+
+ The API introduced in this specification has very low impact with regards to
+ security and privacy. It does not expose any sensitive information that can be
+ used to to identify users. It does not expose any ability to control sensors
+ and any users' devices. It does not introduce any new state for an origin that
+ will persist across browsing sessions. It does not allow an origin to send any
+ data to the underlying platform. It does not introduce or enable new script
+ execution and loading mechanism. It does not allow an origin to draw over a
+ user-agent's native UI. It does not allow an origin to detect if users are in
+ the private or non-private browsing mode.
+
+
Acknowledgments
+ This specification is the collective work of the W3C media Working Group.
+
+ The editors would like to thank Alastor Wu, Becca Hughes, Chris Needham,
+ Chris Pearce, Dale Curtis, Eric Carlson, Gary Katsevman, Jer Noble, Mattias Buelens,
+ Mounir Lamouri, Paul Adenot and Tom Jenkinson for their contributions to this
+ specification.
diff --git a/index.html b/index.html
new file mode 100644
index 0000000..8632874
--- /dev/null
+++ b/index.html
@@ -0,0 +1,1141 @@
+
+
+
+
+ Autoplay Policy Detection
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
This specification provides web developers the ability to detect if automatically starting the playback of a media file is allowed in different situations.
+
+
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/.
+
Feedback and comments on this specification are welcome. GitHub Issues are preferred for discussion on this specification. Alternatively, you can send comments to the Media Working Group’s mailing-list, public-media-wg@w3.org (archives).
+ This draft highlights some of the pending issues that are still to be discussed in the working group.
+ No decision has been taken on the outcome of these issues including whether they are valid.
+
This document was published by the Media Working Group as an Editor’s Draft.
+ This document is intended to become a W3C Recommendation.
+
Publication as an Editor’s 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 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.
+ Most user-agents have their own mechanisms to block autoplaying media, and those
+ mechanisms are implementation-specific. Web developers need to have a way to
+ detect if autoplaying media is allowed or not in order to make actions, such
+ as selecting alternate content or improving the user experience while media
+ is not allowed to autoplay. For instance, if a user-agent only blocks audible
+ autoplay, then web developers can replace audible media with inaudible media
+ to keep media playing, instead of showing a blocked media which looks like a
+ still image to users. If the user-agent does not allow any autoplay media,
+ then web developers could stop loading media resources and related tasks to
+ save the bandwidth and CPU usage for users.
+
Currently, this specification only handles HTMLMediaElement (video and audio) and does not handle Web Audio API, Web Speech API and animated image (GIF animation). Although the result from the document’s autoplayPolicy can be used to detect whether web audio can be
+ started if user-agents block web audio from autoplaying.
+
2. The Autoplay Detection API
+ Autoplay detection can be performed on either the Document element or on
+ the HTMLMediaElement. The former provides a general idea to authors to
+ know if autoplay media is allowed on this document element. If the page
+ contains multiple documents, an implementation can decide to return different
+ results for each of them. The latter provides more accurate result for whether
+ the autoplay is allowed on a specific media element.
+
Note: The autoplay policy represents the current status of whether a
+ user-agent allows media to autoplay, which can vary in the future.
+ Therefore, it is recommended that authors check the result every time
+ they want to have an up-to-date result.
+
If a user-agent uses the user activation, described in HTML 5 §6.3.1 Data model, to determine if the autoplay media
+ are allowed or not, and it blocks all autoplay by default
+ (disallowed). Then the policy can change to allowed or allowed-muted after a
+ user performs a supported user gesture on the page or the media.
None of media belongs to this document are allowed to autoplay.
+
+
Note: Depending on the implementation, it’s still possible for some media
+ that exist on the same document to be allowed to autoplay when the
+ document autoplayPolicy returns disallowed. It is recommended that authors check each media element’s autoplayPolicy
+ in order to get a complete result when document’s autoplayPolicy is
+ disallowed, if authors want to use that as a result to determine whether
+ media can be started playing.
+
+ Some user-agents may not allow any media to autoplay by default, but allow
+ autoplay on those media elements which have been clicked by users. In this
+ case, at first, both the document’s autoplayPolicy and the
+ media element’s autoplayPolicy will be disallowed.
+
However, after a user clicks on a media element, then this media element’s autoplayPolicy might become allowed if a
+ user-agent decides to bless this element because that seems intended by
+ users. In this case, the document’s autoplayPolicy and other
+ media elements' autoplayPolicy (if any), which
+ haven’t been clicked yet and are on the same document, will still be disallowed.
+
+
Note: If the document has child documents, then the result from child
+ documents could be different from the result of their parent documents
+ depending on the implementation.
+
+ Assume that the top level document A in foo.com returns allowed and
+ it has an embedded iframe, which has another document B from bar.com. A
+ user-agent could either make child document B return the same result that
+ is inherited from the top level document A. Or make the document B return
+ a different result, eg. disallowed.
+
Doing the former helps to lower the complexity and make the behavior of
+ blocking autoplay more consistent. The latter helps providing a
+ finer-grained autoplay control.
+
+
Note: In addition, document’s autoplayPolicy can also be
+ used to know whether Web Audio API can be allowed to start if a
+ user-agent blocks web audio by default.
var ac =new AudioContext;
+if(document.autoplayPolicy ==="allowed"){
+ ac.onstatechange =function(){
+ if(ac.state ==="running"){
+ // Start running audio app
+ }else{
+ // Display a bit of UI to ask the user to start the audio app.
+ // Audio starts via calling ac.resume() from a handler, and
+ // 'onstatechange' allows knowing when the audio stack is ready.
+ }
+ }
+}
+
This media element will only be allowed to autoplay if it’s an inaudible media element. If authors make this media element audible
+ right after the media element started playing, then the user-agent MUST pause this media element immediately because it’s no longer
+ inaudible.
+
This media element is not allowed to autoplay. If authors call its play(), the returned promise from play() will be rejected with NotAllowedError exception.
+
function handlePlaySucceeded(){
+ // Update the control UI to playing
+}
+function handlePlayFailed(){
+ // Show a button to allow users to explicitly start the video and
+ // display a image element as poster to replace the video
+}
+
+let video = document.getElementById("video");
+switch(video.autoplayPolicy){
+ case"allowed":
+ video.src ="video.webm";
+ video.play().then(handlePlaySucceeded, handlePlayFailed);
+ break;
+ case"allowed-muted":
+ video.src ="video.webm";
+ video.muted =true;
+ video.play().then(handlePlaySucceeded, handlePlayFailed);
+ break;
+ default:
+ // Autoplay is not allowed, no need to download the resource.
+ handlePlayFailed();
+ break;
+}
+
The API introduced in this specification has very low impact with regards to
+ security and privacy. It does not expose any sensitive information that can be
+ used to to identify users. It does not expose any ability to control sensors
+ and any users' devices. It does not introduce any new state for an origin that
+ will persist across browsing sessions. It does not allow an origin to send any
+ data to the underlying platform. It does not introduce or enable new script
+ execution and loading mechanism. It does not allow an origin to draw over a
+ user-agent’s native UI. It does not allow an origin to detect if users are in
+ the private or non-private browsing mode.
The editors would like to thank Alastor Wu, Becca Hughes, Chris Needham,
+ Chris Pearce, Dale Curtis, Eric Carlson, Gary Katsevman, Jer Noble, Mattias Buelens,
+ Mounir Lamouri, Paul Adenot and Tom Jenkinson for their contributions to this
+ specification.