An Introduction to the Picture-in-Picture Web API

In 2016, Safari browser was released with macOS Sierra, introducing the picture-in-picture feature for the first time. This feature allows the user to pop up the video into a small floating window that is always on top of other windows, allowing the user to continue watching the video while performing other operations. This idea originates from television, for example, users may want to continue watching popular sports events while browsing program lists or other channels.

Not long after, Android 8.0 was released, supporting the picture-in-picture function through a native API. Although this feature is not yet supported on the Chrome desktop version, Chrome on Android can play videos in picture-in-picture mode through this API.

This prompted the development of a standard Picture-in-Picture Web API, enabling the website to initiate and control this behavior.

At the time of writing, only Chrome (version 70 and above) and Edge (version 76 and above) support this feature. Firefox, Safari, and Opera all use proprietary APIs to implement their capabilities.

This browser supports data from Caniuse, which contains more details. The number indicates that the browser supports this feature in this and later versions.

Desktop

Mobile/tablet

How to use the picture-in-picture API

Let's start by adding videos to the web page.

<video controls="" src="video.mp4"></video>

In Chrome, there are already toggle buttons for entering and exiting Picture-in-Picture mode.

To test Firefox implementation, you need to first enable the media.videocontrols.picture-in-picture.enabled flag in about:config and then right-click on the video to find the picture-in-picture option.

While this works, in many cases you want your video controls to be consistent across browsers and you may want to control which videos can go into picture-in-picture mode and which videos can't.

We can use the Picture-in-Picture Web API to replace the default method in the browser to enter Picture-in-Picture mode with our own methods. For example, let's add a button and click it to enable it:

 <button id="pipButton" class="hidden" disabled>Enter picture-in-picture mode</button>

Then select the video and button in JavaScript:

 const video = document.getElementById('video');
const pipButton = document.getElementById('pipButton');

By default, the button is hidden and disabled because we need to know if the Picture-in-Picture API is supported and enabled in the user's browser before displaying it. This is a progressive form of enhancement that helps avoid corrupted experiences in browsers that do not support this feature.

We can check if the API is supported and enable the button as follows:

 if ('pictureInPictureEnabled' in document) {
  pipButton.classList.remove('hidden')
  pipButton.disabled = false;
}

Enter picture-in-picture mode

Assume that our JavaScript has determined that the browser has enabled picture-in-picture support. When clicking the button with #pipButton, let's call requestPictureInPicture() on the video element. This method returns a promise that, by default, when parsing, places the video in a mini window in the lower right corner of the screen, although the user can move it.

 if ('pictureInPictureEnabled' in document) {
  pipButton.classList.remove('hidden')
  pipButton.disabled = false;

  pipButton.addEventListener('click', () => {
    video.requestPictureInPicture();
  });
}

We cannot keep the above code as is because requestPictureInPicture() returns a promise and if, for example, the video metadata has not loaded or the disablePictureInPicture property is present on the video, the promise may be rejected.

Let's add a catch block to catch this potential error and let the user know what's going on:

 pipButton.addEventListener('click', () => {
  video
    .requestPictureInPicture()
    .catch(error => {
      // Error handling});
});

Exit picture-in-picture mode

The browser considerately provides a close button in the Picture-in-Picture window, which can be clicked to close the window. However, we can also provide another way to exit the picture-in-picture mode. For example, we can make clicking our #pipButton close any active picture-in-picture window.

 pipButton.addEventListener('click', () => {
  if (document.pictureInPictureElement) {
    document
      .exitPictureInPicture()
      .catch(error => {
      // Error handling})
  } else {
    // Request Picture in Picture}
});

Another situation where you might want to close the Picture-in-Picture window is when the video enters full screen mode. Chrome already does this automatically without writing any code.

Picture-in-picture events

The browser allows us to detect when a video enters or leaves P-in-Picture mode. Since P-P mode has many ways to enter or exit, it is best to rely on event detection to update media controls.

These events are enterpictureinpicture and leavepictureinpicture, as the name implies, which are fired when the video enters or exits the picture-in-picture mode, respectively.

In our example, we need to update the #pipButton tag based on whether the video is currently in P-P mode.

Here is the code that helps us achieve this:

 video.addEventListener('enterpictureinpicture', () => {
  pipButton.textContent = 'Exit Picture-in-Picture Mode';
});

video.addEventListener('leavepictureinpicture', () => {
  pipButton.textContent = 'Enter Picture-in-Picture Mode';
});

Here is a demonstration:

Customize picture-in-picture window

The browser displays the play/pause button in the Picture-in-Picture window by default unless the video is playing a MediaStream object (generated by a virtual video source, such as a camera, a video recording device, a screen sharing service, or other hardware sources).

You can also add controls to go directly from the Picture-in-Picture window to the previous or next track:

 navigator.mediaSession.setActionHandler('previoustrack', () => {
  // Go to the previous track});

navigator.mediaSession.setActionHandler('nexttrack', () => {
  // Go to the next track});

Show webcam feed in picture-in-picture window

Video conferencing web applications can benefit from placing webcam feeds in picture-in-picture mode when users switch between applications and other browser tabs or windows.

Here is an example:

Disable Picture-in-Picture on Video

If you don't want the video to pop up in the Picture In Picture window, you can add the disabledPictureInPicture property to it, as shown below:

<video controls="" disablepictureinpicture="" src="video.mp4"></video>

Summarize

For now, that's all you need to know about the Picture-in-Picture Web API now! Currently, the API only supports<video></video> element, but it is also intended to extend to other elements.

Although browser support is now jagged, you can still use it as a way to progressively enhance the website video experience.

Further reading

• Picture-in-picture API specifications
• Watch videos using picture-in-picture
• Picture-in-picture example (Google Chrome on GitHub)

The output maintains the original image and its format. The text has been paraphrased and reorganized for improved flow and clarity while retaining the original meaning. Technical terms are kept consistent.

The above is the detailed content of An Introduction to the Picture-in-Picture Web API. For more information, please follow other related articles on the PHP Chinese website!