-
Notifications
You must be signed in to change notification settings - Fork 22.4k
/
index.md
137 lines (103 loc) · 4.99 KB
/
index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
---
title: "HTMLMediaElement: play() method"
short-title: play()
slug: Web/API/HTMLMediaElement/play
page-type: web-api-instance-method
browser-compat: api.HTMLMediaElement.play
---
{{APIRef("HTML DOM")}}
The {{domxref("HTMLMediaElement")}}
**`play()`** method attempts to begin playback of the media.
It returns a {{jsxref("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
```js-nolint
play()
```
### Parameters
None.
### Return value
A {{jsxref("Promise")}} which is resolved when playback has been started, or is
rejected if for any reason playback cannot be started.
> **Note:** Browsers released before 2019 may not return a value from
> `play()`.
### Exceptions
The promise's **rejection handler** is called with a {{domxref("DOMException")}} object
passed in as its sole input parameter (as opposed to a traditional exception being
thrown). Possible errors include:
- `NotAllowedError` {{domxref("DOMException")}}
- : Provided if the user agent (browser) or operating system doesn't allow playback of media in the
current context or situation. The browser may require the user to explicitly start
media playback by clicking a "play" button, for example because of a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy).
- `NotSupportedError` {{domxref("DOMException")}}
- : Provided if the media source (which may be specified as a {{domxref("MediaStream")}},
{{domxref("MediaSource")}}, {{domxref("Blob")}}, or {{domxref("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 {{Glossary("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`. Websites 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 fulfilled or rejected. See the
[example](#examples) 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](/en-US/docs/Web/Media/Autoplay_guide).
## Examples
This example demonstrates how to confirm that playback has begun and how to gracefully
handle blocked automatic playback:
```js
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`](/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
`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
{{jsxref("Promise")}} returned by `play()`.
When this example is executed, it begins by collecting references to the
{{HTMLElement("video")}} element as well as the {{HTMLElement("button")}} used to toggle
playback on and off. It then sets up an event handler for the {{domxref("Element/click_event", "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](https://media-play-promise.glitch.me/).
## Specifications
{{Specifications}}
## Browser compatibility
{{Compat}}
## See also
- [Web media technologies](/en-US/docs/Web/Media)
- Learning: [Video and audio content](/en-US/docs/Learn/HTML/Multimedia_and_embedding/Video_and_audio_content)
- [Autoplay guide for media and Web Audio APIs](/en-US/docs/Web/Media/Autoplay_guide)
- [Using the Web Audio API](/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API)