MediaDevices.getDisplayMedia()

Signature

const stream = await navigator.mediaDevices.getDisplayMedia(constraints);
// constraints: { video, audio }
// returns: Promise<MediaStream>

What it does

Prompts the user to pick a screen, window, or browser tab, then resolves with a MediaStream containing the captured video and, where allowed, audio. The captured tracks behave like any other media tracks.

Key members

Member	Kind	Purpose
`constraints.video`	input	`true` or a constraints object; `false` is not allowed.
`constraints.audio`	input	Request system or tab audio where supported.
returned `MediaStream`	output	Holds the display video track and optional audio.
video track `getSettings().displaySurface`	property	`monitor`, `window`, or `browser`.
video track `ended`	event	Fires when the user clicks "Stop sharing".

Behaviour & constraints

Must be called from a user gesture; the browser shows a non-overridable picker.
The page cannot pre-select which surface is shared: the user always chooses.
video: false is invalid; a video track is always part of the result.
Audio capture is limited and platform-dependent; treat it as best-effort.
Listen for the video track's ended event to detect when the user stops sharing.
Requires a secure context (HTTPS or localhost).

Example

const stream = await navigator.mediaDevices.getDisplayMedia({
  video: { displaySurface: 'monitor' },
  audio: false,
});

const [screen] = stream.getVideoTracks();
screen.addEventListener('ended', () => console.log('sharing stopped'));

pc.addTrack(screen, stream);