Autoplay Policy Detection

1. Introduction

Currently, this specification only handles HTMLMediaElement (video and audio) and Web Audio API. This specification does not handle Web Speech API and animated image (GIF animation).

2. The Autoplay Detection API

2.1. Autoplay Policy Enum

enum AutoplayPolicy {
  "allowed",
  "allowed-muted",
  "disallowed"
};

2.2. The Autoplay Detection Methods

enum AutoplayPolicyMediaType { "mediaelement", "audiocontext" };

[Exposed=Window]
partial interface Navigator {
  AutoplayPolicy getAutoplayPolicy(AutoplayPolicyMediaType type);
  AutoplayPolicy getAutoplayPolicy(HTMLMediaElement element);
  AutoplayPolicy getAutoplayPolicy(AudioContext context);
};

2.2.1. Query by a Media Type

When getAutoplayPolicy(type) method is called, the user agent MUST run the following steps:

1. If type is mediaelement, return a result that represents the current status for HTMLMediaElement and its extensions, such as HTMLVideoElement and HTMLAudioElement, which exist in the document contained in the Window object associated with the queried Navigator object.
2. If type is audiocontext, return a result that represents the current status for AudioContext, which exist in the document contained in the Window object associated with the queried Navigator object.

If the return value is allowed

All media, corresponding with the given type, are allowed to autoplay.

If the return value is allowed-muted

All inaudible media, corresponding with the given type, are allowed to autoplay.

Note: Currently, this attribute will only be returned when the given media type is mediaelement. The inaudible media means inaudible media element.

If the return value is disallowed

None of media, corresponding with the given type, are allowed to autoplay.

2.2.2. Query by an Element

If the return value is allowed

This element is allowed to autoplay within the current execution context.

If the return value is allowed-muted

This element will only be allowed to autoplay if it’s inaudible.

Note: Currently, this attribute will only be returned when the given element is HTMLMediaElement or its extensions, such as HTMLVideoElement or HTMLAudioElement. The inaudible media means inaudible media element.

In addition, if authors make an inaudible media element audible right after it starts playing, then it is recommended for a user agent to pause that media element immediately because it’s no longer inaudible.

If the return value is disallowed

This element is not allowed to autoplay.

Note: For HTMLMediaElement, if authors call its play(), the returned promise from play() will be rejected with NotAllowedError exception.

For AudioContext, that means its AudioContextState would keep in suspended state.

If the result of querying by a media type is different from the result of querying by an element, authors should take the latter one as the correct result. Example 2 shows a possible scenario.

3. Examples

if (navigator.getAutoplayPolicy("mediaelement") === "allowed") {
  // Create and play a new media element.
} else if (navigator.getAutoplayPolicy("mediaelement") === "allowed-muted") {
  // Create a new media element, and play it in muted.
} else {
  // Autoplay is disallowed, maybe show a poster instead.
}

if (navigator.getAutoplayPolicy("audiocontext") === "allowed") {
  let ac = new AudioContext();
  ac.onstatechange = function() {
    if (ac.state === "running") {
      // Start running audio app.
    }
  }
} else {
  // Audio context is not allowed to start. Display a bit of UI to ask
  // users to start the audio app. Audio starts via calling ac.resume()
  // from a handler, and 'onstatechange' allows knowing when the audio
  // stack is ready.
}

function handlePlaySucceeded() {
  // Update the control UI to playing.
}
function handlePlayFailed() {
  // Show a button to allow users to explicitly start the video and
  // display an image element as poster to replace the video.
}

let video = document.getElementById("video");
switch (navigator.getAutoplayPolicy(video)) {
  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;
}

let ac = new AudioContext();
if (navigator.getAutoplayPolicy(ac) === "allowed") {
  ac.onstatechange = function() {
    if (ac.state === "running") {
      // Start running audio app.
    }
  }
} else {
  // Display a bit of UI to ask users to start the audio app.
  // Audio starts via calling ac.resume() from a handler, and
  // 'onstatechange' allows knowing when the audio stack is ready.
}

4. Security and Privacy Considerations

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.

5. Acknowledgments

The editors would like to thank Alastor Wu, Becca Hughes, Christoph Guttandin, Chris Needham, Chris Pearce, Dale Curtis, Eric Carlson, François Daoust, Frank Liberato, Gary Katsevman, Jean-Yves Avenard, Jer Noble, Mattias Buelens, Mounir Lamouri, Paul Adenot and Tom Jenkinson for their contributions to this specification.