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]
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. A local file edit alone does not prove that clients received it. [S1]
Test manual entry first
Recommended sequence:
- Record the server and client build using the version guide.
- Join a disposable test meeting in a supported browser and use its PiP control if available.
- Confirm the selected participant or expected avatar appears, the available controls work, and meeting audio continues.
- Close the PiP surface and verify the original meeting still works.
- 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 for that context rather than applying desktop-browser behavior to every client. [S1]
Sources
- [S1] Pinned 11248 configuration, client PiP gate, toolbar/automatic hooks, and External API controller.
- [S2] Jitsi issue #18060, opened 21 October 2026, checked 24 October; report and hypotheses, not a confirmed fix.
- [S3] Chrome’s automatic picture-in-picture requirements.
- [S4] Document PiP API and compatibility, including secure-context requirements.