PictureInPicture Reference¶

class PictureInPicture()¶

This module is responsible for creating a Picture in Picture window to host a clone of a video element running in web content.

static PictureInPicture.addOriginatingWinToWeakMap(browser)¶

Increase the count of PiP windows for a given AppWindow.

Arguments:

browser (Browser) – The content browser that the originating video lives in and from which we’ll read its parent window to increase PiP window count in originatingWinWeakMap.

static PictureInPicture.addPiPBrowserToWeakMap(browser)¶

Increase the count of PiP windows for a given browser

Arguments:

browser – The browser to increase PiP count in browserWeakMap

static PictureInPicture.clearPipTabIcon(window)¶

Remove attribute which enables pip icon in tab

Arguments:

window (Window) – A PictureInPicture player’s window, used to resolve the player’s associated originating content browser

static PictureInPicture.closePipWindow(pipWin)¶

Closes and waits for passed PiP player window to finish closing.

Arguments:

pipWin (Window) – Player window to close

static PictureInPicture.closeSinglePipWindow(closeData)¶

Closes a single PiP window. Used exclusively in conjunction with support for multiple PiP windows

Arguments:

closeData (Object) – Additional data required to complete a close operation on a PiP window
closeData.actorRef (PictureInPictureParent) – The PictureInPictureParent actor associated with the PiP window being closed
closeData.reason (string) – The reason for closing this PiP window

static PictureInPicture.fitToScreen(requestingWin, videoData)¶

This function tries to restore the last known Picture-in-Picture location and size. If those values are unknown or offscreen, then a default location and size is used.

Arguments:

requestingWin (ChromeWindow|PlayerWindow) – The window hosting the browser that requested the Picture in Picture window. If this is an existing player window then the returned player size and position will be determined based on the existing player window’s size and position.
videoData (object) – An object containing the following properties: videoHeight (int): The preferred height of the video. videoWidth (int): The preferred width of the video.

Returns:

object – The size and position for the player window, in CSS pixels relative to requestingWin. top (int): The top position for the player window. left (int): The left position for the player window. width (int): The width of the player window. height (int): The height of the player window.

static PictureInPicture.getAvailScreenSize(screen)¶

This function takes a screen and will return the left, top, width and height of the screen

Arguments:

screen (Screen) – The screen we need to get the size and coordinates of

Returns:

array – Size and location of screen in desktop pixels. screenLeft.value (int): The left position for the screen. screenTop.value (int): The top position for the screen. screenWidth.value (int): The width of the screen. screenHeight.value (int): The height of the screen.

static PictureInPicture.getEligiblePipVideoCount(browser)¶

Gets the total eligible video count and total PiPDisabled count for a given browser.

Arguments:

browser (Browser) – The selected browser

Returns:

Total count of eligible PiP videos for the selected broser

static PictureInPicture.getPanelForBrowser(browser)¶

Get the PiP panel for a browser. Create the panel if needed.

Arguments:

browser (Browser) – The current browser

Returns:

panel The panel element

static PictureInPicture.getWeakPipPlayer(pipActorRef)¶

Returns the player window if one exists and if it hasn’t yet been closed.

Arguments:

pipActorRef (PictureInPictureParent) – Reference to the calling PictureInPictureParent actor

Returns:

Window – the player window if it exists and is not in the process of being closed. Returns null otherwise.

static PictureInPicture.getWorkingScreen(left, top, width, height)¶

This function takes in a rect in desktop pixels, and returns the screen it is located on.

If the left and top are not on any screen, it will return the default screen.

Arguments:

left (int) – left or x coordinate
top (int) – top or y coordinate
width (int) – top or y coordinate
height (int) – top or y coordinate

Returns:

Screen – screen the screen the left and top are on otherwise, default screen

static PictureInPicture.handlePictureInPictureRequest(wgps, videoData)¶

A request has come up from content to open a Picture in Picture window.

Arguments:

wgps (WindowGlobalParent) – The WindowGlobalParent that is requesting the Picture in Picture window.
videoData (object) – An object containing the following properties: videoHeight (int): The preferred height of the video. videoWidth (int): The preferred width of the video.

Returns:

Promise – Resolves once the Picture in Picture window has been created, and the player component inside it has finished loading.

static PictureInPicture.isOriginatingBrowser(browser)¶

This is used in AsyncTabSwitcher.sys.mjs and tabbrowser.js to check if the browser currently has a PiP window. If the browser has a PiP window we want to keep the browser in an active state because the browser is still partially visible.

Arguments:

browser – The browser to check if it has a PiP window

Returns:

true if browser has PiP window else false

static PictureInPicture.loadPosition()¶

Load last Picture in Picture location and size

Returns:: object – The size and position of the last Picture in Picture window. top (int): The top position for the last player window. Otherwise NaN left (int): The left position for the last player window. Otherwise NaN width (int): The width of the player last window. Otherwise NaN height (int): The height of the player last window. Otherwise NaN

static PictureInPicture.onCommand(event)¶

Called when the browser UI handles the View:PictureInPicture command via the keyboard.

Arguments:

event (Event) –

static PictureInPicture.onPipPanelHidden(event)¶

Update the visibility of the urlbar PiP button when the panel is hidden. The button will show when there is more than 1 video and at least 1 video has PiPDisabled. If we no longer want to respect PiPDisabled then we need to check if the urlbar button should still be visible.

Arguments:

event (Event) – The panel hidden event

static PictureInPicture.onPipPanelShown(event)¶

Set the toggle for PiPDisabled when the panel is shown. If the pref is set from about:config, we need to update the toggle switch in the panel to match the pref.

Arguments:

event (Event) – The panel shown event

static PictureInPicture.openPipWindow(parentWin, videoData, actorReference)¶

Open a Picture in Picture window on the same screen as parentWin, sized based on the information in videoData.

Arguments:

parentWin (ChromeWindow) – The window hosting the browser that requested the Picture in Picture window.
videoData (object) – An object containing the following properties: videoHeight (int): The preferred height of the video. videoWidth (int): The preferred width of the video.
actorReference (PictureInPictureParent) – Reference to the calling PictureInPictureParent

Returns:

Promise – Resolves once the window has opened and loaded the player component.

static PictureInPicture.openToggleContextMenu(window, data)¶

Opens the context menu for toggling PictureInPicture.

Arguments:

window (Window) –
data (object) – Message data from the PictureInPictureToggleParent

static PictureInPicture.removeOriginatingWinFromWeakMap(browser)¶

Decrease the count of PiP windows for a given AppWindow. If the count becomes 0, we will remove the AppWindow from the WeakMap.

Arguments:

browser (Browser) – The content browser that the originating video lives in and from which we’ll read its parent window to decrease PiP window count in originatingWinWeakMap.

static PictureInPicture.removePiPBrowserFromWeakMap(browser)¶

Decrease the count of PiP windows for a given browser. If the count becomes 0, we will remove the browser from the WeakMap

Arguments:

browser – The browser to decrease PiP count in browserWeakMap

static PictureInPicture.resizePictureInPictureWindow(videoData, actorRef)¶

Resizes the the PictureInPicture player window.

Arguments:

videoData (object) – The source video’s data.
actorRef (PictureInPictureParent) – Reference to the PictureInPicture parent actor.

static PictureInPicture.resolveOverlapConflicts(left, top, width, height)¶

This function will take the size and potential location of a new Picture-in-Picture player window, and try to return the location coordinates that will best ensure that the player window will not overlap with other pre-existing player windows.

Arguments:

left (int) – x position of left edge for Picture-in-Picture window that is being opened
top (int) – y position of top edge for Picture-in-Picture window that is being opened
width (int) – Width of Picture-in-Picture window that is being opened
height (int) – Height of Picture-in-Picture window that is being opened

Returns:

object – An object with the following properties: top (int): The recommended top position for the player window. left (int): The recommended left position for the player window.

static PictureInPicture.savePosition(win)¶

Saves position and size of Picture-in-Picture window

Arguments:

win (Window) – The Picture-in-Picture window

static PictureInPicture.setOriginatingWindowActive(browsingContext, isActive)¶

Calls the browsingContext’s forceAppWindowActive flag to determine if the the top level chrome browsingContext should be forcefully set as active or not. When the originating window’s browsing context is set to active, captions on the PiP window are properly updated. Forcing active while a PiP window is open ensures that captions are still updated when the originating window is occluded.

Arguments:

browsingContext (BrowsingContext) – The browsing context of the originating window
isActive (boolean) – True to force originating window as active, or false to not enforce it