Skip to content

Improve description of region capture API #2902

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve description of region capture API #2902

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion features/region-capture.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
name: Region capture
description: The `CropTarget` API crops an element from a video track derived from display-capture of the active browser tab. For example, you can crop out video conferencing during screen sharing.
description: |
Region Capture is an API for cropping video tracks derived from screen-capturing a tab.

The API consists of two parts.

First, a `CropTarget` object is minted from an HTMLElement `e`, representing an element within the captured tab.

Second, `cropTo()` is invoked on the video track, with the aforementioned `CropTarget` as input, after which frames deliver on that track will be cropped to `e`'s bounding box.

Calling `cropTo(null)` restores the track to its original, uncropped form.
Comment on lines +2 to +11
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wrote the original description. It's not great, but I don't think it's wrong. CropTarget is the unavoidable entry point, as far as I can tell.

Here are two new variations for your consideration. The first tries to illustrate the relationship between CropTarget and the video track:

Suggested change
description: |
Region Capture is an API for cropping video tracks derived from screen-capturing a tab.
The API consists of two parts.
First, a `CropTarget` object is minted from an HTMLElement `e`, representing an element within the captured tab.
Second, `cropTo()` is invoked on the video track, with the aforementioned `CropTarget` as input, after which frames deliver on that track will be cropped to `e`'s bounding box.
Calling `cropTo(null)` restores the track to its original, uncropped form.
description: The `CropTarget.fromElement()` static method selects an element to be cropped from a display-capture video track by the track's `cropTo()` method. For example, use it to crop out video conferencing controls during screen sharing.

This one throws up its hands and says, it's complicated:

Suggested change
description: |
Region Capture is an API for cropping video tracks derived from screen-capturing a tab.
The API consists of two parts.
First, a `CropTarget` object is minted from an HTMLElement `e`, representing an element within the captured tab.
Second, `cropTo()` is invoked on the video track, with the aforementioned `CropTarget` as input, after which frames deliver on that track will be cropped to `e`'s bounding box.
Calling `cropTo(null)` restores the track to its original, uncropped form.
description: The region capture API crops an element, such as an element containing video conferencing controls, from a captured video track.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The proposal is shorter and has some benefits, but I worry that it could be misunderstood, especially around the word "select". Calling CropTarget.fromElement() itself has no effect; one could call it multiple times with different inputs and see no change. It's only when the returned token is fed into cropTo() that an effect follows. If the suggestion could be modified to better reflect this, I think that would be best.

Copy link

@eladalon1983 eladalon1983 Apr 30, 2025 •
edited by foolip
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"crops an element ... from"

With this suggestion, I worry that the reader could get the impression that the element is removed from the capture, whereas it's actually everything else that gets removed.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With this suggestion, I worry that the reader could get the impression that the element is removed from the capture, whereas it's actually everything else that gets removed.

This is a very good worry because that's exactly how I misunderstood the feature!

I guess I'd rewrite it like this:

Suggested change
description: |
Region Capture is an API for cropping video tracks derived from screen-capturing a tab.
The API consists of two parts.
First, a `CropTarget` object is minted from an HTMLElement `e`, representing an element within the captured tab.
Second, `cropTo()` is invoked on the video track, with the aforementioned `CropTarget` as input, after which frames deliver on that track will be cropped to `e`'s bounding box.
Calling `cropTo(null)` restores the track to its original, uncropped form.
description: The region capture API crops captured video tracks to show only a selected element.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is better in some ways, but still a few issues:

  • "To only show a selected element" is wrong. That's actually what Element Capture does. Region Capture, on the other hand, uses the element's bounding box, but still shows occluding content. Play around with this demo, focusing on the buttons at the top, to see the difference between "cropping" and "restricting".
  • "Captured video tracks" might be a bit too novel (but I hesitate to use stronger language, for fear that the phrase might have unwittingly been coined by YHS). The word "captured" should bind to "tab" here. That is, we crop a video track that is the result of "capturing" a tab. Phrasing that refers to that would be better, imho.
  • Should "region capture" be capitalized, since it's a proper name? @foolip has mentioned that for the title you use different capitalization, but possibly not for the description?

Thank you for bearing with me here, and apologies for this taking a bit long; I have thrown a semicolon into this sentence as a token of my friendly intentions.

spec: https://w3c.github.io/mediacapture-region/
compat_features:
- api.BrowserCaptureMediaStreamTrack
Expand Down
Loading