This specification defines conformance criteria that apply to a single - product: the user agent that implements the interfaces that it + 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 @@ -82,41 +81,29 @@
A more complicated example shows the use of constraints to limit the - choice to windows and their visible display surface.
- -
-navigator.mediaDevices.getDisplayMedia({
- 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);
- });
-
-
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:
+ screen-based surfaces. Collectively, these are referred to + as display surfaces, of which this + document defines the following types:This document draws a distinction between two variants of each type of display surface:
Output capture is enabled through the addition of a new getDisplayMedia method on the
- NavigatorMediaDevices interface, that is similar
- to getUserMedia [[!GETUSERMEDIA]]. New constraints allow an
- application to control what type of information is requested.
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 ). Two new
+ constraints allow an application to observe what type of information was
+ acquired.
NavigatorUserMedia AdditionsNavigatorUserMedia AdditionsThis method operates identically to getUserMedia,
- expect that it acquires media from output devices.
Two constraints are defined that allow an application to limit the - display surfaces that are selected. This only allows an application to - control the type of surface that is selected, not to identify a specific - surface.
+The getDisplayMedia function permits the use of
+ constraints in the same way that constraints are defined
+ for getUserMedia. However, these constraints MUST NOT
+ constrain the selection of choices that are presented to users in the same
+ way.
The displaySurface
- constraint allows an application to express a preference or requirement
- for the type of display surface that is acquired.
The logicalSurface
- constraint allows an application to express a preference or requirement to
- capture the logical display surface, rather than the visible
- display surface.
What type of display surface to capture. This assumes
- values from the OutputCaptureSurfaceType
- enumeration.
A value of true requests or requires capture of a
- logical display surface; a value of false requests
- or requires capture of a visible display surface.
Once a display surface has been selected, constraints apply to + the MediaStreamTrack instances that are returned. This allows for + changes such as adjustments to frame rate or resolution, or other + constraints.
OutputCaptureSurfaceTypeTwo constraints are defined that allow an application to observe
+ properties of the selected display surface. Since the source of
+ media cannot be changed after a MediaStreamTrack has been
+ returned, these constraints cannot be changed by an application.
The displaySurface
+ constraint allows an application to observe the type of display
+ surface that is being captured.
The logicalSurface
+ constraint allows an application to express a preference or requirement
+ to capture the logical display surface, rather than
+ the visible display surface.
The type of display surface that is being captured. This
+ assumes values from
+ the DisplayCaptureSurfaceType enumeration.
A value of true indicates capture of a
+ logical display surface; a value of false
+ indicates a capture capture of a visible display
+ surface.
The OutputCaptureSurfaceType enumeration
- describes the different types of display surface.
DisplayCaptureSurfaceTypeThe DisplayCaptureSurfaceType enumeration
+ describes the different types of display surface.
Github#2: - Determine whether we want to support application capture.
+MediaStreamTrack API as having a deviceId
parameter that is randomized each time a MediaStreamTrack is
connected. The only other constraint on this value is that it cannot
- conflict with any existing values for deviceId.
+ duplicate any existing values for deviceId.
Capture of logical display surfaces causes there to be a +
Capture of logical display surfaces causes there to be a potential for content to be shared that a user is not made aware of. A logical display surface might render information that a user did - not intend to expose. This can be quickly rectified if this information - is visible. Such means are of course ineffectual against a machine, but a - human recipient is less able to process content that appears only - briefly.
+ not intend to expose. This can be more easily recognized if this + information is visible. Such means are likely ineffectual against a + machine, but a human recipient is less able to process content that + appears only briefly.Information that is not currently rendered to the screen SHOULD be obscured in captures unless the application has been specifically @@ -344,12 +348,16 @@
Active user consent is sufficient where there is little or no risk of an application gaining information that the user did not intend to share. These cases can be identified by those where the application that requests capture has no control over what is rendered to the - captured display surface.
+ captured display surface. + +To prevent applications from limiting the available choices presented
+ to a user with the goal of promoting a particular choice,
+ the getDisplayMedia API does not permit the use of
+ constraints to narrow the set of options presented.
It is strongly advised that elevated permissions be required to access any display surface that might be used to - circumvent origin-based protections for content. The key goal of this + circumvent cross-origin protections for content. The key goal of this consent process is not just to demonstrate that a user intends to share content, but to also to determine that the user exhibits an elevated level of trust in the application that is being granted access.
@@ -376,13 +384,13 @@An elevated permissions experience allows the user
+ An elevated permissions experience could allow the user
agent to communicate the risks associated with enabling this
feature, or at least to convey the need for augmented trust in the
application. Note that elevated permissions are not a substitute for
- active user consent. It is advised that user agents still
+ active user consent. It is advised that user agents still
present users with the ability to select what is shared, even for
applications that have elevated permissions.
Elevated permissions are recommended as a prerequisite for access to capture of monitor or browser display - surfaces. Note that capture of a complete monitor is included + surfaces. Note that capture of a complete monitor is included because this could include a window from the user agent.
Similarly, elevated permissions are a recommended prerequisite - for access to logical display surfaces, where that would not + for access to logical display surfaces, where that would not ordinarily be provided.
A user agent SHOULD persist any elevated permissions @@ -409,12 +417,12 @@
Implementations can handle feedback and control mechanism in a similar - way to how they handle sharing of a camera or microphone, as recommended - in [[GETUSERMEDIA]].
+Implementations are advised to provide user feedback and control + mechanisms similar to those offered users when sharing a camera or + microphone, as recommended in [[GETUSERMEDIA]].
It is important that a user be aware that content is being shared when - content is actively being captured. User agents are advised to + content is actively being captured. User agents are advised to display a prominent indicator while content is being captured. In addition to an indicator, a user agent is advised to provide a means to learn precisely what is being shared; while this capability is