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, and its tentative name is getViewportMedia. The main 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 are widely adopted.

We propose 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 then still shows the user a dialog that complies with all of the requirements placed on getDisplayMedia, by offering all possible sources to the user, but the current tab is presented as the most prominent option.


        partial dictionary MediaStreamConstraints {
          boolean preferCurrentTab = false;

When {{MediaDevices/getDisplayMedia()}} is called with |constraints| (a dictionary), the user agent MUST run the following steps:

  1. If |constraints|.preferCurrentTab is false, abort these steps and continue instead with the getDisplayMedia algorithm.
  2. If |constraints|.{{DisplayMediaStreamOptions/selfBrowserSurface}} is {{SelfCapturePreferenceEnum/"exclude"}}, return a promise [=reject|rejected=] with a newly [=exception/created=] {{TypeError}}.
  3. The rest of the getDisplayMedia algorithm should now be executed, with one change - 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 present the current tab as the most prominent option.