Web/API/HTMLMediaElement/play

The HTMLMediaElement play() method attempts to begin playback of the media. It returns a Promise which is resolved when playback has been successfully started. Failure to begin playback for any reason, such as permission issues, result in the promise being rejected.

Syntax

var promise = HTMLMediaElement.play();

Parameters

None.

Return value

A Promise which is resolved when playback has been started, or is rejected if for any reason playback cannot be started.

Note: Older browsers may not return a value from play().

Exceptions

The promise's rejection handler is called with an exception name passed in as its sole input parameter (as opposed to a traditional exception being thrown). Possible errors include:

NotAllowedError: The user agent (browser) or operating system doesn't allow playback of media in the current context or situation. This may happen, for example, if the browser requires the user to explicitly start media playback by clicking a "play" button.
NotSupportedError: The media source (which may be specified as a MediaStream, MediaSource, Blob, or File, for example) doesn't represent a supported media format.

Other exceptions may be reported, depending on browser implementation details, media player implementation, and so forth.

Usage notes

Although the term "autoplay" is usually thought of as referring to pages that immediately begin playing media upon being loaded, web browsers' autoplay policies also apply to any script-initiated playback of media, including calls to play().

If the user agent is configured not to allow automatic or script-initiated playback of media, calling play() will cause the returned promise to be immediately rejected with a NotAllowedError. Web sites should be prepared to handle this situation. For example, a site should not present a user interface that assumes playback has begun automatically, but should instead update their UI based on whether the returned promise is resolved or rejected. See the example below for more information.

Note: The play() method may cause the user to be asked to grant permission to play the media, resulting in a possible delay before the returned promise is resolved. Be sure your code doesn't expect an immediate response.

For even more in-depth information about autoplay and autoplay blocking, see our article Autoplay guide for media and Web Audio APIs.

Example

This example demonstrates how to confirm that playback has begun and how to gracefully handle blocked automatic playback:

let videoElem = document.getElementById("video");
let playButton = document.getElementById("playbutton");

playButton.addEventListener("click", handlePlayButton, false);
playVideo();

async function playVideo() {
  try {
    await videoElem.play();
    playButton.classList.add("playing");
  } catch(err) {
    playButton.classList.remove("playing");
  }
}

function handlePlayButton() {
  if (videoElem.paused) {
    playVideo();
  } else {
    videoElem.pause(); 
    playButton.classList.remove("playing");
  }
}

In this example, playback of video is toggled off and on by the async playVideo() function. It tries to play the video, and if successful sets the class name of the playButton element to "playing". If playback fails to start, the playButton element's class is cleared, restoring its default appearance. This ensures that the play button matches the actual state of playback by watching for the resolution or rejection of the Promise returned by play().

When this example is executed, it begins by collecting references to the <video> element as well as the <button> used to toggle playback on and off. It then sets up an event handler for the click event on the play toggle button and attempts to automatically begin playback by calling playVideo().

You can try out or remix this example in real time on Glitch.

Specifications

Specification	Status	Comment
HTML Living StandardThe definition of 'play()' in that specification.	Living Standard	Initial definition; living specification.
HTML5The definition of 'play()' in that specification.	Recommendation	Initial definition.

Note: The WHATWG and W3C versions of the specification differ (as of August, 2018) as to whether this method returns a Promise or nothing at all, respectively.

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`play`	Chrome Full support 1	Edge Full support 12	Firefox Full support 3.5	IE Full support 9	Opera Full support 10.5	Safari Full support 6	WebView Android Full support 1	Chrome Android Full support 18	Firefox Android Full support 4	Opera Android Full support 11	Safari iOS Full support 6	Samsung Internet Android Full support 1.0
Returns a `Promise`	Chrome Full support 50	Edge Full support 17	Firefox Full support 53	IE No support No	Opera Full support 37	Safari Full support 10	WebView Android Full support 50	Chrome Android Full support 50	Firefox Android Full support 53	Opera Android Full support 37	Safari iOS Full support 10	Samsung Internet Android Full support 5.0

Legend

Full support: Full support
No support: No support