demo · v142

Window Occlusion Timeline

The browser sometimes fires enterpictureinpicture on its own — usually because the user dragged another window over the video, or switched tabs. With details.reason the page can tell that case apart from a real button click and reject it (e.g. a Zoom call where dropping the user into PiP without warning would be confusing). Drag the overlay window and watch the reason flip.

policy

accept
any reason
accept
only "user" reason
accept
everything except "auto-enter-occlusion"
accept
none — handle yourself
video tab
▶   talking-head video plays here
chat window (drag me)
"hey, did you see that?"
PiP video reason: —

relevant markup

navigator.mediaSession.setActionHandler(
  "enterpictureinpicture",
  (details) => {
    if (details.enterPictureInPictureReason === "auto-enter-occlusion") {
      // Don't surprise the user — return without calling requestPictureInPicture()
      return;
    }
    video.requestPictureInPicture();
  }
);

see also