远程播放 API

本地播放设备是浏览上下文运行所在的设备，以及该设备具有的默认视频/音频输出。

注

本地播放设备可能具有额外的输出，例如外部显示器或扬声器/耳机。只要使用何种输出的切换发生在用户代理之外的系统级别，就本规范而言，该播放就被视为发生在本地播放设备上。

远程播放设备是除本地播放设备之外，浏览上下文可用于播放媒体的任何其他设备。

媒体元素状态是单个媒体元素的所有属性的集合，这些属性可由页面和/或用户通过用户代理实现观察到。为方便起见，本规范引入的新属性不被视为媒体元素状态的一部分。

例如，paused 属性或媒体元素默认控件上反映该状态的暂停/继续按钮，都属于媒体元素状态的一部分。

本地播放状态是用户代理针对特定媒体元素状态的实现，用于在媒体元素的本地播放设备上进行播放。

远程播放状态是用户代理针对特定媒体元素状态的实现，用于在特定媒体元素的某个远程播放设备上进行播放。

注

为获得良好的用户体验，当媒体元素状态发生变化时，state 不应意外变化。同样重要的是，远程播放状态应与媒体元素状态保持同步，这样当媒体在远程播放设备上暂停时，对于用户和页面而言，它看起来都处于暂停状态。

本规范中提到的任务所使用的任务源是媒体元素事件任务源。

WebIDL[Exposed=Window]
interface RemotePlayback : EventTarget {
  Promise<long> watchAvailability(RemotePlaybackAvailabilityCallback callback);
  Promise<undefined> cancelWatchAvailability(optional long id);

  readonly attribute RemotePlaybackState state;

  attribute EventHandler onconnecting;
  attribute EventHandler onconnect;
  attribute EventHandler ondisconnect;

  Promise<undefined> prompt();
};

enum RemotePlaybackState {
  "connecting",
  "connected",
  "disconnected"
};

callback RemotePlaybackAvailabilityCallback = undefined(boolean available);

RemotePlayback 对象允许页面检测远程播放设备的可用性、连接到这些设备并控制其上的播放。

RemotePlaybackState 枚举表示与远程播放设备连接时可能的状态。

RemotePlaybackAvailabilityCallback 返回当前的远程播放设备可用性。

RemotePlaybackAvailabilityCallback 是页面获取相应媒体元素的远程播放设备可用性的方式。如果用户代理能够在后台监视可用远程播放设备列表（而无需等待对prompt() 的请求），则用户代理必须实现下文定义的 RemotePlaybackAvailabilityCallback 行为。否则， watchAvailability() 返回的 promise 必须以 NotSupportedError 拒绝。

用户代理必须跟踪通过 watchAvailability() 方法向每个媒体元素注册的可用性回调集合。每个 RemotePlayback 对象的可用性回调集合表示为一个元组集合 (callbackId, callback)，初始为空，其中：

callbackId 是一个正整数，在给定浏览上下文中所有由 watchAvailability() 返回的 id 中唯一；
callback 是一个RemotePlaybackAvailabilityCallback 对象。

由于每个媒体元素都有且只有一个RemotePlayback 对象，因此可用性回调集合与该元素的 remote 属性所引用的 RemotePlayback 对象的可用性回调集合是同一个集合。

浏览上下文所知的所有RemotePlayback 对象的所有可用性回调集合合并后的集合称为全局可用性回调集合。

用户代理必须维护一个可用远程播放设备列表。此列表包含远程播放设备，并根据特定于实现的发现机制进行填充。它被设置为监视可用远程播放设备列表算法的最新结果；如果该算法尚未运行，则为空列表。

用户代理可以不支持持续运行监视可用远程播放设备列表的算法，例如，由于平台或功耗限制。在这种情况下，由 watchAvailability() 返回的 promise 必须以 NotSupportedError 拒绝，全局可用性回调集合将为空，并且监视可用远程播放设备列表的算法将仅作为发起远程播放算法的一部分运行。

当全局可用性回调集合非空时，用户代理必须持续监视可用远程播放设备列表，以便页面可以跟踪通过已注册回调收到的最后一个值，从而仅在存在可用设备时提供远程播放。

注

为满足节能非功能性要求，用户代理应尽可能不监视可用远程播放设备列表。例如，当全局可用性回调集合为空时，或者当所有具有非空可用性回调集合的媒体元素所在页面均处于后台时，用户代理可能选择不运行监视算法。

某些远程播放设备可能由于功能、安全或硬件限制，只能播放一部分媒体资源。例如，只能渲染特定视频和/或音频格式的机顶盒、智能电视或联网扬声器。如果用户代理能够合理保证由某媒体资源指定的媒体能够在某设备上成功进行远程播放，我们就称该设备是该媒体资源的兼容远程播放设备。

注

用户代理可以使用 track 元素的srclang 属性作为文本轨道数据语言的提示，以帮助识别兼容远程播放设备。

用户代理为查找兼容远程播放设备而考虑过的某媒体元素的媒体资源称为可用性源集合。

某媒体元素中用于在选定远程播放设备上发起远程播放的媒体资源称为远程播放源。远程播放源必须属于该媒体元素的可用性源集合。

从可用性源集合中选择远程播放源的机制由具体实现决定，但用户代理应该将可用性源集合中的每个资源都视为潜在的远程播放源。

注

为选定设备选择远程播放源的算法取决于用户代理以及所支持的远程播放设备类型。例如，在媒体镜像情况下，用户代理只需遵循 HTMLMediaElement 的资源选择算法。但是，如果使用媒体远程传送或媒体投送，最佳媒体源可能取决于所选远程播放设备的获取和播放能力。

如果用户代理无法确定适用于远程播放设备的远程播放源，则建议用户代理将可用性源集合中所有资源的元数据（例如扩展 MIME 类型）发送给远程播放设备，使其可以运行自己的资源选择算法并选择远程播放源。

如果可用远程播放设备列表为空，或者其中没有任何设备与媒体元素的可用性源集合中的任何源兼容，则该媒体元素的远程播放是不可用的。否则，远程播放是可用的。对于某媒体元素，如果远程播放不可用，则设置为 false，如果可用，则设置为 true 的 boolean 称为该媒体元素的可用性。

如果用户代理停止监视可用远程播放设备列表（例如由于用户控制或为节省电量），它应该使用 false 调用全局可用性回调集合中的所有回调，以便页面可以适当地更新其用户体验。它还应该将所有媒体元素的可用性值设置为 false，以便如果用户代理稍后恢复监视可用远程播放设备列表，可用性信息能够正确传播。

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

输入: callback，将使用可用性信息调用的回调。
输出: promise，一个Promise。

令 promise 为一个新的Promise。
返回 promise，并运行以下步骤：
如果disableRemotePlayback 属性存在于媒体元素上，则以 InvalidStateError 拒绝 promise 并中止所有剩余步骤。
如果用户代理在浏览上下文的整个生命周期中都无法监视可用远程播放设备列表（例如，因为用户禁用了此功能），则并行运行以下步骤：
1. 兑现 promise。
2. 将一个任务排入队列，以使用 false 作为参数调用 callback。
3. 中止所有剩余步骤。
如果用户代理无法持续监视可用远程播放设备列表，但可以在发起远程播放时短暂执行，则：
1. 以 NotSupportedError 异常拒绝 promise。
2. 中止所有剩余步骤。
令 callbackId 为一个正整数，在该媒体元素的浏览上下文中，它在这些步骤之前返回的所有 callbackIds 中都是唯一的。
创建一个元组 (callbackId, callback)，并将其添加到此媒体元素的可用性回调集合中。
使用 callbackId 兑现 promise，并并行运行以下步骤：
1. 将一个任务排入队列，以使用该媒体元素当前的可用性作为参数调用 callback。
2. 如果用户代理当前未监视可用远程播放设备列表，则运行监视可用远程播放设备列表的算法。

注

为 callbackId 分配值的一种简单算法是为每个浏览上下文维护一个计数器，并在步骤 6 中递增该计数器。

注

为避免泄露可用于对用户进行指纹识别的信息，用户代理不应分配使用来自浏览器配置文件或远程播放设备的任何持久信息的 callbackId。

如果可用性回调集合非空，或者存在等待中的发起远程播放请求，则用户代理必须通过运行以下步骤来监视可用远程播放设备列表：

检索可用的远程播放设备（使用特定于实现的机制），并令 newDevices 为此列表。
对浏览上下文所知的每个媒体元素：
1. 如果disableRemotePlayback 属性存在于 mediaElement 上，则中止此元组的所有剩余步骤并继续处理下一个元组。
2. 将 newAvailabilityValue 设置为该媒体元素的可用性值，但在计算时使用 newDevices 列表，而不是可用远程播放设备列表。
3. 如果当前可用性不等于 newAvailabilityValue，则对于该元素可用性回调集合中的每个 (callbackId, callback)：
  1. 将一个任务排入队列，以使用 newAvailabilityValue 作为参数调用 callback。
将可用远程播放设备列表设置为 newDevices 的值。

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

输入: id，回调标识符。
输出: promise，一个Promise。

令 promise 为一个新的Promise。
返回 promise，并运行以下步骤：
如果disableRemotePlayback 属性存在于媒体元素上，则以 InvalidStateError 拒绝 promise，并中止所有剩余步骤。
如果参数 id 为 undefined，则清空可用性回调集合。
否则，如果 id 与可用性回调集合中任一条目的 callbackId 匹配，则从集合中移除该条目。
否则，以 NotFoundError 拒绝 promise，并中止所有剩余步骤。
如果可用性回调集合现在为空，并且没有等待中的发起远程播放请求，则为节省电量，取消任何等待中的监视可用远程播放设备列表的任务。
兑现 promise。

注

用于监视远程播放设备可用性，以及确定远程播放设备与所选可用性源集合兼容性的机制，由用户代理决定。

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

输入: 无，但该算法会引用媒体元素、其 remote 属性及其可用性源集合。
输出: 一个Promise。

令 promise 为一个新的Promise。
返回 promise，并并行继续运行这些步骤。
如果disableRemotePlayback 属性存在于媒体元素上，则以 InvalidStateError 拒绝 promise，并中止所有剩余步骤。
如果对于同一媒体元素，甚至同一浏览上下文，之前对 prompt() 的调用已经存在一个尚未敲定的 promise，则用户代理可以以 OperationError 异常拒绝 promise，并中止所有剩余步骤。

注

此处的理由是，用户代理可能会显示一个对媒体元素或浏览上下文而言是模态的对话框。在这种情况下，第二次调用 prompt() 将无法显示任何 UI。
如果文档的活动 window没有瞬态激活，则以 InvalidAccessError 异常拒绝 promise 并中止这些步骤。
可选地，如果用户代理预先知道此特定媒体元素的远程播放不可行（与当前state或可用远程播放设备列表无关），则以NotSupportedError 拒绝 promise，并中止所有剩余步骤。

注

这种情况的一个示例是，用户代理仅支持媒体投送，而媒体元素的源不是可以传递给远程播放设备的 URL。
如果用户代理需要显示可用远程播放设备列表，并且当前未监视可用远程播放设备列表，则并行运行监视可用远程播放设备列表的步骤。
如果远程播放不可用，并且在用户许可请求完成前仍将保持不可用，则以 NotFoundError 异常拒绝 promise，并中止所有剩余步骤。
请求用户许可，以更改远程播放状态。

注

请求许可的一种示例 UI 可以允许用户选择新的远程播放设备、在本地和远程播放设备之间切换，或者与远程播放设备断开连接。

注

用户可能已经为相关用途选择了远程播放设备，例如镜像显示器或当前页面的内容。在这种情况下，用户代理可以选择跳过用于选择设备的 UI，并立即继续下一步。
如果用户选择了一个远程播放设备 device 来发起远程播放，则用户代理必须运行以下步骤：
1. 将 remote 对象的state 设置为connecting。
2. 兑现 promise。
3. 将一个任务排入队列，以在remote 属性上触发一个事件，该事件名为 connecting，该属性属于媒体元素。该事件不得冒泡，不得取消，并且没有默认操作。
4. 为媒体元素与远程播放设备建立连接 device。
注

通过选择远程播放设备，用户即授予许可以使用该设备。
否则，如果用户选择与远程播放设备 device 断开连接，则用户代理必须运行以下步骤：
1. 兑现 promise。
2. 对 device 运行与远程播放设备断开连接算法。
否则，视为用户拒绝许可 使用该设备，因此以 NotAllowedError 异常拒绝 promise，并隐藏用户代理显示的 UI。

注

UI 和设备选择的实现细节由用户代理决定；例如，它可以向用户显示一个对话框，并允许用户选择可用设备（授予许可），或取消选择（拒绝许可）。在大多数情况下，可用设备会公布一个用户友好的名称，以及该名称的区域设置和文本方向信息。建议用户代理呈现此用户友好的名称，并在区域设置和文本方向已知时使用这些信息。

state 属性表示 RemotePlayback 连接的当前状态。根据连接状态，它可以取RemotePlaybackState 的以下值之一：

connecting 表示用户代理正在尝试与所选远程播放设备发起远程播放。这是 prompt() 返回的 promise 被兑现时的初始状态。在此状态下，媒体元素的本地播放会继续，并且媒体命令仍然作用于本地播放状态。
connected 表示从本地播放到远程播放的转换已经完成，所有媒体命令现在都作用于远程播放状态。
disconnected 表示远程播放尚未发起、发起失败或已经停止。所有媒体命令都将作用于本地播放状态。可以通过调用 prompt() 发起远程播放。

当用户代理要与远程播放设备建立连接时，它必须运行以下步骤：

输入: remote，要建立连接的RemotePlayback 对象。; device，要连接到的远程播放设备。

如果 remote 的state 不等于 "connecting"，则中止所有剩余步骤。
请求将 remote 连接到 device。此步骤的实现由用户代理决定。
如果连接成功完成，则将一个任务排入队列以运行以下步骤：
1. 将 remote 的state设置为 "connected"。
2. 在 remote 上触发一个事件，事件名为connect。
3. 将当前媒体元素状态与远程播放状态同步。此步骤的实现由用户代理决定。
如果连接失败，则将一个任务排入队列以运行以下步骤：
1. 将 remote 的远程播放状态设置为 "disconnected"。
2. 在 remote 上触发一个事件，事件名为disconnect。

当远程播放状态为 "connected" 时，用户代理应该暂停媒体元素的本地音频和视频输出。

如果用户代理正在为媒体元素向用户公开用户界面（即使用默认控件），则用户代理应该通过图标或其他方式传达远程播放状态为 "connected" 这一事实。

注

用于将用户代理与远程播放设备连接、选择远程播放源以及发起播放的机制，均由用户代理自行实现。该连接很可能必须提供一种双向消息抽象，能够将媒体命令传递到远程播放设备并接收媒体播放状态，从而保持媒体元素状态和远程播放状态同步（除非使用媒体镜像）。

注

建议用户代理尽可能将区域设置和文本方向信息传递给远程播放设备，以便远程播放设备能够调整其用户界面和操作功能，以适应反映用户偏好的特定于区域设置的属性。例如，远程播放设备可以使用该信息选择与用户代理相同的默认文本轨道，还可以设置它在获取媒体资源时发送的 HTTP Accept-Language 标头。

注

当媒体元素处于 "connected" 状态且其内容正在远程播放设备上渲染时，用户代理不应渲染该媒体元素的输出。

用户代理可以支持从浏览器连接到远程播放设备。这可以通过向向用户公开的用户界面添加适当的媒体控件，或者当用户激活系统范围的显示镜像时来实现。此功能称为浏览器发起的远程播放。支持浏览器发起的远程播放的用户代理应该仅在用户通过用户手势表达了这样做的意图时发起远程播放，例如点击浏览器中的按钮。

如果用户代理支持浏览器发起的远程播放，则 state 属性必须反映与远程播放设备连接的当前状态。当浏览器发起或终止远程播放时，它必须按照与远程播放设备建立连接以及与远程播放设备断开连接的算法触发相应事件。

如果浏览器将在新创建的媒体元素上发起远程播放，则它应该将其 state 属性的值初始化为 "connecting"，然后按照与远程播放设备建立连接的步骤操作。

注

实现浏览器发起的远程播放的用户代理应考虑它与影响媒体播放的其他浏览器策略之间的交互，例如哪些媒体元素被允许播放以及后台媒体播放优化。

一旦与远程播放设备的连接建立， HTMLMediaElement 接口就会与远程播放的媒体进行交互。

当 RemotePlayback 对象的state 为 "connected" 时，以下条件将本地播放状态、媒体元素状态和远程播放状态关联起来：

用户代理必须将关联的 HTMLMediaElement 对象上发出的所有媒体命令发送给远程播放设备，以更改其远程播放状态；
远程播放设备应该实现用户代理发送的所有媒体命令；
远程播放设备应该向用户代理发送远程播放状态的更新，这些更新会影响通过媒体元素状态公开的任何属性；
用户代理必须处理从远程播放设备接收到的所有远程播放状态更新，并相应更新媒体元素的本地播放状态。

如果发送任何命令失败，用户代理可以与远程播放设备断开连接。

注

远程播放设备可以仅实现用户代理播放引擎的一部分功能，并且某些HTMLMediaElement API 在远程播放期间并不总是适合使用。在这种情况下，在远程播放期间不受支持的媒体命令执行后，本地播放状态应尽可能准确地反映实际远程播放状态。

例如，当连接到不支持 fastSeek() 的远程播放设备时调用它， HTMLMediaElement 的 seeking 属性应保持为 false，并且不应触发任何 seeking 事件。

当用户代理要与远程播放设备断开连接时，它必须执行以下操作：

输入: remote，表示要停止的播放的RemotePlayback 对象。; device，要与之断开连接的远程播放设备。

如果 remote 的state 为 disconnected，则中止所有剩余步骤。
将一个任务排入队列以运行以下步骤：
1. 请求断开 remote 与 device 的连接。此步骤的实现由用户代理决定。
2. 将 remote 的 state 更改为 disconnected。
3. 在 remote 上触发一个事件，事件名为disconnect。
4. 将当前媒体元素状态与本地播放状态同步。此步骤的实现由用户代理决定。

如果远程播放设备在播放期间突然断开连接（例如由于断电或网络断开），用户代理应该先运行监视可用远程播放设备列表的步骤，再运行与远程播放设备断开连接的步骤。这使得可用性回调集合中的回调可以在触发 disconnect 事件之前被调用，从而使页面可以更新自身，以表明无法恢复播放。

注

当用户代理请求远程播放设备停止播放时，该设备实际上可能不会停止媒体播放；这取决于用户代理和远程播放设备的实现。在这种情况下，停止远程播放意味着用户代理仅与远程播放设备断开连接，而媒体元素切换到 disconnected 状态。

以下是实现 RemotePlayback 接口的对象必须作为事件处理程序 IDL 属性支持的事件处理程序（以及它们对应的事件处理程序事件类型）：

事件处理程序	事件处理程序事件类型
`onconnecting`	`connecting`
`onconnect`	`connect`
`ondisconnect`	`disconnect`

WebIDLpartial interface HTMLMediaElement {
  [SameObject] readonly attribute RemotePlayback remote;

  [CEReactions] attribute boolean disableRemotePlayback;
};

remote 属性必须返回与该媒体元素关联的RemotePlayback 实例。

某些页面可能希望禁用某个媒体元素的远程播放；例如，它们可能更愿意使用 PresentationRequest 在演示屏幕上呈现完整文档。为支持此用例，在 audio 和 video 元素的内容属性列表中添加了新的 disableRemotePlayback 属性。

对应的disableRemotePlayback IDL 属性会反映每个元素的 disableRemotePlayback 内容属性值，并被添加到 HTMLMediaElement 接口中。 disableRemotePlayback IDL 属性必须反映同名内容属性。

如果disableRemotePlayback 属性存在于媒体元素上，则用户代理不得远程播放该媒体元素，也不得提供任何用于执行此操作的 UI。

当disableRemotePlayback 属性被添加到媒体元素时，用户代理必须运行以下步骤来禁用远程播放：

以 InvalidStateError 拒绝所有由 RemotePlayback 方法返回的等待中 promise。
清空该媒体元素的可用性回调集合。
如果其 state 不是 disconnected，则对媒体元素已连接或正在连接的远程播放设备运行与远程播放设备断开连接算法。

远程播放 API

摘要

本文档的状态

1. 一致性

2. 引言

3. 用例和要求

4. 示例

4.1 监视远程播放设备可用性的示例

4.2 启动视频远程播放的示例

4.3 监视远程播放状态变化

5. API

5.1 常用惯用模式

5.2 `RemotePlayback` 接口

5.2.1 观察远程播放设备可用性

5.2.1.1 可用性回调集合

5.2.1.2 可用远程播放设备列表

5.2.1.3 获取远程播放设备可用性信息

5.2.1.4 监视可用远程播放设备列表

5.2.1.5 停止观察远程播放设备可用性

5.2.2 提示用户更改远程播放状态

5.2.3 `state` 属性

5.2.4 与远程播放设备建立连接

5.2.5 浏览器发起的远程播放

5.2.6 媒体命令和媒体播放状态

5.2.7 与远程播放设备断开连接

5.2.8 事件处理程序

5.3 对 `HTMLMediaElement` 的扩展

5.3.1 `disableRemotePlayback` 属性

5.3.2 禁用远程播放

6. 安全和隐私考虑

6.1 个人身份信息

6.2 用户界面指南

6.3 设备访问

6.4 本地与远程播放设备之间的消息传递

6.5 安全上下文

A. 候选推荐标准退出标准

B. 参考文献

B.1 规范性参考文献

B.2 资料性参考文献

远程播放 API

摘要

本文档的状态

1. 一致性

2. 引言

3. 用例和要求

4. 示例

4.1 监视远程播放设备可用性的示例

4.2 启动视频远程播放的示例

4.3 监视远程播放状态变化

5. API

5.1 常用惯用模式

5.2 RemotePlayback 接口

5.2.1 观察远程播放设备可用性

5.2.1.1 可用性回调集合

5.2.1.2 可用远程播放设备列表

5.2.1.3 获取远程播放设备可用性 信息

5.2.1.4 监视可用远程播放设备列表

5.2.1.5 停止观察远程播放设备可用性

5.2.2 提示用户更改远程播放状态

5.2.3 state 属性

5.2.4 与远程播放设备建立连接

5.2.5 浏览器发起的远程播放

5.2.6 媒体命令和媒体播放状态

5.2.7 与远程播放设备断开连接

5.2.8 事件处理程序

5.3 对 HTMLMediaElement 的扩展

5.3.1 disableRemotePlayback 属性

5.3.2 禁用远程播放

6. 安全和隐私考虑

6.1 个人身份信息

6.2 用户界面指南

6.3 设备访问

6.4 本地与远程播放设备之间的消息传递

6.5 安全上下文

A. 候选推荐标准退出标准

B. 参考文献

B.1 规范性参考文献

B.2 资料性参考文献

5.2 `RemotePlayback` 接口

5.2.1.3 获取远程播放设备可用性信息

5.2.3 `state` 属性

5.3 对 `HTMLMediaElement` 的扩展

5.3.1 `disableRemotePlayback` 属性