屏幕捕获

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

getDisplayMedia

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

用户代理必须每次都让最终用户从所有可用选项中选择一个 显示表面 进行共享，并且不得 使用 MediaTrackConstraints 中的 options.video 或 options.audio 限制该选择。

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

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

对于音频，用户代理可以为最终用户提供可共享的音频源。哪些选项可供选择由用户代理决定， 而音频源不一定与视频源相同。音频源可以是某个 窗口、浏览器、整个系统音频或它们的任意组合。 与getUserMedia()不同，用户代理可以不返回音频，即使音频约束存在。如果用户代理知道在流的生命周期内不会共享音频， 它不得 在结果流中包含音轨。用户代理可以通过仅返回视频轨道接受音视频请求， 也可以通过返回音轨和视频轨道来接受请求。用户代理必须拒绝仅音频请求。

除源选择不同且需要用户选择外，getDisplayMedia() 与 getUserMedia() 的不同还在于 "granted" 权限无法持久化。

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

1. 令 mediaDevices 为 this。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

11. 令 p 为一个新的 promise。

12. 按以下步骤并行运行：

    1. 对于 requestedMediaTypes 中的每个媒体类型 T：

       1. 如果没有类型为 T 的来源，则用带有 DOMException 对象的 promise 拒绝 p，该对象的 name 属性值为 NotFoundError。

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

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

    3. 提示用户选择 一个显示设备，用于 PermissionDescriptor，其 name 设置为 "display-capture"，结果是提供的一组媒体。

       提供的媒体 MUST 包含一个视频轨道。

       提供的媒体 MUST 至多包含一个音频轨道。如果在 requestedMediaTypes 中没有指定音频，或其值为 false，则该音频轨道 MUST NOT 被包含。

       选择的设备 MUST 由用户确定。一旦选择了来源，MediaStreamTrack 的来源 MUST NOT 改变，除非用户通过其与用户代理的交互允许。

       鼓励用户代理警告用户不要共享 浏览器 显示设备或 显示器 显示设备，尤其是在浏览器窗口可见的情况下，或基于这些共享代表了显著更高的风险尝试阻止选择这些设备。

       如果请求的结果是 "granted"， 那么对于每个为提供的媒体提供来源的设备，使用设备的稳定且私有的 ID（deviceId）， 设置 [[devicesLiveMap]][deviceId] 为 true，如果它还没有设置为 true，并且将 [[devicesAccessibleMap]][deviceId] 设置为 true。

       用户代理 MUST NOT 存储 "granted" 权限条目。

       如果结果是 "denied"， 则跳转到标记为 Permission Failure 的步骤。如果用户从未响应，则该算法在此步骤停滞。

       如果用户授予了权限但由于硬件错误（如操作系统/程序/网页锁定）阻止访问，用带有新 DOMException 对象的 promise 拒绝 p，该对象的 name 属性值为 NotReadableError，并中止这些步骤。

       如果结果是 "granted"， 但设备访问由于上述原因以外的任何原因失败，用带有新 DOMException 对象的 promise 拒绝 p，该对象的 name 属性值为 AbortError，并中止这些步骤。

    4. 令 stream 为 MediaStream 对象。

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

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

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

       3. 将轨道来源与 MediaDevices 绑定，使用 source 和 mediaDevices。

    6. 对 stream 中的所有轨道运行 应用约束算法。 如果失败，令 failedConstraint 为失败的算法结果，令 message 为 undefined 或信息性的人类可读消息， 然后用新创建的 OverconstrainedError 拒绝 p，通过调用 OverconstrainedError(failedConstraint, message)。

    7. 此 getDisplayMedia() 调用现在被认为已经产生了一个新的 捕获会话。

    8. 如果 controller 不为 null，执行以下步骤：

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

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

       3. 排队一个任务，以在 controller 上运行 最终确定焦点决策算法。

    9. 解析 p 并中止这些步骤。

    10. Permission Failure：用新 DOMException 对象的 promise 拒绝 p，该对象的 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 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;
      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;
    };

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] 中所鼓励的。

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

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