Media Session API
媒體會話 API 提供了一種自定義媒體通知的方式。它透過提供元資料供使用者代理顯示您網頁應用正在播放的媒體來實現這一點。
它還提供了操作處理程式，瀏覽器可以使用這些處理程式來訪問平臺媒體金鑰，例如鍵盤、耳機、遙控器上的硬體按鍵，以及移動裝置通知區域和鎖屏介面上的軟體按鍵。因此，即使不檢視網頁，您也可以透過裝置無縫控制網頁提供的媒體。
其目的是讓使用者瞭解正在播放的內容並進行控制，而無需開啟啟動它的特定頁面。要支援媒體會話 API，瀏覽器首先需要一種機制來訪問作業系統級別的媒體控制元件（例如 Firefox 的 MediaControl）並受其控制。
媒體會話概念和用法
MediaMetadata 介面允許網站為正在播放的媒體向平臺 UI 提供豐富的元資料。這些元資料包括標題、藝術家（建立者）姓名、專輯（集合）、藝術作品和章節資訊。平臺可以在媒體中心、通知、裝置鎖屏等處顯示這些元資料。例如，不同的裝置可能會像這樣呈現媒體會話 API 資料：
原始圖片來源：使用媒體會話 API 自定義媒體通知和播放控制元件（web.dev，2024 年）
MediaSession 介面允許使用者透過使用者代理定義的介面元素控制媒體播放。與這些元素的互動會觸發正在播放媒體的網頁上的操作處理程式。由於多個頁面可能同時使用此 API，因此使用者代理負責呼叫正確頁面的操作處理程式。當沒有頁面定義的行為可用時，使用者代理會提供預設行為。
訪問媒體會話 API
媒體會話 API 的主要介面是 MediaSession 介面。您不是建立自己的 MediaSession 例項，而是透過 navigator.mediaSession 屬性訪問該 API。例如，要將媒體會話的當前狀態設定為 playing：
navigator.mediaSession.playbackState = "playing";
介面
ChapterInformation-
代表媒體資源（即影片或音訊檔案）的單個章節的元資料。
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 |
瀏覽器相容性
載入中…
另見
- 使用媒體會話 API 自定義媒體通知和播放控制元件（web.dev，2024 年）