BrowserCaptureMediaStreamTrack: restrictTo() method
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
The restrictTo() method of the BrowserCaptureMediaStreamTrack interface restricts a self-capture stream to a specific DOM element (and its descendants).
Syntax
restrictTo(restrictionTarget)
Parameters
restrictionTarget-
A
RestrictionTargetinstance representing the element the stream should be restricted to, ornull/undefined, in which case any previously-set restriction is removed from the track.
Return value
A Promise that resolves to undefined.
The promise will reject if:
- The track
kindis not"video", or itsreadyStateis not"live". - The restriction target element no longer exists.
- The track being restricted is not a track captured from the user's screen.
restrictionTargetis not aRestrictionTargetinstance,null, orundefined.restrictionTargetwas created in a tab other than the one being captured.
Note:
In Chromium, if a track has clones, restrictTo() will reject (see Chrome issue 41482026).
Examples
Basic restriction example
// Options for getDisplayMedia()
const displayMediaOptions = {
preferCurrentTab: true,
};
// Create restriction target from DOM element
const demoElem = document.querySelector("#demo");
const restrictionTarget = await RestrictionTarget.fromElement(demoElem);
// Capture video stream from user's webcam and isolate video track
const stream =
await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
const [track] = stream.getVideoTracks();
// Restrict video track
await track.restrictTo(restrictionTarget);
// Broadcast restricted stream in <video> element
videoElem.srcObject = stream;
See Using the Element Capture and Region Capture APIs for in-context example code.
Stopping the restriction
You can stop the restriction by making a call to restrictTo() on the same track, passing an argument of null to it:
// Stop restricting
await track.restrictTo(null);
Specifications
| Specification |
|---|
| Element Capture # dom-browsercapturemediastreamtrack-restrictto |
Browser compatibility
Loading…