-
Notifications
You must be signed in to change notification settings - Fork 22.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add new screen capture constraints and options (#22733)
* Add new screen capture constraints and options * Making fixes for beaufortfrancois comments * Making fixes for beaufortfrancois comments * Making fixes for wbamberg comments
- Loading branch information
1 parent
d05f7e9
commit 83eccbf
Showing
13 changed files
with
475 additions
and
75 deletions.
There are no files selected for viewing
63 changes: 63 additions & 0 deletions
63
files/en-us/web/api/capturecontroller/capturecontroller/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,63 @@ | ||
--- | ||
title: CaptureController() | ||
slug: Web/API/CaptureController/CaptureController | ||
page-type: web-api-constructor | ||
tags: | ||
- API | ||
- Constructor | ||
- Experimental | ||
- Reference | ||
browser-compat: api.CaptureController.setFocusBehavior | ||
--- | ||
|
||
{{APIRef("Screen Capture API")}}{{seecompattable}} | ||
|
||
The {{domxref("CaptureController")}} constructor creates a new `CaptureController` object instance. | ||
|
||
## Syntax | ||
|
||
```js-nolint | ||
CaptureController() | ||
``` | ||
|
||
### Parameters | ||
|
||
None. | ||
|
||
## Examples | ||
|
||
```js | ||
// Create a new CaptureController instance | ||
const controller = new CaptureController(); | ||
|
||
// Prompt the user to share a tab, window, or screen. | ||
const stream = | ||
await navigator.mediaDevices.getDisplayMedia({ controller }); | ||
|
||
// Query the displaySurface value of the captured video track | ||
const [track] = stream.getVideoTracks(); | ||
const displaySurface = track.getSettings().displaySurface; | ||
|
||
if (displaySurface == 'browser') { | ||
// Focus the captured tab. | ||
controller.setFocusBehavior('focus-captured-surface'); | ||
} else if (displaySurface == 'window') { | ||
// Do not move focus to the captured window. | ||
// Keep the capturing page focused. | ||
controller.setFocusBehavior('no-focus-change'); | ||
} | ||
``` | ||
|
||
## Specifications | ||
|
||
{{Specifications}} | ||
|
||
## Browser compatibility | ||
|
||
{{Compat}} | ||
|
||
## See also | ||
|
||
- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API) | ||
- {{domxref("MediaDevices.getDisplayMedia()")}} | ||
- [Better screen sharing with Conditional Focus](https://developer.chrome.com/docs/web-platform/conditional-focus/) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,66 @@ | ||
--- | ||
title: CaptureController | ||
slug: Web/API/CaptureController | ||
page-type: web-api-interface | ||
tags: | ||
- API | ||
- Interface | ||
- CaptureController | ||
- Reference | ||
- Experimental | ||
browser-compat: api.CaptureController | ||
--- | ||
|
||
{{APIRef("Screen Capture API")}}{{seecompattable}} | ||
|
||
The **`CaptureController`** interface provides methods that can be used to further manipulate a capture session separate from its initiation via {{domxref("MediaDevices.getDisplayMedia()")}}. | ||
|
||
A `CaptureController` object is associated with a capture session by passing it into a {{domxref("MediaDevices.getDisplayMedia", "getDisplayMedia()")}} call as the value of the options object's `controller` property. | ||
|
||
## Constructor | ||
|
||
- {{ domxref("CaptureController.CaptureController", "CaptureController()") }} | ||
- : Creates a new `CaptureController` object instance. | ||
|
||
## Instance methods | ||
|
||
- {{ domxref("CaptureController.setFocusBehavior", "setFocusBehavior()") }} | ||
- : Controls whether the captured tab or window will be focused or whether the focus will remain with the tab containing the capturing app. | ||
|
||
## Examples | ||
|
||
```js | ||
// Create a new CaptureController instance | ||
const controller = new CaptureController(); | ||
|
||
// Prompt the user to share a tab, window, or screen. | ||
const stream = | ||
await navigator.mediaDevices.getDisplayMedia({ controller }); | ||
|
||
// Query the displaySurface value of the captured video track | ||
const [track] = stream.getVideoTracks(); | ||
const displaySurface = track.getSettings().displaySurface; | ||
|
||
if (displaySurface == 'browser') { | ||
// Focus the captured tab. | ||
controller.setFocusBehavior('focus-captured-surface'); | ||
} else if (displaySurface == 'window') { | ||
// Do not move focus to the captured window. | ||
// Keep the capturing page focused. | ||
controller.setFocusBehavior('no-focus-change'); | ||
} | ||
``` | ||
|
||
## Specifications | ||
|
||
{{Specifications}} | ||
|
||
## Browser compatibility | ||
|
||
{{Compat}} | ||
|
||
## See also | ||
|
||
- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API) | ||
- {{domxref("MediaDevices.getDisplayMedia()")}} | ||
- [Better screen sharing with Conditional Focus](https://developer.chrome.com/docs/web-platform/conditional-focus/) |
79 changes: 79 additions & 0 deletions
79
files/en-us/web/api/capturecontroller/setfocusbehavior/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,79 @@ | ||
--- | ||
title: CaptureController.setFocusBehavior() | ||
slug: Web/API/CaptureController/setFocusBehavior | ||
page-type: web-api-instance-method | ||
tags: | ||
- API | ||
- Experimental | ||
- Method | ||
- Reference | ||
- setFocusBehavior | ||
browser-compat: api.CaptureController.setFocusBehavior | ||
--- | ||
|
||
{{APIRef("Screen Capture API")}}{{seecompattable}} | ||
|
||
The {{domxref("CaptureController")}} interface's **`setFocusBehavior()`** method controls whether the captured tab or window will be focused when an associated {{domxref("MediaDevices.getDisplayMedia()")}} {{jsxref("Promise")}} fulfills, or whether the focus will remain with the tab containing the capturing app. | ||
|
||
You can set this behavior multiple times before the {{domxref("MediaDevices.getDisplayMedia()")}} call, or once immediately after its `Promise` resolves. After that, the focus behavior is said to be finalized, and can't be changed. | ||
|
||
## Syntax | ||
|
||
```js-nolint | ||
setFocusBehavior(focusBehavior) | ||
``` | ||
|
||
### Parameters | ||
|
||
- `focusBehavior` | ||
- : An enumerated value that describes whether the user agent should transfer focus to the captured display surface, or keep the capturing app focused. Possible values are `focus-captured-surface` (transfer focus) and `no-focus-change` (keep focus on the capturing app). | ||
|
||
### Return value | ||
|
||
None (`undefined`). | ||
|
||
### Exceptions | ||
|
||
- `InvalidStateError` {{domxref("DOMException")}} | ||
- : Thrown if: | ||
- The capture stream has been stopped. | ||
- The user chose to share a screen ({{domxref("MediaTrackSettings.displaySurface", "displaySurface")}} type `monitor`) rather than a `browser` tab or `window` — you can't focus a monitor. In this case the exception is thrown after the {{domxref("MediaDevices.getDisplayMedia()")}} `Promise` resolves. | ||
- Enough time has elapsed after the {{domxref("MediaDevices.getDisplayMedia()")}} `Promise` fulfills that the focus behavior has been finalized. | ||
|
||
## Examples | ||
|
||
```js | ||
// Create a new CaptureController instance | ||
const controller = new CaptureController(); | ||
|
||
// Prompt the user to share a tab, window, or screen. | ||
const stream = | ||
await navigator.mediaDevices.getDisplayMedia({ controller }); | ||
|
||
// Query the displaySurface value of the captured video track | ||
const [track] = stream.getVideoTracks(); | ||
const displaySurface = track.getSettings().displaySurface; | ||
|
||
if (displaySurface == 'browser') { | ||
// Focus the captured tab. | ||
controller.setFocusBehavior('focus-captured-surface'); | ||
} else if (displaySurface == 'window') { | ||
// Do not move focus to the captured window. | ||
// Keep the capturing page focused. | ||
controller.setFocusBehavior('no-focus-change'); | ||
} | ||
``` | ||
|
||
## Specifications | ||
|
||
{{Specifications}} | ||
|
||
## Browser compatibility | ||
|
||
{{Compat}} | ||
|
||
## See also | ||
|
||
- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API) | ||
- {{domxref("MediaDevices.getDisplayMedia()")}} | ||
- [Better screen sharing with Conditional Focus](https://developer.chrome.com/docs/web-platform/conditional-focus/) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.