Auto-Play Policy Changes for macOS

This is a guest post from the Safari team about changes to how Safari handles HTML5 video and audio auto-play. These changes may affect compatibility with your websites.

As follow up to Safari’s updated video policies for iOS last year, this week we announced we are making important changes to auto-play policies on the Mac. These changes provide users the ability to browse the web with fewer distractions, particularly in the form of relief from websites that auto-play with sound.

New Behaviors

The WebKit engine provides rich flexibility for user agents to configure and manage media auto-play policies. Safari in macOS High Sierra uses an automatic inference engine to block media elements with sound from auto-playing by default on most websites. Safari 11 also gives users control over which websites are allowed to auto-play video and audio by opening Safari’s new “Websites” preferences pane, or through the “Settings for This Website…” option in the Safari menu. Further, a new power-saving feature prevents silent videos from auto-playing when either hidden in a background tab or otherwise off-screen.

Best Practices for Web Developers

Websites should assume any use of <video> or <audio> requires a user gesture click to play. It’s important to detect if auto-play was denied, since users now have the ability to turn off all forms of auto-play, including silent videos. The code snippet below shows just how easy this is to check. It’s worth pointing out that the new auto-play policies apply both to video used as a tool for making something visual happen (like background video or video-as-animated-gif) and also to video that serves as consumable content. We recommend web developers test their site with these new behaviors, ensuring any custom media controls behave correctly when auto-play is disabled, either automatically by Safari or by users.

  • Websites using WebKit’s built-in media controls automatically work great with the new policies.
  • Don’t assume a media element will play, and don’t show the pause button from the start. Look at the Promise returned by the play function on HTMLMediaElement to see if it was rejected:
var promise = document.querySelector('video').play();

if (promise !== undefined) {
    promise.catch(error => {
        // Auto-play was prevented
        // Show a UI element to let the user manually start playback
    }).then(() => {
        // Auto-play started
  • Auto-play restrictions are granted on a per-element basis. Change the source of the media element instead of creating multiple media elements if you want to play multiple videos back to back (or play a pre-roll ad with sound, followed by the main video).
  • Don’t play ads without showing media controls because they may not auto-play and users will have no way of starting playback.
  • Remember that audio tracks that render silence are still audio tracks, and their existence affects whether a video will auto-play at all. In these cases, a video with silent audio tracks won’t play. The audio track should be removed or, alternatively, the muted attribute can be set on the media element.


We’d love to hear from developers on these new auto-play policies. Please reach out to our Web Technologies Evangelist, Jon Davis on Twitter to share your thoughts with our team.