├── .gitignore
├── .pr-preview.json
├── images
    └── fingerprint.png
├── w3c.json
├── LICENSE.md
├── CODE_OF_CONDUCT.md
├── .github
    └── workflows
    │   └── auto-publish.yml
├── CONTRIBUTING.md
├── README.md
├── screenshare.css
├── screenshare.js
├── explainer.md
├── questionnaire.md
└── index.html


/.gitignore:
--------------------------------------------------------------------------------
1 | *~
2 | .DS_Store
3 | build
4 | support
5 | webrtc-respec-ci
6 | 


--------------------------------------------------------------------------------
/.pr-preview.json:
--------------------------------------------------------------------------------
1 | {
2 |   "src_file": "index.html",
3 |   "type": "respec"
4 | }
5 | 


--------------------------------------------------------------------------------
/images/fingerprint.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/w3c/mediacapture-screen-share/HEAD/images/fingerprint.png


--------------------------------------------------------------------------------
/w3c.json:
--------------------------------------------------------------------------------
1 |  {
2 |     "group":      47318
3 | ,   "contacts":   ["dontcallmedom", "caribouW3"]
4 | ,   "shortName":  "screen-capture"
5 | ,   "repo-type":  "rec-track"
6 | }
7 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | All documents in this Repository are licensed by contributors
2 | under the 
3 | [W3C Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software).
4 | 
5 | 


--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | # Code of Conduct
2 | 
3 | All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/).
4 | 


--------------------------------------------------------------------------------
/.github/workflows/auto-publish.yml:
--------------------------------------------------------------------------------
 1 | name: Validate and Auto Publish
 2 | 
 3 | on:
 4 |   push:
 5 |     paths: index.html
 6 |     branches:
 7 |       - gh-pages
 8 |   pull_request: {}
 9 | 
10 | jobs:
11 |   validate-and-publish:
12 |     name: Validate and Publish
13 |     runs-on: ubuntu-latest # only linux supported at present
14 |     steps:
15 |       - uses: actions/checkout@v4
16 |       - uses: w3c/spec-prod@v2 # use the action
17 |         with:
18 |           W3C_ECHIDNA_TOKEN: ${{ secrets.ECHIDNA_TOKEN }}
19 |           W3C_WG_DECISION_URL: "https://lists.w3.org/Archives/Public/public-webrtc/2016Mar/0031.html"
20 |           W3C_NOTIFICATIONS_CC: "dom@w3.org"
21 |           VALIDATE_LINKS: false
22 |           W3C_BUILD_OVERRIDE: |
23 |             specStatus: WD
24 |             shortName: screen-capture          
25 | 


--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
 1 | Contributions to this repository are intended to become part of Recommendation-track documents governed by the
 2 | [W3C Patent Policy](https://www.w3.org/Consortium/Patent-Policy/) and
 3 | [Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software). To make substantive contributions to specifications, you must either participate
 4 | in the relevant W3C Working Group or make a non-member patent licensing commitment.
 5 | 
 6 | If you are not the sole contributor to a contribution (pull request), please identify all
 7 | contributors in the pull request comment.
 8 | 
 9 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows:
10 | 
11 | ```
12 | +@github_username
13 | ```
14 | 
15 | If you added a contributor by mistake, you can remove them in a comment with:
16 | 
17 | ```
18 | -@github_username
19 | ```
20 | 
21 | If you are making a pull request on behalf of someone else but you had no part in designing the
22 | feature, you can remove yourself with the above syntax.
23 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Screen Capture 
 2 | 
 3 | [![WPT Chrome](https://wpt-badge.glitch.me/?product=chrome&prefix=/screen-capture/)](https://wpt.fyi/results/screen-capture)
 4 | [![WPT Firefox](https://wpt-badge.glitch.me/?product=firefox&prefix=/screen-capture/)](https://wpt.fyi/results/screen-capture)
 5 | [![WPT Safari](https://wpt-badge.glitch.me/?product=safari&prefix=/screen-capture/)](https://wpt.fyi/results/screen-capture)
 6 | 
 7 | This work is currently licensed under a Creative Commons Attribution-NoDerivatives 4.0
 8 | International (CC BY-ND 4.0) License. See
 9 | http://creativecommons.org/licenses/by-nd/4.0/legalcode
10 | 
11 | Copyright Cisco and Mozilla
12 | 
13 | ### Published Versions
14 | 
15 | While we have taken measures to reduce the frequency of build breakages, the tip-of-tree
16 | of this document may contain work in progress changes and other inconsistencies.
17 | If you want to review something more coherent, review the latest editors' draft;
18 | these are published at intervals on the order of weeks.
19 | 
20 | * [Tip of tree as HTML](https://w3c.github.io/mediacapture-screen-share/)
21 | * [Latest published editor's draft at github](https://w3c.github.io/mediacapture-screen-share/)
22 | * [Latest W3C published version](https://www.w3.org/TR/screen-capture/) (automatically updated; should be identical to the latest editors' draft)
23 | 
24 | To Reflow the Spec
25 | ------------------
26 | 
27 | To format the draft use something like 
28 | 
29 | tidy --quiet y -utf8 --vertical-space y --tidy-mark n -indent -wrap 80
30 | 


--------------------------------------------------------------------------------
/screenshare.css:
--------------------------------------------------------------------------------
 1 | 
 2 | @media screen {
 3 |   html { background: #eeeeee; }
 4 |   body { margin-bottom: 30%; border-bottom: thin solid #3c790a; max-width: 720px; }
 5 | }
 6 | 
 7 | pre { margin-left: 2em; white-space: pre-wrap; }
 8 | dt, dfn { font-weight: bold; font-style: normal; }
 9 | i, em, dt dfn { font-style: italic; }
10 | pre, code { font-size: inherit; font-family: monospace, Droid Sans Fallback, sans-serif; font-variant: normal; }
11 | pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
12 | pre em { font-weight: bolder; font-style: normal; }
13 | @media screen { code { color: orangered; } }
14 | var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
15 | table { border-collapse: collapse; border-style: hidden hidden none hidden; }
16 | table thead, table tbody { border-bottom: solid; }
17 | table tbody th { text-align: left; }
18 | table tbody th:first-child { border-left: solid; }
19 | table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
20 | 
21 | ins { background: green; color: white; /* color: green; border: solid thin lime; padding: 0.3em; line-height: 1.6em; */ text-decoration: none; }
22 | del { background: maroon; color: white; /* color: maroon; border: solid thin red; padding: 0.3em; line-height: 1.6em; */ text-decoration: line-through; }
23 | body ins, body del { display: block; }
24 | body * ins, body * del { display: inline; }
25 | 
26 | 
27 | p  > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
28 | li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]) { border-bottom: solid #99CC99; }
29 | 
30 | .note { color: green; background: transparent; font-family: sans-serif, Droid Sans Fallback; }
31 | .warning { color: red; background: transparent; }
32 | .note, .warning { font-weight: bolder; font-style: italic; }
33 | .note em, .warning em, .note i, .warning i { font-style: normal; }
34 | p.note, div.note { padding: 0.5em 2em; }
35 | span.note { padding: 0 2em; }
36 | .note p:first-child, .warning p:first-child { margin-top: 0; }
37 | .note p:last-child, .warning p:last-child { margin-bottom: 0; }
38 | .warning:before { font-style: normal; }
39 | p.note:before { content: 'Note: '; }
40 | p.warning:before { content: '\26A0 Warning! '; }
41 | 
42 | .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
43 | .bookkeeping { font-size: 0.8em; margin: 2em 0; }
44 | .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
45 | .bookkeeping dt { margin: 0.5em 2em 0; }
46 | .bookkeeping dd { margin: 0 3em 0.5em; }
47 | 
48 | .critical { margin: 1em; border: double thick red; padding: 1em; background: #FFFFCC; }
49 | .critical > :first-child { margin-top: 0; }
50 | 
51 | .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
52 | td > .example:only-child { margin: 0 0 0 0.1em; }
53 | a.externalDFN {
54 |     color:  inherit;
55 |     border-bottom:  1px dotted #ccc;
56 |     text-decoration:    none;
57 | }
58 | 


--------------------------------------------------------------------------------
/screenshare.js:
--------------------------------------------------------------------------------
 1 | var respecConfig = {
 2 |   // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
 3 |   specStatus:           "ED", // "base",
 4 | 
 5 |   // the specification's short name, as in http://www.w3.org/TR/short-name/
 6 |   shortName:            "screen-capture",
 7 |   // if your specification has a subtitle that goes below the main
 8 |   // formal title, define it here
 9 |   // subtitle   :  "an excellent document",
10 | 
11 |   // if you wish the publication date to be other than today, set this
12 |   // publishDate:  "2009-08-06",
13 | 
14 |   // new ability to override the copyright completely
15 |   // overrideCopyright:  "This document is licensed under a <a href='http://creativecommons.org/licenses/by-nd/4.0/legalcode'>Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0) License. </a> Copyright 2014 Cisco and Mozilla. ",
16 | 
17 |   // if the specification's copyright date is a range of years, specify
18 |   // the start date here:
19 |   copyrightStart: "2015",
20 | 
21 |   // if there is a previously published draft, uncomment this and set its YYYY-MM-DD
22 |   // prevED: "http://dev.w3.org/2011/webrtc/editor/archives/20140321/screenshare.html",
23 | 
24 |   // if there a publicly available Editor's Draft, this is the link
25 |   edDraftURI:           "https://w3c.github.io/mediacapture-screen-share/",
26 | 
27 |   // if this is a LCWD, uncomment and set the end of its review period
28 |   // lcEnd: "2009-08-05",
29 | 
30 |   // if you want to have extra CSS, append them to this list
31 |   // it is recommended that the respec.css stylesheet be kept
32 |   //extraCSS:             ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],
33 |   //extraCSS:           ["../../../2009/dap/ReSpec.js/css/respec.css"],
34 | 
35 |   // editors, add as many as you like
36 |   // only "name" is required
37 |   editors:  [
38 |     // { name: "Your Name", url: "http://example.org/",
39 |     // company: "Your Company", companyURL: "http://example.com/" },
40 |     { name: "Jan-Ivar Bruaroey", company: "Mozilla", w3cid: 79152},
41 |     { name: "Elad Alon", company: "Google", w3cid: 118124}
42 |   ],
43 | 
44 |   formerEditors: [
45 |     { name: "Martin Thomson", company: "Mozilla", w3cid: 68503 },
46 |     { name: "Keith Griffin", company: "Cisco", w3cid: 65606 },
47 |     { name: "Suhas Nandakumar", company: "Cisco", w3cid: 48827},
48 |     { name: "Henrik Boström", company: "Google", w3cid: 96936},
49 |   ],
50 | 
51 |   // authors, add as many as you like.
52 |   // This is optional, uncomment if you have authors as well as editors.
53 |   // only "name" is required. Same format as editors.
54 | 
55 |   //authors:  [
56 |   //    { name: "Your Name", url: "http://example.org/",
57 |   //      company: "Your Company", companyURL: "http://example.com/" },
58 |   //],
59 | 
60 |   // name of the WG
61 |   group: "webrtc",
62 |   xref: ["html", "infra", "permissions", "permissions-policy", "dom", "mediacapture-streams", "webidl", "cssom-view", "css-values", "hr-time"],
63 |   // name (without the @w3.org) of the public mailing to which comments are due
64 |   wgPublicList: "public-webrtc",
65 | 
66 |   github: "https://github.com/w3c/mediacapture-screen-share/",
67 | 
68 |   otherLinks: [
69 |     {
70 |       key: "Participate",
71 |       data: [
72 |         {
73 |           value: "Mailing list",
74 |           href: "https://lists.w3.org/Archives/Public/public-webrtc/"
75 |         }
76 |       ]
77 |     }
78 |   ]
79 | };
80 | 


--------------------------------------------------------------------------------
/explainer.md:
--------------------------------------------------------------------------------
 1 | # Screen Capture Explained
 2 | 
 3 | ## What is it? What’s it for?
 4 | 
 5 | It’s an API to get a live video stream of your computer screen or a single window on it, optionally with sound.
 6 | 
 7 | It’s sometimes referred to as screen-sharing, even though only the capturing part is being defined (sharing is just the primary use case).
 8 | 
 9 | Have you ever been a presenter in an online video conference call? You probably shared your screen or the window of a presentation-program to do that. Have you ever presented in an online video conference call without this feature? You likely either had to gesticulate over printouts in front of your camera, or you had to carefully direct your audience to follow along in their own copy of previously-shared online documents, or both. This can lead to confusion as everyone can get a subtly different view. It’s a pretty key feature. This is that feature.
10 | 
11 |  * Not the networking part—that’s WebRTC’s [RTCPeerConnection](https://w3c.github.io/webrtc-pc/#interface-definition)
12 |  * Not the camera and microphone part—that’s MediaCapture’s [getUserMedia](https://w3c.github.io/mediacapture-main/getusermedia.html#idl-def-mediadevices-partial-1)
13 |  * **Just** the part that captures your computer's display. It’s called: [getDisplayMedia](https://w3c.github.io/mediacapture-screen-share/#mediadevices-additions)
14 | 
15 | Besides formal presentations, being able to spontaneously share what we're looking at on our computers in real-time can complement many online conversations. It's the conversational answer to "What are you looking at?"
16 | 
17 | Web sites may capture the screen for other reasons as well, but screen-sharing is the driving use-case.
18 | 
19 | ## Non-goals
20 | 
21 | Some adjacent goals that are not in scope of this specification:
22 | * Online document sharing
23 | * Remote assistance temporarily "taking over" control of a system
24 | * Co-browsing
25 | 
26 | ## Alternatives
27 | 
28 | Alternatives to screen-sharing:
29 | * Online document sharing using web technology.
30 | * Browser plug-in (like Chrome's now-abandoned Screen Capture extension)
31 | 
32 | Both alternatives have adoption problems and limitations. In contrast, this spec is widely supported, and screen-sharing appears well-understood as a concept.
33 | 
34 | ## Approach
35 | 
36 | The approach is heavily modeled on our [camera API](https://w3c.github.io/mediacapture-main/getusermedia.html#idl-def-mediadevices-partial-1), hence the name similarity. There’s a reason for that: both require user permission, and return a MediaStream object with a pair of highly privacy sensitive video and audio tracks—It’s just your screen instead of your face. The resulting MediaStream is a drop-in anywhere a MediaStream is accepted in the platform. Having obtained such a MediaStream, a website can trivially:
37 | 
38 |  * play the live stream of your screen locally in a video element,
39 |  * send it over a peer connection to another client,
40 |  * send it to a [MediaRecorder](https://w3c.github.io/mediacapture-record/MediaRecorder.html#mediarecorder-api), perhaps for subsequent upload to a server,
41 |  * or all of the above (at once even).
42 | 
43 | This flexibility is thanks to the MediaCapture-main spec which already did the heavy lifting of:
44 |  * defining [MediaStream](https://w3c.github.io/mediacapture-main/getusermedia.html#mediastream) and [MediaStreamTrack](https://w3c.github.io/mediacapture-main/getusermedia.html#dom-mediastreamtrack)
45 |  * defining the constraints an application can apply to downscale and decimate frame-rates
46 |  * defining a privacy-sensitive permission model
47 | 
48 | This leaves this spec to focus on the parts unique to acquiring display media, and its privacy challenges.
49 | 
50 | ## Getting started
51 | 
52 | This is how to request a video MediaStream sourced by screen-capture:
53 | 
54 | ```js
55 | const stream = await navigator.mediaDevices.getDisplayMedia({video: true, audio: true});
56 | ```
57 | 
58 | Compare to a request for camera and microphone:
59 | 
60 | ```js
61 | const stream = await navigator.mediaDevices.getUserMedia({video: true, audio: true});
62 | ```
63 | These streams can then be used interchangeably:
64 | 
65 | ```js
66 | videoElement.srcObject = stream; // self-view
67 | 
68 | new MediaRecorder(stream).start(); // record
69 | 
70 | for (const track of stream.getTracks()) peerConnnection.addTrack(track, stream); // present
71 | 
72 | await stream.getVideoTracks()[0].applyConstraints({height: 480}); // downscale
73 | 
74 | for (const track of stream.getTracks()) track.stop(); // stop capture & relinquish access
75 | ```
76 | 
77 | Some important differences and unique properties of screen capture:
78 | 
79 |  * The request is gated by user activation.
80 |  * The end-user is always prompted each time with a picker to select what to share.
81 |  * It is not possible to persist permission grants (only blocks).
82 |  * Application-supplied constraints are applied after selection, and do not narrow the end-user’s choices (unlike with camera).
83 |  * All choices are videos. Any accompanying audio is optional and requires consent and support.
84 |  * Screen capture sources are never exposed in enumerateDevices().
85 | 
86 | ## Security and privacy implications
87 | 
88 | Allowing a web page to capture and effectively record your screen carries significant privacy and security risks. The three main ones are, in increasing order of severity:
89 | 
90 | **Audio exposure and correlation.** When audio is captured alongside video (which requires specific end-user consent), it may expose additional information about system applications. It may contain system-wide audio in certain cases, which may include audible information from other domains.
91 | 
92 | **End-user oversharing of video.** 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. This can happen from trivial-seeming actions like scrolling, document flipping, even tab headers, anything that’s visible if just for a split second.
93 | 
94 | **Capturing a web surface defeats same-origin protections.** Capturing a browser window or the desktop when a browser window is visible on it, poses a unique privacy and security risk that is unobvious and significant. If a captured browser window is displaying a page that is under the control of a malicious application, even indirectly, it can allow the malicious application to induce presentation of information that would otherwise be secret from it. For details, see [Share browser windows and entire screen only with sites you trust](https://blog.mozilla.org/webrtc/share-browser-windows-entire-screen-sites-trust/).
95 | 
96 | ## Security and Privacy Questionnaire
97 | 
98 | See [questionnaire.md](questionnaire.md).
99 | 


--------------------------------------------------------------------------------
/questionnaire.md:
--------------------------------------------------------------------------------
 1 | # Security and Privacy Questionnaire for Screen Capture
 2 | 
 3 | ## Questions to Consider
 4 | 
 5 | ### 2.1. What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary?
 6 | 
 7 | With a user’s permission, it exposes to a website a live video stream of the user’s desktop, or a window of their choosing, optionally with accompanying audio, if available and consented to.
 8 | The user may choose a **physical** or **virtual monitor**, a **window**, an **application**, or a **browser**. All information visible on the chosen surface is shared. Audible information may also be shared. In addition, depending on the surface, information that’s not currently visible may also be shared. For example: an entire window including parts presently offscreen or obscured by other windows.
 9 | The purpose of the feature is to allow people to share their screen, if they so choose, with others, typically in an online video conference or one-on-one call. A presenter may wish to share the window of their presentation program. Friends and relatives may wish to spontaneously share what they’re looking at on their computer or device to aid or complement a conversation.
10 | See [explainer](explainer.md) for more.
11 | 
12 | ### 2.2. Is this specification exposing the minimum amount of information necessary to power the feature?
13 | 
14 | The decision of what to share (or whether to share anything at all) rests entirely with the end-user. Websites cannot influence this choice in any way, or demand audio be included. A user gesture is required to request, and users may reject or even block all requests. Defining the pool of available sources is left to user agents, as well as decisions about whether to share obscured parts. The spec requires user agents to implement prominent indicators warning users when sharing is live.
15 | 
16 | ### 2.3. How does this specification deal with personal information or personally-identifiable information or information derived thereof?
17 | 
18 | Nothing is shared without a user’s explicit choice. The spec uses the permissions [[PERMISSIONS]](https://www.w3.org/TR/security-privacy-questionnaire/#biblio-permissions) spec to persist denied permissions, and mandates an explicit per-use in-browser chooser prompt. By choosing a surface to share, the end user permits a website one-time access to continuous video (optionally with audio) of that surface, until the website stops the video and/or audio track, the page navigates away, or the user revokes the permission, whichever is sooner. A name (label) of the surface is also shared (e.g. the title of a window) with the track.
19 | 
20 | This is a powerful feature, restricted to secure contexts. No attempt is made to mandate that personal information, sensitive information or cross-origin content be detected and blacked out. To some extent, this is a feature.
21 | 
22 | ### 2.4. How does this specification deal with sensitive information?
23 | 
24 | Per above, nothing prevents a user from sharing a surface that contains sensitive information.
25 | But additionally, the spec strongly advises user agents require [elevated permissions](https://w3c.github.io/mediacapture-screen-share/#elevated-permissions) to share **browser surfaces** or **monitors** with browsers visible. These sources carry **significant risk**, as sensitive information may be leaked through **active attacks on the same-origin policy**. For details, see [Share browser windows and entire screen only with sites you trust](https://blog.mozilla.org/webrtc/share-browser-windows-entire-screen-sites-trust/).
26 | 
27 | ### 2.5. Does this specification introduce new state for an origin that persists across browsing sessions?
28 | 
29 | Nothing is revealed without permission, and grants cannot be persisted. Permission blocking follows feature-policy. See next question.
30 | 
31 | ### 2.6. What information from the underlying platform, e.g. configuration data, is exposed by this specification to an origin?
32 | 
33 | Depending on what a user chooses to share, a website may learn physical properties of their system, such as the size and appearance of their desktop, and any information displayed, e.g. possibly their local time and location (weather) if the user has configured such display on their desktop. This can be correlated to other origins that are using the same API, if  the user shares the same surface there.
34 | 
35 | ### 2.7. Does this specification allow an origin access to sensors on a user’s device
36 | 
37 | Results from sensors may be exposed. While screen-capture is live, the origin may record the result of the user's activity on the system, including, for instance, cursor movements in response to mouse movements.
38 | 
39 | Also, no attempt is made to mandate that camera and microphone sourced playback be excluded from capture. Same with a location shown on a map (from GPS sensors). Users might perceive such mitigations as bugs.
40 | 
41 | ### 2.8. What data does this specification expose to an origin? Please also document what data is identical to data exposed by other features, in the same or different contexts.
42 | 
43 | (This question’s template mentions [same-origin policy](https://www.w3.org/TR/security-privacy-questionnaire/#same-origin-policy) so following that lead) As mentioned earlier, **browser** and **monitor** surfaces may be exploited to circumvent the [same-origin policy](https://www.w3.org/TR/security-privacy-questionnaire/#same-origin-policy), exposing details about another origin’s state in graphical or audible form, which if extracted may be used in POST or GET requests to another origin, potentially carrying severe consequences.
44 | 
45 | A mitigation “strongly advised” by the spec for this is to require [elevated permissions](https://w3c.github.io/mediacapture-screen-share/#elevated-permissions) that “determine that the user exhibits an elevated level of trust in the application that is being granted access” to **browser** and **monitor** sources. At least [one browser attempts to implement](https://support.mozilla.org/en-US/kb/screenshare-safety) this mitigation.
46 | 
47 | ### 2.9. Does this specification enable new script execution/loading mechanisms?
48 | 
49 | No.
50 | 
51 | ### 2.10. Does this specification allow an origin to access other devices?
52 | 
53 | No direct access to other networked devices. All surfaces shared are local (even though this spec inherited the term “device” from the MediaCapture-main specification).
54 | 
55 | No attempt is made to mandate that e.g. a user’s VNC or remote desktop client window be excluded from capture. Users might perceive such mitigations as bugs.
56 | 
57 | ### 2.11. Does this specification allow an origin some measure of control over a user agent’s native UI?
58 | 
59 | In combination with full screen mode, **monitor** surface capture increases a website’s ability to reconstruct a user’s native UI faithfully, in order to fool users or obscure security / privacy controls. However, since the nature of the threat remains unchanged, full screen mode’s existing mitigations should suffice.
60 | 
61 | ### 2.12. What temporary identifiers might this specification create or expose to the web?
62 | 
63 | No temporary identifiers (e.g. deviceIds) are exposed.
64 | 
65 | ### 2.13. How does this specification distinguish between behavior in first-party and third-party contexts?
66 | 
67 | It defines the feature policy “display-capture”. It is off by default in iframes.
68 | 
69 | ### 2.14. How does this specification work in the context of a user agent’s Private Browsing or "incognito" mode?
70 | 
71 | Assuming a user agent allows the same sources in both modes, the same risks of correlation mentioned earlier across origins apply here. Whether the permission is blocked or not also carries some information across, depending on the user agent.
72 | 
73 | ### 2.15. Does this specification have a "Security Considerations" and "Privacy Considerations" section?
74 | 
75 | Yes, see [§8 Security & Permissions](https://w3c.github.io/mediacapture-screen-share/#security-and-permissions) and [§7 Privacy Indicator Requirements](https://w3c.github.io/mediacapture-screen-share/#privacy-indicator-requirements). 
76 | 
77 | ### 2.16. Does this specification allow downgrading default security characteristics?
78 | 
79 | Only permission delegation of this powerful feature to iframes through feature policy, to the extent a site is more secure without this feature.
80 | 
81 | Sharing this feature with an embedded iframe exposes the top-level site to the risks of the same-origin vulnerabilities discussed earlier.
82 | 
83 | ### 2.17. What should this questionnaire have asked?
84 | 
85 | Seems thorough. It wasn’t always clear whether the word “device” referred to a user’s system, other networked systems, or peripherals like camera and microphone, or all of the above. This may stem from a terminology conflict with our WG. What we call “devices”, you seem to call “sensors”.
86 | 


--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
   1 | <!DOCTYPE html>
   2 | 
   3 | <html lang="en-us">
   4 | <head>
   5 |   <link href="screenshare.css" rel="stylesheet" type="text/css">
   6 | 
   7 |   <title>Screen Capture</title>
   8 |   <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
   9 |   <script class="remove" src="screenshare.js" type="text/javascript"></script>
  10 |   <script class="remove" src=
  11 |   "https://www.w3.org/Tools/respec/respec-w3c"></script>
  12 | </head>
  13 | 
  14 | <body>
  15 |   <section id="abstract">
  16 |     <p>This document defines how a user's display, or parts thereof, can be
  17 |     used as the source of a media stream using
  18 |     {{MediaDevices/getDisplayMedia}}, an extension to the Media Capture API
  19 |     [[GETUSERMEDIA]].</p>
  20 |   </section>
  21 | 
  22 | 
  23 |   <section id="sotd">
  24 |     <p>This document is not complete. It is subject to major changes and, while
  25 |     early experimentations are encouraged, it is therefore not intended for
  26 |     implementation.</p>
  27 |   </section>
  28 | 
  29 | 
  30 |   <section class="informative" id="intro">
  31 |     <h2>Introduction</h2>
  32 | 
  33 | 
  34 |     <p>This document describes an extension to the Media Capture API
  35 |     [[GETUSERMEDIA]] that enables the acquisition of a user's display, or part
  36 |     thereof, in the form of a video track. In some cases system, application or
  37 |     window audio is also captured which is presented in the form of an audio
  38 |     track. This enables a number of applications, including screen sharing
  39 |     using WebRTC [[WEBRTC]].</p>
  40 | 
  41 | 
  42 |     <p>This feature has signficant security implications. Applications that use
  43 |     this API to access information that is displayed to users could access
  44 |     confidential information from other origins if that information is under
  45 |     the control of the application. This includes content that would otherwise
  46 |     be inaccessible due to the protections offered by the user agent
  47 |     sandbox.</p>
  48 | 
  49 | 
  50 |     <p>This document concerns itself primarily with the capture of video and
  51 |     audio [[GETUSERMEDIA]], but the general mechanisms defined here could be
  52 |     extended to other types of media, of which depth [[MEDIACAPTURE-DEPTH]] is
  53 |     currently defined.</p>
  54 |   </section>
  55 | 
  56 | 
  57 |   <section id="conformance">
  58 |     <p>This specification defines conformance criteria that apply to a single
  59 |     product: the <dfn data-lt="user agents">user agent</dfn> that implements
  60 |     the interfaces that it contains.</p>
  61 | 
  62 | 
  63 |     <p>Implementations that use ECMAScript [[ECMA-262]] to implement the APIs
  64 |     defined in this specification must implement them in a manner consistent
  65 |     with the ECMAScript Bindings defined in the Web IDL specification
  66 |     [[!WEBIDL]], as this specification uses that specification and
  67 |     terminology.</p>
  68 |   </section>
  69 | 
  70 | 
  71 |   <section>
  72 |     <h2>Example</h2>
  73 | 
  74 | 
  75 |     <p>The following example demonstrates a request for display capture using
  76 |     the <code>navigator.mediaDevices.getDisplayMedia</code> method defined in
  77 |     this document.</p>
  78 | 
  79 |     <pre class="example highlight">try {
  80 |   let mediaStream = await navigator.mediaDevices.getDisplayMedia({video:true});
  81 |   videoElement.srcObject = mediaStream;
  82 | } catch (e) {
  83 |   console.log('Unable to acquire screen capture: ' + e);
  84 | }</pre>
  85 |   </section>
  86 | 
  87 | 
  88 |   <section>
  89 |     <h2>Terminology</h2>
  90 | 
  91 | 
  92 |     <p>This document uses the definition of {{MediaStream}},
  93 |     {{MediaStreamTrack}} and {{ConstrainablePattern}} from
  94 |     [[!GETUSERMEDIA]].</p>
  95 | 
  96 | 
  97 |     <p>Screen capture encompasses the capture of several different types of
  98 |     screen-based surfaces. Collectively, these are referred to as <dfn class=
  99 |     "export" data-lt="display surface">display surfaces</dfn>, of which this
 100 |     document defines the following types:</p>
 101 | 
 102 | 
 103 |     <ul>
 104 |       <li>A <dfn data-dfn-for="display surface" class="export">monitor</dfn>
 105 |       <a>display surface</a> represents a physical display. Some systems have
 106 |       multiple [= display surface/monitor =]s, which can be identified
 107 |       separately. Multiple [= display surface/monitor =]s might also be
 108 |       aggregated into a single logical [= display surface/monitor =]. An
 109 |       aggregated <a>display surface</a> is captured as a single
 110 |       {{MediaStreamTrack}}.
 111 |       </li>
 112 | 
 113 | 
 114 |       <li>A <dfn data-dfn-for="display surface" class="export">window</dfn> <a>
 115 |         display surface</a> is a single contiguous surface that is used by a
 116 |         single application.
 117 |       </li>
 118 | 
 119 | 
 120 |       <li>A <dfn data-dfn-for="display surface" class="export">browser</dfn>
 121 |       <a>display surface</a> is the rendered form of a [=browsing context=].
 122 |       This is not strictly limited to HTML [[HTML]] documents, though the
 123 |       discussion in this document will address some specific concerns with the
 124 |       capture of HTML.
 125 |       </li>
 126 |     </ul>
 127 | 
 128 | 
 129 |     <p>This document draws a distinction between two variants of each type of
 130 |     display surface:</p>
 131 | 
 132 | 
 133 |     <ul>
 134 |       <li>A <dfn class="export">logical display surface</dfn> is the surface
 135 |       that an operating system makes available to an application for the
 136 |       purposes of rendering.</li>
 137 | 
 138 | 
 139 |       <li>a <dfn class="export">visible display surface</dfn> is the portion of
 140 |       a [=logical display surface=] that is rendered to a [= display
 141 |       surface/monitor=].</li>
 142 |     </ul>
 143 | 
 144 | 
 145 |     <p>Some operating systems permit windows from different applications to
 146 |     occlude other windows, in whole or part, so the <a>visible display
 147 |     surface</a> is a strict subset of the <a>logical display surface</a>.</p>
 148 | 
 149 | 
 150 |     <p>The <dfn class="export">source pixel ratio</dfn> of a <a>display
 151 |     surface</a> is 1/96th of 1 inch divided by its vertical pixel size.</p>
 152 | 
 153 |     <p>The <dfn class="event">devicechange</dfn> event is defined in
 154 |     [[GETUSERMEDIA]].</p>
 155 |   </section>
 156 | 
 157 | 
 158 |   <section>
 159 |     <h2>Capturing Displayed Media</h2>
 160 |     <!--
 161 |       Interesting Links
 162 | 
 163 |       https://bugzilla.mozilla.org/show_bug.cgi?id=742832
 164 | 
 165 |       http://www.chromium.org/developers/design-documents/extensions/proposed-changes/apis-under-development/webrtc-tab-content-capture
 166 | 
 167 |       https://docs.google.com/document/d/1-vFghorm8zDCeyg2Yk6kKFT-16GU1Ow1b1bor_jCqD8/edit
 168 |       -->
 169 | 
 170 | 
 171 |     <p>Capture of displayed media is enabled through the addition of a new
 172 |     {{MediaDevices/getDisplayMedia}} method on the {{MediaDevices}} interface,
 173 |     that is similar to {{MediaDevices/getUserMedia()}} , except that it
 174 |     acquires media from one display device chosen by the end-user each
 175 |     time.</p>
 176 | 
 177 | 
 178 |     <section>
 179 |       <h2><dfn>MediaDevices</dfn> Additions</h2>
 180 | 
 181 |       <pre class="idl">partial interface MediaDevices {
 182 |   Promise&lt;MediaStream&gt; getDisplayMedia(optional DisplayMediaStreamOptions options = {});
 183 | };</pre>
 184 | 
 185 |       <dl data-link-for="MediaDevices" data-dfn-for="MediaDevices" class=
 186 |       "methods">
 187 |         <dt><dfn>getDisplayMedia</dfn>
 188 |         </dt>
 189 | 
 190 | 
 191 |         <dd>
 192 |           <p>Prompts the user for permission to live-capture their display.</p>
 193 | 
 194 | 
 195 |           <p>The user agent MUST let the end-user choose which [=display
 196 |           surface=] to share out of all available choices every time, and MUST
 197 |           NOT use any {{MediaTrackConstraints}} in
 198 |           <var>options</var>.<code>video</code> or
 199 |           <var>options</var>.<code>audio</code> to limit that choice.</p>
 200 | 
 201 | 
 202 |           <p>The user agent MAY use the presence of the {{displaySurface}}
 203 |           constraint and its value to influence the presentation to the user of
 204 |           the sources to pick from. The user agent MUST still offer the user
 205 |           unlimited choice of any [=display surface=]. The user agent is
 206 |           strongly recommended to steer users away from sharing a monitor, as
 207 |           this poses <a href="#security-and-permissions">risks to user
 208 |           privacy</a>.</p>
 209 | 
 210 | 
 211 |           <p>Any {{MediaTrackConstraints}} in
 212 |           <var>options</var>.<code>video</code> or
 213 |           <var>options</var>.<code>audio</code> MUST be applied to the media
 214 |           chosen by the user only after the user has made their selection.</p>
 215 | 
 216 | 
 217 |           <p>In the case of audio, the user agent MAY present the end-user with
 218 |           audio sources to share. Which choices are available to choose from is
 219 |           up to the user agent, and the audio source(s) are not necessarily the
 220 |           same as the video source(s). An audio source may be a particular [=
 221 |           display surface/window =], [= display surface/browser =], the entire
 222 |           system audio or any combination thereof. Unlike
 223 |           {{MediaDevices/getUserMedia()}} with regards to audio+video, the user
 224 |           agent is allowed not to return audio even if the audio constraint is
 225 |           present. If the user agent knows no audio will be shared for the
 226 |           lifetime of the stream it MUST NOT include an audio track in the
 227 |           resulting stream. The user agent MAY accept a request for audio and
 228 |           video by only returning a video track in the resulting stream, or it
 229 |           MAY accept the request by returning both an audio track and a video
 230 |           track in the resulting stream. The user agent MUST reject audio-only
 231 |           requests.</p>
 232 | 
 233 | 
 234 |           <p>In addition to drawing from a different set of sources and
 235 |           requiring user selection, {{MediaDevices/getDisplayMedia}} also
 236 |           differs from {{MediaDevices/getUserMedia()}} in that
 237 |           {{PermissionState/"granted"}} permissions cannot be persisted.</p>
 238 | 
 239 | 
 240 |           <p>When the {{MediaDevices/getDisplayMedia()}} method is called, the
 241 |           user agent MUST run the following steps:</p>
 242 | 
 243 | 
 244 |           <ol>
 245 |             <li>
 246 |               <p>Let <var>mediaDevices</var> be [=this=].</p>
 247 |             </li>
 248 | 
 249 | 
 250 |             <li>
 251 |               <p>Let <var>controller</var> be
 252 |               <var>options</var>.<code>controller</code> if present, or
 253 |               <code>null</code> otherwise.</p>
 254 |             </li>
 255 | 
 256 | 
 257 |             <li>
 258 |               <p>If <var>controller</var> is not <code>null</code>, run the
 259 |               following steps:</p>
 260 | 
 261 | 
 262 |               <ol>
 263 |                 <li>
 264 |                   <p>If <var>controller</var>.{{CaptureController/[[IsBound]]}}
 265 |                   is <code>true</code>, return a promise [=reject|rejected=]
 266 |                   with a {{DOMException}} object whose {{DOMException/name}}
 267 |                   attribute has the value {{InvalidStateError}}.</p>
 268 |                 </li>
 269 | 
 270 | 
 271 |                 <li>
 272 |                   <p>Set
 273 |                   <var>controller</var>.{{CaptureController/[[IsBound]]}} to
 274 |                   <code>true</code>.</p>
 275 |                 </li>
 276 |               </ol>
 277 |             </li>
 278 | 
 279 | 
 280 |             <li>
 281 |               <p>If the [=relevant global object=] of [=this=] does not have
 282 |               [=transient activation=], return a promise <a>rejected</a> with a
 283 |               {{DOMException}} object whose {{DOMException/name}} attribute has
 284 |               the value {{InvalidStateError}}.</p>
 285 |             </li>
 286 | 
 287 | 
 288 |             <li>
 289 |               <p>Let <var>options</var> be the method's first argument.</p>
 290 |             </li>
 291 | 
 292 | 
 293 |             <li>
 294 |               <p>Let <var>constraints</var> be
 295 |               <code>[</code><var>options</var>.<code>audio</code>,
 296 |               <var>options</var>.<code>video</code><code>]</code>.</p>
 297 |             </li>
 298 | 
 299 | 
 300 |             <li>
 301 |               <p>If <code>constraints.video</code> is <code>false</code>,
 302 |               return a promise [=reject|rejected=] with a newly
 303 |               [=exception/created=] {{TypeError}}.</p>
 304 |             </li>
 305 | 
 306 | 
 307 |             <li>
 308 |               <p>For each [= map/exist | existing =] member in
 309 |               <var>constraints</var> whose value, <var>CS</var>, is a
 310 |               dictionary, run the following steps:</p>
 311 | 
 312 | 
 313 |               <ol>
 314 |                 <li>
 315 |                   <p>If <var>CS</var> contains a member named
 316 |                   <code>advanced</code>, return a promise [=reject|rejected=]
 317 |                   with a newly [=exception/created=] {{TypeError}}.</p>
 318 |                 </li>
 319 | 
 320 | 
 321 |                 <li>
 322 |                   <p>If <var>CS</var> contains a member whose name specifies a
 323 |                   constrainable property applicable to [=display surface=]s,
 324 |                   and whose value in turn is a dictionary containing a member
 325 |                   named either <code>min</code> or <code>exact</code>, return a
 326 |                   promise [=reject|rejected=] with a newly
 327 |                   [=exception/created=] {{TypeError}}.</p>
 328 |                 </li>
 329 | 
 330 | 
 331 |                 <li>
 332 |                   <p>If <var>CS</var> contains a member whose name specifies a
 333 |                   constrainable property applicable to [=display surface=]s,
 334 |                   and whose value in turn is a dictionary containing a member
 335 |                   named <code>max</code>, and that member's value in turn is
 336 |                   less than the constrainable property's [=floor value=], then
 337 |                   let <var>failedConstraint</var> be the name of the member,
 338 |                   let <var>message</var> be either <code>undefined</code> or an
 339 |                   informative human-readable message, and return a promise
 340 |                   [=reject|rejected=] with a new
 341 |                   <code>OverconstrainedError</code> created by calling
 342 |                   <code>OverconstrainedError(<var>failedConstraint</var>,
 343 |                   <var>message</var>)</code>.</p>
 344 |                 </li>
 345 |               </ol>
 346 |             </li>
 347 | 
 348 | 
 349 |             <li>
 350 |               <p>Let <var>requestedMediaTypes</var> be the set of media types
 351 |               in <var>constraints</var> with either a dictionary value or a
 352 |               value of <code>true</code>.</p>
 353 |             </li>
 354 | 
 355 | 
 356 |             <li>
 357 |               <p>If the <a>current settings object</a>'s [=relevant global
 358 |               object=]'s [=associated `Document`=] is NOT [=Document/fully
 359 |               active=] or does NOT <a data-cite="!HTML/#gains-focus">have
 360 |               focus</a>, return a promise [=reject|rejected=] with a
 361 |               {{DOMException}} object whose {{DOMException/name}} attribute has
 362 |               the value {{InvalidStateError}}.</p>
 363 |             </li>
 364 | 
 365 | 
 366 |             <li>
 367 |               <p>Let <var>p</var> be a new promise.</p>
 368 |             </li>
 369 | 
 370 | 
 371 |             <li>
 372 |               <p>Run the following steps [=in parallel=]:</p>
 373 | 
 374 | 
 375 |               <ol>
 376 |                 <li>
 377 |                   <p>For each media type <var>T</var> in
 378 |                   <var>requestedMediaTypes</var>,</p>
 379 | 
 380 | 
 381 |                   <ol>
 382 |                     <li>
 383 |                       <p>If no sources of type <var>T</var> are available,
 384 |                       [=queue a task=] on the [=user interaction task source=]
 385 |                       to [=reject=] <var>p</var> with a new {{DOMException}}
 386 |                       object whose {{DOMException/name}} attribute has the
 387 |                       value {{NotFoundError}}, and abort these steps.</p>
 388 |                     </li>
 389 | 
 390 | 
 391 |                     <li>
 392 |                       <p>Read the current [= permission state=] for obtaining
 393 |                       sources of type <var>T</var> in the current browsing
 394 |                       context. If the permission state is
 395 |                       {{PermissionState/"denied"}}, jump to the step labeled
 396 |                       <em>PermissionFailure</em> below.</p>
 397 |                     </li>
 398 |                   </ol>
 399 |                 </li>
 400 | 
 401 | 
 402 |                 <li>
 403 |                   <p>Optionally, e.g., based on a previously-established user
 404 |                   preference, for security reasons, or due to platform
 405 |                   limitations, jump to the step labeled <em>Permission
 406 |                   Failure</em> below.</p>
 407 |                 </li>
 408 | 
 409 | 
 410 |                 <li>
 411 |                   <p>[=Prompt the user to choose=] a display device, for a
 412 |                   {{PermissionDescriptor}} with its
 413 |                   {{PermissionDescriptor/name}} set to "display-capture",
 414 |                   resulting in a set of provided media.</p>
 415 | 
 416 | 
 417 |                   <p>The provided media MUST include precisely one video
 418 |                   track.</p>
 419 | 
 420 | 
 421 |                   <p>The provided media MUST include at most one audio track.
 422 |                   This audio track MUST NOT be included if audio was not
 423 |                   specified in <var>requestedMediaTypes</var>, or if it was
 424 |                   specified as <code>false</code>.</p>
 425 | 
 426 | 
 427 |                   <p>The devices chosen MUST be the ones determined by the
 428 |                   user. Once selected, the source of a {{MediaStreamTrack}}
 429 |                   MUST NOT change, unless the user permits it through their
 430 |                   interaction with the user agent.</p>
 431 | 
 432 | 
 433 |                   <p>User agents are encouraged to warn users against sharing
 434 |                   [= display surface/browser =] display devices as well as [=
 435 |                   display surface/monitor =] display devices where browser
 436 |                   windows are visible, or otherwise try to discourage their
 437 |                   selection on the basis that these represent a significantly
 438 |                   higher risk when shared.</p>
 439 | 
 440 | 
 441 |                   <p>If the result of the request is
 442 |                   {{PermissionState/"granted"}}, then for each device that is
 443 |                   sourcing the provided media, using a stable and private id
 444 |                   for the device, <var>deviceId</var>, set
 445 |                   [[\devicesLiveMap]]<var>[deviceId]</var> to
 446 |                   <code>true</code>, if it isn’t already <code>true</code>, and
 447 |                   set the [[\devicesAccessibleMap]]<var>[deviceId]</var> to
 448 |                   <code>true</code>, if it isn’t already <code>true</code>.</p>
 449 | 
 450 | 
 451 |                   <p>The user agent MUST NOT store a
 452 |                   {{PermissionState/"granted"}} permission entry.</p>
 453 | 
 454 | 
 455 |                   <p>If the result is {{PermissionState/"denied"}}, jump to the
 456 |                   step labeled <em>Permission Failure</em> below. If the user
 457 |                   never responds, this algorithm stalls on this step.</p>
 458 | 
 459 | 
 460 |                   <p>If the user grants permission but a hardware error such as
 461 |                   an OS/program/webpage lock prevents access, [=queue a task=]
 462 |                   on the [=user interaction task source=] to [=reject=]
 463 |                   <var>p</var> with a new {{DOMException}} object whose
 464 |                   {{DOMException/name}} attribute has the value
 465 |                   {{NotReadableError}}, and abort these steps.</p>
 466 | 
 467 | 
 468 |                   <p>If the result is {{PermissionState/"granted"}} but device
 469 |                   access fails for any reason other than those listed above,
 470 |                   [=queue a task=] on the [=user interaction task source=] to
 471 |                   [=reject=] <var>p</var> with a new {{DOMException}} object
 472 |                   whose {{DOMException/name}} attribute has the value
 473 |                   {{AbortError}}, and abort these steps.</p>
 474 |                 </li>
 475 | 
 476 | 
 477 |                 <li>
 478 |                   <p>Let <var>stream</var> be a {{MediaStream}} object.</p>
 479 |                 </li>
 480 | 
 481 |                 <li>
 482 |                   <p>For each <var>source</var> that the user granted permission
 483 |                   to, run the following steps:</p>
 484 |                     <ol>
 485 |                       <li>
 486 |                         <p>Let <var>track</var> be the result of [=create a
 487 |                         MediaStreamTrack|creating a MediaStreamTrack=]
 488 |                         with <var>source</var> and <var>mediaDevices</var>.</p>
 489 |                       </li>
 490 |                       <li>
 491 |                         <p>Add <var>track</var> to <var>stream</var>'s track set.</p>
 492 |                       </li>
 493 |                       <li>
 494 |                         <p>[=Tie track source to MediaDevices=] with <var>source</var> and <var>mediaDevices</var>.</p>
 495 |                       </li>
 496 |                     </ol>
 497 |                 </li>
 498 | 
 499 | 
 500 |                 <li>
 501 |                   <p>Run the [=ApplyConstraints algorithm=] on all tracks in
 502 |                   <var>stream</var> with the appropriate constraints. Should
 503 |                   this fail, let <var>failedConstraint</var> be the result of
 504 |                   the algorithm that failed, and let <var>message</var> be
 505 |                   either <code>undefined</code> or an informative
 506 |                   human-readable message, and then [=queue a task=] on the
 507 |                   [=user interaction task source=] to [=reject=] <var>p</var>
 508 |                   with a new <code>OverconstrainedError</code> created by
 509 |                   calling
 510 |                   <code>OverconstrainedError(<var>failedConstraint</var>,
 511 |                   <var>message</var>)</code>, and abort these steps.</p>
 512 |                 </li>
 513 | 
 514 | 
 515 |                 <li>
 516 |                   <p>This invocation of {{MediaDevices/getDisplayMedia()}} is
 517 |                   now considered to have produced a new
 518 |                   <dfn>capture-session</dfn>.</p>
 519 |                 </li>
 520 |                 <li>
 521 |                   <p>[=Queue a task=] on the [=user interaction task source=] to
 522 |                   run the following steps:</p>
 523 |                   <ol>
 524 |                     <li>
 525 |                       <p>If <var>controller</var> is not `null`, run the
 526 |                       following steps:</p>
 527 |                       <ol>
 528 |                         <li>
 529 |                           <p>Set
 530 |                           <var>controller</var>.{{CaptureController/[[Source]]}} to
 531 |                           <var>stream</var>'s video track's <a data-cite=
 532 |                           "GETUSERMEDIA#dfn-source-0">[[\Source]]</a>.</p>
 533 |                         </li>
 534 |                         <li>
 535 |                           <p>Set
 536 |                           <var>controller</var>.{{CaptureController/[[DisplaySurfaceType]]}}
 537 |                           to the to <var>stream</var>'s video track's
 538 |                           {{DisplayCaptureSurfaceType}}.</p>
 539 |                         </li>
 540 |                       </ol>
 541 |                     </li>
 542 |                     <li>
 543 |                       Set the <a data-cite="html/#last-activation-timestamp">last activation timestamp</a>
 544 |                       to the [=current high resolution time=].
 545 |                     </li>
 546 |                     <li>
 547 |                       <p>[=Resolve=] <var>p</var> with <var>stream</var>.</p>
 548 |                     </li>
 549 |                   </ol>
 550 |                 </li>
 551 |                 <li>
 552 |                   <p>If <var>controller</var> is not `null`, [=queue a task=]
 553 |                   on the [=user interaction task source=] to run the
 554 |                   [=finalize focus decision algorithm=] on <var>controller</var>.</p>
 555 |                 </li>
 556 |                 <li>
 557 |                   <p>Abort these steps.</p>
 558 |                 </li>
 559 |                 <li>
 560 |                   <p><em>Permission Failure</em>: [=Queue a task=] on the
 561 |                   [=user interaction task source=] to
 562 |                   [=reject=] <var>p</var> with
 563 |                   a new {{DOMException}} object whose {{DOMException/name}}
 564 |                   attribute has the value {{NotAllowedError}}.</p>
 565 |                 </li>
 566 |               </ol>
 567 |             </li>
 568 | 
 569 | 
 570 |             <li>
 571 |               <p>Return <var>p</var>.</p>
 572 |             </li>
 573 |           </ol>
 574 | 
 575 | 
 576 |           <p>When the top-level document loses focus, run the following steps
 577 |           on all {{CaptureController}} objects in that document and in
 578 |           documents of its nested [=browsing contexts=]:</p>
 579 | 
 580 | 
 581 |           <ol>
 582 |             <li>
 583 |               <p>If {{CaptureController/[[Source]]}} is <code>undefined</code>,
 584 |               abort these steps.</p>
 585 |             </li>
 586 | 
 587 | 
 588 |             <li>
 589 |               <p>Set {{CaptureController/[[FocusChangeDisabled]]}} to
 590 |               <code>true</code>.</p>
 591 |             </li>
 592 |           </ol>
 593 | 
 594 | 
 595 |           <p>The <a>user agent</a> MUST NOT capture content that's behind a
 596 |           partially transparent captured <a>display surface</a>.</p>
 597 | 
 598 | 
 599 |           <p>For the newly created {{MediaStreamTrack}}, the <a>user agent</a>
 600 |           MUST NOT capture the prompt that was shown to the user.</p>
 601 | 
 602 | 
 603 |           <p>Information that is not currently rendered to the screen SHOULD be
 604 |           obscured in captures unless the application has been specifically
 605 |           authorized to access that content (e.g. through means such as
 606 |           <a>elevated permissions</a>).</p>
 607 | 
 608 | 
 609 |           <p>The <a>user agent</a> MUST NOT share audio without <a>active user
 610 |           consent</a>, for example if the capture of the video of a [= display
 611 |           surface/window =] is accompanied by capture of the audio of the
 612 |           entire system, including applications unrelated to that window.</p>
 613 |         </dd>
 614 |       </dl>
 615 |     </section>
 616 | 
 617 | 
 618 |     <section>
 619 |       <h2 id="hidden-display-surfaces">Closed and Minimized Display
 620 |       Surfaces</h2>
 621 | 
 622 | 
 623 |       <p>A <a>display surface</a> that is being shared may temporarily or
 624 |       permanently become inaccessible to the application because of actions
 625 |       taken by the operating system or user agent. What makes a <a>display
 626 |       surface</a> considered inaccesible is outside the scope of this
 627 |       specification, but examples MAY include a [= display surface/monitor =]
 628 |       disconnecting, [= display surface/window =] or [= display surface/browser
 629 |       =] closing or becoming minimized, or due to an incoming call on a
 630 |       phone.</p>
 631 | 
 632 | 
 633 |       <p class="note">User agents ultimately control what inaccesible means in
 634 |       this context, but are encouraged to only fire mute and unmute events for
 635 |       interruptions that have external reasons.</p>
 636 | 
 637 | 
 638 |       <p>When <a>display surface</a> enters an inaccessible state that is not
 639 |       necessarily permanent, the user agent MUST [=queue a task=] on the
 640 |       [=user interaction task source=] that [= MediaStreamTrack/set a
 641 |       track's muted state|sets the muted state =] of the corresponding media
 642 |       track to <code>true</code>.</p>
 643 | 
 644 | 
 645 |       <p>When <a>display surface</a> exits an inaccessible state and becomes
 646 |       accessible, the user agent MUST [=queue a task=] on the
 647 |       [=user interaction task source=] that [= MediaStreamTrack/set a track's muted
 648 |       state|sets the muted state =] of the corresponding media track to
 649 |       <code>false</code>.</p>
 650 | 
 651 | 
 652 |       <p>When a <a>display surface</a> enters an inaccessible state that is
 653 |       permanent (such as the source [= display surface/window=] closing), the
 654 |       user agent MUST [=queue a task=] on the [=user interaction task source=]
 655 |       that [= MediaStreamTrack/ended | ends =] the corresponding media track.</p>
 656 | 
 657 | 
 658 |       <p>A stream that was just returned by {{MediaDevices/getDisplayMedia}}
 659 |       MAY contain tracks that are muted by default. Audio and video tracks
 660 |       belonging to the same stream MAY be muted/unmuted independently of one
 661 |       another.</p>
 662 |     </section>
 663 | 
 664 | 
 665 |     <section>
 666 |       <h2 id="constraints">Unconstrained Display Surface Selection</h2>
 667 | 
 668 | 
 669 |       <p class="fingerprint">Not accepting constraints for source selection
 670 |       means that {{MediaDevices/getDisplayMedia}} only provides fingerprinting
 671 |       surface that exposes whether audio, video or audio and video display
 672 |       sources are present. <img alt="(This is a fingerprinting vector.)" src=
 673 |       "images/fingerprint.png" width="15" height="21"></p>
 674 | 
 675 | 
 676 |       <p>Note that accepting the {{displaySurface}} constraint does not limit
 677 |       user selection.</p>
 678 |     </section>
 679 | 
 680 | 
 681 |     <section>
 682 |       <h2 id="constrainable-properties">Constrainable Properties for Captured
 683 |       Display Surfaces</h2>
 684 | 
 685 | 
 686 |       <p>Constraints serve a different purpose in
 687 |       {{MediaDevices/getDisplayMedia}} than they do in
 688 |       {{MediaDevices/getUserMedia()}}. They do not aid discovery, instead they
 689 |       are applied only after user-selection.</p>
 690 | 
 691 | 
 692 |       <p>This section define which constraints apply to
 693 |       {{MediaDevices/getDisplayMedia}} tracks; constraints defined for
 694 |       {{MediaDevices/getUserMedia()}} do not apply unless listed here.</p>
 695 | 
 696 | 
 697 |       <p>Some of these constraints enable user agent processing like
 698 |       downscaling and frame decimation, as well as display-specific features.
 699 |       Others enable observation of inherent properties of a user-selected
 700 |       <a>display surface</a>, as capabilities and settings.</p>
 701 | 
 702 | 
 703 |       <p>The following new and existing {{MediaStreamTrack}} <a data-cite=
 704 |       "GETUSERMEDIA#constrainable-properties">Constrainable Properties</a> are
 705 |       defined to apply to the user-selected video <a>display surface</a>, with
 706 |       the following behavior:</p>
 707 | 
 708 | 
 709 |       <table class="simple">
 710 |         <thead>
 711 |           <tr>
 712 |             <th>Property Name</th>
 713 | 
 714 |             <th>Type</th>
 715 | 
 716 |             <th>Behavior</th>
 717 |           </tr>
 718 |         </thead>
 719 | 
 720 | 
 721 |         <tbody>
 722 |           <tr id="def-constraint-width">
 723 |             <td><dfn class="export">width</dfn>
 724 |             </td>
 725 | 
 726 |             <td>{{unsigned long}}</td>
 727 | 
 728 |             <td>
 729 |               The width, in pixels. As a capability, max MUST reflect the
 730 |               <a>display surface</a>'s width, and min MUST reflect the width of
 731 |               the smallest aspect-preserving representation available through
 732 |               downscaling by the user agent.
 733 |             </td>
 734 |           </tr>
 735 | 
 736 | 
 737 |           <tr id="def-constraint-height">
 738 |             <td><dfn class="export">height</dfn>
 739 |             </td>
 740 | 
 741 |             <td>{{unsigned long}}</td>
 742 | 
 743 |             <td>
 744 |               The height, in pixels. As a capability, max MUST reflect the
 745 |               <a>display surface</a>'s height, and min MUST reflect the height
 746 |               of the smallest aspect-preserving representation available
 747 |               through downscaling by the user agent.
 748 |             </td>
 749 |           </tr>
 750 | 
 751 | 
 752 |           <tr id="def-constraint-frameRate">
 753 |             <td><dfn class="export">frameRate</dfn>
 754 |             </td>
 755 | 
 756 |             <td>{{double}}</td>
 757 | 
 758 |             <td>
 759 |               The frame rate (frames per second). As a capability, max MUST
 760 |               reflect the <a>display surface</a>'s frame rate, and min MUST
 761 |               reflect the lowest frame rate available through frame decimation
 762 |               by the user agent.
 763 |             </td>
 764 |           </tr>
 765 | 
 766 | 
 767 |           <tr id="def-constraint-aspect">
 768 |             <td><dfn class="export">aspectRatio</dfn>
 769 |             </td>
 770 | 
 771 |             <td>{{double}}</td>
 772 | 
 773 |             <td>The exact aspect ratio (width in pixels divided by height in
 774 |             pixels, represented as a double rounded to the tenth decimal place)
 775 |             or aspect ratio range. As a setting, represents <code>width /
 776 |             height</code>. As a capability, min and max both MUST be the
 777 |             current setting value, rendering this property immutable from the
 778 |             application viewpoint.</td>
 779 |           </tr>
 780 | 
 781 | 
 782 |           <tr id="def-constraint-resizeMode">
 783 |             <td><dfn class="export">resizeMode</dfn>
 784 |             </td>
 785 | 
 786 |             <td>{{DOMString}}</td>
 787 | 
 788 |             <td>
 789 |               This string is one of the members of {{VideoResizeModeEnum}}. As
 790 |               a setting, {{VideoResizeModeEnum/"none"}} means the
 791 |               {{MediaStreamTrack}} contains all bits needed to render the
 792 |               display in full detail, which if the <code><a>source pixel
 793 |               ratio</a> &gt; 1</code>, means <code>width</code> and
 794 |               <code>height</code> will be larger than the display's appearance
 795 |               from an end-user viewpoint would suggest, whereas
 796 |               {{VideoResizeModeEnum/"crop-and-scale"}} means the
 797 |               {{MediaStreamTrack}} contains an aspect-preserved representation
 798 |               of the <a>display surface</a> that has been downscaled by the
 799 |               user agent, but not cropped. As a capability, the values
 800 |               {{VideoResizeModeEnum/"none"}} and
 801 |               {{VideoResizeModeEnum/"crop-and-scale"}} both MUST be present.
 802 |             </td>
 803 |           </tr>
 804 | 
 805 | 
 806 |           <tr id="def-constraint-deviceId">
 807 |             <td><dfn class="export">deviceId</dfn>
 808 |             </td>
 809 | 
 810 |             <td>{{DOMString}}</td>
 811 | 
 812 |             <td>
 813 |               The identifier of the surface being captured.
 814 | 
 815 |               <p>As a setting, identifies the [=display surface=] that
 816 |               is being captured. The identifier MUST be uniquely generated for
 817 |               each [=document=].</p>
 818 | 
 819 |               <p>As a capability, the setting value MUST be the lone value
 820 |               present, rendering this property immutable from the application
 821 |               viewpoint.</p>
 822 |             </td>
 823 |           </tr>
 824 | 
 825 | 
 826 |           <tr id="def-constraint-displaySurface">
 827 |             <td><dfn class="export">displaySurface</dfn>
 828 |             </td>
 829 | 
 830 |             <td>{{DOMString}}</td>
 831 | 
 832 |             <td>
 833 |               <p>This string is one of the members of
 834 |               {{DisplayCaptureSurfaceType}}.</p>
 835 | 
 836 | 
 837 |               <p>As a setting, indicates the type of [=display surface=] that
 838 |               is being captured.</p>
 839 | 
 840 | 
 841 |               <p>As a capability, the setting value MUST be the lone value
 842 |               present, rendering this property immutable from the application
 843 |               viewpoint.</p>
 844 | 
 845 | 
 846 |               <p>As a constraint, the value signals the application's
 847 |               preference of a particular [=display surface=] type to the user
 848 |               agent; the user agent MAY reorder the options offered to the user
 849 |               according to that preference. This constraint is ignored for all
 850 |               other purposes, and can therefore not cause any side effects
 851 |               (such as being the cause of
 852 |               <code>OverconstrainedError</code>).</p>
 853 |             </td>
 854 |           </tr>
 855 | 
 856 | 
 857 |           <tr id="def-constraint-logicalSurface">
 858 |             <td><dfn class="export">logicalSurface</dfn>
 859 |             </td>
 860 | 
 861 |             <td>{{boolean}}</td>
 862 | 
 863 |             <td>As a setting, a value of <code>true</code> indicates capture of
 864 |             a [=logical display surface=], whereas a value of
 865 |             <code>false</code> indicates a capture of a [=visible display
 866 |             surface=]. As a capability, this same value MUST be the lone value
 867 |             present, rendering this property immutable from the application
 868 |             viewpoint.</td>
 869 |           </tr>
 870 | 
 871 | 
 872 |           <tr id="def-constraint-cursor">
 873 |             <td><dfn class="export">cursor</dfn>
 874 |             </td>
 875 | 
 876 |             <td>{{DOMString}}</td>
 877 | 
 878 |             <td>This string is one of the members of
 879 |             {{CursorCaptureConstraint}}. As a setting, indicates if and when
 880 |             the cursor is included in the captured [=display surface=]. As a
 881 |             capability, the user agent MUST include only the set of values from
 882 |             {{CursorCaptureConstraint}} it is capable of supporting for this
 883 |             [=display surface=].</td>
 884 |           </tr>
 885 | 
 886 |           <tr id="def-constraint-pixel-ratio">
 887 |             <td><dfn class="export">screenPixelRatio</dfn>
 888 |             </td>
 889 | 
 890 |             <td>{{double}}</td>
 891 | 
 892 |             <td>As a setting, it is the result of dividing the size of a
 893 |             <a data-xref-type="css-value" data-xref-for="<length>" data-lt="px">CSS pixel</a>
 894 |             at a <a href="https://drafts.csswg.org/cssom-view/#page-zoom">page zoom</a>
 895 |             of 1.0 and using a
 896 |             <a href="https://drafts.csswg.org/cssom-view/#scale-factor">scale factor</a>
 897 |             of 1.0 by the vertical size of a pixel from the [=display surface=].
 898 |             It cannot be used as a constraint or capability.
 899 |             </td>
 900 |           </tr>
 901 |         </tbody>
 902 |       </table>
 903 | 
 904 | 
 905 |       <p>The following new and existing {{MediaStreamTrack}} <a data-cite=
 906 |       "GETUSERMEDIA#constrainable-properties">Constrainable Properties</a> are
 907 |       defined to apply to the user-selected audio sources, with the following
 908 |       behavior:</p>
 909 | 
 910 | 
 911 |       <table class="simple">
 912 |         <thead>
 913 |           <tr>
 914 |             <th>Property Name</th>
 915 | 
 916 |             <th>Type</th>
 917 | 
 918 |             <th>Behavior</th>
 919 |           </tr>
 920 |         </thead>
 921 | 
 922 | 
 923 |         <tbody>
 924 |           <tr id="def-constraint-restrictOwnAudio">
 925 |             <td><dfn class="export">restrictOwnAudio</dfn>
 926 |             </td>
 927 | 
 928 |             <td>{{boolean}}</td>
 929 | 
 930 |             <td>
 931 |               <p>As a setting, this value indicates whether or not the user
 932 |               agent is applying <a>own audio restriction</a> to the source.</p>
 933 | 
 934 | 
 935 |               <p>As a constraint, this property can be constrained resulting in
 936 |               a source with <a>own audio restriction</a> enabled or
 937 |               disabled.</p>
 938 | 
 939 | 
 940 |               <p>When <dfn>own audio restriction</dfn> is applied, the user
 941 |               agent MUST attempt to remove any audio from the audio being
 942 |               captured that was produced by the document that performed
 943 |               {{MediaDevices/getDisplayMedia}}. If the user agent is not able
 944 |               to remove the audio through processing it SHOULD remove the audio
 945 |               by excluding the document's audio from being captured. If this
 946 |               results in no audio being captured, the user agent MUST keep the
 947 |               track muted until it is able to capture audio again.</p>
 948 |             </td>
 949 |           </tr>
 950 | 
 951 | 
 952 |           <tr id="def-constraint-suppressLocalAudioPlayback">
 953 |             <td><dfn class="export">suppressLocalAudioPlayback</dfn>
 954 |             </td>
 955 | 
 956 |             <td>{{boolean}}</td>
 957 | 
 958 |             <td>
 959 |               <p>As a setting, this value indicates whether or not the
 960 |               application instructed the user agent to apply <a>local audio
 961 |               playback suppression</a> to the source.</p>
 962 | 
 963 | 
 964 |               <p>As a constraint, this value is only meaningful if the user
 965 |               selects capturing a [= display surface/browser=] [=display
 966 |               surface=]. In that case, a value of <code>true</code> indicates
 967 |               that the user agent SHOULD perform <a>local audio playback
 968 |               suppression</a> on the captured [= display surface/browser=]
 969 |               [=display surface=].</p>
 970 | 
 971 | 
 972 |               <p>When <dfn>local audio playback suppression</dfn> is applied,
 973 |               the user agent SHOULD stop relaying audio to the local speakers,
 974 |               but that audio MUST still be captured by any ongoing
 975 |               audio-capturing [=capture-sessions=]. This suppression MUST NOT
 976 |               be observable to the captured document. Furthermore, the
 977 |               capturing document may only observe whether it is applying
 978 |               <a>suppressLocalAudioPlayback</a>; not whether that suppression
 979 |               is having an effect (i.e. can't observe if the user is overriding
 980 |               this in the user agent).</p>
 981 | 
 982 | 
 983 |               <p>When a [= display surface/browser=] [=display surface=] is
 984 |               subject to multiple concurrent captures, <a>local audio playback
 985 |               suppression</a> SHOULD be applied as long as at least one active
 986 |               audio-capturing [=capture-session=] is constraining
 987 |               <a>suppressLocalAudioPlayback</a> to <code>true</code>.</p>
 988 |             </td>
 989 |           </tr>
 990 |         </tbody>
 991 |       </table>
 992 | 
 993 | 
 994 |       <p>When inherent properties of the underlying source of a user-selected
 995 |       <a>display surface</a> change, for example in response to the end-user
 996 |       resizing a captured window, and these changes render the capabilities
 997 |       and/or settings of one or more constrainable properties outdated, the
 998 |       user agent MUST [=queue a task=] on the [=user interaction task source=]
 999 |       to run the following step:</p>
1000 | 
1001 | 
1002 |       <ol>
1003 |         <li>
1004 |           <p>Update all affected constrainable properties at the same time.</p>
1005 | 
1006 | 
1007 |           <p>If this causes an "overconstrained" situation, then the user agent
1008 |           MUST ignore the culprit constraints for as long as they
1009 |           overconstrain. The user agent MUST NOT mute the track.</p>
1010 |         </li>
1011 |       </ol>
1012 | 
1013 | 
1014 |       <div class="note">
1015 |         <p>While min and exact constraints produce TypeError on
1016 |         getDisplayMedia(), this specification does not alter the
1017 |         track.applyConstraints() method. Therefore, they may instead produce
1018 |         OverconstrainedError or succeed depending on values, and therefore
1019 |         potentially be present to cause this "overconstrained" situation. The
1020 |         max constraint may also cause this, e.g. with aspectRatio. This spec
1021 |         considers these to be edge cases that aren't useful.</p>
1022 |       </div>
1023 | 
1024 | 
1025 |       <section>
1026 |         <h2>Downscaling and Frame Decimation</h2>
1027 | 
1028 | 
1029 |         <p>For the purposes of the [=SelectSettings=] algorithm, the user agent
1030 |         SHOULD consider all possible combinations of downscaled dimensions that
1031 |         preserve the aspect ratio of the original <a>display surface</a> (to
1032 |         the nearest pixel), and frame rates available through frame decimation,
1033 |         as available [= settings dictionaries =].</p>
1034 | 
1035 | 
1036 |         <p>The downscaling and decimation effects of constraints is then
1037 |         effectively governed by the [= fitness distance =] algorithm.</p>
1038 | 
1039 | 
1040 |         <p>The intent is for the user agent to produce output that is close to
1041 |         the ideal <code>width</code>, ideal <code>height</code>, and/or ideal
1042 |         <code>frameRate</code> when these are specified, while at all times
1043 |         preserving the aspect ratio of the original <a>display surface</a>.</p>
1044 | 
1045 | 
1046 |         <p>The user agent SHOULD downscale by the <a>source pixel ratio</a> by
1047 |         default, unless otherwise directed by applied constraints.</p>
1048 | 
1049 | 
1050 |         <p>The user agent MUST NOT crop the captured output.</p>
1051 | 
1052 | 
1053 |         <p>The user agent MUST NOT upscale the captured output, or create
1054 |         additional frames, except as needed to preserve high resolutions and
1055 |         frame rates in an aggregated <a>display surface</a>.</p>
1056 | 
1057 | 
1058 |         <div class="note">
1059 |           <p>The max constraint type lets a web application provide a maximum
1060 |           envelope for constrainable properties like width and height. This is
1061 |           helpful to limit extreme aspect ratios, should the end-user resize a
1062 |           [= display surface/window =] or [= display surface/browser =] surface
1063 |           to such an extreme while it is being captured.</p>
1064 |         </div>
1065 | 
1066 | 
1067 |         <p>For each constrainable property of positive numeric type in this
1068 |         specification, the user agent MUST establish a <dfn>floor value</dfn>,
1069 |         representing the smallest allowable value supported by the user agent
1070 |         regardless of source. This value MUST be constant and MUST be greater
1071 |         than <code>0</code>. The user agent is encouraged to support all values
1072 |         above the <a>floor value</a> regardless of source.</p>
1073 | 
1074 | 
1075 |         <div class="note">
1076 |           <p>The purpose of the <a>floor value</a> is to help user agents avoid
1077 |           failing {{MediaDevices/getDisplayMedia()}} with
1078 |           <code>OverconstrainedError</code> after the user has already been
1079 |           prompted, and avoid leaking information about the user's system.</p>
1080 |         </div>
1081 |       </section>
1082 | 
1083 | 
1084 |       <section>
1085 |         <h2><dfn>CaptureStartFocusBehavior</dfn>
1086 |         </h2>
1087 | 
1088 | 
1089 |         <p>Describes whether an application invoking
1090 |         {{CaptureController/setFocusBehavior()}} would like the user agent to
1091 |         focus the [=display surface=] associated with that
1092 |         {{CaptureController}}'s [=capture-session=].</p>
1093 | 
1094 |         <pre class="idl">
1095 |             enum CaptureStartFocusBehavior {
1096 |               "focus-capturing-application",
1097 |               "focus-captured-surface",
1098 |               "no-focus-change"
1099 |             };
1100 |           </pre>
1101 | 
1102 |         <table data-dfn-for="CaptureStartFocusBehavior" class="simple">
1103 |           <tbody>
1104 |             <tr>
1105 |               <th colspan="2">Enumeration description</th>
1106 |             </tr>
1107 | 
1108 | 
1109 |             <tr>
1110 |               <td style="white-space:nowrap"><dfn id=
1111 |               "idl-def-CaptureStartFocusBehavior.focus-capturing-application">focus-capturing-application</dfn>
1112 |               </td>
1113 | 
1114 |               <td>The application prefers to be focused.</td>
1115 |             </tr>
1116 | 
1117 | 
1118 |             <tr>
1119 |               <td style="white-space:nowrap"><dfn id=
1120 |               "idl-def-CaptureStartFocusBehavior.focus-captured-surface">focus-captured-surface</dfn>
1121 |               </td>
1122 | 
1123 |               <td>The application prefers that the [=display surface=]
1124 |               associated with this {{CaptureController}}'s [=capture-session=]
1125 |               be focused.</td>
1126 |             </tr>
1127 | 
1128 | 
1129 |             <tr>
1130 |               <td><dfn id=
1131 |               "idl-def-CaptureStartFocusBehavior.no-focus-change">no-focus-change</dfn>
1132 |               </td>
1133 | 
1134 |               <td>The application prefers that the user agent not change focus,
1135 |               leaving focus with whichever surface last had focus following the
1136 |               user's interaction with the user agent and/or operating
1137 |               system.</td>
1138 |             </tr>
1139 |           </tbody>
1140 |         </table>
1141 | 
1142 | 
1143 |         <div class="note">
1144 |           The Working Group is investigating the possibility of deprecating
1145 |           {{CaptureStartFocusBehavior/"no-focus-change"}}.
1146 |         </div>
1147 |       </section>
1148 | 
1149 | 
1150 |       <section>
1151 |         <h2><dfn>CaptureController</dfn>
1152 |         </h2>
1153 | 
1154 | 
1155 |         <p>A {{CaptureController}} object may be associated with a
1156 |         [=capture-session=]. It would be used to expose functionality that's
1157 |         associated with the [=capture-session=] itself, rather than with the
1158 |         call to {{MediaDevices/getDisplayMedia()}} or its resulting stream or
1159 |         tracks.</p>
1160 | 
1161 | 
1162 |         <p>Any given [=capture-session=] is associated with at most one
1163 |         {{CaptureController}}.</p>
1164 | 
1165 | 
1166 |         <p>At most one {{CaptureController}} is associated with any given
1167 |         [=capture-session=].</p>
1168 | 
1169 |         <pre class="idl">
1170 |             [Exposed=Window, SecureContext]
1171 |             interface CaptureController : EventTarget {
1172 |               constructor();
1173 |               undefined setFocusBehavior(CaptureStartFocusBehavior focusBehavior);
1174 |             };
1175 |           </pre>
1176 | 
1177 |         <div class="issue atrisk">
1178 |           <p>{{CaptureController}} does not yet define event handlers, so it is
1179 |           not required to inherit from {{EventTarget}}. This is for the benefit
1180 |           of future specifications that extend {{CaptureController}} with event
1181 |           handler attributes; if inheritance is not used, it can be
1182 |           removed.</p>
1183 |         </div>
1184 | 
1185 | 
1186 |         <dl data-link-for="CaptureController" data-dfn-for="CaptureController"
1187 |         class="methods">
1188 |           <dt><dfn>constructor</dfn>
1189 |           </dt>
1190 | 
1191 | 
1192 |           <dd>
1193 |             Create a new {{CaptureController}} object with the following
1194 |             internal slots:
1195 | 
1196 |             <table class="simple" data-dfn-for="CaptureController">
1197 |               <thead>
1198 |                 <tr>
1199 |                   <th>Internal Slot</th>
1200 | 
1201 |                   <th>Initial value</th>
1202 | 
1203 |                   <th>Description (<em>non-normative</em>)</th>
1204 |                 </tr>
1205 |               </thead>
1206 | 
1207 | 
1208 |               <tbody>
1209 |                 <tr>
1210 |                   <td><dfn class="attribute export">[[\IsBound]]</dfn>
1211 |                   </td>
1212 | 
1213 |                   <td><code>false</code>
1214 |                   </td>
1215 | 
1216 |                   <td>Whether an application has attempted to associate
1217 |                   [=this=] with a [=capture-session=].</td>
1218 |                 </tr>
1219 | 
1220 | 
1221 |                 <tr>
1222 |                   <td><dfn class="attribute export">[[\Source]]</dfn>
1223 |                   </td>
1224 | 
1225 |                   <td><code>null</code>
1226 |                   </td>
1227 | 
1228 |                   <td>The source of the associated [=capture-session=].</td>
1229 |                 </tr>
1230 | 
1231 | 
1232 |                 <tr>
1233 |                   <td><dfn class="attribute export">[[\DisplaySurfaceType]]</dfn>
1234 |                   </td>
1235 | 
1236 |                   <td><code>null</code>
1237 |                   </td>
1238 | 
1239 |                   <td>Once capture starts, this will be set to the type of the
1240 |                   captured [=display surface=].</td>
1241 |                 </tr>
1242 | 
1243 | 
1244 |                 <tr>
1245 |                   <td><dfn class="attribute export">[[\FocusChangeDisabled]]</dfn>
1246 |                   </td>
1247 | 
1248 |                   <td><code>false</code>
1249 |                   </td>
1250 | 
1251 |                   <td>Whether focus-change has been disabled by an external
1252 |                   event or a user agent consideration.</td>
1253 |                 </tr>
1254 | 
1255 | 
1256 |                 <tr>
1257 |                   <td><dfn class="attribute export">[[\FocusDecisionFinalized]]</dfn>
1258 |                   </td>
1259 | 
1260 |                   <td><code>false</code>
1261 |                   </td>
1262 | 
1263 |                   <td>Set to true when the focus decision is finalized.</td>
1264 |                 </tr>
1265 | 
1266 | 
1267 |                 <tr>
1268 |                   <td><dfn class="attribute export">[[\FocusBehavior]]</dfn>
1269 |                   </td>
1270 | 
1271 |                   <td><code>null</code>
1272 |                   </td>
1273 | 
1274 |                   <td>The focus behavior desired by the application.</td>
1275 |                 </tr>
1276 |               </tbody>
1277 |             </table>
1278 | 
1279 | 
1280 |             <p>The user agent MAY set
1281 |             {{CaptureController/[[FocusChangeDisabled]]}} to <code>true</code>
1282 |             at any moment based on its own logic.</p>
1283 |           </dd>
1284 | 
1285 | 
1286 |           <dt><dfn>setFocusBehavior</dfn>
1287 |           </dt>
1288 | 
1289 | 
1290 |           <dd>
1291 |             <p>Run the following steps:</p>
1292 | 
1293 | 
1294 |             <ol>
1295 |               <li>
1296 |                 <p>Let <var>focusBehavior</var> be the method's first
1297 |                 argument.</p>
1298 |               </li>
1299 | 
1300 | 
1301 |               <li>
1302 |                 <p>If [=this=].{{CaptureController/[[Source]]}} is
1303 |                 <code>null</code>, set
1304 |                 [=this=].{{CaptureController/[[FocusBehavior]]}} to
1305 |                 <var>focusBehavior</var> and abort these steps.</p>
1306 |               </li>
1307 | 
1308 | 
1309 |               <li>
1310 |                 <p>If [=this=].{{CaptureController/[[Source]]}} has been
1311 |                 <a data-cite="GETUSERMEDIA#source-stopped">stopped</a>,
1312 |                 [=exception/throw=] an "{{InvalidStateError}}"
1313 |                 {{DOMException}}.</p>
1314 |               </li>
1315 | 
1316 | 
1317 |               <li>
1318 |                 <p>If [=this=].{{CaptureController/[[DisplaySurfaceType]]}} is
1319 |                 neither {{DisplayCaptureSurfaceType/"browser"}} nor
1320 |                 {{DisplayCaptureSurfaceType/"window"}}, [=exception/throw=] an
1321 |                 "{{InvalidStateError}}" {{DOMException}}.</p>
1322 |               </li>
1323 | 
1324 | 
1325 |               <li>
1326 |                 <p>If [=this=].{{CaptureController/[[FocusDecisionFinalized]]}}
1327 |                 is <code>true</code>, [=exception/throw=] an
1328 |                 "{{InvalidStateError}}" {{DOMException}}.</p>
1329 |               </li>
1330 | 
1331 | 
1332 |               <li>
1333 |                 <p>Set [=this=].{{CaptureController/[[FocusBehavior]]}} to
1334 |                 <var>focusBehavior</var>.</p>
1335 |               </li>
1336 | 
1337 | 
1338 |               <li>
1339 |                 <p>Run the [=finalize focus decision algorithm=] on
1340 |                 [=this=].</p>
1341 |               </li>
1342 |             </ol>
1343 |           </dd>
1344 |         </dl>
1345 | 
1346 | 
1347 |         <p>The <dfn>finalize focus decision algorithm</dfn>, given a
1348 |         <var>controller</var>, consists of running the following steps:</p>
1349 | 
1350 | 
1351 |         <ol>
1352 |           <li>
1353 |             <p>If too much time has elapsed since the [=capture-session=]
1354 |             started, the user agent SHOULD set
1355 |             {{CaptureController/[[FocusDecisionFinalized]]}} to
1356 |             <code>true</code>. The timespan is left up to the user agent, but
1357 |             it is recommended that a value of one second be used.</p>
1358 |           </li>
1359 | 
1360 | 
1361 |           <li>
1362 |             <p>If
1363 |             <var>controller</var>.{{CaptureController/[[FocusDecisionFinalized]]}}
1364 |             is <code>true</code>, abort these steps.</p>
1365 |           </li>
1366 | 
1367 | 
1368 |           <li>
1369 |             <p>Set
1370 |             <var>controller</var>.{{CaptureController/[[FocusDecisionFinalized]]}}
1371 |             to <code>true</code>.</p>
1372 |           </li>
1373 | 
1374 | 
1375 |           <li>
1376 |             <p>If
1377 |             <var>controller</var>.{{CaptureController/[[FocusChangeDisabled]]}}
1378 |             is <code>true</code>, abort these steps.</p>
1379 |           </li>
1380 | 
1381 | 
1382 |           <li>
1383 |             <p>If
1384 |             <var>controller</var>.{{CaptureController/[[DisplaySurfaceType]]}}
1385 |             is neither {{DisplayCaptureSurfaceType/"browser"}} nor
1386 |             {{DisplayCaptureSurfaceType/"window"}}, abort these steps.</p>
1387 |           </li>
1388 | 
1389 | 
1390 |           <li>
1391 |             <p>Let <var>focusBehavior</var> be
1392 |             <var>controller</var>.{{CaptureController/[[FocusBehavior]]}}.</p>
1393 |           </li>
1394 | 
1395 | 
1396 |           <li>
1397 |             <p>Run the following steps [=in parallel=]:</p>
1398 | 
1399 | 
1400 |             <ol>
1401 |               <li>
1402 |                 <p>If <var>focusBehavior</var> is
1403 |                 {{CaptureStartFocusBehavior/"focus-capturing-application"}},
1404 |                 focus the [=display surface=] representing the capturing
1405 |                 document.</p>
1406 |               </li>
1407 | 
1408 | 
1409 |               <li>
1410 |                 <p>If <var>focusBehavior</var> is
1411 |                 {{CaptureStartFocusBehavior/"focus-captured-surface"}}, focus
1412 |                 the [=display surface=] referred to by
1413 |                 <var>controller</var>.{{CaptureController/[[Source]]}}.</p>
1414 |               </li>
1415 |             </ol>
1416 |           </li>
1417 |         </ol>
1418 |       </section>
1419 | 
1420 | 
1421 |       <section>
1422 |         <h2><dfn>SelfCapturePreferenceEnum</dfn>
1423 |         </h2>
1424 | 
1425 | 
1426 |         <p>Describes the different hints an application can provide about
1427 |         whether the [=display surface=] the application is in, should be among
1428 |         the choices offered to the user.</p>
1429 | 
1430 |         <pre class="idl">
1431 |             enum SelfCapturePreferenceEnum {
1432 |               "include",
1433 |               "exclude"
1434 |             };
1435 |           </pre>
1436 | 
1437 |         <table data-dfn-for="SelfCapturePreferenceEnum" class="simple">
1438 |           <thead>
1439 |             <tr>
1440 |               <th>Enum value</th>
1441 | 
1442 |               <th>Description</th>
1443 |             </tr>
1444 |           </thead>
1445 | 
1446 | 
1447 |           <tbody>
1448 |             <tr>
1449 |               <td><dfn id=
1450 |               "idl-def-SelfCapturePreferenceEnum.include">include</dfn>
1451 |               </td>
1452 | 
1453 |               <td>The application prefers the surface be included among the
1454 |               choices offered.</td>
1455 |             </tr>
1456 | 
1457 | 
1458 |             <tr>
1459 |               <td><dfn id=
1460 |               "idl-def-SelfCapturePreferenceEnum.exclude">exclude</dfn>
1461 |               </td>
1462 | 
1463 |               <td>The application prefers the surface be excluded from the
1464 |               choices offered.</td>
1465 |             </tr>
1466 |           </tbody>
1467 |         </table>
1468 |       </section>
1469 | 
1470 | 
1471 |       <section>
1472 |         <h2><dfn>SystemAudioPreferenceEnum</dfn>
1473 |         </h2>
1474 | 
1475 | 
1476 |         <p>Describes whether an application invoking
1477 |         {{MediaDevices/getDisplayMedia()}} would like the user agent to include
1478 |         system audio among the audio sources offered to the user for
1479 |         [=display surface/monitor=] [=display surfaces=]. Does not apply to any
1480 |         other type of [=display surface=].
1481 | 
1482 |         <pre class="idl">
1483 |             enum SystemAudioPreferenceEnum {
1484 |               "include",
1485 |               "exclude"
1486 |             };
1487 |           </pre>
1488 | 
1489 |         <table data-dfn-for="SystemAudioPreferenceEnum" class="simple">
1490 |           <tbody>
1491 |             <tr>
1492 |               <th colspan="2">Enumeration description</th>
1493 |             </tr>
1494 | 
1495 | 
1496 |             <tr>
1497 |               <td><dfn id=
1498 |               "idl-def-SystemAudioPreferenceEnum.include">include</dfn>
1499 |               </td>
1500 | 
1501 |               <td>The application prefers that options to share system audio be
1502 |               offered to the user for [=display surface/monitor=] [=display
1503 |               surfaces=].</td>
1504 |             </tr>
1505 | 
1506 | 
1507 |             <tr>
1508 |               <td><dfn id=
1509 |               "idl-def-SystemAudioPreferenceEnum.exclude">exclude</dfn>
1510 |               </td>
1511 | 
1512 |               <td>The application prefers that options to share system audio
1513 |               not be offered to the user for [=display surface/monitor=]
1514 |               [=display surfaces=].</td>
1515 |             </tr>
1516 |           </tbody>
1517 |         </table>
1518 |       </section>
1519 | 
1520 | 
1521 |       <section>
1522 |         <h2><dfn>WindowAudioPreferenceEnum</dfn>
1523 |         </h2>
1524 | 
1525 | 
1526 |         <p>Describes whether an application invoking
1527 |         {{MediaDevices/getDisplayMedia()}} would like the user agent to include
1528 |         window or system audio among the audio sources offered to the user for
1529 |         [=display surface/window=] [=display surfaces=].</p>
1530 | 
1531 | 
1532 |         <pre class="idl">
1533 |             enum WindowAudioPreferenceEnum {
1534 |               "system",
1535 |               "window",
1536 |               "exclude"
1537 |             };
1538 |         </pre>
1539 | 
1540 |         <table data-dfn-for="WindowAudioPreferenceEnum" class="simple">
1541 |           <tbody>
1542 |             <tr>
1543 |               <th colspan="2">Enumeration description</th>
1544 |             </tr>
1545 | 
1546 | 
1547 |             <tr>
1548 |               <td><dfn id=
1549 |               "idl-def-WindowAudioPreferenceEnum.system">system</dfn>
1550 |               </td>
1551 | 
1552 |               <td>The application prefers that options to share system audio be
1553 |               offered to the user for [=display surface/window=] [=display
1554 |               surfaces=].</td>
1555 |             </tr>
1556 | 
1557 | 
1558 |             <tr>
1559 |               <td><dfn id=
1560 |               "idl-def-WindowAudioPreferenceEnum.window">window</dfn>
1561 |               </td>
1562 | 
1563 |               <td>The application prefers that options to share window audio be
1564 |               offered to the user for [=display surface/window=] [=display
1565 |               surfaces=].</td>
1566 |             </tr>
1567 | 
1568 |             <tr>
1569 |               <td><dfn id=
1570 |               "idl-def-WindowAudioPreferenceEnum.exclude">exclude</dfn>
1571 |               </td>
1572 | 
1573 |               <td>The application prefers that options to share audio not be
1574 |               offered to the user for [=display surface/window=] [=display
1575 |               surfaces=].</td>
1576 |             </tr>
1577 |           </tbody>
1578 |         </table>
1579 |       </section>
1580 | 
1581 | 
1582 |       <section>
1583 |         <h2><dfn>SurfaceSwitchingPreferenceEnum</dfn>
1584 |         </h2>
1585 | 
1586 | 
1587 |         <p>Describes whether an application invoking
1588 |         {{MediaDevices/getDisplayMedia()}} would like the user agent to offer
1589 |         the user an option to dynamically switch the source [=display surface=]
1590 |         during the capture.</p>
1591 | 
1592 |         <pre class="idl">
1593 |             enum SurfaceSwitchingPreferenceEnum {
1594 |               "include",
1595 |               "exclude"
1596 |             };
1597 |           </pre>
1598 | 
1599 |         <table data-dfn-for="SurfaceSwitchingPreferenceEnum" class="simple">
1600 |           <tbody>
1601 |             <tr>
1602 |               <th colspan="2">Enumeration description</th>
1603 |             </tr>
1604 | 
1605 | 
1606 |             <tr>
1607 |               <td><dfn id=
1608 |               "idl-def-SurfaceSwitchingPreferenceEnum.include">include</dfn>
1609 |               </td>
1610 | 
1611 |               <td>The application prefers that an option to dynamically switch
1612 |               the source [=display surface=] during the capture be offered to
1613 |               the user.</td>
1614 |             </tr>
1615 | 
1616 | 
1617 |             <tr>
1618 |               <td><dfn id=
1619 |               "idl-def-SurfaceSwitchingPreferenceEnum.exclude">exclude</dfn>
1620 |               </td>
1621 | 
1622 |               <td>The application prefers that an option to dynamically switch
1623 |               the source [=display surface=] during the capture NOT be offered
1624 |               to the user.</td>
1625 |             </tr>
1626 |           </tbody>
1627 |         </table>
1628 |       </section>
1629 | 
1630 | 
1631 |       <section>
1632 |         <h2><dfn>MonitorTypeSurfacesEnum</dfn>
1633 |         </h2>
1634 | 
1635 | 
1636 |         <p>Describes whether the application would like the user agent to offer
1637 |         the user the option to choose [=display surfaces=] whose type is
1638 |         [=display surface/monitor=].</p>
1639 | 
1640 |         <pre class="idl">
1641 |             enum MonitorTypeSurfacesEnum {
1642 |               "include",
1643 |               "exclude"
1644 |             };
1645 |           </pre>
1646 | 
1647 |         <table data-dfn-for="MonitorTypeSurfacesEnum" class="simple">
1648 |           <tbody>
1649 |             <tr>
1650 |               <th colspan="2">Enumeration description</th>
1651 |             </tr>
1652 | 
1653 | 
1654 |             <tr>
1655 |               <td><dfn id=
1656 |               "idl-def-MonitorTypeSurfacesEnum.include">include</dfn>
1657 |               </td>
1658 | 
1659 |               <td>The application prefers that the [=display surfaces=]
1660 |               presented to the user include those of type [=display
1661 |               surface/monitor=].</td>
1662 |             </tr>
1663 | 
1664 | 
1665 |             <tr>
1666 |               <td><dfn id=
1667 |               "idl-def-MonitorTypeSurfacesEnum.exclude">exclude</dfn>
1668 |               </td>
1669 | 
1670 |               <td>The application prefers that the [=display surfaces=]
1671 |               presented to the user exclude those of type [=display
1672 |               surface/monitor=].</td>
1673 |             </tr>
1674 |           </tbody>
1675 |         </table>
1676 |       </section>
1677 | 
1678 | 
1679 |       <section>
1680 |         <h2>DisplayMediaStreamOptions</h2>
1681 | 
1682 | 
1683 |         <p>The <dfn>DisplayMediaStreamOptions</dfn> dictionary is used to
1684 |         instruct the user agent what sort of {{MediaStreamTrack}}s may be
1685 |         included in the {{MediaStream}} returned by
1686 |         {{MediaDevices/getDisplayMedia}}.</p>
1687 | 
1688 | 
1689 |         <div>
1690 |           <pre class="idl">
1691 | dictionary DisplayMediaStreamOptions {
1692 |   (boolean or MediaTrackConstraints) video = true;
1693 |   (boolean or MediaTrackConstraints) audio = false;
1694 |   CaptureController controller;
1695 |   SelfCapturePreferenceEnum selfBrowserSurface;
1696 |   SystemAudioPreferenceEnum systemAudio;
1697 |   WindowAudioPreferenceEnum windowAudio;
1698 |   SurfaceSwitchingPreferenceEnum surfaceSwitching;
1699 |   MonitorTypeSurfacesEnum monitorTypeSurfaces;
1700 | };</pre>
1701 | 
1702 |           <section>
1703 |             <h2>Dictionary <a class="idlType">DisplayMediaStreamOptions</a>
1704 |             Members</h2>
1705 | 
1706 | 
1707 |             <dl data-link-for="DisplayMediaStreamOptions" data-dfn-for=
1708 |             "DisplayMediaStreamOptions" class="dictionary-members">
1709 |               <dt><dfn><code>video</code></dfn> of type <code>(boolean or
1710 |               {{MediaTrackConstraints}})</code>, defaulting to
1711 |               <code>true</code></dt>
1712 | 
1713 | 
1714 |               <dd>
1715 |                 <p>If <code>true</code>, it requests that the returned
1716 |                 {{MediaStream}} contain a video track. If a
1717 |                 <code>Constraints</code> structure is provided, it further
1718 |                 specifies desired processing options to be applied to the video
1719 |                 track rendition of the display surface chosen by the user. If
1720 |                 <code>false</code>, the request will be [=rejected=] with a
1721 |                 {{TypeError}}, as per the <a href=
1722 |                 "#dom-mediadevices-getdisplaymedia">getDisplayMedia
1723 |                 algorithm</a>.</p>
1724 |               </dd>
1725 | 
1726 | 
1727 |               <dt><dfn><code>audio</code></dfn> of type <code>(boolean or
1728 |               {{MediaTrackConstraints}})</code>, defaulting to
1729 |               <code>false</code></dt>
1730 | 
1731 | 
1732 |               <dd>
1733 |                 <p>If <code>true</code>, it signals an interest that the
1734 |                 returned {{MediaStream}} contain an audio track, if supported
1735 |                 and audio is available for display surface chosen by the user.
1736 |                 If a <code>Constraints</code> structure is provided, it further
1737 |                 specifies desired processing options to be applied to the audio
1738 |                 track. If <code>false</code>, the {{MediaStream}} will not
1739 |                 contain an audio track.</p>
1740 |               </dd>
1741 | 
1742 | 
1743 |               <dt><dfn><code>controller</code></dfn> of type
1744 |               <code>{{CaptureController}}</code></dt>
1745 | 
1746 | 
1747 |               <dd>
1748 |                 <p>If present, this {{CaptureController}} object will be
1749 |                 associated with the [=capture-session=]. Through the methods
1750 |                 exposed on this object, the [=capture-session=] can be
1751 |                 manipulated.</p>
1752 |               </dd>
1753 | 
1754 | 
1755 |               <dt><dfn><code>selfBrowserSurface</code></dfn> of type
1756 |               {{SelfCapturePreferenceEnum}}</dt>
1757 | 
1758 | 
1759 |               <dd>If present, signals application preference for whether the
1760 |               [=display surface/browser=] [=display surface=] which is
1761 |               associated with [=this=]'s [=relevant global object=]'s
1762 |               [=associated Document=]'s [=top-level browsing context=], should
1763 |               be among the choices offered to the user. The user agent MAY
1764 |               ignore this hint.</dd>
1765 | 
1766 | 
1767 |               <dt><dfn><code>systemAudio</code></dfn> of type
1768 |               {{SystemAudioPreferenceEnum}}</dt>
1769 | 
1770 | 
1771 |               <dd>If present, signals whether the application would like system
1772 |               audio to be included among the possible audio sources offered to
1773 |               the user for [=display surface/monitor=] [=display surfaces=]. The
1774 |               user agent MAY ignore this hint.</dd>
1775 | 
1776 | 
1777 |               <dt><dfn><code>windowAudio</code></dfn> of type
1778 |               {{WindowAudioPreferenceEnum}}</dt>
1779 | 
1780 | 
1781 |               <dd>If present, signals whether the application would like window
1782 |               or system audio among the possible audio sources offered to the
1783 |               user for [=display surface/window=] [=display surfaces=]. The
1784 |               user agent MAY ignore this hint.</dd>
1785 | 
1786 | 
1787 |               <dt><dfn><code>surfaceSwitching</code></dfn> of type
1788 |               {{SurfaceSwitchingPreferenceEnum}}</dt>
1789 | 
1790 | 
1791 |               <dd>If present, signals whether the application would like the
1792 |               user agent to offer the user an option to dynamically switch the
1793 |               captured [=display surface=]. The user agent MAY ignore this
1794 |               hint.</dd>
1795 | 
1796 | 
1797 |               <dt><dfn><code>monitorTypeSurfaces</code></dfn> of type
1798 |               {{MonitorTypeSurfacesEnum}}</dt>
1799 | 
1800 | 
1801 |               <dd>
1802 |                 <p>If present, signals whether the application would like the
1803 |                 user agent to include [=display surfaces=] whose type is
1804 |                 [=display surface/monitor=] among the choices offered to the
1805 |                 user. The user agent MAY ignore this hint.</p>
1806 | 
1807 | 
1808 |                 <div class="note">
1809 |                   <p>The user agent may still offer to the user the option to
1810 |                   capture [=display surfaces=] of type [=display
1811 |                   surface/monitor=]. Applications are therefore encouraged to
1812 |                   still check the {{MediaTrackSettings/displaySurface}} setting
1813 |                   of the tracks they receive.</p>
1814 |                 </div>
1815 |               </dd>
1816 |             </dl>
1817 |           </section>
1818 |         </div>
1819 |       </section>
1820 | 
1821 | 
1822 |       <section>
1823 |         <h2>Extensions to {{MediaTrackSupportedConstraints}}</h2>
1824 | 
1825 | 
1826 |         <p>{{MediaTrackSupportedConstraints}} is extended here with the list of
1827 |         constraints that a user agent recognizes.</p>
1828 | 
1829 |         <pre class="idl">partial dictionary MediaTrackSupportedConstraints {
1830 |   boolean displaySurface = true;
1831 |   boolean logicalSurface = true;
1832 |   boolean cursor = true;
1833 |   boolean restrictOwnAudio = true;
1834 |   boolean suppressLocalAudioPlayback = true;
1835 | };</pre>
1836 | 
1837 |         <dl data-dfn-for="MediaTrackSupportedConstraints" class=
1838 |         "dictionary-members">
1839 |           <dt><dfn>displaySurface</dfn> of type {{boolean}}, defaulting to
1840 |           <code>true</code></dt>
1841 | 
1842 | 
1843 |           <dd>
1844 |             <p>Whether {{displaySurface}} constraint is recognized.</p>
1845 |           </dd>
1846 | 
1847 | 
1848 |           <dt><dfn><code>logicalSurface</code></dfn> of type {{boolean}},
1849 |           defaulting to <code>true</code></dt>
1850 | 
1851 | 
1852 |           <dd>
1853 |             <p>Whether {{logicalSurface}} constraint is recognized.</p>
1854 |           </dd>
1855 | 
1856 | 
1857 |           <dt><dfn>cursor</dfn> of type {{boolean}}, defaulting to
1858 |           <code>true</code></dt>
1859 | 
1860 | 
1861 |           <dd>
1862 |             <p>Whether {{cursor}} constraint is recognized.</p>
1863 |           </dd>
1864 | 
1865 | 
1866 |           <dt><dfn>restrictOwnAudio</dfn> of type {{boolean}}, defaulting to
1867 |           <code>true</code></dt>
1868 | 
1869 | 
1870 |           <dd>
1871 |             <p>Whether {{restrictOwnAudio}} constraint is recognized.</p>
1872 |           </dd>
1873 | 
1874 | 
1875 |           <dt><dfn>suppressLocalAudioPlayback</dfn> of type {{boolean}},
1876 |           defaulting to <code>true</code></dt>
1877 | 
1878 | 
1879 |           <dd>
1880 |             <p>Whether {{suppressLocalAudioPlayback}} constraint is
1881 |             recognized.</p>
1882 |           </dd>
1883 |         </dl>
1884 |       </section>
1885 | 
1886 | 
1887 |       <section>
1888 |         <h2>Extensions to {{MediaTrackConstraintSet}}</h2>
1889 | 
1890 | 
1891 |         <p>{{MediaTrackConstraintSet}} is used for reading the current status
1892 |         of constraints.</p>
1893 | 
1894 |         <pre class="idl">partial dictionary MediaTrackConstraintSet {
1895 |   ConstrainDOMString displaySurface;
1896 |   ConstrainBoolean logicalSurface;
1897 |   ConstrainDOMString cursor;
1898 |   ConstrainBoolean restrictOwnAudio;
1899 |   ConstrainBoolean suppressLocalAudioPlayback;
1900 | };</pre>
1901 | 
1902 |         <dl data-dfn-for="MediaTrackConstraintSet" class="dictionary-members">
1903 |           <dt><dfn><code>displaySurface</code></dfn> of type
1904 |           {{ConstrainDOMString}}</dt>
1905 | 
1906 | 
1907 |           <dd>
1908 |             <p>The type of [=display surface=] that is being captured. This
1909 |             assumes values from the {{DisplayCaptureSurfaceType}}
1910 |             enumeration.</p>
1911 |           </dd>
1912 | 
1913 | 
1914 |           <dt><dfn>logicalSurface</dfn> of type {{ConstrainBoolean}}</dt>
1915 | 
1916 | 
1917 |           <dd>
1918 |             <p>A value of <code>true</code> indicates capture of a [=logical
1919 |             display surface=]; a value of <code>false</code> indicates a
1920 |             capture of a [=visible display surface=].</p>
1921 |           </dd>
1922 | 
1923 | 
1924 |           <dt><dfn>cursor</dfn> of type {{ConstrainDOMString}}</dt>
1925 | 
1926 | 
1927 |           <dd>
1928 |             <p>Assumes values from the {{CursorCaptureConstraint}} enumeration
1929 |             that determines if and when the cursor is included in the captured
1930 |             display surface.</p>
1931 |           </dd>
1932 | 
1933 | 
1934 |           <dt><dfn>restrictOwnAudio</dfn> of type {{ConstrainBoolean}}</dt>
1935 | 
1936 | 
1937 |           <dd>
1938 |             <p>This constraint is only applicable to audio tracks. See
1939 |             {{restrictOwnAudio}}.</p>
1940 |           </dd>
1941 | 
1942 | 
1943 |           <dt><dfn>suppressLocalAudioPlayback</dfn> of type
1944 |           {{ConstrainBoolean}}</dt>
1945 | 
1946 | 
1947 |           <dd>
1948 |             <p>This constraint is only applicable to audio tracks. See
1949 |             {{suppressLocalAudioPlayback}}.</p>
1950 |           </dd>
1951 |         </dl>
1952 |       </section>
1953 | 
1954 | 
1955 |       <section>
1956 |         <h2>Extensions to {{MediaTrackSettings}}</h2>
1957 | 
1958 | 
1959 |         <p>When the {{MediaStreamTrack/getSettings()}} method is invoked on a
1960 |         video stream track, the user agent must return the extended
1961 |         {{MediaTrackSettings}} dictionary, representing the current status of
1962 |         the underlying user agent.</p>
1963 | 
1964 |         <pre class="idl">partial dictionary MediaTrackSettings {
1965 |   DOMString displaySurface;
1966 |   boolean logicalSurface;
1967 |   DOMString cursor;
1968 |   boolean restrictOwnAudio;
1969 |   boolean suppressLocalAudioPlayback;
1970 |   double screenPixelRatio;
1971 | };</pre>
1972 | 
1973 |         <dl data-link-for="MediaTrackSettings" data-dfn-for=
1974 |         "MediaTrackSettings" class="dictionary-members">
1975 |           <dt><dfn>displaySurface</dfn> of type {{DOMString}}</dt>
1976 | 
1977 | 
1978 |           <dd>
1979 |             <p>The type of [=display surface=] that is being captured. This
1980 |             assumes values from the {{DisplayCaptureSurfaceType}}
1981 |             enumeration.</p>
1982 |           </dd>
1983 | 
1984 | 
1985 |           <dt><dfn>logicalSurface</dfn> of type {{boolean}}</dt>
1986 | 
1987 | 
1988 |           <dd>
1989 |             <p>A value of <code>true</code> indicates capture of a <a>logical
1990 |             display surface</a>; a value of <code>false</code> indicates a
1991 |             capture capture of a <a>visible display surface</a>.</p>
1992 |           </dd>
1993 | 
1994 | 
1995 |           <dt><dfn>cursor</dfn> of type {{DOMString}}</dt>
1996 | 
1997 | 
1998 |           <dd>
1999 |             <p>Assumes values from the {{CursorCaptureConstraint}} enumeration
2000 |             that determines if and when the cursor is included in the captured
2001 |             display surface.</p>
2002 |           </dd>
2003 | 
2004 | 
2005 |           <dt><dfn>restrictOwnAudio</dfn> of type {{boolean}}</dt>
2006 | 
2007 | 
2008 |           <dd>
2009 |             <p>Indicates whether the <a href=
2010 |             "#dfn-restrictownaudio">restrictOwnAudio</a> constraint is applied
2011 |             (<code>true</code>) or not (<code>false</code>).</p>
2012 |           </dd>
2013 | 
2014 | 
2015 |           <dt><dfn>suppressLocalAudioPlayback</dfn> of type {{boolean}}</dt>
2016 | 
2017 | 
2018 |           <dd>
2019 |             <p>Indicates whether or not the application instructed the user
2020 |             agent to apply [=local audio playback suppression=] to the
2021 |             source.</p>
2022 |           </dd>
2023 | 
2024 | 
2025 |           <dt><dfn>screenPixelRatio</dfn> of type {{double}}</dt>
2026 | 
2027 | 
2028 |           <dd>
2029 |             <p>The screen pixel ratio of of the [=display surface=] being captured.</p>
2030 |           </dd>
2031 |         </dl>
2032 |       </section>
2033 | 
2034 | 
2035 |       <section>
2036 |         <h2>Extensions to {{MediaTrackCapabilities}}</h2>
2037 | 
2038 | 
2039 |         <p>When the {{MediaStreamTrack/getCapabilities()}} method is invoked on
2040 |         a video stream track, the user agent must return the extended
2041 |         {{MediaTrackCapabilities}} dictionary, representing the capabilities of
2042 |         the underlying user agent.</p>
2043 | 
2044 |         <pre class="idl">partial dictionary MediaTrackCapabilities {
2045 |   DOMString displaySurface;
2046 |   boolean logicalSurface;
2047 |   sequence&lt;DOMString&gt; cursor;
2048 | };</pre>
2049 | 
2050 |         <dl data-link-for="MediaTrackCapabilities" data-dfn-for=
2051 |         "MediaTrackCapabilities" class="dictionary-members">
2052 |           <dt><dfn>displaySurface</dfn> of type {{DOMString}}</dt>
2053 | 
2054 | 
2055 |           <dd>
2056 |             <p>MUST be the same value as is returned by
2057 |             {{MediaStreamTrack/getSettings()}}, rendering this property
2058 |             immutable from the application's viewpoint.</p>
2059 |           </dd>
2060 | 
2061 | 
2062 |           <dt><dfn>logicalSurface</dfn> of type {{boolean}}</dt>
2063 | 
2064 | 
2065 |           <dd>
2066 |             <p>MUST be the same value as is returned by
2067 |             {{MediaStreamTrack/getSettings()}}, rendering this property
2068 |             immutable from the application's viewpoint.</p>
2069 |           </dd>
2070 | 
2071 | 
2072 |           <dt><dfn>cursor</dfn> of type sequence&lt;DOMString&gt;</dt>
2073 | 
2074 | 
2075 |           <dd>
2076 |             <p>MUST consist of exactly the set of values from
2077 |             {{CursorCaptureConstraint}} that the user agent is capable of
2078 |             supporting for this track.</p>
2079 |           </dd>
2080 |         </dl>
2081 |       </section>
2082 | 
2083 | 
2084 |       <section>
2085 |         <h2><dfn>DisplayCaptureSurfaceType</dfn>
2086 |         </h2>
2087 | 
2088 | 
2089 |         <p>The {{DisplayCaptureSurfaceType}} enumeration describes the
2090 |         different types of display surface.</p>
2091 | 
2092 |         <pre class="idl">enum DisplayCaptureSurfaceType {
2093 |   "monitor",
2094 |   "window",
2095 |   "browser"
2096 | };</pre>
2097 | 
2098 |         <table data-dfn-for="DisplayCaptureSurfaceType" class="simple">
2099 |           <thead>
2100 |             <tr>
2101 |               <th>Enum value</th>
2102 | 
2103 |               <th>Description</th>
2104 |             </tr>
2105 |           </thead>
2106 | 
2107 | 
2108 |           <tbody>
2109 |             <tr>
2110 |               <td><dfn id=
2111 |               "idl-def-DisplayCaptureSurfaceType.monitor">monitor</dfn>
2112 |               </td>
2113 | 
2114 |               <td>a [=display surface/monitor=] [=display surface=], physical
2115 |               display, or collection of physical displays</td>
2116 |             </tr>
2117 | 
2118 | 
2119 |             <tr>
2120 |               <td><dfn id=
2121 |               "idl-def-DisplayCaptureSurfaceType.window">window</dfn>
2122 |               </td>
2123 | 
2124 |               <td>a [= display surface/window =] [=display surface=], or single
2125 |               application window</td>
2126 |             </tr>
2127 | 
2128 | 
2129 |             <tr>
2130 |               <td><dfn id=
2131 |               "idl-def-DisplayCaptureSurfaceType.browser">browser</dfn>
2132 |               </td>
2133 | 
2134 |               <td>a [=display surface/browser=] [=display surface=], or single
2135 |               browser window</td>
2136 |             </tr>
2137 |           </tbody>
2138 |         </table>
2139 |       </section>
2140 | 
2141 | 
2142 |       <section>
2143 |         <h2><dfn>CursorCaptureConstraint</dfn>
2144 |         </h2>
2145 | 
2146 | 
2147 |         <p>The {{CursorCaptureConstraint}} enumerates the conditions under
2148 |         which the cursor is captured.</p>
2149 | 
2150 |         <pre class="idl">enum CursorCaptureConstraint {
2151 |   "never",
2152 |   "always",
2153 |   "motion"
2154 | };</pre>
2155 | 
2156 |         <table data-dfn-for="CursorCaptureConstraint" class="simple">
2157 |           <thead>
2158 |             <tr>
2159 |               <th>Enum value</th>
2160 | 
2161 |               <th>Description</th>
2162 |             </tr>
2163 |           </thead>
2164 | 
2165 | 
2166 |           <tbody>
2167 |             <tr>
2168 |               <td><dfn id="idl-def-CursorCaptureConstraint.never">never</dfn>
2169 |               </td>
2170 | 
2171 |               <td>a {{CursorCaptureConstraint/"never"}} cursor capture
2172 |               constraint omits the cursor from the captured display
2173 |               surface.</td>
2174 |             </tr>
2175 | 
2176 | 
2177 |             <tr>
2178 |               <td><dfn id="idl-def-CursorCaptureConstraint.always">always</dfn>
2179 |               </td>
2180 | 
2181 |               <td>a {{CursorCaptureConstraint/"always"}} cursor capture
2182 |               constraint includes the cursor in the captured display
2183 |               surface.</td>
2184 |             </tr>
2185 | 
2186 | 
2187 |             <tr>
2188 |               <td><dfn id="idl-def-CursorCaptureConstraint.motion">motion</dfn>
2189 |               </td>
2190 | 
2191 |               <td>
2192 |                 a {{CursorCaptureConstraint/"motion"}} cursor capture
2193 |                 constraint includes the cursor in the captured display surface
2194 |                 when the cursor/pointer is moved. The captured cursor is
2195 |                 removed when there is no further movement of the pointer/cursor
2196 |                 for certain period of time, as determined by the <a>user
2197 |                 agent</a>.
2198 |               </td>
2199 |             </tr>
2200 |           </tbody>
2201 |         </table>
2202 |       </section>
2203 |     </section>
2204 | 
2205 | 
2206 |     <section>
2207 |       <h2 id="deviceId">Device Identifiers</h2>
2208 | 
2209 | 
2210 |       <p>Each potential source of capture is treated by this API as a discrete
2211 |       media source. However, display capture sources MUST NOT be enumerated by
2212 |       {{MediaDevices/enumerateDevices()}}, since this would reveal too much
2213 |       information about the host system.</p>
2214 | 
2215 | 
2216 |       <p>Display capture sources therefore cannot be selected with the
2217 |       {{MediaTrackSupportedConstraints/deviceId}} constraint, since their
2218 |       {{MediaDeviceInfo/deviceId}}s are not exposed.</p>
2219 | 
2220 | 
2221 |       <div class="note">
2222 |         <p>This is not to be confused with the stable and private id of the
2223 |         same name used in algorithms to implement privacy indicators.</p>
2224 |       </div>
2225 |     </section>
2226 |   </section>
2227 | 
2228 | 
2229 |   <section data-cite="permissions">
2230 |     <h1 id="permissions-intergration">Permissions Integration</h1>
2231 | 
2232 | 
2233 |     <p><cite>Screen Capture</cite> is a [=powerful feature=] which is
2234 |     identified by the [=powerful feature/name=] "display-capture", requiring
2235 |     [=express permission=] to be used.</p>
2236 | 
2237 | 
2238 |     <p>As required for integration with the [[[Permissions]]] specification,
2239 |     this specification defines the following:</p>
2240 | 
2241 | 
2242 |     <dl>
2243 |       <dt>[=powerful feature/permission state constraints=]</dt>
2244 | 
2245 | 
2246 |       <dd>
2247 |         Valid values for this descriptor's <a>permission state</a> are
2248 |         {{PermissionState/"prompt"}} and {{PermissionState/"denied"}}. The user
2249 |         agent MUST NOT ever set this descriptor's <a>permission state</a> to
2250 |         {{PermissionState/"granted"}}.
2251 |       </dd>
2252 |     </dl>
2253 |   </section>
2254 | 
2255 | 
2256 |   <section>
2257 |     <h1 id="feature-policy-integration">Permissions Policy Integration</h1>
2258 | 
2259 | 
2260 |     <p>This specification defines a [=policy-controlled feature=] identified by
2261 |     the string <dfn class=
2262 |     "permission export"><code>"display-capture"</code></dfn>. Its
2263 |     [=policy-controlled feature/default allowlist=] is <code>"self"</code>.</p>
2264 | 
2265 | 
2266 |     <div class="note">
2267 |       <p>A [=document=]'s [=Document/permissions policy=] determines whether
2268 |       any content in that document is allowed to use
2269 |       {{MediaDevices/getDisplayMedia}}. If disabled in any document, no content
2270 |       in the document will be [=allowed to use=]
2271 |       {{MediaDevices/getDisplayMedia}}. This is enforced by the [=prompt the
2272 |       user to choose=] algorithm.</p>
2273 |     </div>
2274 |   </section>
2275 | 
2276 | 
2277 |   <section>
2278 |     <h1>Privacy Indicator Requirements</h1>
2279 | 
2280 | 
2281 |     <p>This specification extends the <a data-cite=
2282 |     "GETUSERMEDIA#privacy-indicator-requirements">Privacy Indicator
2283 |     Requirements</a> of {{MediaDevices/getUserMedia()}} to include
2284 |     {{MediaDevices/getDisplayMedia}}.</p>
2285 | 
2286 | 
2287 |     <p>References in this specification to [[\devicesLiveMap]],
2288 |     [[\devicesAccessibleMap]], and [[\kindsAccessibleMap]] refer to the
2289 |     definitions already created to support Privacy Indicator Requirements for
2290 |     {{MediaDevices/getUserMedia()}}.</p>
2291 | 
2292 | 
2293 |     <p>For each <var>kind</var> of device that {{MediaDevices/getDisplayMedia}}
2294 |     exposes, using a stable and private id for the device, <var>deviceId</var>,
2295 |     set <var>kind</var> to <code>"Display"</code> + <var>kind</var>, and do the
2296 |     following:</p>
2297 | 
2298 | 
2299 |     <ul>
2300 |       <li>Define <var>any&lt;kind&gt;Accessible</var> (e.g.
2301 |       <var>anyDisplayVideoAccessible</var>) as the logical OR of the
2302 |       [[\kindsAccessibleMap]]<var>[kind]</var> value and all the
2303 |       [[\devicesAccessibleMap]]<var>[deviceId]</var> values for devices of that
2304 |       kind, and initialize all values to <code>false</code>.</li>
2305 | 
2306 | 
2307 |       <li>Define <var>any&lt;kind&gt;Accessible</var> (e.g.
2308 |       <var>anyDisplayVideoAccessible</var>) as the logical OR of the
2309 |       [[\kindsAccessibleMap]]<var>[kind]</var> value and all the
2310 |       [[\devicesAccessibleMap]]<var>[deviceId]</var> values for devices of that
2311 |       kind, and initialize all values to <code>false</code>.</li>
2312 | 
2313 | 
2314 |       <li>Define any<var>&lt;kind&gt;Live</var> (e.g.
2315 |       <var>anyDisplayVideoLive</var>) to be the logical OR of all the
2316 |       [[\devicesLiveMap]]<var>[deviceId]</var> values for devices of that
2317 |       kind.</li>
2318 |     </ul>
2319 | 
2320 | 
2321 |     <p>Then, given the new definitions above, the requirements on the user
2322 |     agent are those specified in <a data-cite=
2323 |     "GETUSERMEDIA#privacy-indicator-requirements">Privacy Indicator
2324 |     Requirements</a> of {{MediaDevices/getUserMedia()}}.</p>
2325 | 
2326 | 
2327 |     <div class="note">
2328 |       <p>Even though there's a single permission descriptor for
2329 |       {{MediaDevices/getDisplayMedia}}, the above definitions distinguish by
2330 |       kind to enable user agents to implement privacy indicators that show the
2331 |       end-user the specific kinds of display sources that are being shared at
2332 |       any point.</p>
2333 |     </div>
2334 | 
2335 | 
2336 |     <div class="note">
2337 |       <p>Since this specification forbids user agents from persisting
2338 |       {{PermissionState/"granted"}} permissions, only the "Live" indicators are
2339 |       significant.</p>
2340 |     </div>
2341 | 
2342 | 
2343 |     <p>The user agent MUST NOT fire the <code><a>devicechange</a></code> event
2344 |     based on changes in the set of available sources from
2345 |     {{MediaDevices/getDisplayMedia}}.</p>
2346 |   </section>
2347 | 
2348 | 
2349 |   <section>
2350 |     <h2>Security and Permissions</h2>
2351 | 
2352 | 
2353 |     <p>This section is informative; however, it notes some serious risks to
2354 |     platform security if the advice it contains are not adhered to.</p>
2355 | 
2356 | 
2357 |     <p>The risks to user privacy and security posed by capture of displayed
2358 |     content are twofold. The immediate and obvious risk is that users
2359 |     inadvertently share content that they did not wish to share, or might not
2360 |     have realized would be shared.</p>
2361 | 
2362 | 
2363 |     <p>Display capture presents a less obvious risk to the cross site request
2364 |     forgery protections offered by the browser sandbox. Display and capture of
2365 |     information that is also under the control of an application, even
2366 |     indirectly, can allow that application to access information that would
2367 |     otherwise be inaccessible to it directly. For example, the canvas API does
2368 |     not permit sampling of a canvas, or conversion to an accessible form if it
2369 |     is not origin-clean [[2DCONTEXT]].</p>
2370 | 
2371 | 
2372 |     <p>This issue is discussed in further detail in [[!RTCWEB-SECURITY-ARCH]]
2373 |     and [[!RTCWEB-SECURITY]].</p>
2374 | 
2375 | 
2376 |     <p>Display capture that includes browser windows, particularly those that
2377 |     are under any form of control by the application, risks violation of these
2378 |     basic security protections. This risk is not entirely contained to browser
2379 |     windows, since control channels between browser applications and other
2380 |     applications, depending on the operating system. The key consideration is
2381 |     whether the captured <a>display surface</a> could be somehow induced to
2382 |     present information that would otherwise be secret from the application
2383 |     that is receiving the resulting media.</p>
2384 | 
2385 | 
2386 |     <section>
2387 |       <h2>Capturing Logical or Visible Display Surfaces</h2>
2388 | 
2389 | 
2390 |       <p>Capture of <a>logical display surfaces</a> causes there to be a
2391 |       potential for content to be shared that a user is not made aware of. A
2392 |       <a>logical display surface</a> might render information that a user did
2393 |       not intend to expose. This can be more easily recognized if this
2394 |       information is visible. Such means are likely ineffectual against a
2395 |       machine, but a human recipient is less able to process content that
2396 |       appears only briefly.</p>
2397 | 
2398 | 
2399 |       <p>It is encouraged that information that is not currently rendered to
2400 |       the screen be obscured in captures unless the application has been
2401 |       specifically authorized to access that content through <a>elevated
2402 |       permissions</a>.</p>
2403 | 
2404 | 
2405 |       <p>How obscured areas of the <a>logical display surface</a> are captured
2406 |       to produce a <a>visible display surface</a> capture MAY vary. Some
2407 |       applications, like presentation software, benefit from having obscured
2408 |       portions of the screen render the image that appeared prior to being
2409 |       obscured. Freezing images can cause visual artifacts for changing
2410 |       content, or hide the fact that content is being obscured. Note that
2411 |       frozen portions of a capture can be incorrectly perceived as a bug.
2412 |       Alternatively, obscured areas might be replaced with content that marks
2413 |       them as being obscured, such as a grey color or hatching.</p>
2414 | 
2415 | 
2416 |       <p>Some systems may only capture the <a>logical display surface</a>.
2417 |       Devices with small screens, for instance, do not typically have the
2418 |       concept of a [= display surface/window =], and render applications in
2419 |       full screen modes only. These systems might provide a capture of an
2420 |       application that is not currently visible, which could be unusable
2421 |       without capturing the <a>logical display surface</a>.</p>
2422 | 
2423 | 
2424 |       <p>When capturing a [= display surface/window =] or other <a>display
2425 |       surface</a> that is partially transparent, any content behind it will not
2426 |       be captured.</p>
2427 | 
2428 | 
2429 |       <p>There is a risk that the user prompt be exposed to the web page for a
2430 |       short amount of time by the newly created {{MediaStreamTrack}}, for
2431 |       instance if the user selects the screen on which the user prompt is
2432 |       displayed. In the case of the user prompt displaying previews of the
2433 |       various surfaces available for selection, those previews will not be
2434 |       captured by the newly created {{MediaStreamTrack}}.</p>
2435 | 
2436 | 
2437 |       <h2>Capturing Audio</h2>
2438 | 
2439 | 
2440 |       <p>{{MediaDevices/getDisplayMedia}} allows capturing audio alongside
2441 |       video, this poses privacy and security concern as this may expose
2442 |       additional information about system applications, and the set of shared
2443 |       audio sources are not necessarily the same as the set of shared video
2444 |       sources. For example, the capture of the video of a [= display
2445 |       surface/window =] that is accompanied by the audio of the entire system,
2446 |       including applications unrelated to that window, will not be shared
2447 |       without <a>active user consent</a>. It is important that the user is
2448 |       aware of what content will be shared, including any possible audio. It is
2449 |       strongly encouraged that the user is allowed to give consent to video but
2450 |       not audio, resulting in a video-only stream. This ensures that the
2451 |       request for audio is always optional and does not restrict the user's
2452 |       choices compared to a video-only request.</p>
2453 |     </section>
2454 | 
2455 | 
2456 |     <section>
2457 |       <h2>Authorizing Display Capture</h2>
2458 | 
2459 | 
2460 |       <p>This document encourages implementations to provide additional
2461 |       limitations on the mechanisms used to affirm user consent. These
2462 |       limitations are designed to mitigate the security and privacy risks that
2463 |       the API poses.</p>
2464 | 
2465 | 
2466 |       <p>Two forms of consent interaction are described: <a>active user
2467 |       consent</a> and a range of <a>elevated permissions</a>. These are
2468 |       non-normative recommandations only.</p>
2469 | 
2470 | 
2471 |       <section>
2472 |         <h2>Active User Consent</h2>
2473 | 
2474 | 
2475 |         <p><dfn>Active user consent</dfn> is sufficient where there is little
2476 |         or no risk of an application gaining information that the user did not
2477 |         intend to share. These cases can be identified by those where the
2478 |         application that requests capture has no control over what is rendered
2479 |         to the captured <a>display surface</a>.</p>
2480 | 
2481 | 
2482 |         <p>To prevent applications from limiting the available choices
2483 |         presented to a user with the goal of promoting a particular choice, the
2484 |         {{MediaDevices/getDisplayMedia}} API does not permit the use of
2485 |         constraints to narrow the set of options presented.</p>
2486 |       </section>
2487 | 
2488 | 
2489 |       <section>
2490 |         <h2>Elevated Permissions</h2>
2491 | 
2492 | 
2493 |         <p>It is strongly advised that <dfn>elevated permissions</dfn> be
2494 |         required to access any <a>display surface</a> that might be used to
2495 |         circumvent cross-origin protections for content. The key goal of this
2496 |         consent process is not just to demonstrate that a user intends to share
2497 |         content, but to also to determine that the user exhibits an elevated
2498 |         level of trust in the application that is being granted access.</p>
2499 | 
2500 | 
2501 |         <p>Several different controls might be provided to grant <a>elevated
2502 |         permissions</a>. This section describes several different capabilities
2503 |         that could be independently granted. A <a>user agent</a> might opt to
2504 |         prohibit access to any capability that requires <a>elevated
2505 |         permissions</a>.</p>
2506 | 
2507 | 
2508 |         <p>If access to these surfaces is supported, it is strongly advised
2509 |         that any mechanism to acquire <a>elevated permissions</a> not rely
2510 |         solely on simple prompts for user consent. Any action needs to ensure
2511 |         that a decision to authorize an application with elevated privileges is
2512 |         deliberate. For instance, a <a>user agent</a> might require a process
2513 |         equivalent to software installation to signify that user consent for
2514 |         <a>elevated permissions</a> is granted.</p>
2515 | 
2516 | 
2517 |         <p>An <a>elevated permissions</a> experience could allow the <a>user
2518 |         agent</a> to communicate the risks associated with enabling this
2519 |         feature, or at least to convey the need for augmented trust in the
2520 |         application.</p>
2521 | 
2522 | 
2523 |         <p>Note that <a>elevated permissions</a> are not a substitute for
2524 |         <a>active user consent</a>. It is advised that <a>user agents</a> still
2525 |         present users with the ability to select what is shared, even for
2526 |         applications that have <a>elevated permissions</a>.</p>
2527 |       </section>
2528 | 
2529 | 
2530 |       <section>
2531 |         <h2>Capabilities Depending on Elevated Permissions</h2>
2532 | 
2533 | 
2534 |         <p><a>Elevated permissions</a> are encouraged as a prerequisite for
2535 |         access to capture of [= display surface/monitor =] or [= display
2536 |         surface/browser =] <a>display surfaces</a>. Note that capture of a
2537 |         complete [= display surface/monitor =] is included because this could
2538 |         include a window from the <a>user agent</a>.</p>
2539 | 
2540 | 
2541 |         <p>Similarly, <a>elevated permissions</a> are an encouraged
2542 |         prerequisite for access to <a>logical display surfaces</a>, where that
2543 |         would not ordinarily be provided.</p>
2544 | 
2545 | 
2546 |         <p>It is encouraged that <a>elevated permissions</a> that are granted
2547 |         to an origin be persisted. An <a>elevated permissions</a> process in
2548 |         part relies on its novelty to ensure that it correctly captures user
2549 |         intent.</p>
2550 |       </section>
2551 |     </section>
2552 | 
2553 | 
2554 |     <section>
2555 |       <h2>Feedback and Interface During Capture</h2>
2556 | 
2557 | 
2558 |       <p>Implementations are advised to provide user feedback and control
2559 |       mechanisms similar to those offered users when sharing a camera or
2560 |       microphone, as encouraged in [[GETUSERMEDIA]].</p>
2561 | 
2562 | 
2563 |       <p>It is important that a user be aware that content is being shared when
2564 |       content is actively being captured. <a>User agents</a> are advised to
2565 |       display a prominent indicator while content is being captured. In
2566 |       addition to an indicator, a <a>user agent</a> is advised to provide a
2567 |       means to learn precisely what is being shared; while this capability is
2568 |       trivially provided by an application by rendering the captured content,
2569 |       this information allows a user to accurately assess what is being
2570 |       shared.</p>
2571 | 
2572 | 
2573 |       <p>In addition to feedback mechanisms, a means to for the user to stop
2574 |       any active capture is advisable.</p>
2575 |     </section>
2576 |   </section>
2577 | </body>
2578 | </html>
2579 | 


--------------------------------------------------------------------------------