SuperAPI AI 工具集

desktop-system-media-integration

通用与其它

查看项目

更新于 10-17 16:16

技能介绍

用途

该技能面向桌面应用开发者,目标是把应用接入各操作系统的“正在播放”面板与硬件/媒体键传输控制,并用一个统一门面(facade)屏蔽平台差异。三个平台各自暴露不同的接口:macOS 通过媒体播放器框架的信息中心(info centre)与命令中心(command centre),Windows 通过系统传输控件,Linux 通过会话总线(session-bus)媒体接口。

主要能力

  • 在播放器处理器中用一个门面统一三种后端,由平台自行选择实现。
  • Linux 与 Windows 共用一个跨平台后端,macOS 使用独立实现。
  • 提供“正在播放”信息更新与远程命令处理(媒体键、面板按钮、进度滑块拖动)。
  • 集成本身可被禁用:原生初始化失败时返回 null,应用其余部分不受影响。

使用方式

门面形态依赖两条规则:

  1. 原生初始化失败返回 null,不抛异常,例如 runCatching { CrossPlatformNowPlaying(platform) }.getOrNull()。
  2. 每个调用点都做空安全处理(如 systemControls?.setNowPlaying(…)),null 仅表示应用没有系统媒体控制,播放器其他逻辑不变。

集成对象上的每个方法都重复守卫,因为初始化可能在对象已存在之后失败:

fun updateNowPlayingInfo(info: NowPlayingInfo) {
    if (!isSupported() || !initialized.get()) return
    try { … } catch (e: Exception) { Logger.e(TAG, "…", e) }
}

初始化时需询问平台而非假设主线程,并做线程跳转:

fun initialize(): Boolean {
    var result = false
    val reached = runCatching { MainQueue.runSync { result = initOnMainThread() } }
        .onFailure { Logger.e(TAG, "main-queue init threw: ${it.message}", it) }
        .getOrDefault(false)
    if (!reached) { Logger.e(TAG, "could not reach the main queue; integration stays disabled"); return false }
    return result
}

适用场景

需要在 macOS、Windows、Linux 桌面端提供系统级“正在播放”展示与媒体键控制的播放器类应用。

限制与陷阱

  • 主线程归属:main() 不一定是平台主线程。macOS 只在线程 0 注册命令处理器;打包启动器通常把线程 0 留给平台事件循环,JVM 在另一线程启动,因此依赖图在启动时构建的内容都不在主线程上。这解释了为何 gradle run 下正常、发布版却静默失效。
  • 死锁:同步派发到当前已所在的队列会死锁。先检查(Darwin 上 pthread_main_np() 在初始线程返回 1),若已在则直接内联执行。
  • 异常不得跨越原生边界:在工作块内捕获、暂存,派发返回后再在自己的侧抛出;异常逃逸进原生派发会终止进程。Windows 上每个导出入口点同样需要守卫。
  • 回调必须持有:OS 只保留函数指针。在注册函数内创建的回调对象在函数返回后即成垃圾,OS 之后(通常是用户首次按媒体键时)会调用已不存在对象的跳板。需用字段持有回调与交出的原生缓冲区,仅在 release() 中释放,且释放时先清除“正在播放”信息并禁用所有命令。
  • 框架字符串常量不等于字面名:部分解析为短属性名,部分为完整常量名。应从框架导出符号读取并解引用,不要硬编码猜测;记录解析失败的项,缺失的键会静默丢掉一个字段。
  • OS 布尔值是一字节:消息发送会提升它,传入语言级布尔会得到错误参数,需显式构造并按 int 传递。
  • Windows 先设媒体类型:类型未设置时面板只渲染应用名,没有标题或艺术家,属于一行顺序修复。
  • Windows 线程安排:Windows 集成需放在独立专用线程,避开 UI 工具包的事件线程,与 macOS 的规则相反;组件运行时初始化需容忍线程已以不同模式初始化,OS 媒体对象需存活整个进程生命周期而非每曲目。
  • 封面图是下载而非属性写入:在 UI 路径之外获取字节,按 URL 缓存,URL 未变则跳过;“正在播放”信息在每次进度更新时都会重写,未缓存的获取会在整首曲目期间重复。

验证方式

  • 测试打包后的应用,而非 gradle run,线程归属不同是此功能发布即坏的最常见原因。
  • 记录初始化运行所在线程以及是否需要主队列跳转。
  • 确认门面确实可选:grep -rn "<facadeField>" --include='*.kt' <src>,每个命中都必须是 ?. 或位于空检查内;一处未守卫的调用就会把已禁用的集成变成崩溃。
  • 从 OS 界面逐一触发每个远程命令(媒体键、面板按钮、拖动面板位置滑块);位置命令携带其他命令没有的负载,是最容易单独失效的一个。
  • 让应用空闲数分钟后按媒体键;启动后立即有效、稍后失效,说明回调引用被丢弃。