Published: February 5, 2025
From Chrome 120, video conferencing web apps can automatically open a picture-in-picture window when the user switches focus from their current tab. This is useful for presenters who want to see and interact with participants in real time while presenting a document or using other tabs or windows. See Automatic picture-in-picture for video conferencing web apps for details.
From Chrome 134, web apps that play audio or video can automatically enter picture-in-picture mode. This means that music and video players on the web can now seamlessly switch to a mini player window when the user switches tabs, eliminating the need for manual activation.
To support these media playback use cases, from Chrome 134 desktop web apps can automatically enter picture-in-picture, with a few restrictions to ensure a positive user experience. A web app is only eligible for automatic picture-in-picture for media playback if it meets all of the following conditions:
The top frame URL is safe according to the Safe Browsing service.
The media lives in the top frame.
The media has been audible within the last two seconds.
The media has audio focus.
The media is playing.
A media session action handler for the
"enterpictureinpicture"
action has been registered.The user's Media Engagement Index threshold has been exceeded, indicating that the user frequently consumes media in this web app. This applies if the user's browser setting is "Can ask to enter picture-in-picture". If the user explicitly allows the web app to enter picture-in-picture, this condition does not apply.
![The automatic picture-in-picture setting in the Chrome browser site information pane.](/static/blog/automatic-picture-in-picture-media-playback/image/browser-setting.jpg)
The bug 386193409 tracks the implementation of surfacing conditions to make debugging and implementation easier.
Note that if another picture-in-picture window is already open, Chrome doesn't trigger automatic picture-in-picture. This rule doesn't apply if the existing picture-in-picture window was opened automatically and is about to close.
When a web app meets the requirements, switching focus to another tab triggers the media session action handler callback function for the "enterpictureinpicture"
action. This lets the web app open a picture-in-picture window without a user gesture. The user may then be presented with a permission dialog, asking if they would like to allow the site to enter picture-in-picture automatically every time, only this time, or never.
![A permission overlay in the picture-in-picture window asking the user if they would like to allow the site to enter picture-in-picture automatically.](/static/blog/automatic-picture-in-picture-media-playback/image/pip-window-popup.jpg)
You can either use the Picture-in-Picture API for <video> to open a picture-in-picture window from an HTML <video>
element, or the Document Picture-in-Picture API to open an always-on-top window to populate with arbitrary HTML content. The picture-in-picture window is not focused when opened and automatically closed when the page becomes visible again.
The following example shows you how to play an HTML <video>
element when a user clicks a button. Then, safely register a media session action handler for the "enterpictureinpicture"
action with a callback function that opens a picture-in-picture window. This window contains the video with the Picture-in-Picture API for <video>.
const video = document.querySelector("video");
async function onPlayButtonClick() {
// Play video.
await video.play();
}
try {
// Request video to automatically enter picture-in-picture when eligible.
navigator.mediaSession.setActionHandler("enterpictureinpicture", async () => {
await video.requestPictureInPicture();
});
} catch (error) {
console.log("The enterpictureinpicture action is not yet supported.");
}
Try the VideoJS player demo which showcases the Document Picture-in-Picture API or play with the Video Media Session and Audio Media Session samples.
Engage and share feedback
If you have feedback or encounter any issues, you can share them at crbug.com.
Resources
Acknowledgments
Thanks to Benjamin Keen and Frank Liberato for their reviews.