v142 · miscellaneous

Media session: add reason to enterpictureinpicture action details

Adds `enterPictureInPictureReason` to the `MediaSessionActionDetails` sent to the `enterpictureinpicture` action in the Media Session API. This allows developers to distinguish between `enterpictureinpicture` actions triggered explicitly by the user (e.g. from a button in the user agent) and `enterpictureinpicture` actions triggered automatically by the user

concepts

  1. PiP Reason

    Trigger PiP through a button or tab switch — watch the action handler receive details.reason and let you opt out of background-triggered PiP.

  2. Auto-PiP Policy

    The reason the enum exists: configure a per-reason allow/deny policy, then trigger each reason. Demonstrates the "honour user clicks, suppress auto-enter for live chats" pattern YouTube + Netflix asked for in the W3C thread.

  3. Window Occlusion Timeline

    Drag the chat window over the video, switch tabs, or click a real PiP button. Watch details.enterPictureInPictureReason flip between user and auto-enter-occlusion live, and toggle which reasons a Zoom-like app should accept.

  4. PiP Reason Logger

    Three trigger buttons simulate different PiP entry paths — user gesture, auto-pip, media-session. A timestamped log captures every enterpictureinpicture event with its details.reason; a live bar chart tallies per-reason counts. Feature detection badges show which APIs are available.

why it shipped

This allows developers to distinguish between `enterpictureinpicture` actions triggered explicitly by the user (e.g. from a button in the user agent) and `enterpictureinpicture` actions triggered automatically by the user agent due to the content becoming occluded.

references