Media Session API 是浏览器提供的标准接口，用于将网页媒体播放状态同步至系统级界面（如锁屏、任务栏、耳机按键），并响应其控制指令；它必须绑定真实 HTMLMediaElement，通过 metadata 设置元数据、setActionHandler 响应操作，并需正确管理 playbackState 与生命周期。

Media Session API 是什么，它能控制哪些通知 Media Session API 不是给网页加个播放器 UI，而是让浏览器知道“当前页面正在播放媒体”，从而把播放控制权暴露给系统级界面：锁屏、任务栏、耳机物理按键、甚至智能手表。它不接管音频解码或播放逻辑，只负责同步状态和响应用户操作。 关键点在于，它必须配合真实的 HTMLMediaElement（<audio> 或 <video>）使用；单纯调用 navigator.mediaSession.setActionHandler() 而没有绑定到正在播放的媒体元素，系统不会显示通知，或点击后无响应。

常见错误现象包括：

anything-to-html

将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。

下载

• 调用 setActionHandler('play', ...) 后锁屏上按钮灰显——说明媒体元素未处于可播放状态（比如还没调用 play()，或被自动暂停）
• 通知出现但封面图不显示——metadata 中的 artwork URL 必须是 HTTPS 且允许跨域（需带 CORS 头），本地 file:// 协议直接失败
• Android 上通知消失太快——没设置 playbackState，系统认为播放已结束

如何正确初始化并设置基础元数据 初始化必须在用户手势触发的上下文中进行（如 click、keydown），否则 Chrome 会静默忽略。不能放在 DOMContentLoaded 或 load 里直接执行。

button.addEventListener('click', async () => {
  const audio = document.querySelector('#my-audio');
  
  // 必须先播放一次，触发媒体会话激活
  try {
    await audio.play();
  } catch (err) {
    console.warn('Autoplay prevented:', err);
    return;
  }

  if ('mediaSession' in navigator) {
    navigator.mediaSession.metadata = new MediaMetadata({
      title: 'Bohemian Rhapsody',
      artist: 'Queen',
      album: 'A Night at the Opera',
      artwork: [
        { src: 'https://example.com/cover.jpg', sizes: '512x512', type: 'image/jpeg' }
      ]
    });
  }
});

注意：artwork 数组至少要有一项，sizes 必须是字符串格式（如 '512x512'，不是 [512, 512]），type 建议明确指定。

如何响应播放/暂停/跳转等系统操作 系统通过 setActionHandler() 注册回调，但每个 handler 必须显式更新 navigator.mediaSession.playbackState，否则通知栏按钮状态不同步。

if ('mediaSession' in navigator) {
  navigator.mediaSession.setActionHandler('play', () => {
    audio.play().catch(e => console.error('play failed:', e));
    navigator.mediaSession.playbackState = 'playing';
  });

  navigator.mediaSession.setActionHandler('pause', () => {
    audio.pause();
    navigator.mediaSession.playbackState = 'paused';
  });

  navigator.mediaSession.setActionHandler('seekto', event => {
    audio.currentTime = event.seekTime || 0;
  });

  // 注意：skipad、previoustrack、nexttrack 等需自行实现逻辑
  navigator.mediaSession.setActionHandler('previoustrack', () => {
    // 比如切换上一首，然后调用 audio.load() + play()
  });
}

容易踩的坑：seekto 的 event 对象里只有 seekTime 字段，没有 currentTime；nexttrack 和 previoustrack 在桌面端 Chrome 支持，在 Android 部分机型上可能被忽略，别依赖它做核心流程。

为什么有时候通知不出现，或者点了没反应 根本原因通常是媒体元素生命周期没对齐。以下条件缺一不可：

• audio 或 video 元素已加载完成（readyState >= 3），且已调用过 play()（哪怕立即 pause()）
• navigator.mediaSession.metadata 已赋值，且 artwork 图片可公开访问（非 localhost、非未授权 CORS）
• 所有 setActionHandler 必须在媒体元素首次播放之后设置（不能早于 play() 成功 resolve）
• 移动端需启用「通知权限」，且页面在前台（后台标签页中，Chrome 会限制 media session 行为）

另外，Safari 目前完全不支持 Media Session API；Firefox 支持有限（无 seekto，无封面图）；所以实际部署时得加降级逻辑，比如只在 'mediaSession' in navigator 且 !/Firefox/.test(navigator.userAgent) 时启用。 真正麻烦的是状态同步——比如用户用耳机按键暂停，你的 JS 得监听 pause 事件并主动设 playbackState = 'paused'，否则下次点通知栏播放按钮会失效。这个闭环很容易漏掉。