远程播放 API

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

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

输入

无，但算法涉及媒体元素、其 remote 属性及其 可用性资源集合。

输出

一个 Promise。

1. 令 promise 为一个新的 Promise。
2. 返回 promise 并继续并行执行下列步骤。
3. 如果该 disableRemotePlayback 属性存在于 媒体元素 上，则拒绝 promise，抛出 InvalidStateError， 并终止所有剩余步骤。
4. 如果此前针对同一个 媒体元素 或同一 浏览上下文 有未决的 prompt() promise，用户代理可以用 OperationError 拒绝 promise 并终止所有剩余步骤。
   注

   设计理由：用户代理可能会出现一个只在媒体元素或整个浏览上下文独占的对话框。在这种情况下，如果调用了第二次 prompt() 则无法再弹出新的 UI。
5. 如果文档的 活动窗口 没有 瞬时激活，用 InvalidAccessError 拒绝 promise 并终止这些步骤。
6. 可选：如果用户代理已知某些 媒体元素远程播放不可行（不关联当前 state 或 可用远程播放设备列表），用 NotSupportedError 拒绝 promise 并终止所有剩余步骤。
   注

   例如，只支持 媒体推送 时，媒体元素的 source 不是能传递给 URL 的远程设备。
7. 如果用户代理需要显示 可用远程播放设备列表，且未监控远程播放设备列表，则应并行运行上述监控算法。
8. 如果远程播放 不可用，且在请求用户权限结束前仍不可用，则用 NotFoundError 拒绝 promise，并终止所有剩余步骤。
9. 请求用户更改远程播放状态的许可。
   注

   示例 UI 如允许用户选择新的 远程播放设备、在本地/远程设备间切换，或断开远程播放设备连接。
   注

   用户可能因其它目的已选择某 远程播放设备，如镜像屏幕或页面内容，用户代理可跳过设备选择 UI 直接进入下一步。
10. 如果用户选择了某个 远程播放设备 device 并 发起远程播放，用户代理 必须 依次执行下述步骤：
    1. 将 remote 对象的 state 设为 connecting。
    2. 标记 promise 完成。
    3. 排队任务，在媒体元素的 remote 属性上 派发名为 connecting 的事件，事件不冒泡且不可取消，无默认动作。
    4. 为该 媒体元素 建立与远程播放设备的连接 device。
    注

    选择 远程播放设备 即表示用户授权使用该设备。

11. 否则如果用户选择断开 远程播放设备 device，用户代理 必须 执行以下步骤：
    1. 标记 promise 完成。
    2. 对该 device 执行 断开远程播放设备连接 算法。
12. 否则，视为用户拒绝授权使用该设备，用 NotAllowedError 拒绝 promise 并隐藏用户代理展示的 UI。

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

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

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

输入

remote，要连接的 RemotePlayback 对象。

device，要连接的 远程播放设备。

1. 如果 remote 的 state 不为 "connecting"，中止所有剩余步骤。
2. 请求将 remote 连接到 device。此步骤的具体实现由用户代理决定。
3. 如果连接成功，排队任务 执行下列操作：
   1. 将 remote 的 state 设为 "connected"。
   2. 派发事件，事件名为 connect，对象为 remote。
   3. 同步当前 媒体元素状态 与 远程播放状态。具体由用户代理实现。
4. 如果连接失败，排队任务 执行下列操作：
   1. 将 remote 的 remote playback state 设为 "disconnected"。
   2. 派发事件，事件名为 disconnect，对象为 remote。

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

如果用户代理为媒体元素 暴露了用户界面（如用默认控件），则 应 通过图标或其他方式展示其 远程播放状态为 "connected"。

用户代理可以支持通过浏览器连接到远程播放设备。如可在 暴露给用户的界面 中添加合适控件，或当开启系统级镜像时进行。此功能称为 浏览器发起远程播放。支持此能力的用户代理 应 仅在用户有明确意图（如点击浏览器按钮）时才发起远程播放。

若用户代理支持 浏览器发起远程播放， state 属性必须反映与 远程播放设备 的当前连接状态。浏览器发起或终止远程播放时，必须按本规范相关算法派发事件。

若 浏览器即将发起媒体元素远程播放， 应先将其 state 初始化为 "connecting"，然后启动与远程播放设备的连接流程。

HTMLMediaElement 接口在与 远程播放设备 建立连接后即与远程媒体交互。

当 state 为 "connected" 时，下述规则关联 本地播放状态、媒体元素状态 和 远程播放状态：

• 用户代理 必须 将 HTMLMediaElement 对象的所有媒体命令发送给 远程播放设备 ，以修改其 远程播放状态；
• 远程播放设备 应 实现用户代理发送的所有媒体命令；
• 远程播放设备 应 向用户代理发送 远程播放状态 的最新信息，以反映通过 媒体元素状态 暴露的任何属性变更；
• 用户代理 必须 处理从 远程播放设备 接收到的所有 远程播放状态 更新，并相应更新媒体元素的 本地播放状态。

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

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

输入

remote，即要停止播放的 RemotePlayback 对象。

device，即要断开的 远程播放设备。

1. 如果 remote 的 state 为 disconnected，终止后续所有步骤。
2. 排队一个任务 执行下列步骤：
   1. 请求将 remote 从 device 断开。此步骤的实现由用户代理具体决定。
   2. 更改 remote 的 state 为 disconnected。
   3. 派发事件，事件名为 disconnect，目标为 remote。
   4. 同步当前 媒体元素状态 和 本地播放状态。此步骤实现由用户代理决定。

如果远程播放设备在播放过程中被突然断开（例如断电或网络中断），用户代理应当先运行监控可用远程播放设备列表的步骤，然后再运行 断开远程播放设备连接的步骤。这样可确保在 disconnect 事件派发前，先唤起 可用性回调集合，便于页面更新提示用户无法恢复播放。

下列表格为实现 RemotePlayback 接口的对象必须支持的事件处理器 及其对应的 事件类型，作为 事件处理器 IDL 属性：

某些页面可能希望禁用远程播放 某个媒体元素，例如他们更希望通过 PresentationRequest 在展示屏上展示整个文档。为支持该场景，audio 和 video 元素的内容属性列表增加了一个新的 disableRemotePlayback 属性。

同时，disableRemotePlayback IDL 属性新增到 HTMLMediaElement 接口，用于反映各元素 disableRemotePlayback 内容属性的取值。 disableRemotePlayback IDL 属性 必须 反映同名内容属性的值。

如果 disableRemotePlayback 属性存在于 媒体元素 上，则用户代理 不得 远程播放该媒体元素，也不得展示相关的 UI。

当 disableRemotePlayback 属性添加到 媒体元素 时，用户代理必须执行 禁用远程播放的操作：

1. 拒绝所有待处理的 RemotePlayback 方法返回的 promise，异常类型为 InvalidStateError。
2. 清空该媒体元素的 可用性回调集合。
3. 如果其 state 不是 disconnected，则为该媒体元素处于连接或连接中状态的 远程播放设备 执行 断开远程播放设备连接 算法。