#MediaSessionAPI实战:让网页音频接管锁屏与车载控制面板(元数据与播放控制)去年十一月我给自己那个播客小站加在线收听,栽过一个跟头,现在想起来都觉得蠢。页面里的播放器我做得挺用心,进度条能拖、倍速能调、切集也顺,自…
Media Session API 实战:让网页音频接管锁屏与车载控制面板(元数据与播放控制)
Media Session API 实战:让网页音频接管锁屏与车载控制面板(元数据与播放控制)
去年十一月我给自己那个播客小站加在线收听,栽过一个跟头,现在想起来都觉得蠢。页面里的播放器我做得挺用心,进度条能拖、倍速能调、切集也顺,自己在电脑上点来点去觉得没毛病。结果有天通勤,我戴上耳机听自己站的节目,顺手把手机锁了屏,想切下一集——锁屏界面上就一个大写的"Chrome",配一个灰不溜秋的播放键,点了半天没反应。封面没有,标题没有,进度条压根不动。
我当时第一反应是音频被系统杀了。毕竟网上一搜"网页后台播放",铺天盖地都在说浏览器怎么怎么限制、锁屏就暂停。我就顺着这个方向翻了快两个小时的后台保活策略,Service Worker 都差点写上了。折腾到晚上十一点多,快要放弃的时候,随手翻到 MDN 的媒体会话那页,才一拍大腿反应过来:根本不是音频被杀,是我这个页面压根没告诉操作系统"我正在播什么"。系统不知道,当然只能拿浏览器的默认图标糊弄我。
补上 Media Session API 那几十行代码之后,我锁了一次屏,界面立马变了——节目封面、标题、主播名,播放暂停上一集下一集全能点,进度条还跟着走。那个反差我记到现在。说白了就是一层窗户纸,捅破了特别简单,没捅破之前能把人绕晕。
这篇就把我接这个"媒体会话"的过程完整捋一遍,重点是那些文档里一笔带过、我自己实打实踩出来的坑。代码都是我站上跑着的版本改的,能直接用。
先把一个误区掰过来
动手之前有个认知得先扭正,不然方向从一开始就错了。
Media Session API 不会让你的音频在后台继续播放。我知道很多人(包括一个月前的我)看到"锁屏控制"四个字,就自动脑补成"用了它锁屏也能播"。真不是。浏览器在标签页失焦、锁屏、最小化的时候暂停有声音频,那是各家统一的策略,跟这个 API 没关系。你要是真在锁屏状态下用 JS 调 audio.play(),多半直接吃一个DOMException: play() failed because the document is not visible。
那它到底干嘛的?就两件事。第一件,把"现在播的是什么、播到哪儿了、是播放还是暂停"这些信息报给操作系统,让锁屏、通知栏、耳机按键、车机屏幕能看到;第二件,把用户在那些地方按的按钮——锁屏的暂停、耳机的下一曲、键盘的媒体键——转发回你的网页,让你决定怎么响应。
我后来做了个小实验确认这点:页面播着音频,我把标签页切到后台,锁屏上控件照样显示、封面标题都在,但页面里注册的那些 handler 其实不再触发了——系统知道你在播,指令却送不回来。这就是它能力边界最直白的写照:它是个显示层加转发层,不是让你突破浏览器策略的后门。想明白这点,我在排查上浪费的那两小时就不算全白费,至少以后再遇到"锁屏能不能继续播"的提问,我能一秒钟给出准确答案,而不是跟着网上那帮人瞎扯什么 Service Worker 保活。
顺便提一句适用面。我个人的判断是,短音效、提示音这类东西别接媒体会话,纯属添乱——用户点个按钮响一声,锁屏通知栏跟着闪一下,反而烦人。真正值得接的是长音频:播客、有声书、在线音乐、长视频,也就是用户会"放着听"、会把手机揣兜里走开的那种场景。判断标准很简单:用户会不会在听的过程中锁屏或者切走?会,就接;不会,就别折腾。
所以它更像一个翻译官,一头接着你的播放器,一头接着整个系统。它不解码音频、不保活、不抢音频焦点,这些都得另说。这跟之前聊的Web Serial API 实战:在浏览器里直接读写串口与硬件设备(requestPort 与数据流收发)是一个路子,都是浏览器把以前只有原生应用才碰得到的系统能力,小心翼翼地开放给网页。想明白这层,后面就不绕了。
第一步:让锁屏知道你在播什么
最小可用版其实只要做一件事——设置元数据,也就是那个metadata。所谓 metadata,就是标题、作者、专辑、封面这一坨信息,锁屏界面上显示的全靠它。
先看代码,我加了注释:
js// 媒体会话的最小可用版:特性检测 + 在用户手势触发播放后再设置元数据const audio = document.querySelector('#podcast-audio');function setupMediaSession(track) { // 老浏览器、部分 App 内置 WebView 没有 mediaSession,直接跳过,别让它抛错 if (!('mediaSession' in navigator)) return; // artwork 一定给多个尺寸,系统会按屏幕自己挑;只给一个尺寸,某些界面干脆不显示封面 navigator.mediaSession.metadata = new MediaMetadata({ title: track.title, // 节目名,锁屏上的大标题 artist: track.author, // 主播/作者 album: track.album, // 专辑/栏目名 artwork: [ { src: 'https://cdn.example.com/cover-96.jpg', sizes: '96x96', type: 'image/jpeg' }, { src: 'https://cdn.example.com/cover-192.jpg', sizes: '192x192', type: 'image/jpeg' }, { src: 'https://cdn.example.com/cover-512.jpg', sizes: '512x512', type: 'image/jpeg' } // 安卓锁屏按 512 走 ] });}// 关键:metadata 要在 play() 成功之后设置,空播的时候设了系统也不搭理playButton.addEventListener('click', async () => { await audio.play(); // 必须由用户手势触发,否则移动端直接给你拦下来 setupMediaSession(currentTrack);});

这段代码有几个点是我用血泪换来的,单独拎出来说。
第一个,设置的时机。我一开始把它放在DOMContentLoaded里,页面一加载就设。结果桌面端看着好像没事,手机上锁屏死活不显示。后来才搞明白:移动端浏览器要求播放必须由用户手势触发,你连播都没播,系统凭什么给你显示媒体控件?所以一定要在play()成功之后(await完)再设。这一点官方那篇web.dev 的媒体会话指南里的例子也是放在play() 返回的 promise 里的,不是随便写的。
第二个,封面的尺寸和协议。artwork 数组给多个尺寸不是我强迫症,是系统真的会挑。安卓通知栏、锁屏、车机屏幕要的图不一样,你只给一张 96 的,高清屏上就糊成马赛克;你只给一张 512 的,小图标界面又可能加载不出来。而且地址必须是 HTTPS,跨域还得带 CORS 头——我图省事用过一次 http://的测试图,结果所有平台上封面全空,退化成一个默认音符图标,排查了半天。别问我怎么知道的。
第三个,字段能省但不能乱填。title和artist 是最基本的,漏了对应位置就空着或者显示"未知"。这俩是纯文本,不支持 HTML 标签也不支持换行,别想着塞个 <br>进去搞两行标题。至于album,建议也带上,车机和智能手表经常拿它做副标题。
还有个更细的坑:切歌的时候,metadata不会自动刷新。我做过一个版本,列表切了源,锁屏还倔强地显示上一首。原因就是元数据属于会话、不属于音频文件,你得在每次切歌时重新赋值一遍。这个后面封装成类的时候会统一处理。
第二步:把系统那几个按钮接上
光有元数据,锁屏上顶多显示个播放暂停。想要上一集、下一集、快进快退、拖进度条这些按钮也都冒出来,你得一个一个注册处理器——你不注册,系统就把那几个按钮置灰,干脆不显示。这点其实挺体贴的,等于让你自己决定给用户哪几个按钮。
js// 把系统/耳机/车载那几个按钮,接到我们自己的播放器逻辑上function bindAction(action, handler) { try { // 有些 action 在当前浏览器根本不被认识,setActionHandler 会直接抛 TypeError navigator.mediaSession.setActionHandler(action, handler); } catch (err) { // 静默降级即可,别让一个不支持的动作把整段初始化搞崩 console.warn(`当前浏览器不支持动作:${action}`, err); }}if ('mediaSession' in navigator) { bindAction('play', () => audio.play()); bindAction('pause', () => audio.pause()); // 上一集/下一集:切完记得同步 metadata,不然锁屏还停在旧的那一集 bindAction('previoustrack', () => playTrack(index - 1)); bindAction('nexttrack', () => playTrack(index + 1)); // 快退/快进:details.seekOffset 是系统给的秒数,没给就默认 10 秒 bindAction('seekbackward', (details) => { audio.currentTime = Math.max(audio.currentTime - (details.seekOffset || 10), 0); }); bindAction('seekforward', (details) => { audio.currentTime = Math.min(audio.currentTime + (details.seekOffset || 10), audio.duration); }); // 拖进度条:details.seekTime 是目标秒数,fastSeek 为真时优先用原生快速跳转 bindAction('seekto', (details) => { if (details.fastSeek && 'fastSeek' in audio) { audio.fastSeek(details.seekTime); // 更快,但精度略粗,适合长按快拖 } else { audio.currentTime = details.seekTime; } });}
这里必须说一句:setActionHandler是会抛异常的。我第一次把seekto 直接注册上去,在 Safari 上整个脚本崩了,后面几行全没执行。原因是不同浏览器、不同系统认识的 action 集合不一样,seekto、skipad这些新动作在有的环境里压根没实现,你传进去它就TypeError。所以我现在一律包一层try/catch,注册失败就当没这个按钮,别连累别的。这个习惯是从MDN 的 Media Session API 文档 里学来的,它对每个 action 的支持情况都标得挺细。
动作枚举值也别写错,标准里常用的是这些:play、pause、stop、previoustrack、nexttrack、seekbackward、seekforward、seekto、skipad。大小写敏感,写成Play就废了。
这里我再多说两句stop和skipad。stop的语义跟pause不一样——暂停是这次会话还在、用户随时能回来接着听,停止则意味着会话结束,播完或者用户明确点了停止按钮。我的处理是stop里把音频pause()之后直接把playbackState设为none,顺手把currentTime归零;而pause只做暂停、状态设paused。这两个要是混为一谈,用户在车机上点停止,回头发现进度还在,就挺怪。至于skipad,本意是广告场景跳过广告,我用不上,但注册一个空实现有个好处——某些平台看到你注册了skipad,会把跳过按钮显示出来,点的时候至少不会报错。用不用得上看你的业务,别为了炫技硬塞。
还有个玄学现象我记一下:按钮显不显示、能不能点,各平台不完全看规范。我这边同样的代码,Chrome 桌面端的媒体中心只显示我注册过的那几个按钮,干净利落;安卓通知栏却偶尔会多冒出一个我压根没注册的按钮,灰着。研究半天没找到强制控制的办法,最后干脆接受——这事交给平台,别较劲,较劲也没用。
seekto的回调参数里有两个字段要注意:seekTime是用户想要跳到的绝对秒数,fastSeek是个布尔值,表示用户是不是在快速拖动。快速拖动的时候用audio.fastSeek()体验更好,普通点按就直接改currentTime。seekbackward和seekforward给的是seekOffset,也就是要跳多少秒,这个值是系统决定的,可能是 10 也可能是 15,别写死,用 || 10兜个底就行。
至于页面里播放按钮的图标怎么跟着切,我顺手用了点CSS,思路跟CSS :has() 关系选择器实战:用"父级选子级"写出更聪明的组件样式(链式与 :not() 组合) 里聊的差不多——让父容器根据自己的状态类去挑子元素图标,省得到处手动改 class。
第三步:状态别让系统去猜
按钮接完了,还有个特别容易翻车的地方:播放状态。
系统那边的播放/暂停按钮图标,是按playbackState显示的。你页面里已经暂停了,却没告诉系统,锁屏上就还显示个"暂停"图标,用户点下去等于没点。所以只要播放状态变了,就得主动同步。
js// 播放状态同步:告诉系统现在是播放中还是暂停,按钮图标才不会反function setPlaybackState() { if (!('mediaSession' in navigator)) return; // 允许的值只有 playing / paused / none(新一点的规范还加了 buffering) navigator.mediaSession.playbackState = audio.paused ? 'paused' : 'playing';}audio.addEventListener('play', setPlaybackState);audio.addEventListener('pause', setPlaybackState);audio.addEventListener('ended', () => { navigator.mediaSession.playbackState = 'none'; // 播完了,把控制权交还系统});// 关键:用户在锁屏上点暂停时,页面里的 audio 不一定知道,得反同步回来navigator.mediaSession.addEventListener('playbackstatechanged', (event) => { console.log('系统侧播放状态变成:', event.playbackState); // event.playbackState === 'playing' | 'paused' | 'none' renderPlayButton(event.playbackState); // 更新页面上的按钮图标});
playbackState能赋的值就三个:playing、paused、none。别自己造词,赋个stopped进去人家不认。播完一集设成none,系统就知道这次会话结束了。
真正让我栽跟头的是后面那个playbackstatechanged事件。我原本以为状态同步是单向的——我告诉系统就行。后来发现用户在锁屏上点暂停的时候,事件是从系统那头过来的,你页面里的audio元素在某些平台上并不会自动跟着停(尤其是那些系统自己管理媒体键的场景)。你要是不监听这个事件把状态拉回来,就会出现"锁屏显示暂停了,页面里还在哗哗响"的精分场面。加了这个监听之后才算两头对上。
不过有个细节得提醒:这个事件只在系统主动改变状态时触发,比如用户在锁屏点了按钮。你自己用 JS 调 audio.pause()是不会触发它的,所以页面内的状态同步还是得靠audio自己的play/pause事件,两条线都得留着,缺一不可。
为了把这套状态流转讲清楚,我画过一张草图贴在显示器边上:页面内audio的play/pause事件是"我→系统"这条线,playbackstatechanged是"系统→我"这条线,两根箭头反过来对上,状态才不会打架。少画一根,运行起来就是各种精分。我一开始只画了单向,还纳闷为什么锁屏和页面老是不同步,把图补上第二根箭头那一刻,问题在哪一目了然。真推荐你也这么捋一遍,比盯着代码干瞪眼快多了。
另外playbackState有个值叫buffering,规范里是有的,表示正在缓冲。我试过在waiting事件里把它设成buffering,大部分系统会显示个转圈,体验挺好;但个别浏览器不认这个值,设进去跟没设一样。所以我的用法是"设了不亏、不认也不崩",当增强用,别把它当成必须同步的核心状态。核心永远是那三个:playing、paused、none。
浏览器支持这块我劝你先看一眼caniuse 上的支持情况 再决定做到什么程度。大致是 Chrome 73、Edge 79 起就有了核心能力,Firefox 82 跟上但个别动作不全,Safari 从 15 开始支持、但一直比较保守,尤其 iOS 上 setActionHandler 的支持Historically 不太完整。我的策略一直是:基础元数据和播放暂停保证能用,花活儿(seekto 之类)做优雅降级,别指望所有平台表现一致。
第四步:让锁屏进度条动起来
元数据、按钮、状态都齐了,最后差个进度条。锁屏上那个能拖的进度条,靠的是setPositionState。
js// 让锁屏/通知栏的进度条跟着走function syncPositionState() { if (!('mediaSession' in navigator)) return; // 直播流、没加载完的音频 duration 可能是 Infinity 或 NaN,直接跳过 if (!Number.isFinite(audio.duration) || audio.duration <= 0) return; // 三个参数都有硬性约束,稍微越界浏览器就抛 TypeError: // duration 必须有限且 > 0;position 必须在 0~duration 之间;playbackRate 必须 > 0 navigator.mediaSession.setPositionState({ duration: audio.duration, position: Math.min(audio.currentTime, audio.duration), playbackRate: audio.playbackRate });}// timeupdate 一秒触发好几次,直接调太浪费,做个简单节流let lastSync = 0;audio.addEventListener('timeupdate', () => { const now = Date.now(); if (now - lastSync > 1000) { // 每秒最多同步一次,肉眼完全够用 lastSync = now; syncPositionState(); }});
这三个参数的约束我吃过亏,得掰开讲。duration必须是有限的正数,音频没加载完的时候它是NaN,直播流是Infinity,这两种情况直接传给setPositionState会当场抛TypeError。所以开头那个Number.isFinite判断不是摆设,必须有。position不能超出duration,我用Math.min夹了一下——别小看这个,播放到最后一两秒的时候,currentTime偶尔会比duration大那么一丁点,不夹就报错。playbackRate 我做的播客支持倍速,这个值必须是正数,正常播放是 1,没问题。
节流这一下也别省。timeupdate事件触发得挺频繁,每次都去调setPositionState有点浪费,而且系统那边刷新那么勤也没意义。每秒同步一次,进度条看起来就是流畅走的,肉眼根本分辨不出差别。
顺便说一句,seekto处理器和setPositionState是配对的:前者负责接收用户拖动的结果,后者负责把当前进度报上去。少了后者,你拖完锁屏进度条会"弹回去",因为系统不知道你实际播到哪儿了。这俩必须一起做。
车载面板那点事,以及一个能直接用的封装
标题里写了"车载控制面板",我知道有人是冲这个来的,得说实话,别把预期拔太高。
车机(Android Auto、CarPlay 这类)能不能显示你的网页媒体,中间隔着两层:一层是浏览器的媒体会话有没有进到系统媒体框架,一层是车机系统愿不愿意把这个会话投到屏幕上。网页这边能做的就是老老实实把媒体会话填完整——元数据、封面、播放状态、进度、动作处理器全套配上,系统才可能把它带进车机。我自己在 Android Auto 上试过,Chrome 播的音频是能出现在车机媒体页里的,封面标题都在,按钮也能反控;但不同车机、不同系统版本差异挺大,有的只认原生 App 的会话。所以我的建议是:把会话做扎实,剩下的交给平台,别承诺"百分百接管车机",那样早晚被打脸。
把前面几步堆一起,每次切歌都要重新设 metadata、同步状态、刷进度,写散了很容易漏。所以最后我封装成了一个类,切歌时调一个方法全搞定:
js// 收尾:把上面几步打包成一个能直接用的 Session 管理器class MediaSessionManager { constructor(audio) { this.audio = audio; this.supported = 'mediaSession' in navigator; } // 切歌时一次把元数据、状态、进度全刷新,避免锁屏停在上一首 setTrack(track) { if (!this.supported) return; navigator.mediaSession.metadata = new MediaMetadata({ title: track.title, artist: track.artist, album: track.album, artwork: track.artwork // [{ src, sizes, type }, ...] 记得走 HTTPS }); this.syncState(); } syncState() { if (!this.supported) return; navigator.mediaSession.playbackState = this.audio.paused ? 'paused' : 'playing'; if (Number.isFinite(this.audio.duration) && this.audio.duration > 0) { navigator.mediaSession.setPositionState({ duration: this.audio.duration, position: this.audio.currentTime, playbackRate: this.audio.playbackRate }); } } // 注销:页面卸载或播放器销毁时调用,别留个空会话挂在系统里 destroy() { if (!this.supported) return; navigator.mediaSession.metadata = null; navigator.mediaSession.playbackState = 'none'; ['play', 'pause', 'nexttrack', 'previoustrack', 'seekto'].forEach(action => { navigator.mediaSession.setActionHandler(action, null); // 传 null 就是取消注册 }); }}
写这个包装类的时候我莫名想起了PHP 8.4 Property Hooks 实战:用属性钩子告别样板 Getter/Setter(虚拟属性与接口约束)——PHP 那边靠属性钩子省掉一大堆 getter/setter 样板,JS 这边对象属性直接读写,反倒没这烦恼。不过 destroy()这一步别偷懒省掉,我见过有人页面关了,系统通知栏还挂着一个"正在播放"的幽灵会话,点了没任何反应,特尴尬。传null给setActionHandler就是标准的取消注册方式。
这个类我实际用的时候还加了两处小改进,一是所有方法开头都判断this.supported,这样就算遇到不支持的环境,整段代码也是静默跳过而不是到处报错——线上环境千奇百怪,防御性写法能省不少半夜被叫起来的事。二是把setTrack和syncState拆开,因为有的场景只是倍速变了、进度跳了,没必要重新构造一遍MediaMetadata,只同步状态就够了。别看这俩改进小,切歌频繁的有声书场景下,少构造一次对象就少一次封面重新加载,锁屏那一下的闪烁能明显减轻。
还有个多人协作才碰得到的问题顺便记一下:如果页面上不止一个地方能改播放状态(比如既有底部播放条,又有列表里的播放按钮),一定要保证所有入口都走这个管理器的方法,别绕过它直接改audio。我吃过一次亏,某处代码直接调了audio.pause(),没走管理器,结果页面停了但playbackState还是playing,锁屏按钮显示的是暂停图标,点了没反应。这种 bug 排查起来特别烦,因为它不是必现的,只有你恰好走那条冷门路径才冒出来。规矩定死:状态变更统一收口到一个地方。
我踩过的坑,攒个清单
评论区老有人问"照着文档写怎么没效果",我把自己撞过的墙列一下,你要是也遇到,八成对号入座:
- 锁屏啥都不显示——九成是没在用户手势触发
play()之后设 metadata,或者压根音频没真正播起来。空会话系统不搭理。 - 封面是空的——检查 HTTPS、检查 CORS 头、检查有没有给多尺寸。本地
file://协议直接没戏。 - 按钮灰的点不动——那个 action 你没注册,或者注册的时候抛异常被吞了。记得
try/catch,也记得看控制台的 warn。 - 进度条拖完弹回去——只做了
seekto没做setPositionState,或者反过来。这俩得成对。 - 锁屏暂停了页面还在响——没监听
playbackstatechanged,系统侧的状态没拉回来。 - 控制台报
TypeError说什么 position 越界——duration是NaN/Infinity了,或者currentTime比duration大了那么一丢丢,按上面那样夹一下就好。
这些坑没有一个是文档没写的,但文档是平铺直叙的,不会告诉你"我当初因为它在凌晨两点抓狂"。真到自己碰上,能少走两步弯路就值了。
说到底,这类浏览器原生 API 的价值都是一样的:把体验从"像个网页"抬到"像个原生应用"。这跟 WebAuthn 与 Passkey 实战:用浏览器原生无密码登录(公钥认证与替代短信验证码的完整流程)用浏览器原生能力替掉短信验证码是一个道理——技术上没多玄乎,就是那层窗户纸,捅破了体验完全两个样。
代码我都放上面了,建议直接拿去改。你要是也在做音频站、播客或者有长音频的页面,花半小时把这个接上,用户锁屏那一刻的感受会完全不一样。真接的时候卡在哪儿,欢迎来博客底下留言,我看到就回。
标签:Media Session API, 媒体会话, 锁屏控制, 音频播放, metadata
描述:通过真实踩坑经历讲解 Media Session API 的实战用法:如何在用户手势播放后设置 metadata 元数据与多尺寸 HTTPS 封面,用 setActionHandler 接管播放、切集、快进与 seekto 拖动,同步 playbackState 播放状态与 setPositionState 进度,让网页音频出现在锁屏、通知栏与车载控制面板,并给出浏览器兼容性与常见报错的完整避坑清单。

发表评论发布评论后审核成功,即可显示在列表中...