# Picture-in-Picture

## Editor’s Draft, 1 January 1970

This version:
  https://w3c.github.io/picture-in-picture
Editors:
  François Beaufort (Google LLC)
  Mounir Lamouri (Google LLC)
Web Platform Tests:
  feature-policy/
  picture-in-picture/

Copyright © 1970 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

## Abstract

This specification intends to provide APIs to allow websites to create a floating video window always on top of other windows so that users may continue consuming media while they interact with other content sites, or applications on their device.

## Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the Media Working Group as an Editors' Draft. This document is intended to become a W3C Recommendation. Feedback and comments on this specification are welcome. Please use Github issues. Discussions may also be found in the public-media-wg@w3.org archives.

Publication as an Editors' Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

## 1. Introduction

This section is non-normative.

Many users want to continue consuming media while they interact with other content, sites, or applications on their device. A common UI affordance for this type of activity is Picture-in-Picture (PiP), where the video is contained in a separate miniature window that is always on top of other windows. This window stays visible even when user agent is not visible. Picture-in-Picture is a common platform-level feature among desktop and mobile OSs.

This specification aims to allow websites to initiate and control this behavior by exposing the following sets of properties to the API:

- Notify the website when it enters and leaves Picture-in-Picture mode.

- Allow the website to trigger Picture-in-Picture mode via a user gesture on a video element.

- Allow the website to know the size of the Picture-in-Picture window and notify the website when it changes.

- Allow the website to exit Picture-in-Picture mode.

- Allow the website to check if Picture-in-Picture mode can be triggered.

The proposed Picture-in-Picture API is very similar to [Fullscreen] as they have similar properties. The API only applies to `HTMLVideoElement` at the moment but is meant to be extensible.

## 2. Examples

### 2.1. Add a custom Picture-in-Picture button

    <video id="video" src="https://example.com/file.mp4"></video>

    <button id="togglePipButton"></button>

    <script>
      const video = document.getElementById('video');
      const togglePipButton = document.getElementById('togglePipButton');

      // Hide button if Picture-in-Picture is not supported or disabled.
      togglePipButton.hidden = !document.pictureInPictureEnabled ||
        video.disablePictureInPicture;

      togglePipButton.addEventListener('click', function() {
        // If there is no element in Picture-in-Picture yet, let’s request
        // Picture-in-Picture for the video, otherwise leave it.
        if (!document.pictureInPictureElement) {
          video.requestPictureInPicture()
          .catch(error => {
            // Video failed to enter Picture-in-Picture mode.
          });
        } else {
          document.exitPictureInPicture()
          .catch(error => {
            // Video failed to leave Picture-in-Picture mode.
          });
        }
      });
    </script>

### 2.2. Monitor video Picture-in-Picture changes

    <video id="video" src="https://example.com/file.mp4"></video>

    <script>
      const video = document.getElementById('video');

      video.addEventListener('enterpictureinpicture', function(event) {
        // Video entered Picture-in-Picture mode.
        const pipWindow = event.pictureInPictureWindow;
        console.log('Picture-in-Picture window width: ' + pipWindow.width);
        console.log('Picture-in-Picture window height: ' + pipWindow.height);
      });

      video.addEventListener('leavepictureinpicture', function() {
        // Video left Picture-in-Picture mode.
      });
    </script>

### 2.3. Update video size based on Picture-in-Picture window size changes

    <video id="video" src="https://example.com/file.mp4"></video>

    <button id="pipButton"></button>

    <script>
      let pipWindow;
      const video = document.getElementById('video');
      const pipButton = document.getElementById('pipButton');

      pipButton.addEventListener('click', function() {
        video.requestPictureInPicture()
        .catch(error => {
          // Video failed to enter Picture-in-Picture mode.
        });
      });

      video.addEventListener('enterpictureinpicture', function(event) {
        // Video entered Picture-in-Picture mode.
        pipWindow = event.pictureInPictureWindow;
        updateVideoSize(pipWindow.width, pipWindow.height);
        pipWindow.addEventListener('resize', onPipWindowResize);
      });

      video.addEventListener('leavepictureinpicture', function() {
        // Video left Picture-in-Picture mode.
        pipWindow.removeEventListener('resize', onPipWindowResize);
      });

      function onPipWindowResize(event) {
        // Picture-in-Picture window has been resized.
        updateVideoSize(event.target.width, event.target.height);
      }

      function updateVideoSize(width, height) {
        // TODO: Update video size based on pip window width and height.
      }
    </script>

## 3. Concepts

### 3.1. Request Picture-in-Picture

When the request Picture-in-Picture algorithm with video, userActivationRequired and playingRequired is invoked, the user agent MUST run the following steps:

1. If Picture-in-Picture support is `false`, throw a `NotSupportedError` and abort these steps.

2. If the document is not allowed to use the policy-controlled feature 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. OPTIONALLY, if the `disablePictureInPicture` attribute is present on video, throw an `InvalidStateError` and abort these steps.

6. If userActivationRequired is `true` and the algorithm is not triggered by user activation, throw a `NotAllowedError` and abort these steps.

7. If video is `pictureInPictureElement`, abort these steps.

8. If playingRequired is `true` and video is `paused`, abort these steps.

9. Set `pictureInPictureElement` to video.

10. Let Picture-in-Picture window be a new instance of `PictureInPictureWindow` associated with `pictureInPictureElement`.

11. Queue a task to fire an event with the name `enterpictureinpicture` using `EnterPictureInPictureEvent` at the video with its `bubbles` attribute initialized to `true` and its `pictureInPictureWindow` attribute initialized to Picture-in-Picture window.

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 in sync.

When a video is played in Picture-in-Picture mode, the states SHOULD transition as if it was played inline. That means that the events SHOULD fire at the same time, calling methods SHOULD have the same behaviour, etc. However, the user agent MAY transition out of Picture-in-Picture when the video element enters a state that is considered not compatible with Picture-in-Picture.

Styles applied to video (such as opacity, visibility, transform, etc.) MUST NOT apply in the Picture-in-Picture window. Its aspect ratio is based on the video size.

It is also RECOMMENDED that the Picture-in-Picture window has a maximum and minimum size. For example, it could be restricted to be between a quarter and a half of one dimension of the screen.

### 3.2. Exit Picture-in-Picture

When the exit Picture-in-Picture algorithm is invoked, the user agent MUST run the following steps:

1. If `pictureInPictureElement` is `null`, throw a `InvalidStateError` and abort these steps.

2. Run the close window algorithm with the Picture-in-Picture window associated with `pictureInPictureElement`.

3. Unset `pictureInPictureElement`.

4. Queue a task to fire an event with the name `leavepictureinpicture` at the video with its `bubbles` attribute initialized to `true`.

It is NOT RECOMMENDED that the video playback state changes when the exit Picture-in-Picture algorithm is invoked. The website SHOULD be in control of the experience if it is website initiated. However, the user agent MAY expose Picture-in-Picture window controls that change video playback state (e.g., pause).

As one of the unloading document cleanup steps, run the exit Picture-in-Picture algorithm.

### 3.3. Disable Picture-in-Picture

Some pages may want to disable Picture-in-Picture mode for a video element; for example, they may want to prevent the user agent from suggesting a Picture-in-Picture context menu or to request Picture-in-Picture automatically in some cases. To support these use cases, a new `disablePictureInPicture` attribute is added to the list of content attributes for video elements.

The `disablePictureInPicture` IDL attribute MUST reflect the content attribute of the same name.

If the `disablePictureInPicture` attribute is present on the video element, the user agent SHOULD NOT play the video element in Picture-in-Picture or present any UI to do so.

When the `disablePictureInPicture` attribute is added to a video element, the user agent SHOULD run these steps:

1. Reject any pending promises returned by the `requestPictureInPicture()` method with `InvalidStateError`.

2. If video is `pictureInPictureElement`, run the exit Picture-in-Picture algorithm.

### 3.4. Auto Picture-in-Picture

Some pages may want to automatically enter and leave Picture-in-Picture for a video element; for example, video meeting web apps would benefit from some automatic Picture-in-Picture behavior when the user switches back and forth between the web app and other applications/tabs. To support these use cases, a new `autoPictureInPicture` attribute is added to the list of content attributes for video elements.

The `autoPictureInPicture` IDL attribute MUST reflect the content attribute of the same name.

The autoPictureInPictureElement is the video element, among all video elements with the `autoPictureInPicture` attribute currently set, whose `autoPictureInPicture` attribute was set most recently. Note that the autoPictureInPictureElement can have the `disablePictureInPicture` attribute set. In that case, as expected, it won’t be allowed to enter Picture-in-Picture mode in the request Picture-in-Picture algorithm.

When the visibility state of a top-level browsing context value switches from "visible" to "hidden", the user agent MAY run these steps:

1. If autoPictureInPictureElement is `null`, abort these steps.

2. If `pictureInPictureElement` is set, abort these steps.

3. Let video be autoPictureInPictureElement.

4. Let userActivationRequired be `false`.

5. Let playingRequired be `true`.

6. Run the request Picture-in-Picture algorithm with video, userActivationRequired, and playingRequired.

When the visibility state of a top-level browsing context value switches from "hidden" to "visible", the user agent MAY run these steps:

1. If autoPictureInPictureElement is `null`, abort these steps.

2. If `pictureInPictureElement` is autoPictureInPictureElement, run the exit Picture-in-Picture algorithm.

### 3.5. Interaction with Remote Playback

The [Remote-Playback] specification defines a local playback device and a local playback state. For the purpose of Picture-in-Picture, the playback is local and regardless of whether it is played in page or in Picture-in-Picture.

### 3.6. Interaction with Media Session

The API will have to be used with the [MediaSession] API for customizing the available controls on the Picture-in-Picture window.

### 3.7. Interaction with Page Visibility

When `pictureInPictureElement` is set, the Picture-in-Picture window MUST be visible, even when the Document is not in focus or hidden. The user agent SHOULD provide a way for users to manually close the Picture-in-Picture window.

The [Page-Visibility] specification defines a `visibilityState` attribute used to determine the visibility state of a top-level browsing context. The Picture-in-Picture window visibility MUST NOT be taken into account when determining the value returned by `visibilityState`.

### 3.8. One Picture-in-Picture window

Operating systems with a Picture-in-Picture API usually restrict Picture-in-Picture mode to only one window. Whether only one window is allowed in Picture-in-Picture mode will be left to the implementation and the platform. However, because of the one Picture-in-Picture window limitation, the specification assumes that a given `Document` can only have one Picture-in-Picture window.

What happens when there is a Picture-in-Picture request while a window is already in Picture-in-Picture will be left as an implementation detail: the current Picture-in-Picture window could be closed, the Picture-in-Picture request could be rejected or even two Picture-in-Picture windows could be created. Regardless, the User Agent will have to fire the appropriate events in order to notify the website of the Picture-in-Picture status changes.

## 4. API

### 4.1. Extensions to `HTMLVideoElement`

    partial interface HTMLVideoElement {
      [NewObject] Promise<PictureInPictureWindow> requestPictureInPicture();

      attribute EventHandler onenterpictureinpicture;
      attribute EventHandler onleavepictureinpicture;

      [CEReactions] attribute boolean autoPictureInPicture;
      [CEReactions] attribute boolean disablePictureInPicture;
    };

The `requestPictureInPicture()` method, when invoked, MUST return a new promise promise and run the following steps in parallel:

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

2. Let userActivationRequired be `true` if `pictureInPictureElement` is `null`. It is `false` otherwise.

3. Let playingRequired be `false`.

4. Run the request Picture-in-Picture algorithm with video, userActivationRequired, and playingRequired.

5. If the previous step threw an exception, reject promise with that exception and abort these steps.

6. Return promise with the Picture-in-Picture window associated with `pictureInPictureElement`.

### 4.2. Extensions to `Document`

    partial interface Document {
      readonly attribute boolean pictureInPictureEnabled;

      [NewObject] Promise<void> exitPictureInPicture();
    };

The `pictureInPictureEnabled` attribute’s getter must return `true` if Picture-in-Picture support is `true` and the context object is allowed to use the feature indicated by attribute name `picture-in-picture`, and `false` otherwise.

Picture-in-Picture support is `false` if there’s a user preference that disables it or a platform limitation. It is `true` otherwise.

The `exitPictureInPicture()` method, when invoked, MUST return a new promise promise and run the following steps in parallel:

1. Run the exit Picture-in-Picture algorithm.

2. If the previous step threw an exception, reject promise with that exception and abort these steps.

3. Return promise.

### 4.3. Extension to `DocumentOrShadowRoot`

    partial interface mixin DocumentOrShadowRoot {
      readonly attribute Element? pictureInPictureElement;
    };

The `pictureInPictureElement` attribute’s getter must run these steps:

1. If the context object is not connected, return `null` and abort these steps.

2. Let candidate be the result of retargeting Picture-in-Picture element against the context object.

3. If candidate and the context object are in the same tree, return candidate and abort these steps.

4. Return `null`.

### 4.4. Interface `PictureInPictureWindow`

    [Exposed=Window]
    interface PictureInPictureWindow : EventTarget {
      readonly attribute long width;
      readonly attribute long height;

      attribute EventHandler onresize;
    };

A `PictureInPictureWindow` instance represents a Picture-in-Picture window associated with an `HTMLVideoElement`. When instantiated, an instance of `PictureInPictureWindow` has its state set to opened.

When the close window algorithm with an instance of `PictureInPictureWindow` is invoked, its state is set to closed.

The `width` attribute MUST return the width in CSS pixels of the Picture-in-Picture window associated with `pictureInPictureElement` if the state is opened. Otherwise, it MUST return 0.

The `height` attribute MUST return the height in CSS pixels of the Picture-in-Picture window associated with `pictureInPictureElement` if the state is opened. Otherwise, it MUST return 0.

When the size of the Picture-in-Picture window associated with `pictureInPictureElement` changes, the user agent MUST queue a task to fire an event with the name `resize` at `pictureInPictureElement`.

### 4.5. Event types

`enterpictureinpicture`

  Fired on a `HTMLVideoElement` when it enters Picture-in-Picture.

    [Exposed=Window]
    interface EnterPictureInPictureEvent : Event {
        constructor(DOMString type, EnterPictureInPictureEventInit eventInitDict);
        [SameObject] readonly attribute PictureInPictureWindow pictureInPictureWindow;
    };

    dictionary EnterPictureInPictureEventInit : EventInit {
        required PictureInPictureWindow pictureInPictureWindow;
    };

`leavepictureinpicture`

  Fired on a `HTMLVideoElement` when it leaves Picture-in-Picture mode.

`resize`

  Fired on a `PictureInPictureWindow` when it changes size.

### 4.6. Task source

The task source for all the tasks queued in this specification is the media element event task source of the video element in question.

### 4.7. CSS pseudo-class

The `:picture-in-picture` pseudo-class MUST match the Picture-in-Picture element. It is different from the `pictureInPictureElement` as it does NOT apply to the shadow host chain.

## 5. Security considerations

This section is non-normative.

The API applies only to `HTMLVideoElement` in order to start on a minimal viable product that has limited security issues. Later versions of this specification may allow PIP-ing arbitrary HTML content.

### 5.1. Feature Policy

This specification defines a policy-controlled feature that controls whether the request Picture-in-Picture algorithm may return a `SecurityError` and whether `pictureInPictureEnabled` is `true` or `false`.

The feature name for this feature is `"picture-in-picture"`.

The default allowlist for this feature is `*`.

## 6. Acknowledgments

Thanks to Jennifer Apacible, Zouhir Chahoud, Marcos Cáceres, Philip Jägenstedt, Jeremy Jones, Chris Needham, Jer Noble, Justin Uberti, Yoav Weiss, and Eckhart Wörner for their contributions to this document.

## Index

### Terms defined by this specification

- autoPictureInPicture, in §4.1
- autoPictureInPictureElement, in §3.4
- close window algorithm, in §4.4
- constructor(type, eventInitDict), in §4.5
- disablePictureInPicture, in §4.1
- enterpictureinpicture, in §4.5
- EnterPictureInPictureEvent, in §4.5
- EnterPictureInPictureEventInit, in §4.5
- EnterPictureInPictureEvent(type, eventInitDict), in §4.5
- exitPictureInPicture(), in §4.2
- exit Picture-in-Picture algorithm, in §3.2
- height, in §4.4
- leavepictureinpicture, in §4.5
- onenterpictureinpicture, in §4.1
- onleavepictureinpicture, in §4.1
- onresize, in §4.4
- pictureInPictureElement, in §4.3
- pictureInPictureEnabled, in §4.2
- Picture-in-Picture support, in §4.2
- Picture-in-Picture window, in §3.1
- PictureInPictureWindow, in §4.4
- pictureInPictureWindow
  - attribute for EnterPictureInPictureEvent, in §4.5
  - dict-member for EnterPictureInPictureEventInit, in §4.5
- requestPictureInPicture(), in §4.1
- request Picture-in-Picture algorithm, in §3.1
- resize, in §4.5
- width, in §4.4

https://drafts.csswg.org/css-values-4/#px Referenced in:

- 4.4. Interface PictureInPictureWindow (2)

https://dom.spec.whatwg.org/#document Referenced in:

- 3.8. One Picture-in-Picture window
- 4.2. Extensions to Document

https://dom.spec.whatwg.org/#documentorshadowroot Referenced in:

- 4.3. Extension to DocumentOrShadowRoot

https://dom.spec.whatwg.org/#element Referenced in:

- 4.3. Extension to DocumentOrShadowRoot

https://dom.spec.whatwg.org/#event Referenced in:

- 4.5. Event types

https://dom.spec.whatwg.org/#dictdef-eventinit Referenced in:

- 4.5. Event types

https://dom.spec.whatwg.org/#eventtarget Referenced in:

- 4.4. Interface PictureInPictureWindow

https://dom.spec.whatwg.org/#dom-event-bubbles Referenced in:

- 3.1. Request Picture-in-Picture
- 3.2. Exit Picture-in-Picture

https://dom.spec.whatwg.org/#connected Referenced in:

- 4.3. Extension to DocumentOrShadowRoot

https://dom.spec.whatwg.org/#context-object Referenced in:

- 4.2. Extensions to Document
- 4.3. Extension to DocumentOrShadowRoot (2) (3)

https://dom.spec.whatwg.org/#concept-document Referenced in:

- 3.7. Interaction with Page Visibility

https://dom.spec.whatwg.org/#concept-event-fire Referenced in:

- 3.1. Request Picture-in-Picture
- 3.2. Exit Picture-in-Picture
- 4.4. Interface PictureInPictureWindow

https://dom.spec.whatwg.org/#retarget Referenced in:

- 4.3. Extension to DocumentOrShadowRoot

https://dom.spec.whatwg.org/#concept-tree Referenced in:

- 4.3. Extension to DocumentOrShadowRoot

https://wicg.github.io/feature-policy/#default-allowlist Referenced in:

- 5.1. Feature Policy

https://wicg.github.io/feature-policy/#feature-name Referenced in:

- 5.1. Feature Policy

https://wicg.github.io/feature-policy/#policy-controlled-feature Referenced in:

- 3.1. Request Picture-in-Picture
- 5.1. Feature Policy

https://html.spec.whatwg.org/multipage/custom-elements.html#cereactions Referenced in:

- 4.1. Extensions to HTMLVideoElement (2)

https://html.spec.whatwg.org/multipage/webappapis.html#eventhandler Referenced in:

- 4.1. Extensions to HTMLVideoElement (2)
- 4.4. Interface PictureInPictureWindow

https://html.spec.whatwg.org/multipage/media.html#dom-media-have_nothing Referenced in:

- 3.1. Request Picture-in-Picture

https://html.spec.whatwg.org/multipage/media.html#htmlvideoelement Referenced in:

- 1. Introduction
- 4.1. Extensions to HTMLVideoElement
- 4.4. Interface PictureInPictureWindow
- 4.5. Event types (2)
- 5. Security considerations

https://html.spec.whatwg.org/multipage/iframe-embed-object.html#allowed-to-use Referenced in:

- 4.2. Extensions to Document

https://html.spec.whatwg.org/multipage/infrastructure.html#in-parallel Referenced in:

- 4.1. Extensions to HTMLVideoElement
- 4.2. Extensions to Document

https://html.spec.whatwg.org/multipage/media.html#media-element-event-task-source Referenced in:

- 4.6. Task source

https://html.spec.whatwg.org/multipage/media.html#dom-media-paused Referenced in:

- 3.1. Request Picture-in-Picture

https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-task Referenced in:

- 3.1. Request Picture-in-Picture
- 3.2. Exit Picture-in-Picture
- 4.4. Interface PictureInPictureWindow

https://html.spec.whatwg.org/multipage/media.html#dom-media-readystate Referenced in:

- 3.1. Request Picture-in-Picture

https://html.spec.whatwg.org/multipage/infrastructure.html#reflect Referenced in:

- 3.3. Disable Picture-in-Picture
- 3.4. Auto Picture-in-Picture

https://html.spec.whatwg.org/multipage/webappapis.html#task-source Referenced in:

- 4.6. Task source

https://html.spec.whatwg.org/multipage/browsers.html#top-level-browsing-context Referenced in:

- 3.4. Auto Picture-in-Picture (2)
- 3.7. Interaction with Page Visibility

https://html.spec.whatwg.org/multipage/interaction.html#triggered-by-user-activation Referenced in:

- 3.1. Request Picture-in-Picture

https://html.spec.whatwg.org/multipage/browsing-the-web.html#unloading-document-cleanup-steps Referenced in:

- 3.2. Exit Picture-in-Picture

https://www.w3.org/TR/page-visibility/#dom-visibilitystate Referenced in:

- 3.7. Interaction with Page Visibility (2)

https://www.w3.org/2001/tag/doc/promises-guide/#a-new-promise Referenced in:

- 4.1. Extensions to HTMLVideoElement
- 4.2. Extensions to Document

https://w3c.github.io/remote-playback/#dfn-local-playback-device Referenced in:

- 3.5. Interaction with Remote Playback

https://w3c.github.io/remote-playback/#dfn-local-playback-state Referenced in:

- 3.5. Interaction with Remote Playback

https://drafts.csswg.org/selectors-4/#pseudo-class Referenced in:

- 4.7. CSS pseudo-class

https://heycam.github.io/webidl/#idl-DOMString Referenced in:

- 4.5. Event types

https://heycam.github.io/webidl/#Exposed Referenced in:

- 4.4. Interface PictureInPictureWindow
- 4.5. Event types

https://heycam.github.io/webidl/#invalidstateerror Referenced in:

- 3.1. Request Picture-in-Picture (2) (3)
- 3.2. Exit Picture-in-Picture
- 3.3. Disable Picture-in-Picture

https://heycam.github.io/webidl/#NewObject Referenced in:

- 4.1. Extensions to HTMLVideoElement
- 4.2. Extensions to Document

https://heycam.github.io/webidl/#notallowederror Referenced in:

- 3.1. Request Picture-in-Picture

https://heycam.github.io/webidl/#notsupportederror Referenced in:

- 3.1. Request Picture-in-Picture

https://heycam.github.io/webidl/#SameObject Referenced in:

- 4.5. Event types

https://heycam.github.io/webidl/#securityerror Referenced in:

- 3.1. Request Picture-in-Picture
- 5.1. Feature Policy

https://heycam.github.io/webidl/#idl-boolean Referenced in:

- 4.1. Extensions to HTMLVideoElement (2)
- 4.2. Extensions to Document

https://heycam.github.io/webidl/#idl-long Referenced in:

- 4.4. Interface PictureInPictureWindow (2)

### Terms defined by reference

- [css-values-4] defines the following terms:
  - px
- [DOM] defines the following terms:
  - Document
  - DocumentOrShadowRoot
  - Element
  - Event
  - EventInit
  - EventTarget
  - bubbles
  - connected
  - context object
  - document
  - fire an event
  - retargeting
  - tree
- [feature policy] defines the following terms:
  - default allowlist
  - feature name
  - policy-controlled feature
- [HTML] defines the following terms:
  - CEReactions
  - EventHandler
  - HAVE_NOTHING
  - HTMLVideoElement
  - allowed to use
  - in parallel
  - media element event task source
  - paused
  - queue a task
  - readyState
  - reflect
  - task source
  - top-level browsing context
  - triggered by user activation
  - unloading document cleanup steps
- [Page-Visibility] defines the following terms:
  - visibilityState
- [promises-guide] defines the following terms:
  - a new promise
- [Remote-Playback] defines the following terms:
  - local playback device
  - local playback state
- [selectors-4] defines the following terms:
  - pseudo-class
- [WebIDL] defines the following terms:
  - DOMString
  - Exposed
  - InvalidStateError
  - NewObject
  - NotAllowedError
  - NotSupportedError
  - SameObject
  - SecurityError
  - boolean
  - long

## References

### Normative References

[CSS-VALUES-4]
  Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 31 January 2019. WD. URL: https://www.w3.org/TR/css-values-4/
[DOM]
  Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[HTML]
  Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[Page-Visibility]
  Jatinder Mann; Arvind Jain. Page Visibility (Second Edition). 29 October 2013. REC. URL: https://www.w3.org/TR/page-visibility/
[PROMISES-GUIDE]
  Domenic Denicola. Writing Promise-Using Specifications. 9 November 2018. TAG Finding. URL: https://www.w3.org/2001/tag/doc/promises-guide
[Remote-Playback]
  Mounir Lamouri; Anton Vayvod. Remote Playback API. 19 October 2017. CR. URL: https://www.w3.org/TR/remote-playback/
[SELECTORS-4]
  Elika Etemad; Tab Atkins Jr.. Selectors Level 4. 21 November 2018. WD. URL: https://www.w3.org/TR/selectors-4/
[WebIDL]
  Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

### Informative References

[Fullscreen]
  Philip Jägenstedt. Fullscreen API Standard. Living Standard. URL: https://fullscreen.spec.whatwg.org/
[MediaSession]
  Media Session. Living Standard. URL: https://wicg.github.io/mediasession/

## IDL Index

    partial interface HTMLVideoElement {
      [NewObject] Promise<PictureInPictureWindow> requestPictureInPicture();

      attribute EventHandler onenterpictureinpicture;
      attribute EventHandler onleavepictureinpicture;

      [CEReactions] attribute boolean autoPictureInPicture;
      [CEReactions] attribute boolean disablePictureInPicture;
    };

    partial interface Document {
      readonly attribute boolean pictureInPictureEnabled;

      [NewObject] Promise<void> exitPictureInPicture();
    };

    partial interface mixin DocumentOrShadowRoot {
      readonly attribute Element? pictureInPictureElement;
    };

    [Exposed=Window]
    interface PictureInPictureWindow : EventTarget {
      readonly attribute long width;
      readonly attribute long height;

      attribute EventHandler onresize;
    };

    [Exposed=Window]
    interface EnterPictureInPictureEvent : Event {
        constructor(DOMString type, EnterPictureInPictureEventInit eventInitDict);
        [SameObject] readonly attribute PictureInPictureWindow pictureInPictureWindow;
    };

    dictionary EnterPictureInPictureEventInit : EventInit {
        required PictureInPictureWindow pictureInPictureWindow;
    };

#request-picture-in-picture-algorithm Referenced in:

- 3.4. Auto Picture-in-Picture (2)
- 4.1. Extensions to HTMLVideoElement
- 5.1. Feature Policy

#picture-in-picture-window Referenced in:

- 3.1. Request Picture-in-Picture
- 3.2. Exit Picture-in-Picture
- 4.1. Extensions to HTMLVideoElement
- 4.4. Interface PictureInPictureWindow (2) (3) (4)

#exit-picture-in-picture-algorithm Referenced in:

- 3.2. Exit Picture-in-Picture (2)
- 3.3. Disable Picture-in-Picture
- 3.4. Auto Picture-in-Picture
- 4.2. Extensions to Document

#autopictureinpictureelement Referenced in:

- 3.4. Auto Picture-in-Picture (2) (3) (4) (5)

#dom-htmlvideoelement-requestpictureinpicture Referenced in:

- 3.3. Disable Picture-in-Picture
- 4.1. Extensions to HTMLVideoElement

#dom-htmlvideoelement-autopictureinpicture Referenced in:

- 3.4. Auto Picture-in-Picture (2) (3) (4)

#dom-htmlvideoelement-disablepictureinpicture Referenced in:

- 3.1. Request Picture-in-Picture
- 3.3. Disable Picture-in-Picture (2) (3) (4)
- 3.4. Auto Picture-in-Picture

#dom-document-pictureinpictureenabled Referenced in:

- 4.2. Extensions to Document
- 5.1. Feature Policy

#dom-document-exitpictureinpicture Referenced in:

- 4.2. Extensions to Document

#picture-in-picture-support Referenced in:

- 3.1. Request Picture-in-Picture
- 4.2. Extensions to Document

#dom-documentorshadowroot-pictureinpictureelement Referenced in:

- 3.1. Request Picture-in-Picture (2) (3)
- 3.2. Exit Picture-in-Picture (2) (3)
- 3.3. Disable Picture-in-Picture
- 3.4. Auto Picture-in-Picture (2)
- 3.7. Interaction with Page Visibility
- 4.1. Extensions to HTMLVideoElement (2)
- 4.3. Extension to DocumentOrShadowRoot
- 4.4. Interface PictureInPictureWindow (2) (3) (4)
- 4.7. CSS pseudo-class

#pictureinpicturewindow Referenced in:

- 3.1. Request Picture-in-Picture
- 4.1. Extensions to HTMLVideoElement
- 4.4. Interface PictureInPictureWindow (2) (3)
- 4.5. Event types (2) (3)

#dom-pictureinpicturewindow-width Referenced in:

- 4.4. Interface PictureInPictureWindow

#dom-pictureinpicturewindow-height Referenced in:

- 4.4. Interface PictureInPictureWindow

#close-window-algorithm Referenced in:

- 3.2. Exit Picture-in-Picture

#eventdef-htmlvideoelement-enterpictureinpicture Referenced in:

- 3.1. Request Picture-in-Picture

#enterpictureinpictureevent Referenced in:

- 3.1. Request Picture-in-Picture

#dom-enterpictureinpictureevent-pictureinpicturewindow Referenced in:

- 3.1. Request Picture-in-Picture

#dictdef-enterpictureinpictureeventinit Referenced in:

- 4.5. Event types

#eventdef-htmlvideoelement-leavepictureinpicture Referenced in:

- 3.2. Exit Picture-in-Picture

#eventdef-pictureinpicturewindow-resize Referenced in:

- 4.4. Interface PictureInPictureWindow