Add EnterPictureInPictureReason (#362)

steimelchrome · web-flow · commit dd37d722bbff · 2025-09-19T16:12:58.000-07:00
This adds EnterPictureInPictureReason to the MediaSessionActionDetails for the enterpictureinpicture action, based on the discussions surrounding #358
diff --git a/index.bs b/index.bs
@@ -767,6 +767,12 @@ enum MediaSessionAction {
   "voiceactivity"
 };
 
+enum MediaSessionEnterPictureInPictureReason {
+  "other",
+  "useraction",
+  "contentoccluded"
+};
+
 callback MediaSessionActionHandler = undefined(MediaSessionActionDetails details);
 
 [Exposed=Window]
@@ -1521,6 +1527,7 @@ dictionary MediaSessionActionDetails {
   double seekTime;
   boolean fastSeek;
   boolean isActivating;
+  MediaSessionEnterPictureInPictureReason enterPictureInPictureReason;
 };
 
 </pre>
@@ -1565,6 +1572,25 @@ of [=pausing all input sources=] and the <a>media session action</a>
 is {{MediaSessionAction/togglecamera}}, {{MediaSessionAction/togglemicrophone}}
 or {{MediaSessionAction/togglescreenshare}}.
 
+When the <a>media session action</a> is {{MediaSessionAction/enterpictureinpicture}},
+the <dfn dict-member for="MediaSessionActionDetails">enterPictureInPictureReason</dfn>
+<a>dictionary member</a> MUST be provided and is the reason the UA has triggered this
+action.
+
+{{enterPictureInPictureReason}} can have one of the following values:
+<ul>
+  <li>
+    <dfn enum-value for="MediaSessionEnterPictureInPictureReason">other</dfn>: the reason for entering picture-in-picture is not one of the existing enum values
+  </li>
+  <li>
+    <dfn enum-value for="MediaSessionEnterPictureInPictureReason">useraction</dfn>: the user has taken an explicit action to enter picture-in-picture (e.g. clicking a picture-in-picture button in the user agent UI)
+  </li>
+  <li>
+    <dfn enum-value for="MediaSessionEnterPictureInPictureReason">contentoccluded</dfn>: the user agent is requesting picture-in-picture because the page has become occluded.
+    This can happen in various cases like tab switching or tab minimization.
+  </li>
+</ul>
+
 <h2 id="permissions-policy">Permissions Policy Integration</h2>
 
 This specification defines a [=policy-controlled feature=] identified by the
