Editorial review: Add documentation for Screen Capture extensions, element capture and region capture #36939

chrisdavidmills · 2024-11-23T16:52:11Z

Description

Motivation

Chrome supports extensions to the Screen Capture API that allow developers to limit the region of the capture. Namely, these are:

The Element Capture API, which is supported from Chrome 132 (see https://chromestatus.com/feature/5198989277790208).
The Region Capture API, which is supported from Chrome 104 (see https://chromestatus.com/feature/5712447794053120).

This PR adds documentation for these APIs.

Additional details

Related issues and pull requests

Fixes mdn/mdn#580

BCD addition: Chrome 132 supports Element Capture API browser-compat-data#25232.
dom-examples addition: Add DOM examples for Screen Capture API dom-examples#285. The linked demos won't work until this PR is merged.

github-actions · 2024-11-23T16:54:02Z

Preview URLs (10 pages)

External URLs (11)

URL: /en-US/docs/Web/API/BrowserCaptureMediaStreamTrack/cropTo
Title: BrowserCaptureMediaStreamTrack: cropTo() method

https://issues.chromium.org/issues/41482026 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/BrowserCaptureMediaStreamTrack/restrictTo
Title: BrowserCaptureMediaStreamTrack: restrictTo() method

https://issues.chromium.org/issues/41482026 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/BrowserCaptureMediaStreamTrack/clone
Title: BrowserCaptureMediaStreamTrack: clone() method

https://issues.chromium.org/issues/41482026 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Screen_Capture_API/Element_Region_Capture
Title: Using the Element Capture and Region Capture APIs

https://developer.chrome.com/docs/web-platform/element-capture (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/web-platform/region-capture (1 time) (Note! This may be a new URL 👀)
https://element-capture-demo.glitch.me/ (1 time) (Note! This may be a new URL 👀)
https://glitch.com/edit/ (1 time) (Note! This may be a new URL 👀)
https://mdn.github.io/dom-examples/screen-capture-api/basic-screen-capture (1 time) (Note! This may be a new URL 👀)
https://mdn.github.io/dom-examples/screen-capture-api/element-capture (2 times) (Note! This may be a new URL 👀)
https://mdn.github.io/dom-examples/screen-capture-api/region-capture (2 times) (Note! This may be a new URL 👀)
https://region-capture-demo.glitch.me/ (2 times) (Note! This may be a new URL 👀)

(comment last updated: 2025-02-07 11:15:03)

skyclouds2001 · 2024-11-24T17:55:40Z

mdn/mdn#580 could be close with this PR

chrisdavidmills · 2024-11-25T09:37:19Z

mdn/mdn#580 could be close with this PR

Cool, thanks for the heads-up @skyclouds2001. I'll update the description to mention it.

…ls/content into region-and-element-capture

files/en-us/web/api/browsercapturemediastreamtrack/cropto/index.md

files/en-us/web/api/browsercapturemediastreamtrack/clone/index.md

files/en-us/web/api/croptarget/fromelement_static/index.md

files/en-us/web/api/croptarget/index.md

files/en-us/web/api/browsercapturemediastreamtrack/clone/index.md

files/en-us/web/api/browsercapturemediastreamtrack/cropto/index.md

files/en-us/web/api/browsercapturemediastreamtrack/restrictto/index.md

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

eladalon1983

LGTM % comment

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

wbamberg · 2025-02-04T20:19:01Z

One kind of overall comment on this is that I think it would be better to present this as part of the Screen Capture API, not as an additional separate API. It's a similar case to https://github.com/orgs/mdn/discussions/683 and similar considerations apply.

wbamberg

These are just comments on the guide, because I started there.

wbamberg · 2025-02-04T20:52:11Z

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

+## Background
+
+The [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API) was created specifically to allow apps to capture the user's screen — or a particular window or tab — and then do something with the resulting stream (such as transmit it to multiple peers via [WebRTC](/en-US/docs/Web/API/WebRTC_API)). The main use case is video conferencing apps, where a user might wish to share a demo running on their local machine with other participants.
+
+The problem with the Screen Capture API is that, by default, it only allows you to broadcast the entire window, screen, or tab selected by the user. Often it would be preferrable to share only a limited region to cut down on unnecessary bandwidth or screen space required to show the capture, or for privacy reasons (you might not want to show other participants your message notifications, or background settings required to run the demo you are sharing). In addition, such apps generally capture your web cam output, meaning that you will likely end up with one of those undesirable "infinite wormhole" or "hall of mirrors" type effects.
+
+To solve such problems, extensions to the Screen Capture API were invented to allow you to restrict the captured stream to a particular subsection of the screen, window, or tab.
+
+In the next section we'll start with a basic Screen Capture API demo to illustrate the issues described above.


This section presents these features in a kind of temporal way:

the SC API was invented

it has some problems

to solve them, some new extensions were added

I think this kind of story works for say a blog post about the new stuff but not so well for reference docs - in 2 years time noone is going to care about the story. It's better just to present the new features as features, and use the present tense, e.g.: "By default, the Screen Capture API captures an entire screen, window, or tab. The element capture and region capture extensions to the API enable you to restrict the captured stream to a specific rendered DOM tree, or to the part of the screen defined by a specific DOM tree's bounding box. This is useful when..."

note also that if we do merge these APIs into the main SC API, I think we should stop capitalizing them, because they're not a title, they're not reified. They're more a part of another API, like we might talk about "how to stream requests", not "how to use the Request Streaming API".

Good call; I have cut down the background section as advised.

However, I'm not sure I should stop capitalizing "Region Capture API" and "Element Capture API" — they are defined in their own specs; they are standalone things. Those things just so happen to extend another API?

wbamberg · 2025-02-04T20:52:15Z

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

+
+## Screen Capture API demo
+
+This demo uses the Screen Capture API to capture a window, screen, or tab, and broadcast the stream via a {{htmlelement("video")}} element on the same page. It also logs the track settings and constraints to a log container below the main app.


Does logging the settings add anything to the tutorial? If not we should omit it.

Yeah, I think you've probably got a point here. I just blindly copied it over when I made these demos based on the original demo on the Screen Capture API usage guide. It doesn't add anything; it just makes the demos more complicated than necessary.

I've removed the demo code in mdn/dom-examples#294. I'll remove it from these code blocks as well.

wbamberg · 2025-02-04T20:52:57Z

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

+page-type: guide
+---
+
+{{SeeCompatTable}}


This should not appear in a guide page (there is no compat table to link)

D'oh! Good point; removed.

wbamberg · 2025-02-04T20:53:16Z

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

+
+{{SeeCompatTable}}
+
+{{DefaultAPISidebar("Screen Capture extensions")}}{{securecontext_header}}


{{securecontext_header}} I think should also be omitted.

wbamberg · 2025-02-04T20:54:53Z

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

+<pre id="log"></pre>
+```
+
+### CSS


I don't think we need to go into the CSS. Apart from the video rule, I don't think it is relevant, is it?

I've hidden most of it now, so the section is a lot shorter than it was. I still think it is worth talking about the couple of bits I'm showing here. They are relevant to the usage of the APIs themselves.

wbamberg · 2025-02-05T00:34:38Z

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

+### Stopping the cropping
+
+You can stop the cropping by making a call to `cropTo()` on the same track, passing an argument of `null` to it:
+
+```js
+// Stop cropping
+await track.cropTo(null);
+```


Again I'd consider excluding this.

Made into a note, as per previous comment.

wbamberg · 2025-02-05T00:35:03Z

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

+await track.cropTo(null);
+```
+
+### Issues with the Region Capture API


Again "restrictions" feels better than "issues".

wbamberg · 2025-02-05T00:37:37Z

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

+- The element will not be cropped to if it is off-screen.
+- The element will not be cropped to if the track being cropped has clones or is not a track captured from the user's screen.
+- The element will not be captured if the `cropTarget` was created in a tab other than the one being captured.
+- Because Region Capture 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 stream.


Consider:

Suggested change

- The element will not be cropped to if it is off-screen.

- The element will not be cropped to if the track being cropped has clones or is not a track captured from the user's screen.

- The element will not be captured if the `cropTarget` was created in a tab other than the one being captured.

- Because Region Capture 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 stream.

The element will not be cropped if any of the following conditions apply:

- It is off-screen.

- The track being cropped has clones or is not a track captured from the user's screen.

- The `cropTarget` was created in a tab other than the one being captured.

Because Region Capture 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 stream.

The fourth is not a condition. Same question about restriction 3 though - how is this possible?

wbamberg · 2025-02-05T00:40:04Z

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

+There are legitimate use cases for both:
+
+- If you need to keep the capture specific to one DOM tree, and exclude anything outside it, then the Element Capture API is a better choice. For example, you don't want private content such as a set of message notifications or a speaker notes UI showing up in the capture.
+- However, if you really do want to capture a region of the browser tab, regardless of what is shown in it, the Region Capture API will serve you well. The [Region Capture Demo](https://region-capture-demo.glitch.me/) shows a useful possibility — zooming in on a particular area of the tab as you show multiple users an interactive walkthrough of some kind.


I wish I could see the source code for this example.

source code link added

wbamberg · 2025-02-05T00:42:19Z

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

+
+- [Screen Capture extensions](/en-US/docs/Web/API/Screen_Capture_extensions)
+- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API)
+- [Element Capture Demo](https://element-capture-demo.glitch.me/)


Include the region capture demo here as well?

wbamberg

Comments on the rest :).

wbamberg · 2025-02-05T00:57:23Z

files/en-us/web/api/browsercapturemediastreamtrack/clone/index.md

+
+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.


The guide page says:

The element will not be cropped to if the track being cropped has clones or is not a track captured from the user's screen.

Is there anything we should capture in this API page about that?

wbamberg · 2025-02-05T00:59:25Z

files/en-us/web/api/browsercapturemediastreamtrack/cropto/index.md

+- 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 has clones or is not a track captured from the user's screen.
+- `CropTarget` is not one of the values specified above.


What does this mean?

Sorry, that was really vague. I rewrote it to

CropTarget is not a {{domxref("CropTarget")}} instance, null, or undefined.

wbamberg · 2025-02-05T00:59:51Z

files/en-us/web/api/browsercapturemediastreamtrack/cropto/index.md

+- The crop target element no longer exists.
+- The track being cropped has clones or is not a track captured from the user's screen.
+- `CropTarget` is not one of the values specified above.
+- `CropTarget` was created in a tab other than the one being captured.


Same question as in the guide page, how is this possible?

same as other page; deleted!

wbamberg · 2025-02-05T01:03:16Z

files/en-us/web/api/browsercapturemediastreamtrack/index.md

+- {{domxref("BrowserCaptureMediaStreamTrack.cropTo", "cropTo()")}} {{Experimental_Inline}}
+  - : Crops a self-capture stream to the area in which a specified crop target element is rendered.
+- {{domxref("BrowserCaptureMediaStreamTrack.restrictTo", "restrictTo()")}} {{Experimental_Inline}}
+  - : Restricts a self-capture stream to a specific rendered restriction target element.


"a specific rendered restriction target element" is a mouthful. What do we lose if we just say "a specific part of the DOM"?

Nothing. Updated!

wbamberg · 2025-02-05T01:04:13Z

files/en-us/web/api/browsercapturemediastreamtrack/restrictto/index.md

+- 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 has clones or is not a track captured from the user's screen.
+- `RestrictionTarget` is not one of the values specified above.
+- `RestrictionTarget` was created in a tab other than the one being captured.


Similar questions as for cropTo().

Same updates made

wbamberg · 2025-02-05T01:17:28Z

files/en-us/web/api/restrictiontarget/fromelement_static/index.md

+    - Be rendered (for example, not be off-screen or hidden via `display: none`).
+    - Contain only one box fragment (for example, not be broken across multiple lines).
+
+      If it does not meet the above criteria, it is considered to be **not eligible for restriction**.


What if the element initially meets the requirements and then doesn't?

I've tested it — when the capture is underway and the element that is being captured suddenly can no longer be captured (e.g. display: none is set), no error is thrown, and the capture just freezes - it continues to show the last captured frame.

I guess this behavior might differ depending on how it became ineligible.

Do you think I need to mention this?

No I guess not. Weird though.

wbamberg · 2025-02-05T01:18:59Z

files/en-us/web/api/restrictiontarget/index.md

+
+{{APIRef("Screen Capture extensions")}}{{SeeCompatTable}}
+
+The **`RestrictionTarget`** interface of the {{domxref("Screen Capture extensions", "Screen Capture extensions", "", "nocode")}} provides a static method, {{domxref("RestrictionTarget.fromElement_static", "fromElement()")}}, which returns a `RestrictionTarget` instance that can be used to restrict a captured video track to a specified DOM element.


Suggested change

The **`RestrictionTarget`** interface of the {{domxref("Screen Capture extensions", "Screen Capture extensions", "", "nocode")}} provides a static method, {{domxref("RestrictionTarget.fromElement_static", "fromElement()")}}, which returns a `RestrictionTarget` instance that can be used to restrict a captured video track to a specified DOM element.

The **`RestrictionTarget`** interface of the {{domxref("Screen Capture extensions", "Screen Capture extensions", "", "nocode")}} provides a static method, {{domxref("RestrictionTarget.fromElement_static", "fromElement()")}}, which returns a `RestrictionTarget` instance that can be used to restrict a captured video track to a specified DOM element.

Suggested change

The **`RestrictionTarget`** interface of the {{domxref("Screen Capture extensions", "Screen Capture extensions", "", "nocode")}} provides a static method, {{domxref("RestrictionTarget.fromElement_static", "fromElement()")}}, which returns a `RestrictionTarget` instance that can be used to restrict a captured video track to a specified DOM element.

The **`RestrictionTarget`** interface of the {{domxref("Screen Capture extensions", "Screen Capture extensions", "", "nocode")}} API provides a static method, {{domxref("RestrictionTarget.fromElement_static", "fromElement()")}}, which returns a `RestrictionTarget` instance that can be used to restrict a captured video track to a specified DOM element.

(although of course see my other comment about not making this a standalone API...)

I moved it all over to the Screen Capture, so this is all good now.

wbamberg · 2025-02-05T01:19:32Z

files/en-us/web/api/restrictiontarget/index.md

+## Static methods
+
+- {{domxref("RestrictionTarget.fromElement_static", "fromElement()")}} {{Experimental_Inline}}
+  - : Returns a `RestrictionTarget` instance that can be used to crop a captured video track to a specified DOM element.


Suggested change

- : Returns a `RestrictionTarget` instance that can be used to crop a captured video track to a specified DOM element.

- : Returns a `RestrictionTarget` instance that can be used to restrict a captured video track to a specified DOM element.

wbamberg · 2025-02-05T01:20:41Z

files/en-us/web/api/screen_capture_extensions/index.md

+The Screen Capture API was created specifically to allow apps to capture the user's screen — or a particular window or tab — and then do something with the resulting stream (such as transmit it to multiple peers via [WebRTC](/en-US/docs/Web/API/WebRTC_API)). The main use case is video conferencing apps, where a user might wish to share a demo running on their local machine with other participants.
+
+The problem with the Screen Capture API is that, by default, it only allows you to broadcast the entire window, screen or tab selected by the user. Often it would be preferrable to share only a limited region to cut down on unnecessary bandwidth or screen space required to show the capture, or for privacy reasons (you might not want to show other participants your message notifications, or background settings required to run the demo you are sharing).
+
+The following Screen Capture API extensions provide mechanisms to limit the region captured in the stream:
+
+- The **Element Capture API** restricts the captured region to a specified rendered DOM element.
+- The **Region Capture API** crops the captured region to the area of the screen in which a specified DOM element is rendered.
+


Similar comments to those about the "Background" bit of the guide, as this is similar content.

This page no longer exists.

wbamberg · 2025-02-05T01:21:56Z

files/jsondata/GroupData.json

+        "CropTarget",
+        "RestrictionTarget"
+      ],
+      "methods": ["MediaDevices.getDisplayMedia()"],


It is weird I think (and might cause weird problems) to include an item in two different APIs.

this API entry no longer exists.

wbamberg · 2025-02-05T19:21:41Z

Thank you for the updates, Chris!

wbamberg

Thank you for those updates Chris! I just had a few more little bits.

wbamberg · 2025-02-05T23:20:36Z

files/en-us/web/api/screen_capture_api/element_region_capture/index.md

+}
+```
+
+1. Here, we start by grabbing the media stream as before, using, `mediaDevices.getDisplayMedia()`.


Suggested change

1. Here, we start by grabbing the media stream as before, using, `mediaDevices.getDisplayMedia()`.

1. Here, we start by grabbing the media stream as before, using `mediaDevices.getDisplayMedia()`.

wbamberg · 2025-02-05T23:25:15Z

files/en-us/web/api/croptarget/fromelement_static/index.md

+
+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 {{domxref("Window.postMessage()")}}, for example.


Yes, sorry about this! But please see also #36939 (comment).

wbamberg · 2025-02-05T23:28:33Z

files/en-us/web/api/screen_capture_api/element_region_capture/index.md

+
+- The element will not be cropped to if the track being cropped has clones or is not a track captured from the user's screen.
+- The element will not be captured if the `cropTarget` was created in a tab other than the one being captured.
+- Because Region Capture 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 stream.


This is not a restriction, so doesn't belong in the list. It's actually the key fact about the RC API, and I feel it is a little buried here.

I've moved these details to the CropTarget: fromElement() static method page, and put it as a standalone point in the page intro.

wbamberg · 2025-02-05T23:29:12Z

files/en-us/web/api/screen_capture_api/element_region_capture/index.md

+
+## When to use each API
+
+As explained above, Element Capture captures the element itself (and its descendants), whereas Region Capture captures the area of the browser tab defined by the bounding box of the target element. Element Capture will always show just the captured element, even if other DOM content overlaps it, whereas Region Capture can result in overlapping content being shown over the top of the content you intended to share.


Suggested change

As explained above, Element Capture captures the element itself (and its descendants), whereas Region Capture captures the area of the browser tab defined by the bounding box of the target element. Element Capture will always show just the captured element, even if other DOM content overlaps it, whereas Region Capture can result in overlapping content being shown over the top of the content you intended to share.

Element Capture captures the element itself (and its descendants), whereas Region Capture captures the area of the browser tab defined by the bounding box of the target element. Element Capture will always show just the captured element, even if other DOM content overlaps it, whereas Region Capture can result in overlapping content being shown over the top of the content you intended to share.

(I don't think that phrase really adds anything, and it's a bit vague - where is it explained? It's fine to repeat key messages and we don't need to apologize for that :))

Yeah, I agree. This bit got removed anyway, when I moved this section up to the top of the article. It really didn't make sense up there ;-)

wbamberg · 2025-02-05T23:29:56Z

files/en-us/web/api/screen_capture_api/element_region_capture/index.md

+
+## See also
+
+- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API)


Suggested change

- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API)

(don't need this link any more, we are already here)

wbamberg · 2025-02-05T23:31:07Z

files/en-us/web/api/screen_capture_api/index.md


+## Screen Capture extension interfaces
+


Suggested change

## Screen Capture extension interfaces

I think it is better just to present these as interfaces. I don't think anyone really cares that they are defined in a separate specification, at least not to the extent that it merits a separate top-level heading here.

OK, I've deleted the heading, and put the interfaces in a single list.

wbamberg · 2025-02-05T23:32:05Z

files/en-us/web/api/screen_capture_api/index.md

@@ -24,11 +31,29 @@ The {{jsxref("Promise")}} returned by `getDisplayMedia()` resolves to a {{domxre

 See the article [Using the Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API/Using_Screen_Capture) for a more in-depth look at how to use the API to capture screen contents as a stream.

+## Screen Capture extensions


Again I would not have this as a separate section. I think the developers this is just part of the SC API.

OK, updated

wbamberg · 2025-02-05T23:37:43Z

files/en-us/web/api/browsercapturemediastreamtrack/clone/index.md

+> [!NOTE]
+> When attempting to crop a captured stream using {{domxref("BrowserCaptureMediaStreamTrack.cropTo", "cropTo()")}} or restrict it using {{domxref("BrowserCaptureMediaStreamTrack.restrictTo", "restrictTo()")}}, elements will not be cropped or restricted to if the track being captured has clones.


Should we instead say something like: "If a track has clones, its cropTo() and restrictTo() will reject with an error." I think this is clearer than "elements will not be cropped or restricted to".

Also I couldn't see a source for this in the specification.

See https://developer.chrome.com/docs/web-platform/element-capture#restricting and https://developer.chrome.com/docs/web-platform/region-capture#cropping. I don't think it is in the spec, rather it is a current technical limitation they are trying to work around. But I'm not sure if it is helpful to separate this information out as a result.

Thanks for the info! It's usually our practice to distinguish between restrictions that are intentional per spec and browser bugs, and I think we ought to do that here, too.

wbamberg · 2025-02-05T23:39:49Z

files/en-us/web/api/restrictiontarget/fromelement_static/index.md

+    - Be rendered (for example, not be off-screen or hidden via `display: none`).
+    - Contain only one box fragment (for example, not be broken across multiple lines).
+
+      If it does not meet the above criteria, it is considered to be **not eligible for restriction**.


No I guess not. Weird though.

wbamberg · 2025-02-05T23:45:26Z

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

+
+## The Region Capture API
+
+The Region Capture API has a very similar effect to the Element Capture API, except that rather than restricting the captured region to a specific rendered DOM tree, it crops the stream to the area of the current browser tab defined by the bounding box of the target element. Let's look at a demo and then explore the differences between the two in more detail later on.


The reason I'm suggesting this is that it's easier, cognitively, on the reader. Otherwise I'm thinking: here are 2 similar APIs, that have some unknown difference, and I have to keep that unanswered question in my head while I'm reading all the demo, until the "reveal" at the end. It's like a puzzle, where I have to work out what the difference is, then I get the answer at the end.

If I get the reveal at the start, then I know what the difference is, and the analysis/walkthrough is all just confirmation, I just nod as I read through.

wbamberg

Thank you Chris for your patience as always! I'm approving this because it's 99% there and I don't want to block on another round of timezones. I do think it is worth separating out the "clones" limitation from those that are per-spec - for instance having a note like "Note than in Chromium, ... " and linking to the bug. But I don't think it's a blocker, and happy for you to merge either way.

chrisdavidmills · 2025-02-07T11:15:14Z

Thank you Chris for your patience as always! I'm approving this because it's 99% there and I don't want to block on another round of timezones. I do think it is worth separating out the "clones" limitation from those that are per-spec - for instance having a note like "Note than in Chromium, ... " and linking to the bug. But I don't think it's a blocker, and happy for you to merge either way.

Thanks so much @wbamberg for the thorough review. You've helped make this much better.

I've moved the clone restriction info into notes in appropriate places as suggested.

Time to merge!

Adding landing page for Screen Capture extrensions

6edd354

chrisdavidmills requested review from a team as code owners November 23, 2024 16:52

chrisdavidmills requested review from sideshowbarker and bsmth and removed request for a team November 23, 2024 16:52

chrisdavidmills marked this pull request as draft November 23, 2024 16:52

github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Nov 23, 2024

Add usage guide

3e80b04

chrisdavidmills mentioned this pull request Nov 25, 2024

Add DOM examples for Screen Capture API mdn/dom-examples#285

Merged

Add reference pages

bc36f1c

github-actions bot added size/l [PR only] 501-1000 LoC changed and removed size/m [PR only] 51-500 LoC changed labels Nov 26, 2024

chrisdavidmills marked this pull request as ready for review November 26, 2024 14:58

chrisdavidmills added 3 commits November 26, 2024 14:58

Merge branch 'main' into region-and-element-capture

96bc1f5

Fix a couple of flaws

27e5207

Merge branch 'region-and-element-capture' of github.com:chrisdavidmil…

536f60a

…ls/content into region-and-element-capture

chrisdavidmills mentioned this pull request Nov 26, 2024

Chrome 132 supports Element Capture API mdn/browser-compat-data#25232

Merged

beaufortfrancois reviewed Nov 27, 2024

View reviewed changes

Fixes for beaufortfrancois review comments

5c20d74

beaufortfrancois reviewed Nov 29, 2024

View reviewed changes

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md Outdated Show resolved Hide resolved

chrisdavidmills added 2 commits November 29, 2024 11:00

remove audio: false,

2e95813

Make it clearer that preferCurrentTab is a hint

cb3315e

wbamberg removed request for sideshowbarker and bsmth December 11, 2024 17:02

chrisdavidmills added 2 commits January 27, 2025 07:43

Merge branch 'main' into region-and-element-capture

fc26a2d

Fix respective use cases content

24d1675

eladalon1983 reviewed Jan 29, 2025

View reviewed changes

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md Outdated Show resolved Hide resolved

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md Outdated Show resolved Hide resolved

chrisdavidmills added 2 commits January 29, 2025 18:31

Merge branch 'main' into region-and-element-capture

6f3f1f7

Fixes for last few eladalon comments

b8dac53

chrisdavidmills requested a review from eladalon1983 January 29, 2025 18:55

Merge branch 'main' into region-and-element-capture

8ad73f5

chrisdavidmills changed the title ~~Add documentation for Screen Capture extensions, element capture and region capture~~ Editorial review: Add documentation for Screen Capture extensions, element capture and region capture Feb 4, 2025

eladalon1983 reviewed Feb 4, 2025

View reviewed changes

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md Outdated Show resolved Hide resolved

Tighten up prose; remove screen versus tab confusion

a419c6d

wbamberg requested changes Feb 5, 2025

View reviewed changes

chrisdavidmills mentioned this pull request Feb 5, 2025

Remove logging code from screen capture demos mdn/dom-examples#294

Open

Fixes for wbamberg review comments

fa7a504

chrisdavidmills requested a review from wbamberg February 5, 2025 19:11

wbamberg requested changes Feb 5, 2025

View reviewed changes

Second round of fixes for wbamberg review comments

57dafb6

chrisdavidmills requested a review from wbamberg February 6, 2025 10:20

wbamberg approved these changes Feb 6, 2025

View reviewed changes

Separate out browser-specific limitations info

0ca8d4d

chrisdavidmills merged commit d9879ec into mdn:main Feb 7, 2025
9 checks passed

chrisdavidmills deleted the region-and-element-capture branch February 7, 2025 11:17


		## Screen Capture API demo

		This demo uses the Screen Capture API to capture a window, screen, or tab, and broadcast the stream via a {{htmlelement("video")}} element on the same page. It also logs the track settings and constraints to a log container below the main app.


		{{SeeCompatTable}}

		{{DefaultAPISidebar("Screen Capture extensions")}}{{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.


		{{APIRef("Screen Capture extensions")}}{{SeeCompatTable}}

		The `RestrictionTarget` interface of the {{domxref("Screen Capture extensions", "Screen Capture extensions", "", "nocode")}} provides a static method, {{domxref("RestrictionTarget.fromElement_static", "fromElement()")}}, which returns a `RestrictionTarget` instance that can be used to restrict a captured video track to a specified DOM element.

	- : Returns a `RestrictionTarget` instance that can be used to crop a captured video track to a specified DOM element.
	- : Returns a `RestrictionTarget` instance that can be used to restrict a captured video track to a specified DOM element.

	1. Here, we start by grabbing the media stream as before, using, `mediaDevices.getDisplayMedia()`.
	1. Here, we start by grabbing the media stream as before, using `mediaDevices.getDisplayMedia()`.


		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 {{domxref("Window.postMessage()")}}, for example.


		## When to use each API

		As explained above, Element Capture captures the element itself (and its descendants), whereas Region Capture captures the area of the browser tab defined by the bounding box of the target element. Element Capture will always show just the captured element, even if other DOM content overlaps it, whereas Region Capture can result in overlapping content being shown over the top of the content you intended to share.


		## See also

		- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API)

		@@ -24,11 +31,29 @@ The {{jsxref("Promise")}} returned by `getDisplayMedia()` resolves to a {{domxre

		See the article [Using the Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API/Using_Screen_Capture) for a more in-depth look at how to use the API to capture screen contents as a stream.

		## Screen Capture extensions

		> [!NOTE]
		> When attempting to crop a captured stream using {{domxref("BrowserCaptureMediaStreamTrack.cropTo", "cropTo()")}} or restrict it using {{domxref("BrowserCaptureMediaStreamTrack.restrictTo", "restrictTo()")}}, elements will not be cropped or restricted to if the track being captured has clones.


		## The Region Capture API

		The Region Capture API has a very similar effect to the Element Capture API, except that rather than restricting the captured region to a specific rendered DOM tree, it crops the stream to the area of the current browser tab defined by the bounding box of the target element. Let's look at a demo and then explore the differences between the two in more detail later on.

Editorial review: Add documentation for Screen Capture extensions, element capture and region capture #36939

Editorial review: Add documentation for Screen Capture extensions, element capture and region capture #36939

Conversation

chrisdavidmills commented Nov 23, 2024 • edited Loading

Description

Motivation

Additional details

Related issues and pull requests

github-actions bot commented Nov 23, 2024 • edited Loading

skyclouds2001 commented Nov 24, 2024

chrisdavidmills commented Nov 25, 2024

eladalon1983 left a comment

Choose a reason for hiding this comment

wbamberg commented Feb 4, 2025

wbamberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidmills Feb 5, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidmills Feb 5, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg commented Feb 5, 2025

wbamberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg Feb 5, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidmills commented Nov 23, 2024 •

edited

Loading

github-actions bot commented Nov 23, 2024 •

edited

Loading

chrisdavidmills Feb 5, 2025 •

edited

Loading

chrisdavidmills Feb 5, 2025 •

edited

Loading

wbamberg Feb 5, 2025 •

edited

Loading