MediaTrackConstraints: displaySurface property

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

TheMediaTrackConstraints dictionary'sdisplaySurface property is aConstrainDOMString describing the preferred value for thedisplaySurface constrainable property.

This is set by the application to identify to the user agent the type of display surface (window,browser, ormonitor) preferred by the application. It has no effect on what the user can choose to share, but may be used to present the options in a different order.

If needed, you can determine whether or not this constraint is supported by checking the value ofMediaTrackSupportedConstraints.displaySurface as returned by a call toMediaDevices.getSupportedConstraints(). However, typically this is unnecessary since browsers will ignore any constraints they're unfamiliar with.

Value

AConstrainDOMString which specifies the type of display surface preferred by the application.This valuedoes not add or remove display sources in the browser's user interface, but may reorder them. You can't use this property to limit the user to a subset of the three display-surface valueswindow,browser, andmonitor — but, as you will see below, you can see what was chosen, and reject it.

Seehow constraints are defined.

Note:You cannot setmonitorTypeSurfaces: "exclude" at the same time asdisplaySurface: "monitor" as the two settings are contradictory. Trying to do so will result in the associatedgetDisplayMedia() call failing with aTypeError.

Usage notes

You can check the setting selected by the user agent after the display media has beencreated bygetDisplayMedia() by callinggetSettings() on the display media'svideoMediaStreamTrack, then checking the value of the returnedMediaTrackSettings object'sdisplaySurface object.

For example, if your app prefers not to share a monitor — meaning that there's possibly a non-content backdrop being captured — it can use code similarto this:

let mayHaveBackdropFlag = false;let displaySurface = displayStream  .getVideoTracks()[0]  .getSettings().displaySurface;if (displaySurface === "monitor") {  mayHaveBackdropFlag = true;}

Following this code,mayHaveBackdrop istrue if the displaysurface contained in the stream is of typemonitor.Later code can use this flag to determine whether or not to perform special processing,such as to remove or replace the backdrop, or to "cut" the individual display areas outof the received frames of video.

Examples

Here are some example constraints objects forgetDisplayMedia() that makeuse of thedisplaySurface property.

dsConstraints = { displaySurface: "window" }; // 'browser' and 'monitor' are also possibleapplyConstraints(dsConstraints);// The user still may choose to share the monitor or the browser,// but we indicated that a window is preferred.

In addition, see theConstraint exerciser examplethat demonstrates how constraints are used.