利用捕获句柄改善标签页共享体验

François Beaufort
François Beaufort
GitHub
Elad Alon

浏览器支持

  • 102
  • 102
  • x
  • x

Web 平台现在附带有 Capture Handle，该机制有助于捕获和捕获 Web 应用之间的协作。捕获句柄允许捕获 Web 应用根据工效学而自信地识别捕获的 Web 应用（如果捕获的 Web 应用已选择启用）。

下面几个例子可以说明这样做的好处。

示例 1：如果视频会议 Web 应用截取的是演示文稿 Web 应用的呈现方式，那么视频会议 Web 应用可以向用户提供在幻灯片之间导航的控件。由于这些控件直接嵌入在视频会议 Web 应用中，因此用户无需重复切换“视频会议”标签页和“演示”标签页。减轻这一负担后，用户现在可以更专注于演示演示文稿的提供。

示例 2：当拍摄的 Surface 呈现回被拍摄的位置时，就会出现“镜厅”效果。值得注意的是，如果用户选择截取进行视频会议的标签页，而视频会议 Web 应用呈现本地预览，则会观察到这种可怕的效果。使用捕获句柄，您可以检测到自拍并减少自拍问题；例如，通过禁止本地预览的 Web 应用。

镜厅效果的插图

关于捕获句柄

捕获句柄由两个互补部分组成：

  • 捕获的 Web 应用可以选择使用 navigator.mediaDevices.setCaptureHandleConfig() 向某些源公开某些信息。
  • 然后，捕获 Web 应用便可以使用 getCaptureHandle() 对 MediaStreamTrack 对象读取该信息。

截取的一面

Web 应用可以公开信息，供即将捕获的 Web 应用使用。为此，它会使用包含以下成员的可选对象调用 navigator.mediaDevices.setCaptureHandleConfig()：

  • handle：可以是最多 1024 个字符的任意字符串。
  • exposeOrigin：如果为 true，则捕获的 Web 应用的来源可能会公开以捕获 Web 应用。
  • permittedOrigins：有效值包括 (i) 空数组、(ii) 包含单项 "*" 的数组或 (iii) 出发地数组。如果 permittedOrigins 由单个项 "*" 组成，则 CaptureHandle 可由所有捕获的 Web 应用观察。否则，只能捕获来源为 permittedOrigins 的 Web 应用。

以下示例展示了如何将随机生成的 UUID 作为句柄公开，并向任何捕获的 Web 应用公开源站。

const config = {
  handle: crypto.randomUUID(),
  exposeOrigin: true,
  permittedOrigins: ['*'],
};
navigator.mediaDevices.setCaptureHandleConfig(config);

请注意，捕获的 Web 应用不知道是否正在捕获它。除非也就是，捕获的 Web 应用使用 CaptureHandle 信息与捕获的 Web 应用建立通信（例如，通过工作器或共享云基础架构使用消息传递）。

截图中的一面

拍摄 Web 应用会存储视频 MediaStreamTrack，并可以通过对该 MediaStreamTrack 调用 getCaptureHandle() 来读取拍摄句柄信息。如果没有可用的捕获句柄，或不允许捕获的 Web 应用进行读取，此调用将返回 null。如果有捕获句柄，并且捕获的 Web 应用已添加到 permittedOrigins，此调用将返回包含以下成员的对象：

  • handle：由捕获的 Web 应用通过 navigator.mediaDevices.setCaptureHandleConfig() 设置的字符串值。
  • origin：捕获的 Web 应用的来源（如果 exposeOrigin 设置为 true）。否则，不会进行定义。

以下示例展示了如何从视频轨道中读取捕获句柄信息。

// Prompt the user to capture their display (screen, window, tab).
const stream = await navigator.mediaDevices.getDisplayMedia();

// Check if the video track is exposing information.
const [videoTrack] = stream.getVideoTracks();
const captureHandle = videoTrack.getCaptureHandle();
if (captureHandle) {
  // Use captureHandle.origin and captureHandle.handle...
}

通过监听 MediaStreamTrack 对象上的 "capturehandlechange" 事件来监控 CaptureHandle 更改。更改会在以下情况发生：

  • 捕获的 Web 应用会调用 navigator.mediaDevices.setCaptureHandleConfig()。
  • 跨文档导航发生在捕获的 Web 应用中。
videoTrack.addEventListener('capturehandlechange', event => {
  captureHandle = event.target.getCaptureHandle();
  // Consume new capture handle...
});

安全和隐私设置

从理论上说，如今，捕获和捕获的 Web 应用之间可以进行协作，例如在捕获的 Web 应用中嵌入“魔法像素”，或在视频流中嵌入二维码。捕获句柄提供了一种更简单、更可靠且更安全的机制。它还允许捕获的 Web 应用选择受众群体 - 选择来源或整个网络。

请注意，navigator.mediaDevices.setCaptureHandleConfig() 仅适用于安全浏览环境（仅限 HTTPS）中的顶级主框架。

示例

您可以通过在 Glitch 上运行示例来使用捕获手柄。请务必查看源代码。

样本歌曲

部分演示位于：

功能检测

如需检查 getCaptureHandle() 是否受支持，请使用以下命令：

if ('getCaptureHandle' in MediaStreamTrack.prototype) {
  // getCaptureHandle() is supported.
}

如需检查 navigator.mediaDevices.setCaptureHandleConfig() 是否受支持，请使用以下命令：

if ('setCaptureHandleConfig' in navigator.mediaDevices) {
  // navigator.mediaDevices.setCaptureHandleConfig() is supported.
}

后续步骤

下面简要介绍了在未来如何改进网络屏幕共享功能，让您先睹为快：

  • 区域捕获将允许剪裁来自当前标签页的显示捕获的视频轨道。
  • 条件焦点将允许捕获的 Web 应用指示浏览器将焦点切换到捕获的显示表面，或避免此类焦点更改。

反馈

Chrome 团队和网络标准社区希望了解您使用“捕获句柄”的体验。

向我们介绍设计

拍摄句柄是否有功能无法按预期运行？或者，您是否缺少实现自己的想法所需的方法或属性？对安全模型有疑问或意见？

  • 在 GitHub 代码库中提交规范问题，或者添加您对现有问题的看法。

实施时遇到问题？

您在 Chrome 的实现过程中是否发现了错误？或者，实现是否与规范不同？

  • 请前往 https://new.crbug.com 提交错误。请务必提供尽可能多的细节信息，并提供关于重现错误的简单说明。Glitch 非常适用于分享轻松快速的重现问题。

表示支持

您打算使用拍摄句柄吗？您的公开支持有助于 Chrome 团队确定各项功能的优先级，并向其他浏览器供应商展示支持这些功能的重要性。

请向 @ChromiumDev 发送 tweet 消息，告诉我们您在何处以及如何使用它。

致谢

感谢 Joe Medley 审核本文。