视口捕获

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

getViewportMedia

提示用户授予对视口（当前标签页）进行实时捕获的权限。

用户代理 MUST 在权限 被授予后，将任何提供的 options 应用于所产生的媒体。

对于音频，如果可用，用户代理 MAY 向最终用户提供一个 用于在捕获中包含来自 当前视口音频的选项。与 getDisplayMedia() 关于 音频+视频的情况一样，即使存在音频约束，用户代理也可以不返回音频。如果 用户代理知道在流的整个生命周期内都不会共享音频，则它 MUST NOT 在结果流中包含音频轨道。用户代理 MAY 接受对音频 和视频的请求，但在结果流中只返回视频 轨道；或者它 MAY 通过在结果流中 同时返回音频轨道和视频 轨道来接受该请求。用户代理 MUST 拒绝仅音频 请求。

与 getDisplayMedia() 一样， “granted” 权限不能被持久化。

当调用 getViewportMedia() 方法时，用户代理 MUST 运行以下 步骤：

1. 如果 当前 设置对象的 跨源 隔离能力为 false，则返回一个使用 DOMException 对象 拒绝的 promise，该对象的 name 属性的值为 SecurityError。

2. 如果 相关 全局对象的 关联 Document 的 顶级 浏览上下文的 required document policy 不包含 Require-Document-Policy: viewport-capture 和 Document-Policy: viewport-capture （TODO：使用正确的算法），则返回一个使用 DOMException 对象 拒绝的 promise，该对象的 name 属性的值为 SecurityError。

3. 如果 相关 全局对象（属于 this）没有 瞬态 激活，则返回一个使用 拒绝的 promise，其拒绝理由为一个 DOMException 对象，该对象的 name 属性的值为 InvalidStateError。

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

5. 如果 options.video 为 false，则返回一个使用新 创建的 TypeError 拒绝的 promise。

6. 对 options 中每个值 CS 为字典的 存在的成员，运行以下步骤：

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

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

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

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

8. 如果 相关 全局对象的 关联 Document不是 完全 活跃的，或 没有 获得焦点，则返回 一个使用 DOMException 对象 拒绝的 promise，该对象的 name 属性的值为 InvalidStateError。

9. 令 p 为一个新的 promise。

10. 并行运行以下步骤：

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

       1. 如果没有可用的 T 类型源，则使用一个新的 DOMException 对象 拒绝 p，该对象的 name 属性的值为 NotFoundError。

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

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

    3. 请求 使用视口捕获的权限，针对一个 PermissionDescriptor， 其 name 设置为 "viewport-capture"， 产生一组提供的 媒体。

       所提供的媒体 MUST 精确包含一个视频 轨道，该轨道 MUST 是 相关 全局对象的 关联 Document 的 顶级 浏览上下文的 视口的 浏览器 显示 表面 的实时捕获。

       所提供的媒体 MUST 最多包含一个音频 轨道；如果提供，则该轨道 MUST 是由一组文档产生的组合 音频之和，这组文档包括 相关 全局对象的 关联 Document 的 顶级 浏览上下文的 活动 文档，以及 相关 全局对象的 关联 Document 的 顶级 浏览上下文中嵌套 浏览 上下文内的所有 活动 文档。如果未在 requestedMediaTypes 中指定音频，或如果 音频被指定 为 false，则该音频轨道 MUST NOT 被包含。

       MediaStreamTrack 的源 MUST NOT 改变。

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

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

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

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

       如果结果为“granted”， 但设备访问因上述原因之外的任何原因失败，则使用一个新的 DOMException 对象 拒绝 p，该对象的 name 属性的值为 AbortError， 并中止这些步骤。

    4. 令 stream 为用户授予权限的 MediaStream 对象。

    5. 使用适当的约束，在 stream 中的所有轨道上运行 ApplyConstraints 算法。如果这失败，则令 failedConstraint 为失败算法的结果，并令 message 为 undefined 或一条信息性 的人类可读消息，然后使用新的 OverconstrainedError 拒绝 p，该错误通过调用 OverconstrainedError(failedConstraint, message) 创建。

    6. 令 videoTrack 为 stream 中的视频轨道。
    7. 将 videoTrack.[[Restrictable]] 设置为 true。

    8. 使用 stream 解决 p，并中止这些步骤。

    9. Permission Failure：使用一个新的 DOMException 对象 拒绝 p，该对象的 name 属性的值为 NotAllowedError。

11. 返回 p。

用户代理 MUST NOT 捕获位于部分透明的被捕获 显示表面背后的内容。

用户代理 MUST NOT 共享来自被捕获 标签页所发出音频之外的音频，并且 MUST NOT 共享整个系统的音频。

与 getViewportMedia 相关的约束只是 与 getDisplayMedia() 相关的那些约束，如 5.4 被捕获显示表面的可约束属性中所定义。

Viewport Capture 是一个 强大特性，其由 名称 "viewport-capture" 标识，并且需要 明确权限才能使用。

按照与 Permissions 规范集成的要求，本 规范定义了 以下内容：

权限状态 约束

此描述符的 权限状态的有效值为“prompt” 和 “denied”。 用户代理 MUST NOT 将此描述符的 权限状态设置为 “granted”。

本规范定义了一个 策略控制 特性，由字符串 "viewport-capture" 标识。 其 默认 允许列表为 "self"。