网页加载完成后立即播放音频（或带有音频轨道的视频）可能会意外地打扰到用户。尽管自动播放媒体文件是一个很实用的功能，但是我们也应该谨慎地使用它，保证只有在它被需要的时候才使用。为了让用户拥有控制权，通常浏览器会提供各种方式禁用自动播放音频功能。在这篇文章中，我们将介绍各种媒体和 Web Audio APIs 的自动播放功能，包括关于如何使用自动播放功能、如何优雅的处理阻止自动播放功能的一些简短的介绍。
Autoplay blocking is not applied to {{HTMLElement("video")}} elements when the source media does not have an audio track, or if the audio track is muted. Media with an active audio track are considered to be audible, and autoplay blocking applies to them. Inaudible media are not affected by autoplay blocking.
The term autoplay refers to any feature that causes audio to begin to play without the user specifically requesting that playback begin. This includes both the use of HTML attributes to autoplay media as well as the user of JavaScript code to start playback outside the context of handling user input.
That means that both of the following are considered autoplay behavior, and are therefore subject to the browser's autoplay blocking policy:
<audio src="/music.mp4" autoplay>
和
audioElement.play();
以下网络功能和API可能会受到自动播放阻止的影响：
从用户的角度来看，网页或应用程序自动地发出噪音而没有警告可能会令人讨厌、不便或令人反感。因此，浏览器通常仅允许在特定情况下进行自动播放。
据新政策，媒体内容将在满足以下至少一个的条件下自动播放：
否则，播放可能会被阻止。导致播放被阻塞的确切情况以及将网站列入白名单的具体方法因浏览器而异，但最好是遵循以上的原则。
详情，请参阅 Google Chrome 和 WebKit 的自动播放政策。
注意: 换句话说，如果在尚无任何用户交互的页面中通过编程方式启动播放，则通常会阻止任何包含音频在内的媒体的播放。
既然我们已经介绍了什么是自动播放以及什么可以阻止自动播放，接下来我们将介绍您的网站或应用程序如何在页面加载时自动播放媒体，如何检测何时自动播放失败，以及当自动播放被浏览器拒绝时的应对技巧。
想让内容自动播放的最简单方法是将{{htmlattrxref("autoplay", "audio")}}属性添加到{{HTMLElement("audio")}}或{{HTMLElement("video")}}元素。并将{{domxref("HTMLMediaElement.autoplay", "autoplay")}}属性设置为 true ，当 autoplay 的属性为 true 时，媒体元素将在发生以下情况后尽快自动开始播放：
页面允许使用自动播放功能
使用 autoplay 属性的{{HTMLElement("audio")}}元素就像如下：
<audio id="musicplayer" autoplay> <source src="/music/chapter1.mp4" </audio>
如果你依靠自动播放功能去做一些重要的事情，或者自动播放失败会以任何方式影响你的应用程序，那你可能会想知道自动播放什么时候没有开始。不幸的是，对于{{htmlattrxref("autoplay", "audio")}}属性，识别自动播放是否成功开始是很棘手的。自动播放失败时不会触发任何事件。也没有抛出异常或可以设置回调，甚至在媒体元素上都没有标记来告诉你自动播放是否起作用。你实际能做的就是检查一些值，然后根据这些值猜测自动播放是否起作用。
如果您能够调整查看内容的方向，那么更好的方法是，依靠知道媒体播放已成功开始，而不是在媒体启动失败时知道。您可以通过侦听要在媒体元素上触发的{{event("play")}}事件来轻松实现此目的。
The play event is sent both when the media is resumed after being paused and when autoplay occurs. That means that the first time the play event is fired, you know your media is being started for the first time after the page is opened.
Consider this HTML for a media element:
<video src="myvideo.mp4" autoplay onplay=handleFirstPlay(event)">
Here we have a {{HTMLElement("video")}} element whose {{htmlattrxref("autoplay", "video")}} attribute is set, with an {{domxref("HTMLMediaElement.onplay", "onplay")}} event handler set up; the event is handled by a function called handleFirstPlay(), which receives as input the play event.
handleFirstPlay() looks like this:
function handleFirstPlay(event) {
let vid = event.target;
vid.onplay = null;
// Start whatever you need to do after playback has started
}
After getting a reference to the video element from the {{domxref("Event")}} object's {{domxref("Event.target", "target")}}, the element's onplay handler is set to null. This will prevent any future play events from being delivered to the handler. That could happen if the video is paused and resumed by the user or automatically by the browser when the document is in a background tab.
At this point, your site or app can begin whatever it needs to do that relies upon the video having been started up.
Note: This approach doesn't differentiate between autoplay and the user starting playback manually.
The term "autoplay" also refers to scenarios in which a script tries to trigger the playback of media that includes audio, outside the context of handling a user input event. This is done by calling the media element's {{domxref("HTMLMediaElement.play", "play()")}} method.
Note: It is strongly recommended that you use the autoplay attribute whenever possible, because support for autoplay preferences are more widespread for the autoplay attribute than for other means of playing media automatically. It also lets the browser take responsibility for starting playback, letting it optimize the timing of that taking place.
This simple example plays the first {{HTMLElement("video")}} element found in the document. play() won't let the playback begin unless the document has permission to automatically play media.
document.querySelector("video").play();
It's much easier to detect a failure to autoplay media when you use the {{domxref("HTMLMediaElement.play", "play()")}} method to start it. play() returns a {{jsxref("Promise")}} which is resolved once the media successfully begins to play, and is rejected when playback fails to begin (such as if autoplay is denied). When autoplay fails, you likely will want to offer a way for the user to manually tell the browser to ask the user to grant permission to play media.
You might use code like this to accomplish the job:
let startPlayPromise = videoElem.play();
if (startPlayPromise !== undefined) {
startPlayPromise.catch(error => {
if (error.name === "NotAllowedError") {
showPlayButton(videoElem);
} else {
// Handle a load or playback error
}
}).then(() => {
// Start whatever you need to do only after playback
// has begun.
});
}
The first thing we do with the result of play() is make sure it's not undefined. We check for this because in earlier versions of the HTML specification, play() didn't return a value. Returning a promise to allow you to determine success or failure of the operation was added more recently. Checking for undefined prevents this code from failing with an error on older versions of web browsers.
We then add a {{jsxref("Promise.catch", "catch()")}} handler to the promise. This looks at the error's {{domxref("DOMException.name", "name")}} to see if it's NotAllowedError. This indicates that playback failed due to a permission issue, such as autoplay being denied. If that's the case, we should present a user interface to let the user manually start playback; that's handled here by a function showPlayButton().
Any other errors are handled as appropriate.
If the promise returned by play() is resolved without error, the then() clause is run and can begin whatever needs to be done when autoplay has begun.
In the Web Audio API, a web site or app can start playing audio using the start() method on a source node linked to the {{domxref("AudioContext")}}. Doing so outside the context of handling a user input event is subject to autoplay rules.
More content will come soon; autoplay blocking is still being worked on at Mozilla. If others have it already, they are welcome to pitch in with this section...
In addition to the browser-side management and control over autoplay functionality described above, a web server can also express its willingness to allow autoplay to function. The {{Glossary("HTTP")}} {{HTTPHeader("Feature-Policy")}} header's autoplay directive is used to control which domains, if any, can be used to autoplay media. By default, the autoplay feature policy is set to 'self' (including the single quote characters), indicating that autoplay is permitted as they're hosted on the same domain as the document.
You can also specify 'none' to disable autoplay entirely, '*' to allow autoplay from all domains, or one or more specific origins from which media can be automatically played. These origins are separated by space characters.
Note: The specified feature policy applies to the document and every {{HTMLElement("iframe")}} nested within it, unless those frames include an {{htmlattrxref("allow", "iframe")}}, which sets a new feature policy for that frame and all frames nested within it.
When using the {{htmlattrxref("allow", "iframe")}} attribute on an <iframe> to specify a feature policy for that frame and its nested frames, you can also specify the value 'src' to allow autoplay of media only from the same domain as that specified by the frame's {{htmlattrxref("src", "iframe")}} attribute.
To use the {{HTTPHeader("Feature-Policy")}} header to only allow media to autoplay from the document's {{Glossary("origin")}}:
Feature-Policy: autoplay 'self'
To do the same for an {{HTMLElement("iframe")}}:
<iframe src="mediaplayer.html"
allow="autoplay 'src'">
</iframe>
Adding Fullscreen API permission to the previous example results in a Feature-Policy header like the following if fullscreen access is allowed regardless of the domain; a domain restriction can be added as well as needed.
Feature-Policy: autoplay 'self'; fullscreen
The same permissions, grated using the <iframe> element's allow property, look like this:
<iframe src="mediaplayer.html"
allow="autoplay 'src'; fullscreen">
</iframe>
The Feature-Policy header to allow media to be played from both the document's (or <iframe>'s) own domain and https://example.media looks like this:
Feature-Policy: autoplay 'self' https://example.media
An {{HTMLElement("iframe")}} can be written to specify that this autoplay policy should be applied to itself and any child frames would be written thusly:
<iframe width="300" height="200"
src="mediaplayer.html"
allow="autoplay 'src' https://example.media">
</iframe>
Setting the autoplay feature policy to 'none' disables autoplay entirely for the document or <iframe> and all nested frames. The HTTP header is:
Feature-Policy: autoplay 'none'
Using the <iframe>'s allow attribute:
<iframe src="mediaplayer.html"
allow="autoplay 'none'">
</iframe>
Tips and recommended best practices to help you make the most of working with autoplay are offered here.
A common use case for autoplay is to automatically begin to play a video clip that goes along with an article, an advertisement, or a preview of the page's main functionality. To autoplay videos like these, you have two options: don't have an audio track, or have an audio track but configure the {{HTMLElement("video")}} element to mute the audio by default, like this:
<video src="/videos/awesomevid.webm" controls autoplay muted>
This video element is configured to include the user controls (typically play/pause, scrubbing through the video's timeline, volume control, and muting); also, since the {{htmlattrxref("muted", "video")}} attribute is included, the video will autoplay but with the audio muted. The user has the option, however, of re-enabling the audio by clicking on the unmute button in the controls.
Browsers may have preferences that control the way autoplay works, or how autoplay blocking is handled. Here, any such preferences that may be of special significance or importance to you as a web developer are listed. These include any that may aid in testing or debugging as well as any that could be set in a way that you need to be prepared to handle.
media.allowed-to-play.enabledfalse by default (except in nightly builds, where it's true by default). If this is false, the allowedToPlay property is missing from the HTMLMediaElement interface, and is thus not present on either {{HTMLElement("audio")}} or {{HTMLElement("video")}} elements.media.autoplay.allow-extension-background-pagestrue, allows browser extensions' background scripts to autoplay audio media. Setting this value to false disables this capability. The default value is true.media.autoplay.allow-mutedtrue (the default) allows audio media which is currently muted to be automatically played. If this has been changed to false, media with an audio track will not be permitted to play even if muted.media.autoplay.block-webaudiotrue.media.autoplay.default0), blocked (1), or prompt-on-use (2). The default value is 0.media.autoplay.enabled.user-gestures-needed (Nightly builds only)media.autoplay.default. If media.autoplay.default is not set to 0 (autoplay allowed by default), this preference being true allows autoplay of media with audio tracks anyway if the page has been activated by user gestures, and media that isn't audible is not restricted at all.media.block-autoplay-until-in-foregroundtrue, means that even when otherwise available, autoplay won't take place until after a tab is brought to the foreground. This prevents the distracting situation in which a tab begins playing sound and the user can't find the tab among all their tabs and windows.