企业官网建设流程全解析

如何让网页音乐在锁屏播放：WebToApp Media Session桥与蓝牙耳机、车机接入教程

想在安卓手机上听网页音乐，却总遇到"锁屏就断音"的尴尬？WebToApp（开源 Web to APK 工具箱）内置的Media Session 桥（媒体会话集成）能把网页里的播放器接入安卓系统级媒体控制：锁屏媒体卡片、通知栏播放控件、蓝牙耳机切歌、车机 Android Auto 全部可用，而声音本身仍由网页播放，无需搬运音频流。本文面向新手，带你从零开启这项能力。

为什么网页音乐锁屏会停止播放？

普通"网页封装"应用只是套了一层 WebView。网页内的<audio>/<video>一旦没有向系统注册媒体会话（Media Session API），安卓就不知道"有音乐在放"：

• 锁屏界面上不出现播放卡片；
• 蓝牙耳机按键、车载面板无法控制播放；
• 切到后台或息屏后，系统可能回收播放资源导致断音。

WebToApp 的解决方案是 MediaSessionBridge.kt：在页面文档加载起始阶段注入脚本，把网页的navigator.mediaSession元数据（标题、艺术家、专辑、封面）和播放状态实时同步到原生MediaSession，再由 MediaSessionCore.kt 驱动系统通知与锁屏控件。

一键开启步骤：媒体会话桥开关

1. 在 WebToApp 中创建一个Web类型应用，填入音乐网站地址；
2. 进入「编辑通用配置」→特殊设置卡片；
3. 打开媒体会话集成（enableMediaSession）开关。

💡 对新建应用，该开关默认开启，属于安全体验特性之一——所以多数情况下你什么都不用改，直接导出 APK 即可。开关说明可参考官方文档 特殊设置。

导出后的应用行为：

保活由 WebMediaPlaybackService.kt 完成：播放时申请 CPU 唤醒锁并挂前台通知，暂停时释放，避免后台被系统杀进程。

蓝牙耳机与车机（Android Auto）接入

开启媒体会话后，无需任何额外配置即可获得硬件级控制：

🎧 蓝牙耳机 / 蓝牙音箱

• 播放中按下耳机键：播放/暂停
• 长按或双击（视耳机型号）：切歌、上一曲

🚗 车机 Android Auto

• 媒体卡片直接出现在车机媒体列表中，曲目名与封面来自网页播放器
• 方向盘按键控制播放/暂停，与系统音乐 App 体验一致

📱 手机侧

• 下拉通知栏即可 seek 进度、切换上下曲（前提是网页播放器本身支持这些操作，桥会按页面声明的能力动态显示按钮）

值得一提的是，桥接层做了"帧仲裁"：如果一个页面里同时存在多个播放源（例如主播放器 + 静音广告 iframe），只有真正出声且正在播放的帧才能获得会话控制权，避免静音广告抢占你的播放信息。

常见问题（FAQ）

Q1：为什么我的网站没有显示切歌按钮？网页播放器用navigator.mediaSession.setActionHandler()声明了哪些操作，桥才显示哪些按钮。只支持播放/暂停的站点就只有播放/暂停。

Q2：锁屏进度条不动或回跳？MediaSessionCore.kt 对位置做了插值处理，播放中会按上次锚点平滑推进，避免心跳刷新把进度条拉回旧值；若仍跳变，通常是网页自身进度上报稀疏所致。

Q3：视频网站能用吗？可以。HTML5 视频的元数据同样会被桥接，锁屏/车机可控制网页视频播放（含全屏视频的方向设置）。

写在最后

WebToApp 把"网页音乐 App 化"做成了开箱即用的体验：Media Session 桥默认开启，锁屏、耳机、车机控制零配置生效，背后由 WebMediaPlaybackService.kt 负责后台保活。更多桥接开关（剪贴板、分享、打印等）都在同一张"特殊设置"卡片中，详见 docs/zh/guide/app-actions/edit-common-config/ 文档目录。