媒体会话

1. 简介

本节为非规范性内容。

媒体在当今被广泛使用，而 Web 是消费媒体内容的主要渠道之一。许多平台可以在各种用户界面元素中显示媒体元数据，例如标题、艺术家、专辑和专辑封面，这些元素包括通知、媒体控制中心、设备锁屏以及可穿戴设备。本规范旨在使网页能够指定在平台界面中显示的媒体元数据，并响应可能来自平台界面或媒体按键的媒体控制，从而提升用户体验。

5. MediaSession 接口

[Exposed=Window]
partial interface Navigator {
  [SameObject] readonly attribute MediaSession mediaSession;
};

enum MediaSessionPlaybackState {
  "none",
  "paused",
  "playing"
};

enum MediaSessionAction {
  "play",
  "pause",
  "seekbackward",
  "seekforward",
  "previoustrack",
  "nexttrack",
  "skipad",
  "stop",
  "seekto",
  "togglemicrophone",
  "togglecamera",
  "togglescreenshare",
  "hangup",
  "previousslide",
  "nextslide",
  "enterpictureinpicture",
  "voiceactivity"
};

enum MediaSessionEnterPictureInPictureReason {
  "other",
  "useraction",
  "contentoccluded"
};

callback MediaSessionActionHandler = undefined(MediaSessionActionDetails details);

[Exposed=Window]
interface MediaSession {
  attribute MediaMetadata? metadata;

  attribute MediaSessionPlaybackState playbackState;

  undefined setActionHandler(MediaSessionAction action, MediaSessionActionHandler? handler);

  undefined setPositionState(optional MediaPositionState state = {});

  Promise<undefined> setMicrophoneActive(boolean active);

  Promise<undefined> setCameraActive(boolean active);

  Promise<undefined> setScreenshareActive(boolean active);
};

MediaSession 对象表示给定文档的媒体会话，并允许文档向用户代理传递有关播放及其处理方式的信息。

MediaSession 关联有一个 metadata 对象，由 MediaMetadata 表示。初始值为 null。

mediaSession 属性 必须返回与该 MediaSession 实例关联的 Navigator 对象。

metadata 属性 反映 MediaSession 的 metadata。 读取时，必须返回 MediaSession 的 metadata。 设置时，需按照以下步骤（value为新值）执行：

1. 如果 MediaSession 的 metadata 不为 null，则将其 media session 设为 null。
2. 将 MediaSession 的 metadata 设为 value。
3. 如果 MediaSession 的 metadata 不为 null，则将其 media session 设为当前 MediaSession。
4. 并行运行 元数据更新算法。

playbackState 属性表示 媒体会话 的 声明播放状态，用于声明会话的 浏览上下文 是否正在播放媒体。初始值为 none。设置时，如果为有效的 MediaSessionPlaybackState 值，则用户代理必须设置此 IDL 属性为新值。读取时，用户代理必须返回最近设置的有效值。playbackState 属性用于提示用户代理判断 浏览上下文 当前是播放还是暂停状态。

设置 playbackState 可能导致 实际播放状态发生变化，并运行 媒体会话操作更新算法。

MediaSessionPlaybackState 枚举用于指示 浏览上下文是否正在播放媒体，值描述如下：

• none 表示 浏览上下文 未声明播放或暂停状态，仅可用于 playbackState 属性。
• playing 表示 浏览上下文 当前正在播放媒体，可被暂停。
• paused 表示 浏览上下文已暂停媒体，可被恢复。

setActionHandler(action, handler) 方法被调用时，必须在 MediaSession 上以 action 和 handler 运行 操作处理器更新算法。

setPositionState(state) 方法被调用时，必须执行以下步骤：

• 如果 state 是空字典，则清除 位置状态并终止这些步骤。
• 如果 state 的 duration 未定义，则抛出 TypeError。
• 如果 state 的 duration 为负或 NaN，则抛出 TypeError。
• 如果 state 的 position 未定义，则设为零。
• 如果 state 的 position 为负或大于 duration，则抛出 TypeError。
• 如果 state 的 playbackRate 未定义，则设为 1.0。
• 如果 state 的 playbackRate 为零，则抛出 TypeError。
• 更新 位置状态 和 上次位置更新时间。

setMicrophoneActive(active) 方法用于向用户代理指示页面期望的麦克风采集状态（例如页面不再通过通话发送音频时视为“非激活”，可调用 setMicrophoneActive(false)）。被调用时，必须执行以下步骤：

1. 令 document 为 this 的 相关全局对象 的 关联文档。
2. 令 captureKind 为 "microphone"。
3. 返回运行 采集状态更新算法（参数：document, active, captureKind）的结果。

同理，setCameraActive(active) 方法用于向用户代理指示页面期望的摄像头采集状态。调用时，必须执行以下步骤：

1. 令 document 为 this 的 相关全局对象 的 关联文档。
2. 令 captureKind 为 "camera"。
3. 返回运行 采集状态更新算法（参数：document, active, captureKind）的结果。

同理，setScreenshareActive(active) 方法用于向用户代理指示页面期望的屏幕共享采集状态。调用时，必须执行以下步骤：

1. 令 document 为 this 的 相关全局对象 的 关联文档。
2. 令 captureKind 为 "screenshare"。
3. 返回运行 采集状态更新算法（参数：document, active, captureKind）的结果。

采集状态更新算法在以 document、active 和 captureKind 调用时，必须执行以下步骤：

1. 如果 document 不是 完全激活，返回 一个被拒绝的 promise，错误为 InvalidStateError。
2. 如果 active 为 true 且 document 的 可见性状态不是 "visible"，用户代理可返回 一个被拒绝的 promise，错误为 InvalidStateError。
3. 令 p 为新建的 promise。
4. 并行运行以下步骤：
   1. 令 applyPausePolicy 为 true，如果用户代理实现了针对 UI 的 暂停所有输入源（类型为 captureKind）的策略，否则为 false。
   2. 如果 applyPausePolicy 为 true，运行以下子步骤：
      1. 令 currentlyActive 为 false，如果用户代理当前 暂停所有输入源（类型为 captureKind），否则为 true。
      2. 如果 active 等于 currentlyActive，使用 队列任务，任务源为 用户交互任务源，将 p resolve 为 undefined 并终止这些步骤。
      3. 如果 active 为 true，用户代理可以等待继续，比如提示用户。
      4. 如果用户代理拒绝更新采集状态请求，使用 队列任务，任务源为 用户交互任务源，将 p reject 为 NotAllowedError 并终止这些步骤。
   3. 按照 captureKind 和 active 更新用户代理采集状态界面。
   4. 使用 队列任务，任务源为 用户交互任务源，将 p resolve 为 undefined。
   5. 如果 applyPausePolicy 为 true，运行以下子步骤：
      1. 令 newMutedState 为 true，如果 active 为 false，否则为 false。
      2. 对每个来源为 captureKind 的 MediaStreamTrack， 使用 队列任务，任务源为 用户交互任务源， 设置 track 静音状态为 newMutedState。
5. 返回 p。

setMicrophoneActive(active)、setCameraActive(active) 和 setScreenshareActive(active) 方法可能会根据用户代理的特定启发式拒绝调用。这尤其可能发生在网页请求激活（取消静音）麦克风、摄像头或屏幕共享时。用户代理可要求 临时激活，也可能通过提示要求用户输入以做出最终决定。

用户代理可以显示 UI，以触发 媒体会话操作的处理器。

6. MediaMetadata 接口

[Exposed=Window]
interface MediaMetadata {
  constructor(optional MediaMetadataInit init = {});
  attribute DOMString title;
  attribute DOMString artist;
  attribute DOMString album;
  attribute FrozenArray<object> artwork;
  [SameObject] readonly attribute FrozenArray<ChapterInformation> chapterInfo;
};

dictionary MediaMetadataInit {
  DOMString title = "";
  DOMString artist = "";
  DOMString album = "";
  sequence<MediaImage> artwork = [];
  sequence<ChapterInformationInit> chapterInfo = [];
};

MediaMetadata 对象用于表示与 MediaSession 相关联的元数据，用户代理可以用它来提供自定义的用户界面。

MediaMetadata 可以关联一个 媒体会话 对象。

MediaMetadata 关联有 标题、艺术家 和 专辑，类型为 DOMString。

MediaMetadata 关联有一个 封面图片序列，类型为 MediaImage。MediaMetadata 还关联有一个 已转换封面图片，初始值为 undefined。

MediaMetadata 关联有一个 章节信息列表。

当 MediaMetadata 等于 null 或同时满足以下所有条件时，称其为 空元数据：

• 其 标题 为空字符串。
• 其 艺术家 为空字符串。
• 其 专辑 为空字符串。
• 其 封面图片长度为 0。
• 其 章节信息长度为 0。

MediaMetadata(init) 构造函数被调用时，必须执行以下步骤：

1. 令 metadata 为一个新的 MediaMetadata 对象。
2. 将 metadata 的 title 设为 init 的 title。
3. 将 metadata 的 artist 设为 init 的 artist。
4. 将 metadata 的 album 设为 init 的 album。
5. 用 init 的 artwork 作为 input，运行 封面转换算法，如果成功则将 metadata 的 封面图片设为结果。
6. 令 chapters 为类型为 ChapterInformation 的空列表。
7. 对 init 的 chapterInfo 中的每个 entry，创建 ChapterInformation 并添加到 chapters。
8. 将 metadata 的 章节信息设为 创建冻结数组后的结果。
9. 返回 metadata。

当以 input 参数调用 封面转换算法时，其中 input 为类型 MediaImage 的序列，用户代理必须执行以下步骤：

1. 令 output 为类型 MediaImage 的空列表。
2. 对 input（MediaImage 列表）中的每个 entry，执行以下步骤：
   1. 令 image 为新的 MediaImage。
   2. 令 baseURL 为 入口设置对象指定的 API 基础 URL。
   3. 解析 entry 的 src，使用 baseURL。如果未失败，则将 image 的 src 设为返回值，否则抛出 TypeError 并终止这些步骤。
   4. 将 image 的 sizes 设为 entry 的 sizes。
   5. 将 image 的 type 设为 entry 的 type。
   6. 将 image 添加到 output。
3. 返回 output 作为结果。

title 属性反映 MediaMetadata 的 标题。读取时，必须返回 MediaMetadata 的 标题。设置时，必须将 MediaMetadata 的 标题 设为给定值。

artist 属性反映 MediaMetadata 的 艺术家。读取时，必须返回 MediaMetadata 的 艺术家。设置时，必须将 MediaMetadata 的 艺术家 设为给定值。

album 属性反映 MediaMetadata 的 专辑。读取时，必须返回 MediaMetadata 的 专辑。设置时，必须将 MediaMetadata 的 专辑 设为给定值。

artwork 属性反映 MediaMetadata 的 封面图片。读取时，必须执行以下步骤：

1. 如果 MediaMetadata 的 已转换封面图片为 undefined，则执行以下步骤：
   1. 令 frozenArtwork 为一个 JavaScript 数组值。
   2. 对 MediaMetadata 的 封面图片中的每个 entry，执行以下步骤：
      1. 令 image 为 IDL 转为 JS 对象后的 entry。
      2. 执行 SetIntegrityLevel(image, "frozen")，防止脚本意外变更。
      3. 将 image 推入 frozenArtwork。
   3. 执行 SetIntegrityLevel(frozenArtwork, "frozen")。
   4. 将 MediaMetadata 的 已转换封面图片 设为 frozenArtwork。
2. 返回 MediaMetadata 的 已转换封面图片。

设置时，必须按如下步骤，以 value 为新值：

1. 令 convertedArtwork 为 将 ECMAScript 转为 IDL 值的 value，类型为 MediaImage 的序列。
2. 用 convertedArtwork 运行 封面转换算法，成功则将 MediaMetadata 的 封面图片 设为结果。
3. 将 MediaMetadata 的 已转换封面图片设为 undefined。

当 MediaMetadata 的 标题、艺术家、专辑或 封面图片被修改时，用户代理必须执行以下步骤：

1. 如果该实例没有关联的 媒体会话，则终止这些步骤。
2. 否则，队列一个任务以执行以下子步骤：
   1. 如果该实例不再有关联的 媒体会话，则终止这些步骤。
   2. 否则，并行运行 元数据更新算法。

7. ChapterInformation 接口

[Exposed=Window]
interface ChapterInformation {
  readonly attribute DOMString title;
  readonly attribute double startTime;
  [SameObject] readonly attribute FrozenArray<MediaImage> artwork;
};

dictionary ChapterInformationInit {
  DOMString title = "";
  double startTime = 0;
  sequence<MediaImage> artwork = [];
};

ChapterInformation 对象用于表示单独章节的元数据，例如章节标题、时间戳和该章节的截图图片数据，用户代理可用其提供自定义用户界面。

ChapterInformation 关联有 标题，类型为 DOMString。

ChapterInformation 关联有 startTime，类型为 double。

ChapterInformation 关联有 封面图片列表。

要创建一个 ChapterInformation，传入 init，按如下步骤执行：

1. 令 chapterInfo 为一个新的 ChapterInformation 对象。
2. 将 chapterInfo 的 title 设为 init 的 title。
3. 将 chapterInfo 的 startTime 设为 init 的 startTime。 如果 startTime 为负或大于 duration，抛出 TypeError。
4. 令 artwork 为用 init 的 artwork 作为 input 运行 封面转换算法 的结果。
5. 将 chapterInfo 的 封面图片设为 创建冻结数组后的 artwork。
6. 返回 chapterInfo。

title 属性反映 ChapterInformation 的 标题。读取时，必须返回 ChapterInformation 的 标题。

startTime 属性反映 ChapterInformation 的 startTime（秒）。读取时，必须返回 ChapterInformation 的 startTime。

artwork 属性反映 ChapterInformation 的 封面图片。读取时，必须返回 ChapterInformation 的 封面图片。

8. MediaImage 字典

dictionary MediaImage {
  required USVString src;
  DOMString sizes = "";
  DOMString type = "";
};

MediaImage 字典成员借鉴了 ImageResource，见 [IMAGE-RESOURCE]。

src 字典成员用于指定 MediaImage 对象的 source。它是用户代理可用于获取图片数据的 URL。

sizes 字典成员用于指定 MediaImage 对象的 sizes。其规范遵循 HTML sizes 属性，为字符串，由一组唯一的、以空格分隔的 tokens 组成（无序），这些 tokens 是 ASCII 不区分大小写，用于表示图片的尺寸。每个关键字要么是字符串 "any" 的 ASCII 不区分大小写匹配，要么是由两个有效的非负整数构成（不能有前导 0），用一个小写字母 x 或大写字母 X 分隔。关键字表示原始像素尺寸（非 CSS 像素）。当有多个图片对象时，用户代理可以用该值决定最适合某显示环境的图标（并忽略不适合的）。sizes 属性的解析步骤必须遵循 HTML link 元素 sizes 属性的解析步骤。

type 字典成员用于指定 MediaImage 对象的 MIME 类型。它作为图片的媒体类型的提示，便于用户代理忽略不支持的媒体类型图片。

9. MediaPositionState 字典

dictionary MediaPositionState {
  unrestricted double duration;
  double playbackRate;
  double position;
};

MediaPositionState 字典用于表示与 MediaSession 相关联的当前播放位置，用户代理可用它提供显示当前播放位置和时长的界面。

duration 字典成员用于指定 时长（秒）。应始终为正数，正无穷可用于表示无定义结束点的媒体（如直播）。

playbackRate 字典成员用于指定 播放速率。可为正表示正向播放，负表示倒放，不应为零。

position 字典成员用于指定 最后报告的播放位置（秒），应始终为正数。

10. MediaSessionActionDetails 字典

dictionary MediaSessionActionDetails {
  required MediaSessionAction action;
  double seekOffset;
  double seekTime;
  boolean fastSeek;
  boolean isActivating;
  MediaSessionEnterPictureInPictureReason enterPictureInPictureReason;
};

MediaSessionActionHandler 必须以 details 参数运行，其字典类型为 MediaSessionActionDetails。

action 字典成员用于指定 媒体会话操作，即 MediaSessionActionHandler 关联的操作类型。

seekOffset 字典成员可在 媒体会话操作为 seekbackward 或 seekforward 时提供。它表示需要调整的播放时间（秒），如果有应为正值，否则网站应自行选择合理时间（如几秒）。

当 媒体会话操作为 seekto 时：

• seekTime 字典成员必须提供，表示需要跳转到的播放时间（秒）。
• fastSeek 字典成员可选，若在一系列操作中被多次调用且不是最后一次，则为 true。

isActivating 字典成员：如果用户代理即将 暂停所有相关输入源，则为 false，否则为 true。如果用户代理实现了暂停所有输入源策略，并且 媒体会话操作为 togglecamera、togglemicrophone 或 togglescreenshare，该成员必须存在。

当 媒体会话操作为 enterpictureinpicture 时，enterPictureInPictureReason 字典成员必须提供，表示用户代理触发此操作的原因。

enterPictureInPictureReason 可取如下值：

• other：进入画中画的原因不是现有枚举值之一
• useraction：用户主动执行了进入画中画操作（如点击用户代理界面的画中画按钮）
• contentoccluded：由于页面内容被遮挡，用户代理请求进入画中画。可能是切换标签页、最小化等场景。

11. 权限策略集成

本规范定义了一个由字符串 "mediasession" 标识的 策略控制特性。其 默认允许列表为 *。

文档的 权限策略决定该文档中的内容是否允许使用 MediaSession API。如果在文档中被禁用，用户代理必须不将该文档的媒体会话选为 活动媒体会话。

12. 示例

本节为非规范性内容。

navigator.mediaSession.metadata = new MediaMetadata({
  title: "Episode Title",
  artist: "Podcast Host",
  album: "Podcast Title",
  artwork: [{src: "podcast.jpg"}],
  chapterInfo: [
    {title: "Chapter 1", startTime: 0, artwork: [{src: "chapter1.jpg"}]},
    {title: "Chapter 2", startTime: 120, artwork: [{src: "chapter2.jpg"}]}
  ]
});

navigator.mediaSession.metadata = new MediaMetadata({
  title: "Episode Title",
  artist: "Podcast Host",
  album: "Podcast Title",
  artwork: [
    {src: "podcast.jpg", sizes: "128x128", type: "image/jpeg"},
    {src: "podcast_hd.jpg", sizes: "256x256"},
    {src: "podcast_xhd.jpg", sizes: "1024x1024", type: "image/jpeg"},
    {src: "podcast.png", sizes: "128x128", type: "image/png"},
    {src: "podcast_hd.png", sizes: "256x256", type: "image/png"},
    {src: "podcast.ico", sizes: "128x128 256x256", type: "image/x-icon"}
  ],
  chapterInfo: [
    {title: "Chapter 1", startTime: 0, artwork: [
       {src: "chapter1_a.jpg", sizes: "128x128", type: "image/jpeg"},
       {src: "chapter1_b.png", sizes: "256x256", type: "image/png"}
     ]},
    {title: "Chapter 2", startTime: 120, artwork: [
       {src: "chapter2_a.jpg", sizes: "128x128", type: "image/jpeg"},
       {src: "chapter2_b.png", sizes: "256x256", type: "image/png"}
     ]}
  ]
});

var audio1 = document.createElement("audio");
audio1.src = "chapter1.mp3";

var audio2 = document.createElement("audio");
audio2.src = "chapter2.mp3";

audio1.play();
audio1.addEventListener("ended", function() {
  audio2.play();
});

function updateMetadata(event) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: event.target == audio1 ? "Chapter 1" : "Chapter 2",
    artist: "An Author",
    album: "A Book",
    artwork: [{src: "cover.jpg"}]
  });
}

audio1.addEventListener("play", updateMetadata);
audio2.addEventListener("play", updateMetadata);

var tracks = ["chapter1.mp3", "chapter2.mp3", "chapter3.mp3"];
var trackId = 0;

var audio = document.createElement("audio");
audio.src = tracks[trackId];

function updatePlayingMedia() {
  audio.src = tracks[trackId];
  // 更新 metadata（已省略）
}

navigator.mediaSession.setActionHandler("previoustrack", function() {
  trackId = (trackId + tracks.length - 1) % tracks.length;
  updatePlayingMedia();
});

navigator.mediaSession.setActionHandler("nexttrack", function() {
  trackId = (trackId + 1) % tracks.length;
  updatePlayingMedia();
});

navigator.mediaSession.setActionHandler("seekto", function(details) {
  audio.currentTime = details.seekTime;
});

var adFrame;
var audio = document.createElement("audio");
audio.src = "foo.mp3";

function resetActionHandlers() {
  navigator.mediaSession.setActionHandler("play", _ => audio.play());
  navigator.mediaSession.setActionHandler("pause", _ => audio.pause());
}

resetActionHandlers();

// 当页面希望播放广告时会调用此方法。
function pauseAudioAndPlayAd() {
  audio.pause();
  navigator.mediaSession.playbackState = "playing";
  setUpAdFrame();
  adFrame.contentWindow.postMessage("play_ad");
  navigator.mediaSession.setActionHandler("pause", pauseAd);
}

function pauseAd() {
  adFrame.contentWindow.postMessage("pause_ad");
  navigator.mediaSession.playbackState = "paused";
  navigator.mediaSession.setActionHandler("play", resumeAd);
}

function resumeAd() {
  adFrame.contentWindow.postMessage("resume_ad");
  navigator.mediaSession.playbackState = "playing";
  navigator.mediaSession.setActionHandler("pause", pauseAd);
}

window.onmessage = function(e) {
  if (e.data === "ad finished") {
    removeAdFrame();
    navigator.mediaSession.playbackState = "none";
    resetActionHandlers();
  }
}

function setUpAdFrame() {
  adFrame = document.createElement("iframe");
  adFrame.src = "https://example.com/ad-iframe.html";
  document.body.appendChild(adFrame);
}

function removeAdFrame() {
  adFrame.remove();
}

// 媒体已加载，设置时长。
navigator.mediaSession.setPositionState({
  duration: 60
});

// 媒体从开头开始播放。
navigator.mediaSession.playbackState = "playing";

// 媒体以 2 倍速从第 10 秒开始播放。
navigator.mediaSession.setPositionState({
  duration: 60,
  playbackRate: 2,
  position: 10
});

// 媒体已暂停。
navigator.mediaSession.playbackState = "paused";

// 媒体已重置。
navigator.mediaSession.setPositionState(null);

var isMicrophoneActive = false;
var isCameraActive = false;

navigator.mediaSession.setMicrophoneActive(isMicrophoneActive);
navigator.mediaSession.setCameraActive(isCameraActive);

navigator.mediaSession.setActionHandler("togglemicrophone", function() {
  if (isMicrophoneActive) {
    // 静音麦克风。实现已省略。
  } else {
    // 取消麦克风静音。实现已省略。
  }
  isMicrophoneActive = !isMicrophoneActive;
  navigator.mediaSession.setMicrophoneActive(isMicrophoneActive);
});

navigator.mediaSession.setActionHandler("togglecamera", function() {
  if (isCameraActive) {
    // 关闭摄像头。实现已省略。
  } else {
    // 开启摄像头。实现已省略。
  }
  isCameraActive = !isCameraActive;
  navigator.mediaSession.setCameraActive(isCameraActive);
});

navigator.mediaSession.setActionHandler("hangup", function() {
  // 结束通话。实现已省略。
});

var currentSlideIndex = 0;

navigator.mediaSession.setActionHandler("previousslide", function() {
  currentSlideIndex--;
  // 设置当前幻灯片。实现已省略。
});

navigator.mediaSession.setActionHandler("nextslide", function() {
  currentSlideIndex++;
  // 设置当前幻灯片。实现已省略。
});

navigator.mediaSession.setActionHandler("enterpictureinpicture", function() {
  remoteVideo.requestPictureInPicture();
});

// 创建一个启用音频的 MediaStream。
const stream = await navigator.mediaDevices.getUserMedia({audio:true});
const track = stream.getAudioTracks()[0];
navigator.mediaSession.setActionHandler("voiceactivity", function() {
  if (track.muted) {
    // 显示取消静音通知。如用户允许取消静音，则调用 setMicrophoneActive(true) 进行取消静音。
  }
});

致谢

编辑们感谢 Paul Adenot、Jake Archibald、Tab Atkins、Jonathan Bailey、François Beaufort、Marcos Caceres、Domenic Denicola、Ralph Giles、Anne van Kesteren、Tobie Langel、Michael Mahemoff、Jer Noble、Elliott Sprehn、Chris Wilson 和 Jörn Zaefferer 参与技术讨论，使本规范成为可能。

特别感谢 Philip Jägenstedt 和 David Vest 在设计媒体会话的每个方面时提供的帮助，以及他们在初始设计问题上展现的近乎无限的耐心；感谢 Jer Noble 协助建立适用于 iOS 音频焦点模型的方案；感谢 Mounir Lamouri 和 Anton Vayvod 在早期参与、反馈和支持本规范的制定。