Document the Captured Surface Control API #39982

chrisdavidmills · 2025-06-18T14:09:52Z

Description

Chrome 136+ supports the Captured Surface Control API, another extension to the Screen Capture API. See https://chromestatus.com/feature/5092615678066688 for details of the addition.

This PR documents the new features, providing reference docs and a guide.

Motivation

Additional details

Related issues and pull requests

github-actions · 2025-06-18T14:12:22Z

Preview URLs (14 pages)

Flaws (3)

Note! 13 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/captured-surface-control
Title: Permissions-Policy: captured-surface-control directive
Flaw count: 3

unknown:
- No generic content config found
- no blog root
- no blog root

(comment last updated: 2025-06-24 09:42:07)

eladalon1983 · 2025-06-20T16:50:43Z

files/en-us/web/api/capturecontroller/forwardwheel/index.md

+### Parameters
+
+- `element`
+  - : A reference to the element whose captured `wheel` events you want to forward to the associated captured display surface.


The wheel events of that element are not the thing that is "captured". Rather, the wheel events are forwarded to the "captured" surface. (Same comment throughout.)

Ah, good catch. I've checked through the docs and edited them to make sure I'm not referring to captured wheel events here, or anywhere else.

eladalon1983 · 2025-06-20T16:52:15Z

files/en-us/web/api/capturecontroller/forwardwheel/index.md

+  - : Thrown when:
+    - The capturing {{domxref("MediaStream")}} returned by the originating {{domxref("MediaDevices.getDisplayMedia()")}} call is no longer capturing, for example because the associated {{domxref("MediaStreamTrack")}} objects have had {{domxref("MediaStreamTrack.stop", "stop()")}} called on them.
+    - The application is capturing itself.
+    - an attempt was made to invoke `forwardWheel()` without transient activation.


It is permissible to call forwardWheel() without transient activation, if the relevant permission is already "granted".

I've added something to the page to cover this:

The forwardWheel method must be invoked via transient activation, in which case the user is asked for permission to scroll the captured page. Specifically, the only events that can successfully invoke it are click and input. If the relevant permission is already "granted", transient activation is not needed.

I wonder if there is anything we need to say about this API in the Permissions API docs. Permissions API integration is not mentioned anywhere in the spec; just Permissions-Policy.

eladalon1983 · 2025-06-20T16:52:51Z

files/en-us/web/api/capturecontroller/forwardwheel/index.md

+
+```js
+videoElem.srcObject =
+  await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);


You can omit displayMediaOptions.

I've thought about this and elected to include the following at the start of each brief code snippet:

// Create controller and start capture const controller = new CaptureController(); videoElem.srcObject = await navigator.mediaDevices.getDisplayMedia({ controller, }); // ...

Just so that we show the context for the controller object then being used.

eladalon1983 · 2025-06-20T16:54:20Z

files/en-us/web/api/capturecontroller/getsupportedzoomlevels/index.md

+
+## Examples
+
+### Basic `getSupportedZoomLevels()` usage


The section title says getSupportedZoomLevels(), but the first API surface discussed is actually the event handler for "zoomlevelchange".

Good point. I've cut this down to just focus on the specific bit that uses getSupportedZoomLevels().

eladalon1983 · 2025-06-20T16:55:54Z

files/en-us/web/api/capturecontroller/getsupportedzoomlevels/index.md

+    incBtn.disabled = true;
+  }
+}
+```


You'd might want to mention that decreaseZoomLevel() and increaseZoomLevel() should still be called from a try-block, because the zoom level could be changed asynchronously by an entity other than the application; for example, by the user's direct interaction with the user agent,

Good call. I've updated the relevant functions in the guide to use try/catch, and added a note highlighting why you should do this. I've also added the code blocks and note to the reference pages where appropriate (so, this one, and the decreaseZoomLevel() and increaseZoomLevel() pages).

eladalon1983 · 2025-06-20T16:56:54Z

files/en-us/web/api/capturecontroller/resetzoomlevel/index.md

+
+### Basic `resetZoomLevel()` usage
+
+The following snippet adds an event listener to a button so that when it is clicked, the `resetZoom()` function is called. This in turn calls the `resetZoomLevel()` method, resetting the captured surface's zoom level.


You probably want to explain what "resetting" means in this context. Namely, that it sets the zoom level to 100.

Done. Added to this page, and the guide.

eladalon1983 · 2025-06-20T16:57:34Z

files/en-us/web/api/capturecontroller/zoomlevel/index.md

+
+When a captured display surface's zoom level changes, a {{domxref("CaptureController.zoomlevelchange_event", "zoomlevelchange")}} event fires on the controller, which can be used to run an event handler such as the following. This writes the updated zoom percentage to an output element of some kind.
+
+```js


This section is quite similar to another snippet above which also used the same event handler. (But maybe I am being confused by multiple documents being updated concurrently with roughly the same information.)

Yeah, it is used quite a lot. I've updated the wording on this page to at least make it more relevant to the zoomLevel property.

eladalon1983 · 2025-06-20T16:58:32Z

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

+
+{{EmbedLiveSample("surface-control-demo", , "500px", , , , "captured-surface-control")}}
+
+EDITORIAL: The demo works, but when you scroll the captured display surface, it crashes the browser tab.


Really?! Have you filed a Chromium bug? (If so, please assign it to me.)

Done: https://issues.chromium.org/issues/427295493.

I haven't assigned it to you because I don't think I have the permissions to do so. Mentioning @guidou so that it is handled while you are OOO.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

…x.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions · 2025-06-24T09:27:52Z

This pull request has merge conflicts that must be resolved before it can be merged.

…x.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions · 2025-06-24T09:28:57Z

files/en-us/web/api/mediadevices/getdisplaymedia/index.md

@@ -28,9 +28,8 @@ getDisplayMedia(options)
 - `options` {{optional_inline}}



[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

…/content into captured-surface-control

Document the Captured Surface Control API

e8ab23a

chrisdavidmills requested a review from a team as a code owner June 18, 2025 14:09

chrisdavidmills requested review from wbamberg and removed request for a team June 18, 2025 14:09

chrisdavidmills marked this pull request as draft June 18, 2025 14:09

github-actions bot added Content:WebAPI Web API docs size/s [PR only] 6-50 LoC changed labels Jun 18, 2025

Add remaining ref pages, fix guide

e1fb96a

github-actions bot added Content:HTTP HTTP docs size/l [PR only] 501-1000 LoC changed labels Jun 20, 2025

eladalon1983 reviewed Jun 20, 2025

View reviewed changes

chrisdavidmills marked this pull request as ready for review June 20, 2025 17:53

chrisdavidmills requested review from a team as code owners June 20, 2025 17:53

chrisdavidmills requested review from hamishwillee and dipikabh and removed request for a team June 20, 2025 17:53

chrisdavidmills and others added 3 commits June 24, 2025 10:25

Fixes for eladalon1983 review comments

c4ca2cc

Update files/en-us/web/api/mediadevices/getdisplaymedia/index.md

7b4eb9e

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update files/en-us/web/http/reference/headers/permissions-policy/inde…

d67aa8b

…x.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions bot added the merge conflicts 🚧 [PR only] label Jun 24, 2025

chrisdavidmills and others added 2 commits June 24, 2025 10:27

Update files/en-us/web/http/reference/headers/permissions-policy/inde…

5638096

…x.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update files/en-us/web/http/reference/headers/permissions-policy/inde…

c8a9c16

…x.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions bot added the size/xs [PR only] 0-5 LoC changed label Jun 24, 2025

github-actions bot reviewed Jun 24, 2025

View reviewed changes

Merge branch 'main' into captured-surface-control

96642dc

github-actions bot removed the merge conflicts 🚧 [PR only] label Jun 24, 2025

chrisdavidmills added 2 commits June 24, 2025 10:39

Add display-capture permission to the embed iframe

ae145f5

Merge branch 'captured-surface-control' of github.com:chrisdavidmills…

14f73dc

…/content into captured-surface-control


		### Basic `resetZoomLevel()` usage

		The following snippet adds an event listener to a button so that when it is clicked, the `resetZoom()` function is called. This in turn calls the `resetZoomLevel()` method, resetting the captured surface's zoom level.


		When a captured display surface's zoom level changes, a {{domxref("CaptureController.zoomlevelchange_event", "zoomlevelchange")}} event fires on the controller, which can be used to run an event handler such as the following. This writes the updated zoom percentage to an output element of some kind.

		```js


		{{EmbedLiveSample("surface-control-demo", , "500px", , , , "captured-surface-control")}}

		EDITORIAL: The demo works, but when you scroll the captured display surface, it crashes the browser tab.

		@@ -28,9 +28,8 @@ getDisplayMedia(options)
		- `options` {{optional_inline}}

Document the Captured Surface Control API #39982

Are you sure you want to change the base?

Document the Captured Surface Control API #39982

Uh oh!

Conversation

chrisdavidmills commented Jun 18, 2025

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions bot commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jun 24, 2025

Uh oh!

github-actions bot Jun 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Jun 18, 2025 •

edited

Loading