Media Session API 是原生 Web API,用于在系统通知栏、锁屏或任务管理器中显示媒体控件与元数据,需用户手势触发初始化,设置 metadata 和 actionHandler 后方可生效,并支持动态更新播放状态与进度。

Media Session API 允许网页在系统通知栏(Android)、锁屏界面(iOS)或任务管理器(桌面端)中显示媒体控件与元数据,比如播放/暂停按钮、歌曲标题、艺术家、专辑封面等。它不依赖特定框架,是原生 Web API,但需配合 HTMLMediaElement 和用户手势触发才能生效。
基础启用:绑定 mediaSession 并设置初始元数据
必须在用户交互(如点击、触摸)后初始化 mediaSession,否则浏览器会静默忽略。一旦激活,可设置基本元数据和事件监听:
- 调用
navigator.mediaSession.metadata = new MediaMetadata({...})设置标题、艺术家、专辑、封面(封面需为 HTTPS URL 数组,推荐提供多种尺寸) - 封面数组示例:
[{src: 'cover-512.png', sizes: '512x512', type: 'image/png'}];缺失封面可能导致部分平台(如 Android)不显示控件 - 必须显式启用播放控制:设置
navigator.mediaSession.setActionHandler('play', handlePlay)等,否则按钮灰显或不可点
控制逻辑定制:响应系统级操作并同步状态
系统通知栏的按钮点击会触发对应 action handler,你需要在此完成实际播放逻辑,并主动更新 playback state 以驱动 UI 反馈:
使用 Playwright 为 jimeng.jianying.com 管理浏览器会话,导入 cookies/localStorage 以自动化视频生成工作流,支持图片上传等功能
- 支持的操作包括:
'play'、'pause'、'seekbackward'、'seekforward'、'previoustrack'、'nexttrack'、'skipad' - 每个 handler 中应调用
audio.play()或audio.pause(),并同步设置navigator.mediaSession.playbackState = 'playing'或'paused' - 若使用自定义播放器(非原生
动态更新:实时刷新元数据与播放进度
元数据和进度条不是静态快照,需随播放过程持续更新:
- 切换歌曲时,重新赋值
navigator.mediaSession.metadata即可刷新标题、封面等;无需重新注册 handler - 实现进度条(如 Android 上的 seekable 进度条):设置
mediaSession.setPositionState({duration, position, playbackRate}),其中position应基于audio.currentTime定期更新(建议用requestAnimationFrame或timeupdate事件) - 注意:仅当
playbackState === 'playing'时,系统才可能显示并响应进度拖动;暂停状态下拖动无效
兼容性与常见陷阱
并非所有平台表现一致,需针对性处理:
- iOS Safari 支持有限:仅在锁屏显示基础控件,不支持
setPositionState和大部分 action(如 seek),且元数据更新延迟明显 - 桌面 Chrome/Firefox 支持完整功能,但需用户首次通过手势触发播放后 mediaSession 才“激活”;后续自动播放(如后台续播)可能被策略阻止
- Android Chrome 要求页面处于前台且有活跃音频上下文;若页面被切到后台超过数分钟,系统可能回收 session,需监听
visibilitychange做恢复 - 测试时避免使用隐身模式——部分浏览器在隐身窗口中禁用 mediaSession

















