Bug 303885 – [iOS/iPadOS] requestPictureInPicture() (PiP / PinP) does not work in Home Screen Web Apps (PWA) on iOS/iPadOS

• Status: NEW
• Component: Media

SUMMARY
-------
On iOS and iPadOS, a website can enter Picture-in-Picture (PiP / PinP) using `HTMLVideoElement.requestPictureInPicture()` when loaded in Safari.

However, if the same site is installed to the Home Screen as a PWA (`display: "standalone"` in manifest), the video element no longer supports Picture-in-Picture:

  - The built-in PiP control disappears from the media controls.
  - Calling `video.requestPictureInPicture()` from a user gesture either throws `NotSupportedError` or silently does nothing, even though `document.pictureInPictureEnabled === true`.

This makes it impossible to offer PiP in Home Screen web apps, despite it working in Safari on the same device with the same page.

This issue closely parallels Bug 254545 (Wake Lock API not working in Home Screen Web Apps), which was resolved in iOS 18.4 after Safari adopted new WebKit API. The root cause may be similar: a capability that works in Safari but is not exposed to the standalone PWA context.


STEPS TO REPRODUCE
------------------
1. Open a test page in Safari on iOS/iPadOS with:
   - A `<video>` element playing a video stream
   - A button that calls `video.requestPictureInPicture()` on click

   Live test page (created by Anton Barkovsky, another developer affected by this issue):
   https://anton.codes/ios-pwa-video-issues/
   Source code: https://github.com/zemlanin/ios-pwa-video-issues

   Minimal reproduction code:

   <video id="player" controls playsinline>
     <source src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" type="application/x-mpegURL">
   </video>
   <button id="pip">requestPictureInPicture</button>

   <script>
     document.getElementById('pip').addEventListener('click', async () => {
       const video = document.getElementById('player');
       try {
         console.log('pictureInPictureEnabled:', document.pictureInPictureEnabled);
         await video.requestPictureInPicture();
         console.log('Entered PiP');
       } catch (err) {
         console.error(err.name, err.message);
       }
     });
   </script>

2. In Safari, start video playback and tap the PiP button.
   → PiP works correctly. The video detaches into a floating window.

3. Add the same page to the Home Screen ("Add to Home Screen").

4. Launch from the Home Screen icon (opens in standalone mode, no Safari UI).

5. Start playback and tap the PiP button.


EXPECTED RESULT
---------------
Home Screen web apps should have the same Picture-in-Picture capabilities as the same origin loaded in Safari:

  - The built-in PiP control should appear on `<video>` elements.
  - `video.requestPictureInPicture()` called from a user gesture should enter PiP successfully.

The only difference between the two contexts is the display mode. The underlying WebKit engine capabilities should be identical.


ACTUAL RESULT
-------------
In the Home Screen / standalone context:

  - The system PiP button is missing from video controls.
  - `document.pictureInPictureEnabled` still returns `true`.
  - `video.requestPictureInPicture()` called from a click handler:
    - Either throws: `NotSupportedError: The video element does not support the Picture-in-Picture mode.`
    - Or silently does nothing (no exception, no PiP).

The same URL, same code, and same user interaction work correctly in Safari.


ENVIRONMENT
-----------
I have personally reproduced this issue on:
  - iOS 18.5, iPhone SE (2nd generation)
  - iPadOS 18.3.1, iPad (7th generation, 2019)
  - iOS 26.1 beta, iPhone 17

Other developers have reported the same behavior across a wide range of devices and OS versions:
  - iOS 14.5 through iOS 18.x (Stack Overflow, 2021–present)
  - iPadOS 18.x (Apple Developer Forums)
  - iOS/iPadOS 26 Developer Beta 1 (Anton Barkovsky's blog)

The issue occurs regardless of:
  - Video format (HLS, MP4, ManagedMediaSource, MediaSource)
  - Using `<source>` vs `src` attribute
  - Using native controls vs custom PiP button

This suggests the problem has existed since at least iOS 14.5 (circa 2021) and persists in current releases and developer betas.


RELATED REPORTS
---------------
Multiple developers have independently reported this issue over the past four years:

  - Stack Overflow (Feb 2021): "requestPictureInPicture not working on iOS PWA"
    A developer reported that PiP works in Safari but throws `NotSupportedError` when the same site is launched from the Home Screen. The question remains unresolved.
    https://stackoverflow.com/questions/66048676/requestpictureinpicture-not-working-on-ios-pwa

  - Anton Barkovsky's blog (2024–2025): "iOS PWA Video Issues"
    Provides a live reproduction page demonstrating that `video.requestPictureInPicture` does nothing in PWA mode even when `document.pictureInPictureEnabled` is `true`. The author notes the issue persists in iOS/iPadOS 26 Developer Beta 1 and has filed Apple Feedback Assistant report FB17983433.
    https://anton.codes/ios-pwa-video-issues/

  - Apple Developer Forums: "PiP on iOS doesn't work when safari site is added to home screen"
    A developer reported that the PiP button disappears entirely and `requestPictureInPicture()` throws `NotSupportedError` in Home Screen mode, while the same site works in Safari.
    https://discussions.apple.com/thread/255709452

  - WebKit Bug 254545: Same pattern with Wake Lock API
    Wake Lock worked in Safari but failed in Home Screen Web Apps. This was fixed in iOS 18.4 after Safari adopted the new WebKit API. The current PiP issue may require a similar fix.
    https://bugs.webkit.org/show_bug.cgi?id=254545

The existence of Anton Barkovsky's well-documented test page demonstrates that multiple developers are affected and have invested effort into diagnosing this issue.


IMPACT
------
For media-centric PWAs (live TV players, video streaming apps, conferencing tools), PiP is essential to the user experience on iOS/iPadOS.

Currently, developers must choose between:
  - "Install our app to Home Screen, but you lose PiP functionality", or
  - "Use Safari if you want PiP; the Home Screen app is strictly inferior."

This significantly degrades the value proposition of Home Screen web apps compared to:
  - The same experience in Safari on the same device
  - PWAs on other platforms where PiP works in standalone mode

Aligning Home Screen web app capabilities with Safari would immediately improve media PWA quality on iOS and iPadOS.

[Alexey Proskuryakov]

rdar://121964774

Thank you for the report! This is tracked as the above issue by Apple internally, so if your theory is correct, then the action will be there, not in Bugzilla.