VBLOCKS-4212 documentPictureInPicture support (#2093)

* VBLOCKS-4212 documentPictureInPicture support

* Fix build and address PR review

* Adding tests

* Adding changelog

Author: charliesantos

CHANGELOG.md

@@ -2,6 +2,16 @@ The Twilio Programmable Video SDKs use [Semantic Versioning](http://www.semver.o
 
 **Version 1.x reached End of Life on September 8th, 2021.** See the changelog entry [here](https://www.twilio.com/changelog/end-of-life-complete-for-unsupported-versions-of-the-programmable-video-sdk). Support for the 1.x version ended on December 4th, 2020.
 
+2.31.0 (In Progress)
+====================
+
+New Features
+------------
+
+### Document Picture-in-Picture API Support
+
+Previously, when `Client Track Switch Off Control` was set to `auto`, video tracks were automatically switched off—even if they were visible and rendered in a [Document Picture-in-Picture](https://developer.chrome.com/docs/web-platform/document-picture-in-picture) (PiP) window. This caused issues where users could see the video element, but the track itself was disabled. In this new SDK version, video tracks will remain active and continue to play when displayed in a PiP window.
+
 2.30.0 (March 28, 2025)
 ========================
 

lib/media/track/remotevideotrack.js

@@ -338,15 +338,19 @@ class RemoteVideoTrack extends RemoteMediaVideoTrack {
   }
 }
 
-function setupDocumentVisibilityTurnOff(removeVideoTrack) {
-  function onVisibilityChanged() {
-    maybeUpdateEnabledHint(removeVideoTrack);
+function isAttachedToDocumentPip(remoteVideoTrack) {
+  if (!('documentPictureInPicture' in globalThis)) {
+    return false;
   }
 
-  documentVisibilityMonitor.onVisibilityChange(1, onVisibilityChanged);
-  return () => {
-    documentVisibilityMonitor.offVisibilityChange(1, onVisibilityChanged);
-  };
+  const pipWindow = globalThis.documentPictureInPicture.window;
+  if (!pipWindow) {
+    return false;
+  }
+
+  const pipEls = new WeakSet(pipWindow.document.querySelectorAll('video'));
+
+  return remoteVideoTrack._getAllAttachedElements().some(el => pipEls.has(el));
 }
 
 function maybeUpdateEnabledHint(remoteVideoTrack) {
@@ -358,7 +362,9 @@ function maybeUpdateEnabledHint(remoteVideoTrack) {
   const pipWindows = remoteVideoTrack._getAllAttachedElements().filter(el => remoteVideoTrack._elToPipWindows.has(el));
 
   // even when document is invisible we may have track playing in pip window.
-  const enabled = pipWindows.length > 0 || (document.visibilityState === 'visible' && visibleElements.length > 0);
+  const enabled = pipWindows.length > 0 ||
+    isAttachedToDocumentPip(remoteVideoTrack) ||
+    (document.visibilityState === 'visible' && visibleElements.length > 0);
 
   if (enabled === true) {
     remoteVideoTrack._turnOffTimer.clear();
@@ -388,6 +394,17 @@ function maybeUpdateDimensionHint(remoteVideoTrack) {
   }
 }
 
+function setupDocumentVisibilityTurnOff(removeVideoTrack) {
+  function onVisibilityChanged() {
+    maybeUpdateEnabledHint(removeVideoTrack);
+  }
+
+  documentVisibilityMonitor.onVisibilityChange(1, onVisibilityChanged);
+  return () => {
+    documentVisibilityMonitor.offVisibilityChange(1, onVisibilityChanged);
+  };
+}
+
 /**
  * @typedef {object} VideoContentPreferences
  * @property {VideoTrack.Dimensions} [renderDimensions] - Render Dimensions to request for the {@link RemoteVideoTrack}.

test/unit/spec/media/track/remotevideotrack.js

@@ -414,6 +414,64 @@ describe('RemoteVideoTrack', () => {
       });
     });
   });
+
+  describe('Picture-in-Picture', () => {
+    let el;
+    let setRenderHintsSpy;
+    let track;
+    let originalDocumentPictureInPicture;
+    let pipEls;
+
+    const dispatchVisibilityChangeEvent = async () => {
+      document.visibilityState = 'visible';
+      document.dispatchEvent('visibilitychange');
+      await waitForSometime();
+    };
+
+    beforeEach(() => {
+      documentVisibilityMonitor.clear();
+      originalDocumentPictureInPicture = global.documentPictureInPicture;
+      global.documentPictureInPicture = { window: { document: { querySelectorAll: () => pipEls } } };
+      global.document = global.document || new Document();
+      setRenderHintsSpy = sinon.spy();
+      el = document.createElement('video');
+      track = makeTrack({ id: 'foo', sid: 'bar', setRenderHint: setRenderHintsSpy, options: { enableDocumentVisibilityTurnOff: true } });
+      track.attach(el);
+      pipEls = [el];
+    });
+
+    afterEach(() => {
+      global.documentPictureInPicture = originalDocumentPictureInPicture;
+      if (global.document instanceof Document) {
+        delete global.document;
+      }
+    });
+
+    it('should call _setRenderHint with enable = true', async () => {
+      await dispatchVisibilityChangeEvent();
+      sinon.assert.calledWith(setRenderHintsSpy, { enabled: true });
+    });
+
+    describe('should not call _setRenderHint', () => {
+      it('when documentPictureInPicture is not supported', async () => {
+        delete global.documentPictureInPicture;
+        await dispatchVisibilityChangeEvent();
+        sinon.assert.notCalled(setRenderHintsSpy);
+      });
+
+      it('when documentPictureInPicture window is not open', async () => {
+        delete global.documentPictureInPicture.window;
+        await dispatchVisibilityChangeEvent();
+        sinon.assert.notCalled(setRenderHintsSpy);
+      });
+
+      it('when els are not on the documentPictureInPicture window', async () => {
+        pipEls = [];
+        await dispatchVisibilityChangeEvent();
+        sinon.assert.notCalled(setRenderHintsSpy);
+      });
+    });
+  });
 });