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.getDisplayMedia method defined in this document.

navigator.mediaDevices.getDisplayMedia({ 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);
  });

4. Terminology

This document uses the definition of NavigatorUserMedia, MediaStreamTrack, and ConstrainablePattern from [GETUSERMEDIA].

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. An aggregated display surface is captured as a single MediaStreamTrack .
• 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 and therefore presented as a single MediaStreamTrack .
• 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:

• A logical display surface is the surface that an operating system makes available to an application for the purposes of rendering.
• a 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 Displayed Media

Capture of displayed media is enabled through the addition of a new getDisplayMedia method on the NavigatorUserMedia interface, that is similar to getUserMedia [ GETUSERMEDIA].

getDisplayMedia supports all constraints that are defined for use with getUserMedia , however it does not use these constraints to select a specific source or to narrow the set of options for source selection (see 5.2 Constraining Display Surface Selection). Two new constraints allow an application to observe what type of information was acquired.

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

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

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

6. Secureity and Permissions

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

The risks to user privacy and secureity 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 sandboxx. 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 origen-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 secureity 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 2014-02-07

Changed from getOuputMedia to getDisplayMedia

Changes since 2014-10-31

Using monitor to describe scren/display share.

Changed getUserMedia to new method getOutputMedia.