Adding documentation for autoplay

docs/media/autoplay.md

Index: docs/media/autoplay.md
diff --git a/docs/media/autoplay.md b/docs/media/autoplay.md
new file mode 100644
index 0000000000000000000000000000000000000000..b9eb461f1ad1427fd21583f14f68206a0b49a1bb
--- /dev/null
+++ b/docs/media/autoplay.md
@@ -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:
+
+![Autoplay by attribute](autoplay_by_attribute.png)
+
+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:
+
+![Autoplay by play() method](autoplay_by_play_method.png)
+
+This means if autoplay is initiated by `play()` method, we continue playing the
+video as normal `play()`. However if the page tries to umute the video, we check

[sandersd (OOO until July 31), 2017/03/29 19:47:04]

unmute?

[Zhiqiang Zhang (Slow), 2017/03/30 11:15:48]

Done.

+the gesture lock and pause the video if it is still `true`.