Navigator: getAutoplayPolicy() method
The getAutoplayPolicy()
method of the Autoplay Policy Detection API provides information about whether autoplay of media elements and audio contexts is allowed, disallowed, or only allowed if the audio is muted.
Applications can use this information to provide an appropriate user experience. For example, if the user agent policy only allows autoplay of inaudible content, the application might mute videos so that they can still autoplay.
The method can be used to get either the broad autoplay policy for all items of a particular type in the document, or for specific media elements or audio contexts.
Syntax
getAutoplayPolicy(type)
getAutoplayPolicy(element)
getAutoplayPolicy(context)
Parameters
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
.
Return value
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.
Exceptions
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
.
Description
"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") {
} else if (navigator.getAutoplayPolicy("mediaelement") === "allowed-muted") {
} else {
}
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") {
} else if (navigator.getAutoplayPolicy(video) === "allowed-muted") {
} else {
}
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.
Examples
Checking if the feature is supported
The code below shows how to check if navigator.getAutoplayPolicy()
is supported:
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>
<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") {
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>
<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 {
log.textContent = `navigator.getAutoplayPolicy(video) == ${navigator.getAutoplayPolicy(
"mediaelement",
)}`;
if (navigator.getAutoplayPolicy(video) === "allowed-muted") {
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.
Specifications
Browser compatibility
|
Desktop |
Mobile |
|
Chrome |
Edge |
Firefox |
Internet Explorer |
Opera |
Safari |
WebView Android |
Chrome Android |
Firefox for Android |
Opera Android |
Safari on IOS |
Samsung Internet |
getAutoplayPolicy |
No |
No |
112 |
No |
No |
No |
No |
No |
112 |
No |
No |
No |
See also