Navigator: getAutoplayPolicy() method

The method must be called with one (and only one) of the following three parameters:

type Optional

A string indicating the media playing feature for which the broad autoplay policy is required.

The supported values are:

mediaelement

Get the broad autoplay policy for media elements in the document. Media elements are HTMLMediaElement derived objects such as HTMLAudioElement and HTMLVideoElement, and their corresponding tags <audio> and <video>.

audiocontext

Get the broad autoplay policy for Web Audio API players in the document.

element Optional

A specific media element. This must be an HTMLMediaElement, including derived elements such as HTMLVideoElement and HTMLAudioElement.

context Optional

A specific AudioContext.

A string indicating the autoplay policy for the specified media feature type, element, or context. This will be a string containing one of the following values:

allowed

Autoplay is allowed.

allowed-muted

Autoplay is allowed only for inaudible media. This includes media that has no audio track, or for which the audio has been muted.

disallowed

Autoplay is not allowed.

Note that the autoplay policy returned for a type parameter is the broad policy for items of the indicated type. On page load, all items of a type will have the same policy as the type. Once the user has interacted with the page/site, on some browsers individual items may have a different policy to the corresponding type.

TypeError

The object passed to the method is not an allowed type. The allowed types include HTMLMediaElement (or a derived element such as HTMLVideoElement and HTMLAudioElement), or AudioContext.

"Autoplay" refers to any feature that causes content to begin to play without the user specifically requesting that playback begin. This includes the autoplay attribute in the HTML <video> and <audio> elements, and using JavaScript code to start playback without any user interaction.

User agents commonly block autoplay, or only allow inaudible content to autoplay, because unexpected sounds when a page first loads can result in a jarring and unpleasant user experience. The mechanisms used to determine whether content can autoplay or not, or only play for inaudible content, differ between user agents.

The getAutoplayPolicy() method provides a standard mechanism to determine the policy for a particular user agent to autoplay a particular type or item of content. This enables application customization such as automatic muting of video on sites where autoplay of audible content is not allowed, or modifying the application to behave without autoplay.

The recommended use of the method is to call it on page load (or before the content playing elements are created) specifying the type of feature to check, and then configuring autoplay of media elements based on the result. For example, if the application wants to autoplay video elements that have an audio track, you might use the following code to mute the video if only inaudible content is allowed to play.

if (navigator.getAutoplayPolicy("mediaelement") === "allowed") {
  // Do nothing. The content can autoplay.
} else if (navigator.getAutoplayPolicy("mediaelement") === "allowed-muted") {
  // Mute the video so it can autoplay.
} else {
  // Autoplay disallowed.
  // Add a play button to the video element.
}

The method can also be called to check the autoplay policy for a specific media element or audio context. As shown below, the code looks exactly the same except you pass in the specify item rather than the type string.

const video = document.getElementById("video_element_id");
if (navigator.getAutoplayPolicy(video) === "allowed") {
  // Do nothing. The content can autoplay.
} else if (navigator.getAutoplayPolicy(video) === "allowed-muted") {
  // Mute the video so it can autoplay.
} else {
  // Autoplay disallowed.
  // Add a play button to the video element.
}

On page load, before the user has interacted with the page or site, the autoplay policy for the type and the individual items will be the same. After the user interacts with the site, page, or specific elements, the autoplay policy may change for the whole type. It is also possible that the policy for a specific item will change, even if the overall policy for the type does not.

There is no way to be notified that the autoplay policy has changed. For this reason, while you can check the policy for a type or item at any time, usually you will only do so on page load or before attempting to play content.

The code below shows how to check if navigator.getAutoplayPolicy() is supported:

<div id="reportResult"></div>

const log = document.getElementById("reportResult");

if (!navigator.getAutoplayPolicy) {
  log.textContent = "navigator.getAutoplayPolicy() not supported.";
} else {
  log.textContent = "navigator.getAutoplayPolicy() is supported.";
}

The result of running the code on this page is:

This example demonstrates how you can check the autoplay policy for the media elements type.

The code creates a video element that has the autoplay attribute and is not muted by default. If the autoplay policy is "allowed-muted", the video will be muted to allow it to play.

HTML

The HTML below has a div element that is used as a reporting log, and also displays a <video> that has the autoplay attribute. This should not be muted by default, and should play automatically if autoplay is not blocked.

<div id="reportResult"></div>
<!-- Simple video example -->
<!-- 'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org -->
<!-- Poster from peach.blender.org -->
<video
  id="bunny_vid"
  autoplay
  controls
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
  width="620">
  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a href="https://archive.org/details/BigBuckBunny_124">download it</a> and
  watch it with your favorite video player!
</video>

JavaScript

The code reports whether or not the getAutoplayPolicy() method is supported, and if it is, the policy for media elements.

If the policy is allowed-muted, only muted videos can be played. In this case we add some text explaining what is happening and mute the video.

const log = document.getElementById("reportResult");
const video = document.getElementById("bunny_vid");

if (!navigator.getAutoplayPolicy) {
  log.textContent =
    "navigator.getAutoplayPolicy() not supported. It may or may not autoplay, depending on the browser!";
} else {
  log.textContent = `Autoplay policy for media elements is: ${navigator.getAutoplayPolicy(
    "mediaelement"
  )}. `;

  if (navigator.getAutoplayPolicy("mediaelement") === "allowed-muted") {
    // Mute the video so it can autoplay
    video.muted = true;
    log.textContent += "Video has been muted to allow it to autoplay.";
  }
}

Note that you might similarly check for allowed and disallowed.

Result

The video is displayed below along with information about whether the getAutoplayPolicy() method is supported, and if so, the policy.

If getAutoplayPolicy() is supported and the policy is allowed, the video will play automatically with sound. If the policy is allowed-muted, the video will play without sound.

Note that if getAutoplayPolicy() is not supported, the video will either autoplay with audio or not play. The code has no control over this behavior: you're at the mercy of the browser implementation!

This example shows how you can check whether a specific media element will autoplay. It is almost exactly the same as the previous example (an AudioContext check would also be similar). Note that it is possible for specific elements to autoplay even if a check on the mediaelement type indicates that autoplay is disallowed; in other words, a check on a specific element is more reliable (though it doesn't matter on page load).

The code creates a video element that has the autoplay attribute. If the autoplay policy is "allowed-muted", the video will be muted to allow it to play.

HTML

The HTML below has a div element that is used as a reporting log, and also displays a <video> that has the autoplay attribute. This should not be muted by default, and should play automatically if autoplay is not blocked.

<div id="reportResult"></div>
<!-- Simple video example -->
<!-- 'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org -->
<!-- Poster from peach.blender.org -->
<video
  id="bunny_vid"
  autoplay
  controls
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
  width="620">
  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a href="https://archive.org/details/BigBuckBunny_124">download it</a> and
  watch it with your favorite video player!
</video>

JavaScript

The code reports whether or not the getAutoplayPolicy() method is supported, and if it is, the policy for media elements.

If the policy is allowed-muted, only muted videos can be played, so the code mutes the video.

const log = document.getElementById("reportResult");
const video = document.getElementById("bunny_vid");

if (!navigator.getAutoplayPolicy) {
  log.textContent =
    "navigator.getAutoplayPolicy() not supported. It may or may not autoplay, depending on the browser!";
} else {
  // Here we pass in the HTMLVideoElement to check
  log.textContent = `navigator.getAutoplayPolicy(video) == ${navigator.getAutoplayPolicy(
    "mediaelement"
  )}`;

  if (navigator.getAutoplayPolicy(video) === "allowed-muted") {
    // Mute the video so it can autoplay
    video.muted = true;
    log.textContent += "Video has been muted to allow it to autoplay.";
  }
}

Result

The result is the same as in the previous example:

• The video should autoplay with sound if allowed is returned, and no sound if allowed-muted is returned.
• If getAutoplayPolicy() is not supported, the video autoplay behavior depends only on the browser.

• Autoplay guide for media and Web Audio APIs