-
Notifications
You must be signed in to change notification settings - Fork 1
/
index.html
134 lines (134 loc) · 6.31 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
<!DOCTYPE html>
<html lang="en-us">
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<title>preferCurrentTab</title>
<script class="remove" src="prefer-current-tab.js" type="text/javascript"></script>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
</head>
<body>
<section id="abstract">
<h2>Abstract</h2>
<p>
This document proposes a new dictionary member for
<a data-cite="SCREEN-CAPTURE#dom-mediadevices-getdisplaymedia">getDisplayMedia</a>. This new
member allows an application to specify a preference for capturing the tab from which
<a data-cite="SCREEN-CAPTURE#dom-mediadevices-getdisplaymedia">getDisplayMedia</a> was
called.
</p>
</section>
<section id="conformance"></section>
<section>
<h2>Background</h2>
<p>
Currently,
<a data-cite="SCREEN-CAPTURE#dom-mediadevices-getdisplaymedia">getDisplayMedia</a> does not
allow the application to influence the user's selection of a capture source. This design
decision is perennially debated.
</p>
<p>
Consider the case of a productivity suite that wishes to stream itself to a virtual
conference. When such an application calls
<a data-cite="SCREEN-CAPTURE#dom-mediadevices-getdisplaymedia">getDisplayMedia</a>, 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.
</p>
<p>
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
<a data-cite="mediacapture-viewport/#dom-mediadevices-getviewportmedia">getViewportMedia</a
>. The benefit of
<a data-cite="mediacapture-viewport/#dom-mediadevices-getviewportmedia">getViewportMedia</a>
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.
</p>
<p>
We introduce a simpler mechanism that can act as a stopgap measure until
<a data-cite="mediacapture-viewport/#dom-mediadevices-getviewportmedia">getViewportMedia</a>
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.
</p>
<p>
In either case, this API is meant to ultimately be replaced by [[mediacapture-viewport]].
</p>
</section>
<section id="prefer-current-tab">
<h2>preferCurrentTab</h2>
<pre class="idl">
partial dictionary MediaStreamConstraints {
boolean preferCurrentTab = false;
};
</pre>
<dl data-link-for="MediaStreamConstraints" data-dfn-for="MediaStreamConstraints">
<dt>
<dfn>preferCurrentTab</dfn>
</dt>
<dd>
<p>
When {{MediaDevices/getDisplayMedia()}} is called with <code>|constraints|</code> (a
dictionary), the user agent MUST run the following steps:
</p>
<ol>
<li>
If <code>|constraints|.preferCurrentTab</code> is <code>false</code>, abort these
steps and continue instead with the
<a href="https://www.w3.org/TR/screen-capture/#dom-mediadevices-getdisplaymedia"
>getDisplayMedia algorithm</a
>.
</li>
<li>
If <code>|constraints|.</code>{{DisplayMediaStreamOptions/selfBrowserSurface}} is
{{SelfCapturePreferenceEnum/"exclude"}}, return a {{Promise}} [=reject|rejected=] with
a newly [=exception/created=] {{TypeError}}.
</li>
<li>
<p>
The rest of the
<a href="https://www.w3.org/TR/screen-capture/#dom-mediadevices-getdisplaymedia"
>getDisplayMedia algorithm</a
>
should now be executed with the following changes:
</p>
</li>
<ol>
<li>
<p>
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.
</p>
<div class="note">
<p>
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.).
</p>
</div>
</li>
<li>
<p>
Let |p| be {{Promise}} returned by the
<a href="https://www.w3.org/TR/screen-capture/#dom-mediadevices-getdisplaymedia"
>getDisplayMedia algorithm</a
>. 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
<a href="https://www.w3.org/TR/mediacapture-streams/#dfn-video">"video"</a>. Set
|p|.{{MediaStreamTrack/[[Restrictable]]}} to <code>true</code>.
</p>
</li>
</ol>
</ol>
</dd>
</dl>
</section>
</body>
</html>