This document proposes a new dictionary member for getDisplayMedia. This new member allows an application to specify a preference for capturing the tab from which getDisplayMedia was called.
Currently, getDisplayMedia does not allow the application to influence the user's selection of a capture source. This design decision is perennially debated.
Consider the case of a productivity suite that wishes to stream itself to a virtual conference. When such an application calls getDisplayMedia, any selection by the user of a source other than the current tab is likely user-error, and the application is likely to discard the resulting {{MediaStream}} rather than use it.
In such a case, there is only one capture-source that makes sense - the current tab. An API is required that only offers the current tab. Such an API is currently in the works - see [[mediacapture-viewport]], which introduces getViewportMedia. The benefit of getViewportMedia is that it will offer the user a confirmation-only dialog. The drawbacks are the long time until this API is be standardized, implemented, and until the security mechanisms it requires become widely adopted.
We introduce a simpler mechanism that can act as a stopgap measure until getViewportMedia is standardized, implemented and adopted by the Web. This mechanism is a dictionary member that indicates to the user agent that the application prefers the current tab. The user agent can then take that preference into consideration when representing the request to the user.
In either case, this API is meant to ultimately be replaced by [[mediacapture-viewport]].
partial dictionary MediaStreamConstraints {
boolean preferCurrentTab = false;
};
When {{MediaDevices/getDisplayMedia()}} is called with |constraints| (a
dictionary), the user agent MUST run the following steps:
|constraints|.preferCurrentTab is false, abort these
steps and continue instead with the
getDisplayMedia algorithm.
|constraints|.{{DisplayMediaStreamOptions/selfBrowserSurface}} is
{{SelfCapturePreferenceEnum/"exclude"}}, return a {{Promise}} [=reject|rejected=] with
a newly [=exception/created=] {{TypeError}}.
The rest of the getDisplayMedia algorithm should now be executed with the following changes:
If the algorithm's execution reaches the step where the user agent asks the user to choose a display surface to capture, then the user agent SHOULD take the applications's preference for the current tab into account, making it the most prominent of any option presented. User agents MAY rely on this preference to limit the set of options presented to the user.
This carve-out is an intentional violation of [[SCREEN-CAPTURE]]'s requirement that "the getDisplayMedia API does not permit the use of constraints to narrow the set of options presented." This carve-out does not obviate user agents' duty to ensure active user consent, for example by mitigating against inadvertent sharing (clickjacking, etc.).
Let |p| be {{Promise}} returned by the
getDisplayMedia algorithm. If |p| is resolved, then let |stream| be the {{MediaStream}} it resolves to,
and let |videoTrack| be the single {{MediaStreamTrack}} in |stream|'s [=track
set=] whose {{MediaStreamTrack/kind}} is equal to
"video". Set
|p|.{{MediaStreamTrack/[[Restrictable]]}} to true.