屏幕捕获

WebIDLpartial interface MediaDevices {
  Promise<MediaStream> getDisplayMedia(optional DisplayMediaStreamOptions options = {});
};

getDisplayMedia

提示用户许可以实时捕获其显示屏。

用户代理必须让最终用户每次从所有可用选项中选择要共享的显示界面，并且不得使用 options.video 或 options.audio 中的任何 MediaTrackConstraints 来限制该选择。

用户代理可以使用 displaySurface 限制的存在及其值来影响向用户展示的源选择。 但用户代理必须仍然为用户提供无限制的显示表面选择。强烈建议用户代理引导用户避免共享整个显示器， 因为这会对用户隐私构成 风险。

options.video 或 options.audio 中的任何 MediaTrackConstraints 必须仅在用户做出选择后应用于用户选择的媒体。

对于音频，用户代理可以向最终用户呈现可供共享的音频源。具体有哪些选项可供选择由用户代理决定，并且音频源不一定与视频源相同。音频源可以是特定的窗口、浏览器、整个系统音频或其任意组合。与 getUserMedia() 在音频+视频方面不同，即使用户指定了音频约束，用户代理也允许不返回音频。如果用户代理知道在流的生命周期内不会共享任何音频，则它不得在结果流中包含音轨。用户代理可以接受音频和视频请求，并在结果流中仅返回视频轨道，或者它可以接受请求，并在结果流中同时返回音轨和视频轨道。用户代理必须拒绝纯音频请求。

除了从不同的源集合中提取并需要用户选择之外，getDisplayMedia 与 getUserMedia() 的不同之处还在于“granted”权限不能被持久化。

当调用 getDisplayMedia() 方法时，用户代理必须运行以下步骤：

1. 令 mediaDevices 为this。

2. 令 controller 为 options.controller（如果存在），否则为 null。

3. 如果 controller 不为 null，则运行以下步骤：

   1. 如果 controller.[[IsBound]] 为 true，则返回一个 rejected 的 promise，其值为一个 DOMException 对象，该对象的 name 属性值为 InvalidStateError。

   2. 将 controller.[[IsBound]] 设置为 true。

4. 如果this的相关全局对象没有瞬时激活，则返回一个 rejected 的 promise，其值为一个 DOMException 对象，该对象的 name 属性值为 InvalidStateError。

5. 令 options 为该方法的第一个参数。

6. 令 constraints 为 [options.audio, options.video]。

7. 如果 constraints.video 为 false，则返回一个 rejected 的 promise，其值为一个新创建的 TypeError。

8. 对于 constraints 中每个值为字典 CS 的现有成员，运行以下步骤：

   1. 如果 CS 包含名为 advanced 的成员，则返回一个 rejected 的 promise，其值为一个新创建的 TypeError。

   2. 如果 CS 包含一个成员，其名称指定了适用于显示界面的可约束属性，并且其值又是一个包含名为 min 或 exact 的成员的字典，则返回一个 rejected 的 promise，其值为一个新创建的 TypeError。

   3. 如果 CS 包含一个成员，其名称指定了适用于显示界面的可约束属性，并且其值又是一个包含名为 max 的成员的字典，并且该成员的值又小于该可约束属性的下限值，则令 failedConstraint 为该成员的名称，令 message 为 undefined 或一个信息性的人类可读消息，并返回一个 rejected 的 promise，其值为通过调用 OverconstrainedError(failedConstraint, message) 创建的新 OverconstrainedError。

9. 令 requestedMediaTypes 为 constraints 中值为字典或 true 的媒体类型集合。

10. 如果当前设置对象的相关全局对象的关联 Document 不是完全激活的或没有获得焦点，则返回一个 rejected 的 promise，其值为一个 DOMException 对象，该对象的 name 属性值为 InvalidStateError。

11. 令 p 为一个新的 promise。

12. 并行运行以下步骤：

    1. 对于 requestedMediaTypes 中的每种媒体类型 T，

       1. 如果没有类型为 T 的可用源，则在用户交互任务源上排队一个任务以 reject p，其值为一个新的 DOMException 对象，该对象的 name 属性值为 NotFoundError，并中止这些步骤。

       2. 读取当前浏览上下文中获取类型为 T 的源的当前权限状态。如果权限状态为“denied”，则跳转到下面标记为权限失败的步骤。

    2. 可选地，例如，基于先前建立的用户偏好、出于安全原因或由于平台限制，跳转到下面标记为权限失败的步骤。

    3. 提示用户选择一个显示设备，其 PermissionDescriptor 的 name 设置为 "display-capture"，从而产生一组提供的媒体。

       提供的媒体必须精确包含一个视频轨道。

       提供的媒体必须最多包含一个音轨。如果在 requestedMediaTypes 中未指定音频，或者指定为 false，则不得包含此音轨。

       选择的设备必须是用户确定的设备。一旦选定，MediaStreamTrack 的源不得更改，除非用户通过与用户代理的交互允许更改。

       鼓励用户代理警告用户不要共享浏览器显示设备以及可见浏览器窗口的显示器显示设备，或者以这些设备共享时风险显著更高为由，尽量阻止用户选择它们。

       如果请求的结果是“granted”，则对于提供媒体的每个设备，使用该设备的稳定且私有的 id deviceId，将 [[devicesLiveMap]][deviceId] 设置为 true（如果尚未为 true），并将 [[devicesAccessibleMap]][deviceId] 设置为 true（如果尚未为 true）。

       用户代理不得存储“granted”权限条目。

       如果结果是“denied”，则跳转到下面标记为权限失败的步骤。如果用户从未响应，则此算法在此步骤暂停。

       如果用户授予权限但硬件错误（例如操作系统/程序/网页锁定）阻止访问，则在用户交互任务源上排队一个任务以 reject p，其值为一个新的 DOMException 对象，该对象的 name 属性值为 NotReadableError，并中止这些步骤。

       如果结果是“granted”但设备访问因上述未列出的任何其他原因失败，则在用户交互任务源上排队一个任务以 reject p，其值为一个新的 DOMException 对象，该对象的 name 属性值为 AbortError，并中止这些步骤。

    4. 令 stream 为一个 MediaStream 对象。

    5. 对于用户授予权限的每个 source，运行以下步骤：

       1. 令 track 为使用 source 和 mediaDevices 创建 MediaStreamTrack 的结果。

       2. 将 track 添加到 stream 的轨道集中。

       3. 使用 source 和 mediaDevices 将轨道源绑定到 MediaDevices。

    6. 使用适当的约束对 stream 中的所有轨道运行应用约束算法。如果此操作失败，则令 failedConstraint 为失败算法的结果，令 message 为 undefined 或一个信息性的人类可读消息，然后在用户交互任务源上排队一个任务以 reject p，其值为通过调用 OverconstrainedError(failedConstraint, message) 创建的新 OverconstrainedError，并中止这些步骤。

    7. 现在认为 getDisplayMedia() 的这次调用产生了一个新的捕获会话。

    8. 在用户交互任务源上排队一个任务以运行以下步骤：

       1. 如果 controller 不为 null，则运行以下步骤：

          1. 将 controller.[[Source]] 设置为 stream 的视频轨道的 [[Source]]。

          2. 将 controller.[[DisplaySurfaceType]] 设置为 stream 的视频轨道的 DisplayCaptureSurfaceType。

       2. 将最后激活时间戳设置为当前高精度时间。

       3. 用 stream resolve p。

    9. 如果 controller 不为 null，则在用户交互任务源上排队一个任务以在 controller 上运行最终确定焦点决策算法。

    10. 中止这些步骤。

    11. 权限失败：在用户交互任务源上排队一个任务以 reject p，其值为一个新的 DOMException 对象，该对象的 name 属性值为 NotAllowedError。

13. 返回 p。

当顶层文档失去焦点时，对该文档及其嵌套浏览上下文的文档中的所有 CaptureController 对象运行以下步骤：

1. 如果 [[Source]] 是 undefined，则中止这些步骤。

2. 将 [[FocusChangeDisabled]] 设置为 true。

用户代理 不得 捕获部分透明的已捕获 显示表面 背后的内容。

对于新创建的 MediaStreamTrack，用户代理不得捕获显示给用户的提示。

未当前显示在屏幕上的信息 应当 在捕获中被模糊处理，除非应用程序已被特别授权访问该内容（例如，通过 提升的权限 等方式）。

用户代理 不得 在没有 用户主动同意 的情况下共享音频，例如当捕获一个 窗口 的视频伴随捕获整个系统的音频，包括与该窗口无关的应用程序时。

共享的显示表面可能会因操作系统或用户代理采取的操作而暂时或永久变得无法访问。显示表面被视为不可访问的具体情况不在本规范范围内，但示例可能包括监视器断开连接、窗口或浏览器关闭或最小化，或由于电话上的来电导致。

当显示界面进入不一定永久的不可访问状态时，用户代理必须在用户交互任务源上排队一个任务，该任务将相应媒体轨道的静音状态设置为 true。

当显示界面退出不可访问状态并变为可访问时，用户代理必须在用户交互任务源上排队一个任务，该任务将相应媒体轨道的静音状态设置为 false。

当显示界面进入永久的不可访问状态（例如源窗口关闭）时，用户代理必须在用户交互任务源上排队一个任务，该任务将结束相应的媒体轨道。

刚刚由getDisplayMedia 返回的流可能包含默认静音的轨道。属于同一流的音频和视频轨道可以独立静音或取消静音。

不接受源选择的约束意味着getDisplayMedia 仅提供指纹信息，暴露是否存在音频、视频或音视频显示源。

请注意，接受displaySurface约束不会限制用户选择。

约束在 getDisplayMedia 中的作用与它们在 getUserMedia() 中的作用不同。 它们不辅助发现，而是在用户选择之后才应用。

本节定义了哪些约束适用于 getDisplayMedia 轨道； 为 getUserMedia() 定义的约束除非在此处列出，否则不适用。

其中一些约束启用了用户代理处理，例如缩减采样和帧抽取，以及特定于显示的功能。 其他约束则能够以功能和设置的形式观察用户选择的 显示界面的固有属性。

定义了以下新的和现有的 MediaStreamTrack 可约束属性以应用于用户选择的视频显示界面，其行为如下：

以下新的和现有的 MediaStreamTrack 可约束属性被定义为应用于用户选择的音频源，其行为如下：

当用户选择的显示界面的底层源的固有属性发生更改时（例如，响应最终用户调整捕获窗口的大小），并且这些更改导致一个或多个可约束属性的功能和/或设置过时，用户代理必须在用户交互任务源上排队一个任务以运行以下步骤：

1. 同时更新所有受影响的可约束属性。

   如果这导致“过度约束”的情况，那么用户代理必须忽略造成过度约束的约束，只要它们继续过度约束。用户代理不得使音轨静音。

WebIDLenum CaptureStartFocusBehavior {
                  "focus-capturing-application",
                  "focus-captured-surface",
                  "no-focus-change"
                };

WebIDL[Exposed=Window, SecureContext]
interface CaptureController : EventTarget {
  constructor();
  undefined setFocusBehavior(CaptureStartFocusBehavior focusBehavior);
};

WebIDLenum SelfCapturePreferenceEnum {
  "include",
  "exclude"
};

WebIDLenum SystemAudioPreferenceEnum {
  "include",
  "exclude"
};

WebIDLenum WindowAudioPreferenceEnum {
  "system",
  "window",
  "exclude"
};

WebIDLenum SurfaceSwitchingPreferenceEnum {
  "include",
  "exclude"
};

WebIDLenum MonitorTypeSurfacesEnum {
  "include",
  "exclude"
};

WebIDLdictionary DisplayMediaStreamOptions {
  (boolean or MediaTrackConstraints) video = true;
  (boolean or MediaTrackConstraints) audio = false;
  CaptureController controller;
  SelfCapturePreferenceEnum selfBrowserSurface;
  SystemAudioPreferenceEnum systemAudio;
  WindowAudioPreferenceEnum windowAudio;
  SurfaceSwitchingPreferenceEnum surfaceSwitching;
  MonitorTypeSurfacesEnum monitorTypeSurfaces;
};

WebIDLpartial dictionary MediaTrackSupportedConstraints {
  boolean displaySurface = true;
  boolean logicalSurface = true;
  boolean cursor = true;
  boolean restrictOwnAudio = true;
  boolean suppressLocalAudioPlayback = true;
};

WebIDLpartial dictionary MediaTrackConstraintSet {
  ConstrainDOMString displaySurface;
  ConstrainBoolean logicalSurface;
  ConstrainDOMString cursor;
  ConstrainBoolean restrictOwnAudio;
  ConstrainBoolean suppressLocalAudioPlayback;
};

WebIDLpartial dictionary MediaTrackSettings {
  DOMString displaySurface;
  boolean logicalSurface;
  DOMString cursor;
  boolean restrictOwnAudio;
  boolean suppressLocalAudioPlayback;
  double screenPixelRatio;
};

WebIDLpartial dictionary MediaTrackCapabilities {
  DOMString displaySurface;
  boolean logicalSurface;
  sequence<DOMString> cursor;
};

WebIDLenum DisplayCaptureSurfaceType {
                  "monitor",
                  "window",
                  "browser"
                };

WebIDLenum CursorCaptureConstraint {
                  "never",
                  "always",
                  "motion"
                };

此 API 将每个潜在的捕获源都视为一个离散的媒体源。但是，显示捕获源不得由 enumerateDevices() 枚举，因为这会泄露过多关于主机系统的信息。

因此，显示捕获源无法通过 deviceId 约束进行选择，因为它们的 deviceId 未公开。

捕获 逻辑显示表面 会导致有可能共享用户未意识到的内容。一个 逻辑显示表面 可能会呈现用户不打算公开的信息。如果这些信息是可见的，用户更容易识别出来。这些方法对机器可能无效，但人类接收者不太可能处理仅短暂出现的内容。

建议将当前未渲染到屏幕上的信息在捕获时遮蔽，除非应用程序已通过 提升权限 专门授权访问该内容。

如何捕获 逻辑显示表面 的遮蔽区域以生成 可见显示表面 捕获 可以 变化。一些应用程序，如演示软件，受益于将遮蔽部分的屏幕渲染为在遮蔽之前出现的图像。冻结图像可能会导致动态内容的视觉伪影，或隐藏内容被遮蔽的事实。请注意，捕获的冻结部分可能被错误地认为是错误。或者，遮蔽区域可能被替换为标记其被遮蔽的内容，例如灰色或阴影。

一些系统可能仅捕获 逻辑显示表面。例如，具有小屏幕的设备通常没有 窗口 的概念，并且仅以全屏模式呈现应用程序。这些系统可能会提供对当前不可见的应用程序的捕获，如果不捕获 逻辑显示表面，则可能无法使用。

当捕获部分透明的 窗口 或其他 显示表面 时，任何后面的内容将不会被捕获。

存在这样一种风险，即用户提示可能会通过新创建的 MediaStreamTrack 短暂地暴露给网页， 例如，如果用户选择了显示用户提示的屏幕。在用户提示显示可供选择的各种界面的预览的情况下，这些预览将不会被新创建的 MediaStreamTrack 捕获。

本文档鼓励实现提供额外的限制，以加强用于确认用户同意的机制。这些限制旨在减轻 API 带来的安全和隐私风险。

描述了两种形式的同意交互：主动用户同意 和一系列 提升权限。这些仅为非规范性建议。

建议实现提供类似于用户在共享摄像头或麦克风时所提供的用户反馈和控制机制，正如 [GETUSERMEDIA] 中所鼓励的。

用户在内容被积极捕获时了解内容正在被共享是非常重要的。用户代理 建议在内容被捕获时显示显著的指示器。除了指示器外，建议 用户代理 提供一种方法，精确了解正在共享的内容；虽然应用程序通过呈现捕获的内容可以轻松提供此功能，但此信息允许用户准确评估正在共享的内容。

除了反馈机制外，还建议提供一种方法让用户停止任何活动的捕获。