Editorial review: Add documentation for Screen Capture extensions, el…

…ement capture and region capture (#36939) * Adding landing page for Screen Capture extrensions * Add usage guide * Add reference pages * Fix a couple of flaws * Fixes for beaufortfrancois review comments * remove audio: false, * Make it clearer that preferCurrentTab is a hint * Fix respective use cases content * Fixes for last few eladalon comments * Tighten up prose; remove screen versus tab confusion * Fixes for wbamberg review comments * Second round of fixes for wbamberg review comments * Separate out browser-specific limitations info --------- Co-authored-by: wbamberg <[email protected]>
mdn · Feb 7, 2025 · d9879ec · d9879ec
1 parent 8e726de
commit d9879ec
Show file tree

Hide file tree

Showing 12 changed files with 885 additions and 3 deletions.
diff --git a/files/en-us/web/api/browsercapturemediastreamtrack/clone/index.md b/files/en-us/web/api/browsercapturemediastreamtrack/clone/index.md
@@ -0,0 +1,69 @@
+---
+title: "BrowserCaptureMediaStreamTrack: clone() method"
+short-title: clone()
+slug: Web/API/BrowserCaptureMediaStreamTrack/clone
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.BrowserCaptureMediaStreamTrack.clone
+---
+
+{{APIRef("Screen Capture API")}}{{SeeCompatTable}}{{securecontext_header}}
+
+The **`clone()`** method of the {{domxref("BrowserCaptureMediaStreamTrack")}} interface returns a clone of the original `BrowserCaptureMediaStreamTrack`.
+
+This method is functionally identical to {{domxref("MediaStreamTrack.clone()")}}, except that it handles cases where cropping or restriction have been applied to the track. The returned clone is identical to the original `BrowserCaptureMediaStreamTrack`, but with any cropping or restriction removed.
+
+> [!NOTE]
+> In Chromium, if a track has clones, its {{domxref("BrowserCaptureMediaStreamTrack.cropTo", "cropTo()")}} and {{domxref("BrowserCaptureMediaStreamTrack.restrictTo", "restrictTo()")}} methods will reject (see [Chrome issue 41482026](https://issues.chromium.org/issues/41482026)).
+
+## Syntax
+
+```js-nolint
+clone()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A {{domxref("BrowserCaptureMediaStreamTrack")}} instance.
+
+## Examples
+
+```js
+// 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);
+
+// Create uncropped clone of the track
+const clonedTrack = track.clone();
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API)
+- [Using the Element Capture and Region Capture APIs](/en-US/docs/Web/API/Screen_Capture_API/Element_Region_Capture)
diff --git a/files/en-us/web/api/browsercapturemediastreamtrack/cropto/index.md b/files/en-us/web/api/browsercapturemediastreamtrack/cropto/index.md
@@ -0,0 +1,89 @@
+---
+title: "BrowserCaptureMediaStreamTrack: cropTo() method"
+short-title: cropTo()
+slug: Web/API/BrowserCaptureMediaStreamTrack/cropTo
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.BrowserCaptureMediaStreamTrack.cropTo
+---
+
+{{APIRef("Screen Capture API")}}{{SeeCompatTable}}{{securecontext_header}}
+
+The **`cropTo()`** method of the {{domxref("BrowserCaptureMediaStreamTrack")}} interface crops a self-capture stream to the area in which a specified DOM element is rendered.
+
+## Syntax
+
+```js-nolint
+cropTo(cropTarget)
+```
+
+### Parameters
+
+- `cropTarget`
+  - : A {{domxref("CropTarget")}} instance representing the element rendering area the stream should be cropped to, or `null`/`undefined`, in which case any previously-set cropping is removed from the track.
+
+### Return value
+
+A {{jsxref("Promise")}} that resolves to {{jsxref("undefined")}}.
+
+The promise will reject if:
+
+- The track [`kind`](/en-US/docs/Web/API/MediaStreamTrack/kind) is not `"video"`, or its [`readyState`](/en-US/docs/Web/API/MediaStreamTrack/readyState) 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 a {{domxref("CropTarget")}} instance, `null`, or `undefined`.
+- `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](https://issues.chromium.org/issues/41482026)).
+
+## Examples
+
+### Basic cropping example
+
+```js
+// 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](/en-US/docs/Web/API/Screen_Capture_API/Element_Region_Capture) 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:
+
+```js
+// Stop cropping
+await track.cropTo(null);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API)
+- [Using the Element Capture and Region Capture APIs](/en-US/docs/Web/API/Screen_Capture_API/Element_Region_Capture)
diff --git a/files/en-us/web/api/browsercapturemediastreamtrack/index.md b/files/en-us/web/api/browsercapturemediastreamtrack/index.md
@@ -0,0 +1,40 @@
+---
+title: BrowserCaptureMediaStreamTrack
+slug: Web/API/BrowserCaptureMediaStreamTrack
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.BrowserCaptureMediaStreamTrack
+---
+
+{{APIRef("Screen Capture API")}}{{SeeCompatTable}}
+
+The **`BrowserCaptureMediaStreamTrack`** interface of the {{domxref("Screen Capture API", "Screen Capture API", "", "nocode")}} represents a single video track. It extends the {{domxref("MediaStreamTrack")}} class with methods to limit the part of a self-capture stream (for example, a user's screen or window) that is captured.
+
+{{InheritanceDiagram}}
+
+## Instance methods
+
+- {{domxref("BrowserCaptureMediaStreamTrack.clone", "clone()")}} {{Experimental_Inline}}
+  - : Returns an uncropped, unrestricted clone of the original `BrowserCaptureMediaStreamTrack`.
+- {{domxref("BrowserCaptureMediaStreamTrack.cropTo", "cropTo()")}} {{Experimental_Inline}}
+  - : Crops a self-capture stream to the area in which a specified DOM element is rendered.
+- {{domxref("BrowserCaptureMediaStreamTrack.restrictTo", "restrictTo()")}} {{Experimental_Inline}}
+  - : Restricts a self-capture stream to a specific DOM element.
+
+## Examples
+
+See [Using the Element Capture and Region Capture APIs](/en-US/docs/Web/API/Screen_Capture_API/Element_Region_Capture) for in-context example code.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API)
+- [Using the Element Capture and Region Capture APIs](/en-US/docs/Web/API/Screen_Capture_API/Element_Region_Capture)
diff --git a/files/en-us/web/api/browsercapturemediastreamtrack/restrictto/index.md b/files/en-us/web/api/browsercapturemediastreamtrack/restrictto/index.md
@@ -0,0 +1,87 @@
+---
+title: "BrowserCaptureMediaStreamTrack: restrictTo() method"
+short-title: restrictTo()
+slug: Web/API/BrowserCaptureMediaStreamTrack/restrictTo
+page-type: web-api-instance-method
+browser-compat: api.BrowserCaptureMediaStreamTrack.restrictTo
+---
+
+{{APIRef("Screen Capture API")}}{{SeeCompatTable}}{{securecontext_header}}
+
+The **`restrictTo()`** method of the {{domxref("BrowserCaptureMediaStreamTrack")}} interface restricts a self-capture stream to a specific DOM element (and its descendants).
+
+## Syntax
+
+```js-nolint
+restrictTo(restrictionTarget)
+```
+
+### Parameters
+
+- `restrictionTarget`
+  - : A {{domxref("RestrictionTarget")}} instance representing the element the stream should be restricted to, or `null`/`undefined`, in which case any previously-set restriction is removed from the track.
+
+### Return value
+
+A {{jsxref("Promise")}} that resolves to {{jsxref("undefined")}}.
+
+The promise will reject if:
+
+- The track [`kind`](/en-US/docs/Web/API/MediaStreamTrack/kind) is not `"video"`, or its [`readyState`](/en-US/docs/Web/API/MediaStreamTrack/readyState) is not `"live"`.
+- The restriction target element no longer exists.
+- The track being restricted is not a track captured from the user's screen.
+- `restrictionTarget` is not a {{domxref("RestrictionTarget")}} instance, `null`, or `undefined`.
+- `restrictionTarget` was 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](https://issues.chromium.org/issues/41482026)).
+
+## Examples
+
+### Basic restriction example
+
+```js
+// 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](/en-US/docs/Web/API/Screen_Capture_API/Element_Region_Capture) 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:
+
+```js
+// Stop restricting
+await track.restrictTo(null);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API)
+- [Using the Element Capture and Region Capture APIs](/en-US/docs/Web/API/Screen_Capture_API/Element_Region_Capture)
diff --git a/files/en-us/web/api/croptarget/fromelement_static/index.md b/files/en-us/web/api/croptarget/fromelement_static/index.md
@@ -0,0 +1,75 @@
+---
+title: "CropTarget: fromElement() static method"
+short-title: fromElement()
+slug: Web/API/CropTarget/fromElement_static
+page-type: web-api-static-method
+browser-compat: api.CropTarget.fromElement_static
+---
+
+{{APIRef("Screen Capture API")}}{{SeeCompatTable}}{{securecontext_header}}
+
+The **`fromElement()`** static method of the {{domxref("CropTarget")}} interface returns a `CropTarget` instance that can be used to crop a captured video track to the area in which a specified element is rendered.
+
+Because the Region Capture API crops to an area of the current browser tab rather than capturing a specific element, any content drawn on top of the cropped area will be shown in the capture.
+
+## Syntax
+
+```js-nolint
+CropTarget.fromElement(element)
+```
+
+### Parameters
+
+- `element`
+
+  - : A reference to an {{domxref("Element")}} that you want to use as a crop target. For an element to be used as a crop target, it must be:
+
+    - On-screen
+    - Visible, that is, not hidden via `display: none` for example.
+
+    In addition, the element will not be captured if the track being restricted has clones (that is, created by {{domxref("BrowserCaptureMediaStreamTrack.clone()")}}) or is captured from a different tab to the current user's tab (passed via {{domxref("Window.postMessage()")}}, for example).
+
+### Return value
+
+A {{jsxref("Promise")}} that resolves to a {{domxref("CropTarget")}} object instance, which can then be passed to {{domxref("BrowserCaptureMediaStreamTrack.CropTo()")}} to crop the video captured in the track to just the area the specified DOM element is rendered in.
+
+`CropTarget` objects are serializable. They can be passed to another document using mechanisms such as {{domxref("Window.postMessage()")}}.
+
+## Examples
+
+```js
+// 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](/en-US/docs/Web/API/Screen_Capture_API/Element_Region_Capture) for in-context example code.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API)
+- [Using the Element Capture and Region Capture APIs](/en-US/docs/Web/API/Screen_Capture_API/Element_Region_Capture)