API сеанса медиа

API сеанса медиа предоставляет способ настройки уведомлений о медиа. Он делает это, предоставляя метаданные для отображения пользователем для медиа, которые воспроизводятся вашим веб-приложением.

Он также предоставляет обработчики действий, которые браузер может использовать для доступа к платным медиа-кнопкам, таким как аппаратные кнопки, найденные на клавиатурах, гарнитурах, пультах дистанционного управления, и программные кнопки, найденные в областях уведомлений и на экранах блокировки мобильных устройств. Таким образом, вы можете беспрепятственно управлять медиа, предоставляемыми веб-страницей, через ваше устройство, даже не смотря на веб-страницу.

Цель состоит в том, чтобы пользователи могли знать, что воспроизводится, и управлять этим, не открывая конкретную страницу, которая его запустила. Для поддержки API сеанса медиа браузеру сначала нужен механизм для доступа и управления средствами управления медиа на уровне ОС (например, MediaControl в Firefox).

Интерфейс MediaMetadata позволяет веб-сайту предоставлять богатые метаданные пользовательскому интерфейсу платформы для воспроизводимых медиа. Эти метаданные включают заголовок, имя исполнителя (создателя), название альбома (коллекции), обложку и информацию о главе. Платформа может отображать эти метаданные в центрах медиа, уведомлениях, на экранах блокировки устройств и так далее. Например, разные устройства могут представлять данные API сеанса медиа следующим образом:

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

Основным интерфейсом для API сеанса медиа является интерфейс MediaSession. Вместо создания собственного экземпляра MediaSession, вы получаете доступ к API с помощью свойства navigator.mediaSession. Например, чтобы установить текущее состояние сеанса медиа на playing,

navigator.mediaSession.playbackState = "playing";

ChapterInformation

Представляет метаданные для отдельной главы медиаресурса (например, видео- или аудиофайла).

MediaMetadata

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

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.');
}

См. Пример презентации слайдов/сеанса медиа для рабочего примера.

• Настройка уведомлений и элементов управления воспроизведением медиа с помощью API сеанса медиа на web.dev (2024)