Adding documentation for autoplay
BUG=None Review-Url: https://codereview.chromium.org/2787513002 Cr-Commit-Position: refs/heads/master@{#460722}
This commit is contained in:
49
docs/media/autoplay.md
Normal file
49
docs/media/autoplay.md
Normal file
@ -0,0 +1,49 @@
|
||||
# Autoplay of HTMLMediaElements
|
||||
|
||||
Autoplay is the concept of playing media elements without user gesture. On
|
||||
desktop, autoplay is always allowed. On mobile, only muted video elements are
|
||||
allowed to autoplay. The autoplay logic follows
|
||||
the
|
||||
[HTML spec](https://html.spec.whatwg.org/multipage/embedded-content.html#media-elements).
|
||||
|
||||
There are two ways of initiating autoplay:
|
||||
|
||||
* Autoplay by attribute: Setting the `autoplay` attribute on the media element.
|
||||
The element will try to autoplay when the `readyState` changes to
|
||||
HAVE_ENOUGH_DATA.
|
||||
* Autoplay by `play()` method: Explicitly calling the `play()` method without
|
||||
user gesture.
|
||||
|
||||
## User gesture lock
|
||||
|
||||
Each media element has a user gesture lock. If the element is allowed to
|
||||
autoplay, the lock is initialized as `false`, otherwise it's `true`.
|
||||
|
||||
When the element is trying to initate autoplay, we check the gesture lock. If
|
||||
the lock is `false`, it will be allowed. Otherwise autoplay will be blocked. An
|
||||
exception is that if the element is a muted video element, the gesture lock
|
||||
check will be bypassed.
|
||||
|
||||
To unlock the gesture lock (make it `false`). The page needs to call play() or
|
||||
load() on the element when responding to a user gesture.
|
||||
|
||||
## Autoplay flowchart
|
||||
|
||||
The treatments of autoplay by different methods are different. For autoplay by
|
||||
attribute, it is:
|
||||
|
||||

|
||||
|
||||
This means if autoplay is initiated by attribute, it enters the autoplaying
|
||||
phase, we play it as long as the video is visible. When the page explicitly
|
||||
calls `play()`, `pause()`, we leave the autoplaying phase. When the page tries
|
||||
to unmute the video, we check the gesture lock and pause the video if it is
|
||||
still `true`.
|
||||
|
||||
For autoplay by `play()` method, it is:
|
||||
|
||||

|
||||
|
||||
This means if autoplay is initiated by `play()` method, we continue playing the
|
||||
video as normal `play()`. However if the page tries to unmute the video, we check
|
||||
the gesture lock and pause the video if it is still `true`.
|
BIN
docs/media/autoplay_by_attribute.png
Normal file
BIN
docs/media/autoplay_by_attribute.png
Normal file
Binary file not shown.
After ![]() (image error) Size: 22 KiB |
BIN
docs/media/autoplay_by_play_method.png
Normal file
BIN
docs/media/autoplay_by_play_method.png
Normal file
Binary file not shown.
After ![]() (image error) Size: 20 KiB |
Reference in New Issue
Block a user