Table of Contents

• 1. Introduction
• 2. Conformance
• 3. Example
• 4. Terminology
• 5. Capturing Output Media
  • 5.1 NavigatorUserMedia Additions
    • 5.1.1 Methods
  • 5.2 Constraining Display Surface Selection
    • 5.2.1 Dictionary MediaTrackConstraintSet Members
    • 5.2.2 OutputCaptureSurfaceType
  • 5.3 Device Identifiers
• 6. Security and Permissions
  • 6.1 Capturing Logical or Visible Display Surfaces
  • 6.2 Authorizing Display Capture
    • 6.2.1 Active User Consent
    • 6.2.2 Elevated Permissions
    • 6.2.3 Capabilities Depending on Elevated Permissions
  • 6.3 Feedback and Interface During Capture
• 7. Change Log
• A. Acknowledgements
• B. References
  • B.1 Normative references
  • B.2 Informative references

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST NOT, and SHOULD are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript [ECMA-262] to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

3. Example

The following example demonstrates a request for display capture using the navigator.mediaDevices.getOutputMedia method defined in this document.

navigator.mediaDevices.getOutputMedia({ video: true })
  .then(stream => {
    // we have a stream, attach it to a feedback video element
    videoElement.srcObject = stream;
  }, error => {
    console.log("Unable to acquire screen capture", error);
  });

A more complicated example shows the use of constraints to limit the choice to windows and their visible display surface.

navigator.mediaDevices.getOutputMedia({
  video: {
    displaySurface: { exact: "window" },
    logicalSurface: { exact: false }
  }
}).then(stream => {
    // we have a stream, attach it to a feedback video element
    videoElement.srcObject = stream;
  }, error => {
    console.log("Unable to acquire screen capture", error);
  });

4. Terminology

Screen capture encompasses the capture of several different types of screen-based surfaces. Collectively, these are referred to as display surfaces, of which this document defines the following types:

• A monitor display surface represents a physical display. Some systems have multiple monitors, which can be identified separately. Multiple monitors might also be aggregated into as a single logical monitor.
• A window display surface is a single contiguous surface that is used by a single application. A single application might have several windows available to it, and those can be aggregated into a single application surface, representing all the windows available to that application.
• A browser display surface is the rendered form of a single document. This is not strictly limited to HTML [HTML5] documents, though the discussion in this document will address some specific concerns with the capture of HTML.

This document draws a distinction between two variants of each type of display surface:

• The logical display surface is the surface that an operating system makes available to an application for the purposes of rendering.
• The visible display surface is the portion of a logical display surface that is rendered to a monitor.

Some operating systems permit windows from different applications to occlude other windows, in whole or part, so the visible display surface is a strict subset of the logical display surface.

5. Capturing Output Media

Output capture is enabled through the addition of a new getOutputMedia method on the NavigatorMediaDevices interface, that is similar to getUserMedia [GETUSERMEDIA]. New constraints allow an application to control what type of information is requested.

partial interface NavigatorUserMedia {
    Promise<MediaStream> getOutputMedia (MediaStreamConstraints constraints);
};

partial dictionary MediaTrackConstraintSet {
    ConstrainDOMString displaySurface;
    ConstrainBoolean   logicalSurface;
};

enum OutputCaptureSurfaceType {
    "monitor",
    "window",
    "application",
    "browser"
};

6. Security and Permissions

This section is informative; however, it notes some serious risks to platform security if the advice it contains are not adhered to.

The risks to user privacy and security posed by capture of displayed content are twofold. The immediate and obvious risk is that users inadvertently share content that they did not wish to share, or might not have realized would be shared.

Display capture presents a less obvious risk to the cross site request forgery protections offered by the browser sandbox. Display and capture of information that is also under the control of an application, even indirectly, can allow that application to access information that would otherwise by inaccessible to it directly. For example, the canvas API does not permit sampling of a canvas, or conversion to an accessible form if it is not origin-clean [2DCONTEXT].

This issue is discussed in further detail in [RTCWEB-SECURITY-ARCH] and [RTCWEB-SECURITY].

Display capture that includes browser windows, particularly those that are under any form of control by the application, risks violation of these basic security protections. Though this risk is not entirely contained to browser windows, since control channels between browser applications and other applications, depending on the operating system. The key consideration is whether the captured display surface could be somehow induced to present information that would otherwise be secret from the application that is receiving the resulting media.

7. Change Log

This section will be removed before publication.

Changes since Oct 31st, 2014

Using monitor to describe scren/display share.

Changed getUserMedia to new method getOutputMedia.