feat: Add enablePictureInPicture option (#168)

mister-ben · web-flow · commit 3ee19164b2a7 · 2023-04-25T16:44:09.000+02:00
* feat: Add enablePictureInPicture option

* add disablePictureInPicture option too

* origin trial note

* typo

* Enable docPiP

* fix weird padding

* update deps

* version note

* versions in options guide

* typos
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -43,10 +43,10 @@
     "shortid": "^2.2.14",
     "styled-components": "^5.3.5",
     "typescript": "^2.9.2",
-    "video.js": "^7.20.1",
+    "video.js": "^8.3.0",
     "videojs-mux": "^4.6.6",
-    "videojs-playlist": "^4.3.1",
-    "videojs-playlist-ui": "^4.1.0"
+    "videojs-playlist": "^5.1.0",
+    "videojs-playlist-ui": "^4.2.0"
   },
   "devDependencies": {
     "bluebird": "^3.7.2",
diff --git a/src/components/HomeComponents/AdvancedExample/PlayerPlaylist.jsx b/src/components/HomeComponents/AdvancedExample/PlayerPlaylist.jsx
@@ -90,7 +90,7 @@ const PlaylistWrapper = styled.div`
 
 const Playlist = () => (
   <PlaylistWrapper>
-    <div className="vjs-playlist vjs-fluid" />
+    <div className="vjs-playlist" />
   </PlaylistWrapper>
 );
 
diff --git a/src/components/HomeComponents/AdvancedExample/index.jsx b/src/components/HomeComponents/AdvancedExample/index.jsx
@@ -115,7 +115,10 @@ class AdvancedExample extends React.Component {
   }
 
   componentDidMount() {
-    this.player = videojs(this.videoEl, {}, () => {
+    this.player = videojs(this.videoEl, {
+      aspectRatio: '21:9',
+      enableDocumentPictureInPicture: true
+    }, () => {
       if (this.player.hasPlugin('mux')) {
         this.player.mux({
           data: {
diff --git a/src/components/HomeComponents/Hero.jsx b/src/components/HomeComponents/Hero.jsx
@@ -115,6 +115,7 @@ const HomeHero = props => (
               { src: props.heroTheme.video, type: 'application/x-mpegurl' },
             ]}
             poster={props.heroTheme.poster}
+            enableDocumentPictureInPicture='true'
             onPlay={props.onPlay}
             playsInline
           />
diff --git a/src/mdx-pages/guides/options.mdx b/src/mdx-pages/guides/options.mdx
@@ -193,6 +193,28 @@ See the file `sandbox/responsive.html.example` for an example of a responsive pl
 
 This option is inherited from the [`Component` base class](#component-options).
 
+### `disablePictureInPicture`
+
+> Type: `boolean`
+
+If `true`, switching the video element into picture-in-picture is disabled. Default is `false`.
+
+This has no effect on Firefox, which implements a proprietary picture-in-picture mode which does not implement the standard picture-in-picture API.
+
+This does not disable the document picture-in-picture mode which allows the player element to put into a PiP window.
+
+### `enableDocumentPictureInPicture`
+
+> Type: `boolean`
+
+_Since 8.3.0_
+
+If `true`, the [documentPictureInPicture API](https://developer.chrome.com/docs/web-platform/document-picture-in-picture/) will be used for picture-in-picture, if available. Defaults to `false`, but may default to `true` when the feature has become established.
+
+Currently this is available in Chrome 111+ as an origin trial.
+
+This is a different picture-in-picture mode than has previously been available, where the entire player element is windowed rather than just the video itself. Since there are scenarios where it would be desirable to allow PiP on the player but not PiP on the video alone (such as ads, overlays), the `disablePictureInPicture` option **only** disables the old-style picture-in-picture mode on the video.
+
 ### `fluid`
 
 > Type: `boolean`
@@ -373,10 +395,14 @@ If set to an HTML Element, that element would replace the disposed player instea
 
 > Type: `Object`
 
+_Since 8.2.0_
+
 ### `skipButtons.forward`
 
 > Type: `number`
 
+_Since 8.2.0_
+
 If specified, Video.js displays a control allowing the 
 user to jump forward in a video by the specified number of seconds.
 
@@ -396,6 +422,8 @@ videojs('my-player', {
 
 > Type: `number`
 
+_Since 8.2.0_
+
 If specified, Video.js displays a control allowing the 
 user to jump back in a video by the specified number of seconds.
 
diff --git a/src/mdx-pages/guides/picture-in-picture.mdx b/src/mdx-pages/guides/picture-in-picture.mdx
@@ -0,0 +1,57 @@
+---
+title: Picture-in-Picture Options
+category: advanced
+description: Picture-in-picture modes available to a Video.js player. 
+---
+
+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][disable-elpip].
+
+By default this mode is enabled if the browser supports the [picture-in-picture API][pip-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][doc-pip] 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][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][enable-docpip]. 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`][disable-elpip] and document PiP (docPiP) [`enableDocumentPictureInPicture`][enable-docpip] 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.
+
+| disablePictureInPicture | enableDocumentPictureInPicture | Effect* |
+| ----------------------- | ------------------------------ | ------ |
+| `false` (default)       | `false` (default)              | vPiP used on browsers that support it. |
+| `false` (default)       | `true`                         | docPiP will be used if the browser supports it, otherwise vPiP used on browsers that support it. |
+| `true`                  | `true`                         | docPiP will be used if the browser supports it. vPiP will not be used. |
+| `true`                  | `false` (default)              | Neither docPiP not vPiP will be used. |
+
+_* None of these options can have any effect on Firefox's behaviour._
+
+[pip-api]: https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API
+[doc-pip]: https://developer.chrome.com/docs/web-platform/document-picture-in-picture/
+[origin-trial]: https://developer.chrome.com/docs/web-platform/origin-trials/
+[disable-elpip]: /guides/options/#disablepictureinpicture
+[enable-docpip]: /guides/options/#enabledocumentpictureinpicture
diff --git a/src/templates/HomeTemplate.jsx b/src/templates/HomeTemplate.jsx
@@ -11,6 +11,7 @@ import Sponsors from '../components/HomeComponents/Sponsors';
 import Implementation from '../components/HomeComponents/Implementation';
 import AdvancedExample from '../components/HomeComponents/AdvancedExample';
 import GetInvolved from '../components/HomeComponents/GetInvolved';
+import { Helmet } from 'react-helmet';
 
 const IndexPage = props => {
   const themeName = props.pageContext.theme;
@@ -23,6 +24,10 @@ const IndexPage = props => {
         keywords={['HTML5 video', 'player', 'hls', 'adaptive-bitrate']}
         description="The world's most popular open source HTML5 player framework"
       />
+      <Helmet>
+        {/* Origin trial for documentPictureInPicture */}
+        <meta http-equiv="origin-trial" content="AtSClXdNOoAPsggUV+nqh187coO6axCtgTdtFue+P9rz9xqRA5qjlz0AB92Edaxh9imwk/NJueqxdO9QmkqrswUAAABzeyJvcmlnaW4iOiJodHRwczovL3ZpZGVvanMuY29tOjQ0MyIsImZlYXR1cmUiOiJEb2N1bWVudFBpY3R1cmVJblBpY3R1cmVBUEkiLCJleHBpcnkiOjE2OTQxMzExOTksImlzU3ViZG9tYWluIjp0cnVlfQ==" />
+      </Helmet>
       <Hero
         heroTheme={heroTheme}
         transitionDuration={props.transitionDuration}
