Improve description of region capture API #2902
Conversation
github-actions
bot
added
the
feature definition
features/region-capture.yml
Outdated
| 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. |
There was a problem hiding this comment.
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:
| 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:
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
"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.
There was a problem hiding this comment.
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:
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Coming back to this after a long time; friendly intentions conveyed through punctuations are the best!
It seem like I made a pretty important error. Would this fix at least be an accurate description?
The region capture API captures the contents of a tab as a video track, optionally cropping to the bounding box of a given element. Any content that overlays that element is still included.
There was a problem hiding this comment.
FWIW, that suggestion works for me.
There was a problem hiding this comment.
Looking at https://w3c.github.io/mediacapture-region/ again I think it's still not quite right. navigator.mediaDevices.getDisplayMedia() is the API that can capture a whole tab, and region capture is a way of cropping to the bounding box of a given element. So maybe:
When using
navigator.mediaDevices.getDisplayMedia()to capture a browser tab as a video stream, the region capture API allows you to crop the video to the bounding box of a given element. In contrast to the element capture API, any content that overlays that element is also captured.
There was a problem hiding this comment.
Thanks @eladalon1983, finally I got it right :D
These are changes suggested by @eladalon1983 after I asked about the current description, which I thought seemed wrong in parts.