媒体会话 API

有限可用性

此功能不是基线功能，因为它在一些最广泛使用的浏览器中不起作用。

**媒体会话 API** 提供了一种自定义媒体通知的方式。它通过为用户代理提供元数据来实现此目的，这些元数据用于显示您的 Web 应用程序正在播放的媒体。

它还提供操作处理程序，浏览器可以使用这些处理程序访问平台媒体键，例如键盘、耳机、遥控器上找到的硬件键，以及移动设备的通知区域和锁定屏幕上找到的软件键。因此，您可以通过您的设备无缝控制 Web 提供的媒体，即使没有查看网页。

其目标是允许用户知道正在播放的内容并控制它，而无需打开启动它的特定页面。为了能够支持媒体会话 API，浏览器首先需要一种机制来访问和被操作系统级别的媒体控件控制（例如 Firefox 的 MediaControl）。

媒体会话的概念和用法

MediaMetadata 接口允许网站为正在播放的媒体提供丰富的元数据到平台 UI。此元数据包括标题、艺术家（创建者）姓名、专辑（合集）、作品集和章节信息。平台可以在媒体中心、通知、设备锁定屏幕等位置显示此元数据。例如，不同的设备可能会像这样呈现媒体会话 API 数据

Media Session data for the Sintel trailer title and artwork presented on a desktop browser, mobile phone, and smartwatch

原始图像来源：使用媒体会话 API 自定义媒体通知和播放控件在 web.dev 上 (2024)

MediaSession 接口允许用户通过用户代理定义的界面元素控制媒体的播放。与这些元素的交互会触发正在播放媒体的网页上的操作处理程序。由于多个页面可能同时使用此 API，因此用户代理负责调用正确页面的操作处理程序。当没有页面定义的行为可用时，用户代理会提供默认行为。

访问媒体会话 API

媒体会话 API 的主要接口是 MediaSession 接口。您无需创建自己的 MediaSession 实例，而是可以使用 navigator.mediaSession 属性访问 API。例如，要将媒体会话的当前状态设置为 playing

navigator.mediaSession.playbackState = "playing";

接口

章节信息: 表示媒体资源（即视频或音频文件）的单个章节的元数据。
MediaMetadata: 允许网页提供丰富的媒体元数据，以便在平台 UI 中显示。
MediaSession: 允许网页为标准媒体播放交互提供自定义行为。

示例

为音乐播放器设置操作处理程序

以下示例显示了媒体会话 API 的功能检测。然后，它为会话实例化一个元数据对象，并为用户控件操作添加操作处理程序

if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: "Unforgettable",
    artist: "Nat King Cole",
    album: "The Ultimate Collection (Remastered)",
    artwork: [
      {
        src: "https://dummyimage.com/96x96",
        sizes: "96x96",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/128x128",
        sizes: "128x128",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/192x192",
        sizes: "192x192",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/256x256",
        sizes: "256x256",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/384x384",
        sizes: "384x384",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/512x512",
        sizes: "512x512",
        type: "image/png",
      },
    ],
  });

  navigator.mediaSession.setActionHandler("play", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("pause", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("stop", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("seekbackward", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("seekforward", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("seekto", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("previoustrack", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("nexttrack", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("skipad", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("togglecamera", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("togglemicrophone", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("hangup", () => {
    /* Code excerpted. */
  });
}

某些用户代理会禁用移动设备上媒体元素的自动播放，并要求用户手势才能启动媒体。以下示例向页面上的播放按钮添加 pointerup 事件，然后使用该事件启动媒体会话代码

playButton.addEventListener("pointerup", (event) => {
  const audio = document.querySelector("audio");

  // User interacted with the page. Let's play audio!
  audio
    .play()
    .then(() => {
      /* Set up media session controls, as shown above. */
    })
    .catch((error) => {
      console.error(error);
    });
});

使用操作处理程序控制幻灯片演示

例如，当用户将其演示文稿放入画中画窗口并按下浏览器提供的用于浏览幻灯片的控件时，可以使用 "previousslide" 和 "nextslide" 操作处理程序来处理在幻灯片演示中向前和向后移动。

try {
  navigator.mediaSession.setActionHandler("previousslide", () => {
    log('> User clicked "Previous Slide" icon.');
    if (slideNumber > 1) slideNumber--;
    updateSlide();
  });
} catch (error) {
  log('Warning! The "previousslide" media session action is not supported.');
}

try {
  navigator.mediaSession.setActionHandler("nextslide", () => {
    log('> User clicked "Next Slide" icon.');
    slideNumber++;
    updateSlide();
  });
} catch (error) {
  log('Warning! The "nextslide" media session action is not supported.');
}

有关工作示例，请参阅演示幻灯片 / 媒体会话示例。

规范

规范
媒体会话 # the-mediasession-interface

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅

使用媒体会话 API 自定义媒体通知和播放控件在 web.dev 上 (2024)