Media Session API
=================

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

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

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

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

Работа с Media Session API
--------------------------

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


```js
navigator.mediaSession.playbackState = "playing";
```

Интерфейсы
----------

`MediaMetadata` (en-US)

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

`MediaSession` (en-US)

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

Объекты
-------

`MediaImage` (en-US)

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

`MediaPositionState` (en-US)

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

`MediaSessionActionDetails` (en-US)

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

Примеры
-------

Данный пример демонстрирует работу и определение доступности 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 |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.