系统媒体会话
本模块中的examples组件仅用于仓库本地开发功能验证,不随应用打包或导出。 当前媒体的读取与有限控制范围以本文为准,实际检查见实现说明(宿主文档:../implementation.md)。
权限与范围
media.get / media.control / media.artwork。这些方法为无需声明或授权的基础接口,用于当前系统媒体,并非组件自身音频。作者不能枚举播放器、指定 App ID、路径、原生对象或其他安装身份。封面、专辑元数据、时间轴与跳转接口见媒体补全。宿主不读取播放历史、源文件路径或其他进程信息;音量控制使用基础audio.output接口。
media.get {} 返回 {session:null} 或 {session:{sessionId,title,artist,playback,controls:{play,pause,next,previous}}}。title/artist 各最多 128 UTF-16 单元、过滤控制字符并不截断代理对;playback 为 closed/opened/changing/stopped/playing/paused/unknown。没有当前会话返回 null,API 失败返回 RESOURCE_UNAVAILABLE,不能用空字符串伪装系统失败。
media.control {sessionId,command} 返回 {accepted:boolean},command 接受 play/pause/next/previous,另有受范围约束的seek扩展,见媒体补全;不开放任意快捷键或Shell命令。命令对应系统支持标志,不支持返回 RESOURCE_UNAVAILABLE;accepted 仅表示系统接受请求,不保证播放器完成。命令使用最近读取的随机会话引用,属于当前实例与原文档,60 秒到期,每文档仅一份、全局最多 64 份。同文档新读取替换旧引用;主视图与附属视图的引用不能互用;不能猜测、跨实例或在重载、停用后复用。每次执行前检查系统当前会话仍为已捕获对象,切换后拒绝,不自动控制新的播放器。系统检查与远端副作用不能组成原子事务,已发出的操作不能撤回,但不会把请求重新指向新对象。
所有权、预算与取消
Services 保留实例/安装失效代次与命令额度;原生代理只接收实例资源键、有限请求和同步有效性回调,不包含服务模型。读取和控制在现有有界外部 IO 队列执行,不持 Services 事务锁。原生统一管理一份系统 SessionManager 与一秒采样缓存,无每实例采集线程或历史事件队列;没有有效引用时清除缓存/会话。后台沿用资源回收,每份引用持有原文档及生命周期有效性回调,停用后不会因重新启用复活;读取和控制均在每次操作及最终投递复核有效性。
原生最多一项系统调用在途,竞争返回 RESOURCE_UNAVAILABLE,不堆积等待锁。异步操作等待预算三秒,期间检查取消并 Cancel,不将该预算描述为 OS 调用硬时限。读取可每秒一次,UI 示例只在可见且未退出时每两秒刷新且最多一项在途,pagehide 取消。控制每安装一分钟最多 30 次、全局 120 次;合法保留额度后计数,系统拒绝不重试。执行和最终投递复核实例及文档。状态、引用不写磁盘、布局、配置、日志或存档;卸载释放资源,不改变播放器当前状态。
API 依据与验证
验证只向本次测试的受控发布者发送控制,不操作用户其他播放器;实际当前源不符时停止且不输出其元数据。服务测试覆盖无需授权、停用/重启、实例隔离、配额、取消和最终投递;注入后端不能当作真实系统媒体结果。
媒体遥控示例位于examples/media-remote:握手后即可读取,宿主及文档可见时每两秒最多一次自动刷新、最多一项在途。隐藏停止主动刷新,不支持的按钮禁用;所有按钮使用最近引用,切换失败要求刷新,不自动播放或控制。
作者页从握手前占用单个操作槽,每次await后检查取消及页面生命周期。读取失败释放会话引用,禁用控制;pagehide取消、解除监听并禁止新调用,迟到结果不得恢复页面或按钮。取消不能撤回已经发送的系统控制,原生执行及最终投递检查保持。
媒体遥控将本次控制回复与随后状态读取的结果分开反馈。页面已消费accepted回复后,即使后续读取失败,也保留“请求已接受”或“播放器未接受”,同时说明状态刷新失败;接受不代表播放已完成,不自动重发控制。读取失败仍释放会话引用、禁用控制,只能重新读取后再操作。本次反馈只属于当前操作,不沿用到下一次刷新;离开页面优先,迟到结果不得恢复反馈或会话。
媒体遥控在pagehide时同时禁用全部操作按钮、解除onclick处理器并释放当前会话引用;关闭后取得的旧事件回调不得改写标题/状态或触发刷新。已取得的旧按钮/显隐/定时回调也不得发出调用,迟到握手及在途结果保持丢弃。无需授权的读取/控制、自动刷新间隔和隐藏语义保持;关闭时不向系统发送播放或暂停指令。