HTMLMediaElement: play() method
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
TheHTMLMediaElementplay() method attempts to begin playback of the media.It returns aPromise which is resolved when playback has beensuccessfully started.
Failure to begin playback for any reason, such aspermission issues, result in the promise being rejected.
Syntax
play()Parameters
None.
Return value
APromise which is resolved when playback has been started, or isrejected if for any reason playback cannot be started.
Note:Browsers released before 2019 may not return a value fromplay().
Exceptions
The promise'srejection handler is called with aDOMException objectpassed in as its sole input parameter (as opposed to a traditional exception beingthrown). Possible errors include:
NotAllowedErrorDOMExceptionProvided if the user agent (browser) or operating system doesn't allow playback of media in thecurrent context or situation. The browser may require the user to explicitly startmedia playback by clicking a "play" button, for example because of aPermissions Policy.
NotSupportedErrorDOMExceptionProvided if the media source (which may be specified as a
MediaStream,MediaSource,Blob, orFile, for example)doesn't represent a supported media format.
Other exceptions may be reported, depending on browser implementation details, mediaplayer implementation, and so forth.
Usage notes
Although the term "autoplay" is usually thought of as referring to pages thatimmediately begin playing media upon being loaded, web browsers' autoplay policies alsoapply to any script-initiated playback of media, including calls toplay().
If theuser agent is configured not to allow automatic orscript-initiated playback of media, callingplay() will cause the returnedpromise to be immediately rejected with aNotAllowedError. Websites shouldbe prepared to handle this situation. For example, a site should not present a userinterface that assumes playback has begun automatically, but should instead update theirUI based on whether the returned promise is fulfilled or rejected. See theexample below for more information.
Note:Theplay() method may cause the user to be askedto grant permission to play the media, resulting in a possible delay before thereturned 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 ourarticleAutoplay guide for media and Web Audio APIs.
Examples
Confirming playback and handling states
This example demonstrates how to confirm that playback has begun and how to gracefullyhandle blocked automatic playback.
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 theclick event on the toggle button and attempts to automatically begin playback by calling theasyncplayVideo() function.
A helper functiontoggleButton() lets us define what should happen in the code when we pass it a boolean value representing the playing state (e.g.,toggleButton(true))If playback is successful, the button text and itsaria-label changes to "Pause".If playback fails, the button andaria-label shows "Play".This ensures that theplayButton matches the playback state by watching for the resolution or rejection of thePromise returned byplay():
<div> <video width="480" loop src="/shared-assets/videos/flower.mp4"></video> <button type="button" aria-label="Play"></button></div>let videoElem = document.getElementById("video");let playButton = document.getElementById("play-button");playButton.addEventListener("click", handlePlayButton);playVideo();function toggleButton(playing) { if (playing) { playButton.textContent = "Pause"; playButton.setAttribute("aria-label", "Pause"); } else { playButton.textContent = "Play"; playButton.setAttribute("aria-label", "Play"); }}async function playVideo() { try { await videoElem.play(); toggleButton(true); } catch (err) { toggleButton(false); }}function handlePlayButton() { if (videoElem.paused) { playVideo(); } else { videoElem.pause(); toggleButton(false); }}.video-box { position: relative;}#video { border: 2px solid black;}#play-button { position: absolute; top: 10px; left: 10px; padding: 8px 12px; background-color: black; color: white; border: none; cursor: pointer;}Specifications
| Specification |
|---|
| HTML # dom-media-play-dev |