Skip to content

Add capture handle feature #2904

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

Add capture handle feature #2904

Show file tree
Hide file tree
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
3 changes: 1 addition & 2 deletions ...es/draft/spec/capture-handle-identity.yml → features/capture-handle.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
draft_date: 2024-09-09
name: Capture Handle - Bootstrapping Collaboration when Screensharing
name: Capture handle
Copy link

Choose a reason for hiding this comment

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

nit: Capitalize "Handle"

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Per https://github.com/web-platform-dx/web-features/blob/main/docs/guidelines.md we use sentence case for feature names, even though this sometimes looks funny. There's some discussion of it in #548.

description: TODO
Copy link

Choose a reason for hiding this comment

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

Suggested description:

Expose custom metadata to Web applications that capture this application using getDisplayMedia().

Copy link
Collaborator

@ddbeck ddbeck Apr 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

When it makes sense (I'm not versed enough in this feature to be sure), it's nice when the description name checks the entry point into the feature (i.e., the thing the developer types to "get" that feature). So maybe something like this?

The navigator.mediaDevices.setCaptureHandleConfig() method exposes metadata about the application, if the application is captured by another using getDisplayMedia().

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

The API requires using both navigator.mediaDevices.setCaptureHandleConfig() on the captured side and track.getCaptureHandle() on the capturing side. If we also want to mention getDisplayMedia(), that's a bit much IMHO.

How about:

The capture handle API allows you to share a custom handle (a string) from a web application being captured by getDisplayMedia() to the capturing web application.

It seems like the communication channel is through changing the handle, but that would be a one-way channel from the captured to capturing side. I don't understand how https://w3c.github.io/mediacapture-handle/identity/#use-case-1 is achieved, which would require a channel in the other direction.

@eladalon1983 is there something useful the description could say about the communication channel that capture handle establishes? And is it one-way from captured to capturing?

Copy link
Collaborator

Choose a reason for hiding this comment

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

Yes, I like what you're thinking here. I like the idea about being more direct about what exactly is passing between the two applications:

The capture handle API shares a string from a screen-captured web application with the capturing application.

I think part of the problem here is that the spec introduces some new terminology (a "handle"), which is hard to accommodate in a short description like this—we're not really in a position to teach a developer a new term, so it's probably best if we avoid it outside the feature's name, which basically means avoiding the API's names in general.

Copy link

Choose a reason for hiding this comment

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

Either of your descriptions works for me.

The use case you're asking about, @foolip, can be explained more easily with examples:

  1. Assume meet.google.com captures docs.google.com. They can communicate using pre-existing means, but without Capture Handle, how would Meet know (i) that it's capturing docs.google.com rather than foo.bar.com, or (ii) which of many open docs.google.com tabs the user chose? Cue Capture Handle...
  2. Assume dual-use.com/capturer is capturing dual-use.com/capturee-827273. It is able to communicate with a BroadcastChannel, but what is the name of the BC where the captured tab is expecting to be contacted?
  3. Assume another capturer/capturee pair where the capturer advertises the address of some cloud service, and an unguessable token that it knows only a capturer would be able to read, which it will require as part of the custom handshake protocol.

That is, the use case assumes the collaborating capturer/capturee need some help for the handshake, but the communication itself will happen outside of Capture Handle.

spec: https://w3c.github.io/mediacapture-handle/identity/
compat_features:
Expand Down
2 changes: 1 addition & 1 deletion ...aft/spec/capture-handle-identity.yml.dist → features/capture-handle.yml.dist
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Generated from: capture-handle-identity.yml
# Generated from: capture-handle.yml
# Do not edit this file by hand. Edit the source file instead!

status:
Expand Down