Screen Capture API

, MediaStream navigator.mediaDevices.getDisplayMedia(), , , .

: async/await

async function startCapture(displayMediaOptions) {
  let captureStream = null;

  try {
    captureStream =
      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
  } catch (err) {
    console.error("Error: " + err);
  }
  return captureStream;
}

, await , , Promise , .

: Promise

function startCapture(displayMediaOptions) {
  let captureStream = null;

  return navigator.mediaDevices
    .getDisplayMedia(displayMediaOptions)
    .catch((err) => {
      console.error("Error:" + err);
      return null;
    });
}

user agent , . startCapture() MediaStream , ( ?).

Options and constraints, , , , .

,

[Screenshot of Chrome's window for picking a source surface]

captureStream, , . examples

Screen Capture API, - , API () . , , , , ( , ).

. - , , , .

- , , , . . , , - , . , , , , .

. , , , .

, getDisplayMedia() DisplayMediaStreamConstraints , .

, MediaTrackConstraints ( MediaTrackSupportedConstraints MediaTrackSettings) :

cursor

, , , . :

always

() .

motion

( ) , ( user agent ) . .

never

() ..

logicalSurface

Boolean , , , .

, . ,

, width , , , , .

, , - , , .

getDisplayMedia() . user agents . , , ( ) .

, , Browser compatibility, .

, getDisplayMedia():

const gdmOptions = {
  video: true,
  audio: true,
};

, , , . , audio video:

const gdmOptions = {
  video: {
    cursor: "always",
  },
  audio: {
    echoCancellation: true,
    noiseSuppression: true,
    sampleRate: 44100,
  },
};

, , 44,1

, - , MediaStream - .

Using the captured stream

The Promise returned by getDisplayMedia() resolves to a MediaStream that contains at least one video stream that contains the screen or screen area, and which is adjusted or filtered based upon the constraints specifed when getDisplayMedia() was called.

Potential risks

Privacy and security issues surrounding screen sharing are usually not overly serious, but they do exist. The largest potential issue is users inadvertently sharing content they did not wish to share.

For example, privacy and/or security violations can easily occur if the user is sharing their screen and a visible background window happens to contain personal information, or if their password manager is visible in the shared stream. This effect can be amplified when capturing logical display surfaces, which may contain content that the user doesn't know about at all, let alone see.

User agents which take privacy seriously should obfuscate content that is not actually visible onscreen, unless authorization has been given to share that content specifically.

Authorizing capture of display contents

Before streaming of captured screen contents can begin, the user agent will ask the user to confirm the sharing request, and to select the content to share.

Examples

Simple screen capture

In this example, the contents of the captured screen area are simply streamed into a <video> element on the same page.

JavaScript

There isn't all that much code needed in order to make this work, and if you're familiar with using getUserMedia() to capture video from a camera, you'll find getDisplayMedia() to be very familiar.

Setup

First, some constants are set up to reference the elements on the page to which we'll need access: the <video> into which the captured screen contents will be streamed, a box into which logged output will be drawn, and the start and stop buttons that will turn on and off capture of screen imagery.

The object displayMediaOptions contains the MediaStreamConstraints to pass into getDisplayMedia(); here, the cursor property is set to always, indicating that the mouse cursor should always be included in the captured media.

Finally, event listeners are established to detect user clicks on the start and stop buttons.

const videoElem = document.getElementById("video");
const logElem = document.getElementById("log");
const startElem = document.getElementById("start");
const stopElem = document.getElementById("stop");

// Options for getDisplayMedia()

var displayMediaOptions = {
  video: {
    cursor: "always",
  },
  audio: false,
};

// Set event listeners for the start and stop buttons
startElem.addEventListener(
  "click",
  function (evt) {
    startCapture();
  },
  false,
);

stopElem.addEventListener(
  "click",
  function (evt) {
    stopCapture();
  },
  false,
);

Logging content

To make logging of errors and other issues easy, this example overrides certain Console methods to output their messages to the <pre> block whose ID is log.

console.log = (msg) => (logElem.innerHTML += `${msg}<br>`);
console.error = (msg) =>
  (logElem.innerHTML += `<span class="error">${msg}</span><br>`);
console.warn = (msg) =>
  (logElem.innerHTML += `<span class="warn">${msg}<span><br>`);
console.info = (msg) =>
  (logElem.innerHTML += `<span class="info">${msg}</span><br>`);

This allows us to use the familiar console.log(), console.error(), and so on to log information to the log box in the document.

Starting display capture

The startCapture() method, below, starts the capture of a MediaStream whose contents are taken from a user-selected area of the screen. startCapture() is called when the "Start Capture" button is clicked.

async function startCapture() {
  logElem.innerHTML = "";

  try {
    videoElem.srcObject =
      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
    dumpOptionsInfo();
  } catch (err) {
    console.error("Error: " + err);
  }
}

After clearing the contents of the log in order to get rid of any leftover text from the previous attempt to connect, startCapture() calls getDisplayMedia(), passing into it the constraints object defined by displayMediaOptions. Using await, the following line of code does not get executed until after the Promise returned by getDisplayMedia() resolves. Upon resolution, the promise returns a MediaStream, which will stream the contents of the screen, window, or other region selected by the user.

The stream is connected to the <video> element by storing the returned MediaStream into the element's srcObject.

The dumpOptionsInfo() functionwhich we will look at in a momentdumps information about the stream to the log box for educational purposes.

If any of that fails, the catch() clause outputs an error message to the log box.

Stopping display capture

The stopCapture() method is called when the "Stop Capture" button is clicked. It stops the stream by getting its track list using MediaStream.getTracks(), then calling each track's {domxref("MediaStreamTrack.stop, "stop()")}} method. Once that's done, srcObject is set to null to make sure it's understood by anyone interested that there's no stream connected.

function stopCapture(evt) {
  let tracks = videoElem.srcObject.getTracks();

  tracks.forEach((track) => track.stop());
  videoElem.srcObject = null;
}

Dumping configuration information

For informational purposes, the startCapture() method shown above calls a method named dumpOptions(), which outputs the current track settings as well as the consrtaints that were placed upon the stream when it was created.

function dumpOptionsInfo() {
  const videoTrack = videoElem.srcObject.getVideoTracks()[0];

  console.info("Track settings:");
  console.info(JSON.stringify(videoTrack.getSettings(), null, 2));
  console.info("Track constraints:");
  console.info(JSON.stringify(videoTrack.getConstraints(), null, 2));
}

The track list is obtained by calling getVideoTracks() on the capture'd screen's MediaStream. The settings currentoly in effect are obtained using getSettings() and the established constraints are gotten with getConstraints()

HTML

The HTML starts with a simple introductory paragraph, then gets into the meat of things.

<p>
  This example shows you the contents of the selected part of your display.
  Click the Start Capture button to begin.
</p>

<p>
  <button id="start">Start Capture</button>&nbsp;<button id="stop">
    Stop Capture
  </button>
</p>

<video id="video" autoplay></video>
<br />

<strong>Log:</strong>
<br />
<pre id="log"></pre>

The key parts of the HTML are:

1. A <button> labeled "Start Capture" which, when clicked, calls the startCapture() function to request access to, and begin capturing, screen contents.
2. A second button, "Stop Capture", which upon being clicked calls stopCapture() to terminate capture of screen contents.
3. A <video> into which the captured screen contents are streamed.
4. A <pre> block into which logged text is placed by the intercepted Consolemethod.

CSS

The CSS is entirely cosmetic in this example. The video is given a border, and its width is set to occupy nearly the entire available horizontal space (width: 98%). max-width is set to 860px to set an absolute upper limit on the video's size,

The error, warn, and info classes are used to style the corresponding console output types.

#video {
  border: 1px solid #999;
  width: 98%;
  max-width: 860px;
}

.error {
  color: red;
}

.warn {
  color: orange;
}

.info {
  color: darkgreen;
}

Result

The final product looks like this. If your browser supports Screen Capture API, clicking "Start Capture" will present the user agent's interface for selecting a screen, window, or tab to share.

Security

In order to function when Feature Policy is enabled, you will need the display-capture permission. This can be done using the Feature-Policy HTTP header orif you're using the Screen Capture API in an <iframe>, the <iframe> element's allow attribute.

For example, this line in the HTTP headers will enable Screen Capture API for the document and any embedded <iframe> elements that are loaded from the same origin:

Feature-Policy: display-capture 'self'

If you're performing screen capture within an <iframe>, you can request permission just for that frame, which is clearly more secure than requesting a more general permission:

<iframe src="https://mycode.example.net/etc" allow="display-capture"> </iframe>

• Screen Capture API
• Media Capture and Streams API
• Taking still photos with WebRTC
• HTMLCanvasElement.captureStream() to obtain a MediaStream with the live contents of a <canvas>