Viewport Capture

WebIDLpartial interface MediaDevices {
  Promise<MediaStream> getViewportMedia(
      optional DisplayMediaStreamOptions options = {});
};

getViewportMedia

Prompts the user for permission to live-capture the viewport (current tab).

The user agent MUST apply any provided options to the produced media after permission has been granted.

In the case of audio, the user agent MAY present the end-user with an option to include audio from the current viewport in the capture, if available. Like getDisplayMedia() with regards to audio+video, the user agent is allowed to not return audio even if the audio constraint is present. If the user agent knows no audio will be shared for the lifetime of the stream it MUST NOT include an audio track in the resulting stream. The user agent MAY accept a request for audio and video by only returning a video track in the resulting stream, or it MAY accept the request by returning both an audio track and a video track in the resulting stream. The user agent MUST reject audio-only requests.

Like getDisplayMedia(), the "granted" permission cannot be persisted.

When the getViewportMedia() method is called, the user agent MUST run the following steps:

1. If the current settings object's cross-origin isolated capability is false, return a promise rejected with a DOMException object whose name attribute has the value SecurityError.

2. If the relevant global object's associated Document's top-level browsing context's required document policy does not contain Require-Document-Policy: viewport-capture and Document-Policy: viewport-capture (TODO: use correct algorithm), return a promise rejected with a DOMException object whose name attribute has the value SecurityError.

3. If the relevant global object of this does not have transient activation, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.

4. Let options be the method's first argument.

5. If options.video is false, return a promise rejected with a newly created TypeError.

6. For each existing member in options whose value, CS, is a dictionary, run the following steps:

   1. If CS contains a member named advanced, return a promise rejected with a newly created TypeError.

   2. If CS contains a member whose name specifies a constrainable property applicable to display surfaces, and whose value in turn is a dictionary containing a member named either min or exact, return a promise rejected with a newly created TypeError.

   3. If CS contains a member whose name specifies a constrainable property applicable to display surfaces, and whose value in turn is a dictionary containing a member named max, and that member's value in turn is less than the constrainable property's floor value, then let failedConstraint be the name of the member, let message be either undefined or an informative human-readable message, and return a promise rejected with a new OverconstrainedError created by calling OverconstrainedError(failedConstraint, message).

7. Let requestedMediaTypes be the set of media types in options with either a dictionary value or a value of true.

8. If the relevant global object's associated Document is NOT fully active or does NOT have focus, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.

9. Let p be a new promise.

10. Run the following steps in parallel:

    1. For each media type T in requestedMediaTypes,

       1. If no sources of type T are available, reject p with a new DOMException object whose name attribute has the value NotFoundError.

       2. Read the current permission state for obtaining sources of type T in the current browsing context. If the permission state is "denied", jump to the step labeled PermissionFailure below.

    2. Optionally, e.g., based on a previously-established user preference, for security reasons, or due to platform limitations, jump to the step labeled Permission Failure below.

    3. Request permission to use viewport capture, for a PermissionDescriptor with its name set to "viewport-capture", resulting in a set of provided media.

       The provided media MUST include precisely one video track, which MUST be a live-capture of the browser display surface of the relevant global object's associated Document's top-level browsing context's viewport.

       The provided media MUST include at most one audio track, which, if provided, MUST be the combined audio produced by the sum of documents that consist of the relevant global object's associated Document's top-level browsing context's active document, and all active documents in nested browsing contexts of the relevant global object's associated Document's top-level browsing context. This audio track MUST NOT be included if audio was not specified in requestedMediaTypes, or if it was specified as false.

       The source of a MediaStreamTrack MUST NOT change.

       If the result of the request is "granted", then for each device that is sourcing the provided media, using a stable and private id for the device, deviceId, set [[devicesLiveMap]][deviceId] to true, if it isn’t already true, and set the [[devicesAccessibleMap]][deviceId] to true, if it isn’t already true.

       The user agent MUST NOT store a "granted" permission entry.

       If the result is "denied", jump to the step labeled Permission Failure below. If the user never responds, this algorithm stalls on this step.

       If the user grants permission but a hardware error such as an OS/program/webpage lock prevents access, reject p with a new DOMException object whose name attribute has the value NotReadableError and abort these steps.

       If the result is "granted" but device access fails for any reason other than those listed above, reject p with a new DOMException object whose name attribute has the value AbortError and abort these steps.

    4. Let stream be the MediaStream object for which the user granted permission.

    5. Run the ApplyConstraints algorithm on all tracks in stream with the appropriate constraints. Should this fail, let failedConstraint be the result of the algorithm that failed, and let message be either undefined or an informative human-readable message, and then reject p with a new OverconstrainedError created by calling OverconstrainedError(failedConstraint, message).

    6. Let videoTrack be the video track in stream.
    7. Set videoTrack.[[Restrictable]] to true.

    8. Resolve p with stream and abort these steps.

    9. Permission Failure: Reject p with a new DOMException object whose name attribute has the value NotAllowedError.

11. Return p.

The user agent MUST NOT capture content that's behind a partially transparent captured display surface.

The user agent MUST NOT share the audio other than audio emitted from the captured tab, and MUST NOT share audio of the entire system.

The constraints relevant to getViewportMedia are only those relevant to getDisplayMedia(), as defined in 5.4 Constrainable Properties for Captured Display Surfaces.

Viewport Capture is a powerful feature which is identified by the name "viewport-capture", requiring express permission to be used.

As required for integration with the Permissions specification, this specification defines the following:

permission state constraints

Valid values for this descriptor's permission state are "prompt" and "denied". The user agent MUST NOT ever set this descriptor's permission state to "granted".

This specification defines a policy-controlled feature identified by the string "viewport-capture". Its default allowlist is "self".