# Jitsi picture-in-picture not working

> First separate a missing PiP control from a failure to open automatically. In the reviewed Jitsi Meet 11248 client, browser PiP is opt-in: pip.enableBrowserPiP must be true, supported browser APIs must exist, and other visibility rules still apply. A working manual button does not prove automatic tab-switch behavior. [S1][S2]

Source: https://jitsi.help/troubleshooting/jitsi-picture-in-picture-not-working/
Updated: October 24, 2026
Publisher: Jitsi Help (https://jitsi.help/)

## Identify which part fails

| Symptom | First check |
| --- | --- |
| No PiP button | Client build, merged configuration and browser API support. [S1] |
| Button exists but opening fails | Secure context, browser restrictions and the exact error. [S1][S4] |
| Manual opening works, tab switching does nothing | Automatic-entry eligibility and the current issue status. [S2][S3] |
| No PiP before joining | `pip.showOnPrejoin` defaults to false in the reviewed config. [S1] |
| Avatar appears instead of video | The selected track may be absent, muted or inactive; this alone does not prove a PiP failure. [S1] |

## Check the deployment before changing the browser

This review uses Jitsi Meet 11248 source commit `f765042`. Its client requires `pip.enableBrowserPiP === true` outside Electron. `pip.disabled` is a separate global switch, and `pip.showToolbarButton` controls the manual trigger. The external API's preliminary capability check is intentionally more permissive than the client's final merged-config check. [S1]

On a server you operate, preserve existing policy when enabling the feature. For Docker, add the following to the existing `custom-config.js` through your normal configuration workflow. For package installs, merge the equivalent options into the installed web configuration. Do not replace an entire configuration with this fragment. [S1]

```javascript
config.pip = {
    ...config.pip,
    enableBrowserPiP: true,
    showToolbarButton: true
};
```

This preserves any explicit `disabled` value; if your organization disabled PiP deliberately, resolve that policy first. Recreate or reload through the installation's normal procedure and verify the configuration actually served to a fresh client. See [custom configuration diagnostics](/troubleshooting/custom-config-js-ignored/). A local file edit alone does not prove that clients received it. [S1]

## Test manual entry first

Recommended sequence:

1. Record the server and client build using [the version guide](/guides/check-jitsi-version/).
2. Join a disposable test meeting in a supported browser and use its PiP control if available.
3. Confirm the selected participant or expected avatar appears, the available controls work, and meeting audio continues.
4. Close the PiP surface and verify the original meeting still works.
5. Only then test automatic entry by moving to another tab and returning.

Document PiP is an HTTPS browser feature with limited availability. Browser policies for automatic PiP are separate from a normal manual request; Chrome's documentation describes eligibility and its site-level control. Do not assume that enabling a button bypasses those requirements. [S3][S4]

## Embedded meetings need a separate check

An iframe cannot directly create a Document PiP window as though it were the top-level page. Jitsi's implementation coordinates with the embedding page through its External API transport. Keep the matching API script and meeting deployment together; a hand-written extra iframe is not equivalent to that integration. [S1][S4]

The selected video is forwarded to the embedded PiP surface, while meeting audio remains in the original iframe. Closing or unloading that iframe is not a way to keep the call running in PiP. [S1]

On 21 October 2026, issue #18060 reported manual opening working but automatic tab-switch entry failing in an embedded configuration. As of this review the issue was open. Its author proposed an origin/MediaSession explanation and later noted the scope might be wider. Neither that hypothesis nor a universal workaround is confirmed. [S2]

For support, record manual and automatic results separately for a direct meeting, a same-origin embed and a cross-origin embed where your test environment supports them. Do not describe an untested combination as supported simply because an announcement exists. [S1][S2]

## Open questions and maintenance

These are source-reviewed diagnostics and a configuration fragment, not a completed browser/device test matrix. We have not reproduced automatic entry, cross-origin PiP media or permission prompts in this review. Retain the original meeting as a fallback and recheck issue #18060 and the installed release before recommending a patch. [S2]

Mobile apps, mobile SDKs and Electron have different implementations. Use [the mobile guide](/guides/jitsi-meet-mobile-app/) for that context rather than applying desktop-browser behavior to every client. [S1]

## Sources

- **[S1]** Pinned 11248 [configuration](https://github.com/jitsi/jitsi-meet/blob/f765042bf280cbd7dcd4a9bbdb63b09e9e4d3259/config.js), [client PiP gate](https://github.com/jitsi/jitsi-meet/blob/f765042bf280cbd7dcd4a9bbdb63b09e9e4d3259/react/features/pip/functions.ts), [toolbar/automatic hooks](https://github.com/jitsi/jitsi-meet/blob/f765042bf280cbd7dcd4a9bbdb63b09e9e4d3259/react/features/pip/hooks.ts), and [External API controller](https://github.com/jitsi/jitsi-meet/blob/f765042bf280cbd7dcd4a9bbdb63b09e9e4d3259/modules/API/external/external_api.js).
- **[S2]** [Jitsi issue #18060](https://github.com/jitsi/jitsi-meet/issues/18060), opened 21 October 2026, checked 24 October; report and hypotheses, not a confirmed fix.
- **[S3]** Chrome's [automatic picture-in-picture requirements](https://developer.chrome.com/blog/automatic-picture-in-picture).
- **[S4]** [Document PiP API and compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Document_Picture-in-Picture_API), including secure-context requirements.

## Frequently asked questions

### Why is the Jitsi PiP button missing?

Check the deployed client version and merged configuration. In the reviewed browser client, PiP requires enableBrowserPiP to be true, browser support and no global disabled switch. The toolbar and prejoin visibility settings also matter.

### Does a working PiP button mean automatic opening must work?

No. Automatic entry has separate browser eligibility and permission requirements. An open October 2026 report describes manual success with failed tab-switch entry in an embedded setup; its root cause and fix remain unconfirmed.

### Is Document PiP supported by every browser?

No. Document PiP and video-only PiP are different APIs. Jitsi can choose a supported implementation, but browser, client and embedding context must be checked separately.

### Why does an embedded PiP window have no separate audio?

The reviewed embedded implementation forwards the selected video to its PiP surface while conference audio stays in the original meeting iframe. Keep the original meeting open and verify its audio path.

### Can a meeting participant enable PiP on someone else's server?

The service operator controls its deployed configuration. Ask the operator about feature availability. A configuration example for your own server is not proof that a public service offers the feature.


---

Jitsi Help is an independent service. It is not affiliated with, endorsed by or sponsored by 8x8, Inc. or the Jitsi project. Jitsi and Jitsi Meet are trademarks of 8x8, Inc., used here only to describe the software we host and support.