使用 Media Session API 自定义媒体通知和播放控件

如何与硬件媒体键集成、自定义媒体通知等。

为了让用户知道浏览器中当前播放的内容并对其进行控制，而无需返回启动它的网页，我们引入了 Media Session API。它允许 Web 开发者通过自定义媒体通知、媒体事件（例如播放、暂停、跳转、跟踪更改、视频会议事件（例如将麦克风静音/取消静音、开启/关闭摄像头和挂断）等媒体事件）中的元数据自定义此体验。这些自定义设置适用于多种情境，包括桌面媒体中心、移动设备上的媒体通知，甚至是穿戴式设备。我将在本文中介绍这些自定义设置。

Media Session API 简介

媒体会话 API 具有以下优势和功能：

• 支持硬件媒体键。
• 媒体通知可在移动设备、桌面设备和已配对的穿戴式设备上自定义。
• 媒体中心可在桌面设备上使用。
• 您可以在 ChromeOS 和移动设备上使用锁定屏幕媒体控件。
• 画中画窗口控件可用于音频播放、视频会议和演示幻灯片。
• 支持在移动设备上集成 Google 助理。

我们将通过几个示例来说明其中的部分内容。

示例 1：如果用户按键盘上的“下一首”媒体键，那么无论浏览器是位于前台还是后台，Web 开发者都可以处理此用户操作。

示例 2：如果用户在设备屏幕处于锁定状态时通过网页收听播客，他们仍然可以点击锁定屏幕媒体控件中的“快退”图标，这样 Web 开发者就能将播放时间向后缩短几秒钟。

示例 3：如果用户使用正在播放音频的标签页，他们可以通过桌面设备上的媒体中心轻松地停止播放，以便 Web 开发者有机会清除其状态。

示例 4：如果用户正在进行视频通话，可以按画中画窗口中的“切换开关麦克风”控件，以阻止网站接收麦克风数据。

这全部是通过两个不同的接口完成的：MediaSession 接口和 MediaMetadata 接口。第一种方法可让用户控制播放内容。第二，如何告知 MediaSession 需要控制什么。

为便于说明，下图展示了这些界面与特定媒体控件（在本例中为移动设备上的媒体通知）之间的关系。

让用户知道当前播放的是什么

当网站播放音频和视频时，用户会自动在移动设备上的通知栏中或桌面设备上的媒体中心收到媒体通知。浏览器会使用文档标题和它能找到的最大图标图片来尽可能显示适当的信息。借助 Media Session API，您可以使用一些更丰富的媒体元数据（例如标题、音乐人姓名、专辑名称和海报图片）来自定义媒体通知，如下所示。

仅当媒体时长至少为 5 秒时，Chrome 才会请求“完整”音频焦点，以便显示媒体通知。这样可以确保偶然声（例如叮当声）不会显示通知。

// After media (video or audio) starts playing
await document.querySelector("video").play();

if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Never Gonna Give You Up',
    artist: 'Rick Astley',
    album: 'Whenever You Need Somebody',
    artwork: [
      { src: 'https://via.placeholder.com/96',   sizes: '96x96',   type: 'image/png' },
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/192', sizes: '192x192', type: 'image/png' },
      { src: 'https://via.placeholder.com/256', sizes: '256x256', type: 'image/png' },
      { src: 'https://via.placeholder.com/384', sizes: '384x384', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  });

  // TODO: Update playback state.
}

播放结束后，无需“释放”媒体会话，因为通知会自动消失。但请注意，系统会在下次开始播放时使用 navigator.mediaSession.metadata。因此，请务必在媒体播放来源发生变化时对其进行更新，以确保媒体通知中显示相关信息。

关于媒体元数据，有几点需要注意。

• 通知图片数组支持 blob 网址和数据网址。
• 如果未定义海报图片，且存在所需尺寸的图标图片（使用 <link rel=icon> 指定），则媒体通知会使用该图片。
• Chrome（Android 版）中的通知图片目标大小为 512x512。对于低端设备，则为 256x256。
• 媒体 HTML 元素的 title 属性用于“闻曲知音”macOS widget。
• 如果媒体资源已嵌入（例如在 iframe 中），则必须从嵌入的上下文中设置 Media Session API 信息。请参阅以下代码段。

<iframe id="iframe">
  <video>...</video>
</iframe>
<script>
  iframe.contentWindow.navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Never Gonna Give You Up',
    ...
  });
</script>

您还可以向媒体元数据中添加各个章节信息，例如章节标题、时间戳和屏幕截图图片。这让用户能够浏览媒体内容的内容。

navigator.mediaSession.metadata = new MediaMetadata({
  // title, artist, album, artwork, ...
  chapterInfo: [{
    title: 'Chapter 1',
    startTime: 0,
    artwork: [
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  }, {
    title: 'Chapter 2',
    startTime: 42,
    artwork: [
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  }]
});

让用户控制播放内容

媒体会话操作是网站可以在用户与当前的媒体播放互动时处理的一种操作（例如“播放”或“暂停”）。操作类似于事件，其运作方式与事件类似。与事件一样，操作是通过在适当的对象（在本例中为 MediaSession 的实例）上设置处理程序来实现的。当用户按下耳机、其他远程设备或键盘上的按钮，或与媒体通知互动时，就会触发某些操作。

由于某些媒体会话操作可能不受支持，因此建议使用 try…catch 代码块进行设置。

const actionHandlers = [
  ['play',          () => { /* ... */ }],
  ['pause',         () => { /* ... */ }],
  ['previoustrack', () => { /* ... */ }],
  ['nexttrack',     () => { /* ... */ }],
  ['stop',          () => { /* ... */ }],
  ['seekbackward',  (details) => { /* ... */ }],
  ['seekforward',   (details) => { /* ... */ }],
  ['seekto',        (details) => { /* ... */ }],
  /* Video conferencing actions */
  ['togglemicrophone', () => { /* ... */ }],
  ['togglecamera',     () => { /* ... */ }],
  ['hangup',           () => { /* ... */ }],
  /* Presenting slides actions */
  ['previousslide', () => { /* ... */ }],
  ['nextslide',     () => { /* ... */ }],
];

for (const [action, handler] of actionHandlers) {
  try {
    navigator.mediaSession.setActionHandler(action, handler);
  } catch (error) {
    console.log(`The media session action "${action}" is not supported yet.`);
  }
}

若要取消设置媒体会话操作处理程序，只需将其设为 null 即可。

try {
  // Unset the "nexttrack" action handler at the end of a playlist.
  navigator.mediaSession.setActionHandler('nexttrack', null);
} catch (error) {
  console.log(`The media session action "nexttrack" is not supported yet.`);
}

设置后，媒体会话操作处理程序将在媒体播放过程中持续保留。这与事件监听器模式类似，不同之处在于处理事件意味着浏览器会停止执行任何默认行为，并将其用作网站支持媒体操作的信号。因此，除非设置了正确的操作处理程序，否则媒体操作控件不会显示。

播放 / 暂停

"play" 操作表示用户想要恢复媒体播放，而 "pause" 操作表示想要暂时停止媒体播放。

媒体通知中始终显示“播放/暂停”图标，并且浏览器会自动处理相关的媒体事件。如需替换其默认行为，请处理“播放”和“暂停”媒体操作，如下所示。

例如，在跳转或加载时，浏览器可能会将某个网站视为不播放媒体。在这种情况下，您可以通过将 navigator.mediaSession.playbackState 设置为 "playing" 或 "paused" 来替换此行为，以确保网站界面与媒体通知设置保持同步。

const video = document.querySelector('video');

navigator.mediaSession.setActionHandler('play', async () => {
  // Resume playback
  await video.play();
});

navigator.mediaSession.setActionHandler('pause', () => {
  // Pause active playback
  video.pause();
});

video.addEventListener('play', () => {
  navigator.mediaSession.playbackState = 'playing';
});

video.addEventListener('pause', () => {
  navigator.mediaSession.playbackState = 'paused';
});

上一首

"previoustrack" 操作指示用户希望从头开始播放当前媒体（如果媒体播放具有开始播放的概念），或者移动到播放列表中的上一项（如果媒体播放具有播放列表的概念）。

navigator.mediaSession.setActionHandler('previoustrack', () => {
  // Play previous track.
});

下一首

"nexttrack" 操作表示，如果媒体播放具有播放列表的概念，用户希望将媒体播放移至播放列表中的下一项。

navigator.mediaSession.setActionHandler('nexttrack', () => {
  // Play next track.
});

停止

"stop" 操作表示用户想要停止媒体播放并在适当的情况下清除状态。

navigator.mediaSession.setActionHandler('stop', () => {
  // Stop playback and clear state if appropriate.
});

快退 / 快进

"seekbackward" 操作表示用户希望将媒体播放时间向后延长一小段时间，而 "seekforward" 则表示希望将媒体播放时间向前延长一小段时间。在这两种情况下，用时较短意味着只需几秒钟的时间。

操作处理程序中提供的 seekOffset 值是媒体播放时间移动的时间（以秒为单位）。如果未提供（例如 undefined），则应使用合理的时间（例如 10-30 秒）。

const video = document.querySelector('video');
const defaultSkipTime = 10; /* Time to skip in seconds by default */

navigator.mediaSession.setActionHandler('seekbackward', (details) => {
  const skipTime = details.seekOffset || defaultSkipTime;
  video.currentTime = Math.max(video.currentTime - skipTime, 0);
  // TODO: Update playback state.
});

navigator.mediaSession.setActionHandler('seekforward', (details) => {
  const skipTime = details.seekOffset || defaultSkipTime;
  video.currentTime = Math.min(video.currentTime + skipTime, video.duration);
  // TODO: Update playback state.
});

跳至特定时间

"seekto" 操作表示用户希望将媒体播放时间移至特定时间。

操作处理程序中提供的 seekTime 值是将媒体播放时间移至的秒数。

如果操作在序列中被多次调用，并且这不是该序列中的最后一次调用，则操作处理程序中提供的 fastSeek 布尔值为 true。

const video = document.querySelector('video');

navigator.mediaSession.setActionHandler('seekto', (details) => {
  if (details.fastSeek && 'fastSeek' in video) {
    // Only use fast seek if supported.
    video.fastSeek(details.seekTime);
    return;
  }
  video.currentTime = details.seekTime;
  // TODO: Update playback state.
});

设置播放位置

在通知中准确显示媒体播放位置就像在适当的时间设置位置状态一样简单，如下所示。位置状态由媒体播放速率、时长和当前时间组成。

时长必须是正值。位置必须为正数，且小于时长。播放速率必须大于 0。

const video = document.querySelector('video');

function updatePositionState() {
  if ('setPositionState' in navigator.mediaSession) {
    navigator.mediaSession.setPositionState({
      duration: video.duration,
      playbackRate: video.playbackRate,
      position: video.currentTime,
    });
  }
}

// When video starts playing, update duration.
await video.play();
updatePositionState();

// When user wants to seek backward, update position.
navigator.mediaSession.setActionHandler('seekbackward', (details) => {
  /* ... */
  updatePositionState();
});

// When user wants to seek forward, update position.
navigator.mediaSession.setActionHandler('seekforward', (details) => {
  /* ... */
  updatePositionState();
});

// When user wants to seek to a specific time, update position.
navigator.mediaSession.setActionHandler('seekto', (details) => {
  /* ... */
  updatePositionState();
});

// When video playback rate changes, update position state.
video.addEventListener('ratechange', (event) => {
  updatePositionState();
});

重置位置状态只需将其设为 null 即可。

// Reset position state when media is reset.
navigator.mediaSession.setPositionState(null);

视频会议操作

用户将视频通话置于画中画窗口中时，浏览器可能会显示麦克风、摄像头以及挂断电话的控件。当用户点击这些按钮时，网站会通过下面的视频会议操作来处理它们。如需查看示例，请参阅视频会议示例。

开启/关闭麦克风

"togglemicrophone" 操作表示用户要将麦克风静音或取消静音。setMicrophoneActive(isActive) 方法可告知浏览器网站当前是否认为麦克风已激活。

let isMicrophoneActive = false;

navigator.mediaSession.setActionHandler('togglemicrophone', () => {
  if (isMicrophoneActive) {
    // Mute the microphone.
  } else {
    // Unmute the microphone.
  }
  isMicrophoneActive = !isMicrophoneActive;
  navigator.mediaSession.setMicrophoneActive(isMicrophoneActive);
});

切换相机

"togglecamera" 操作表示用户想要开启或关闭活跃摄像头。setCameraActive(isActive) 方法可指明浏览器是否认为网站处于活跃状态。

let isCameraActive = false;

navigator.mediaSession.setActionHandler('togglecamera', () => {
  if (isCameraActive) {
    // Disable the camera.
  } else {
    // Enable the camera.
  }
  isCameraActive = !isCameraActive;
  navigator.mediaSession.setCameraActive(isCameraActive);
});

挂断

"hangup" 操作表示用户想要结束通话。

navigator.mediaSession.setActionHandler('hangup', () => {
  // End the call.
});

演示幻灯片操作

当用户将其幻灯片演示文稿置于画中画窗口中时，浏览器可能会显示用于浏览幻灯片的控件。当用户点击这些按钮时，网站会通过 Media Session API 来处理它们。如需查看示例，请参阅演示幻灯片示例。

上一张幻灯片

"previousslide" 操作表示用户在演示幻灯片时想要返回上一张幻灯片。

navigator.mediaSession.setActionHandler('previousslide', () => {
  // Show previous slide.
});

下一张幻灯片

"nextslide" 操作表示用户在演示幻灯片时想要转到下一张幻灯片。

navigator.mediaSession.setActionHandler('nextslide', () => {
  // Show next slide.
});

示例

查看一些介绍 Blender Foundation 和 Jan Morgenstern 作品的媒体会话示例。

资源

• 媒体会话规范：wicg.github.io/mediasession
• 规范问题：github.com/WICG/mediasession/issues
• Chrome Bug：crbug.com