1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
---
title: Screen Capture API
slug: Web/API/Screen_Capture_API
tags:
- API
- Capture
- Conference
- Media
- MediaDevices
- MediaStream
- NeedsTranslation
- Overview
- Screen Capture
- Screen Capture API
- Screen Sharing
- Sharing
- TopicStub
- Video
- Window
- display
- getDisplayMedia
- screen
translation_of: Web/API/Screen_Capture_API
---
<div>{{DefaultAPISidebar("Screen Capture API")}}</div>
<p><span class="seoSummary">The Screen Capture API introduces additions to the existing Media Capture and Streams API to let the user select a screen or portion of a screen (such as a window) to capture as a media stream.</span> This stream can then be recorded or shared with others over the network.</p>
<h2 id="Screen_Capture_API_concepts_and_usage">Screen Capture API concepts and usage</h2>
<p>The Screen Capture API is relatively simple to use. Its sole method is {{domxref("MediaDevices.getDisplayMedia()")}}, whose job is to ask the user to select a screen or portion of a screen to capture in the form of a {{domxref("MediaStream")}}.</p>
<p>To start capturing video from the screen, you call <code>getDisplayMedia()</code> on the instance of <code>Media</code> <code>navigator.mediaDevices</code>:</p>
<pre class="brush: js">captureStream = await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);</pre>
<p>The {{jsxref("Promise")}} returned by <code>getDisplayMedia()</code> resolves to a {{domxref("MediaStream")}} which streams the captured media.</p>
<p>See the article <a href="/en-US/docs/Web/API/Screen_Capture_API/Using_Screen_Capture">Using the Screen Capture API</a> for a more in-depth look at how to use the API to capture screen contents as a stream.</p>
<h2 id="Additions_to_existing_interfaces">Additions to existing interfaces</h2>
<p>The Screen Capture API doesn't have any interfaces of its own; instead, it adds one method to the existing {{domxref("MediaDevices")}} interface.</p>
<h3 id="MediaDevices_interface">MediaDevices interface</h3>
<dl>
<dt>{{domxref("MediaDevices.getDisplayMedia()")}}</dt>
<dd>The <code>getDisplayMedia()</code> method is added to the <code>MediaDevices</code> interface. Similar to {{domxref("MediaDevices.getUserMedia", "getUserMedia()")}}, this method creates a promise that resolves with a {{domxref("MediaStream")}} containing the display area selected by the user, in a format that matches the specified options.</dd>
</dl>
<h2 id="Additions_to_existing_dictionaries">Additions to existing dictionaries</h2>
<p>The Screen Capture API adds properties to the following dictionaries defined by other specifications.</p>
<h3 id="MediaTrackConstraints">MediaTrackConstraints</h3>
<dl>
<dt>{{domxref("MediaTrackConstraints.cursor")}}</dt>
<dd>A {{domxref("ConstrainDOMString")}} indicating whether or not the cursor should be included in the captured display surface's stream, and if it should always be visible or if it should only be visible while the mouse is in motion.</dd>
<dt>{{domxref("MediaTrackConstraints.displaySurface")}}</dt>
<dd>A {{domxref("ConstrainDOMString")}} indicating what type of display surface is to be captured. The value is one of <code>application</code>, <code>browser</code>, <code>monitor</code>, or <code>window</code>.</dd>
<dt>{{domxref("MediaTrackConstraints.logicalSurface")}}</dt>
<dd>Indicates whether or not the video in the stream represents a logical display surface (that is, one which may not be entirely visible onscreen, or may be completely offscreen). A value of <code>true</code> indicates a logical display surface is to be captured.</dd>
</dl>
<h3 id="MediaTrackSettings">MediaTrackSettings</h3>
<dl>
<dt>{{domxref("MediaTrackSettings.cursor")}}</dt>
<dd>A string which indicates whether or not the display surface currently being captured includes the mouse cursor, and if so, whether it's only visible while the mouse is in motion or if it's always visible. The value is one of <code>always</code>, <code>motion</code>, or <code>never</code>.</dd>
<dt>{{domxref("MediaTrackSettings.displaySurface")}}</dt>
<dd>A string indicating what type of display surface is currently being captured. The value is one of <code>application</code>, <code>browser</code>, <code>monitor</code>, or <code>window</code>.</dd>
<dt>{{domxref("MediaTrackSettings.logicalSurface")}}</dt>
<dd>A Boolean value which is <code>true</code> if the video being captured doesn't directly correspond to a single onscreen display area.</dd>
</dl>
<h3 id="MediaTrackSupportedConstraints">MediaTrackSupportedConstraints</h3>
<dl>
<dt>{{domxref("MediaTrackSupportedConstraints.cursor")}}</dt>
<dd>A Boolean which is <code>true</code> if the user agent and device support the {{domxref("MediaTrackConstraints.cursor")}} constraint.</dd>
<dt>{{domxref("MediaTrackSupportedConstraints.displaySurface")}}</dt>
<dd>A Boolean which is <code>true</code> if the current environment supports the {{domxref("MediaTrackConstraints.displaySurface")}} constraint.</dd>
<dt>{{domxref("MediaTrackSupportedConstraints.logicalSurface")}}</dt>
<dd>A Boolean which is <code>true</code> if the current environment supports the constraint {{domxref("MediaTrackConstraints.logicalSurface")}}.</dd>
</dl>
<h2 id="Dictionaries">Dictionaries</h2>
<p>The following dictionaries are defined by the Screen Capture API.</p>
<dl>
<dt><code>CursorCaptureConstraint</code></dt>
<dd>An enumerated string type used to provide the value for the <code>cursor</code> property for the settings and constraints. The possible values are <code>always</code>, <code>motion</code>, and <code>never</code>.</dd>
<dt><code>DisplayCaptureSurfaceType</code></dt>
<dd>An enumerated string type which is used to identify the kind of display surface to capture. This type is used for the <code>displaySurface</code> property in the constraints and settings objects, and has the possible values <code>application</code>, <code>browser</code>, <code>monitor</code>, and <code>window</code>.</dd>
</dl>
<h2 id="Feature_Policy_validation">Feature Policy validation</h2>
<p>{{Glossary("User agent", "User agents")}} that support Feature Policy (either using HTTP's {{HTTPHeader("Feature-Policy")}} header or the {{HTMLElement("iframe")}} attribute {{htmlattrxref("allow", "iframe")}}) can specify a desire to use the Screen Capture API using the policy control directive <code>display-capture</code>:</p>
<pre class="brush: html"><iframe allow="display-capture" src="/some-other-document.html"></pre>
<p>The default allow list is <code>self</code>, which lets the any content within the document use Screen Capture.</p>
<p>See <a href="/en-US/docs/Web/HTTP/Feature_Policy/Using_Feature_Policy">Using Feature Policy</a> for a more in-depth explanation of how Feature Policy is used.</p>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
<tr>
<td>{{SpecName('Screen Capture')}}</td>
<td>{{Spec2('Screen Capture')}}</td>
<td>Initial definition</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<div>
<p>{{Compat("api.MediaDevices.getDisplayMedia")}}</p>
</div>
<h2 id="See_also">See also</h2>
<ul>
<li><a href="/en-US/docs/Web/API/Screen_Capture_API/Using_Screen_Capture">Using the Screen Capture API</a></li>
<li>{{domxref("MediaDevices.getDisplayMedia()")}}</li>
</ul>
|
