demo · v142

Auto-PiP Policy

The reason this enum landed: the same handler runs whether the user pressed the page's PiP button, switched tabs, or minimised the window — but the right behaviour differs. YouTube wants to honour explicit user-clicks but suppress auto-PiP for live chats and educational videos. Netflix wants every reason allowed. The matrix below configures a per-reason policy and the handler reads the incoming details.reason to decide.

video element — pretend this is your stream

per-reason policy (click a cell to flip)

details.reasonpolicydescription

simulate a trigger

MediaSession.setActionHandler exists
—
last action
—

Chrome 142 adds details.reason on the handler argument, letting pages make policy decisions instead of either always allowing or always opting out via navigator.mediaSession.setActionHandler("enterpictureinpicture", null).

handler pattern

navigator.mediaSession.setActionHandler("enterpictureinpicture", (details) => {
  // details.reason: "user-initiated" | "auto-enter" | "page-hidden"
  if (details.reason !== "user-initiated" && videoIsLive()) {
    return; // skip auto-PiP for live chats / lectures
  }
  document.pictureInPictureElement || video.requestPictureInPicture();
});

see also