Add enterpictureinpicture action

index.bs

@@ -458,6 +458,10 @@ conforming IDL fragments, as described in the Web IDL specification. [[!WEBIDL]]
           <dfn enum-value for=MediaSessionAction>nextslide</dfn>: the action's intent
           is to go to the next slide when presenting slides.
         </li>
+        <li>
+          <dfn enum-value for=MediaSessionAction>enterpictureinpicture</dfn>: the action's intent
+          is to open the playback in a picture-in-picture window.
+        </li>
       </ul>
     </p>
 
@@ -749,7 +753,8 @@ enum MediaSessionAction {
   "togglecamera",
   "hangup",
   "previousslide",
-  "nextslide"
+  "nextslide",
+  "enterpictureinpicture"
 };
 
 callback MediaSessionActionHandler = undefined(MediaSessionActionDetails details);
@@ -1227,10 +1232,20 @@ should always be positive.
 
 dictionary MediaSessionActionDetails {
   required MediaSessionAction action;
+};
+
+dictionary MediaSessionSeekActionDetails : MediaSessionActionDetails {
   double seekOffset;
+};
+
+dictionary MediaSessionSeekToActionDetails : MediaSessionActionDetails {
   double seekTime;
   boolean fastSeek;
 };
+
+dictionary MediaSessionPictureInPictureActionDetails : MediaSessionActionDetails {
+  boolean automatic;
+};
 </pre>
 
 The {{MediaSessionActionHandler}} MUST be run with the <var>details</var>
@@ -1242,7 +1257,7 @@ member</a>
 is used to specify the <a>media session action</a> that the
 {{MediaSessionActionHandler}} is associated with.
 
-The <dfn dict-member for="MediaSessionActionDetails">seekOffset</dfn>
+The <dfn dict-member for="MediaSessionSeekActionDetails">seekOffset</dfn>
 <a>dictionary member</a> MAY be provided when the <a>media session action</a>
 is <a enum-value for=MediaSessionAction>seekbackward</a> or
 <a enum-value for=MediaSessionAction>seekforward</a>. It is the time in seconds
@@ -1254,19 +1269,26 @@ When the <a>media session action</a> is
 
 <ul>
   <li>
-    The <dfn dict-member for="MediaSessionActionDetails">seekTime</dfn>
+    The <dfn dict-member for="MediaSessionSeekToActionDetails">seekTime</dfn>
     <a>dictionary member</a> MUST be provided and is the time in seconds to
     move the playback time to.
   </li>
 
   <li>
-    The <dfn dict-member for="MediaSessionActionDetails">fastSeek</dfn>
+    The <dfn dict-member for="MediaSessionSeekToActionDetails">fastSeek</dfn>
     <a>dictionary member</a> MAY be provided and will be true if the
     <a lt="media session action">action</a> is being called multiple times
     as part of a sequence and this is not the last call in that sequence.
   </li>
 </ul>
 
+The <dfn dict-member for="MediaSessionPictureInPictureActionDetails">automatic</dfn>
+<a>dictionary member</a> MUST be provided when the <a>media session action</a>
+is <a enum-value for=MediaSessionAction>enterpictureinpicture</a>. This boolean
+distinguishes an explicit user action to enter picture-in-picture (e.g. a
+picture-in-picture button on the user agent) and an automatic picture-in-picture
+action from the user agent when the content is hidden.
+
 <h2 id="examples">Examples</h2>
 
 <em>This section is non-normative.</em>
@@ -1519,6 +1541,18 @@ When the <a>media session action</a> is
   </pre>
 </div>
 
+<div class="example" id="example-enterpictureinpicture">
+  Handling picture-in-picture:
+  <pre class="lang-javascript">
+    navigator.mediaSession.setActionHandler("enterpictureinpicture", function(details) {
+      if (details.automatic && !mywebsite.userSettings.allowAutomaticPictureInPicture) {
+        return;
+      }
+      video.requestPictureInPicture();
+    });
+  </pre>
+</div>
+
 <h2 id="acknowledgments" class="no-num">Acknowledgments</h2>
 
 The editors would like to thank Paul Adenot, Jake Archibald, Tab Atkins,