HTML中如何使用Media Session API自定义媒体通知-html教程-PHP中文网

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

html中如何使用media session api自定义媒体通知

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

常见错误现象包括：

Wechat HTML Publisher

直接上传HTML富文本到微信公众号草稿箱。支持完整的HTML格式,无需Markdown转换。

下载

调用 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 部分机型上可能被忽略，别依赖它做核心流程。