spec:dom; type:interface; text:Document

spec:html; type:attribute; for:HTMLMediaElement; text:readyState

spec:html; type:dfn; for:/; text:browsing context

spec:html; type:dfn; text:allowed to use

spec:infra; type:dfn; text:user agent

spec:infra; type:dfn; for:list; text:item

</pre>

# Concepts # {#concepts}

## Internal Slot Definitions ## {#defines}

## Definitions ## {#defines}

A <dfn>Picture-in-Picture window</dfn> is a window displaying the <{video}> element.

A {{DocumentOrShadowRoot}} has:

1. A <dfn>Picture-in-Picture element</dfn>, which is an {{Element}} or `null`, initially `null`.

A <a for="/">traversable navigable</a> has:

1. A <dfn>picture-in-picture parallel queue</dfn>, which is a [=parallel queue=] created by

[=starting a new parallel queue=].

A <a>user agent</a> has:

1. An <dfn>initiators of active Picture-in-Picture sessions</dfn>

list of zero or more <a>origins</a>, which is initially empty.

Note: In case a <a>user agent</a> supports multiple Picture-in-Picture

windows, the list allows duplicates.

Note: In case a <a>user agent</a> supports multiple Picture-in-Picture windows, the list allows duplicates.

An origin is said to have an active Picture-in-Picture session if any

of the origins in <a>initiators of active Picture-in-Picture sessions</a>

are <a>same origin-domain</a> with origin.

## Request Picture-in-Picture ## {#request-pip}

When the <dfn>request Picture-in-Picture algorithm</dfn> with |video| is invoked,

the user agent MUST run the following steps:

1. If <a>Picture-in-Picture support</a> is `false`, throw a

{{NotSupportedError}} and abort these steps.

2. If the document is not <a>allowed to use</a> the <a>policy-controlled feature</a>

named `"picture-in-picture"`, throw a {{SecurityError}} and abort these

steps.

3. If |video|'s {{readyState}} attribute is {{HAVE_NOTHING}}, throw a

{{InvalidStateError}} and abort these steps.

4. If |video| has no video track, throw a {{InvalidStateError}} and abort

these steps.

5. If |video|'s {{HTMLVideoElement/disablePictureInPicture}} is true,

the user agent MAY throw an {{InvalidStateError}} and abort these steps.

6. If {{pictureInPictureElement}} is `null`:

1. If <a>this</a>'s <a>relevant global object</a> does not have

<a>transient activation</a>, throw a {{NotAllowedError}} and abort these steps.

2. [=Consume user activation=] given <a>this</a>'s <a>relevant global object</a>.

7. If |video| is {{pictureInPictureElement}}, abort these steps.

8. Set {{pictureInPictureElement}} to |video|.

9. Let <dfn>Picture-in-Picture window</dfn> be a new instance of

{{PictureInPictureWindow}} associated with {{pictureInPictureElement}}.

10. Append <a>relevant settings object</a>'s <a>origin</a> to

<a>initiators of active Picture-in-Picture sessions</a>.

11. <a>Queue a task</a> to <a>fire an event</a> named

{{enterpictureinpicture}} using {{PictureInPictureEvent}} at the

|video| with its {{bubbles}} attribute initialized to `true` and its

{{PictureInPictureEvent/pictureInPictureWindow}} attribute initialized to

<a>Picture-in-Picture window</a>.

12. If {{pictureInPictureElement}} is <a>fullscreenElement</a>, it is

RECOMMENDED to <a>exit fullscreen</a>.

## Picture-in-Picture ## {#pip}

It is RECOMMENDED that video frames are not rendered in the page and in the

Picture-in-Picture window at the same time but if they are, they MUST be kept

minimum size. For example, it could be restricted to be between a quarter and

a half of one dimension of the screen.

When a {{DocumentOrShadowRoot}}'s {{pictureInPictureElement}} attribute is set,

When a {{DocumentOrShadowRoot}}'s <a>Picture-in-Picture element</a> is set,

the [=Picture-in-Picture window=] MUST be visible, even when the

{{DocumentOrShadowRoot}}'s [=relevant global object=]'s [=associated Document=]'s

[=Document/visibility state=] is "hidden".

};

</pre>

The {{requestPictureInPicture()}} method, when invoked, MUST

return <a>a new promise</a> |promise| and run the following steps <a>in

parallel</a>:

The {{requestPictureInPicture()}} method steps <dfn export>request Picture-in-Picture</dfn>:

1. If [=Picture-in-Picture support=] is `false`, return [=a promise rejected with=] {{NotSupportedError}} {{DOMException}}.

2. Let |doc| be [=this=]'s [=node document=].

3. If |doc| is not [=allowed to use=] the [=policy-controlled feature=]

named `"picture-in-picture"`, return [=a promise rejected with=] {{NotAllowedError}} {{DOMException}}.

4. If [=this=]'s {{readyState}} attribute is {{HAVE_NOTHING}}, return [=a promise rejected with=] {{InvalidStateError}} {{DOMException}}.

5. If [=this=] has no video track, return [=a promise rejected with=] {{InvalidStateError}} {{DOMException}}.

6. If [=this=]'s {{HTMLVideoElement/disablePictureInPicture}} is true, user agent may return [=a promise rejected with=] {{InvalidStateError}} {{DOMException}}.

7. If |doc|'s [=Picture-in-Picture element=] is `null`:

1. If [=this=]'s [=relevant global object=] does not have a [=transient activation=], then return [=a

promise rejected with=] {{NotAllowedError}} {{DOMException}}.

2. [=Consume user activation=] given [=this=]'s [=relevant global object=].

8. If [=this=] is |doc|'s [=Picture-in-Picture element=]:

1. Return [=a promise resolved with=] the [=Picture-in-Picture window=] associated with |doc|'s [=Picture-in-Picture element=].

9. Let |global| be [=this=]'s [=relevant global object=].

10. Let |p| be [=a new promise=] created in [=this=]'s [=relevant realm=].

11. Return |p|, and [=enqueue the following steps=] to |doc|'s [=picture-in-picture parallel queue=]:

1. If [=this=] is |doc|'s [=Picture-in-Picture element=]:

1. [=Queue a global task=] on the [=media element event task source=] given |global| to

[=/resolve=] |p| with the [=Picture-in-Picture window=] associated with

[=this=].

2. Abort these steps.

2. Attempt to associate a [=Picture-in-Picture window=] with [=this=].

3. If the previous step failed:

1. [=Queue a global task=] on the [=media element event task source=] given |global| to

[=/reject=] |p| with {{InvalidStateError}} {{DOMException}}.

2. Abort these steps.

4. Let |pipWindow| be a new instance of {{PictureInPictureWindow}} that represents [=this=]'s associated [=Picture-in-Picture window=].

5. [=Queue a global task=] on the [=media element event task source=] given |global|, to perform

the following steps:

1. If {{pictureInPictureElement}} is not `null`, run the [=exit Picture-in-Picture algorithm=].

2. Set |doc|'s [=Picture-in-Picture element=] to [=this=].

3. [=list/Append=] [=relevant settings object=]'s [=origin=] to [=initiators of active

Picture-in-Picture sessions=].

4. If [=this=] is [=fullscreenElement=], [=exit fullscreen=].

5. [=Fire an event=] named {{enterpictureinpicture}} using {{PictureInPictureEvent}} at

[=this=] with its {{bubbles}} attribute initialized to `true` and its

{{PictureInPictureEvent/pictureInPictureWindow}} attribute initialized to

[=Picture-in-Picture window=].

6. [=/Resolve=] |p| with |pipWindow|.

1. Let |video| be the video element on which the method was invoked.

2. Run the <a>request Picture-in-Picture algorithm</a> with |video|.

3. If the previous step threw an exception, reject |promise| with that

exception and abort these steps.

4. [=/Resolve=] |promise| with the <a>Picture-in-Picture window</a> associated with

{{pictureInPictureElement}}.

## Extensions to <code>Document</code> ## {#document-extensions}

1. If <a>this</a> is a <a for=/>shadow root</a> and its <a for=DocumentFragment>host</a>

is not <a>connected</a>, return `null` and abort these steps.

2. Let |candidate| be the result of <a>retargeting</a> Picture-in-Picture

element against <a>this</a>.

2. Let |candidate| be the result of [=retargeting=] [=Picture-in-Picture element=] against [=this=].

3. If |candidate| and <a>this</a> are in the same <a>tree</a>,

return |candidate| and abort these steps.

4. Return `null`.

## Permissions Policy ## {#permissions-policy}

This specification defines a <a>policy-controlled feature</a> named

`"picture-in-picture"` that controls whether the <a>request Picture-in-Picture

algorithm</a> may return a {{SecurityError}} and whether

`"picture-in-picture"` that controls whether [=request Picture-in-Picture=]

returns a {{SecurityError}} and whether

{{pictureInPictureEnabled}} is `true` or `false`.

The <a>default allowlist</a> for this feature is `*`.