Media Session API

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

API Media Session даёт разработчику возможность настроить уведомление о медиа. С помощью него можно предоставить метаданные о проигрываемых приложением медиа, а также позволяет приложению реагировать на команды управления воспроизведением. Смысл данного интерфейса в том, чтобы пользователь мог просматривать и управлять медиаконтентом, не переходя на страницу, где происходит воспроизведение.

Принципы и использование Media Session

Интерфейс MediaMetadata позволяет приложению передавать метаданные о воспроизводимом контенте браузеру и ОС. Примеры таких метаданных: название, исполнитель, альбом и обложка. Данная информация может отображаться в медиацентре, блоке уведомлений или на экране блокировки.

Интерфейс MediaSession позволяет пользователям контролировать воспроизведение с помощью элементов управления браузера. Взаимодействие с этими элементами также вызывает события в приложении. Так как этот API может использоваться сразу несколькими страницами, браузер контролирует, какая страница получит события. Браузер предоставляет поведение по умолчанию, если оно не было переопределено страницами.

Работа с Media Session API

Главный интерфейс Media Session API — MediaSession. Не нужно создавать собственный экземпляр MediaSession, доступ к API осуществляется через свойство navigator.mediaSession. Например, следующий код укажет, что страница воспроизводит медиа в данный момент:

js
navigator.mediaSession.playbackState = "playing";

Интерфейсы

MediaMetadata

Позволяет веб-странице предоставить метаданные о воспроизведении для показа в интерфейсе платформы.

MediaSession

Позволяет странице определить собственные обработчики стандартных медиа-событий.

Объекты

MediaImage

Объект MediaImage содержит информацию об отображаемой картинке. Чаще всего этим изображением является обложка или постер.

MediaPositionState

Содержит информацию о длине трека, месте и скорости воспроизведения, передаваемую с помощью метода setPositionState().

MediaSessionActionDetails

Предоставляет информацию, необходимую для выполнения запрошенного действия, например тип действия или позицию перемотки.

Примеры

Данный пример демонстрирует работу и определение доступности Media Session API. Также, он передаёт метаданные и определяет собственные обработчики событий:

js
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", function () {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("pause", function () {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("seekbackward", function () {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("seekforward", function () {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("previoustrack", function () {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("nexttrack", function () {
    /* Code excerpted. */
  });
}

Некоторые браузеры отключают автовоспроизведение медиаэлементов на мобильных устройствах и требуют действий пользователя для начала воспроизведения. Этот пример добавит обработчик события pointerup для кнопки воспроизведения на странице, который начнёт работу с медиасессией:

js
playButton.addEventListener("pointerup", function (event) {
  var audio = document.querySelector("audio");

  // Пользователь нажал кнопку, начинаем воспроизведение...
  audio
    .play()
    .then((_) => {
      /* Настройка элементов управления (показана выше). */
    })
    .catch((error) => {
      console.log(error);
    });
});

Спецификации

Specification
Media Session
# the-mediasession-interface

Совместимость с браузерами

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
MediaSession
metadata
playbackState
setActionHandler()
"hangup" type
"nextslide" type
"nexttrack" type
"pause" type
"play" type
"previousslide" type
"previoustrack" type
"seekbackward" type
"seekforward" type
"seekto" type
"skipad" type
"stop" type
"togglecamera" type
"togglemicrophone" type
setCameraActive()
Experimental
setMicrophoneActive()
Experimental
setPositionState()

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.