Picture-in-picture (PiP) is a mode where the video is shown in a window on top of the browser, so the video can be watched while multitasking. Browsers have different PiP capabilities and the options available differ.

Picture-in-Picture Types

• Video element PiP
• Document PiP
• Browser native - the browser's proprietary PiP implementation that is not controllable by API

Video element PiP

This picture-in-picture mode is now available on most browsers but notably not Firefox. The video element can be put into a separate window.

This mode has limitations which may make it unsuitable for some use cases. Since only the video is in the PiP window, Video.js player controls will not be displayed, nor will emulated text tracks or any overlays or interactive elements. This mode is also not useful if the video source will change, especially for advertising. If needed, it can be disabled.

By default this mode is enabled if the browser supports the picture-in-picture API. If the Document PiP mode is enabled on a browser that supports it, that will take precedence.

Document PiP

Added in v8.3.0

Document picture-in-picture is an improved approach where the whole player element can be placed in a PiP window rather than just the video. This allows player controls, text tracks, overlays to be used.

Currently this is supported on Chrome 111 and above as an origin trial. The player at videojs.com will use this mode on supported browsers.

At this time this mode defaults to off, but can be simply enabled with a player option. If enabled, and supported by the browser, this takes prcedence over the video picture-in-picture mode.

Browser native PiP

Firefox does not implement the picture-in-picture API. Instead it has a proprietary picture-in-picture mode. It displays a PiP button on top of the video.

It is not possible to customize or remove this button programatically, nor is it possible to initiate PiP from a custom control. The Video.js picture-in-picture options have no effect.

Options

The video element PiP (vPiP) disablePictureInPicture and document PiP (docPiP) enableDocumentPictureInPicture options work independently of each other, so it's possible to use the improved document PiP mode on browsers that support it while disabling the video element PiP mode on browsers that don't.

* None of these options can have any effect on Firefox's behaviour.