BrowserCaptureMediaStreamTrack: cropTo() 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 cropTo()
method of the BrowserCaptureMediaStreamTrack
interface crops a self-capture stream to the area in which a specified DOM element is rendered.
Syntax
cropTo(cropTarget)
Parameters
cropTarget
-
A
CropTarget
instance representing the element rendering area the stream should be cropped to, ornull
/undefined
, in which case any previously-set cropping is removed from the track.
Return value
A Promise
that resolves to undefined
.
The promise will reject if:
- The track
kind
is not"video"
, or itsreadyState
is not"live"
. - The crop target element no longer exists.
- The track being cropped is not a track captured from the user's screen.
cropTarget
is not aCropTarget
instance,null
, orundefined
.cropTarget
was created in a tab other than the one being captured.
Note:
In Chromium, if a track has clones, cropTo()
will reject (see Chrome issue 41482026).
Examples
Basic cropping example
// Options for getDisplayMedia()
const displayMediaOptions = {
preferCurrentTab: true,
};
// Create crop target from DOM element
const demoElem = document.querySelector("#demo");
const cropTarget = await CropTarget.fromElement(demoElem);
// Capture video stream from user's webcam and isolate video track
const stream =
await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
const [track] = stream.getVideoTracks();
// Crop video track
await track.cropTo(cropTarget);
// Broadcast cropped stream in <video> element
videoElem.srcObject = stream;
See Using the Element Capture and Region Capture APIs for in-context example code.
Stopping the cropping
You can stop the cropping by making a call to cropTo()
on a previously-cropped track, passing an argument of null
to it:
// Stop cropping
await track.cropTo(null);
Specifications
Specification |
---|
Region Capture # dom-browsercapturemediastreamtrack-cropto |
Browser compatibility
Report problems with this compatibility data on GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
cropTo |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- No support
- No support
- Experimental. Expect behavior to change in the future.