用途
该技能面向桌面应用开发者,目标是把应用接入各操作系统的“正在播放”面板与硬件/媒体键传输控制,并用一个统一门面(facade)屏蔽平台差异。三个平台各自暴露不同的接口:macOS 通过媒体播放器框架的信息中心(info centre)与命令中心(command centre),Windows 通过系统传输控件,Linux 通过会话总线(session-bus)媒体接口。
主要能力
- 在播放器处理器中用一个门面统一三种后端,由平台自行选择实现。
- Linux 与 Windows 共用一个跨平台后端,macOS 使用独立实现。
- 提供“正在播放”信息更新与远程命令处理(媒体键、面板按钮、进度滑块拖动)。
- 集成本身可被禁用:原生初始化失败时返回 null,应用其余部分不受影响。
使用方式
门面形态依赖两条规则:
- 原生初始化失败返回 null,不抛异常,例如
runCatching { CrossPlatformNowPlaying(platform) }.getOrNull()。 - 每个调用点都做空安全处理(如
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 界面逐一触发每个远程命令(媒体键、面板按钮、拖动面板位置滑块);位置命令携带其他命令没有的负载,是最容易单独失效的一个。
- 让应用空闲数分钟后按媒体键;启动后立即有效、稍后失效,说明回调引用被丢弃。